Electric Imp

This tutorial will help you to start using CommonSense on the electric imp platform.

We used an imp card (imp001) with an April development board to create this guide.

April is a simple breakout board which provides the minimum an imp needs to run.
There are other reference boards which provide more functionality.

The hardware page has a lot of information on creating imp powered devices.

Hardware and software requirements

For this tutorial you will need the following things:

  • imp card (or an imp002 solder down module)
  • imp breakout board
  • headers
  • jumper
  • breadboard
  • breadboarding wire
  • resistors
  • a LED
  • a simple photocell
  • CommonSense account
  • Electric Imp account
  • Our library containing snippets and full examples, including the code used in this tutorial
  • The Electric Imp app (available for iOS and Android)


You will need at least an imp and access to the online IDE to start programming your imp.
However, the most important feature of the Electric Imp platform is connecting your Device to the internet. This can easily be done using an Agent.

Your device and agent programs will be written in Squirrel using the Electric Imp API.


This tutorial contains several terms commonly used in the Electric Imp community. The Electric Imp team has published a glossary on their website.

Setting up the hardware and software

Depending on the vendor you got your board from, you may have to solder components to it yourself.

Once you've got the board fully assembled, connecting a power source should make the imp blink orange.

To start programming you will have to connect it to the imp cloud.
In order to configure wifi you will have to use the Electric Imp app.

This guide explains how the configuration process works.
If you run into problems during configuration, there's a troubleshooting page explaining the colour codes.

Hook up the photocell and LED to the imp using either of the following diagrams.

tutorial_bb tutorial_schem

There is no real software setup for the Electric Imp platform. All you need is a web browser to use the online IDE.

The Electric Imp IDE

Go to the IDE and have a look at the device list to the left. If you completed the configuration process there should be a new device available.

Click on the device and give it a name e.g. 'living room'. The 'associated model' is a name for the entire product e.g. 'environment monitor'.
You could have multiple devices of the model 'environment monitor' where you distinguish them using their names.

Selecting the device will show your code and a log. Feel free to resize the compartments however you like. The buttons in the top-right corner allow you to change the view settings or go full screen.

The basics

Here's a breakdown of the tutorial program (examples/tutorial/) in our repository (which can be found here).

Unfortunately there currently is no way to include code other than copy pasting it into the IDE. You will have to copy the functions from examples/tutorial/agent.nut in order to use them.

This example will be polling a photocell every 10 seconds and turn on a LED accordingly using PWM.

Start by setting things up. The device will tell the agent to get started and provide it's unique id.

Agent code:

credentials <- {}; // create a table to hold our credentials

credentials.username <- "user";
credentials.password <- "5f4dcc3b5aa765d61d8327deb882cf99";

device.on("initialise", function(impeeid){ // the device is telling me to start
    uuid <- impeeid; // store my impee id
    session_id <- GetSessionId(credentials); // store my session_id

    server.log("uuid: "+uuid); // print my impeeid in the log
    server.log("session_id: "+session_id); // print my session_id

Device code:

agent.send("initialise", hardware.getimpeeid()); // tell the agent to get started

Now create a sensor on CommonSense. The data from the photocell will be stored in this sensor.

Agent code:

device.on("initialise", function(impeeid){ // device tells me to start ...
    uuid <- impeeid; // store my impee id
    session_id <- GetSessionId(credentials); // store my session_id

    photocell_id <- CreateSensor("gl5528", "ldr", "photocell", "json", "\"{\\\"value\\\":\\\"Integer\\\"}\"", uuid, session_id);

    server.log("uuid: "+uuid); // print my impeeid in the log
    server.log("session_id: "+session_id); // print my session_id
    server.log("photocell_id: "+photocell_id); // print my photocell_id

Now that you've set everything up, it's time to start uploading data and using it afterwards. The device will be reading the photocell every millisecond and adjust the brightness of the led. Every 5 seconds it will upload the value that was most recently read.

Agent code:

device.on("upload", function(value){
    local data = {}; // create a table 
    table.lux <- data; // put the value from the sensor as value for the sensor

    UploadData(data, photocell_id, session_id); // upload the data to the right sensor

Device code:

photocell <- hardware.pin1;

photocell_value <- 0;

led <- hardware.pin9;
led.configure(PWM_OUT, 1.0/200, 0);

function ReadPR(){
    photocell_value = photocell.read();

    led.write(1 - (photocell_value.tofloat()/math.pow(2,16)));

    imp.wakeup(0.001, ReadPR);

function UploadData(){
    agent.send("upload", photocell_value);

    imp.wakeup(5, UploadData); // wakeup in 10 seconds to do the same thing again


For the complete examples check the repository.

More learning resources

If you're familiar with Lua this blog post may be interesting.