Using the RWIO interface

Sometimes, you just need to have a simple and transparent method of accessing your devices to write and read data. This is what our RWIO interface is for. For a better platform integration you should however provide sensor and actuator definitions as this will make your devices interoperable with other BlueRange devices and will abstract the binary data structures from third party systems such as middlewares, apps, …

The RWIO interface will only publish data from the device if it was sent with a different actionType than UNSPECIFIED. For a full list of actionTypes, see the component_sense documentation. This was done to reduce the MQTT traffic as it would otherwhise report each sensor value twice: once through the RWIO API and next through the sensor API.

Connecting via MQTT

First, you need to have a connection to the MQTT Broker of your platform, this is explained in a lot of detail in our API Authentication guide. Make sure to follow all the steps to set up your MQTT client to get the relevant information and subscribe to the topic of your organization.

You should set up the client to only listen for messages within your current test network, so you should subscribe to the topic:

//You can listen to all messages of the organization, but a bit of filtering
//is helpful for this tutorial
rltn-iot/ORGA_UUID/NETWORK_UUID/#

The easiest way to find out the UUID of your organisation, network, device, …. is by using the developer console of your browser (e.g. F12 for chromium based browsers) while you are logged into the BlueRange portal. Look out for a request against the currentAuthorization REST endpoint and it will tell you the UUID of your current organisation in the response. To get the UUID of your network, simply navigate to your network in the portal and you should see the UUID in your browser’s address bar right after /network/….. You can also find out a UUID of any device when navigating to the device details.

Publishing a WRITE or WRITE_ACK

Now, you will first need to trigger a WRITE to set the status of your LED. You can either do this by executing the component_act command on the Gateway through our Portal as explained previously, or you can publish the command through our RWIO API.

Publishing the RWIO command can be seen in the following screenshot:

mqtt rwio write publish

//The topic contains the necessary identification for the device and what should be done
//You can also modify this topic and use writeAck instead of write to request a response
Topic: rltn-iot/ORGA_UUID/NETWORK_UUID/DEVICE_UUID/rwio/abcd01f0/1-2/write

//The payload duplicates some values of the topic and allows to switch the led on or off
 //AQ== switches the led on, use AA== to switch it off
{
  "module": "abcd01f0",
  "component": 1,
  "register": 2,
  "length": 1,
  "data": "AQ==",
  "requestHandle": 0,
  "timestamp": 1628857259621
}

Getting a Write Response

When using the write, the device will not generate any response but you should see the LED change its state. In order to get a response, modify the topic and use writeAck instead of write. You will then receive a writeRsp through the RWIO API on MQTT as seen below.

mqtt rwio write rsp

You are not seeing the periodically reported sensor values from your device here, because the Gateway is filtering out all component_sense messages with the actionType UNSPECIFIED. These are meant to be sensor values. Check out the next chapter to learn how to use them.

Now, here is an explanation of the writeRsp that we just received:

//The topic contains all the necessary UUIDs to identify the device
//It also contains the module name, the vendor moduleId that we were using
//Finally, it also includes the component and register seperated by a "-"
//and the actionType "writeRsp"
rltn-iot/ORGA_UUID/NETWORK_UUID/DEVICE_UUID/rwio/abcd01f0/1-1/writeRsp

//The Payload duplicates some of the information of the topic and adds
//the data encoded in Base64, which, in this case translates to 0x01
//which means that the LED has been turned on
{
  "module": "abcd01f0",
  "component": 1,
  "register": 1,
  "length": 1,
  "data": "AQ==",
  "requestHandle": 0,
  "timestamp": 1628857259621
}

Other Action Types

To see a list of possible actionTypes, refer to our MQTT API documentation. These actionTypes are mapped to the very similarly named actionTypes in our firmware.

Next Up

Now, as the RWIO interface is working, we are going to take a look at the configuration of a sensor and actuator Setting.