Using REST and IBM Watson™ IoT Platform Service with IoT Blockchain Service

In the following topic we go over the steps to deploy IBM Watson™ IoT Platform Service, import and deploy a supply chain sample IoT contract, use Postman to manually configure IoT Blockchain Service with the IBM-provided postman collection, set up Node-RED to send device data to Watson™ IoT Platform Service and finally configure Watson™ IoT Platform Service to store your IoT device data in a blockchain.

Before you begin

Before you start you must complete the steps in the IoT Blockchain Service quick start guide, and verify that your blockchain transactions show up in IBM Blockchain Platform.

Step 1: Deploy or install the required supporting software

Installed as part of this getting started example:

Postman

Previously deployed as part of IoT Blockchain Service quick start

IBM Blockchain Platform
Hyperledger Composer CLI
Node-RED

Required for this getting started example:

Watson IoT Platform Service
Use an existing Watson IoT Platform Service organization, for example the instance that might be included with IBM® Watson™ IoT Platform, or deploy a new instance.
Tip: You can create an Watson IoT Platform Service instance directly from the Watson IoT Platform Service page in the IBM Cloud Services Catalog. For more information, see the Getting started with Watson IoT Platform Service topic in the Watson IoT Platform Service documentation.

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

The Watson IoT Platform Service REST and Watson IoT Platform Service architecture. This graphic is explained in the surrounding text.

Step 2: Get started with IoT Blockchain Service and Watson™ IoT Platform Service

Configure IoT Blockchain Service and Watson™ IoT Platform Service. With that done, use the Node-RED device simulator to writing device data to blockchain.

Utilize the sample contract previously deployed and locate the admin@iot-supplychain-network card you created as part of IoT Blockchain Service quick start.
Create a fabric definition in IoT Blockchain Service.
Import a Hyperledger Composer Business Network Card to create an IoT Blockchain Service fabric definition for IoT Supply Chain Business Network.
1. Go to the IoT Blockchain Service login page at: https://iot-blockchain.ibm.com/#.
2. Click Launch and log in with your IBMid. This action takes you to the IoT Blockchain Service user interface.
3. In the Organization and Blockchain Routes tile, click Manage Fabric Definitions to work with your fabric and route definitions.
4. Click Select a Composer ID Card and import the Hyperledger Composer Business Network Card that you downloaded earlier.
5. Provide any route name, any short description, and provide the fabric name k8sFabric.
6. Select the Composer version you are using.
7. If you selected Composer v0.16.x enter the public IP address. If you selected Composer v0.19.x or Composer v0.20.x skip this step.
8. Select No Notification as you will not need IoT Blockchain Service notifications for this exercise.
9. Click Create New Route.
Configure IoT Blockchain Service via Postman.
Use Postman to manually configure IoT Blockchain Service with the IBM®-provided postman collection.
Important: To access the IoT Blockchain Service API with Postman, use Basic Auth with the fixed user name use-token-auth and the API key that you created as part of the IoT Blockchain Service quick start as password.
1. Set up Postman.
  Download and install Postman at: https://www.getpostman.com.
2. Import the Postman collection.
  1. Download the IoTBC_Customer.postman_collection.json collection file from Github.
  2. In Postman, click Import and then import the file that you just downloaded.
3. Create a Postman environment.
  1. In Postman, select Environment options > Manage Environments, then click Add.
  2. Add a descriptive environment name, such as Blockchain.
  3. Click Bulk Edit.
  4. Paste the following sample and replace <organization_id> and <your_api_key> with the information for your environment:
```
iotbc_url:https://iot-blockchain.ibm.com  
org:<organization_id>  
user:use-token-auth  
api:api/v1/{{org}}  
pass:<your_organization_api_key>
```
  5. Click Add to create the environment.
4. Display your IoT Blockchain Service fabric definition.
  Use Postman to list the IoT Blockchain Service fabric definition that you created when you loaded your Hyperledger Composer ID card. This fabric definition lets IoT Blockchain Service connect to your deployed Hyperledger Fabric instance.
  1. To check your submission, select the GET all fabrics REST call under the Fabrics section of the Postman Collections.
  2. Click Send to get a list of all fabrics.
5. Configure IoT Blockchain Service route definitions.
  Use Postman to create a route definition in IoT Blockchain Service to map your data from your IoT device or application to your deployed contract. Because you are using the IoT Blockchain Service supply chain IoT sample contract (iot-supplychain-network), you can use the POST new route iot-device-create and POST new route iot-device-reading REST calls under the Routes section without changes.
  1. Select POST new route iot-device-create and click Send to submit the route to IoT Blockchain Service.
  2. Select POST new route iot-device-reading and click Send to submit the route to IoT Blockchain Service.
  3. To check your submission, select the GET all routes REST call under the Routes section of the Postman Collections.
  4. Click Send to get a list of all routes.
