Saturday, June 11, 2011

Terrarium Twitter Monitoring

In this post I would like to show you how to build a terrarium monitoring system by using twitter for event notifications. This post is also an entry for the Adafruit / Instructables Make It Tweet Contest which will be open for voting after June 26th. So make sure to vote for me then if you like this tutorial.

If you are a reptile owner like myself you should already know that your little friends have very special needs. Be it a certain temperature which they would appreciate in their natural habitat or special humidity settings. You also need to make sure that they have the correct lighting and most importantly that you don't forget to feed your companions.
With most other pets you wouldn't have a hard time keeping track of everything as they would remind you in an audible way. Reptiles on the other hand tend to suffer quietly. This is a big problem as there are a lot of inexperienced reptile holders out there which are overchallenged with their reptiles special needs. Too often this results in reptiles being released into the wild, putting them into animal shelters or in the worst case them dying silently. To give my chameleons a voice to be heard I decided to hook up their terrarium with some sensors and tweet certain events via twitter to be always up to date when my reptile friends need some extra attention.

With this tutorial you will be able to be notified via twitter when the humidity or temperature reaches a defined threshold, when the light is turned on/off and when someone opens/closes the terrarium doors. It is important that the humidity and temperature values are in a range which conforms to the natural habitat of your reptile. So when a threshold is reached you will get notified to take action like sprinkling some water on the terrarium plants to increase the humidity and lower the temperature. Reptiles have also special needs when it comes to light settings. They need spotlights to heat up an area for sunbathing and regulating their body temperature. They also need special UV lights to enable molting and to harden their bones since they lack calcium in captivity. With the twitter monitoring you can keep track of the on/off cycles of your lights, if they are broken or even if they decay slowly in their intensity. It might also be helpful to monitor when the terrarium doors have been opened or closed to make sure that they can't wander around in your home. You could also be reminded that you haven't fed them yet if the doors were closed the whole day.

After this long but neccessary introduction it is time to get to work.


For this tutorial you will need an Arduino Uno or similar microcontroller board, a WiFly shield or Ethernet shield for socket communication with a desktop computer, a photoresistor for light sensing, a temperature and humidity sensor and a tilt switch. Here is the part list of the components I used:

Assembling the WiFly shield / Ethernet shield and Arduino

The first thing you have to do is to assemble the WiFly shield. This turns out to be pretty simple. You only need to solder on the Arduino stackable headers as the board comes without the headers. You could also use an Ethernet shield if you have an ethernet connection near your terrarium. Since mine is in another room I had to stick to the WiFly shield. Once finished stack the shield onto the Arduino. Now you have laid the foundation for the sensor processing.

Building the Door Sensor

As a door sensor I used a Tilt switch. My terrarium has a simple lock which you have to turn downwards from a horizontal position in order to open the door. That kind of lock makes perfect use for a tilt switch as it can close a circuit when turned into a certain position. The tilt switch I used had 4 connector pins so I had to figure out which two pins would be needed to operate the switch. Have a look at the corresponding datasheet or product description if you have one, or just simply use a tilt switch with two connector pins. Make sure that your wires are long enough since you might need the wires of the switch to reach from the front of your terrarium all the way to the upper back. Now solder the wires onto the switch.

Connect one wire to a digital port (I used D5) of the Arduino and the other one to GND.

Congratulations you already finished the door sensor.

Building the Light Sensor

The light sensor is a simple photoresistor which changes its resistive value when exposed to light. When connected together with the 10kΩ resistor in a voltage devider circuit, you can read voltage changes on an analog port of the Arduino. The analog port on the Arduino converts those voltage measurement values to digital values which can be processed in your code. This is called ADC or analog to digital converter.
Solder some wires to your photoresistor and again make sure that they are long enough as they have to reach from your Arduino to your lighting setup. Then connect the photoresistor to +3.3V and an analog port of your Arduino (I used port A0). Connect the 10kΩ resistor to the same analog port and to GND. This is how it should look when you connected everything.

Congratulations you finished the light sensor.

Building the Humidity and Temperature Sensor

I used the SHT15 breakout board which is a preassembled board which had a humidity and temperature sensor combined. You will need to solder on only 4 pin headers. Two for VCC and GND and two for DATA and SCK as it works with a two-wire digital interface. Solder on the necessary wires. Connect the VCC wire to +5V. Connect the GND wire to GND. Connect the DATA wire to a digital pin (I used D4). Last but not least connect the SCK wire to another digital pin (I used D2). It's as simple as that.

Sources and Communication with the Desktop Computer

Now that you have assembled everything the next step on the list is the coding part. Since my terrariums are situated in another room than my dekstop computer I chose to let the Arduino communicate via WiFi with a small desktop console application running on my desktop computer. The desktop part is fairly simple. It consists of a single Java class which handles the socket communication and posts default message to Twitter depending on the events it receives. For the Twitter communication part I used the well known twitter4j library which handles the OAuth authentication part and the posting.

You can download the example desktop application from github. Once downloaded you can run the code from a console. Make sure that you have Java installed on your machine and navigate to the download folder. Change into the executable_jar folder and edit the file. You have to insert the credentials for your own Twitter account. Afterwards run the application from the console by typing:
javac -jar TwitterTerrariumConnector.jar
Now the desktop machine will listen for incoming data.

The Arduino code is pretty simple too. The most complex part is getting the values from the SHT15 humidity and temperature board. The rest is a piece of cake. The Arduino code can also be found on github .

You will have to change some settings in this code to let the WiFly shield connect to your home network. The lines are documented in the setup routine.

After you have uploaded the code to your Arduino the WiFly shield will connect to your home network and starts to poll the sensors for their values. If one of your configured thresholds is reached or an event is triggered, the Arduino will send the corresponding event in form of a byte to the IP-address of your desktop computer. The desktop computer receives and evaluates the event and posts the corresponding message to Twitter.

Position the Sensors and let the Monitoring begin

Now position your sensors in the measurement critical areas of your terrarium. Please make sure that you position them in an area where your little friends can't reach them as you don't want them to get hurt by accident. You can see where I placed them in the demo video. Now let's see the whole project in action.

Door Monitoring:

Light Monitoring:

Humidity and Temperature Monitoring:


  1. Hi,

    Thanks for sharing the nice article on Arduino & WiFly shield. I am trying in the similar way, where my idea is to send an simple message to desktop IP whenever an push button (which is assembled on breadboard) is pressed. If you have some suggestions kindly help me how I can succeed with this problem.

    Thanks & Regards,

    1. Well it's actually pretty easy if you are using the WiFly Arduino library. Just have a look at how I do it in my Arduino code for this project

      You just have to init a Client object providing the desktop IP and port.

      byte desktopIp[] = {192, 168, 0, 100};
      Client client(desktopIp, 80);

      Afterwards when your button was pressed you can send bytes to your desktop system by using the write method on the client object. Don't forget to call the stop method when you're done to close the connection.


  2. Thanks for your suggestions. Hope I will succeed with this problem.