Deploying The Solution

10min
﻿
﻿
This guide provides step-by-step instructions to set up and deploy the LE Sparkplug Edge Node solution on your Litmus Edge device. Before proceeding with the guide, make sure you have the following prerequisites:
Litmus Edge API Token. Please follow the Create an API Token instructions to obtain the API token. (Optional with Litmus Edge Manger v2.9.x and later)
MQTT Broker connection credentials. The solution supports MQTT Protocol versions 3.1.0 and 3.1.1.
There are two methods to deploy the solution.
Method 1: Upload the Image to Litmus Edge
Download the LE Sparkplug Edge Node image from the Central Portal website by clicking on the Download button and selecting the appropriate version (LE Sparkplug Edge Node vx.x.x).
﻿
Download the LE Sparkplug Edge Node Image
﻿
Log in to your Litmus Edge and navigate to Applications > Images.
Click the Upload Image (+) icon, select Upload, and then select the downloaded image (le-sparkplug-x-x-x.tar.gz), and click Import. It may take a while for the image to appear.
Use the docker run command to run the application, providing the required environment variables. For example:
Linux
docker run -itd --name le-sparkplug --network host \
-e EDGE_API_TOKEN="<API Token>" \
-e PRIMARY_HOST_SUPPORT=true \
-e PRIMARY_HOST_ID="<Host ID>" \
-e LE_STORE_AND_FORWARD=true \
-e GROUP_ID="<Group ID>" \
-e NODE_ID="<Node ID>" \
-e MQTT_SERVERS='[{\"url\":\"<Broker URL>\",\"user\":\"<Username>\",\"password\":\"<Password>\"}]' \
<imgName>:<tagName>
docker run -itd --name le-sparkplug --network host \
-e EDGE_API_TOKEN="<API Token>" \
-e PRIMARY_HOST_SUPPORT=true \
-e PRIMARY_HOST_ID="<Host ID>" \
-e LE_STORE_AND_FORWARD=true \
-e GROUP_ID="<Group ID>" \
-e NODE_ID="<Node ID>" \
-e MQTT_SERVERS='[{\"url\":\"<Broker URL>\",\"user\":\"<Username>\",\"password\":\"<Password>\"}]' \
<imgName>:<tagName>
﻿
Additionally, the following optional fields can be included in each MQTT Server Object to configure TLS settings for the server:
ca_cert: Base64-encoded string representing the CA certificate that should be used to verify the MQTT server's certificate.
client_cert: Base64-encoded string representing the client certificate that should be presented to the MQTT server during the TLS handshake.
client_key: Base64-encoded string representing the private key that should be used with the client certificate.
skip_cert_verify: Boolean indicating whether certificate verification should be skipped during TLS handshake. If this field is set to true, the MQTT client will not verify the server's certificate, and the connection will be vulnerable to man-in-the-middle attacks. This field should only be set to true for testing and debugging purposes.
If any of the optional fields are included in an MQTT Server Object, the MQTT client will use them to configure TLS settings for that server. If any of the fields are missing or invalid, the MQTT client will use default settings. Please follow the instructions in TLS Certs﻿ to encode the certifications in base64 strings.
For example:
Linux
docker run -itd --name le-sparkplug --network host \
-e EDGE_API_TOKEN="<API Token>" \
-e PRIMARY_HOST_SUPPORT=true \
-e PRIMARY_HOST_ID="<Host ID>" \
-e LE_STORE_AND_FORWARD=true \
-e GROUP_ID="<Group ID>" \
-e NODE_ID="<Node ID>" \
-e MQTT_SERVERS='"[{\"url\":\"<BrokerURL>\",\"user\":\"<Username>\",\"password\":\"<Password>\",\"ca_cert\":\"<CACert>\",\"client_cert\":\"<ClientCert>\",\"client_key\":\"<ClientKey>\",\"skip_cert_verify\":\"<SkipCertVerify>\"}]"' \
<imgName>:<tagName>
docker run -itd --name le-sparkplug --network host \
-e EDGE_API_TOKEN="<API Token>" \
-e PRIMARY_HOST_SUPPORT=true \
-e PRIMARY_HOST_ID="<Host ID>" \
-e LE_STORE_AND_FORWARD=true \
-e GROUP_ID="<Group ID>" \
-e NODE_ID="<Node ID>" \
-e MQTT_SERVERS='"[{\"url\":\"<BrokerURL>\",\"user\":\"<Username>\",\"password\":\"<Password>\",\"ca_cert\":\"<CACert>\",\"client_cert\":\"<ClientCert>\",\"client_key\":\"<ClientKey>\",\"skip_cert_verify\":\"<SkipCertVerify>\"}]"' \
<imgName>:<tagName>
﻿
﻿Store And Forward Mechanism is available in LE Sparkplug Edge Node v1.4.0 and later﻿
Please refer to the Environment Variables﻿ used by the application.
Alternatively, create a JSON configuration file with the provided flow (RECOMMENDED). 
Download the flow from the downloading page by clicking on LE Sparkplug Edge Node - Flow
﻿
Download the Flow
﻿
Here's an example of a JSON configuration file:
JSON
{
    "edge_api_token": "0iriyynzv5xjac1aupqxm4j2tzuls5pf",
    "mqtt": {
        "servers": [
            {                
                "url": "ssl://mqtt.example.com:8883",
                "user": "myuser",
                "password": "mypassword",
                "ca_cert": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FUtCk1JSUVkakNDQWRZQ0...",
                "client_cert": "LS0tLS1CRUdJTiBSU0EgUFVCTElDIEtFWS0tpRd0lC...",
                "client_key": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktUlCRXdF...",
                "skip_cert_verify": false
            },
            {
                "url": "tcp://mqtt.example.com:1883",
                "username": "admin",
                "password": "admin@"
            }
        ],
        "client_id": "",
        "client_id_suffix": "le-spb",
        "connect_timeout": "30s",
        "write_timeout": "3s",
        "keepalive": 30
    },
    "group_id": "LE-Group",
    "node_id": "LE-Node",
    "primary_host_support": true,
    "le_store_and_forward": false,
    "primary_host_id": "LE-97IS6VF",
    "le_logging_level": "info"
}
{
    "edge_api_token": "0iriyynzv5xjac1aupqxm4j2tzuls5pf",
    "mqtt": {
        "servers": [
            {                
                "url": "ssl://mqtt.example.com:8883",
                "user": "myuser",
                "password": "mypassword",
                "ca_cert": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FUtCk1JSUVkakNDQWRZQ0...",
                "client_cert": "LS0tLS1CRUdJTiBSU0EgUFVCTElDIEtFWS0tpRd0lC...",
                "client_key": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktUlCRXdF...",
                "skip_cert_verify": false
            },
            {
                "url": "tcp://mqtt.example.com:1883",
                "username": "admin",
                "password": "admin@"
            }
        ],
        "client_id": "",
        "client_id_suffix": "le-spb",
        "connect_timeout": "30s",
        "write_timeout": "3s",
        "keepalive": 30
    },
    "group_id": "LE-Group",
    "node_id": "LE-Node",
    "primary_host_support": true,
    "le_store_and_forward": false,
    "primary_host_id": "LE-97IS6VF",
    "le_logging_level": "info"
}
﻿
Use the docker run command to run the application, mounting the configuration file's directory. For example:
Linux
docker run -d --network host -v /var/lib/customer/sparkplug/:/le-sparkplug/data/ <imgName>:<tagName>
docker run -d --network host -v /var/lib/customer/sparkplug/:/le-sparkplug/data/ <imgName>:<tagName>
﻿
Method 2: Using the Marketplace (Litmus Edge Manager)
Download the catalog JSON file by clicking on Litmus Edge Manager - App from  the downloading page:
Download the catalog JSON file
﻿
Import the LE Sparkplug Edge Node application to your catalog by using the catalog JSON file. Refer to the instructions on Marketplace: Catalogs and Applications for more details.
Download the Litmus Solutions Registry from the downloading page:
Download The Registry
﻿
Please follow the instructions on Registry Management to import the Litmus Solutions Registry 
Deploy the application to your Litmus Edge device by following the instructions in Deploy an Application to Edge Devices or by using the Marketplace in Litmus Edge, as explained in Deploy a Marketplace Application.
Note: Before deploying the application, make sure to Provision a connection between the edge device and Litmus Edge Manager.
﻿
That's it! Your LE Sparkplug Edge Node application should now be running on your Litmus Edge device. 🎉
﻿
Updated 23 Apr 2024
LE Sparkplug Edge Node
Environment Variables