MQTT Configuration¶
Input API is based on MQTT protocol and includes authentication, optional encryption, device configuration and real-time stream of measured data.
Used data format is text oriented JSON.
Authentication¶
Each Homebase has unique credentials to MQTT server – the username is 16 character long serial number and password is 16 character long string from secret saved in non-volatile memory during manufacturing.
Customer’s MQTT server can download all secrets from provisioning server. Each secret is 256 bytes long array and has following structure:
struct {
uint8_t aes_key[32]; // AES-128 or AES-256 encryption key.
uint8_t mqtt_password[8]; // Password for MQTT authentification.
uint8_t aes_iv[16]; // Initialization vector for AES.
uint8_t hmac_key[32]; // HMAC-SHA256 key.
uint8_t unused[168]; // Unused, reserved for future use.
} ewg_secret_t;
The MQTT password is printed as 16 character long lowercase HEX string. For example
Homebase with serial number 2318A20DEF4818EA has following MQTT credentials:
// Secret array stored in both Homebase non-volatile memory and provisioning server.
uint8_t secret[256] = {..., 178, 59, 52, 13, 47, 116, 76, 143, ...};
// Pointer to first byte of mqtt password in secret array.
uint8_t *mqtt_password = secret + 32;
// The MQTT password is converted to string as HEX numbers, lowercase.
char mqtt_password_str[16] = "b23b340d2f744c8f";
// The MQTT username is Homebase's serial number, uppercase.
char mqtt_username_str[16] = "2318A20DEF4818EA";
Configuration¶
The Homebase configuration has several phases. The phases are device registration, apps registration, sending data.
Device Registration¶
After power-on or reset and before power-down or reset, the device has to send status
information to the MQTT server. Each device has unique topic where status is sent. The
topic has format sn/{sn}/status where {sn} is device’s unique serial number.
Payload is an ASCII string connected or disconnected.
Disconnected message can be set as last will mechanism on the MQTT server, so it will be sent as soon as MQTT connection between device and server is closed. All messages in this topic are sent with retain flag. If encryption is enabled, this topic is the only one send in plaintext.
Example 1: device 6748E0F8B843A6EE powered on and connects to MQTT server
Topic: sn/6748E0F8B843A6EE/status
Payload: connected
Example 2: device 6748E0F8B843A6EE set last will to status topic and after some
time it lost internet connection
Topic: sn/6748E0F8B843A6EE/status
Payload: disconnected
Apps Registration¶
Each separate Homebase functionality is called app and can be configured via MQTT.
In order to communicate with server, each application has to register itself. This registration is done on two MQTT topics:
Init: app sends message to this topic to register itself.
Configuration: server publish configuration to this topic for app.
MQTT init topic is sn/{sn}/{app_name}/init where {sn} is device’s serial number
and {app_name} is application name. Payload in this topic has to be in JSON format
and has to contain key version with application version.
MQTT configuration topic is sn/{sn}/{app_name}/conf. The application has to subscribe
to this topic before init message. Payload in this topic can be in JSON format.
Application should not unsubscribe from its configuration topic because server
can send new configuration anytime after registration.
There are two apps in standard MQTT firmware: clock and collector.
Clock¶
Since Homebase does not have RTC (real-time clock), the time has to be set up after each power-up or reset. The clock application synchronizes Homebase’s internal clock with server.
The valid configuration parameters for this application are:
time [uint32]: actual time, Unix epoch time, seconds since 1.1.1970.
Note
Wihout time, the Homebase will NOT receive any packets from radio and all measured
data will be lost. The server has to assure valid time is send to Homebase as soon
as clock/init message is received.
Collector¶
This application sends received Chirp packets in JSON format to server. The valid configuration parameters are:
topic [array, 42B]: string, MQTT topic where standard Chirp trap packets will be send.
topic-bct [array, 42B]: string, MQTT topic where broadcast Chirp packets will be send.
stop [uint16]: stop sending measured data, number of seconds.
edfmin [uint8]: minimum supported data format version.
edfmax [uint8]: maximum supported data format version.
All five parameters are optional and can be missing in config message from server.
The stop parameter can be used to mute Homebase for defined time and can be send to Homebase any time. All measured data are stored into internal buffer and send to server as soon as stop time ended. This functionality is supported since collector version 2.0.
The topic and topic-bct parameters both contains topic string where received Chirp packets will be sent to MQTT server. Topic defined in topic parameter will be used for standard Chirp trap packets (measured data from sensors paired to Homebase channels) and topic-bct parameter will be used for Chirp broadcast packets (measured data from all nearby sensors, not paired to any Homebase’s channel). If some topic parameter is missing in config message from server, the corresponding packet type will be ignored by Homebase and will not be send to MQTT server. Broadcast packets are supported since collector version 3.0.
Payload send to topics and topic-bct has format defined in section Payload Format
The edfmin and edfmax parameters contain minimum and maximum data format version supported by the MQTT server. The Homebase will send data in the highest format version supported both by its firmware and the MQTT server. If the parameters are not specified, it will use version 1. This functionality is supported since collector version 4.0.
edfmin and edfmax use format version defined in section Payload Format
Example 3: application collector on device 6748E0F8B843A6EE:
Configuration subsribe
Topic: sn/6748E0F8B843A6EE/collector/conf
Init message
Topic: sn/6748E0F8B843A6EE/collector/init
Payload: {"version": "3.0"}
Configuration data from server (all parameters):
Topic: sn/6748E0F8B843A6EE/collector/conf
Payload: {"topic": "data/trap/123", "topic-bct": "data/broadcast/123, "stop": 60, "edfmin": 1, "edfmax": 4}
Configuration data from server (send only Chirp trap packets to server):
Topic: sn/6748E0F8B843A6EE/collector/conf
Payload: {"topic": "data/trap/123"}
Configuration data from server (send only broadcast packets to server):
Topic: sn/6748E0F8B843A6EE/collector/conf
Payload: {"topic-bct": "data/broadcast/123"}
Example 4: application clock on device 6748E0F8B843A6EE:
Configuration subsribe
Topic: sn/6748E0F8B843A6EE/clock/conf
Init message
Topic: sn/6748E0F8B843A6EE/clock/init
Payload: {"version": "1.0"}
Configuration data from server:
Topic: sn/6748E0F8B843A6EE/clock/conf
Payload: {"time": 1429012381}
Full configuration example¶
PUBLISH: sn/6748E0F8B843A6EE/status connected
LAST WILL: sn/6748E0F8B843A6EE/status disconnected
SUBSCRIBE: sn/6748E0F8B843A6EE/collector/conf
SUBSCRIBE: sn/6748E0F8B843A6EE/clock/conf
PUBLISH: sn/6748E0F8B843A6EE/collector/init {"version": "1.2"}
PUBLISH: sn/6748E0F8B843A6EE/clock/init {"version": "12.3"}
RECEIVE: sn/6748E0F8B843A6EE/clock/conf {"time": 123456789}
RECEIVE: sn/6748E0F8B843A6EE/collector/conf {"topic": "data/trap/123", "topic-bct": "data/broadcast/123, "edfmin": 4, "edfmax": 4}