Onboarding an IoT Device with Google Cloud connectivity, Wi-Fi-setup

Suru Dissanaike

Published in

HiMinds

9 min readJan 28, 2019

Ever wondered how you can onboard an IoT device in real-life?

Are you ready to take the leap from prototype to production-ready product with cloud connectivity?

I have read several tutorials about how you connect your IoT device to different cloud solutions. It is fantastic that so many people share their knowledge about connecting their embedded devices such as Raspberry Pi, Arduino, ESP32 etc. to Google IoT core and similar solutions.

Something that I have been missing is an article that discusses how to install a new device in your home; give it access to the internet and connect it to a cloud solution. This also means that an end-user somehow needs to link the new device to an account (that they use to login in the app) and during process claim it (prove they own the device). To make it slightly more difficult we also decided that everything needs to be open source and it would be great if the end-user can build their own firmware.

Together with my colleagues, we are building a Home Energy Monitor that enables you to perform a power signature analysis. Our end-goal is very modest, it is not about building a commercial product that will compete with similar products. This is what it looks like at the moment:

So why are we doing this?

It is a way for us to learn about the technology stack that is needed to create an Internet of things (IoT) products that consist of both hardware, back-end and a mobile app. We want to do it with a start-up mentality in our case also with a very limited budget.

What do we mean with device onboarding?

We have an app that the end-user uses to view their energy data. Let us call it the Home Energy Monitor App (shown above).

We also have a hardware device that connects to your electricity meter/fuse box using clip-on sensors (CT-clamps). Let us call it the home energy meter, it will report energy data to our Google Cloud solution using the WiFi connectivity in your home.

Create an account in the Home Energy Monitor App
Share your WiFi credentials with the home energy meter
Claim your home energy meter, prove that your account should be linked to a specific home energy meter
Verify that you can access energy data in your Home Energy Monitor App

The 4-step process above is our device onboarding process. We claim ownership of a specific home energy meter and we give it access to the Internet.

What happens in the factory?

Each device needs a unique identifier; often referred to as the serial number. This is not a secret (fully visible to the end-user), it helps the manufacturer to identify a specific device. Information that can be included in the serial number is:

Model (1 Digit)
Production Batch (2 Digits)
Serial number (5 Digits)
Checksum (2 Digits, CRC-8)

Most likely the serial number is printed on the device in the form of a barcode; this means that there are some limitations on the number of characters depending on which barcode coding is used. A QR-code could be used instead and include much more information but most end-users cannot “read/decrypt” a QR-code. That is why we often see a Code-128 barcode

Let's say that we have 10 alphanumeric characters that we can use to print a fairly small barcode. An example could look like this:

A01AB001A3

The checksum is calculated using a CRC-8, you can find an online calculator here. In Sweden, products usually need to be CE marked. This means that it is the manufacturer’s responsibility to:

Carry out the conformity assessment
Set up the technical file (TF)
issue the EC Declaration of Conformity (DoC)
place CE marking on a product

The CE marking is usually a label with the CE-logo and the information needed to fulfil the CE traceability requirements and other applicable requirements depending on how classification of the product. You usually also find the Producer mark, postal address of the manufacturer and unique identification code of the product i.e. the serial number.

Parts that are specific to the cloud

In this example we use the:

Most IoT cloud solutions require that an asymmetric authentication. This is done using public/private key pairs. Google IoT Core supports the RSA and Elliptic Curve algorithms. We can use openssl to generate the keys. It would look like this:

openssl genrsa -out rsa_private_DEVICE_ID.pem 2048
openssl rsa -in rsa_private_DEVICE_ID.pem -pubout -out rsa_public_DEVICE_ID.pem

This gives you a private and public key. You also need a CA certificate (Root SSL certificate). The CA certificate is used to establish a secure and trusted connection to your cloud solution, it contains several public keys.

If you want to learn more about how the CA certificate is used have a look at the SSL handshake, but basically, your device uses the public key in the CA certificate to verify the digital signature on the server cert.

Steps performed in the factory

Getting back to the factory;

In the factory, you would do the following:

Put firmware on your IoT device
Provision Serial number
Provision Private key and CA certificate
Perform functional production test

If your product has a “factory reset” functionality, the information above is never deleted.

After unpacking your Home Energy Meter, how do you give it internet access?

Most IoT devices lack a display and a keyboard to easily enter your WiFi credentials. Some devices use have WPS button but most do not. This excellent link has a Catalog of Onboarding Mechanisms for IoT Devices but what we quickly learn is that there are several standards. Which reminds me of a quote from the author of “Computer Networks”, course literature at my University.

“The good thing about standards is that there are so many to choose from.”
― Andrew S. Tanenbaum

