Event Payload

As said in the Getting Started, an event is a message sent by a device or app to notify Lhings that something has happened. It is different from status in that status components are properties of the device itself, and an event could notify about anything: a door has opened, an actuator has moved, a process has finished, whatever.

However, in many cases, knowing that the event has happened is not enough, you need more information about the event. Following with the examples above, you may want to know who opened the door, which actuator has moved and the result of the process. This is where payload comes into play. The payload of an event is some additional information the device attaches to the event to precise and complement its meaning.

The payload of events is made available to the outside world in two ways:

  • Through event notifications: the app Lhings Mobile allows you to subscribe to events, so that you are notified in your phone when an event is reported by some device. You will be able to see all the information contained in the payload of the event in Lhings Mobile.
  • Through rules: when two devices are linked through a rule, the payload of the event of the source device is sent by Lhings to the target device, which can check that information and use it conveniently.

Raw and structured payloads

From a technical point of view, the payload is a string that can contain anything you want. Attending to its shape we can talk about two different kinds of payload:

  • Raw payload: it is a simple string whose content has no structure, at least not a structure recognizable by Lhings. You can use it to convey any information: a temperature value, a name, even a CSV list of values, whatever you want. In Lhings Mobile the string will be shown as is. The main drawback with raw payloads is that the content of the string must be understood by the receiving device when it is sent to it using a rule, i. e., the target device of the rule must understand "the language" of the source device.
  • Structured payload: it is also a string, but its content is a JSON array of name - value pairs, which we call components of the payload and can be understood by Lhings. The advantages of it is that in Lhings Mobile you will see the information contained in the payload in a much more contextualized shape, you can also attach images and geolocations to an event!! And with rules it is even more powerful. Since the content of the payload is understood by Lhings, it can map the payload to whatever inputs has the action of the target device. Thus, even if the source and the target device were able to "talk" to each other, you can connect them using Lhings and structured payloads.

How to use structured payloads

First, let's see how a structured payload looks like. Following with the car example of the descriptor reference page, we will use its event "fuel_low" to explain how it works. Suppose this event has information attached related to:

  • Remaining distance with current fuel.
  • Current GPS position of the car.
  • Distance in kilometers to the nearest fuel station.
  • Whether the car will reach the nearest station or not.

How the car obtains this information is irrelevant in this example. Suppose we label each of these items with the tags remaining_distance, gps_position, distance_for_refuelling and will_make_it. Then the structured payload will be:

[
    {"name": "remaining_distance", "value": 20.8},
    {"name": "gps_position", "value": {"latitude": 41.235645, "longitude": 2.4525858,"altitude": 545.34} },
    {"name": "distance_for_refuelling", "value": 54},
    {"name": "will_make_it", "value": false}
]

Lhings Mobile will show this information in a nice table, showing also the map with the position of the car. Images can be attached to structured payloads too.

Each of these four data items in the payload are called payload components. Your device should declare in its descriptor which components are used for each event, in the way shown in the descriptor reference.

Besides being a tool useful for visualization, payload components are also very powerful to connect devices using rules. Let's suppose you have a "fuel on the go" service that sends you the fuel you need to reach the next station with a drone. This drone is also connected to Lhings and has an action called "refuel" which takes two arguments, the position of your car, the amount of fuel needed (e. g., in liters), and how much the owner of the car has to pay for it. This action would be represented in the device descriptor as:

{
...
"actionList": [
{
    "name": "refuel",
    "description": "makes the drone take the fuel to a car",
    "inputs": [
        {
            "name": "position",
            "type": "geolocation"
        },
        {
            "name": "amount_of_fuel",
            "type": "integer"
        },
        {
            "name": "price",
            "type": "float"
        }
    ]
}
]
...
}

However, the event "fuel_low" event of the car does not contain any information directly usable to fill the inputs of the action of the drone. How we connect both devices (the car and the drone) with a rule? It is very easy with Lhings. When creating the rule you can set the values of the arguments of the action to Javascript expressions in which the payload components are the variables. For example, given that the car consumes 10 liters each 100 km, the amount_of_fuel argument of the action should be set to (distance_for_refuelling - remaining_distance) * 10 / 100. In order to have Lhings recognize this formula, you must put the component names in the formula between double braces ({{ }}), so you will set the value of the amount argument to:

({{distance_for_refuelling}} - {{remaining_distance}}) * 0.1

This example is fully developed using the REST API in the documentation for the Rule.create web service.

Rules, components and connectors

So, on one side we have actions, which may have arguments that define the details about how they must be performed. On the other side we have events, which may have a structured payload that defines some components, which are data items that complement the information of the event. And finally we have rules, which are something that links events and actions, to trigger the execution of an action of a device when some other device notifies about certain event. That Javascript expression with the component names in double braces is called connector in Lhings jargon, because is really what allows to connect the devices to each other, as represented graphically in the figure below.

Diagram: how connectors work

As you can see, not all the payload components need to be linked to action arguments using a connector. In the diagram above the component will_make_it is left out. However, all the arguments of the action must receive a value. Because of that, you can also define custom values for some of them, like for price, in the example above.

Remember, the arguments of the actions are typed parameters. So, in order for a connector to be valid its Javascript expression must evaluate to a result of the correct type. In the example above the argument "amount" is an integer, and the connector also evaluates to a integer, so the connector is valid. The following connector is not valid for the amount_of_fuel argument:

{{remaining_distance}} < 30

but it would have been valid if the argument had been of type boolean.

As you can see payload components, used together with connectors, are a very powerful tool to connect your devices together and build interesting logic.

See the Rule.create service reference for implementations details, and also the descriptor reference to know how to define payload components for the events of your devices.

Back to top