Create a device type, device and API key in Watson™ IoT Platform Service.
1. Open your Watson™ IoT Platform Service dashboard.
2. Create a device type and register your IoT device with Watson™ IoT Platform Service.
  For more details on this step, see Connecting Devices in the Watson™ IoT Platform Service documentation.
  Important: Record the device type, device ID and device token for your registered device. You will need this information later when you configure your Node-RED device simulator.
  Use the following device information for this example:
  - Device type: iotsensor_device
  - Device ID: iotsensor
3. Create an API key with the Device Application role.
  For more details on this step, see Connecting Applications in the Watson™ IoT Platform Service documentation.
  Important: Record the API key and API token. You will need this information later when you configure your Node-RED MQTT Listener.
Configure Node-RED to send simulated device data to Watson™ IoT Platform Service.
1. Navigate to the Node-RED flow in Github.
2. Select and copy all the text.
3. Open the Node-RED flow editor.
4. From the Node-RED menu, select Import > Clipboard and paste the selected text then click Import.
5. In the flow, select the Post to IoT Blockchain node and replace <your_org> in the URL with your IoT Blockchain Service org ID.
6. In the flow, double-click the Publish to IoT node.
7. Click the edit icon next to the Server field.
8. Update the Server name to correspond to your IoT Platform organization.
  {org_ID}.messaging.internetofthings.ibmcloud.com
9. Make sure Enable secure (SSL/TLS) connection is checked. Where {org_ID} is the six character ID of your Watson™ IoT Platform Service organization.
10. Update the Client ID with your organization ID, device type, and device ID:
  d:<organization_id>:iotsensor_device:iotsensor
11. Select the Security tab.
12. Verify that the Username field has the value use-token-auth.
13. Update the Password field with the Watson™ IoT Platform Service device token that you saved earlier.
14. Click Update and then OK.
15. Deploy the updated Node-RED flow.
  Important: If you edit the Security tab settings in the future, you must provide the Authentication Token again. Don't assume that the ******* value that you see is the token that you previously provided. If you click Update without correcting this field, your Node-RED flow will fail. If you open this node to view the information, be sure to click Cancel.
Configure Node-RED to listen for IoT device messages from Watson™ IoT Platform Service and send those messages to IoT Blockchain Service.
1. Navigate to the Node-RED flow in Github.
2. Select and copy all the text.
3. Open the Node-RED flow editor.
4. From the Node-RED menu, select Import > Clipboard and paste the selected text then click Import.
5. In the flow, edit the Post to IoT Blockchain node and replace <your_org> entry in the URL field with your IoT Blockchain Service org ID.
6. Select to use basic authentication.
7. Set the Username field to the value use-token-auth.
8. Update the Password field with the IoT Blockchain Service API key that you recorded earlier.
9. Make sure Enable secure (SSL/TLS) connection is checked.
10. Click Done.
11. In the flow, edit the IBM IoT MQTT Listener node.
12. Click the edit icon next to the API Key field.
13. Provide your Watson™ IoT Platform Service API key in the API Key field.
14. Provide your Watson™ IoT Platform Service authentication token in the API Token field.
15. Replace the <your_org> entry in the Server-Name field with your Watson™ IoT Platform Service org ID.
  Important: If you edit the Post to IoT Blockchain or IBM IoT MQTT Listener nodes in the future, you must provide the API Key or API Token again. Don't assume that the ******* value that you see is the API key or token that you previously provided. If you click Update without correcting these fields, your Node-RED flow will fail. If you open these nodes to view the information, be sure to click Cancel.
Send a transaction to IoT Blockchain Service from Node-RED.
1. Open the Node-RED flow editor.
2. Click the injector button in your Create Device iotsensor node to send a CreateIoTDevice message to the blockchain.
  Tip: A device only needs to be created once in Hyperledger Composer.
3. Click the injector button in your Send Device Reading iotsensor node to send an IoTDeviceReading message to the blockchain.
View your data in the blockchain.
View the blockchain from the IBM Blockchain Platform Monitor application in IBM Cloud to see that a new transaction was added to the blockchain.
1. Open your IBM Blockchain Platform Starter or Enterprise service instance in IBM Cloud and start the Monitor app.
2. Navigate to Channels then double-click on the channel you created when you deployed the composer contract.
3. View the details of the latest block in the blockchain.

Congratulations, your IoT Blockchain Service and Watson™ IoT Platform Service getting started environment is now up and running! Happy blockchaining!