Getting started tutorial with Waspmote

This tutorial explains how to connect the Waspmote PRO v1.2 equipped with the Wifly Wifi module from Libelium to Lhings and how to create interesting applications with it. Before trying, make sure you have created a user account in Lhings.

This tutorial applies to release wa001.

Basic Concepts

What is Lhings?

In brief, Lhings is a platform which provides connectivity features to your devices through the internet. Using Lhings you can easily receive information from your devices and control them remotely. You can even delegate the control of some devices to others, so that your own ecosystem of Things works automatically.

What is a device in Lhings?

Basically, a Device is a physical object which can perform a set of actions, and can notify about the occurrence of some events. A sensor, an actuator, a ball, a computer, a table and a button could interact among themselves whenever they connect to internet and communicate to Lhings. Would you like your Device to communicate to Lhings? We tell you how!

Actions and events

Device operation and interaction capabilities are defined through actions and events. As an example, suppose you have an alarm clock connected to Lhings and was set to ring at 12:00h. An event would be the notification the alarm clock generates when it triggers at 12:00h, while an action would be to make it ring under the reception of a command or order. Device actions and events can be customized and edited through its descriptor. This is described in detail further in this tutorial.

What is a Rule in Lhings?

Rules are relationships between events and actions that allow the interaction among different Devices. This refers to: when an event occurs, then do that action. You can create and edit your own Rules in your dashboard and automate their interaction.

Getting started

Before starting you must have a user account registered in Lhings. For this example, please check that you have the following items:

  • One Waspmote PRO board.
  • One Wifi Module (Waspmotes are used to bring the Wifly RN-XV).
  • One USB cable for programming and powering.
  • A home router connected to the internet.
  • The Waspmote IDE installed on your computer. Download it from here.
  • The Waspmote Lhings Library. You can download from the releases page.
  • The Lhings Getting Started example, which is included in the examples folder of the release archive.

Once you have all these items in place, follow these steps:

1. Set up your programming environment.

  • Import the Lhings_Waspmote_library. In the Waspmote IDE go to Sketch → Import library → Add library, and navigate to the folder where you unzipped and saved the file Lhings_library.zip. Select the folder Lhings_Waspmote_library.

  • Open the example sketch. In the Waspmote IDE go to File → Open, and navigate to the folder where you saved the file Lhings_Waspmote_example.pde. This is an example sketch that must be edited with your Lhings credentials and may be modified to suit to your requirements.

2. Set your network settings in your device.

Once you have opened the example sketch, you must edit your Waspmote WIFI settings, so it gets access to your router and to the internet. As this example uses the Wifly module (RN-XV), it is necessary to edit the Wifi access point (AP) Name and its Security Phrase:

#define ESSID "MyWifiName"
#define AUTHKEY "MyWifiPassword"

3. Set your Lhings credentials on your device

 (do not have credentials? Check our FAQs).
  • Relate your device with your Lhings account. First, you need to introduce a couple of access parameters in the code: username and API-KEY. To get your API-KEY, you will need to log into your Lhings account and click on your username. In the page that appears look for your API-KEY and copy it.

  • In your sketch you have to edit these couple of access parameters in the following #define directives:

#define LHINGS_USERNAME "your_username_here"
#define LHINGS_APIKEY "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxxx"

These two directives will be used by the Lhings library to authenticate against the server.

  • You also have to edit your device name, using the directive:
#define LHINGS_DEVNAME "your_device_name_here"

The device NAME can be whatever you want as long as all devices in your account have different names. Leave the following directive as is, because is deprecated and will be removed in future releases:

#define LHINGS_DEVUUID NULL

The device descriptor

As the final configuration step, you have to set up your device descriptor. The device descriptor is a file that tells Lhings which are the capabilities of your device, i. e., which are its actions, events, and state variables. Each time the device starts session, it sends the descriptor to Lhings, so that it knows how to talk to your device, and how to configure the Lhings web interface for it.

For simple descriptors, the library has a built-in feature to generate the descriptor for you, to save you typing and to avoid errors. In order to configure the descriptor, you have to define which are the actions, events and state variables for your device. You can do this using the following three arrays:

Action_List  Lhings_ActionList[] =  {                               
                                      {"threshold++", ACT_BUTTON},      	
                                      {"threshold--",  ACT_BUTTON},
                                      {NULL, 0}
                                    };		
Event_List   *Lhings_EventList[] =  {"temp. change", NULL};				
Status_List  *Lhings_StatusList[] = {"temperature", NULL};

Do not forget to NULL terminate the arrays. If you have no actions, events or state variables, simply leave NULL as the only item in the corresponding array. The Lhings library will use these arrays to build the device descriptor.

