Registering devices

Single device registration

Cumulocity IoT offers single device registration to connect devices manually one by one.

To connect a device manually

1. Click Registration in the Devices menu of the navigator.
2. 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.
3. 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.
4. Optionally, select a group to assign your device to after registration, see also Grouping devices.
5. 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.
6. 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”.

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.

Cumulocity IoT supports the following values for the security token policy:

• IGNORED - Even if a device requires secure registration, Cumulocity IoT will ignore that requirement.
• OPTIONAL - If a device requires secure registration, Cumulocity IoT will request an additional security token from the user.
• REQUIRED - All devices connected to Cumulocity IoT 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:

{
  "category": "device-registration",
  "key": "security-token.policy",
  "value": "IGNORED"
}

Ignored security token policy

With a value of IGNORED for the security token policy, a device connected to Cumulocity IoT 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 IoT 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 IoT 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 IoT 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 IoT must use a security token on establishing the connection and the user must enter the same token when accepting the device.

The procedure of accepting devices is the same as described in Optional security token policy.

While in this mode, any devices connecting to Cumulocity IoT 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 IoT offers the option to bulk-register devices, that means, to register larger amounts of devices by uploading a CSV file.

To bulk-register devices

1. Click Registration in the Devices menu of the navigator.

2. 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.

3. 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

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:

ID;CREDENTIALS;TYPE;NAME;ICCID;IDTYPE;PATH;SHELL;AUTH_TYPE
006064ce800a;LF2PWJoLG1Fz;c8y_Device;Sample_Device1;+491555555;c8y_Serial;bulk group/subgroup1;1;BASIC
006064ce8077;OowoGKAbiNJs;c8y_Device;Sample_Device2;+491555555;c8y_Serial;bulk group/subgroup2;1;BASIC

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 IoT 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 IoT 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.

To import CSV data in Microsoft Excel

1. In Microsoft Excel, switch to the Data tab.
2. In the Data tab, select From Text in the top menu bar.
3. 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 IoT platform).
4. In Step 1 of the Text Import Wizard, leave the default settings and click Next.
5. 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 IoT OpenAPI Specification.