IoT Blockchain Service quick start

In this quick start tutorial, we cover the steps to install and deploy the required software: IBM Blockchain Platform.

We also show how to import and deploy the sample IoT contract by using the Hyperledger Composer CLI and how to configure IoT Blockchain Service.

Finally, we guide you through the steps that are required to set up Node-RED as a device simulator and start writing device data to blockchain.

Step 1: Verify your IoT Blockchain Service SaaS Service

Before you can start, verify that your IoT Blockchain Service organization is up and running and is ready to configure.

Navigate to the IoT Blockchain Service login page.
Click Launch and log in with your IBMid. This action takes you to the IoT Blockchain Service user interface.

You will use the IoT Blockchain Service user interface to create a fabric definition and a default route as part of this tutorial.

Step 2: Deploy or install the required supporting software

Installed as part of this getting started example:

IBM Blockchain Platform

Required for this getting started example:

Node.js versions 6.x or higher.
Node-RED: Deploy a new instance or use an existing instance. Node-RED can run locally, or you can deploy it on IBM Cloud.
Note: If you choose to run Node-RED locally, you will need to install the latest ibmiot node for the Using REST and IBM Watson™ IoT Platform Service with IoT Blockchain Service tutorial.
Hyperledger Composer: Install the Hyperledger Composer CLI using npm install -g composer-cli@0.19.5 for IBM Blockchain Platform Enterprise Edition or npm install -g composer-cli@0.20.0 for IBM Blockchain Platform Starter Edition.

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

The Watson IoT Platform Service quick start architecture. This graphic is explained in the surrounding text.

Step 3: Get started with IoT Blockchain Service

Important:

Make sure that you install the supported version of Hyperledger Composer CLI:
- Hyperledger Composer CLI 0.20.x for contracts deployed to IBM Blockchain Platform Starter Edition (based on Hyperledger Fabric 1.2).
- Hyperledger Composer CLI 0.19.5 for contracts deployed to IBM Blockchain Platform Enterprise Edition (based on Hyperledger Fabric 1.1).

To deploy the required software:

Provision an instance of IBM Blockchain Platform Starter Edition or IBM Blockchain Platform Enterprise Edition in IBM® Cloud.
Download the IoT Blockchain Service IoT supply chain sample contract (iot-supplychain-network.bna) business network archive file from Github.
Install the contract.
1. In your Starter or Enterprise IBM Blockchain Platform instance, navigate to My Code > Develop Code > Deployment Guide.
2. Follow the instructions with the following modification.
  In Step One: Retrieve admin secret, check if your connection-profile.json file includes more than one channel. If so, edit the file to include only the single channel that you will deploy your contract to as a part of Step Five: Installing and starting the business network in the instructions.
  The following example illustrates a correctly configured channels entry in a connection-profile.json file. Your channel name, peers and channel members might vary.
```
  "channels": {
       "test-channel2": {
           "x-status": "membership_valid",
           "orderers": [
               "orderer"
          ],
           "peers": {
               "org1-peer1": {
                   "x-chaincode": {}
               }
           },
           "chaincodes": [],
           "x-members": [
               "org1"
           ]
       }
 },
```
  This step is necessary to ensure that IoT Blockchain Service connections to your contract are successful.
3. Continue with the instructions to install the iot-supplychain-network.bna contract that you downloaded.
  Take note of the location of the admin@iot-supplychain-network card that you create during those steps, as you will need that card to configure IoT Blockchain Service.
Configure IoT Blockchain Service.
Create an API key and use a Hyperledger Composer Business Network Card to configure a IoT Blockchain Service route.
1. Navigate to the IoT Blockchain Service login page.
2. Click Launch and log in with your IBMid. This action takes you to the IoT Blockchain Service user interface.
3. View the API Keys tile and record your organization ID.
4. Create an API key.
  1. In the API Keys tile, click Generate New API Key to navigate to the API Key page.
    Important: If you previously created an API key, that key is no longer valid when you create a new key.
  2. Click Generate New API Key.
  3. Copy and save the newly created API key and then click OK.
5. Create a blockchain fabric definition and route.
  A route is a mapping of device attributes to contract attributes. For information about using the API to create a route, see Managing IoT Blockchain Service routes.
  1. In the Organization and Blockchain Routes tile, click Manage Fabric Definitions.
  2. Click Select a Composer ID Card to import the Business Network Card that you created earlier.
  3. Supply the Route Name IoTDeviceReading and the Blockchain Fabric Name blockchain1. Supply a short description.
  4. Select the Composer version you are using.
  5. 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.
  6. For notification, select No Notification.
  7. Click Create New Route.
Configure Node-RED to send simulated device data to IoT Blockchain Service.
Use Node-RED to simulate a device.
1. Download the Node-RED Sample Application Node-RED flow from Github.
2. Open the file and then 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 imported flow, double-click the post-to-iot-blockchain node.
6. Add your organization to the URL by replacing <your_org> with the organization ID that you recorded as part of the Configure IoT Blockchain Service. step.
7. Select use basic authentication.
8. Set the Username field to the value use-token-auth.
9. Update the Password field with the IoT Blockchain Service API key that you recorded earlier.
10. Make sure Enable secure (SSL/TLS) connection is checked.
11. Click Done.
12. Deploy the updated Node-RED flow.
  Important: If you edit the Post to IoT Blockchain node in the future, you must provide the API Key again. Don't assume that the ******* value you see is the key 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.
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 quick start environment is now up and running!

What's next?

Continue with the Using REST and IBM Watson™ IoT Platform Service with IoT Blockchain Service topic to learn how to connect a simulated device to Watson IoT Platform Service, take advantage of analytics and device management, use Postman to manually configure IoT Blockchain Service with the IBM-provided postman collection, and store your IoT device data in a blockchain.