In the Device registration page all devices are displayed which are currently in the registration process.
The following information is shown for each device:
Device name specified in the registration process
Status of the device (see below)
Creation date
Tenant from which the device was registered
The devices may have one of the following status:
Waiting for connection - The device has been registered but no device with the specified ID has tried to connect.
Pending acceptance - There is communication from a device with the specified ID, but the user doing the registration must still explicitly accept it so that the credentials are sent to the device.
Accepted - The user has allowed the credentials to be send to the device.
Blocked - The device registration has been blocked due to the exceeded limit of failed attempts.
Info
If a device registration is blocked, you will need to delete it first and then create it again.
Devices can be connected to your Cumulocity account in different ways.
To register devices, you can select one of the following options:
Microservice developers can also use the Extensible device registration and implement a custom registration form that blends seamlessly into the UI.
Info
The following descriptions apply to the general device registration processes. If you subscribe to specific protocol integrations, you will see additional protocol-specific options (for example, for LWM2M or OPC UA). A full list of supported protocols can be found in Device integration. It also contains descriptions for the protocol specific registration processes.
Cumulocity offers single device registration to connect devices manually one by one.
To connect a device manually
Info
Depending on the type of device you want to connect, not all steps of the following process may be relevant.
Click Registration in the Devices menu of the navigator.
In the Device registration page, click Register device at the right of the top bar and from the dropdown menu select Single registration > General. The Register devices dialog box will be displayed.
In the Device ID field, enter a unique ID for the device. To determine the ID, consult the device documentation. In case of mobile devices the ID usually is the IMEI (International Mobile Equipment Identity) often found on the back of the device.
Optionally, select a group to assign your device to after registration, see also Grouping devices.
Click Add device to register one more device. Again, enter the device ID and optionally select a group. This way, you can add multiple devices in one step.
Click Next to register your device(s).
Info
In an Enterprise tenant, the Management tenant may also directly select a tenant to which the device will be added from here. Note that since the Management tenant does not have access to the subtenant’s inventory you can either register devices to a tenant OR to a group, not both.
After successful registration the device(s) will be listed in the Device registration page with the status “Waiting for connection”.
Turn on the device(s) and wait for the connection to be established.
Once a device is connected, its status will change to “Pending acceptance”.
Click Accept to confirm the connection. The status of the device will change to “Accepted”.
Info
In case of any issues, consult the documentation applicable for your device type in the Cumulocity Partner Devices Ecosystem or look up the manual of your device.
Security token policy
Configure the security token policy to reduce the risk of devices which are not yet registered being taken over by threat actors, for example, by guessing their serial numbers.
Info
The feature requires READ permission for “Option management”. If the permission is missing, the security token policy defaults to OPTIONAL.
Cumulocity supports the following values for the security token policy:
IGNORED - Even if a device requires secure registration, Cumulocity will ignore that requirement.
OPTIONAL - If a device requires secure registration, Cumulocity will request an additional security token from the user.
REQUIRED - All devices connected to Cumulocity must use a security token during registration.
The policy can be configured by setting the following tenant option with one of the values listed above, for example:
With a value of IGNORED for the security token policy, a device connected to Cumulocity can be accepted without any token validation:
Optional security token policy
The list of device registrations is presented in the image below. Note that the input for security token is displayed for all devices.
Registration without using a security token
When a device connected to Cumulocity doesn’t use a security token, the registration can proceed without providing any value in the security token input.
If a security token is provided for a device which is connected insecurely, it will be accepted and the token will be ignored.
Registration using a security token
When a device connected to Cumulocity does use a security token, the registration can be completed only if the user provides a token matching the one sent by the device on establishing the connection.
In the case of providing an incorrect token, an error message will be displayed informing about a mismatch between the value used by the device and the value provided via the user interface.
After a certain amount of failed attempts, the registration will reach the blocked state, indicated by a corresponding error message.
The blocked registration must be removed before the next attempt to connect the device.
Limited usage of “Accept all” feature
The accept all feature is supported for devices connected to Cumulocity without the usage of a security token.
For any device which uses a security token, the accept all feature is not available and will display a warning message. The details of the warning message provide the list of devices which could not be accepted automatically.
Such devices must be accepted manually by providing the correct Security token value and clicking Accept.
Required security token policy
In this mode any device connected to Cumulocity must use a security token on establishing the connection and the user must enter the same token when accepting the device.
While in this mode, any devices connecting to Cumulocity without a security token will be blocked and it won’t be possible to complete their registration.
Bulk device registration
To connect larger amounts of devices, Cumulocity offers the option to bulk-register devices, that means, to register larger amounts of devices by uploading a CSV file.
Info
There is no restriction on the number of devices that you can bulk-register but the more devices you add the slower the creation and operation gets.
To bulk-register devices
Click Registration in the Devices menu of the navigator.
In the Device registration page, click Register device at the right of the top bar and from the dropdown menu select Bulk registration > General. The Bulk device registration dialog box will be displayed.
Click the Plus button to select or drag-and-drop the CSV file you want to upload.
Depending on the format of the uploaded CSV file, one of the following registration types will be processed:
Simple registration
Full registration
Info
Bulk registration creates an elementary representation of the device. Then, the device must update it to a full representation with its own status.
A separator is automatically obtained from the CSV file. Valid separator values are: \t (tabulation mark), ; (semicolon) and , (comma).
Simple registration
The CSV file contains two columns: ID;PATH, where ID is the device identifier, for example, serial number, and PATH is a slash-separated list of group names (path to the group where the device should be assigned to after registration).
ID;PATH
Device1;Group A
Device2;Group A/Group B
After the file is uploaded, all required new groups will be created, new registrations will be created with status “Waiting for connection”, and the normal registration process must be continued (see above).
Full registration
The CSV files must contain at least the IDs as device identifier and the credentials of the devices.
In addition to these columns the file can also contain other columns like ICCID, NAME, TYPE as shown in the following example:
To connect the devices, they are pre-registered with the relevant information. More specific, each device will be configured as follows:
Username - the username for accessing Cumulocity must have the format <tenant>/device_<id>, where <tenant> refers to the tenant from which the CSV file is imported and <id> refers to the respective value in the CSV file.
Password - the unique password for each device to access Cumulocity equals the value “Credentials” in the CSV file.
Device in managed object representation - fields TYPE, NAME, ICCID, IDTYPE, PATH, SHELL in the CSV file.
After the data is imported, you will get feedback on the number of devices that were pre-registered as well as on any potential errors that may have occurred.
For your convenience, we provide CSV template files for both bulk registration types (simple/full) which you can download from the registration wizard to view or copy the structure.
Info
If the device with the given identifier already exists, it will be updated with the data from the CSV file.
To import CSV data in Microsoft Excel
In Microsoft Excel, switch to the Data tab.
In the Data tab, select From Text in the top menu bar.
Select the CSV file you want to import by browsing for it (in this case the template file that you have downloaded from the Cumulocity platform).
In Step 1 of the Text Import Wizard, leave the default settings and click Next.
In Step 2 of the Text Import Wizard, select Semicolon as delimiter and click Finish.
For further information on the file format and accepted CSV variants, also refer to
Create a bulk device credentials request in the Cumulocity OpenAPI Specification.
Info
In an Enterprise tenant you may also register devices across multiple tenants by adding a Tenant column to the spreadsheet and importing the CSV file from the Management tenant. Contact your Operations team for further support.
Extensible device registration
To address the growing number of IoT protocols and certain restrictions in the general single or bulk device registration, Cumulocity provides an extensible device registration feature.
The general concept is based on extending the device registration using a metadata-based approach. Microservices and agents that implement current device registrations can add custom forms to the device registration wizard by providing simple descriptions of the required registration attributes. The metadata is then used by the UI to render a corresponding device registration wizard.
Extensible device registration requires application extensions to be defined, and the microservice to implement the predefined endpoints used for getting device registration metadata and creating the device.
Advantages of extended device registration
The extended device registration provides the following advantages:
Extensibility of the device registration wizard: You can easily add own forms to the device registration wizard in the Device Management application UI. The values to be entered in the user-specified forms can be freely customized by the device integration developers.
Support for bulk registration using custom CSV: You can customize the bulk registration and hence implement support for CSV files of a different format.
No UI code changes required: You do not need to write UI Angular code. This keeps the amount of integration work as little as possible. The device integration developer must only subscribe a microservice that provides an own wizard, and the wizard shows up automatically.
Extension enabling
As a first step to extend the device registration flow you must define extensions in the application representation.
Info
The extensions fragment can be placed either as root level or inside the manifest fragment of the application representation.
There are two types of extensions:
Single device registrations type: extensibleDeviceRegistration, for example:
After enabling the extensibleDeviceRegistration extension type, the Devices > Register device menu in the Device Management application is extended with an entry corresponding to the extension name property.
From now on, everything will be rendered based on data provided via the custom microservice. The added menu entry opens a window which fetches the form definition using the following endpoint:
GET /service/<contextPath>/deviceRegistration/metadata&lang=<user-language>
Make use of the lang query parameter in your microservice to respond with the already translated JSON Schema metadata. See also Limitations.
The UI automatically takes the contextPath for the GET request from the application definition of the microservice:
The important part is the pages array which contains steps of the wizard that the modal is going to render accordingly to the JSON Schema definition: https://json-schema.org/.
As a result the following wizard will be displayed:
In the final step all data collected via the wizard will be sent back to the microservice using the following REST endpoint:
The form is able to send anything defined via JSON Schema to the microservice. The Microservice provides the form definition and is responsible for the proper handling of the submitted data.
API specification
The device integration microservices must implement the following REST endpoints:
GET /service/<contextPath>/deviceRegistration/metadata?lang=<user-language>
Accept: application/json
Returns the metadata in the vocabulary of the JSON Schema.
POST /service/<contextPath>/deviceRegistration
Content-type: application/json
Creates a single device based on the collected data. Sends application/json with key-value pairs.
Single device registration flow diagram
The following diagram visualizes the single device registration flow:
Bulk device registration
Many device integrations require the registration of many devices at the same time. Currently, all protocols must rely on the bulk registration mechanism of the platform, which often either requires too many fields or requires custom fields to be added. The latter ones can however so far not be validated, as the core directly creates devices – and microservices and agents have no control over the properties being written to the managed objects.
After enabling the extensibleBulkDeviceRegistration extension type, the Device management & connectivity > Devices > Register device Bulk device registration modal is displayed with an extended wizard entry corresponding to the extension name property.
Additionally, the microservice provides the title of the wizard step and example bulk file(s):
The following diagram visualizes the bulk device registration flow:
Limitations
The concept does not allow the microservice to hook into deregistrations/decommissioning of a device:
Any device integration microservice must check if a device was deleted, for example to perform garbage collection.
Interactive steps (like “Bluetooth Coupling”) can not be implemented as of now. The reason here is that the concept assumes that only static properties are required for a device registration, not some process that requires user interactions.
In theory, the meta-data based approach can easily be extended in a way that the JSON used to render the form is not static, but dynamically generated by the microservice. For example, you could specify a “page” that draws the next specification dynamically from an endpoint after posting all given user inputs there.
We step back from such a solution for now, because it complicates the data model and the requirements to be fulfilled by the microservice.
No custom validations in the UI besides input validations by the JSON Schema vocabulary
No custom styling possible
Internationalization is not handled by the UI. As microservice developer it is your responsibility to provide already translated JSON Schema metadata
