Lemonbeat

  • 6 minute(s) read

Create services for smart buildings using the Lemonbeat smart meters and sensors.

The Lemonbeat Connector can be used to exchange data from devices connected through the Lemonbeat IoT Platform.

System Architecture

The Lemonbeat Connector is based on a specific micro-service letting Servitly to communicate with the AMQP server, the endpoint where IoT data are initially collected.

Periodically (every 5 minutes) through the API, the connector retrieves from each customer the AMQP connection information.

In this way, the connector verifies the presence of new connections to be established with an AMQP server or invalid ones to be evicted.

This means that when a new customer is created within Servitly or a Lemonbeat Connector configuration is updated (e.g. expired certificate), IoT data may take at most 5 minutes to be read and displayed within the dashboards.

Data Listening

The flow of data from the remote device to Servitly follows the following steps:

  1. A device data is published to the AMQP server.

  2. An LsDl message is notified to the Lemonbeat Connector.

  3. The LsDl message is parsed and converted to the Servitly standard JSON format, using the field names as metric names.

  4. The transformed message is forwarded to Servitly by using the standard MQTT channel and the device UUID and topic part

Data Publishing

The flow of data from Servitly to the remote device follows the following steps:

  1. A user changes a configuration parameter or executes a command from the dashboard.

  2. A message is published on the MQTT channel and made available to the Lemonbeat Connector.

  3. An LsBl message is created encapsulating the data.

  4. The LsBl message is sent to the Lemonbeat backend through the REST API and finally dispatched to the remote device.

Plugin Configuration

To enable this plugin, you need to:

  1. Go to the Integrations / Plugins page.

  2. Select the IoT Connectors category.

  3. Locate the Lemonbeat card.

  4. Click on the card switch to activate the plugin.

  5. Configure the plugin properties and save.

Here is the list of all the properties that can be used in the plugin configuration.

PROPERTIES

Base API URL

The Lemonbeat backend URL used for managing automations.
Type: STRING | Optional

Username

The username used for Lemonbeat backend authentication.
Type: STRING | Optional

Password

The password used for Lemonbeat backend authentication.
Type: PASSWORD | Optional

Connector Configuration

Once plugin has been enabled, it is possible to configure the Lemonbeat Connector.
This operation can be done directly from the Console to configure the global IoT Connector, or directly in the DPS in order to configure the connector mapping for a specific customer.
Customers without an explicit connector mapped, will use the global one.

Within the configuration page, you have to insert some information that are provided by the Lemonbeat team, for instance:

  • broker endpoints and credentials for listening to device IoT data.

  • backend credentials for performing REST API requests.

  • certificates for client authentication and secure channel establishment.

The private client certificate can be provided by following the reported procedure.

  1. Click the Generate new certificate button.


  2. Download the CSR in order to obtain a certificate file to upload.


  3. When the private certificate file has been uploaded, in a few minutes you will see the connector status updated.

In case you need to configure a Lemonbeat Connector for a specific customer, by entering the DPS, and navigate the Customer ā†’ Edit ā†’ Connection, you will find the same panel present in the Console.
By pressing the Override button, you can redefine the connection mapping as you need.

Meta Data Events

The connector subscribes to events published under the topic EVENT.APP.METADATASERVICE.

According to the received event type the connector updates the things and gateways.

METADATA_DEVICE_INCLUDED

When an event is received, the connector performs the following steps:

  1. Reads the message UUID and retrieves all the things having the mapping Asset Id equals to the UUID.

  2. Reads all the attribute inside the metadata report message node.

  3. Reads the value description report and group properties by prefix (name part before "_").

  4. Filter the found things having the mapping path equals to the prefix (if preset).

  5. If the thing is missing:

    1. Retrieves the Location by using the LocationId present into the attributes.

    2. Retrieves the Thing Definition having the "deviceTypeId" property equals to the DeviceTypeId present into the attributes.

    3. A new thing is created under the location.

  6. The thing is activated

  7. The Serial Number is updated by using the "SerialNumber" attribute.

  8. The "GTW_SGTIN" thing property is updated by using the gateway SGTIN present into the event.

  9. The "UUID" thing property is updated by using the UUID present into the event.

  10. The "SGTIN" thing property is updated by using the device SGTIN present into the event.

  11. The "deviceUsageId" thing property is updated by using the metadata report "DeviceUsageId" value.

  12. The "PATH" thing property is updated by using the metadata indexed prefix path (if present).

  13. The "MeterSerialNumber" thing property is updated by using the metadata report "MeterSerialNumber" value.

  14. The "MeterDeviceUsage" thing property is updated by using the metadata report "MeterDeviceUsage" value.

  15. Update any other property with group "Connector" with the relative metadata report value, by suing the thing property name as key (also replacing "-" with "_").

  16. Updates thing properties whose name is prefixed by "device_".

