Win $20,000. Help build the future of education. Answer the call. Learn more

Troubleshoot device event problems

Introduction

The Watson IoT Platform has a feature called Last Event Cache that allows for temporary storage and retrieval of the last published event(s) for a device. This is very useful for troubleshooting purposes. Last Event Cache includes a RESTful API that allows for retrieval of event data received by the platform.

To use this feature, it must first be enabled on the Watson IoT Platform service dashboard.

alt

Once enabled, the API can be invoked to retrieve the last event data for a particular device.

To invoke the Last Event Cache API, the following properties must be used. It is possible to filter for the exact event by adding it after the events section.

URL: https://[orgID].internetofthings.ibmcloud.com/api/v0002/device/types/[deviceType]/devices/[deviceId]/events
Method: GET
Authorization: Basic
User name: [apiKey]
Password: [apiToken]

The apiKey and apiToken are generated from the Watson IoT Platform service dashboard, under the Apps tab.

alt

Devices can publish events in either JSON format or binary format. The Last Event Cache feature retrieves the data and wraps it in a Base64 format and returns it to the client in a JSON document. This allows for the representation of string or binary data (both are wrapped in Base64).

The payload from the Last Event Cache API can be decoded so it is human-readable (assuming that the original event was published in JSON format). There are a number of online tools that can be used to decode the payload, for example: https://www.base64decode.org/

Additionally, other tools like Node-RED or POSTMan can be used to retrieve and convert the Last Event Cache payload.  

Node-RED Flow Sample

Using Node-RED, it is easy to consume payloads from the LEC. The following flow is an example of a solution for retrieving and transforming the LEC payload:

alt

prepareIOTCalls Function Node

This following node is used to configure the parameters needed for the GET call.

// WIoTP URL
var WIOTPURL = "https://{orgID}.internetofthings.ibmcloud.com";
var url = WIOTPURL + "/api/v0002/device/types/";

// Authorization
var apikey = "{apiKey}";
var apitoken = "{apiToken}";
var auth = 'Basic ' + new Buffer(apikey + ':' + apitoken).toString('base64');

// Device type and name
var deviceType = "{deviceType}";
var deviceName = "{deviceId}";

msg.url = url + deviceType + "/devices/" + deviceName + "/events";
msg.headers = {};
msg.headers.Authorization = auth;

return msg;

GET LastEvents HTTP Node

This node executes the API call. There is no configuration needed for this node, as it uses the msg properties that are set in the prepareIOTCalls node.

processResponse Function Node

The following node handles the conversion of the payload from Base64 format.

var msgList = [];
var curMsg = {};

for (var row in msg.payload) {
   var rawData = new Buffer.from(msg.payload[row].payload, 'base64');
   var data = rawData.toString('utf8');
   msg.payload[row].payload = JSON.parse(data);
}

return msg;

lastEventData debug Node

Outputs the decoded message(s) to the debug console for inspection.

POSTMan Sample

POSTMan is a widely-used 3rd party API development and testing tool.

Using POSTMan, a GET call can be configured with Authentication (basic with apiKey and apiToken as username/password) and with the URL previously defined.

The following is an example of a POSTMan GET for a LEC event.

alt

The result of the GET call is a JSON document that includes a payload property in Base64 format. This payload can be decoded online or using the Tests feature of POSTMan, a small test can be added to the call to perform the conversion:

alt

The script code is below.

pm.test("payload", function () {

var payload = pm.response.json();
var decoded = CryptoJS.enc.Base64.parse(payload[0].payload);

console.log("decoded: " + CryptoJS.enc.Utf8.stringify(decoded));

});

Once added, the GET call can be executed again. This time, the test script will also fire after the response is obtained from the server and the code will output to the POSTMan console.

alt

As shown above, the Base64 payload is shown in the console in human-readable format.

Conclusion

The Watson IoT Platform Last Event Cache is a useful feature for inspecting the raw payload received by the platform from any device. The feature must first be enabled in the service dashboard. Once enabled, a RESTful API is provided to access the last event data.

The Last Event Cache API returns a JSON payload that is formatted in Base64 format. This payload can be converted to human-readable format using a number of tools. This tutorial described three approaches for performing the conversion, including a free online tool, Node-RED, and POSTMan.