Device onboarding and connection options
This section describes how a device establishes a connection to your Device Management account for the first time (onboarding) and how that connection is maintained. The two underlying concepts are bootstrapping and registration.
Device Management provides two ways to onboard a device, which also affect connection maintenance:
Using bootstrap: The device received bootstrap credentials in the factory. The device first connects to the bootstrap service, which provides the LwM2M server account credentials for registration. This option allows the device to fall back to bootstrapping for renewing the LwM2M credentials.
Using direct Pelion LwM2M server credentials: The device received LwM2M server security object credentials in the factory. The device registers straight to the LwM2M server. With this option, the device cannot fall back to bootstrap. This places limitations on certificate renewing and connectivity maintenance.
Both options rely on provisioning the device credentials to the device during manufacturing. To get device connected, you must ensure that:
- The device is configured to use your chosen connection option. Set the value of the
- The device has credentials that allow it to access the registration mechanism (either bootstrap or LwM2M). See the full provisioning documentation for details.
- The CA certificate is uploaded to the system which enables Device Management to do the handshake with the device.
Tip: During development, you can use the Developer certificate option. It uses the bootstrap onboarding and a certificate obtained from Device Management Portal (and compiled into the binary), without requiring the factory tools.
Device ownership claiming during the onboarding process
Device Management provides a possibility to manufacture devices that do not need to be assigned to a specific account in the factory. Read more about the ownership claiming in the Device ownership chapter.
In the bootstrap flow, the device gets its Pelion LwM2M service credentials from the Device Management bootstrap service. This flow provides an advantage to connectivity maintenance: a device can fall back to the bootstrap flow to renew its LwM2M credentials if those expire or become invalid.
Currently, Device Management implements bootstrapping at two stages:
- Automatically, on the first power on.
- Whenever an already-bootstrapped client triggers the process (for example, because of expired credentials or changed ownership).
In bootstrapping, the device's endpoint name is used as the identifier if the device does not yet have a device ID. If Device Management has a matching device ID for the endpoint name, it will be used for the device. This means that the endpoint name must be unique in the account.
This is what happens between Device Management Client and the Device Management services in the bootstrap flow:
- The device connects to the bootstrap server with factory-provisioned credentials (or a developer certificate). The Device Management Client's
setup()API checks whether there are LwM2M server credentials available. If those credentials exist, the device registers directly with the LwM2M server. Otherwise, it connects to the bootstrap server.
- For a new device, Device Management creates an entry for the device in the Device Directory, assigns it a new device ID and sets its state to
cloud enrolling. If the device had onboarded in the past, a new device ID is not assigned. Instead, the device's existing Device Directory entry is updated.
- The bootstrap server sends the client the information it needs to connect to the LwM2M server: LwM2M credentials, device ID and the server's secure URI.
- When the device successfully bootstraps, it starts the registration flow.
The device now has an entry in Device Directory, and you can use the device ID to manage the device (through the portal or the APIs). But the device is still not registered with Device Management, and the Connect and Update features are not yet available; it must now complete the registration flow.
Note: There can be a delay of a few seconds before the device appears in the Device Directory and the Pelion portal UI.
The registration flow connects the device to the LwM2M server. The device then has access to all Device Management services.
There are two ways for the device to reach the registration flow:
Using the LwM2M credentials received during the bootstrap flow.
- The device ID individualizes the device. If there are two devices with the same device ID, the latest registration will overwrite the previous device.
Direct LwM2M mode: the device bypasses the bootstrap service and registers directly with the LwM2M server, using factory-injected LwM2M credentials. This mode is available only for commercial accounts and is not the preferred solution.
- The endpoint name individualizes the device. If there are two devices with same endpoint name, the last registering device will overwrite the existing one.
Note: Even if the endpoint name is the individualizing factor in this flow, the device ID needs to be used in REST API side. The device ID stays the same as it is mapped to the endpoint name.
This is what happens between Device Management Client and the Device Management services in the registration flow:
- The device registers with the LwM2M server using its LwM2M credentials, and provides its resource structure.
setup()API sets up a secure connection to the LwM2M server and registers the device.
- The registration transaction includes a negotiation of the registration session lifetime. It is initially configured in the client, as explained here.
- Device Management Connect implements the CoAP Resource directory to store the device's Resource structure (see RFC 6690).
- If the device already exists in Device Directory, its entry is updated. Otherwise, Device Directory creates a new device entry and device ID.
- The LwM2M server uses the Event notification channel to notify the application server of the registered device.
- The LwM2M server provides both the original device name (
oep) and the new device ID (
ep) to the application server.
- The application server must use the device ID to manage the device through the REST APIs. Tip: You can see the original device name and device ID mapping in the Device Directory API.
- The notification includes the device's Resource structure.
- The LwM2M server provides both the original device name (
- The device maintains the registration automatically by sending the server registration updates within the agreed lifetime. Registration updates include a delta of the resource structure (which the device application can change).
- The LwM2M server notifies the application server of the
- Note that the LwM2M server does not provide the original device name anymore; the web application works with the new device ID.
- The registration update includes the full Resource structure.
You can now use the device ID to manage the device and its Resources, and include the device in an update campaign.
Note: There can be a delay of a few seconds before the device appears in the Device Directory and the Device Management Portal. However, the application server is notified about the device registration as soon as device registration has completed.
- During registration, the device provides its Resource structure to the LwM2M server. The server stores the structure and maintains the needed queues. Whenever the client deregisters or its registration session expires, the server clears the Resource structure info and message queues (see below for more information about deregistration).
- If the client performs any registration action (register or register-update) more than 10 times within 10 seconds, it will be put on hold for 60 seconds.
A device can deregister from the LwM2M server:
- The device deregisters itself when it no longer needs connectivity.
- The LwM2M server notifies the application server about the device deregistration:
register_updateprovides only the device ID.
- The LwM2M server clears the device queues and resource structures from the server.
Renewing LwM2M credentials
To maintain a high level of security, the device certificates that the client receives from the bootstrap server have limited validity and expire regularly. Device Management Client checks the certificate validity, and can act to renew it when it expires:
- If the certificate validity expires or the system thinks that the device's security is compromised, the client removes these certificates and falls back to bootstrap mode.
- The client re-bootstraps to get the updated device certificates.
- The device ID remains the same, so the device does not lose its identity on Device Management.