Getting started tutorial with Arduino

This tutorial explains how to connect an Arduino board equipped with an internet shield to Lhings and how to create interesting applications with it. Before trying, make sure you have created a user account in Lhings (http://lhings.com).

This tutorial applies to release [ar002a].

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

In this tutorial we are going to get a taste of the basic usage of Lhings by connecting an Arduino board equipped with any internet shield compatible with the Ethernet Shield library. Then, you will be able to control it remotely and create new rules from your dashboard. You will see how easy it is to connect your device to Lhings, set its actions and events, and start programming your own Internet of Things applications.

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

  • One Arduino board.
  • One Arduino Ethernet Shield (or any other internet shield with compatible libraries).
  • One USB cable.
  • One Ethernet cable.
  • A home router connected to the internet with at least one Ethernet port available.
  • The Arduino IDE installed on your computer. Download it from here.
  • The Arduino 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_Arduino_library. In the Arduino IDE go to Sketch → Import library → Add library, and navigate to the folder where you unzipped and saved the file Lhings_library.zip.
    • Open the example sketch. In the Arduino IDE go to File → Open, and navigate to the folder where you saved the file Lhings_Dhalsim_Ethernet_Shield.ino. 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 Lhings credentials on your device (do not have credentials? Check our FAQ).
    • Once you have opened the example sketch, you must edit your Lhings credentials. This will relate your Arduino with your Lhings account. Therefore, you need to introduce first 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 context menu, click on “Technical data”. 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 configuration, using two directives: 
      #define LHINGS_DEVNAME "your_device_name_here"
#define LHINGS_DEVUUID NULL
      The device NAME can be whatever you want as long as all devices in your account have different names. If the LHINGS_DEV_UUID is NULL, then Lhings will automatically assign the device uuid for you. This is the recommended setting.
  3. Set your network settings in your device. Now, you have to configure your network parameters in the Arduino, so it gets access to your router and to the internet. The Arduino Ethernet Shield needs a MAC address; you can assign any. Use the default value if in doubt. Then, you have to provide also a local IP address valid for your network. Commonly, an IP address of the kind 192.168.0.15x or 172.16.1.15x will work, where x is any number from 0 to 9. If you are not sure about the IP address, this is a good try. However, if this does not work, you have to find out which kind of IP addresses your router provides and set yours according to that range by changing the last digits. This can be achieved in several forms; one is obtaining the IP address of your PC by following this guide. In the code, you have to edit the following byte arrays to configure the MAC and IP addresses: 
    byte mac[] = {0xA0, 0xA4, 0xDA, 0x01, 0x17, 0x88}; 
byte ip[] = {192,168,0,150};

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. You can learn more about the device descriptor here.

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[] =  {                               
                                      {"switch", ACT_BUTTON},      	
                                      {"reset",  ACT_BUTTON},
                                      {NULL, 0}
                                    };		
Event_List   *Lhings_EventList[] =  {"pressed", NULL};				
Status_List  *Lhings_StatusList[] = {"Led status", 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 Arduino library the amount of status variables is limited to 4. 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: 

{
    "deviceType": "arduino",
    "friendlyName": "arduino",
    "manufacturer": "arduino",
    "modelName": "Arduino UNO",
    "actionList": [
        {
            "name": "switch",
            "description": "action",
            "inputs": []
        },
        {
            "name": "reset",
            "description": "action",
            "inputs": []
        }
    ],
    "eventList": [
        {
            "name": "pressed"
        }
    ],
    "stateVariableList": [
        {
            "name": "Led status",
            "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 the library

Now your sketch is properly configured to use Lhings. But you still have to include three lines of code more in order to make it work. First, you need to initialize networking with the ethernet shield. Include the next line in the setup() function: 

Ethernet.begin(mac, ip);
Also in the setup() function, you need to initialize the Lhings engine: 
if(!Lhings.begin(LHINGS_DEVNAME, LHINGS_DEVUUID, LHINGS_USERNAME, LHINGS_APIKEY))
    Serial.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 Arduino like you would normally do.

What else?

Now you can upload your sketch to your Arduino and see how it works. Open your serial monitor, and you will see how it talks to the Lhings server. Also, you can enter in your Lhings web interface, and you will see your Arduino in the section devices. Click on it and select an action. In this example, one Led connected to digital pin 9 can be switched on/off by clicking the action "switch" from anywhere.

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 program, the reception of the action with name “switch” is checked. If this action is received, switch on/off the led:

if(Lhings.actionAvailable("switch")) {
  Serial.println("Action received:");
 
  if(ledFlag == false){
    digitalWrite(ledPin, HIGH);
    Lhings.statusWrite("Led status", "on");
    ledFlag = true;
  }
  else{
    digitalWrite(ledPin, LOW);
    Lhings.statusWrite("Led status", "off");
    ledFlag = false;
  }
}

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 Lhings.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 in the Lhings_EventList[]:

if(digitalRead(button)==1) {
  Lhings.eventWrite("pressed", &l_event[0], strlen((const char*)l_event), EVT_PAYLOAD);
}

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