Asset Tracking with Blockchain and IoT

🚧🚧🚧 This pattern is currently being updated - it uses depracated components. Use at your own risk! 🚧🚧🚧 In this pattern, we will be creating a local Hyperledger Fabric network using the IBM Blockchain Platform extension for VSCode which makes it easy to start developing smart contracts.

The solution that we will be creating is an asset lifecycle and tracking solution that keeps a record of the asset from creation to deletion. Also, we will be creating and managing asset leases which keep track of the lease terms in a lease agreement such as end date, price, and deposit amount.

For the IoT integration, we will be leveraging the IBM Watson IoT Platform to handle device scanning at various locations as the asset is being transferred. Instead of having an actual physical device, we will be creating a web app pretending to be a device which will trigger these scans and notify a locally node.js app to invoke the updateAssetLocation transaction.

After completing this pattern you will understand how to:

• Deploy smart contracts to a local Hyperledger Fabric network
• Create a simulated IoT device using the IBM Watson IoT Platform and Node-Red
• Connect to a Hyperledger Fabric application using the Fabric SDK for Node.js
• Publish IoT events to the ledger on a device event such as a scan

Flow

1. The smart contract is deployed to a local Hyperledger Fabric network via the IBM Blockchain Platform extension for VS Code.
2. As the asset is moved from place to place it is scanned via RFID or barcode by an IoT device. In this pattern, the device is simulated.
3. The IoT device publishes an event notification to the IBM Watson IoT Platform, which then notifies all listening applications that a scan has taken place.
4. An application listening to the IBM Watson IoT Platform for scanning events then invokes a transfer transaction.
5. The location of the asset is updated in the ledger automatically.

Scenario

In this demo scenario we have three participants: a manufacturer, a vendor, and a contractor.

1. The manufacturer creates the asset and sells it to the vendor.
2. The vendor then creates a lease with the contractor which defines terms including how much deposit is to be paid and how much deposit will be returned based on the amount of damage that the asset has received during the lease duration. For example, if the asset is returned with 21% damage then only 60% of the deposit will be returned.
3. After the lease duration is over, the asset is returned to the vendor and inspected for damage. The lease is then updated to reflect the amount of damage that the asset received.
4. The asset is sent back to the manufacturer for repairs. If the vendor has a warranty to cover future repairs with the manufacturer, the manufacturer could take a look at the history of the asset and see if any activity such as imporper usage has voided the warranty.
5. The asset is then returned to the vendor to be leased out again.

Structure of Asset

The asset being stored in the ledger has the following properties:

• manufacturer - creator of the asset
• assetNumber - serial number given to the asset
• assetType - type of asset
• currentOwner - Who currently posesses the asset
• currentState - The current state of the asset
• percentDamage - The amount of damage in percent found during the inspection stage
• location - Where the asset was scanned last

Structure of the Asset Lease

The asset lease being stored in the ledger has the following properties:

• leaseNumber - Lease agreement number
• lessee - Who is receiving the lease
• lessor - Who is leasing the asset out
• assetKey - The key of the asset being leased
• dateLeased - The date the lease goes into effect
• endOfLease - The end of the lease agreement
• price - The total price of the lease payments
• depositPaid - The deposit paid up front
• dateReturned - The date the asset was returned
• percentDamaged - The condition of the asset on return displayed in percent damaged
• depositReturned - Based on the ammount of damage, the amount of the deposit returned

Prerequisites

• an IBM Cloud account
• VSCode
• The IBM Blockchain Platform extension for VSCode

Creating the Node-Red simulated device application

To start off, we are going to create the simulated IoT device which will invoke the updateAssetLocation with the location where the device was "scanned". We will be using the IBM Watson IoT Platform to facilitate the communicaton from our virtual device to a local IoT service which will be listening for published device events.

For the code used to build this virtual device, we will be using a framework called Node-Red which is a low code environment which allows for drag and drop of preconfigured nodes to easily build applications.

IBM Cloud has a starter kit for IoT applications that comes with a Node-Red application and an instance of the IBM Watson IoT Platform service already bound to it.

1. Go to IBM Cloud and log in if you haven't already
2. Click on Catalog at the top right of the page
3. From the catalog, select Starter Kits from the category list on the left side to narrow the services shown.
4. Then, find and click on the Internet of Things Platform Starter kit.

5. On the next page, give the new application a name. It's important that the name be unique so that there are no hostname conflicts with other applications out there. To make it easy, you can add your initials before the hostname (e.g. My name is Oliver Rodriguez so I might name my application or-asset-tracking).

6. Click create. This creation process will take a bit.

7. Once the application is deployed, click on Visit App URL at the top of the page to go to the application.

8. The first time you open a Node-Red application you have to go through the initial set up wizard. To start, create an admin username and password. You can also select the checkbox to give read access to anybody that visit's your app.

9. When done with the wizard you should be taken to the application. Click on the red button that says Go to your Node-RED flow editor. The page that you are brought to is called the Canvas which is where you drag and drop your nodes. The left pane that holds all the nodes is called the palette.

10. To make any changes you will need to log in with the admin account created during set up. Click on the sillouette at the top right of the page and click log in. Then, enter your username and password to log in.

You may notice that this application already comes with some starter code, go ahead and select it all with your curser by clicking and draging and then press your delete key.

10. We will be importing some of our own code for the virtual device. To do this, click on the menu button at the top right, select Import and Clipboard.

Then paste in the contents of the flow.json file from this repo and click Import.

Now that we have our flow imported, we now need to use the IBM Watson IoT Platform to facilitate communication between the virtual device and the local IoT application.

Connect with the IBM Watson IoT Platform

1. From the dashboard of IBM Cloud, click on the IBM Watson IoT Platform service. You may need to expand the Cloud Foundry services section.
2. On the overview page for the service, click on Launch

3. Once in the IoT Platform, click on the Devices button from the left navigation panel.

Create a new Device Type

4. Once in the devices page, click on Add Device at the top right of the page.
5. Click on the Device Type tab at the top left of the page.
6. Once on the new page, click on Add Device Type at the top right.
7. Then, ensure Type is Device and enter asset as the Name

8. Click Next and click Done on the next page.

Register a new device

9. On the new page, click on Register Devices

10. Next, ensure that asset is selected as the Device Type and enter A-001 as the DeviceID
11. Click Next, and then Next again on the device defaults page, and then Next again on the token generation page.
12. Click Done to complete device registration
13. Once you complete registration, you will be taken to the Device credentials page. Copy everything in the Device credentials object and save it in a seperate doc.

It's important to copy the Authentication Token as you will not be able to retrieve it once you leave the page.

Register an App

Now we need to register an application with the platform to generate an API key

1. Click on the Apps button on the left navigation panel

2. On the Apps, page, click on Generate API Key at the top right of the page.

3. Add a description if you wish, then click on Next

4. On the new page, select Standard Application as the Role

5. Click Generate Key

6. Once the API Key has been added, copy both the API Key and the Authentication Token to a seperate doc.

Again, just like with the device credentials, you cannot retrieve the token once you leave the page. Be sure to have it copied somewhere.

7. Next, take a look at the address bar of your IBM Watson IoT platform page and copy the part of the address that comes before .internetofthings.ibmcloud.com. It should be 6 characters. These character represent your IoT org. Copy them into a text document for later.

Now that we have our device reg