Introduction: TempBug: Internet-connected Thermometer

About: Developer at Electric Imp

Last January, we had some trouble with the heat in my office. Specifically, the kind of trouble wherein the heat is not on, you turn it up, and it still not on. This went on for more than a few days, and finally ended a day or two after we got an email announcing that the heat was broken and speculating that it had probably been down for a few days. My teammates and I laughed a bit at this - we knew exactly when the heat had stopped working. We had a continuous record of the temperature in the office going back months, with 10-minute resolution.

You can do this too, and it's quick, cheap, and easy! This little gadget is built around an electric imp, and you can push the data from the imp out to anywhere you want. In my case, I found it handy to push the data to Sparkfun's Data Stream service, which stores the data for free. Even better, I can use imp.guru's Sparkfun Data Stream frontend to get nice graphs of the data I've collected.

This project takes about an hour to two hours, if you've never done a project with an electric imp before, and when you're done you'll have a thermometer that you can toss anywhere with WiFi and collect data for months to years on a single battery, depending on how often you check the temperature.

Step 1: Gather the Parts

Here are the parts you'll need to build your internet-connected thermometer:

  1. An electric imp (currently available on Sparkfun and Adafruit) - $30
  2. An electric imp breakout board (again, Sparkfun or Adafruit) - $12.50
  3. A 9V battery - $2.00
  4. A 9V battery clip, like this one from Sparkfun (we're just going to cut the end off of it, so the connector doesn't matter) - $1.25
  5. A big capacitor, like this one on Digikey (220 uF, 50V). Make sure it's at least rated to 16V if you're going to connect it to a 9V battery, or you'll have a bad time. - $0.40
  6. A 100kΩ resistor, preferably 1% tolerance, like this one on Digikey. - $0.10
  7. An NTC (negative-temperature-coefficient) Thermistor. I used this one on Digikey. It needs to have a room-temperature resistance equal to your resistor (#6) - this one is 100kΩ at room temperature. - $3.25

Parts total: $49.50

You'll need some tools and supplies, as well:

  1. Soldering iron
  2. Solder
  3. A bit of foam tape or other thick, double-sided tape for securing the battery to the breakout board
  4. Angle cutters / wire cutters
  5. Wire strippers
  6. A smart phone for using BlinkUp to put the imp on your wifi network
  7. A computer to program the imp

Alright! Let's get started!

Step 2: Wire It Up

Check out the breadboard diagram in the photos to see how we'll be wiring up your tempbug.

First, connect the battery clip to the breakout board.

  1. If your battery clip has a connector on the end, cut it off. Strip about 1/8" off the end of each wire and twist the strands to keep them together. If you don't want long leads hanging off your tempbug, you'll want to cut the wire to about 2" long or a little less.
  2. Secure your electric imp breakout board to your work surface and heat up your soldering iron.
  3. One pad at a time, use the soldering iron to heat the "P+" and "P-" battery pads on the breakout board. For each pad, when it gets hot, flow a good-sized bead of solder onto the pad. Take care not to short the pads together.
  4. Place the red lead from the battery clip against the bead of solder on the "P+" pad and heat the pad and wire together with the soldering iron. When the solder flows, hold the parts together and remove the iron. Let the solder cool, then let go.
  5. Repeat previous step with black lead and "P-" pad. Refer to photos to see how this should be arranged. Note that you should follow the label on the board, not right vs. left, as your breakout board may have the pads on opposite sides.

Connect the Capacitor

When the imp turns on its WiFi transmitter, it can draw a lot of current (up to 400 mA, during initial calibration) from your power supply. To keep this sudden current draw from "drooping" the power supply and browning out your tempBug, we've got a BIG HONKING CAP. We'll connect the capacitor in parallel with the battery, the battery will charge the capacitor to the same voltage as the battery, and if the imp suddenly demands more current than the battery can dish out, the capacitor will pitch in to help out.

  1. The leads on the capacitor go through the breakout board at "VIN" and "GND" which are next to each other along the bottom edge of the board. Note that the negative side of the capacitor is marked with a big stripe with a "-" sign in it, and should go to ground
  2. One pad at a time, use the soldering iron to heat the wire and the pad, then flow some solder onto the joint and remove the iron.
  3. When you're all secure, trim the excess from the capacitor leads with your angle cutters or wire cutters.

Connect the Resistor

  1. The 100kΩ resistor can go either way around and is connected between pin9 and 3V3 on the electric imp breakout board.
  2. Bend the wire leads to fit and push them through the holes marked "3V3" and "Pin9".
  3. Just as you did with the capacitor leads, solder ONLY THE 3V3 SIDE to the breakout board. The thermistor needs to share the Pin9 pad with the resistor, so don't solder that side yet!

Connect the Thermistor

  1. Just like the resistor, the thermistor is a passive component and can go either way around. If you bought the same one as me, the wire ends come pre-stripped. Push one end through the Pin9 hole and the other through the hole marked "Pin8".
  2. Now, solder the resistor and thermistor leads together through the Pin9 pad.
  3. Lastly, solder the last thermistor lead into the Pin8 pad.


Alright, all wired up! Let's take a look at what you just built.

Step 3: How's This Thing Work?

The operating principle behind the tempbug is really simple. All we're doing here is making a resistive divider using a resistor and a thermistor, and measuring the voltage in the middle using an Analog-to-digital converter in the electric imp.

Wait, what's a thermistor?

A thermistor is a temperature-dependent resistor; it has a specific resistance at room temperature, and its resistance varies in a known proportion with the temperature of the component. In our case, we've selected a NTC, or negative-temperature-coefficient thermistor; the resistance of the part will decrease as temperature increases.

Got it, but what's the deal with the resistor?

Together, the resistor and thermistor form a resistive divider; the two resistors, wired up in series (end-to-end) have an effective resistance equal to the sum of their individual resistances. This determines the amount of current that flows through them: V=I*R (ohm's law), V=3.3V (from the imp breakout board's 3.3V on-board power supply), R = the 100kΩ + the thermistor's resistance at the current temperature -> now we know how much current is flowing through the circuit.

Going back to Ohm's Law, we know that the voltage across the thermistor = I*R, where I is the current through the divider (they're in series, so both components see the same current), and R is the current resistance of the thermistor. Therefore, if we can measure the voltage at pin 9, we can solve for the resistance of the thermistor. Given the thermistor's resistance, we can determine the temperature of the part.

