Tweeting Pet Bowl

Have you ever walked past your pet’s water or food bowl and see it empty; only to wonder how long your pets have been without water? Here’s my take on a solution to this problem: a bowl that tweets when it is empty or low on contents. It’s a simple build and should be adaptable to any bowl you choose. And best of all, it’s wireless!

My hope in writing this instructable is that you can, of course, make your own tweeting pet bowl, but also that this can be used as a reference. That being said, this is my first instructable, so I appreciate any feedback that would help make future instructables better.

So let's get started!

Step 1: What You Need

Here's what you need to make your own tweeting pet bowl.

Hardware
2 x XBee Module
2 x XBee Adapter
1 x USB FTDI Cable
1 x Force-Sensitive Resistor
1 x 10K Ohm Resistor
1 x 2 AA Battery Holder
2 x AA Battery
1 x Small Perfboard
10 x Nuts
1 x Dog Bowl
? x Extra Wire

Software
We'll be using Python for this project so you'll need to have it installed on the computer you plan to hook up the receiver to. If you don't already have Python and/or the other dependencies installed, don't worry: I will cover how to install Python later in the instructable.

Skills
All you really need are some basic soldering skills and a little patience.

Step 2: Build the XBee Adapters

We’re using XBee adapters from adafruit.com. There are extremely detailed instructions on ladyada’s website, so I’ll just put a link to it here .

Step 3: Configuring and Testing the XBee's

Connect the FTDI cable to your computer. While drivers are installed, head over to http://www.digi.com/support/productdetl.jsp?pid=3352&osvid=57&s=316&tp=5&tp2=0 and download and install X-CTU. We’ll use this program as a simple means of configuring our XBee’s. This program is only for windows, as far as I know, but there is a way to configure your XBee modules from a serial console. If you need to do this, head over to Ladyada’s website and check out the Tweet-a-Watt tutorial.

Now it’s time to configure your XBee radios. Take your FTDI cable and connect it to the XBee with the black cable on GND. See the first image above.

Now open up X-CTU. You’ll start on the PC Settings tab. Select the COM port you are using and make sure that the settings are as follows:
• Baud: 9600
• Flow Control: NONE
• Data Bits: 8
• Parity: NONE
• Stop Bits: 1
Click on the Test/Query button to ensure that X-CTU can communicate with the XBee.

Time to upgrade your XBee’s. Click on the Modem Configuration Tab. Click the Download New Versions… button to make sure you have the newest version firmware. If you don’t, it will be automatically downloaded for you. Now click on the Read button and the current settings of the XBee will be displayed. Go over to the Version drop down menu and select the newest available version, then check the Always Update Firmware Check box, and then finally click Write. Follow these steps again with your second XBee and then un-check the Always Update Firmware box.

Transmitter
Now we will configure our transmitter. Connect the XBee you wish to use as a transmitter to your computer and press the Read button inside X-CTU. You’ll see a list of all the setting that XBee has. Navigate through the list and make the following changes:
• MY = 1
• SM = 4
• ST = 3
• SP = 68B0
• D0 = 2
• IT = 13
• IR = 1
So what do these setting mean? The MY attribute is an identifier for the XBee and if we were using more than one transmitter each would have its own MY value. SM sets the type of sleep mode. Here we are using cyclic sleep mode. ST defines the sleep time. We’re setting it to 3 which means we’ll have 3 milliseconds after waking up before we go back to sleep. During this awake time the XBee will transmit data to the receiver. The SP value defines the sleep period. As its name suggests, this is the amount of time the radio will sleep for. I’ve set a hexadecimal value of 0x68B0 or 26800 in decimal. This tells the XBee we want it to sleep for (SP * 10 msec) = 268 seconds before waking up and transmitting. Next, setting D0 to 2 means that we want the digital zero pin to be in ADC mode. Then, we define the number of samples per packet, IT, to 0x13 or 19 ADC samples per packet. And finally, we set IR to 1 msec between each ADC sampling.

Receiver
The receiving XBee will not need any additional settings, so once it’s firmware has been updated you’re all set. However, I do recommend labeling the radio in some way so that you can keep track of which is the transmitter and which is the receiver.

