Lemonbeat

  • 6 minute(s) read
Prev Next

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 microservice that allows Servitly to communicate with the AMQP server, the endpoint where IoT data is 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. 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 to manage 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 the 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 is 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 navigating 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 equal to the UUID.

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

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

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

  5. If the thing is missing:

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

    2. Retrieves the Thing Definition having the "deviceTypeId" property equal to the DeviceTypeId present in 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 in the event.

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

  10. The "SGTIN" thing property is updated by using the device SGTIN present in 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 using the thing property name as key (also replacing "-" with "_").

  16. In case of a new device, it updates the properties of things whose name is preceded by ā€œdevice_ā€.
    If the device was already present in the DPS, these properties are left unchanged.

METADATA_CHANGED

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

METADATA_DEVICE_REMOVED

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 equal 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 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 equal 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 an event 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 a 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, read the "type_id" attribute.

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

  5. If the property is missing, replace the "-" character with "_" and search 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, it computes a JSON message and publishes it 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 equal to the Gateway UUID.

  2. For each metadata device, retrieve the thing having the mapping Asset Id equal to the Device UUID.

  3. If the gateway has been found, the heartbeat timestamp is published 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.