In this article, we use a quite common way of providing the wifi credentials. Our IoT device (the home energy meter) can act both as an AP and STA; it starts up in AP mode and creates a WiFi network called “home-energy-meter” with the password “power”. You can use your mobile phone/tablet/laptop etc. to connect to the home energy meter SSID.

What is a captive portal?

Imagine you visit your local coffeehouse and order a matcha Latte or a traditional cappuccino. You decide to have a seat and enjoy your coffee at the coffeehouse. While you are sipping your hot drink you see that the café provides free internet access to its customers. The Wi-Fi is called “Coffeehouse rules”, you select the Wi-Fi network in your phone and suddenly a web page appears with some terms and conditions, you need to accept the terms and conditions in order to get Wi-Fi access. This is called a captive portal; so a captive portal is a Web page that the user of a public-access network is obliged to view and interact with before access is granted.

How does it work?

In order to serve a web page to the end-user, we need to run a web server. When the phone connects to the AP we provide an IP, DNS etc. We can either control the DNS lookups and always re-direct them to our Wi-Fi configuration page or we can support several HTTP endpoints for known Captive Portal device endpoints. Here is a list of some of the most common endpoints.

/hotspot-detect.html iOS
/library/test/success.html iOS
/mobile/status.php Android 8.0
/generate_204 Android
/gen_204 Android
/ncsi.txt Windows

wifi-captive-portal, an awesome project

Our Home Energy Meter uses an ESP32 and we run Mongoose on it. There is an awesome Mongoose OS library created by Myles McNamara called wifi-captive-portal. It does all of the heavy-lifting we just need to do a bit of configuration. When running the demo project; my device identifies itself as “Mongooose_058029”, I select it and enter the passkey “mongoose”

When I log in to the “Mongooose_058029" network the captive portal automatically appears:

Our onboarding process

In order to view the data in your Home Energy Monitor App; you need to give your Home Energy Meter internet access and also claim it in the system. This means that you need to prove that you own a specific Home Energy Meter in order to view its data. Sometimes this part of the process is referred to as “proof of possession mechanism”.The Home Energy Monitor app requires that you log in to use it, you just need to create an account.

These are the steps that the end-user of the Home Energy Meter needs to perform:

Download the Home Energy Monitor App
Register and verify your account
Get your activation code (displayed in the app)
Power-up your Home Energy Meter and connect to the “home-energy-meter” SSID with the password “power”
Enter the WiFi credentials and activation code in the captive portal
If everything goes according to plan, your Home Energy Meter will start to publish data to your account, success!

How do we know if this is a good process?

We can try to answer the questions in the “Catalog of Onboarding Mechanisms for IoT Devices”, this should give us some feedback.

Catalog of Onboarding Mechanisms for IoT Devices Q&A

The Github page for “Catalog of Onboarding Mechanisms for IoT Devices” has some excellent questions related to the onboarding mechanism, let us try to answer some of them:

How does device introduce itself to the infrastructure or peer?

Our Home Energy Meter starts in AP mode and advertises the SSID “home-energy-meter”

What, if any, proof of possession mechanism is there?

We use an activation code, which is displayed in the App. It is communicated over an out-of-band channel, i.e. displayed on the screen.

Is full Internet access required for onboarding?

No, you connect to the AP and enter the WiFi credentials of the AP that has internet connectivity.

What happens if the box gets reset?

A factory reset will remove the credentials will be removed and the device needs to be onboarded again.

How can transfer of ownership occur?

A factory reset and then remove the link to the home energy meter in the App/user account.

What sort of manufacturing requirements are there?

The private key, CA certificate and serial number are provisioned in the factory.

We did fairly okay answering the questions.

Next step

When looking at our onboarding process we see that we need to do a bit of tweaking of the wifi-captive-portal. In order to understand a bit more about what happens under the hood, we will base our wifi-configuration page on a more minimalistic solution and add functionality. This will be our starting point.

Wrap up

In this article, we discussed how our Home Energy Meter is installed in your home and what is done in the factory prior to shipping the product. A private key, CA certificate and serial number are provisioned in the factory. The keys that are provisioned are batch created and the production system keeps track of which private key is associated with which serial number.

We talked about how the end-user install the products and gives it access to the internet. We also discussed the claiming process were the end-user links their account in the Home Energy Monitor App to a specific Home Energy Meter.

Thank you for reading! Take care and hope to see you soon. 🙏🏽

Credits and highly recommended links

An Introduction to AC Power, chapter “Real Power, Reactive Power and Apparent Power”, URL: https://learn.openenergymonitor.org/electricity-monitoring/ac-power-theory/introduction
Catalog of Onboarding Mechanisms for IoT Devices URL: https://github.com/iot-onboarding/catalog
Mongoose OS Wifi Captive Portal URL: https://github.com/tripflex/wifi-captive-portal
You can find the HiMinds GitHub page here: www.himinds.io

The Source code

Part one, the starting point: