Microsoft Azure IoT Hub Use Case Notes

Microsoft Azure Configuration

To configure the JSON-RBE for Microsoft Azure, the following settings are needed in the MQ Client object:

Client ID: Use gateway device ID, or ${GATEWAY} or ${SERIAL} to retrieve dynamically from RediGate.

User Name: Must be in the format:

            iothubhostname/gwid

Examples:       elecsys.azure-devices.net/testdevice1

                        elecsys.azure-devices.net/${GATEWAY}

                        elecsys.azure-devices.net/${SERIAL}

Password: Use substitutable parameter such as ${AZURE_LOGIN}

Azure requires the password to be a Shared Access Signature (SAS) token, generated by an algorithm. The token is usually about 160 characters long, which is longer than the 128 characters allowed in the MQ Client Password field. In order to make this work, the ACE configuration needs a Global_Texts object that is referenced in the password string with a parameter such as ${AZURE_LOGIN}. Then in the Global_Texts object, add a row containing (with no ${ } characters):

Search Name

Replacement Text

AZURE_LOGIN

SAS_token_generated_for_this_device

 

Last Will Topic: This topic can be defined such as:

            devices/gwid/messages/events/{propertybag}

(similar to publish topics described below; {propertybag} is optional, but slash after “events” is required)

Last Will Payload: Payload can be simple text, such as “OFFLINE”.

SSL/TLS Configuration

Azure requires the TLS connection to be made on port 8883. The IoT Hub uses a DNS name, such as iothubhostname.azure-devices.net. The TLS “Connect To” field should be, for example: elecsys.azure-devices.net:8883

The issuing authority for the TLS certs is: https://ssl-tools.net/certificates/d4de20d05e66fc53fe1a50882c78db2852cae474.pem

 

For the JSON_RBE object, use the following settings that are unique to Azure, in addition to setting other standard properties:

Service: Microsoft Azure JSON

Topic Rules: Enter the following topics. The “Device Publish” and “Device Subscription” topics are relatively fixed by Azure specification. The other topics are user-definable but suggested here.

Device Publish Topic (RBE data from RediGate to Azure):

            devices/gwid/messages/events/{propertybag}

gwid must be the ID of the gateway registered in Azure. It can be hard-coded or use a variable such as ${GATEWAY} or ${SERIAL} for the RediGate name or serial#.

{propertybag} is optional and represents additional message properties in a url-encoded format; but the final slash / after “events” must be included in any case.

Device Subscription Topic (commands sent from Azure to an end device):

            devices/gwid/messages/devicebound/device=${DEV}_

gwid must be the ID of the gateway registered in Azure. It can be hard-coded or use a variable such as ${GATEWAY} or ${SERIAL} for the RediGate name or serial#.

device=${DEV}_ is used to specify the field unit name to which the commands are being sent. Note that there must be a terminating character after ${DEV}, such as underscore. In Azure, published messages include a “propertybag” portion as the last field of the topic. When publishing commands to a device, include a key/value pair of “device/devicename_” (with terminating character), so that the published topic will be built correctly. Azure will include “device=devicename_” in the topic, and the RediGate searches through the last field of the topic for a match, according to the ${DEV} substitutable parameter.

Once a device command topic has been validated, the JSON payload with tag/value pairs will be parsed, comparing the included tags or register numbers against the field unit’s RTDB, and sending data to the field unit in its native protocol. If a command message does not match the data fields, the values will be discarded.