Your First Program: “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 impAccelerator™ Fieldbus Gateway’s three LEDs: your device will announce its presence with a visual “Hello, World”.

1. Set up the Fieldbus Gateway

Power up your Fieldbus Gateway so that it connects to the Internet. If you haven’t configured your Fieldbus Gateway 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 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 Fieldbus Gateway, 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 package it up for retrieval by all of the devices assigned to the viewed Device Group. It then tells those devices to restart. Every time an imp-enabled device connects to the Internet, it checks if there is new or updated application code for it to install. If there is, it replaces any code it already has and runs the new software. For your Fieldbus Gateway, 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 Fieldbus Gateway’s three application status LEDs flash on and off, but also messages like these in impCentral’s 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. 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. We use our first object in line three: hardware, which is an object we use to control any device hardware connected to the Fieldbus Gateway’s on-board imp005 module. The hardware object has properties for all of the imp005’s components. We use three of them here: for example, pinP is the General Purpose Input/Output (GPIO) pin that is connected to the Gateway’s red LED. We know pinP is a property of hardware because the two are linked by a period:

hardware.pinP

This says ‘get me the pinP property of the object hardware’. In fact, pinP is an object too, with properties and methods of its own. One such method is configure(), used to set up the pin’s functionality. We could write line 12 this way:

hardware.pinP.configure(DIGITAL_OUT, 1);

This says ‘perform the method configure() of the object pinP, a property of the object hardware’. Writing the relationship between objects, properties and methods this way is called ‘dot syntax’. The brackets after its 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 in this case. A second parameter sets the pin’s initial state. All of the possible values you can pass to configure() are listed in the imp API documentation.

This is an example of the device’s pins being used for GPIO. A digital output pin can be set (‘written’) with two possible values, 1 and 0 (sometimes called High and Low, respectively). This applies a voltages to the pin: either 3.3V (High) or 0V (Low). When the pin is Low, the LED illuminates.

Lines three to five and eight introduce Squirrel’s <- operator, which is used to declare a variable as global (it can be accessed from anywhere within the program) and to assign it an initial value. It’s also used to create and add a entry in a ‘table’, a Squirrel data structure comprising pairs of values and the keys used to identify those values. Why the same operator for both these situations? Because Squirrel stores all global variables in its system table.

We create four globals here: red, yellow and green which are used to store references to the objects representing the Fieldbus Gateway’s three application-status LEDs, and activeLed, which we use to indicate which LED should be lit.

Line 42 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 device 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().

It’s important to note that flash (without the brackets) is the name of the method, ie. a reference to it, but flash() (with the brackets) is an instruction to perform that function immediately.

The use of imp.wakeup() is how program loops are implemented on imp-based devices. Unlike other embedded systems, imp modules have their own operating system, impOS™, and when your code comes to an end or a pause, impOS has an opportunity to perform essential system tasks, specifically maintaining contact with the Electric Imp 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 essential housekeeping functions for the duration of the loop. This is not recommended and should be avoided.

Using a timer to re-call a function is an example if the Electric Imp Platform’s event-driven programming methodology: code is run only when caused 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.

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.