Skip to content

Device provisioning

Provisioning a device means enrolling it into the platform, and configuring it to be able to communicate with the platform. It is a central operation in Kamea. In the Kamea environment, provisioning generally refers to the device enrollment, because the device in itself is out of the scope of Kamea.

Provisioning a device includes those steps (which are automatically handed by the API): - Associating a device to a channel - Declaring to the ingestion chain that the device is allowed to communicate on this channel. For instance, in Azure, it means creating a document describing the device, its channels, etc... in the Storage Account used by the Azure Functions that compose the ingestion chain. This operations lets the Azure Functions know that the device is authorized to communicate on this channel, and how the payload must be decoded - Creating the device on the underlying interface if needed. In the case of IoT Hub, it means creating the device in the IoT Hub device registry. When using HTTP, this step is skipped, because there is no external interface to use.

Once the device has been provisioned, its credentials can be retrieved from the API. Those credentials depend on how the device has been provisioned. For example, a device provisioned on IoT Hub will need one of the supported authentication methods (symmetric key, self signed certificate, CA signed certificate), and the credentials will change based on the chosen authentication method.

Devices must be provisioned before being able to connect to Kamea.

The next sections present the technical details of the provisioning on all of the supported interfaces.

HTTP

HTTP is the simplest form of provisioning, and more generally the simplest interface to use. It does not require any external connectivity layer: Kamea is self sufficient in this case.

When provisioning a device on HTTP, a random secret is generated in the database. This secret is used by the devices to authenticate their API calls, whether they are trying to upload telemetries, update their state, read their configurations, etc...

The secret must be passed in the headers of the HTTP request:

Authorization: Secret <device secret>

The secret is also stored, after being hashed, in the storage dedicated to the ingestion chain. When a device sends telemetries, its secret is hashed by the ingestion chain, and compared to the one stored in the storage. All the requests that are not used to send telemetries are handled by the API, so the secret is directly compared to the one stored in database.

Note

The secret is not hashed in database, because it needs to be retrievable by the user.

Apart from the secret, the API exposes a second information: the URL where the device should send its telemetries. This URL includes the device ID in order to identify it.

Note

The device must know two different URLs: one for the ingestion chain to upload telemetries, and one for the API to communicated state changes and read new configurations.

IoT Hub

When provisioning a device on IoT Hub, the API creates the device in the IoT Hub registry. Once IoT Hub has completed the device registration (which can take up to a few seconds), the device can start sending data, reading its state, etc...

The IoT Hub device is named after the device internal Kamea UUID.

Note

The device name can be customized by specifying the system metadata iotHubDeviceName, which must contain the chosen device name as its value. As long as this metadata is present in the system, Kamea will use it to retrieve the device on IoT Hub, as well as when receiving device events like device twin updates, or connectivity changes.

It's up to the user to choose which authentication method must be used by the device. This information will be forwarded to IoT Hub, which handles the credential generation in the case of symmetric keys.

When communicating with a device through IoT Hub, the API will use the IoT Hub API to send commands, write desired properties, read the device twin, etc... On the other side, the device just needs to use the IoT Hub SDK to communicate with the cloud. There is nothing related to Kamea that it has to take into account. Which means that developers need to refer to Microsoft documentations when implementing the device firmware.

DPS

Kamea also supports creating devices directly in IoT Hub. Which means that it also supports provisioning devices through the Azure DPS (Device Provisioning Service) resource, because DPS ends up creating the device on IoT Hub.

The API listens to the device lifecycle events sent by IoT Hub. Upon reception of an event notifying the creation of a new device, the API runs the usual provisioning process, creates the device in database and in the ingestion chain storage.

When devices are created directly through IoT Hub, any name can be used. Since the device does not yet exist in database, we cannot refer to it by its UUID. The system metadata iotHubDeviceName is used to customize the name.