Improve this doc

Microsoft Azure IoT Suite integration

Balena makes it simple to deploy, update, and maintain code running on remote devices. Microsoft's new IoT Suite makes it easy to manage and capture the data those devices generate. This tutorial will walk you through using the two in conjunction.

Connect your device to balena

Follow our getting started guide to get your device connect to your balena dashboard. Once your device shows up on the dashboard you're ready for the next step.

factory-build

Create the balena API Key

Find your Application ID in the balena dashboard url: https://dashboard.balena-cloud.com/apps/NNNN/devices and your auth-token from the preferences panel. Then combine insert the two into the curl request below.

curl -H 'Authorization: Bearer AUTH_TOKEN' -X POST https://api.www.balena.io/application/NNNN/generate-api-key

This will return your new API key.

NOTE: The key will be returned in quotation marks, but these should be stripped before using it in the following step.

Add balena API key to IoT Hub Admin portal

Signup and following the Azure IoT Suite getting started guide.

NOTE: you'll have to use the special version with balena integration additions as our integration is not currently a part of the code Microsoft releases.

Go to the IoT Hub Admin portal, select 'Balena Config' and set the App ID and the newly generated API Key.

IoT-hub-creds

This will automatically create a new device on IoT Hub with every device you currently have on balena as well as every future device you may have, as it constantly polls for new devices.

devices-pending

This also automatically creates application wide and per device environment variables on balena that are accessible by your code. e.g. $IOT_HUB_DEVICE_ID. This obviously simplifies sending data to the IoT hub.

The variables are:

  • Application-wide
    • IOT_HUB_HOST - full hostname, like MyHub.azure-devices.net
    • IOT_HUB_NAME - first part of the hostname, like MyHub
    • IOT_HUB_SUFFIX - rest of the hostname, like azure-devices.net
  • Per-device:
    • IOT_HUB_DEVICE_ID
    • IOT_HUB_DEVICE_KEY

resin-envar

Push the sample app to your devices

When you push code to the balena git endpoint several things happen, including:

  • balena creates a Docker container
  • it provisions it following the instructions in Dockerfile (for example, it automatically installs Linux packages and builds C sources in our case)
  • it notifies the devices about the new container availability

When you power on the device, it connects to the balena API and fetches the application container. It also does it every time a new container is available (when you push the updated code).

First clone the the sample application to your local machine.

NOTE: Our integration is not part of the code Microsoft releases, instead it will stay as a separate fork that should be used instead of the official sample solution.

git clone https://github.com/balena-io-projects/resin-azure-iot-sample && cd resin-azure-iot-sample && git checkout resin-node

Then add your balena applications remote endpoint to the git repository. It can be found in the top right hand corner of your balena applications dashboard.

git remote add balena <your-applications-remote-endpoint>

Then all that's left to do is push your repository to your balena application endpoint we have just created.

git push balena resin-node:master

Once the container is successfully built (you'll see a unicorn), the container will begin to download to the device.

downloading

Once the download is complete, head to the device logs you'll notice that we are sending telemetry data to the IoT Hub.

resin-logs

Have fun!

Now you’re done. Provision as many devices as you need with balena (you can use the same device OS image you’ve downloaded at step 1, burn it to multiple SD cards and power on the devices). You can watch devices appearing online through balena dashboard. You can check app and device environment variables that should be created quickly after the device is online. Then you can check the device logs and see as they send the information to the IoT Hub. Finally you can go to the IoT Hub Admin portal and check that the new devices appear as running there.

devices-running