Setting up 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 – admin/{gatewayserial}/azureiothub
    Using the EnOcean Service – admin/{gatewayserial}/enocean
    Using the IBM Watson Service – admin/{gatewayserial}/ibmwatson

    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: ‘admin/{gatewayserial}/azureiothub/getconfig’

    Payload:

    {}

    View example screenshot

    If you have done this correctly you should receive the following response from the gateway.

    Response from gateway:

    Topic: ‘admin/{gatewayserial}/azureiothub/config’

    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

    /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: ‘admin/{gatewayserial}/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

    If you have done this correctly you should receive the following response from the gateway.
    Response from gateway:

    Topic: ‘admin/{gatewayserial}/azureiothub/update/ack’

    Payload:

    {
       "success": "BOOLEAN",
       "error": "NULL / ERRORCODE"
    }
    

    View example screenshot

    /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: ‘admin/{gatewayserial}/azureiothub/getstatus

    Payload:

    {}

    View example screenshot

    If you have done this correctly you should receive the following response from the gateway.
    Response from gateway:

    Topic: ‘admin/{gatewayserial}/azureiothub/status’

    Payload:

    {
       "azureiothubstatus": "STRING",
    }
    

    View example screenshot

    IBM Watson

    The IBM Watson management service currently supports the below actions.

    • /getconfig – This action allows you to request the current credentials for your IBM Watson connection.
    • /update – This action allows you to update the credentials for your IBM Watson connection.
    • /getstatus – This action allows you to request the current status of your IBM Watson connection.

    /getconfig

    If you wish to receive the current IBM Watson credentials, insert the following line of text into the topic you wish to publish to MQTT on your gateway.

    Request from application:

    Topic: ‘admin/{gatewayserial}/ibmwatson/getconfig’

    Payload:

    {}

    View example screenshot

    If you have done this correctly you should receive the following response from the gateway.

    Response from gateway:

    Topic: ‘admin/{gatewayserial}/ibmwatson/config’

    Payload:

    {
       "ibmconnection": "ON/OFF",
       "organisationid": "STRING",
       "gatewaytype": "STRING",
       "gatewayid": "STRING",
       "authtoken": "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

    /update

    If you wish to update the current IBM Watson credentials, insert the following line of text into the topic you wish to publish to MQTT on your gateway.

    Request from application:

    Topic: ‘admin/{gatewayserial}/ibmwatson/update’

    Payload:

    {
       "ibmconnection": "ON/OFF",
       "organisationid": "STRING",
       "gatewaytype": "STRING",
       "gatewayid": "STRING",
       "authtoken": "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

    If you have done this correctly you should receive the following response from the gateway.

    Response from gateway:

    Topic: ‘admin/{gatewayserial}/ibmwatson/update/ack’

    Payload:

    {
       "success": "BOOLEAN",
       "error": "NULL / ERRORCODE"
    }
    

    View example screenshot

    Possible errors:

    • “error”: “Invalid IBM organisation ID”
    • “error”: “Invalid IBM Watson gateway type”
    • “error”: “Invalid IBM Watson gateway ID”
    • “error”: “Invalid IBM Watson token”
    • “error”: “Invalid IBM Watson included data structure”

    /getstatus

    If you wish to receive the status of your IBM Watson connection, insert the following line of text into the topic you wish to publish to MQTT on your gateway.

    Request from application:

    Topic: ‘admin/{gatewayserial}/ibmwatson/getstatus’

    Payload:

    {}

    View example screenshot

    If you have done this correctly you should receive the following response from the gateway.

    Response from gateway:

    Topic: ‘admin/{gatewayserial}/ibmwatson/status’

    Payload:

    {
       "ibmconnectionstatus": "STRING",
    }
    

    View example screenshot

    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: ‘admin/{gatewayserial}/mqtt/settings/getconfig’

    Payload:

    {}

    View example screenshot

    If you have done this correctly you should receive the following response from the gateway.

    Response from gateway:

    Topic: ‘admin/{gatewayserial}/mqtt/settings/config’

    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

    /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: ‘admin/{gatewayserial}/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

    If you have done this correctly you should receive the following response from the gateway.

    Response from gateway:

    Topic: ‘admin/{gatewayserial}/mqtt/settings/update/ack’

    Payload:

    {
       "success": "BOOLEAN",
       "error": "NULL / ERRORCODE"
    }
    

    View example screenshot

    /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: ‘admin/{gatewayserial}/mqtt/connections/getconfig’

    Payload:

    {
       "mqttindex": "INTEGER[1…5]"
    }
    

    View example screenshot

    If you have done this correctly you should receive the following response from the gateway.

    Response from gateway:

    Topic: ‘admin/{gatewayserial}/mqtt/connections/config’

    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

    /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: ‘admin/{gatewayserial}/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

    If you have done this correctly you should receive the following response from the gateway.

    Response from gateway:

    Topic: ‘admin/{gatewayserial}/mqtt/connections/update/ack’

    Payload:

    {
       "success": "BOOLEAN",
       "error": "NULL / ERRORCODE"
    }
    

    View example screenshot

    /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: ‘admin/{gatewayserial}/mqtt/connections/getstatus’

    Payload:

    {
       "mqttindex": "INTEGER[1…5]"
    }
    

    View example screenshot

    If you have done this correctly you should receive the following response from the gateway.

    Response from gateway:

    Topic: ‘admin/{gatewayserial}/mqtt/connections/status’

    Payload:

    {
       "mqttindex": "INTEGER[1..5]",
       "status": "STRING"
    }
    

    View example screenshot

    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: ‘admin/{gatewayserial}/enocean/removedevice’

    Payload:

    {
       "deviceid": "HEX"
    }
    

    View example screenshot

    If you have done this correctly you should receive the following response from the gateway.

    Response from gateway:

    Topic: ‘admin/{gatewayserial}/enocean/removedevice/ack’

    Payload:

    {
       "success": "BOOLEAN",
       "error": "NULL / ERRORCODE"
    }
    

    View example screenshot

    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: ‘admin/{gatewayserial}/enocean/adddevice’

    Payload:

    {
       "devicename": "STRING",
       "deviceid": "HEX",
       "location": "STRING",
       "sendDuplicate": "BOOLEAN",
       "eep": "RORG-FUNC-TYPE",
       "type": "STRING",
       "security”: “BOOLEAN"
       }
    

    View example screenshot

    If you have done this correctly you should receive the following response from the gateway.

    Response from gateway:

    Topic: ‘admin/{gatewayserial}/enocean/adddevice/ack’

    Payload:

    {
       "success": "BOOLEAN",
       "error": "NULL / ERRORCODE"
    }
    

    View example screenshot

    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: ‘admin/{gatewayserial}/enocean/editdevice’

    Payload:

    {
       "devicename": "STRING",
       "deviceid": "HEX",
       "location": "STRING",
       "sendDuplicate": "BOOLEAN",
       "eep": "RORG-FUNC-TYPE",
       "type": "STRING"
    }
    

    View example screenshot

    If you have done this correctly you should receive the following response from the gateway.

    Response from gateway:

    Topic: ‘admin/{gatewayserial}/enocean/editdevice/ack’

    Payload:

    {
       "success": "BOOLEAN",
       "error": "NULL / ERRORCODE"
    }
    

    View example screenshot

    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: ‘admin/{gatewayserial}/enocean/getdevicelist’

    Payload:

    {}

    View example screenshot

    If you have done this correctly you should receive the following response from the gateway.

    Response from gateway:

    Topic: ‘admin/{gatewayserial}/enocean/devicelist’

    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

    /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: ‘admin/{gatewayserial}/enocean/geteeplist’

    Payload:

    {}

    View example screenshot

    If you have done this correctly you should receive the following response from the gateway.

    Response from gateway:

    Topic: ‘admin/{gatewayserial}/enocean/eeplist’

    Payload:

    {
       "success": "BOOLEAN",
       "error": "NULL / ERRORCODE",
       "eepcount": "INT",
       "eeps": ["XX-XX-XX", "XX-XX-XX", ...]
    }
    

    View example screenshot

    in Gateway configuration