Actions are defined in the Lhings_ActionList[]. Each action is defined by pairs: {action_name, action_type}. These actions will appear in Lhings when accessing the Control Panel of this device. Thus, each action will appear with its corresponding name and displayed with the appropriate widget. In this version of the library these types are allowed: ACT_BUTTON and ACT_STRING.

When setting up the descriptor this way, all the statuses you define in Lhings_StatusList[] will be of type string. In fact, in this version of the Waspmote library the amount of status variables is limited to 8. You can change its value using the function of the library statusWrite(char *status_name, char *status_content); .

For the sake of completeness, we provide here the device descriptor that the Lhings library generates for our getting started sketch example:

{
    "version": "1",
    "deviceType": "waspmote",
    "friendlyName": "waspmote",
    "manufacturer": "libelium",
    "modelName": "WaspMote",
    "actionList": [
        {
            "name": "threshold++",
            "description": "action",
            "inputs": []
        },
        {
            "name": "threshold--",
            "description": "action",
            "inputs": []
        }
    ],
    "eventList": [
        {
            "name": "temp. change"
        }
    ],
    "stateVariableList": [
        {
            "name": "temperature",
            "modifiable": false,
            "type": "string"
        },
        {
            "name": "threshold",
            "modifiable": false,
            "type": "string"
        }
    ]
}

If you want to learn more about the device descriptor and how to provide additional details about your device, check the reference about the device descriptor.

How to use this library

Now your sketch is properly configured to use Lhings. But you still have to include a couple of lines of code in order to make it work. First, you need to initialize the Lhings’ STUN-based engine. Include the next line in the setup() function:

if(!Lhings.begin(LHINGS_DEVNAME, LHINGS_DEVUUID, LHINGS_USERNAME, LHINGS_APIKEY))
     USB.println("ERROR: vars. out of range");

Finally, in your loop() function, you need to call the Lhings main loop, which is who actually does the hard work for you:

Lhings.loop();

Now you have configured your sketch to use Lhings. The rest of the programming is up to you!! You can program your Waspmote like you would normally do.

What happens if the device is "deleted" from Lhings?

When a connected device is deleted from Lhings, it's automatically detached from your account. This means that the UUID used by your device will be rejected by Lhings as it's not recognized.

To connect again your device to your account or to another one, your device will need a new UUID. In the case your device is a Waspmote, and the UUID was received from Lhings during the installation process and stored in its EEPROM, you must erase the saved UUID directly. Therefore, you must program your Waspmote with a reset instruction:

void setup(){
    Lhings.reset();
}

void loop(){ }

Notice that this is a particular case for Arduinos or Waspmotes. Programming it again without the reset instruction doesn't erase the UUID and will not connect to Lhings.

What else?

Now you can upload your sketch to your device and see how it works. Open your serial monitor, and you will see how it talks to the Lhings server. Also, you can enter the Lhings web interface, and you will see your Waspmote in the Devices section. Click on it and select an action. In this example, temperature threshold can be incremented and decremented.

By the way, one interesting tip: How does the Lhings library redirect the actions received to the actual code that performs the action? Easy. Look at the following line in your sketch, the reception of the action with name “threshold++” is checked. If this action is received, perform an increment of the temperature threshold:

if(Lhings.actionAvailable("threshold++")){
   
    // Set new threshold
    if(tempThresholdValue < 10){
         tempThresholdValue++;
         sprintf(tempThreshold, "%dºC", tempThresholdValue);
         USB.print("Incremented threshold: ");
         USB.println(tempThreshold);
    }
}

The function Lhings.actionAvailable(char* name) will return true when an action with a determined input “name” is received. This name must correspond to one of the previously defined actions in Lhings_ActionList[].

You can also send events using the function Lhings.eventWrite(char *name) or eventWrite(char *name, char *payload, int len, bool type) when your event has payload data. The event name must correspond to one of the previously defined events Lhings_EventList[]:

Lhings.eventWrite("temp. change", &tempPayload[0], strlen((const char*)tempPayload), EVT_PAYLOAD);

NOTE: this library applies STUN-based communications. It means that it needs periodic keep-alive packet transmissions. For low-power applications that require minimum communications and low-battery consumption, it’s recommended to communicate with Lhings via API.

What have we learnt?

Important lessons to keep in mind:

  • In Lhings a device is something that can perform actions and can send events.
  • Lhings knows which actions and events your device has because it reads the descriptor file sent by the device.
  • In order to use Lhings in your sketch you have to configure some #define directives with information regarding your account and your device.
  • Include the Lhings.begin() function in the setup() function of your sketch.
  • Include the Lhings.loop() function the the loop() function of your sketch.
  • To receive actions and send events, you have to use the Lhings.actionAvailable and Lhings.eventWrite functions.

You tasted it and still want more? Keep on reading our next tutorial!!

Back to top