Open Edge Device Kit¶

Introduction¶

The Open Edge Device Kit aims at third-party device producers who want make their devices compatible with Insights Hub. It is a stand-alone module that can be installed on the device and acts as an interface to Insights Hub. The Open Edge Device Kit fulfills common requirements:

• Perform authentication at Insights Hub
• Perform security related actions
• Periodically check for relevant information on Insights Hub
• Cache data

The Open Edge Device Kit calls Insights Hub endpoints to send status updates and time series data into the cloud and to collect new information for the device. It handles the communication on the device using MQTT messages. Modules running on the device don't have to access Insights Hub directly. They only have to publish and subscribe to specific topics and communicate with the Open Edge Device Kit. This makes the Open Edge Device Kit an easy solution for getting existing devices ready for connecting to Insights Hub.

Get the Open Edge Device Kit¶

You can download the Open Edge Device Kit from the Siemens Industry Online Support (SIOS) Portal following these links [EN]/[DE]. The Open Edge Device Kit can be downloaded as an installation script or as a docker image. The docker image also contains Eclipse Mosquitto, which is used as MQTT broker.

Communication Protocol¶

Modules on the device have to use the MQTT protocol to communicate with the Open Edge Device Kit and act as MQTT clients. It is recommended to use the Mosquitto MQTT Broker, as other brokers have not been tested with the Open Edge Device Kit. The docker version of the Open Edge Device Kit already includes this broker.

Connection Parameters¶

The following parameters are required for establishing the MQTT connection:

Parameter	Value	Description
Address	localhost:1883	The address for MQTT clients to connect to the broker
QoS	refer to topic details	The Quality of Service (QoS) level of a message can be one of the following: 0: The broker/client delivers the message once without confirmation. 1: The broker/client delivers the message at least once, confirmation required. 2: The broker/client delivers the message exactly once by using a four-step-handshake.
Message Retention Policy	refer to topic details	If the retained flag of a message is set to TRUE, the broker stores the last message of a topic and the corresponding QoS. Each client that subscribes to this topic will receive the message immediately after subscribing.
Automatic Reconnect Policy	TRUE	MQTT clients must activate the automatic reconnect feature.
Clean Session	FALSE	The subscriptions of MQTT clients persist and any messages with QoS 1 or 2 are stored until the clients reconnect.
Connection Keep Alive Interval	180 sec	Defines the maximum time interval between messages. This enables MQTT clients to detect, if the server is no longer available without waiting for the TCP/IP timeout. The client sends a "ping" message which is acknowledged by the server.
sys_interval	10	The number of seconds between updates of the $SYS subscription hierarchy, which provides status information about the broker. Reloaded on reload signal.

Topics¶

Subscribed by the Open Edge Device Kit¶

The Open Edge Device Kit subscribes to the topics listed in this section. They allow modules to control the Open Edge Device Kit, to send status messages and to send time series data, which the Open Edge Device Kit uploads to Insights Hub.

Open Edge Device Kit Controls¶

Modules can use the following topics to control the Open Edge Device Kit:

• Initializing an agent
• Stopping an agent
• Setting an agent's log level

Status Messages¶

Modules can use the following topics to send their status to the Open Edge Device Kit:

• Configuration update status
• Offboarding success message
• Firmware version

Time Series Data Upload¶

Modules can use the following topics to send data to the Open Edge Device Kit:

• Time series upload
• Time series upload diagnostics

File Upload¶

Modules can use the following topics to send data (file) to the Open Edge Device Kit:

• File upload

Published by the Open Edge Device Kit¶

The Open Edge Device Kit publishes the topics listed in this section. The messages contain status information, configuration data and commands received from the Insights Hub backend. Modules only receive these messages, if they subscribe to the respective topics.

Open Edge Device Kit Status Messages¶

The Open Edge Device Kit publishes the following status messages.

• Connection Status
• Onboarding Status
• Buffer Status
• Data Sources Status
• Time difference to Insights Hub clock
• Agent initialization status
• Agent stopping status

Configuration Updates¶

The Open Edge Device Kit publishes configuration and firmware updates using the following topics:

• Device configuration update
• Application configuration update
• Data source configuration update
• All data sources configuration

Time Series Data Upload¶

• Stopping Data Upload

Limitations¶

Data Upload Limits¶

Insights Hub limits the maximum allowed data upload rate depending on the purchased Insights Hub plan. Since this limit is variable, the Open Edge Device Kit does not employ a checking mechanism for the upload rate. The user is responsible for staying within their limits.

The Open Edge Device Kit performs data upload operations periodically, uploading all data received within one period at the end of each cycle. If this causes the data ingestion limit to be exceeded, Insights Hub will drop data packages causing data loss. The upload period for the Open Edge Device Kit can be adjusted per data source in the data source configuration file.

Except where otherwise noted, content on this site is licensed under the Development License Agreement.