Skip to main content

Ready-to-Run Code Libraries

Now you understand that there are two parts to each imp application — the agent code and the device code — you’re ready to develop your own connected application. However, you might very well be wondering how you’re going to come up with all the code you need: the software that runs in the cloud and connects your application to services such as Azure, AWS, PubNub and Twitter, and the code that runs on your device that communicates with the peripherals you want to build into your hardware, such as LEDs, LCDs, sensors and actuators.

The good news is that much of this code has already been written for you. Better still, it’s really easy to incorporate this existing software into your own.

Electric Imp maintains a library of Squirrel classes — templates for objects which represent anything from a web service to a hardware add-on — any of which you can include in your code with a single instruction. In fact, you’ve already used one of these libraries: WS2812.class.nut. However, there are many more. For example, we can make use of libraries to work with the impExplorer™ Developer Kit’s on-board sensors. And we can use the Twitter library to publish the results.

1. Power up the impExplorer Developer Kit

Power up you impExplorer Developer Kit so that it connects to the Internet. This time don’t use the USB port, use three AA batteries (not included) and fit them into the bay on the underside of the impExplorer Developer Kit.

If you haven’t configured your impExplorer Developer Kit for Internet access yet, this section will show you how.

2. Open impCentral

If you’ve just completed the previous section of the Getting Started Guide, you’ll have impCentral open on your computer. If not, load it up now and sign in using the account log-in details you created in the first part of this Guide.

Locate the Connected Product Product and its Test Hardware Device Group that you created earlier:

  • Click Account in the nav var.
  • Select your personal account.
  • Find Connected Product in the Products list.
  • Click Development Zone in the MANAGE column.
  • Find Test Hardware in the Development Device Groups list.
  • Click Code in the MANAGE column.

impCentral’s code editor will now appear.

3. Program Your Device and its Agent

Here is the code you’ll need to run the example — just replace any code you’ve already entered. Again there are two parts: code for the device, and code for the agent. Copy the two code listings below, making sure you paste each one into the relevant part of the impCentral code editor. If you’re not sure which part of impCentral is which, refresh your memory here.

Device Code

Agent Code

What the Code Does

Let’s look at the device code first. The first three lines are the important ones: they use the directive #require to load in a series of libraries. In each line, you can see the library’s name between the double-quote marks, along with the version number and a colon to separate the two. This formatting is important: you must include both the full library name and the version number you want, and you must separate these two bits of information with a colon and wrap them all in double-quotes. Don’t place a semi-colon after the directive as this is an instruction for the compiler, not Squirrel code.

The body of the device code follows — and must follow — any #require statements you include.

Next we declare constants and global variables, among them variables which will reference the impExplorer Developer Kit’s sensors and RGB LED. This is followed by the function that we’ll call to take a set of readings, flash the LED to indicate activity and then put the impExplorer Developer Kit to sleep to preserve your AA batteries.

The next function performs the aforementioned flash: it sets the LED blue, pauses for half a second and then clears it.

In the last section, the impExplorer Developer Kit’s I²C bus is configured and used to instantiate the software objects that represent the impExplorer Developer Kit’s temperature and pressure sensors. Notice we assign the bus to the local variable i2c; all Squirrel variables which are not global must be marked as local to their context using the local keyword. Next, we set up the LED as we did in the Hello World section and, finally, call the function that takes the readings.

This program is quite linear: we set everything up, take a set of readings, flash the LED and tell impOS™ to put the device to sleep as soon as it can. We don’t actually need to declare functions here, but doing so helps modularize the program so that it’s easier to use the parts of the code presented as functions in other programs.

Why do we do all that set up every time? When an imp goes to sleep, it enters a very low-power state to preserve energy. This is very handy if you’re powering it with batteries. It means we only need expend significant amounts of energy when we power the impExplorer Developer Kit up (every two minutes, as set by the constant SLEEP_TIME, which is passed into server.sleepfor() in line 30 to take readings and connect to WiFi to send them (line 23). When the on-board imp001 wakes from sleep, it starts its Squirrel code in a fresh state, so we have to re-configure components and buses.

Why do we not just call server.sleepfor() in line 29? We could but by embedding the call in the imp API’s imp.onidle() we give impOS time to perform any necessary housekeeping before putting everything to sleep. This is the recommended approach. imp.onidle() registers a function that will be called when the imp001 goes idle. Here we don’t pass in a the name of function, we use an inline function declaration.

Now you understand how libraries are included in code, you know what happens in the agent. Once again, we include a library — the Twitter library — at the start of the program. Don’t forget, it has to go right at the top — you can’t include libraries further on in the code or they‘ll be ignored. We also make sure the #require statement provides all the information the code compiler needs: the full library name and the version number.

The agent uses the Twitter library to establish a Twitter instance, tweeter, which we configure with access credentials (see below). We register the function that will be called when the agent receives a message ("reading.sent") from the device indicating the device has been moved. This function extracts the data sent by the device, puts into a message which the Twitter class instance tweets.

4. Run the Code

To try this for yourself, you’ll need to visit Twitter and sign up as an application developer. Go to the Twitter website and sign in using your own Twitter account. If you don’t have a Twitter account yet, you’ll need to set one up now. When you’ve signed in, go to the site’s apps section. Here you’ll need to click the Create New App button and provide the information Twitter requests:


 

This process is designed for app developers who want to embed a Twitter feed into their own code. Although we’re not developing an app here, we’ll use the same approach. When you’ve set up your app, look for the Keys and Access Tokens tab. Here you’ll find the four codes — Consumer Key (API Key), Consumer Key Secret (API Secret), Access Token and Access Token Secret — that you’ll need to copy into the agent code.


 

Select these four values one at a time and paste them into the agent code where you see them (line 19). Now click Build and Force Restart — and watch your Twitter stream!

Where Next?

To find out all the libraries that we currently offer — the list is always growing — visit the Libraries page. It also includes more information on including libraries in your code, some troubleshooting guidance, and describes how you can make libraries you write accessible via the Electric Imp Platform.

To find out where to go next as an Electric Imp Developer, take a look at the next section.