Managing IoT Blockchain Service routes

A route is a IoT Blockchain Service component that is used to connect your IoT device or application to a blockchain and map all or part of the incoming payload data to a smart contract.

Overview

An IoT Blockchain Service route connects a source end-point to a destination end-point with a mapping between their payload schema formats.

Note: In the following diagrams the label IoT Blockchain Service identifies the IoT Blockchain Service service component.

A map can be passthrough or contain individual mappings for properties:

Route components

The following components make up a IoT Blockchain Service route:

Create an IoT Blockchain Service route with the API

Follow these steps to create a route with the IoT Blockchain Service API.

Tip: You can also create basic passthrough routes using the IoT Blockchain Service user interface. For information, see Getting started with IoT Blockchain Service.

Before you begin.

Create an IoT Blockchain Service notification endpoint with the API

A notification endpoint is defined in a separate Endpoint document, which defines an application end point with an HTTP or Event Streams target server to which IoT Blockchain Service sends the selected notifications. For more information, see the Endpoint and Route sections of the API documentation. The IoT Blockchain Service Postman collection contains examples of the two types of notifications under “3 Notify endpoints”.

To create an endpoint document, do the following API POST:
{iotbc_url}/api/v1/{org}/endpoints/{endpoint}
Where:

Create a route

For a route and mapping example, see Sample route.

  1. Create a JSON routing map to map the properties.
    Decide which device payload properties to include as required and which contract properties to map them to.

  2. Create the route.
    For detailed information, see Create route API documentation.
    Tip: If you installed the Postman collection, use the modified new route... postman command that you created.

    Do the following API POST:
    {iotbc_url}/api/v1/{org}/routes/{appname}/{appevent}
    Where:

    • {iotbc_url} is the SaaS URL for your IoT Blockchain Service organization: https://iot-blockchain.ibm.com

      • {org} is your five alphanumeric character IoT Blockchain Service organization identifier.
      • {appname} is the application name.
        Tip: For Watson IoT Platform Service you could for example use the device name for clarity.
      • {appevent} is the smart contract transaction to execute.

      Use the following message content:

      • Content-Type header: application/json
      • Authorization header: Basic Auth with username use-token-auth and password:{apiKey}.
        Note: For more information, see Creating IoT Blockchain Service API keys.
      • Body: raw JSON (application/json) mapping. A mappings example is available in the Example route section.

Examples

The following examples are based on the sample IoT Blockchain Service supply chain IoT sample contract (iot-supplychain-network.bna) business network that is available Github.

Smart contract example

The sample smart contract data model looks like the following abbreviated example which defines a simple IoT device asset that is identified by deviceId and that contains several properties. Each of the transactions take the same required parameter object format of type deviceId.

Two transactions are shown:

Note: The full sample contract includes additional transactions.

/**
 * Sample IoT business network definition for supply chain.
 */
namespace org.poc.scbn

asset IoTDevice identified by deviceId {
  o String deviceId
  o String description optional
  o DateTime date optional
  o DateTime time optional
  o Double altitude optional
  o Double accelX optional
  o Double accelY optional
  o Double accelZ optional
  o Double latitude optional
  o Double longitude optional
  o Double temperature optional
  o Double humidity optional
  o Integer eventCode optional
  o String shipmentId optional
  --> SupplyChainParticipant participant optional
}

participant SupplyChainParticipant identified by email {
  o String email
  o String name
}

transaction CreateIoTDevice {
  o String deviceId
  o String description optional
  o DateTime date optional
  o DateTime time optional
  o Double altitude optional
  o Double accelX optional
  o Double accelY optional
  o Double accelZ optional
  o Double latitude optional
  o Double longitude optional
  o Double temperature optional
  o Double humidity optional
  o Integer eventCode optional
  o String shipmentId optional
  --> SupplyChainParticipant participant optional
}