Resetting a Sleeping XBee
If you want to make changes to the XBee later on and you get error message saying “Action Required,” then there is a good chance your XBee cannot reset itself. There is an easy fix to this. Once the message pops up, touch the GND pin and the RST pin together on the XBee adapter; the message should disappear and your XBee’s settings should successfully be changed.

Step 4: Add Remaining Components

We have one more part of this project that involves soldering. We need a way to connect the Force-Resistance Sensor (FSR) to the XBee digital zero pin. In order to make the ADC work on the XBee, we need to make a connection to Vref too. To make all these connections, we'll used a small perfboard. The connections are straightforward, so this step should not be too difficult.

If you look at the images above, the red and black lines mark the positive and negative buses respectively. The green connection are just all common connections. The yellow and orange wire go to the Vref and Vcc on the XBee and connect to the positive bus. The green wire connects to GND on the XBee and goes to the group the bus. And the blue wire connects to the AD0 on the XBee and connects in between the FSR and 10K Ohm resistor.

Be advised that you must be extremely careful when soldering to the FSR! If you hold the iron on the sensor too long you could melt the plastic and permanently damage the sensor.

Step 5: Modifying the Bowl

So let's get the bowl set up. This step, of course, will vary depending on the type of bowl you have. I'll explain the process I used for my bowl, and in doing so will hopefully cover the necessary requirements that can be applied to any type of bowl.

The idea is have the bowl sit primarily on the FSR. I'm using nuts in this case as a sort of stilt. Then to help balance the bowl, I use additional nuts around the perimeter of the bowl. The idea is to have the bowl rest on the FSR while reducing wobbling.

Here's what I did. First, I removed the rubber feet from the bottom of the bowl. I was lucky enough to have feet that had prongs on the back of them and easily allowed me to screw the nuts onto the feet. I did this to four of the feet and then used hot glue to attach them to the perimeter of the bowl. Next, I peeled off the thin layer of plastic on the back of the FSR to reveal a sticky area. I attached the FSR to the center of the bottom of the bowl and then used a small piece of double sided tape to attach a nut to the center of the FSR. Finally, I hot glued another nut on top of that nut.

After this primary set up, I decided to tuck the electronics inside of inner "compartment" of the bowl and used some small velcro squares to attach the XBee with perfboard and the batteries inside.

Step 6: Set Up ATwitter Application

First, if you don’t already, head over to Twitter and create an account for yourself. In order to have access to the Twitter API through your python script, you’ll need to set up a Twitter application. To do this, go dev.twitter.com and sign in with your Twitter account. Click on the “Your Apps” link on the top of page and you’ll be brought to a list of all your projects. On the right should be a link that says “Register a new App,” click on it and follow the instructions to set up your new Twitter application. I called mine Tweeting Pet Bowl, but you can choose whatever you want for yours.

Now you should see your application on the “Your App” page. Click on it and you’ll see a lot of different information. What we want are four codes that the python script requires to connect to twitter via oauth. First two are the Consumer Key and the Consumer Secret Key. They are both located on the main setting page. The second two are the Access Token and Access Token Secret. To get these to click on the link on right that says “My Access Token.”

Hold onto these values. You’ll need them for the python script configuration step.

Step 7: Installing Python

Python
If you don't have python installed on your computer follow these steps to get it up and running and then follow the instructions in the dependencies section. If you have python already, skip on down to dependencies.

Head over to the Python downloads page at http://www.python.org/download/ to get the newest version. I used version 2.7.2 and if you have windows, installing is as easy as clicking on the executable and following the steps to install. I recommend installing the root drive of computer (usually C:). Once installed, you're ready to add some dependencies that our script will need in order to run.

Dependencies
The first thing we're going to need is the pyserial plugin that will allow your computer to communicate with the XBee through a serial port. You can get this from here . Once you've downloaded it, just double click on the executable and install it.

Next, we're going to install simplejson. The python-twitter library will need to have this to connect to the Twitter API. Installing this is slightly more difficult. First, download the package here and then extract the archive. Once extracted, open up the command prompt and change your directory such that you are inside the simplejson directory. The easiest way I found to do this was navigate in windows explorer to the simplejson folder and then copied the address. (In case you don't know, changing directories in command prompt is achieved by typing "cd C:\Users\Chris\...").  Once you're in the correct folder, you'll want to type:

