Skip to main content

Magenta IoT Hub

The Magenta IoT Hub is an IoT Platform to manage Edge devices and process data streams. The hopit Edge Magenta Target features Data streaming, Namespace discovery, Device Twin synchronization and remote Tasks execution. The communication protocol used to communicate with the IoT Hub is MQTT.

For further information visit the IoT Hub documentation.

Configuration​

Magenta IoT Hub​

A virtual device must be created on the IoT Hub and the transport type of the device profile must be MQTT.

The credentials for hopit Edge can be:

  • Access Token: Access Token from the IoT Device is used as Username in Target settings.
  • MQTT Basic Authentication: ClientID, Username and Password are set in the IoT Hub and the same are used in Target settings.

hopit Edge​

The Magenta Target has the following parameters:

  • Client ID: MQTT client ID, if not set generated automatically.
  • Username: The desired user name.
  • Password: The login password.
  • QoS: Quality of Service, select from:
    • AtMostOnce
    • AtLeastOnce
    • ExactlyOnce
  • ProtocolVersion: MQTT protocol version, select from:
    • V310
    • V311
    • V500
  • TargetType: The type is always Magenta for this Target.

For the common parameters, see the Introduction.

Corresponding Edge configuration and Device Twin definition to activate the Magenta Target service:
https://localhost:5050/Targets
Magenta Target Settings

Data Streaming​

MQTT messages will be sent to the /telemetry topic. All signals will be added to a flat JSON format.

A sample message could be

{
  "signal-1": "value-1",
  "signal-2": "value-2"
}

Signals can be also read with Regex matcher. See the Router documentation for details.

Signal discovery is available for this Target. See the Introduction for more details.

For information how signals are named and labeled in Data Lakes, please read the Data Lake documentation.

Device Twin​

Device Twin updates are synchronized using the topic v1/devices/me/attributes if the Target is enabled in the Device Twin settings.

Report​

If the Device Twin is changed on the Edge, all settings are published as JSON message to the Client Attribute DeviceTwinReported. Client Attributes are always read-only for the IoT Hub.

{ 
    "DeviceTwinReported":{ 
        "AdsRouter": { 
          "Enabled":false 
        }, 
        "LogCollector": { 
          "Enabled":true 
        },
        ...
    }
}

Desire​

To update the Device Twin from the IoT Hub on the Edge device, publish the settings to the Shared Attribute DeviceTwinDesired. Shared Attributes can be updated by Dashboard Widgets or in the device settings.

{ 
    "DeviceTwinDesired":{ 
        "AdsRouter": { 
          "Enabled":true 
        }
    }
}

In the IoT Hub it will look like this:

RPC Widgets

info

Shared attributes have to be created by the user, while client attributes are registered automatically, when received.

Target or Route deletion​

To delete a Target or a Route via the Device Twin, it have to be set to null.

The Device Twin documentation shows more details about the operation.

Tasks​

To remotely execute Tasks on the Edge device, the Magenta RPC (Remote Procedure Call) feature is used. To trigger a Task execution, publish a JSON message with the parameters method (the Task name) and params (the Task arguments). For example:

{"method":"Reboot","params":{}}

If a two way RPC call was executed, the Edge device will send back a response.

The JSON string can be generated by Dashboard Widgets at the IoT Hub:

RPC Widgets

Please read the Tasks for more information about Tasks.

Start Discovery Task​

The StartDiscovery Task can only be executed from a remote target. See the Tasks documentation for details.

The namespace is sent back as Attribute DiscoveredSignals-[Target Name] with the JSON format:

{
    "signal-1": "value-1",
    "signal-2": "value-2",
    ...
}