How Lhings Works

If you read the Getting started section, you may have noticed that when you add a device, Lhings knows a lot about it from the start. In fact, the control panel is customized to match the capabilities of the device. You can enable and disable features of your device, and the control panel will change accordingly. Furthermore, Lhings knows if your device is online or not, its status and much more. How can Lhings know all this? Which kind of interaction happens between your device and Lhings to make it possible? This section is devoted to explain how Lhings and your devices interact from a technical point of view, but without entering into the details of how the communication is performed.

The Api-Key

Each Lhings account is assigned an Api-Key. The Api-Key is a number similar to this example 5abe6e34-1569-4ad0-892f-b23ccec47da2 that is used for authentication when communicating with the devices. You can check the value of your Api-Key in the profile of your account in Lhings. Using this authentication mechanism prevents other from controlling your devices or having any kind of access to them. Keep it safe!

The lifecycle of a device in Lhings

The lifecycle of a device in Lhings is composed of four main states:

1. Not registered: the state of a brand new device, Lhings does know nothing about it.
2. Registered: the device has "introduced" itself to Lhings, and informed about its capabilities.
3. Online: the device has told Lhings he is willing to communicate with Lhings both for sending events to it and receiving actions.
4. Offline: the device has told Lhings he is no longer willing to communicate with Lhings, until further notice.

See the figure below for more details. The procedures that take the device from one state to another are the following:

• Registration, to go from not registered to registered.
• Start session, to go from registered to online, and from offline to online.
• End session, to go from online to offline.

The device will be able to send events and receive action only when it is online. Bear in mind that online and offline states do not have to do with the quality of the communication link (the device can be reached over the network or not), but represent the intent of the device to communicate with Lhings.

The control panel of a device will be enabled only when the device is online, so to be able to control remotely a device it must be online.

Registering a device in Lhings

Before being able to communicate, Lhings must know your device exists and that it is a trustworthy device. This is performed using a process called registration, during which the device sends some information to Lhings to "introduce itself", and Lhings assigns to it a unique identifier. Registration is a two step process:

• First, the device sends Lhings its device name. It can be whatever UTF-8 encoded string, as long as it is 50 characters long or less. Lhings will answer telling the device a identifier, which is unique to each device and we call it device UUID through this documentation. The device must store this UUID because it will be asked by Lhings in every communication to identify the device.
• Then, the device must send a descriptor, formatted in JSON, which describes the properties of the device and tells Lhings about its capabilities regarding actions, events, and status.

Once all this has been sent to Lhings, the device is ready to start session and communicate with Lhings.

Being online: events, actions, and status

The interactions between Lhings and your devices can be split into two categories, attending to which actor requests the communication:

• The device starts the communication: the only interactions in this category are the events, which are sent from the device to Lhings to notify that something happened. Devices can send events at any time, as long as they are online.
• Lhings starts the communication: both actions and status fall in this category.
  • Actions: the actions are always requested by Lhings to the device. The cause of this request can be a user action in the control panel or the execution of a rule.
  • Status: whenever Lhings needs to know the status of a device, it will send a request asking for it.

Events

An event is characterized only by its name. The name of the event is defined by the device itself when it sends its own descriptor to Lhings.

Events can convey some optional payload. The payload is additional information about the event. For instance, a thermometer can have and event called "temperature changed". Each time the event is sent it may carry a payload providing the new temperature value.

If the event is linked to an action through a rule the payload is sent to the device that will perform the action. Following the previous example, this can be useful if some devices has an action which needs to know the temperature of the thermometer.

Actions

Actions are characterized by its name, and also by an optional set of typed parameters (up to 8). These parameters are employed to configure the details of how the action must be performed. Although an action may or may not have parameters, it can always receive a payload. The payload will usually have been generated by an event, and will reach the action because of a rule that links both.

Status

The status is defined by a set of typed parameters (up to 8). It may be requested by Lhings at any moment, for instance, when the user clicks on Refresh status in the control panel.

The implications of being online

A device can send events and receive actions and status requests only when it is online. Thus, when a device starts session is also telling Lhings "I'm available to execute actions and telling you my status". However, due to the nature of the Internet, being able to receive action and status requests usually means mantaining a communication link open continuously between the device and Lhings. This is not always posible or desirable, specially for devices working on battery power. This kind of devices usually wake up at predefined intervals, perform some tasks, and go back to sleep. In order to work with Lhings, these devices must start session, perform their work (e. g. send events), and end session before they go back to sleep mode. They won't be able to respond to action requests, as they may come at any moment. Currently Lhings lacks a "delayed delivery" feature to communicate pending actions to those devices when they are back online.

These devices with sleep mode will not be able to answer status requests also, but they are able to tell Lhings their status using the data API.