# Extra settings

Before executing this agent, please note that the conventions described below has to be followed for a successful communication between the agent and the MQTT Broker.

# Topics structure

This agent works under the following assumptions:

The devices and agent are connected to the same MQTT broker
The devices publish data to the same topics to which the agent is subscribed
The published data (payloads) are formatted as JSON

Note that all data will be exchanged under the topics structure defined below.

# Registration

The following topic structure is used for registration purposes (i.e., for explicit device identification).

Topic structure: mytopic

For instance, if the following payload is published to the topic mytopic:

{
  "ID": "1234", 
  "title": "my device", 
  "description": "this is my device"
}

The agent will automatically register and create (in the IoTHub to which it is connected) a new device with identifier 1234, title my device, and description this is my device. Note that this new device will be created without properties. Moreover, keep in mind that not all devices need to pass over a registration process.

# Incoming data

The following topic is used for data exchange coming from the device.

Topic structure: mytopic/deviceid

For instance, if the following payload is published to the topic mytopic/1234:

{
  "active": true,
  "temperature": 100
}

If there is no device already registered whose identifier is 1234 (the last potion of the topic), then the agent will register and create (in the IoTHub to which it is connected) a new device with the identifier 1234, and the properties active and temperature (together with their respective values). In case there is already a device with this identifier, then the properties active and temperature will be updated, or created in case one of them (or both) do not exist.

# Outgoing data (write)

The following topic is used for publishing write attempts. This information is commonly sent from the IoTHub through this agent to the devices (i.e., devices do not publish to this topic).

Topic structure: mytopic/deviceid/write

For instance, if the following payload is published to the topic mytopic/1234/write:

{
  "temperature-format": "kelvin"
}

Then it is expected that the device which is subscribed to the mentioned topic reacts on the given data (e.g., it updates its temperature format to "kelvin").

# Outgoing data (configuration)

The following topic is used for configuration purposes (e.g., for defining a new sending interval, among other settings). The data exchanged in this topic is commonly sent from the IoTHub through this agent to the devices (i.e., the devices do not publish to this topic).

Topic structure: mytopic/deviceid/config

For instance, if the following payload is published to the topic mytopic/1234/config:

{
  "interval": 1000,
  "unit": "milliseconds"
}

Then it is expected that the device which is subscribed to the mentioned topic reacts on the given data (e.g., it updates its sending interval to 1000 milliseconds).

# Connection

The following topic is used for handling connection statuses.

Topic structure: mytopic/deviceid/connection

This information is coming from the device, and it can be easily implemented by using the Last Will and Testament (LWT) feature of MQTT for publishing a payload if the device was disconnected ungracefully (e.g., for cases such as if the power supply was removed and the device was suddenly switched off). In this case, a payload with byte 1 means that the device was connected, and a payload with byte 0 (or an empty payload) means that the device was disconnected.

TIP

In the examples above, you can replace mytopic, config, and write with different keywords by setting the arguments root-topic, config-topic, and write-topic (respectively) at the time of starting the agent.

← Device settings Executing this version →