18 enero 2013

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:
     

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:


Download RPiTwit from the following address:


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!

9 comentarios:

Adi Mulawarman dijo...

Hi did you ever create a method to run this as a script?

Adi Mulawarman dijo...

Hi do I setup the rpitwit to be executed as part of the start up?
it always ask for a pin number if I try running it inside a script but when I run the rpitwit on the prompt, it didn't ask for pin.

Mario Gómez dijo...

Hi Adi Mulawarman!

RPiTwit generates a config file that is loaded from the user directory. When you use it as a "service" at startup it looks for it on the root home directory.

Try copying the config file to the root home directory and see if it works.You can use the following command:

cp /home/<your username>/.rpitwit_config /root/.rpitwit_config

However, I do not recommend to run rpitwit as root, if you can run it as a normal user it would be better and more secure. You can use "su" to do that:

/bin/su <your username> -c /usr/bin/rpitwit

I'm planning to release a new version that allows you to specify a config file from the command line, wait for it in the next week.

Regards,
Mario

ILWON dijo...
Este comentario ha sido eliminado por el autor.
ILWON dijo...

And also have other question about magicword.

First of all, I tried to copy the command you wrote up above,but it didn't give me any result.

And if I can edit magicword, does it mean that I can use other word instead of typing "#rpitwit"?

ILWON dijo...

Can I change "#rpitwit" to the other word? If so, how can I do that?
I tried to access the config file, but

cp /home//.rpitwit_config /root/.rpitwit_config

This code doesn't work with either root access.

Javier Magán dijo...

I have a question. On the twitter page I received this message: "SSL is required". What can I do? Thanks

Javier Magán dijo...

Changing http://... by https://
More info https://dev.twitter.com/discussions/24239

Thanks ;)

MisterTee dijo...

Hi this is a great post. I was looking to control a light in my house with the 'mains switch widget' from sf innovations and this looks like it will do the job.
Thanks