Bosch IoT Suite

Unique identifier - common device ID patterns

In a complex system architecture, you will need to clearly identify your devices across several layers.

Providing a unique ID for all entities, helps to avoid ambiguity.


Table of contents


Device ID and allowed characters

The identifier is composed of the namespace and the name, separated by a colon : character.

Namespace

In order to separate things from different solution spaces from each other, they are required to be created in a specific namespace.

  • The namespace must conform to the reverse domain name notation:

    • must start with a lower- or uppercase character from a-z

    • can use dots (“.”) to separate characters

    • a dot (“.”) must be followed by a lower- or uppercase character from a-z

    • numbers can be used

    • underscore can be used

  • The namespace is separated by a mandatory colon (:) from the rest of the thing identifier.

Name

Due to the fact that a thing ID often needs to be set in the path of a HTTP request, following restrictions apply:

  • may not contain the slash character /

  • may not contain the control characters hex 00-1F to 7F-FF

  • may contain special characters, but these have to be encoded/decoded according to the standard/format required for the respective channel.
    See Decoding and encoding of special characters for details.


Examples for a valid device ID and thing ID

  • com.example.my.solution:00000018283

  • com.acme.foo.bar:00000018283

  • com.acme.foo.bar.tenant_42:00000018283

  • com.bosch.example:my-device 4711

Best practices

  • The namespace could represent the manufacturer, customer, subscription, tenant or project, which your other code uses.

    • In case you can choose only one namespace, you can optionally add structuring information, e.g.

      • com.bosch.home.smokedetector

    • In case of a standard plan you can even reserve multiple namespaces, if it helps your filtering, or for other purposes.
      Examples for namespaces showing a hierarchy:

      • com.bosch

      • com.bosch.ebike

      • com bosch.ebike.battery

  • The device name could be a device serial number or similar identifier.

    • The syntax of the name is very open and we will not prevent you from starting with a blank or star, even if in some cases such IDs are not easy to understand.

    • However, you don't need to invest too much time in encoding and decoding special characters,
      if your device name's regex would look like this: [a-zA-Z0-9-_:]+$
      meaning, it uses small and capital letters, numbers, minus, underscores, and colon.


Device ID of devices registered automatically via a gateway device

A gateway running the Bosch IoT Edge Agent is provisioned in a way, that it allows to automatically register the devices, which are attached to the gateway. The implicit registration is triggered on the first device message.

Examples for devices registered via an edge agent

A gateway, named com.example.my.solution:gw-01 registered with the specific empowerment would automatically provision:

  • com.example.my.solution:gw-01:edge:containers - the thing which manages the OCI containers

As soon as you instantiate additionally the Bosch IoT Edge Services, following virtual devices will be auto-registered:

  • com.example.my.solution:gw-01:edge:services:runtime - the thing which represents the Edge Services Runtime (OSGi runtime)

  • com.example.my.solution:gw-01:edge:services:bundles - the thing which manages the bundles of the Edge Services Runtime (OSGi bundles)

  • com.example.my.solution:gw-01:edge:services:configurations - the thing which manages the configurations of the Edge Services Runtime (OSGi configurations)

As soon as you instantiate additionally a device, the pattern is:

  • com.example.my.solution:gw-01:<device_id> - the thing which represents the Edge Services Runtime connected device (OSGi Device Access devices)

Examples for IDs of auto-registered Bluetooth, Onvif, Z-Wave and ZigBee devices:

  • com.example.my.solution:gw-01:da:device:BluetoothLE:DC:A6:32:0D:21:8D

  • com.example.my.solution:gw-01:da:device:ONVIF:ONVIF controller

  • com.example.my.solution:gw-01:da:device:ONVIF:Bosch-FLEXIDOME_IP_5000i_IR-094456675477890014

  • com.example.my.solution:gw-01:da:device:ONVIF:Dahua-SD22204T-GN-4G00D74PAJ1DDFD

  • com.example.my.solution:gw-01:da:device:ZWave:CA0D6357%2F1

  • com.example.my.solution:gw-01:da:device:ZWave:CA0D6357%2F2

  • com.example.my.solution:gw-01:da:device:ZWave:CA0D6357%2F3

  • com.example.my.solution:gw-01:da:device:ZWave:CA0D6357%2F4

  • com.example.my.solution:gw-01:da:device:ZWave:CA0D6357%2F8

  • com.example.my.solution:gw-01:da:device:ZigBee:000d6f0001b64f6a

  • com.example.my.solution:gw-01:da:device:ZigBee:00124b000420cefd

Device to digital twin relation

As of today the Device Provisioning API and the default connection between the Hub and Things building blocks is implemented as 1:1 relation.

It imposes, that both - the device and its digital twin - are registered with the exact same identifier, composed of the namespace and the name, separated by a colon : character.

namespace:unique-name

This way, we can assure that a device within Bosch IoT Hub can only update its own digital twin in Bosch IoT Things (i.e. the one with the same ID).

In scenarios, where you create a connection by yourself, and where you don't need this feature, you can uncheck the "Enable Bosch IoT Hub/Things ID convention" checkbox in your connections source configuration.

Further notes

On all Bosch IoT Suite APIs the transfer of IDs needs to be encoded according to the respective channel technology (e.g. IDs in HTTP URLs must be URL-encoded). No additional Suite-specific encoding must be used.

Additionally, please keep in mind, that the device ID and thing ID may only consist of up to 256 characters in total.