Skip to content

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.

Open Edge Device Kit Architecture

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:

Status Messages

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

Time Series Data Upload

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

File Upload

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

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.

Configuration Updates

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

Time Series 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.


Last update: February 23, 2024

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