Hello World

This is a simple ‘Hello World’ application which turns on LEDs when buttons are pressed. If you press EVB button BTN1, the board’s multi-color LED glows blue. If you press button BTN2, the LED turns green. If you press both buttons, the LED glows red.

Peripherals Used

• Buttons BTN1, BTN2
• RGB LED

APIs Used

• pin

Setup

Create a Developer Account and add your EVB to impCentral™

1. Create a free Developer Account to access Electric Imp impCentral and log in.
2. Download the Electric Imp app from the App Store or Google Play store on your iOS or Android device, and log in using your Developer Account credentials.
3. On the Connect an Imp page, select your WiFi network.
   • The imp only operates using 2.4GHz 802.11b, g or n. 5GHz networks are not supported.
4. Use BlinkUp™ to configure your EVB for Internet access. Power up the EVB then press Send BlinkUp in the Electric Imp app. As soon as you hear the countdown tones, place your tablet or phone’s screen against the EVB’s imp003/LBWA1ZV1CD breakout board until the screen stops flashing and you hear a second set of tones.

If you are having problems getting the EVB online, please consult the BlinkUp Troubleshooting Guide.

A successful BlinkUp operation is indicated by a slowly flashing green LED on the EVB. The EVB will be listed in impCentral’s ‘My Development Devices’ list (accessed via the devices menu in the black bar at the top). The number presented in impCentral is the EVB’s unique Device ID. You can, if you wish, give it a more friendly name as follows:

1. Click ‘Settings’ in the ‘MANAGE’ column.
2. In the ‘Device Settings’ panel, enter a new name and click ‘Update’.

Create a New Product and Device Group

1. Click on your account name in the grey bar at the top of the window to view a list of your Products — this will be empty initially.
2. Click ‘Create New Product’.
3. Enter a name for the Product: “EVB”.
4. Enter a name for the first Device Group: “Hello World”.

Add Code

1. Copy the device code from our GitHub repo and paste it into the impCentral’s code editor ‘Device Code’ pane.
2. Click ‘Build and Force Restart’ to transfer the device code to the imp003/LBWA1ZV1CD and the agent code to Electric Imp impCloud™, and to run them.

What’s Going On

The purpose of this example is to illustrate how you configure and interact with the imp003/LBWA1ZV1CD module’s GPIO pins. This is achieved through the imp API's Pin() class, which is instantiated at startup as an object, hardware.pin, one for each of the available imp003/LBWA1ZV1CD pins and named for them. All of the imp003/LBWA1ZV1CD’s available pins are listed on the pin mux page

In order to use an imp003/LBWA1ZV1CD GPIO pin, you need to configure it for a particular purpose: digital or analog input or output; UART, SPI or I²C bus; and so on. In this case, we want to interact with button inputs and LED outputs.

First, for convenience we assign the hardware pins a variable name. If you are new to the Squirrel programming language used by the imp003/LBWA1ZV1CD, the <- that appears in the code below is Squirrel’s assignment operator for global variables. To learn more about Squirrel, see the Squirrel Programming Guide.

// Pin allocation

btn1 <- hardware.pinU;
btn2 <- hardware.pinV;
led_blue <- hardware.pinK;
led_red <- hardware.pinE;
led_green <- hardware.pinF;

Next, we configure these buttons as digital inputs using the imp003/LBWA1ZV1CD’s built-in pull-down resistors by using the constant DIGITAL_IN_PULLDOWN. Internal pull-down resistors ensure the input will read 0 unless the button is pressed. Had we connected external pull-down resistors, we would configure the pins with DIGITAL_IN.

// Button configuration

btn1.configure(DIGITAL_IN_PULLDOWN);
btn2.configure(DIGITAL_IN_PULLDOWN);

Lastly, we configure the LED pins as digital outputs:

// LED configuration

led_blue.configure(DIGITAL_OUT);
led_green.configure(DIGITAL_OUT);
led_red.configure(DIGITAL_OUT);

To read a value from a specific input pin — in this case the one already connected to BTN1 on the EVB — we simply call:

btn1.read();

To change the state of an output pin you call:

led_red.write(value);

where value is 1 or 0 — or another value if the pin is configured as a different type of IO device.

One way to continually check the state of the buttons is to poll their values by calling pin.read() in a loop. However, this approach blocks Squirrel’s single execution thread and prevents the imp OS from maintaining communications between itself, its agent and impCentral. A better technique is to make use of the imp’s event-driven programming methodology and have the pin trigger a callback function if and when its state changes.

This is what the following code does. First, we define the function, and then register it as a callback in the pin.configure() call:

// Button event handler (button1 = blue, button2 = green, button1 + button2 = red)

function configureLights()
{
    led_blue.write(1-btn1.read());
    led_green.write(1-btn2.read());
    led_red.write(btn1.read() == 1 && btn2.read() == 1 ? 0 : 1);
}

// Button configuration

btn1.configure(DIGITAL_IN_PULLDOWN, configureLights);

Now every time the button is pressed or released, the configureLights() function is called to assign new values to the LED-connected pins, in turn switching the LEDs on or off.

To learn more about the imp’s event-based programming style, see Event-driven Programming. To discover the right way to implement program loops, see our guide to writing program loops the imp way.

In the next section, we’ll examine how to begin to connect the imp003/LBWA1ZV1CD EVB to environment sensors and log the data to a graphing web service.