METADATA_CHANGED

When an event is received, the connector performs the sames steps as per METADATA_DEVICE_INCLUDED events without the thing provisioning steps.

METADATA_DEVICE_REMOVED

When anevent is received, the connector performs the following steps:

  1. Reads the message UUID and retrieves all the things having the mapping Asset Id equals to the UUID.

  2. Deletes all the found things.

  3. Optionally uses the metadata report "LocationId" attribute to search for things to delete.

METADATA_DEVICE_EXCLUDED

When anevent is received, the connector performs the following steps:

  1. Reads the message UUID and retrieves all the things having the mapping Asset Id equals to the UUID.

  2. Deactivates all the found things.

  3. Optionally uses the metadata report "LocationId" attribute to search for things to deactivate.

METADATA_GATEWAY_INCLUDED

When anevent is received, the connector performs the same steps for the METADATA_DEVICE_INCLUDED, but limited to the gateway device type creation. You must have a thing definition having the same "DeviceTypeId" property value, or "Gateway" as fallback "DeviceTypeId" value.

METADATA_GATEWAY_REMOVED

When an event is received, the connector performs no steps, so the event at the moment is discarded.

Device Description Reported Events

The connector subscribes to events published to this topic EVENT.APP.TOPOSERVICE.DEVICE_DESCRIPTION_REPORTED.

You can define properties of things with the prefix "device_" in the name; the connector updates these properties based on the contents of the DEVICE_DESCRIPTION_REPORTED event.

Note that, to identify the thing to be updated, it is mandatory to define the thing property named "SGTIN". This property is automatically updated by the connector during METADATA events processing (e.g. METADATA_DEVICE_INCLUDED, METADATA_CHANGED).

When an event is received, the connector performs the following steps:

  1. Retrieves the Thing by SGTIN.

  2. Extracts all the "device_description_report" child nodes having the "name" attribute equal to "info".

  3. For each element, reads the "type_id" attribute.

  4. Searches for a property whose name is equal to "device_<@type_id>".

  5. If the property is missing replaces the "-" character with "_" and searches again.

  6. Retrieves the value by reading one of these attributes: "number", "string", "hex".

  7. Converts the value according to the property type (e.g. boolean 1 -> true).

  8. Updates the property.

Status Reported Events

The connector subscribes to events published to this topic EVENT.APP.STATUSSERVICE.STATUS_REPORTED.

When an event is received, the connector performs the following steps:

  1. Retrieves the thing by using the SGTIN property which must be equal to the device SGTIN included in the message.

  2. For each status report item, computes a JSON message and publish under the "LBStatusReport" thing metric.

TOPIC: <USERNAME>/<ASSET_ID>/ms
PAYLOAD:
{
 "ts" : 1719478178000,
 "data": {
    "LBStatusReport" : "<StatusReportItem as JSON>"
 }
}

Heartbeat Events

The connector subscribes to events published to this topic EVENT.APP.METADATASERVICE.METADATA_HEARTBEAT_REPORTED.

When an event is received, the connector performs the following steps:

  1. Reads the message UUID and retrieves the gateway thing having the mapping Asset Id equals to the Gateway UUID.

  2. For each metadata device retrieves the thing having the mapping Asset Id equals to the Device UUID.

  3. If the gateway has been found, the heartbeat timestamp is publised under the "heartbeat" metric.

    TOPIC: <USERNAME>/<ASSET_ID>/ms

PAYLOAD:
{
 "ts" : 1719478178000,
 "data": {
 "heartbeat" : 1719478178000
 }
}

  4. For each identified thing, the location property "gatewayHeartbeat" is updated with the heartbeat timestamp.