Hey wait, the other side of the thermistor isn't connected to ground!

Right you are. It's connected to pin 8. This is a sneaky trick we'll use to save the battery. Current flowing through the resistive divider drains the battery, so we'll only let the current flow when we want to measure the temperature. We do this by programming pin8 to be a digital output. When we set pin 8 high, the voltage drop across the divider is 0V, so no current flows. When we want to take a measurement, we drive pin 8 low and sink current from the divider through the imp.

How do we actually do the measuring?

To measure the voltage across the thermistor, we set up pin 9 as an analog-to-digital converter, which allows us to take an accurate measurement of the analog voltage on the pin using the imp. Check out the software in a few steps to see how that's done.


Step 4: Power Up!

Ok, enough math, let's get to the actual temperature-measuring part.

Connect the battery

To secure the battery to the breakout board, a little square of foam tape will do the trick. Cut a small piece off with a pair of scissors and stick the sticky side to the back of the breakout board. Peel back the backing film, and stick the battery on, making sure to keep it nice and square - this stuff is sticky! Once you've got it stuck in place, go ahead and connect the battery clip.

Check the jumper

Make sure the jumper on your breakout board is set to connect the middle pin and the "BAT" pin. Check the photos if you're not sure. If your imp doesn't power up when you click it into the socket, double-check the jumper.

Plug in the imp

