IBM Watson IoT Use Case Notes

Owned by Former user (Deleted)
Last updated: Jul 20, 2017

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

 Client ID: Customer has to enter in IBM format

            g:orgid:gatewaytype:gatewayid

 “g:” is for gateway.

orgid and gatewaytype are user-defined and must be added as a gateway device in IBM Bluemix before the RediGate can publish data.

User can hard-code gatewayid or use ${GATEWAY} or ${SERIAL} substitutable parameter to automatically use the gateway’s unit name or serial number.

 

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

            iot-2/type/gwtype/id/gwid/evt/STATE/fmt/text

(similar to publish topics described below, but typically using “fmt/text” at the end)

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

User Name: Enter the text:   use-token-auth

Password: User has to enter the gateway password registered in Bluemix for the gateway. (Can use ${TOKEN} to include password from the Global Texts object.)

 

IP/TLS Configuration: IBM requires SSL/TLS connection, so the IP address (or URL_List) option to be set to a localhost address (e.g. 127.0.0.1) in MQTT Client. It is suggested to use port 1883 for the internal (non-encrypted) MQTT connection. The TLS “STUNNEL Parameters” must be configured to forward the local connection to Bluemix on port 8883, such as:

            127.0.0.1:1883          orgid.messaging.internetofthings.ibmcloud.com:8883

 

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

Service: IBM BlueMix JSON

Topic Rules: Enter one or more of the following topics in the Topic Rules table:

Gateway Publish Topic:

Only one Gateway Publish Topic is allowed per JSON publisher.

Gateway information, such as birth message, will be published with gateway ID, such as:

            iot-2/type/gwtype/id/gwid/evt/STAT/fmt/json

gwtype must be defined in IBM BlueMix.

gwid must be defined as a device in IBM BlueMix. The substitutable parameters ${GATEWAY} or ${SERIAL} could be used to automatically bring in the RediGate unit name or serial number.

evt/STAT is an example of a user-definable event type, accessible in NodeRED.

Device Publish Topic:

Only one Device Publish Topic is allowed per JSON publisher.

Data can be published with the device type and ID, such as:

            iot-2/type/devtype/id/devid/evt/RBE/fmt/json

devtype can be an end device type. It does not need to be pre-defined in Bluemix, because devices published by gateways are automatically registered.

devid is the device ID, which will be automatically registered in Bluemix. This can be hard-coded, but more likely it should use a substitutable parameter. It can use ${DEV} to automatically use the field unit name, but it is recommended to use something like:

            ${GATEWAY}_${DEV} or ${SERIAL}_${DEV}

to incorporate the gateway identifier with the device, so all devices across all gateways in the system don’t have to be uniquely named. IBM requires data to be published from a gateway on behalf of a device to use a unique device ID.

evt/RBE is an example of a user-definable Event type, accessible in a NodeRED “ibmiot in” node as a “Device Event.”

Gateway Subscription Topic:

One or more subscription entries can be included for the gateway, for system commands to be sent for gateway control, such as:

            iot-2/type/gwtype/id/gwid/cmd/SYS/fmt/json

gwid can be ${GATEWAY} or ${SERIAL} to use substitutable parameters.

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

One or more Device Subscription Topics can be included, for command data to be sent to an end device, such as:

            iot-2/type/devtype/id/devid/cmd/CMD/fmt/json

devid is the end device ID. This can be hard-coded multiple subscribe topics, or it can be entered as a single topic using substitutable parameters. It can use ${DEV} to automatically use the field unit name, but it is recommended to use something like:

            ${GATEWAY}_${DEV} or ${SERIAL}_${DEV}

to incorporate the gateway identifier with the device, so all devices across all gateways in the system don’t have to be uniquely named. IBM requires data to be published from a gateway on behalf of a device to use a unique device ID.

cmd/CMD is an example of a user-definable command type, which would need to be included in the published topic. The “Device Command” is published from a NodeRED “ibmiot out” node.

For the device command subscription, the RediGate will substitute the RediGate name or serial number in place of ${GATEWAY} or ${SERIAL}. It will also substitute a “+” in place of any section of the topic that includes either ${CHAN} or ${DEV}, such as a subscription for:

            iot-2/type/gwtype/id/+/cmd/CMD/fmt/json

 

When publishing a device command message to the RediGate, the message received by the RediGate will be parsed the topic to verify the incoming message matches the configured Device Subscription topic(s). If any part of the Device Subscription topic includes the parameters ${GATEWAY}, ${SERIAL}, ${CHAN}, or ${DEV}, the RediGate will iterate through its list of channel and/or field unit names to verify if the topic matches a unit in the configuration.

The payload should include tag/value pairs using the IBM JSON format. Once a device command topic has been validated, the JSON-RBE process will iterate through the message, comparing the included tags  or register numbers against the field unit’s RTDB, and send data to the field unit in its native protocol. If a command message does not match any channel/RTU, it will be discarded. If a tag/register doesn’t match the configuration of a device, it will be discarded.