How to Get Started with IBM Watson IoT Containers¶

In this tutorial you will be guided through the process of setting up your device. In this case a Raspberry Pi 3 - to IBM Watson IoT. By using the IBM IoT container available on the Foundries.io Docker App Store, together with your FoundriesFactory, you will learn how to connect your device to the cloud with just a few simple commands. Before you know it, data - like CPU and RAM usage - will be flowing through the IBM Watson IoT, allowing you to easily integrate your device data with any IBM Service.

Once you install your app, you just need to load one config file over fioctl and the device will start to send important system information to IBM Watson IoT. In this tutorial we’re assuming that you already have an IBM Watson IoT Account and your Raspberry Pi 3 is already connected to your FoundriesFactory.

IBM Configuration¶

For the purposes of this tutorial we will begin by completing the necessary steps to configure IBM IoT and next we will configure and enable the IBM IoT container using FoundriesFactory.

Create your Resource¶

First, we need to create resource.

Go to: “IBM Dashboard” page.

At the top right of the window, click on “Create resource”.

Create Resource¶

Search for “internet of things” and select the “Internet of Things Platform” box.

Internet of Things Platform¶

On the next window make sure that the Lite (free) plan is selected and click on the Create button.

Project Name¶

You should now see the “Internet of Things Platform-te” page.

Click on “Launch”

Internet of Things Platform-te¶

Create Device¶

Now we are ready to create our first device. We are using the Raspberry Pi 3B for our demonstration but you may use any LmP device for the rest of this tutorial.

On the Browse Devices window click on the “Create a device” button.

Create a device¶

In the “Add Device” dialog, enter your “Device Type”. In my case, I will use: RPi3B

Enter your “Device ID”. In my case, I will use: 0001

Click on “Next”.

Add Device¶

In the “Device Information”, all fields are optional. In my case, I will complete at least model and location:

Device Information¶

In the “Security”, we will use “Auto-Generated authentication token”.

Click on “Next”

Auto-Generated authentication token¶

Finally in the “Summary”, click on “Finish”

Add device summary¶

After finishing the device creation, you will see important information.

Save the “Organization ID”, “Device Type”, “Device ID” and the “Authentication Token”

FoundriesFactory¶

Cloning your repository¶

To interact with your FoundriesFactory you’ll first need to download the necessary repositories, change the code and send it back to the server.

First, navigate to Foundries App, find your Factory and the source code.

Device activation page¶

Open the container repository and clone it on your host machine:

# Ubuntu Host Machine
$ mkdir getstartedvideo
$ cd getstartevideo
$ git clone https://source.foundries.io/factories/getstartedvideo/containers.git/
$ cd containers

In order to enable IBM IoT app we will need to clone some files from our reference repository:

# Ubuntu Host Machine
$ git remote add fio https://github.com/foundriesio/extra-containers.git
$ git remote update
$ git checkout remotes/fio/master -- ibm-iotsdk

Edit the docker compose app file and update the Factory name:

# Ubuntu Host Machine
$ vim ibm-iotsdk/docker-compose.yml

ibm-iotsdk/docker-compose.yml:

# ibm-iotsdk/docker-compose.yml
version: "3"
services:
  ibm-iotsdk:
    image: hub.foundries.io/<YOUR_FACTORY_NAME>/ibm-iotsdk:latest
    tmpfs:
        - /run
        - /var/lock
        - /var/log
    volumes:
        - /var/run/secrets:/config
    tty: true
    network_mode: "host"
    privileged: true
    restart: always

Add the changes to your Factory and wait for it to finish compiling your app:

# Ubuntu Host Machine
$ git add ibm-iotsdk/
$ git commit "Adding new ibm-iotsdk app"
$ git push

Building App¶

Enabling the App on your Device¶

In the following steps we assume you have your Raspberry Pi 3 with Foundries.io’s LmP running and correctly registered to your Factory.

With fioctl, we will enable the application “ibm-iotsdk” on your device registered with the name raspberrypi3. For more information about how to register and enable application, check the page Managing the Device:

# Ubuntu Host Machine
# Configure the device to run the "ibm-iotsdk" app
$ fioctl devices config updates raspberrypi3 --apps ibm-iotsdk --tags master

On your Raspberry Pi, you should receive the update soon. You can watch the logs by running the following commands:

# Ubuntu Host Machine
$ ssh [email protected]
# Raspberry Pi 3 Target Machine
$ sudo journalctl -f -u aktualizr-lite

Debugging the IBM IoT Container APP¶

In your Raspberry Pi 3 you can check the running container and copy the container ID:

# Raspberry Pi 3 Target Machine
$ docker ps

docker ps¶

With the container ID check the container logs:

# Raspberry Pi 3 Target Machine
$ docker logs -f 20a1ede9c146

docker log¶

As you can see, IBM IoT app is waiting for config files to connect and start sending data to the cloud.

Config files¶

We need to send a file configuration to the device. Create a file with some variables needed on the application.

Create a file “ibm.config” and copy the “Organization ID”, “Device Type”, “Device ID” and the “Authentication Token” to the variables:

# Ubuntu Host Machine
$ mkdir config
$ cd config
$ vim ibm.config

ibm.config:

WIOTP_IDENTITY_ORGID='rmboq4'
WIOTP_IDENTITY_TYPEID='RPi3B'
WIOTP_IDENTITY_DEVICEID='0001'
WIOTP_AUTH_TOKEN=XXXXXXXXXX

Use fioclt to send the files to the device safely:

# Ubuntu Host Machine
$ fioctl devices config set homeassistant32 ibm.config="$(cat ibm.config)""

After some time, the files will be copied to the folder “/var/run/secrets” on your device:

# Raspberry Pi 3 Target Machine
$ root@raspberrypi3:/home/prjs/ibm/config# ls /var/run/secrets/
ibm.config

Connect and send data to IBM IoT¶

As soon as the container finds the “ibm.config” file, it will automatically start sending data to the IBM Watson IoT Cloud.

IBM Watson IoT¶

Receiving data on IBM IoT core¶

Once the previews steps are complete you will be able to receive data inside your IBM Watson IoT.

At your IoT Dashboard, find “Boards” in the left menu.

Boards¶

Click on “Usage Overview” card.

Usage Overview¶

Click on “Add New Card”.

Add New Card¶

In the “Create Card” dialog, select “Line chart”.

Create Card dialog¶

Select your device.

Select your device¶

In the “Create Line chart Card” select:

Event: psutil
Property: cpu
Name: cpu
Type: Number
Unit: (empety)
Min: 0
Max: 100

Click on “Next”

Create Line chart Card¶

Select the chart size you prefer.

Chart Size¶

Finally, complete the chart name and click on “Submit”

Chart Size¶

Now you can see your device CPU usage live in the chart.

CPU Chart¶