Table of Content
- Setting up Eclipse Hono MQTT remote management
- Management service identifiers
- Azure IoT Hub
- MQTT
- EnOcean
Setting up Eclipse HONO remote management
Prerequisites:
- Initial set up gateway
- MQTT broker
Navigate to the Remote Management page by clicking “- Remote Management” in the "System" sub-menu on the Pressac EnOcean Gateway web-interface.
Here you will enable remote management and populate the fields with your MQTT Broker information.
- Status– Current status of the connection to the admin MQTT broker.
- MQTT API– MQTT API can be enabled/disabled here (defaults to disabled).
- Client ID– Client ID is display only and cannot be changed (defaults to {gatewayserial})
- Hostname– Hostname of admin MQTT broker
- TLS– Whether the admin MQTT broker has security enabled
- Port– Port for admin MQTT broker
- Username– Username for admin MQTT broker
- Password– Password for admin MQTT broker
- Save Button– Saves any changes made to settings
Once you have done this you are now able to use remote management via MQTT on your gateway.
Management service identifiers
Service identifiers are used after the root topic to identify the service you would like to manage. Initial services include Azure IoT Hub – {azureiothub}, IBM Watson – {ibmwatson} and EnOcean – {enocean}.
Examples below.
Using the Azure IoT Hub – c//{gatewayserial}/req/{reqID}/azureiothub
Using the EnOcean Service – c//{gatewayserial}/req/{reqID}/enocean
Using the IBM Watson Service – c//{gatewayserial}/req/{reqID}/ibmwatson
Using the MQTT Service - c//{gatewayserial}/req/{reqID}/mqtt
Note: When inputting {gatewayserial} ensure that the letters are in lowercase format.
Azure IoT Hub
The Azure IoT Hub management service currently supports the below actions.
- /getconfig – This action allows you to request the current credentials for your Azure IoT Hub connection.
- /update – This action allows you to update the credentials for your Azure IoT Hub connection.
- /getstatus – This action allows you to request the current status of your Azure IoT Hub connection.
/getconfig
If you wish to receive the current Azure IoT Hub credentials, insert the following line of text into the topic you wish to publish to MQTT on your gateway.
Request from application:
Topic: ‘c//{gatewayserial}/req/{reqID}/azureiothub-getconfig’
Payload:
{}
View example screenshot below:
If you have done this correctly you should receive the following response from the gateway.
Response from gateway:
Topic: ‘c//{gatewayserial}/res/{reqID}/200’
Payload:
{
"azureconnection": "ON/OFF",
"hostname": "STRING",
"deviceid": "STRING",
"accesskey": "STRING",
"includeddata": {
"timestamp": "BOOLEAN",
"devicename": "BOOLEAN",
"deviceid": "BOOLEAN",
"devicetype": "BOOLEAN",
"gatewayname": "BOOLEAN",
"devicelocation": "BOOLEAN",
"devicevalues": "BOOLEAN",
"devicevalueunit": "BOOLEAN",
"signalstrength": "BOOLEAN",
"security": "BOOLEAN"
}
}
View example screenshot below:
/update
If you wish to update the current Azure IoT Hub credentials, insert the following line of text into the topic you wish to publish to MQTT on your gateway.
Request from application:
Topic: ‘c//{gatewayserial}/req/{reqID}/azureiothub-update’
Payload:
{
"azureconnection": "ON/OFF",
"hostname": "STRING",
"deviceid": "STRING",
"accesskey": "STRING",
"includeddata": {
"timestamp": "BOOLEAN",
"devicename": "BOOLEAN",
"deviceid": "BOOLEAN",
"devicetype": "BOOLEAN",
"gatewayname": "BOOLEAN",
"devicelocation": "BOOLEAN",
"devicevalues": "BOOLEAN",
"devicevalueunit": "BOOLEAN",
"signalstrength": "BOOLEAN",
"security": "BOOLEAN"
}
}
View example screenshot below:
If you have done this correctly you should receive the following response from the gateway.
Response from gateway:
Topic: ‘c//{gatewayserial}/res/{reqID}/200’
Payload:
{
"success": "BOOLEAN",
"error": "NULL / ERRORCODE"
}
View example screenshot below:
/getstatus
If you wish to receive the status of your Azure IoT Hub connection, insert the following line of text into the topic you wish to publish to MQTT on your gateway.
Request from application:
Topic: ‘c//{gatewayserial}/req/{reqID}/azureiothub-getstatus’
Payload:
{}
View example screenshot below:
If you have done this correctly you should receive the following response from the gateway.
Response from gateway:
Topic: ‘c//{gatewayserial}/res/{reqID}/200’
Payload:
{
"azureiothubstatus": "STRING",
}
View example screenshot below:
MQTT
The MQTT management service currently supports the below actions.
- /settings/getconfig
- /settings/update
- /connections/getconfig
- /connections/update
- /connection/getstatus
/settings/getconfig
If you wish to receive the current MQTT settings, insert the following line of text into the topic you wish to publish to MQTT on your gateway.
Request from application:
Topic: ‘c//{gatewayserial}/req/{reqID}/mqtt-settings-getconfig’
Payload:
{}
View example screenshot below:
If you have done this correctly you should receive the following response from the gateway.
Response from gateway:
Topic: ‘c//{gatewayserial}/res/{reqID}/200’
Payload:
{
"defaultclientid": "STRING",
"roottopic": "STRING",
"deviceidentifier": "STRING",
"includeddata": {
"timestamp": "BOOLEAN",
"devicename": "BOOLEAN",
"deviceid": "BOOLEAN",
"devicetype": "BOOLEAN",
"gatewayname": "BOOLEAN",
"devicelocation": "BOOLEAN",
"devicevalues": "BOOLEAN",
"devicevalueunit": "BOOLEAN",
"signalstrength": "BOOLEAN",
"security": "BOOLEAN"
}
}
View example screenshot below:
/settings/update
If you wish to update the current MQTT settings, insert the following line of text into the topic you wish to publish to MQTT on your gateway.
Request from application:
Topic: ‘c//{gatewayserial}/req/{reqID}/mqtt-settings-update’
Payload:
{
"defaultclientid": "STRING",
"roottopic": "STRING",
"deviceidentifier": "STRING",
"includeddata": {
"timestamp": "BOOLEAN",
"devicename": "BOOLEAN",
"deviceid": "BOOLEAN",
"devicetype": "BOOLEAN",
"gatewayname": "BOOLEAN",
"devicelocation": "BOOLEAN",
"devicevalues": "BOOLEAN",
"devicevalueunit": "BOOLEAN",
"signalstrength": "BOOLEAN",
"security": "BOOLEAN"
}
}
View example screenshot below:
If you have done this correctly you should receive the following response from the gateway.
Response from gateway:
Topic: ‘c//{gatewayserial}/res/{reqID}/200’
Payload:
{
"success": "BOOLEAN",
"error": "NULL / ERRORCODE"
}
View example screenshot below:
/connections/getconfig
If you wish to receive the current settings of the MQTT connections, insert the following line of text into the topic you wish to publish to MQTT on your gateway.
Request from application:
Topic: ‘c//{gatewayserial}/req/{reqID}/mqtt-connections-getconfig’
Payload:
{
"success": "BOOLEAN",
"error": "NULL / ERRORCODE"
}
View example screenshot below:
If you have done this correctly you should receive the following response from the gateway.
Response from gateway:
Topic: ‘c//{gatewayserial}/res/{reqID}/400’
Payload:
{
"mqttindex": "INTEGER[1…5]",
"mqttconnection": "ON/OFF",
"connectionname": "STRING",
"clientid": {
"usedefault": "BOOLEAN",
"clientid": "STRING"
},
"hostname": "STRING",
"port": "STRING",
"tls": "BOOLEAN",
"authentication": "BOOLEAN",
"credentials": {
"username": "STRING",
"password": "STRING"
}
}
View example screenshot below:
/connections/update
If you wish to update the MQTT connection settings, insert the following line of text into the topic you wish to publish to MQTT on your gateway.
Request from application:
Topic: ‘c//{gatewayserial}/req/{reqID}/mqtt-connections-update’
Payload:
{
"mqttindex": "INTEGER[1…5]",
"mqttconnection": "ON/OFF",
"connectionname": "STRING",
"clientid": {
"usedefault": "BOOLEAN",
"clientid": "STRING"
},
"hostname": "STRING",
"port": "STRING",
"tls": "BOOLEAN",
"authentication": "BOOLEAN",
"credentials": {
"username": "STRING",
"password": "STRING"
}
}
View example screenshot below:
If you have done this correctly you should receive the following response from the gateway.
Response from gateway:
Topic: ‘c//{gatewayserial}/res/{reqID}/200’
Payload:
{
"success": "BOOLEAN",
"error": "NULL / ERRORCODE"
}
View example screenshot below:
/connections/getstatus
If you wish to receive the status of the MQTT connections, insert the following line of text into the topic you wish to publish to MQTT on your gateway.
Request from application:
Topic: ‘c//{gatewayserial}/req/{reqID}/mqtt-connections-getstatus’
Payload:
{
"mqttindex": "INTEGER[1…5]"
}
View example screenshot below:
If you have done this correctly you should receive the following response from the gateway.
Response from gateway:
Topic: ‘c//{gatewayserial}/res/{reqID}/200’
Payload:
{
"mqttindex": "INTEGER[1..5]",
"status": "STRING"
}
View example screenshot below:
EnOcean
The EnOcean management service currently supports the below actions.
- /removedevice
- /adddevice
- /editdevice
- /getdevicelist
- /geteeplist
/removedevice
If you wish to remove an EnOcean device, insert the following line of text into the topic you wish to publish to MQTT on your gateway.
Request from application:
Topic: ‘c//{gatewayserial}/req/{reqID}/enocean-removedevice’
Payload:
{
"deviceid": "HEX"
}
View example screenshot below:
If you have done this correctly you should receive the following response from the gateway.
Response from gateway:
Topic: ‘c//{gatewayserial}/res/{reqID}/200’
Payload:
{
"success": "BOOLEAN",
"error": "NULL / ERRORCODE"
}
View example screenshot below:
Possible Errors:
- “error”: “EnOcean device does not exist”
- “error”: “Invalid EnOcean device ID”
/adddevice
If you wish to add an EnOcean device, insert the following line of text into the topic you wish to publish to MQTT on your gateway.
Note: You cannot add security enabled devices via this method.
Request from application:
Topic: ‘c//{gatewayserial}/req/{reqID}/enocean-adddevice’
Payload:
{
"devicename": "STRING",
"deviceid": "HEX",
"location": "STRING",
"sendDuplicate": "BOOLEAN",
"eep": "RORG-FUNC-TYPE",
"type": "STRING",
"security”: “BOOLEAN"
}
View example screenshot below:
If you have done this correctly you should receive the following response from the gateway.
Response from gateway:
Topic: ‘c//{gatewayserial}/res/{reqID}/200’
Payload:
{
"success": "BOOLEAN",
"error": "NULL / ERRORCODE"
}
View example screenshot below:
Possible Errors:
- “error”: “EnOcean device already exists”
- “error”: “Invalid EnOcean device name”
- “error”: “Invalid EnOcean device ID”
- “error”: “Invalid EnOcean device eep”
- “error”: “Invalid EnOcean security structure”
/editdevice
If you wish to edit an existing EnOcean device, insert the following line of text into the topic you wish to publish to MQTT on your gateway.
Request from application:
Topic: ‘c//{gatewayserial}/req/{reqID}/enocean-editdevice’
Payload:
{
"devicename": "STRING",
"deviceid": "HEX",
"location": "STRING",
"sendDuplicate": "BOOLEAN",
"eep": "RORG-FUNC-TYPE",
"type": "STRING"
}
View example screenshot below:
If you have done this correctly you should receive the following response from the gateway.
Response from gateway:
Topic: ‘c//{gatewayserial}/res/{reqID}/200’
Payload:
{
"success": "BOOLEAN",
"error": "NULL / ERRORCODE"
}
View example screenshot below:
Possible errors:
- “error”: “EnOcean device does not exist”
- “error”: “Invalid EnOcean device name”
- “error”: “Invalid EnOcean device ID”
- “error”: “Invalid EnOcean device eep”
/getdevicelist
If you wish to receive a list of EnOcean devices on the gateway, insert the following line of text into the topic you wish to publish to MQTT on your gateway.
Request from application:
Topic: ‘c//{gatewayserial}/req/{reqID}/enocean-getdevicelist’
Payload:
{}
View example screenshot below:
If you have done this correctly you should receive the following response from the gateway.
Response from gateway:
Topic: ‘c//{gatewayserial}/res/{reqID}/200’
Payload:
{
"success": "BOOLEAN",
"error": "NULL / ERRORCODE",
"devicecount": "INT",
"devices": [{
"deviceid": "HEX",
"devicename": "STRING",
"location": "STRING",
"sendDuplicate": "BOOLEAN",
"eep": "RORG - FUNC - TYPE",
"type": "STRING"
"security": "BOOLEAN"
},….]
}
View example screenshot below:
/geteeplist
If you wish to receive a list of supported EnOcean EEPs on the gateway, insert the following line of text into the topic you wish to publish to MQTT on your gateway.
Request from application:
Topic: ‘c//{gatewayserial}/req/{reqID}/enocean-geteeplist’
Payload:
{}
View example screenshot below:
If you have done this correctly you should receive the following response from the gateway.
Response from gateway:
Topic: ‘c//{gatewayserial}/res/{reqID}/200’
Payload:
{
"success": "BOOLEAN",
"error": "NULL / ERRORCODE",
"eepcount": "INT",
"eeps": ["XX-XX-XX", "XX-XX-XX", ...]
}
View example screenshot below:
