Have you ever wondered what your hamster is doing when you're asleep or out of the house? Is he throwing wild parties or practising French? Or maybe just running in his wheel?

We wanted to find out for ourselves what our hamster, Martin, was getting up to behind closed doors and so we built him a tweeting hamster cage. Now all of Martin's friends can keep up with his exercise routine on Twitter and we get to see how far he runs every night!

@IsMartinRunning

This is a guide on how to make your own Raspberry Pi/Arduino based tweeting hamster cage, which uploads a photo of the wheel and distance run every time your hamster goes for a spin. It also has the ability to respond to tweets, it can reply with information about the temperature/humidity in the cage as well as being able to dispense treats on command.

Step 1: What You'll Need

For this project you will need:

1 x Raspberry Pi,

2 x Arduino

1 x USB web cam

1 x Hall sensor (http://www.amazon.co.uk/gp/product/B00IFD0F7M)

2 x small magnet (these are great so we bought lots)

2 x 10k resistor

1 x 100uF capacitor

1 x hamster cage (plus lovely hamster)

1 x temp/humidity sensor (DHT sensor) (http://www.amazon.co.uk/Temperature-Relative-Humid...)

1 x 9g servo (http://www.amazon.co.uk/dp/B00J593VRQ)

Plus whatever you want to make the dispenser out of (we used a plastic tube, cardboard and string)

Step 2: Setting Up a Twitterbot

A twitter bot is something that automatically sends tweets for you, a good example is Big Ben which BONGs every hour (https://twitter.com/big_ben_clock), which would be a tiring job for a human.

Our twitter bot will be run by a Raspberry Pi, and instead of tweeting on the hour, it will tweet in response to the wheel spinning. First, we need to set up a twitter bot. The best tutorial on how to do this with a Raspberry Pi can be found at this link: http://www.makeuseof.com/tag/how-to-build-a-raspb...

It even tells you how to get it to tweet photos, which is something we want ours to do as well.

We used 2 twitter bots, one to tweet the photos and distances, and another to respond to mentions whenever people want to give Martin a treat or find out what the weather's like.

Step 3: Arduinos (the Code)

The next part of the project is to get the Arduinos set up with the code that will allow them to sense/interact with the hamster cage. All of the code for this project is available at github.com/Kimbsy/IsMartinRunning (if you've used git before you can just clone the whole project into your pi's home directory). But I'll also upload the files here for those who find that easier.

We'll be using two Arduinos here, one for sensing any movement of the wheel and a second one to get temperature/humidity data and to control the treat dispenser. Some of you may be wondering why we don't do this all on one Arduino (or for that matter just use the GPIO of the pi), there are three main reasons:

Simplicity (it's easier to explain to people what it's doing, and it's much easier to write the code).
Separation of concerns (if one part breaks, we can keep the others running while we try and fix it).
We did this project bit by bit and that's just how everything fell together :)

The first arduino, which will do the wheel detection, will need the hall.ino sketch (in the git repo at sketches/hall/hall.ino). This sketch listens to a hall sensor attached to pin 12 which sends a signal every time it detects a magnet move past it. We are going to attach two magnets to opposite sides of the wheel, so one will flash past every half rotation. The code measures how many rotations happen before the wheel stops spinning and works out the speed and distance. You will need to edit this sketch before uploading it to change the value of the CIRCUMFERENCE constant on line 17. This should be the circumference of you hamster wheel (measured in metres).

The second arduino which will be sensing temperature and humidity as well as controlling the treat dispenser will need the dht_with_servo.ino sketch (in the git repo at sketches/dht_with_servo/dht_with_servo.ino). This sketch waits for a command from the pi and either activates the treat dispenser servo or collects temperature and humidity data from the DHT sensor and sends that back to the pi.

Once these sketches have been uploaded to the arduinos, we can wire up the components.

Step 4: Arduinos (the Hardware)

Now that we have the sketches uploaded to the Arduinos we can wire up the sensors.

Wheel sensor:

The wheel sensing Arduino needs a hall sensor with a 10k resistor across the 5V input and the signal output pins (see circuit diagrams). We soldered the resistor directly onto the hall sensor to keep things neat.

The wires connecting to the sensor should be long enough to reach the wheel from wherever you plan to keep the Arduino.

Temp/Humidity sensor and servo control:

This Arduino needs the DHT sensor attached as well as a servo motor. There is a 10k resistor over the 5V input and the signal output for the DHT sensor (see circuit diagrams). There is also a 100uF capacitor from the reset pin to ground (this is required due to the way we'll be communicating with the Arduino).

NOTE: Your DHT sensor may have 3 or 4 pins, both work just fine. In the photo above we used a 3 pin one where all 3 pins are connected. If you have a 4 pin one, make sure to connect it like the one in the circuit diagram (one of the pins is left unconnected).

The wires going to the DHT sensor should be long enough to get it into the cage, and the wires for the servo should be long enough to get it to wherever you plan to have your treat dispenser.

Step 5: Modding the Cage

Now it's time to install the parts in the cage itself. Make sure your hamster is off having fun somewhere else for this bit as you don't want to disturb him. Attach the Arduinos to the top of the cage (or wherever you find it easiest to keep them) and then install the sensors.

Wheel sensor:

Attach two magnets to the outside of the wheel opposite each other.
Attach the hall sensor to the side of the cage next to the wheel so that as the wheel spins, the magnets go past the sensor, as close as possible without touching (see above pictures).
Attach the camera to the inside wall of the cage facing the wheel.

Temperatur/Humidty sensor and treat dispenser:

Make the treat dispenser. We used a small section of plastic tube with a cardboard flap taped to the bottom, the flap is held closed with a string attached to the servo horn. When the servo is activated it loosens the string which allows the flap to open and the treats to fall out of the tube.

Attach the DHT sensor somewhere inside the cage out of reach of tiny hamster hands.
Attach the servo to the top of the cage above where you want the treat dispenser. The servo horn should be pointing up.
Attach the treat dispenser to the inside wall of the cage and connect the flap to the servo horn with the string keeping the string taught (see above pictures).

It's important to remember that hamsters love to chew on things, so as much as possible try and keep things out of reach, wires should not be left dangling as they are particularly likely to be chewed.

Step 6: Raspberry Pi (the Code)

We're getting close now, your hamster is nearly ready to enter the world of social media. We have sensors, servos and cameras all ready, we just need to hook them up to the Raspberry Pi and tell them what to do. I've gone back through all the files involved in the project and filled them with comments explaining what each part of the code is doing for any of you who are interested.

There's a fair bit of code required to make this project work, so I've put it all in a repository (repo) on GitHub. You can install the command line tool for GitHub (called git) on your pi by running the command:

sudo apt-get install git

We can now use git to clone the repo onto the pi (basically we'll be downloading all the files onto the pi along with the correct folder structure to make them all work (see above picture)). The following commands should get you set up:

# cd to the home directory

cd ~/

# clone the repo

git clone git@github.com:Kimbsy/IsMartinRunning.git

You should now have all the code you'll need. We'll just need to check a couple of variables are correct and set up the access tokens for your Twitter bots.

Setting up twitter access tokens

We'll need to crate a new directory inside the project

mkdir ~/IsMartinRunning/.secrets

Prefixing the directory name with a dot makes it hidden (you won't be able to see it with 'ls' you'll need to use 'ls -a'). Inside this directory make two files (one for each of your Twitter bots):

cd ~/IsMartinRuning/.secrets

touch martinBot.access mentions.access

Now in each of these files we need to put the access credentials for one of the Twitter bots. Using the first four lines of the file write:

The consumer key
The consumer secret
The access token
The access token secret

You can find these values by going to apps.twitter.com and going to the 'Keys and Access Tokens' tab for your bot. We do this for security reasons, it's totally possible to just write these keys into the scripts themselves, but then if you host them in a public repo (like I do) everyone suddenly has access to your twitter bots (which is undesirable).

Now let's go through the files, look at what they do and whether they need customising.

MartinBot/MartinBot.py

This is a Python script which takes data from the wheel sensor dween as an argument. It takes a photo using the webcam, checks whether this new run beats any of the previous personal bests, constructs an appropriate tweet and uses the python library Twython to send it.

This file does need a bit of work. First of all we'll need to install the Twython library. This can be done using the python package manager pip. So really first of all we'll need to install pip :)

# install pip

sudo apt-get install python-pip

# install Twython using pip

sudo pip install twython

Next we'll need to make sure the file paths are correct. Lines 27, 40, 60 and 65 all have file paths that need to be correct for your pi (i.e. you might need to change the username in the path).

Finally we'll need to make sure the serial port for the webcam is correct (line 24 '/dev/video0'). You can check this by unplugging the webcam from the pi, the running the command:

ls /dev

Then plugging the webcam back in and running the same command again. This time a new port should show up and this is the one you want. We'll be using this same technique to check the ports of the Arduinos too.

MartinBot/image.png

This is the image the webcam takes, ready to be uploaded to Twitter.

MartinBot/personal_bests

This file contains the highest recorded values for average speed and distance. It is used and updated by the MartinBot.py script to check for new records.

MartinBot/wheel_listener.sh

This is a Bash script which will loop continuously listening to the wheel sensing Arduino for any data about a new run. When it gets the data it will run the MartinBot.py script passing in the data for it to use.

The serial port on line 15 ('/dev/ttyACM0') needs to be set to whatever port your wheel sensor Arduino is on (just like the webcam).

The file path on line 19 needs to be correct.

circuit_diagrams/*

These are the circuit diagrams for the Arduinos as well as the .fzz files used to create them with a program called Fritzing (it's very useful).

These aren't actually used so you don't need to worry about them. I just like to keep all this stuff together on GitHub.

get_mentions/get_mentions.py

This Python script is more complex than the last one. It hits up the Twitter API looking for any tweets that mention '@IsMartinRunning' (yours will automatically search for the Twitter handle of whatever account owns the twitter bot). It then checks to see if these are newer than the most recent one it responded to, these new tweets then get searched for keywords such as 'weather', 'temperature' and 'treat'. If any of these words are found a reply tweet needs to be created. If they mentioned any of the temperature of humidity keywords, the script sends a signal to the hdt_with_servo Arduino asking for the temperature/humidity data, if the tweet contained the treat keyword, the script sends a signal to the Arduino telling it to activate the treat dispenser servo. The script then comes up with an appropriate response, tweets it and then updates the most recent responded to tweet.

The 'serial_path' variable on line 55 needs to be referring to the correct serial port for the hdt_with_servo Arduino.

The file paths on lines 58, 92 and 145 need to be correct.

get_mentions/mention_listener.sh

This Bash script runs the get_mentions.py script every minute (this is as often as the Twitter API will allow).

The fie path on line 13 needs to be correct.

get_mentions/most_recent

This file contains the tweet id of the most recent tweet responded to by the get_mentions.py script. This is so we only respond to tweets once.

sketches/**/*

These files are the Arduino sketches needed to make the sensors and servos work.

Phew, I know it's a lot to think about all in one go, but we should be done now. Next let's get these scripts running.

Step 7: Running the Scripts (and Notes)

The only thing left to do now is set it running.

# cd to the home directory

cd ~/

# run the wheel_listener script (the '&' means run as a new process so we get control of the terminal again)

IsMartinRunning/MartinBot/./wheel_listener.sh &

# run the get_mentions script (again, we'll do this as a new process)

IsMartinRunning/get_mentions/./get_mentions.sh &

And that's it! Whenever your hamster runs, the cage will tweet about it and whenever you tweet at your hamster with the correct keywords it will respond appropriately :D Hooray!

Things to mention:

So hamsters are nocturnal. This means that the majority of your photos will be taken at night and will be entirely black. I am sorry.

Our plan to fix this is to set up a bunch of infra-red LEDs pointing at the wheel as most cameras can see into the infra-red without any modifications. Hamsters (I looked this up) can't see infra-red light so will not be bothered by this at all :)

If you have any problems with this project or any cool new suggestions or ideas, please leave them in the comments!

Happy making!

BethAndDave