Bosch IoT Device Management - will be discontinued by mid 2024

Things and features

The versatile assets in IoT applications can be managed as things.

Thing

Things are generic entities and can be used as a “handle” for multiple features belonging to this thing.

Examples:

  • Physical device: a lawn mower, a sensor, a vehicle, a lamp

  • Virtual device: a room in a house, a virtual power plant spanning multiple power plants, the weather information for a specific location collected by various sensors

  • Transactional entity: a tour of a vehicle (from start until stop), a series of measurements of a machine

  • Master data entity: a supplier of devices or a service provider for devices, an entity representing a city/region

  • Anything else - if it can be modeled and managed appropriately by the supported concepts/capabilities

Thing ID

For choosing custom IDs when creating a thing, the following rules apply:

thingId = <namespace> + ":" + <thing-name>

The thing ID may only consist of up to 256 characters.

Namespace

To distinguish things from different solution spaces, they need be created in separate namespaces.

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

    • must start with a lower- or uppercase character from A-Z

    • dot (".") can be used, but must be followed by a lower- or uppercase character from a-z

    • numbers can be used

    • underscore ("_") can be used

    • dash ("-") can be used, but must be followed by a lower- or uppercase character from a-z

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

Allowed characters for the thing name

Due to the fact that a thing ID often needs to be set in the path of a HTTP request, the 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 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

  • com-bosch-example:my-device 4711

Definition

A thing may optionally contain a definition describing which model the thing adheres to. It holds a fully qualified identifier.

The pattern for a valid identifier is namespace:name:version.

The identifier could reference a device abstraction (e.g. an “Information Model” created with Eclipse Vorto).

Attributes

Attributes describe the thing in more detail. They can be of any type, and can be structured flat or nested - whatever fits better your application. Typically, they hold rather static properties, where static means that the values do not change as frequently as property values of Features.

Attributes can also be used to find things.

Feature

A Feature is used to manage all data and functionality of a thing that can be clustered in an outlined technical context.

For different contexts or aspects of a thing, different features can be used, which are all belonging to the same thing and do not exist without this thing.

Feature properties

The data related to a feature is managed in the form of a list of properties. These properties can be categorized, e.g. to manage the status, the configuration or any fault information.

The feature properties can represent:

  • properties (e.g. values as reported by a physical device)

  • desiredProperties (e.g. values set via a remote management UI, aiming to trigger the device integration layer to change the device configuration).

Each property itself can be either a simple scalar value or a complex object. Allowed is any JSON object.

You can create, read, update and delete all properties and desiredProperties. Further such properties and desiredProperties fields can be used within get thing requests, search or count conditions, or filters.
Like for all other fields of a thing, the permission to read and write those fields is controlled via the policy.

Please note however, that for the time being, the digital twin layer does not implement further processing for desiredProperties. Such functionality will come with future releases.

Characters allowed in a feature ID

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

  • max. 256 characters

  • may not be the wildcard operator *, due to the special meaning of this character for filtering

  • may not contain the slash character /

  • may not contain the control characters hex 00-1F and 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.

The same restrictions apply for attribute keys, as the key could also get in the path of a HTTP request.

Definition field at the features level

A feature may optionally contain a definition describing which model the feature adheres to. It holds a fully qualified identifier.

The pattern for a valid identifier is namespace:name:version.

The identifier could reference a device abstraction (e.g. a “Function Block” created with Eclipse Vorto).

Deviating from the definition field at the thing level, the feature definition field is an array, and thus can hold a comma separated list of multiple definitions.

Example

{
"thingId": "org.example:coffee-machine",
"policyId": "org.example:coffee-machine",
"definition": "com.acme:coffee-machine:1.0.1",
"attributes": {
"manufacturer": "ACME demo corp.",
"location": "Berlin, main floor",
"serialno": "42",
"model": "Speaking coffee machine"
},
"features": {
"coffee-brewer": {
"definition": ["com.acme:coffeebrewer:0.1.0"],
"properties": {
"brewed-coffees": 0
}
},
"water-tank": {
"definition": ["com.acme:watertank:1.0.0"],
"properties": {
"configuration": {
"smartMode": true,
"brewingTemp": 87,
"tempToHold": 44,
"timeoutSeconds": 6000
},
"status": {
"waterAmount": 731,
"temperature": 44
}
},
"desiredProperties": {
"status": {
"temperature": 80
}
}
}
}
}

Find the API description and examples at following sections:
Things see Things resources.
Search Things see Search resources.


How does a definition apply

A definition identifier can be stored at the thing level, and/or a the specific feature of your thing within the digital twin store, given that you follow the pattern shown above.

However, at the time of writing we do not apply any definition:

  • We do not check whether or not such a definition is available at the Eclipse Vorto repository.

  • In case of multiple definition identifiers, we do not interpret how the multiple definitions complement or override one another.

As a consequence, the digital twin layer currently does not check the conformity of the feature properties with the definition.

If you store the definition at the thing level, this field can be used for filtering, be in for your get things request, for search or count.
Like for all other fields of a thing, the permission to read and write those fields is controlled via the policy.


Further reading on Eclipse Vorto models

How does a desired properties value apply

You can only define desiredProperties on existing features. It expresses the desire that the device should be reconfigured in a way that the desired properties value should be accomplished. Setting new desired properties on a feature will overwrite older values.

Such desiredProperties fields can be used additionally or alternatively to other properties within get thing requests, search or count conditions, or filters.
Like for all other fields of a thing, the permission to read and write those fields is controlled via the policy.

Please note however, that for the time being, the digital twin layer does not implement further processing for desiredProperties. Such functionality will come with future releases.

Example: encoding special characters in a thing ID

See Register a device via the Device Provisioning API with a special character in the ID