Getting started with IoT Blockchain Service

IoT Blockchain Service lets you easily add transactions from IoT devices to a blockchain in a trusted and secure manner.

Before you begin

Before you can start posting your IoT device data to a blockchain ledger, your environment must meet the following requirements:

• Your IoT Blockchain Service organization is up and running and is ready to configure.
• A Hyperledger Fabric instance is configured and running.
  Supported environments include IBM Blockchain Platform and Hyperledger Fabric. You can follow the process as documented in the Quick start tutorial to create a Hyperledger Fabric instance.
  Important: IoT Blockchain Service requires unique channel names across the blockchain fabrics that are used by your IoT Blockchain Service organization.
• Hyperledger Composer is running in a Kubernetes or Local environment.
  Hyperledger Composer is used to access and configure your Hyperledger Fabric instance. In addition to other Hyperledger Fabric actions, with IoT Blockchain Service you use Hyperledger Composer to create fabric definitions and routes. If your IBM Blockchain environment already includes Hyperledger Composer, you can use that instance. If not, you can follow the process in the Quick start tutorial to install Hyperledger Composer.
• A smart contract is deployed on your Hyperledger Fabric instance.
  IoT Blockchain Service requires Hyperledger Composer-based smart contracts. To use the IoT Blockchain Service sample contract, follow the process as documented in the Quick start tutorial.
  Note: Writing and testing smart contracts are beyond the scope of this documentation.
• IoT devices that are providing IoT data that you want to place in your blockchain ledger, or make actionable using a smart contract.
  To use the Node-RED device simulator to get started, follow the process in the Quick start tutorial.
• If your IoT device data is routed through an IoT platform, your IoT platform must have a mechanism for calling the IoT Blockchain Service REST API.
  For a Node-RED flow example that consumes Watson™ IoT Platform Service connected device data, see the sample MQTT Listener Node-RED Application on GitHub.

Tip: If you are a developer who is new to working with IoT Blockchain Service, you can use the step-by-step processes in the Quick start tutorial section.

About this task

The following steps walk you through how to quickly get started with IoT Blockchain Service to securely write IoT data to a blockchain.

Step 1 - Create your IoT Blockchain Service organization API key

The first step in connecting to and using IoT Blockchain Service to invoke transactions on your blockchain is to use the IoT Blockchain Service dashboard to create an IoT Blockchain Service API key for your IoT Blockchain Service organization. This key is used in all API activity and is used by all applications that invokes the IoT Blockchain Service REST API.

Important: Each IoT Blockchain Service organization is associated with one unique API key. Ideally, creating an API key is a one-time task. If you create a new API key, the existing one is discontinued and no longer works.

1. On the IoT Blockchain Service login page, click Launch and log in with your IBMid.
2. In the IoT Blockchain Service user interface, on the API Keys tile, click Generate a new API key and then click Proceed.
3. Copy and save the API key.

Step 2 - Create a fabric definition and default passthrough route for your Hyperledger Fabric instance

For IoT Blockchain Service to be able to communicate with your Hyperledger Fabric instance, you must add a fabric definition. The fabric definition includes information such as Hyperledger Fabric instance URLs, business network name, and more. As part of creating the fabric definition with the Hyperledger Composer ID card, an initial passthrough route is also created.

All interactions with your blockchain ledger via IoT Blockchain Service takes place using a route. The route maps incoming data to existing attributes in your smart contract and lets you invoke transactions on the blockchain.

Note: A passthrough route passes the unmodified payload directly to the blockchain. Routes can also use strict parameter mapping where you can select the properties that get passed on. For more information on how to create additional parameter mapping routes, see the Managing IoT Blockchain Service routes topic.

1. Import the Composer ID card.
   1. Open your Hyperledger Composer at:
      http://<public_IP>:31080
   2. Under Identity cards for hlfv1, find the card that corresponds to your business network.
   3. Click the download icon on the card to download the ID card.
2. Create the fabric definition and default passthrough route.
   1. In the IoT Blockchain Service dashboard, select the Blockchain Routes tile, click Existing Blockchain Definitions.
   2. Import the Hyperledger Composer ID card that you downloaded earlier by clicking Composer ID Card. If asked for an IP address, use the public IP address of your Kubernetes cluster.
   3. In the New Fabric and Route dialog box, provide a default route name and a short description. Supply a Blockchain Fabric Name and verify that the route is set to the default Pass-Through.
   4. Verify that the Composer Type corresponds to the version of Hyperledger Composer that you used to create the card.
   5. Select the Notification options that you want to use.
      Tipe: If you do not have any notification URL defined, select No notifications. For more information, see the Route components topic.
   6. Click Create New Route. The newly created fabric definition and default route is added to the Blockchain Routes table.

Step 3 - Verify that IoT events trigger smart contract blockchain transactions

To execute smart contract transactions on your blockchain, an application or IoT device must send events to the IoT Blockchain Service REST API. For more information, see the Transactions API documentation.

1. Make a manual transaction REST API call.
   The REST API call to use is defined by the route name. For example, for the route name myRoute, the REST call would be:
   POST https://iot-blockchain.ibm.com/api/v1/<your_org>/tx/appType/instance1/myRoute
   Where:
   • <your_org> is your IoT Blockchain Service org ID.
   • The body of the POST is the JSON payload that is expected by your contract.
2. View the blockchain from your Hyperledger Composer to see that new transactions were added to the blockchain.
   1. In your Hyperledger Composer, click Connect on the block that represents the contract that you deployed earlier.
   2. Select the Test tab and click All Transactions to see the latest transactions. Check for your IoT device reading sample transactions.
      Tip: If you don't see your transaction, you might need to reload the Hyperledger Composer user interface to refresh the connection.

What's next?

In a production IoT environment, an application would send actual IoT data from your devices for routing to the blockchain by IoT Blockchain Service.

For a Node-RED flow example that consumes Watson™ IoT Platform Service connected device data, see MQTT Listener Node-RED Application on GitHub.

Import the flow text to your Node-RED flow editor, and then follow the embedded instructions to configure the flow for your Watson™ IoT Platform Service and IoT Blockchain Service environments.