Getting started tutorial with Openpicus

This tutorial explains how to connect the Flyport Wifi module from Openpicus 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 [op002a].

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 the Flyport Wifi module. 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 Flyport Wifi and its Nest board for programming.
  • One USB cable for programming.
  • A home router connected to the internet.
  • The Openpicus IDE installed on your computer. Download it from here.
  • The Openpicus 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_Openpicus_library. In the Openpicus IDE add the library Lhings.c and Lhings.h files downloaded form here.
    • Open the example file - taskFlyport.c. Replace the file with this same name in your IDE and configure your wifi settings by using the Setup Wizard.
  2. Set your Lhings credentials on your device (do not have credentials? Check our FAQ).
    • Once you have opened the example taskFlyport.c, you must edit your Lhings credentials. This will relate your Flyport 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 program 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.

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[] =  {                               
                                      {"switch", ACT_BUTTON},      	
                                      {"reset",  ACT_BUTTON},
                                      {NULL, 0}
                                    };		
Event_List   *Lhings_EventList[] =  {"motion", 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 Flyport 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 example:

{
    "version": "1",
    "deviceType": "flyport",
    "friendlyName": "flyport",
    "manufacturer": "openpicus",
    "modelName": "Flyport Wifi",
    "actionList": [
        {
            "name": "switch",
            "description": "action",
            "inputs": []
        },
        {
            "name": "reset",
            "description": "action",
            "inputs": []
        }
    ],
    "eventList": [
        {
            "name": "motion"
        }
    ],
    "stateVariableList": [
        {
            "name": "Led status",
            "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 the library

Now your program is properly configured to use Lhings. But you still have to include three lines of code more in order to make it work.

First, in the FlyportTask() function, you need to initialize the Lhings engine: 

if(!LhingsBegin(LHINGS_DEVNAME, LHINGS_DEVUUID, LHINGS_USERNAME, LHINGS_APIKEY))
    	UARTWrite(1,"ERROR: Lhings access vars. out of range\r\n");
Finally, in your FlyportTask() function loop, you need to call the Lhings main loop, which is who actually does the hard work for you: 
LhingsLoop();
Now you have configured your program to use Lhings. The rest of the programming is up to you!! You can program your Flyport like you would normally do.

What else?

Now you can download your firmware to your Flyport 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 web interface, and you will see your Flyport in the section devices. Click on it and select an action. In this example, one Led of the Grove board can be switched on/off by clicking the action "switch".

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(LhingsActionAvailable("switch")){
	UARTWrite(1,"Action received: switch\r\n");
	
	if(LedStatus){
		set(led, OFF);
		LedStatus = FALSE;
		// Set ** LHINGS STATUS vars. **
		// Set the Value of the Status vars. defined above in Lhings_StatusList[]
		LhingsStatusWrite("Led status", "off");
	}
	else{
		set(led, ON);
		LedStatus = TRUE;
		// Set ** LHINGS STATUS vars. **
		// Set the Value of the Status vars. defined above in Lhings_StatusList[]
		LhingsStatusWrite("Led status", "on");
	}
}

The function LhingsActionAvailable(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 LhingsEventWrite(char *name) or LhingsEventWrite_withPayload(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[]:

LhingsEventWrite_withPayload("motion", mEventMsg, strlen(mEventMsg), 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 program you have to configure some #define directives with information regarding your account and your device.
  • Include the LhingsBegin function in the FlyportTask() function of your program.
  • Include the LhingsLoop() function the the FlyportTask() function loop of your program.
  • To receive actions and send events, you have to use the LhingsActionAvailable and LhingsEventWrite functions.

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

Back to top