Connecting a Device to Oracle IoT Cloud

Hey guys! Over the past week I’ve had a couple people ask how I got data from a physical device into Oracle Internet of Things Cloud Service. This guide will go over my whole setup, from hardware to cloud. Have fun!

Part 0: Things you Need:

Before you start, there are a few things you’re going to need:

• An Oracle Cloud account with Internet of Things Cloud Service. If you don’t already have an account, click here to get started!!
• A BBC micro:bit (http://microbit.org/)
• A Raspberry Pi with nodejs installed

Part 1: Create an Application in IoTCS

To start, let’s set up an application inside your Internet of Things cloud service. Once you log into your instance, you should be able to see a dashboard like the one in Figure A. This dashboard gives you a summary of all the activity in your environment over the last week.

Figure 1: Internet of Things Desktop

To create a new application, click on the hamburger menu in the top left and then click Applications > Browse Applications

Figure 2: Applications Dashboard

The application page gives you the option to import an existing app or create a new one. For this guide, we’re going to create a new app. Click on Create Application and enter the name you want to give your application here.

Figure 3: Create a new Application

Once the application has been created, click on it to go to the Application Dashboard. Before we can start getting data into the app, we have to create a device model. Click on ‘Create Device Model’ to start.

Figure 4: Blank Application Page

Our first device model is going to be pretty simple. Fill out the following fields:

• Name
• URN — this needs to be in the format urn:<your>:<device>:<here>. Save this URN, because we’ll need it for the gateway code!
• Custom attributes — these can be whatever data you want to send; I’ve chosen to send the micro:bit name and a message, both of which are strings.

Figure 5: Example Device Model

Click on ‘Save’ in the top right corner to save your model. Once you’ve saved your model, it should appear under your device models.

Figure 6: Completed Device Model

We’re also going to need a device model for our raspberry pi gateway. This device can be even simpler than the first one; the gateway doesn’t need any custom attributes so we can just give it a name and a URN.

Figure 7: Gateway Device Model

Finally, we need to register our gateway with IoTCS. To do this, open up the side menu and navigate to Devices > Registration

Figure 8: Opening Device Registration

We only have one gateway, so click ‘Register a single device’.

Figure 9: Device Registration Home

Here, the only field we really need to fill out is Activation ID. I also usually like to define the secret as well; in this case it’s just ‘secret’. You can add more metadata if you like; I usually stick with just these two fields. Once you’ve filled this form out, click ‘Register’.

Figure 10: Device Registration Form

Registration isn’t quite finished! Next, we need to specify a password for the provisioning file that has been created, and then download the file. Once you have the file downloaded, click finish.

Figure 11: Downloading Provisioning File

You’ll need to transfer this file over to your raspberry pi; mine is stored in ~/iot-demo/Keys.

That’s it for the Cloud Side! Next, let’s take a look at the network architecture.

Part 2: Network Setup

One of the biggest challenges we’ve had is connecting devices to the internet. Using open WiFi for IoT can bring up security concerns, and many enterprise networks have several layers of security that makes it hard to connect nonstandard devices. To get around this, we’re using a Raspberry Pi as a gateway. The Raspberry Pi can then be connected either via WiFi or by Ethernet.

The micro:bit will then talk to the Raspberry Pi using the Bluetooth protocol, and then the Pi will send the data to the cloud.

Figure 12: Network Diagram

Part 3: Coding the micro:bit

One of the reasons I chose to use the micro:bit as a hardware platform is the fact that it is BLE enabled. The micro:bit comes with a number of BLE profiles and services out of the box. The one we’re going to be using is called the Event Service. Most of the heavy lifting for this will be done on the Pi; from the micro:bit side, all we have to do is create events with an ID and a payload. We’re going to use some of the built in inputs from the micro:bit for these events.

The editor for micro:bit can be found here: https://makecode.microbit.org/

Once you open the editor, the first thing we need to do is to add the bluetooth library. Click ‘Advanced’ and then ‘Add Package’.

Figure 13: micro:bit Makecode UI

Search for ‘bluetooth’ and then click on the bluetooth package.

Figure 14: Adding the Bluetooth Library

If it asks you if you want to get rid of the radio package, click yes. The bluetooth and radio libraries are incompatible because they both use the wireless antenna. We don’t need radio, so it’s okay to get rid of it.

Once the library is imported, it’s time to start coding! I prefer working in javascript; my code is shown below. If working with blocks is easier for you, I’ve included that code too.

Figure 15: Javascript Code for micro:bit

Figure 16: Blocks Code for micro:bit

This code is pretty simple; I’ve chosen 4096 for my event ID, and then based on the input type I’m sending a different value. I’m also showing the value that’s being shown, just so I can see what’s happening.

There’s only one more step before we download this code to the micro:bit. If you aren’t already in javascript mode, click on javascript. Then click on pxt.json and click on turn on ‘No Pairing Required’

Figure 17: Turning off Pairing

The page will reload, and then you’re ready to save the code!

Plug the micro:bit into your laptop, name your project, and then click ‘Download’. When prompted, save the hex file to the micro:bit. Once it finishes flashing, you should be able to test your code by pushing buttons and shaking the micro:bit.

Part 4: Running the Gateway Code

This is where things start coming together. All the code can be found here:

unofficialoraclecloudhub/iotcs-demo

You should clone this repository to your raspberry pi. Copy the provisioning file you got in Step 2 into the /iot-demo/Keys directory.

There are several node libraries you’ll need to run the code. In a terminal session in your Raspberry Pi, type the following commands:

sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev
npm install -g node-forge
npm install -g jsdoc
npm install -g noble

Before you run anything, you’ll need to make one minor modification in the script. First, open a terminal session on your raspberry pi and run the following command:

sudo bluetoothctl

This will open a bluetooth console. We need to find the MAC address of our micro:bit, so type ‘scan on’ to start the bluetooth scan and ‘scan off’ to stop it once you’ve found your device. One of the entries should look like ‘xx:xx:xx:xx:xx:xx BBC micro:bit [xxxxx]’. The first part of this line (xx:xx:xx:xx:xx:xx) is your MAC address; copy this down, we’ll need it in a minute. Type ‘quit’ to exit the bluetooth terminal.

Open /iot-demo/csl/js/code/demo.js in your favorite text editor. Change the variable mac_addr to the address you just got for you device. Save the change, and then close the editor.

To run the script, navigate to the /iot-demo directory and use the following command, replacing <your key> and <your key secret> with your respective values.

sudo ./csl/js/scripts/run-device-node-sample.sh csl/js/code/demo.js Keys/<your key> <your key secret>

If there are no errors, you should see data coming in on your console when you press the buttons and shake the micro:bit. In your IoT Console, you should also see a new device, as well as any messages that have been sent.

Figure 18: IoT Console

This has been a pretty simple of example of getting a physical device to send messages to Oracle’s IoTCS, and there’s a lot more we can do with it. If you’re interested in following our IoT adventure, check us out on GitHub, where we’ll be posting any future projects we do.

unofficialoraclecloudhub