| copyright | lastupdated | ||
|---|---|---|---|
|
2017-10-18 |
{:new_window: target="_blank"} {:shortdesc: .shortdesc} {:screen: .screen} {:codeblock: .codeblock} {:pre: .pre}
{: #gettingstartedtemplate}
{{site.data.keyword.iot_short_notm}} blockchain integration enables IoT devices to provide data to blockchain transactions, which stores the data in the blockchain's immutable ledger and uses it in the business rules that are implemented in the blockchain's smart contracts. {:shortdesc}
The platform takes device data in its native MQTT format, maps it to the data format that is required by the blockchain's smart contract, and passes it to a blockchain fabric to store in the blockchain ledger. A blockchain fabric is the collection of peer and certification nodes that make up an instance of {{site.data.keyword.blockchainfull}} and Hyperledger.
{: #architecture}
A generic {{site.data.keyword.iot_short_notm}} blockchain integration environment consists of the following components:
- One or more devices that produces data that you want to write into a blockchain ledger.
- {{site.data.keyword.Bluemix_notm}} organization:
- {{site.data.keyword.iot_short_notm}} service with IoT blockchain integration enabled.
- {{site.data.keyword.blockchainfull_notm}} or Hyperledger fabric with one or more smart contracts deployed.
- Local environment:
- IoT Blockchain Monitoring UI
For information about the setup and requirements for an extended environment for producing and deploying smart contracts, see Developing smart contracts for {{site.data.keyword.iot_short_notm}} blockchain integration.
The following diagram illustrates the general {{site.data.keyword.iot_short_notm}} blockchain integration environment.
{: #byb}
- Get an overview of {{site.data.keyword.iot_short_notm}}, how it relates to the general blockchain concept, and what it can do for you at {{site.data.keyword.iot_short_notm}}
{: new_window} on IBM.com. - Enable {{site.data.keyword.iot_short_notm}} blockchain integration for your organization.
- Connect devices that produce data that you want to write to the blockchain ledger.
Follow the instructions in the Connecting devices topic to connect your devices. - Install the Monitoring UI.
The Monitoring UI is used to verify the connection between {{site.data.keyword.iot_short_notm}} and the blockchain fabric. Follow the instructions in the Monitoring UI readme document that is available in the Blockchain Monitoring UI {: new_window} GitHub directory.
To quickly get started with testing {{site.data.keyword.iot_short_notm}} blockchain integration, you can connect to an IBM-provided fabric and map a Node-RED sample device to the IBM-provided sample contract. The steps required for this scenario are labeled IBM basic scenario in this topic.
Important: Be aware that the IBM-provided sample blockchain ledger and all its data is visible to all users of the sample blockchain. Do not store any sensitive information in the IBM-provided sample blockchain. In addition, sample fabrics that support the sample and trade lane contracts are subject to change, including the connection info for each peer. The connection details are provided in the IoT Blockchain Connection Info {: new_window} wiki page in the Watson IoT Blockchain community.
The IBM-provided basic {{site.data.keyword.iot_short_notm}} blockchain integration environment consists of the following components:
- {{site.data.keyword.Bluemix_notm}}:
- {{site.data.keyword.iot_short_notm}} service with IoT blockchain integration enabled
- Optional: Node-RED application running IoT device simulator
Note: The device simulator can also be deployed in a local Node-RED environment. - Local environment:
- Node.js
- IoT Blockchain Monitoring UI
- IBM provided:
- Optional: {{site.data.keyword.iot_short_notm}} fabric with a pre-deployed simple smart contract.
The following architecture diagram illustrates the components that are required for this sample scenario.
IBM basic scenario: Create a Node-RED device simulator by following the instructions in the Creating and connecting a Node-RED device simulator topic. For blockchain integration, use the blockchain device-specific node information when you import the node data. The node information is available in the Node-RED Device Simulator {: new_window} wiki page in the Watson IoT Blockchain Community. If needed, contact your IBM blockchain contact to get access to the community.
{: #getting_started}
Because {{site.data.keyword.iot_short_notm}} blockchain integration is enabled, you can now connect to blockchain fabrics that are hosted by {{site.data.keyword.blockchainfull_notm}} or the Linux Foundation Hyperledger.
To connect to a blockchain fabric:
- From the {{site.data.keyword.iot_short_notm}} dashboard, select Extensions.
- In the Extensions page, in the Blockchain tile, click Setup.
- In the Extensions page, in the Blockchain tile, click Setup, or click
if you already have fabrics linked, and then enter the fabric information. - In the Fabric tab, enter a name to identify the fabric in {{site.data.keyword.iot_short_notm}}, then click Next.
- In the Peer tab, enter the peer information:
| Parameter | Value |
|---|---|
| Name | Enter a name to identify the peer in {{site.data.keyword.iot_short_notm}}. |
| Host | The `api_host` address for the Validating Peer 1 server |
| Port | The `api_port` number
|
| User ID | The `username` string for the user that was used to register the smart contract with the blockchain. You also use this user ID when you later configure the Simple UI. |
| Secret Key | The `secret` string for the user |
| Use TLS | On or Off Use Transport Layer Security to encrypt the communication between {{site.data.keyword.iot_short_notm}} and the contract in the fabric. The default port numbers are set by the deployed {{site.data.keyword.iot_short_notm}} instance that you are connecting to. |
IBM basic scenario: To connect to the IBM-provided fabric, use the connection details for the Sample Contract that are provided in the IoT Blockchain Connection Info {: new_window} wiki page in the Watson IoT Blockchain community. If needed, contact your IBM blockchain contact to get access to the community.
{: #map_device_properties}
To write device data to the blockchain ledger, you must first map the device properties for a device type to the parameters that are defined by the smart contract.
To map device data to a contract:
- From the {{site.data.keyword.iot_short_notm}} dashboard, click
in the menu side bar. - Click Map Device Data.
- Select the device type for which you want to store device data in the blockchain.
- Enter the event name for the events that you want to store.
Tip: The default event name for the sample Node-RED blockchain device is obc. To find the event types for a device, from the {{site.data.keyword.iot_short_notm}} dashboard, select Devices and click the device name to open the device details page. Scroll down to the Sensor Information section to see a list of the available events and data points for the device. You can change the event name that the Node-RED device publishes by updating the Topic field in the Publish to IoT mqtt out node. - Click Next.
- Select the fabric instance that you created earlier.
- Enter a contract name and the contract ID.
| Parameter | Comment |
|---|---|
| Contract name | A name that is used to identify the contract in {{site.data.keyword.iot_short_notm}}. |
| Contract ID | The unique 128-character ID of the mapped contract. **Important:** The contract that you map must at a minimum support the following methods: - updateAsset - readAssetSchemas |
- Create a route to map device properties to contract parameters.
The parameters that are available in the contract are imported. For each parameter, enter a corresponding event property.
Important: Do not include thed.that is prepended to the data point in the device message. IBM basic scenario: If you are using the IBM-provided contracts, map the following parameters that are listed in the Data mapping{: new_window} wiki page in the Watson IoT Blockchain community. If needed, contact your IBM blockchain contact to get access to the community. - In the summary page, verify that all information was entered correctly.
- The device data to contract mapping is displayed in the Blockchain page.
Congratulations, you are now up and running!
{: #test_simple}
If you are connected to the IBM-provided fabric and mapped your device data to the sample contract, you can test the end-to-end data flow from the device to the blockchain ledger. Use the IoT Blockchain Monitoring UI to view the blockchain activity and data for your assets.
Tip: If the Monitoring UI is not yet installed in your local environment, you can install it now. Follow the instructions in the Monitoring UI readme document that is available in the Blockchain Monitoring UI {: new_window} GitHub directory.
- Configure the Monitoring UI to connect to {{site.data.keyword.iot_short_notm}}.
In the Monitoring UI, click CONFIGURATION to configure the Monitoring UI connection:
| Parameter | Comment |
|---|---|
| API Host and Port | The host and port for the {{site.data.keyword.iot_short_notm}} REST API that is prepended with `http://`. Use the `api_host` address and `api_port` number. |
| Chaincode ID | The contract ID is a 128-character alphanumeric string that corresponds with the Contract ID entry. **Important:** When you cut and paste the chaincode ID, make sure that no spaces are included in the ID. If the ID is incorrectly entered, the the blockchain ledger entries are displayed, but the asset search function does not work. |
| Secure Context | This parameter is required for connecting to {{site.data.keyword.iot_short_notm}} instances on {{site.data.keyword.Bluemix_notm}}. Use the secureContext entry. **Important:** The secureContext should be an authorized user of the fabric, defined when you created the fabric. |
{: #next_steps}
You have now installed and configured a basic IoT blockchain integrated {{site.data.keyword.iot_short_notm}} environment. In this minimal scenario, the basic smart contract lets you write device data to the blockchain ledger to create an indelible device data history. Now that you completed these initial steps and tested the simple contract, you can try the more advanced trade lane sample contract and write your own contracts.
Instructions for these more advanced steps are provided in the Developing smart contracts for {{site.data.keyword.iot_short_notm}} blockchain integration topic.