Skip to main content

Your First Project: “Hello, World”

Getting a new device to turn on an LED is the classic ‘Hello, World’ application: it shows that the core hardware is working. That’s what we’re going to create here. You’ll use impCentral™ to enter some code which, when run, will flash your imp005-EZ Eval Kit’s three LEDs: your device will announce its presence with a visual “Hello, World”.

1. Set up the imp005-EZ Eval Kit

Power up your imp005-EZ Eval Kit so that it connects to the Internet. If you haven’t configured your imp005-EZ Eval Kit for Internet access yet, the BlinkUp section will show you how.

2. Open impCentral

If you’ve just completed the previous section of this 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 earlier.

Locate the Connected Product Product and its Test Hardware Development Device Group that you created in the previous section:

  • 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

You program your device using a language called Squirrel. This is very similar to C and its many popular derivatives, such as C++ and JavaScript. There are a few subtle differences between Squirrel and these others languages, but nothing that should hinder experienced or new programmers. The Squirrel Programming Guide in the Electric Imp Dev Center details the points where Squirrel diverges from these languages, and covers those areas where it offers unique functionality and methodologies. The Electric Imp Dev Center also includes a full Squirrel reference.

All Squirrel programs will need to use at least some of the imp API — the objects and classes that encapsulate your imp005-EZ Eval Kit, its on-board imp005, any connected hardware, and its Internet connection.

The Code

For this example, we’ve written the code for you: just copy and paste it into impCentral’s Device Code pane:

To run the code, click the Build and Force Restart button. This tells impCentral to check the code’s syntax and then parcel it up for retrieval by your device. It then tells your device to restart. Every time an imp-enabled device connects to the Internet, it checks if new or updated code is available. If there is, the imp replaces any code it already has and runs the new program. For your imp005-EZ Eval Kit, the new code is the program you just pasted into impCentral.

This code will now run on your device. You should not only see the imp005-EZ Eval Kit’s RGB LED flash on and off, but also messages like these in the impCentral log window:

[Status] Device Disconnecting
[Status] Device Booting; 0.37% program storage used

What the Code Does

Though very simple, the code illustrates some key aspects of how imp-enabled devices work. Line two shows how we define a Squirrel class, in this a driver for the imp005-EZ Eval Kit’s APA102 RGB LED. We instantiate that class in line 83, and call its methods in line 78: set() to specify the colour in the form of an array of three numbers representing red, green and blue values, and draw() to update the LED.

Class? Instantiate? Methods? If these terms are unfamiliar to you it’s because you may not have encountered objet-oriented programming before. As we noted earlier, Squirrel is an object-oriented language. An object is a software construct that combines data (called ‘properties’) with functions (called ‘methods’) that work with that data. Classes are template objects and are primarily used to create working copies (‘instances’).

We use our first object in line 18: hardware, which is an object we use to control device hardware connected to the imp. The hardware object has properties for all of the imp’s pins and standard component-communication buses. We use one of the pin properties here: pinY, which represents one of the imp005-EZ Eval Kit’s GPIO pins. We know pinY is a property of hardware because the two are linked by a period:

hardware.pinY

This says ‘get me the pinY property of the object hardware’, and the use of the period to indicate this relationship is called ‘dot syntax’. In fact, pinY is an object too, with properties and methods of its own. One such method is configure(), used in line 19 to set up the pin’s parameters.

The brackets after configure()’s name tells the device to call (run) that method — configure() takes a value which tells the device how the pin should operate: as a digital output (DIGITAL_OUT) and with an initial output value (0). All of the possible values you can pass to configure() are listed in the imp API documentation.

Lines 71 and 72 introduce Squirrel’s <- operator, which is used to mark a variable as a global and to assign it an initial value; future assignments of a global variable use the = operator, as you can see in line 83. The <- operator is also used to create and add an entry into a ‘table’, a Squirrel data structure comprising key-value pairs. Why use the same operator for both these situations? Because Squirrel stores all global variables in its system table.

We create two globals here: led, which we'll use to refer to the APA102 RGB LED, and state, which records whether the LED is lit or not.

Line 79 is also important. It calls the imp API method imp.wakeup() — which we now know means ‘the method wakeup() of object imp’. This method tells the imp to run the function named in the second parameter when the number of seconds specified in the first parameter have elapsed. In this case, we pass the name of the function we’ve just run, flash().

Remember, flash (without the brackets) is a reference to it, but flash() (with the brackets) is an instruction to execute that function now — which is what we need to start the loop, in line 86.

This is how program loops are implemented on imp-based devices. Unlike other embedded systems, imps have their own operating system, and when your code comes to an end or a pause, this OS has an opportunity to perform essential system tasks, specifically maintaining contact with the impCloud™ and impCentral. If we had used a classic delay loop, such as

local i = 0;
do {
    i++
} while (i < 10000);

we would dominate (‘block’) the imp’s single execution thread and prevent impOS from performing its housekeeping functions for the duration of the loop. This should be avoided.

Using a timer to re-activate the program is an example if the Electric Imp Platform’s event-driven programming methodology: code is run only when triggered to do so by an event. If impOS has done its work, and there’s no user code that needs to be run yet, the device can slow down to conserve power, or even go into a sleep state. We’ll explore this event-driven nature further in the next section.

The code you just entered isn’t interactive: you have no way of controlling the LEDs while the program is running. We’ll implement code to change the state of each LED remotely, via the Internet, in the next section.

Further Reading