transaction IoTDeviceReading {
  o String deviceId
  o String description optional
  o DateTime date optional
  o DateTime time optional
  o Double altitude optional
  o Double accelX optional
  o Double accelY optional
  o Double accelZ optional
  o Double latitude optional
  o Double longitude optional
  o Double temperature optional
  o Double humidity optional
  o Integer eventCode optional
  o String shipmentId optional
  --> SupplyChainParticipant participant optional
}

...

event LogInfoEvent {
  o String message
  o String payload
}

Incoming payload example

An operational payload from an IoT device that is sending a temperature reading might look like this:

{
    "jsonString": {
      "deviceId": "device1",
      "temperature": -1.1,
      "humidity": "83.0",
      "latitude": 123,
      "longitude": 456
    }
}

Outgoing payload example

For Hyperledger Composer transactions, the transaction class, consisting of name space plus transaction class name, for the transaction provides the actual routing to the specific API which is implemented in JavaScript to match the defined transaction data model format. In this case, the transaction class for creation would be constant.org.poc.scbn.CreateIoTDevice.

An outgoing payload, with only the deviceId parameter included might look like this for CreateIoTDevice:

{
  "$class": "constant.org.poc.scbn.CreateIoTDevice",
  "iotsensor_device": {
    "deviceId": "device1"
    }
}

This transaction creates an IoTDevice asset on the blockchain but doesn't include any associated data. Data can be added to the blockchain later by using the IoTDeviceReading transaction.

Route example

The following sample mapping route is included with the Postman IoTBC_Customer.postman_collection.json collection that is available from Github.

Notes

{
  "deviceType": "iotsensor_device",
  "eventId": "CreateIoTDevice",
  "fabricName": "k8sFabric",
  "dataMap": [
    {
      "output": "json",
      "mappings": [
        {
          "deviceKey": "$class",
          "chaincodeKey": "$class",
          "required": true,
          "default": "org.poc.scbn.CreateIoTDevice"
        },
        {
          "deviceKey": "server.uuid",
          "chaincodeKey": "transactionId",
          "required": false
        },
        {
          "deviceKey": "deviceId",
          "chaincodeKey": "deviceId",
          "required": true
        },
        {
          "deviceKey": "description",
          "chaincodeKey": "description",
          "required": false
        },
        {
          "deviceKey": "date",
          "chaincodeKey": "date",
          "required": false
        },
        {
          "deviceKey": "time",
          "chaincodeKey": "time",
          "required": false
        },
        {
          "deviceKey": "altitude",
          "chaincodeKey": "altitude",
          "required": false
        },
        {
          "deviceKey": "accelX",
          "chaincodeKey": "accelX",
          "required": false
        },
        {
          "deviceKey": "accelY",
          "chaincodeKey": "accelY",
          "required": false
        },
        {
          "deviceKey": "accelZ",
          "chaincodeKey": "accelZ",
          "required": false
        },
        {
          "deviceKey": "humidity",
          "chaincodeKey": "humidity",
          "required": false
        },
        {
          "deviceKey": "latitude",
          "chaincodeKey": "latitude",
          "required": false
        },
        {
          "deviceKey": "longitude",
          "chaincodeKey": "longitude",
          "required": false
        },
        {
          "deviceKey": "eventCode",
          "chaincodeKey": "eventCode",
          "required": false
        },
        {
          "deviceKey": "shipmentId",
          "chaincodeKey": "shipmentId",
          "required": false
        },
        {
          "deviceKey": "temperature",
          "chaincodeKey": "temperature",
          "required": false
        },
        {
          "deviceKey": "timestamp",
          "chaincodeKey": "timestamp",
          "required": true,
          "default": "server.timestamp"
        },
        {
          "deviceKey": "participant",
          "chaincodeKey": "participant",
          "required": false
        }
      ]
    }
  ],
  "notification": false
}

A notification configuration section might look like this:

HTTP:

"notification":
{
  "notifyName": "{endpoint}",
  "notifyAssetUpdate": true,
  "notifySettlement": true,
  "notifyContractEvent": true
}

Where {endpoint} is the name of the endpoint that you created.