Key Distribution Description

As the first thing, Homer sits down and registers himself on ThingSpeak.

After logging in, he observes his account API key. It is something like R9TUHWKR8OOQEHWU.

This extra step is necessary, because we (as Smart Widgets 'R Us) don’t have access to ThingSpeak account management API. So our users have to carry out this registration on their own. This restriction will be lifted in the future when we’ll operate an IoT platform by ourselves.

If you’d scroll down to the summary figure or open it schema-1.png, this step is marked as #1.

Just after registration to ThingSpeak, Homer opens midPoint and fills-in the second (and last) registration form.

From this point on, midPoint knows about Homer and is ready to manage his devices, ThingSpeak channels, and affiliated users.

Technically, an organization The Simpsons has been created in midPoint, having:

What is also important, midPoint generated so called registration key that will be entered into devices so they could connect to midPoint.

This step is marked as #2 in the schema-1.png.

The registration form and code behind it is part of a midPoint overlay project: iot-story on github.

At this point (or anytime later) Homer can log into midPoint and create arbitrary sub-organizations as containers for his users and devices. So he immediately creates Household and Power plant orgs, and marge@simps.net and bart@simps.net users. He places Marge into Household organization, thus allowing her to see only devices that will be present there.

(See step #3 in the schema-1.png.)

When finished playing with midPoint, Homer unwraps the bag full of thermometers and looks at them. Connects one of them via good old serial link to a terminal and copies there the registration key of HQ481047-1JWORF43 that he finds in midPoint. (Technically, it’s extension/registrationKey property of The Simpsons org object.)

<TODO screenshot>

Now he power cycles the device. After starting, the thermometer connects to midPoint and registers itself in it. It does so by connecting to http://localhost:8080/midpoint/ws/iot/devices/74743827342?key=HQ481047. There are two pieces of data there: 74743827342 is the serial number of the devices (burned into it), and HQ481047 is the first half of the registration key, used as an authentication measure. MidPoint reacts by creating the object for the device and a ThingSpeak channel for it. From ThingSpeak it obtains channel number and credentials (read and write key) and sends back the channel number and the write key, encrypted using the second half of the registration key (1JWORF43).

The thermometer stores the ThingSpeak channel number and write key in its EEPROM, and starts measuring the temperature and sending it to ThingSpeak channel.

This process is covered by steps 4, 5 (including 5a), and 6 in the schema-1.png.

At this moment, Homer invites Marge to log into midPoint and find her access keys there.

<TODO screenshot>

Unfortunately, ThingSpeak doesn’t have custom GUI for retrieving graphs via channel read key. So she points her browser to https://thingspeak.com/channels/142770/charts/1?api_key=C0FPQ9W3ET7A4S2S (C0FPQ9W3ET7A4S2S is the read key, and 142770 is the channel number she learns from midPoint as well). As we are getting better in web programming each day, she can also do this directly from midPoint, displaying all the channels she has authorizations for.

<TODO screenshot>

Here is the summary picture of how the keys are distributed.

TODO