Introduction
The Hobson MQTT plugin (when installed) allows external devices (such as sensors) to connect to Hobson via MQTT for sending and/or receiving of data.
Device Bootstrapping
The process of setting up a brand new MQTT-enabled device with Hobson is referred to as bootstrapping.
...
Gliffy | ||||
---|---|---|---|---|
|
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:
...
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:
...
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
Attribute | Value | Optional | Description |
---|---|---|---|
deviceId | String | No | The device's unique ID |
nonce | String | No | A device-generated nonce that will be used as part of the bootstrap response topic (as with any nonce, it should not be re-used) |
name | String | Yes | The device's name |
data | Object | Yes | The initial values for all the device's variables |
...
{
"deviceId": "abc123",
"nonce": "fd54Ab",
"name": "Sensor 1",
"data": { "inTempF": "72.5",
"inRh": "30.1" }
}
Bootstrap Response Message
Attribute | Value | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
error | String | A description of the error that occurred (if this is present, the rest of the fields will not be). | |||||||||
id | String | The username that should be used for subsequent connections to the MQTT server | |||||||||
secret | String | The password that should be used for subsequent connections to the MQTT server | |||||||||
topics |
| The topics the sensor should publish and subscribe to |
...
{
"id": "abc123",
"secret": "3b2184be2f2c11e5a151feff999cdc9e",
"topics": {
"data": "devices/3b2184be-2f2c-11e5-a151-feff819cdc9f/data",
"control": "devices/3b2184be-2f2c-11e5-a151-feff819cdc9f/control"
}
}
Data Message
Attribute | Value |
---|---|
Variable name | the variable value as a string |
...
{
"inTempF":
"72.5",
"inRh": "30.1"
}
Command Message
Description forthcoming.