Insert your imp into the socket on the breakout board, and it should start to blink red or orange (unless you've connected it before on this network, in which case it will just connect again). Congrats! You're powered up and ready to blink up and program.

BlinkUp

If you haven't already registered as an electric imp developer, you'll need to do that now. Head to ide.electricimp.com to sign up (it's free). You'll also need to download the electric imp app on your smart phone, which is also free - just search for "electric imp". Log into the app with the same account credentials you used to register at ide.electricimp.com.

Once you're logged in, add your wireless network to the list of networks in the electric imp app. If you're on iOS, it will prompt you to allow it to use the network you're already on, and you'll just need to add the password yourself. To add a new network manually, select "other network" and type in your SSID and password. Check the "save this network" button!

Once you've added the network, you're ready to configure the device with BlinkUp. Make sure the imp is powered up. If it's powered up but stopped blinking, reset the power by "push-pushing" the card (push once to disconnect, count to 3, push again to reconnect) so you can be sure it's listening for the BlinkUp signal.

Hold the screen of your phone against the top edge of the imp and press "send BlinkUp" in the electric imp app. The screen on your phone will begin to blink quickly for about 10 to 20 seconds, then stop. The imp should blink green once ("got it!"), then start to blink red/orange ("found the network, connecting to the electric imp server"). After a second or so, the imp should be able to phone home to the electric imp server, and will start to blink green. You're connected. Excellent.

Now it's time to program the imp! Head to the next step.


Step 5: Setting Your Imp Firmware

Point your browser to ide.electricimp.com again and log in. This takes you back to the IDE window.

If you've connected this imp breakout board before (you pro), it will pop back up in the IDE under the model it was last a part of. If this is a brand-new breakout board, it will appear in the IDE's left-hand nav panel under "New Devices", at the top of the panel. You'll see a little number in this panel showing the number of new devices there waiting to be configured - probably just one!

Click "New Devices" to see the list of new devices. Again, if you've never configured this device before, it won't have a name, so it will default to a long hex string (this device's Device ID). Click on the small gear next to the device name to open up the settings for the device. This is where you can name the device and assign it a model. Go ahead and name it whatever you like, and create a new model by typing a name for your new model in the model drop-down and pressing enter. When you hit "save changes", you'll be taken to the code window for this new model, and you'll see your new device is now listed under that model in the left-hand nav.

A model has two parts: an agent and a device. The device firmware is simply the code that runs on the imp itself. The agent is that device's partner - a tiny server that runs in the electric imp cloud. The device and agent can send information back and forth, and the agent can talk to the rest of the internet and has its own URL. You get to write code for both of them.

... Or you can use the code that's already written for you :)Head to github, and notice that there are two files here - one for the agent and one for the device. Accordingly, there are two windows for you in the IDE - one will say "agent" and the other "device". Copy the correct code into each window.

If you hit "Build and Run" now, you'll see the device read the temperature and then go to sleep, but the agent will have an error when it tries to log the data to Sparkfun because you haven't added your Sparkfun account yet. Let's do that next. If you did do this, and your device has gone to sleep for 15 minutes, you can disconnect and reconnect power (by simply pulling and re-inserting the jumper) to get the imp to wake up again.

Let's connect your new thermometer to Sparkfun to log the data, then we can come back and take a look at what makes the firmware work.

Step 6: Connecting to Sparkfun Data Stream

To connect your thermometer to Sparkfun, you'll first need to create a new Sparkfun Data Stream. Head to data.sparkfun.com and click on "Create" on the right side of the page.

You'll need to fill in a few details about your new stream: a title, a description, and some data fields. What you call the data fields is important: make sure you create a field called "temp". The electric imp code is set up to post the temperature data with this field name, and if the fields don't match, your code will throw errors. You can create other fields if you want, too, but the only one you need (and the only one your code is already set up to use) is "temp".

Once you've filled in the details and clicked "save", you'll be taken to a page with the keys to your new stream. Save the public and private keys from this page. You'll need to add these keys to your electric imp agent code in order to tell your TempBug which Sparkfun Data Stream to post the data to. Save the stream URL you configured, too - it'll be a quick and easy place to see your data arrive in the Sparkfun stream.

Paste your keys into lines 6 and 7 in the agent back in the electric imp IDE:

const SPARKFUN_PUBLIC_KEY = "YOUR PUBLIC KEY HERE";
const SPARKFUN_PRIVATE_KEY = "YOUR PRIVATE KEY HERE";

Click "Build and Run" in the electric imp IDE to deploy the code that now includes your keys. Your thermometer is probably asleep, so if you want to test it right away, do a quick push-push (push the imp card to eject it from the SD socket, count to 3, push it in to the socket again) to reboot the imp, and you should see the logs report a successful post to Sparkfun!

2015-01-30 09:15:05 UTC-8[Status]Device Booting; 5.14% program storage used
2015-01-30 09:15:05 UTC-8[Agent]PUSH: 200 - 1 success
2015-01-30 09:15:05 UTC-8[Device]sleeping until 1422639001000 2015-01-30 09:16:51 UTC-8[Status]Device disconnected

Point your browser at the Stream URL you configured when you set up your data stream to see the data logged in the Sparkfun stream. Of course, you'll probably want a graph. Good news: that's easy.

Head to imp.guru and you'll find a page that asks for your Sparkfun stream public key. Paste the public key in here and hit enter, and the page will build you a graph of your temperature data!

Let's head back to the code editor and take a look at how the imp is working this magic.

Step 7: Digging Into the Code

Imp firmwares are written in an object-oriented language called squirrel, which looks and feels a lot like javascript. Squirrel runs in a virtual machine on top of the imp OS inside the imp, so runtime errors won't knock your device offline, and you have access to a lot of nice OS-based features, like buffered serial input and easy one-line APIs to set GPIOs or communicate with peripheral devices.

To take a look at all the things you can do in your imp firmware, check out the electric imp API reference and electric imp worked examples page. To see which pins can do what, check out the imp pin mux.

Our code here is pretty simple. Here's our basic operating procedure:

  • Set some constants
  • Define a class for our temperature sensor
  • Instantiate our class to create a temperature sensor object
  • Read the Temperature Sensor
  • Send the datapoint to the agent
  • Schedule ourselves to wake up in a bit and do it all again

The constants on lines 8 and 9 look a little ominous, but they're simple. These are the parameters for your thermistor - you can find them on the datasheet for the thermistor you're using. If you're using the thermistor I linked to earlier, you can even keep the parameters already set here.

Lines 20 to 71 are a class definition - this is basically a set of instructions for how to do various important things with a thermistor, like read the temperature. This comes straight from github - it's a nice, modular piece of code so that it can easily be reused.

After that, we just need to define our high-level logic. On lines 79 to 83, we configure the two pins we're using. Remember from when we built the device - one of the pins is anenable pin, which will allow current to flow through the thermistor when it is set low. The other pin is our analog input pin, which we'll use to read the voltage across the thermistor.

// Configure Pins
// pin 8 is driven high to turn off temp monitor (saves power) or low to read
therm_en_l <- hardware.pin8;
therm_en_l.configure(DIGITAL_OUT);
therm_en_l.write(1); 
// pin 9 is the middle of the voltage divider formed by the NTC - read the analog voltage to determine temperature
temp_sns <- hardware.pin9;

On Line 86, we call on our class definition from earlier to create a thermistor object. This object takes in the constants we set earlier, and has methods that allow us to read the temperature in Celsius or Fahrenheit.

// instantiate our thermistor class
myThermistor <- thermistor(temp_sns, b_therm, t0_therm, 10, false);

Lines 88 to 96 are where the magic happens - we enable the sensor, take a reading, send it to the agent, and disable the sensor again to save battery.

therm_en_l.write(0);
imp.sleep(0.001);
local id = hardware.getdeviceid();
local datapoint = {
    "id" : id,
    "temp" : format("%.2f",myThermistor.read_f()),
}
agent.send("data",datapoint);
therm_en_l.write(1);

And lastly, schedule a wakeup in fifteen minutes. We'll go to deep sleep in the mean time, saving the battery:

//Sleep for 15 minutes and 1 second, minus the time past the 0:15
//so we wake up near each 15 minute mark (prevents drifting on slow DHCP)
imp.onidle( function() { 
    //server.sleepfor(1 + 15 - (time() % (WAKEINTERVAL_MIN*15)));
    server.sleepfor(1 + WAKEINTERVAL_MIN*60 - (time() % (WAKEINTERVAL_MIN*60))); 
});

That's the device firmware - let's take a look at the agent. You've already seen part of the agent - we set the Sparkfun Public Key and Private Key lines 6 and 7 of the agent earlier. Below that, we have another class definition; this one defines methods for interacting with a Sparkfun Data Stream.

Lines 62 to 65 are a really interesting bit of code - this is the hook that the agent uses to receive new temperature data from the device. This is done by registering an agent "callback" with agent.on. This says, "when the device sends you an event called "temp", call the following function with the data marked with that tag". Looking back at line 95 of the device firmware, we see that we sent data marked "temp" with a function called "agent.send". This is where that data went!

device.on("data", function(datapoint) {
    local resp = stream.push({"temp": datapoint.temp});
    server.log(format("PUSH: %i - %s", resp.statuscode, resp.body));
});

Lastly, we see the agent do two things when it first starts running. The first: it sends a log message letting us know that it started and is ready to get data. Second, it instantiates a Sparkfun Data Stream object with the class we defined earlier, letting us use the methods of those classes to send data to Sparkfun as it comes in.

The agent doesn't restart or sleep; it starts the first time the device boots with this model, and continues to run forever, handling each new datapoint when it comes in by calling the "device.on" callback. It's the device's brain in the cloud!

That's the firmware! Enjoy your new Internet-connected thermometer.