C:\python27\python.exe setup.py install

This command should successfully install the simplejson package.

Lastly, we need the library that allows python to communicate with Twitter. This python library can be found here . Locate the download link on the left side of page and click it. The installation of this is very similar to the installation of simplejson. Extract the archive and open command prompt. Navigate to the python-twitter directory and copy the address. Then go your command window and change directories. Here we need to type two commands to install the library. First type:

C:\python27\python.exe setup.py build

hit enter and then type

C:\python27\python.exe setup.py install

And that's it. Now let's look at the actual script that will tweet for us.

Step 8: Understanding the Software

Here we'll look at what is going in the software. The script is simple and I'll keep the explanation brief. In the attached archive there are three files. The way this works is that approximately every 4.5 minutes the transmitter XBee will transmit and ADC reading. The script will analyze the value and decide if it needs to tweet. It will tweet every 4.5 minutes until the water is replaced. The first script we'll look at is helper.py.

helper.py
This script is simply for you to use in order to take preliminary measurements. I'm not going to explain what is going on in this script because it is literally copied and pasted out of the tpb.py script. We'll use this in the next step to help us configure our final main script.

xbee.py
This piece of code is a small set of functions designed to help handle the incoming packets from the XBee. It makes parsing data really simple. We won't go through this line by line because understanding it's functionality is trivial to this project.

tpb.py
Finally, we come to the main script for this project. This is actually what will be getting the XBee's ADC reading and Tweeting when necessary. Let's take a closer look.

We start by importing all the necessary external dependencies: the serial library, the XBee library, and the Twitter library. Next we define some initial variables that we'll use later on. Theses are commented on the script as to what each is for and their names should be self explanatory.

Next, we'll initialize the twitter API. The call twitter.Api(...) takes four arguments. The first two are the Consumer Key and Consumer Secret respectively. The second two are Access Token and Access Token Secret. These are the strings of characters we got when we set up the twitter application.

Then we have to open the serial connection with the receiver XBee. We set up a serial object with the serial port and the baud rate and then we open the connection.

Now we'll define our main program loop which I just call mainLoop. First thing we'll do in our main loop is get a packet from the XBee or else we'll return out of the function. Then we'll parse the packet by calling a function contained in the XBee library. Now we'll set up and array to contain the ADC reading from all the samples of the packet except for the first one (ADC reading can sometimes be screwy on the first read). Then we'll average those values. Then, we check if the if the averaged value is less than the value we set as the Threshold value. If it is we tweet and increment the warning the number otherwise we set the warning number to zero.

And finally, we put a while loop with a true condition to keep the script running indefinitely and call the mainLoop function.

Step 9: Configure the Software

Configuring the software is simple. Download the attached archive and extract it wherever you would like the script to finally live. Open the helper.py and tpb.py script and set the Serial Port in both. Close helper.py. Now in tpb.py, set who you want to tweet to by storing it in the TWEETATS variable.

Skip down to the line where the Twitter API is initialized and copy and paste your Consumer Key, Consumer Secret, Access Token, and Access Token Secret into the arguments of the twitter.Api function call.

The final step to configuring the script is to set the BASELINE and THRESHOLD values. These are the ADC readings when the bowl is empty and when it has an amount to water in it that you feel it needs more. To set these values, we're going to use the helper.py script. First, make sure you have your receiver hooked up to your computer and your transmitter powered and the bowl empty. Now navigate to where to you have the helper.py script and double click on it to run it. You'll see a command window open. About every 5 minutes you'll see a sensor reading and an average reading. Be patient and let the script run for a few cycles. Then note the average values. They should be the same or close the same. Take that value and store it as your BASELINE value in the tpb.py script.

Now, fill the bowl up with water or food to the point where you would normally refill it. Again, allow a couple of cycles to happen and record the average number as the THRESHOLD value.

You should be all set up! Now you have a few options as how to make the script run on you computer. One way is to just click on the script whenever you want to use it. Another way is setting it to run on start up.

Step 10: Enjoy

That's it! Just place your bowl where you want it, start the script, and start receiving warning tweets from your bowl. I hope you enjoy.

P.S. I'd like to extend a special thanks to Ladyada, as this project would not have been possible without the guidance found on her site.