MQTT Plugin

Introduction

The Hobson MQTT plugin allows external devices (such as sensors) to connect to Hobson via MQTT for sending and/or receiving of data.

When the plugin is installed, Hobson creates a local MQTT server that devices can connect to anonymously. The anonymous connection is used by a device to obtain a device passport from Hobson. This passport allows the device to re-connect securely to Hobson's MQTT server and participate as a normal device within the Hobson system.

Device Bootstrapping

The process a device uses to obtain device passport information from Hobson is referred to as bootstrapping.

When a device with no bootstrap information is powered on, it should immediately begin the bootstrapping process.

The bootstrapping process should ideally only performed once. However, there may be circumstances where a device has to go through the process again (for example, if the device is factory reset).

Below is an outline of the steps involved in the bootstrapping process:

1. The user must create a new MQTT device in Hobson through the web console or REST API. This will generate a secret for the device and it will show up in Hobson's list of devices.
2. The user powers on the device.
3. It is up to the device to determine how it identifies Hobson's MQTT server. One suggestion is to dynamically discover it using an SSDP search (see below).
4. When the device identifies Hobson's MQTT server, it must anonymously connect to the MQTT server and begin listening to the appropriate bootstrap response topic (see below).
5. If the previous step is successful, the device must post a bootstrap request message to the bootstrap topic (see below).
6. If Hobson allows the registration, the device will receive a bootstrap response message on the bootstrap response topic containing the passport information. Otherwise, an error message is sent to the bootstrap response topic.
7. The device should store the contents of the bootstrap response message for future use (e.g. if the device is power cycled).

The below diagram visually illustrates a successful bootstrapping sequence:

SSDP Search

Description forthcoming.

Bootstrap Request Topic

Hobson is always listening on the bootstrap request topic for bootstrap request messages. The topic is of the form:
 

bootstrap
 

When a bootstrap request message is received, Hobson will confirm the validity of the request and issue a bootstrap response message (see the Messages section below).

Bootstrap Response Topic

Hobson will publish its bootstrap response message to the bootstrap response topic. The topic is of the form:

bootstrap/{deviceId}/{nonce}

where deviceId and nonce are values taken from the bootstrap request message (see the Messages section below).

Note: The only topics that the anonymous MQTT user can subscribe to are bootstrap topics.

Bootstrap Failure

There are a few reasons why a device's bootstrapping attempt might fail:

• It is unable to find Hobson's MQTT server. In this case, it should periodically search for one (e.g. via SSDP). This should not be done too frequently to avoid flooding the network.
• It is unable to anonymously connect to Hobson's MQTT server (should only occur if there is a problem with Hobson). In this case, it should periodically attempt to connect. This should not be done too frequently to avoid inundating Hobson with MQTT connection attempts.
• It receives a bootstrap response message with an error or no bootstrap response message after a waiting for the timeout interval. In this case, it should disconnect from the MQTT server and periodically attempt the process again. This should not be done too frequently to avoid inundating Hobson with MQTT traffic.

Bootstrap Success

A successfully bootstrapped device will have stored the bootstrap data included in the bootstrap response message. That data is comprised of:

1. The device's unique MQTT server credentials.
2. The data topic to use for sending data.
3. The command topic to use for receiving commands.

When a successfully bootstrapped device is initialized, it should automatically connect to its identified Hobson MQTT server using its unique credentials. Once connected, it can listen for command messages or send data messages using the appropriate topics.

Revoking Devices

There may be cases where a Hobson user revokes a device that was previously bootstrapped using the web console or REST API. This may happen, for example, if the device was somehow compromised.

When a device is revoked, its unique MQTT credentials become invalid and any attempt to connect to the MQTT server using them will fail. A device should detect this situation and automatically revert itself to an un-bootstrapped state and begin the bootstrap process again.

Security

Hub Secure Mode

When the Hobson Hub is running in secure mode, all MQTT traffic uses SSL/TLS channel encryption and the adding of the device ID to Hobson prior to device bootstrapping is required.

Hub Insecure Mode

When the Hobson Hub is running in insecure mode (e.g. on a secure network or for testing purposes), MQTT traffic uses no channel encryption and Hobson will always successfully respond to a bootstrap request message.

Messages

Bootstrap Request Message

JSON example (a device that reports temperature and humidity data):

{
  "deviceId": "abc123",
  "nonce": "fd54Ab",
  "name": "Sensor 1",
  "data": {
    "inTempF": "72.5",
    "inRh": "30.1"
  }
}

Bootstrap Response Message

JSON example:

{
  "id": "abc123",
  "secret": "3b2184be2f2c11e5a151feff999cdc9e",
  "topics": {
    "data": "devices/3b2184be-2f2c-11e5-a151-feff819cdc9f/data",
    "control": "devices/3b2184be-2f2c-11e5-a151-feff819cdc9f/control"
  }

}

Data Message

JSON example (temperature and humidity data):

{
  "inTempF": "72.5",
  "inRh": "30.1"
}

Command Message

Description forthcoming.