Controlling the Raspberry PI via Twitter

Before writing anything, I just want to warn you that English is not my native language, that means that this articles are my "best try" on trying to exercise my written English. So I would be very happy if you can correct me or suggest me a better way to write my articles.

The Main Idea

Yesterday I was trying to write a small python script to track tweets about traffic here in my country, and I was thinking that it would be really interesting to control the Raspberry PI using my twitter status.

After googling for a while, I found the "Python Twitter Tools", this is a small script that connects to the Twitter Rest API and gives you a couple of tools to publish and follow Twitter posts.

What is most interesting is that this tools includes a small API that allows you to create customs programs. And believe me, you can create interesting things in lesss than 10 lines of code.

So I told to myself... Why not program something?

How it works?

After working at night, I finished a small client (alpha with a lot of bus) for the command line that does something really simple:

If you publish a twitter starting with the hashtag #rpitwit followed by a "command name" if would check if that python or shell script exists on the "rpitwit_commands" directory under your user directory and executes it.

For example if you have a script that take a picture from a webcam an uploads it to a website you could put something like this on your twitter status:

#rpitwit takepicture

It would check if a script named "takepicture" or "takepicture.py" exists inside the command directory and is going to execute it.

Its possible to send parameters to the command for example we can imagine that we can set the size of the picture and send something like this:

#rpitwit takepicture 800x600

And that's it! That's the way it works.

Why simply don't allow it to execute any command?

Well... That would have been too easy. But the main reason is that in general, its not a really good idea to leave any way to execute remote commands over an "insecure" channel (Yes, Twitter is a public and really insecure way to send commands to your RasPI), so, limiting the execution to the scripts under the user directory helps to keep things "under certain control".

You would need first to create the scripts and put them to the commands directory before being able to execute them remotely from Twitter.

You can modify the source and allow the program to execute ANY command but I don't really recommend you to do that.

How to Install it

Prerequisites

• First, you would need Python 2.7.x, download it and install it.
• Next, you need to be sure to have "setuptools". In most of the cases you already have it installed. If not. go to the following addresses and follow the instructions to install it:
  
  http://pypi.python.org/pypi/setuptools
   

Installing "The easy way"

Run as root the following command:

easy_install rpitwit

Installing "The hard way"

Download the package for Python Twitter Tools from the following address:

http://pypi.python.org/pypi/twitter

Download RPiTwit from the following address:

http://pypi.python.org/pypi/rpitwit

To install execute the following commands

tar -xzf twitter*.gz
cd twitter-1.9.0

As root:

python setup.py install

Then:

tar -xzf rpitwit-0.1.0.tar.gz
cd rpitwit-0.1.0

As root:

python setup.py install

Running it for the first time

Note: Never run this command as "root".

Execute on the console the following command:

rpitwit

A browser is going to open and ask you to authorize the "RPiTwitt" application to access your public information.

On the twitter page you are going to recive a "PIN" that you need to write on the console like this:

Please enter the PIN:

If the script cannot open a browser windows, copy the address open it in a browser window.

After that the script is going to ask you for the usernames who are going to be able to execute commands, don't put the @ at the begining of the username.

For example if you want to allow me to run commands on your RasPI, just put my username:

Please write the username(s) which do you want to<
authorize to send commands (separated by commas):
mxgxw_alpha

A confirmation message is going to inform you if the user was added to the authorization list:

Trying to get userid for mxgxw_alpha
>User @mxgxw_alpha added to the list.

Then the script is going to create the "commands" directory, its called rpitwit_commands under your home directory. On the raspberry pi if you are running "raspbian" is going to be /home/pi/rpitwit_commands

Creating script directory on /home/pi/rpitwit_commands
Copy your shell or python scripts to the
script directory and execute them using:
#rpitwit <command> [args]

A final message is going to confirm you that the script is "following" the users.

Note: this message shows the user IDs and not the usernames.

Following to 257243704

This program runs on foreground and prints "debug" messages that are usefull to monitor if it's working right.

TODO: May be in a next version I include a script to install it as a service.

Creating custom commands

Python scripts

This is the interesting and more easy part. Just create a python script and put it under the commands directory. Let's make a "Hello World!".

Create a file with the text:

print "Hello World!"

And save it under /home/pi/rpitwit_commands using the name "hello.py"

Verify that rpitwit is running.

Now go to your twitter account and publish:

#rpitwit hello

Verify on console that you get something like:

Running python script hello.py
Arguments
Hello World!

Bash scripts

Create a file with the text:

#!/bin/sh 
echo "Hello World!"

And save it under /home/pi/rpitwit_commands using the name "hellosh"

Change the file permissions and make it executable:

chmod 755 hellosh

Verify that rpitwit is running.

Now go to your twitter account and publish:

#rpitwit hellosh

Verify on console that you get something like:

Running command hellosh
Arguments
[u'/home/pi/rpitwit_commands/hellosh']
Hello World!

There is anything else that I need to know?

Yes.

The config file

This scripts creates a config file named .rpitwit_config under your user directory, there are several things that you wold change but try to not change anything but the following two lines:

magicword=#rpitwit

This is the word used to instruct rpitwit to execute a command. You can change to anything that you want, it doesn't need to be a hashtag.

follow=<some_numbers>

This are the user IDs that rpitwit allow to execute commands using the "magicword". You can find a user id with the following address:

https://api.twitter.com/1/users/show.xml?screen_name=<write here the user name>

On the response look for "id", that's the number that you would need to put on "follow".

A final disclaimer

This script doesn't only works on the "Raspberry PI", I've just teste it on my Slackware Linux, in theory it would work on any Linux distribution with Python and setuptools.

I have written this program with the objective to be something useful and easy to use. Use with caution, don't put "dangerous commands" on the commands directory or scripts from unknown sources.

Yo also can use your own Twitter application keys, sadly there is no easy way to change them, read the documentation folder for more info. 

The code is under the GNU GPL v3 License, you can modify and redistribute keeping the original Copyrights.

Not having more to write... Download it and enjoy!