Skip to content

Device Serialization

For secure operation it is essential that each device can be uniquely identified. Most devices are created with a serial number that may include the product code, manufacturing batch number and individual serial number. However, while this serial number may be unique, it can be easily guessed because serial numbers typically follow a predictable format.

Instead of using the existing serial number, Ioto uses a random, unique claim ID (UCI) that is a random, 80-bit number that is not guessable and does not follow a predictable pattern. When paired with the product ID it is used as a unique claim ticket, allowing users to claim devices for management.

1
JT08FFQXWQ

The 10 letter UCI results in over 1 quadrillion possible combinations (32^10).

During manufacturing, each device is given a UCI that identifies the device to the service and is used by the user to "claim" the device after purchase or installation.

For User-Claimed devices, the UCI should be printed on the device label and be clearly identified as the Claim ID. The Claim ID can also be represented as a QR code if you choose to develop a mobile app for users to claim devices. (See Claiming below).

Device Label

Creating the UCI

There are several ways to create the UCI depending on how you operate your production process.

  • Manually configure the UCI in the device.json5
  • Have the Ioto Agent generate a UCI on startup.
  • Create unique firmware for each device.
  • Factory allocate the UCI in each device during manufacturing.

Regardless of which method you choose, the end result is the Ioto device.json5 configuration file is updated with the UCI in the id property.

1
2
3
4
{
    "id": "JT08FFQXWQ",
    "product": "01G8YJKKRNTHW213TRZYX3YH0M"
}

The product property in the device.json5 is generated by the Builder Site when you define your product.

Manually Creating the UCI

If you have a very small production run of devices, you can manually create the UCI with unique values for each device. You can simply edit the device.json5 with the required values.

With any significant production volumes, you will want an automated process.

Agent Generated UCI

If you set the services.serialize property in the config.json5 to "auto", Ioto will automatically generate a UCI and save it to the device.json5 file.

1
2
3
4
5
6
7
{
    services: {
        cloud: {
            serialize: "auto"
        }
    }
}

Unique Firmware

If you create unique firmware for each device, you can set the UCI in the device.json5 when you create the firmware.

To generate a UCI, you can either run the ioto process with the --id argument or you can create a simple program that calls the cryptID API from the libioto library. See the ./factory/serialize.c sample for an example.

Factory UCI

If you are using identical firmware for each device, you can allocate the UCI by having the Ioto device agent connect to a factory serialization service during manufacturing. The serialization service will generate and provide the UCI to the agent, which will then persist it to the device.json5 configuration file.

This generation should be integrated with your label creation process during manufacturing so that the UCI in the device.json5 matches that product label affixed to the device.

The serialization service should listen for client requests on a HTTP endpoint and provide the UCI as the response.

To enable factory UCI generation, set the services.serialize property to "factory" and define the address of the serialization HTTP endpoint in the api.serialize property in the config.json5 configuration file.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    api: {
        serialize: "http://localhost:1234/ioto/serialize"
    },
    services: {
        cloud: {
            serialize: "factory"
        }
    }
}

The Ioto agent includes a sample serialization service in the ./factory/serialize.c file.