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.

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