Things and features

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

Thing

Things are very 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, following rules apply:

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

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

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.

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, 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

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.

note 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 to 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 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 Bosch IoT Things service 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 an 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.

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

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

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

Schematic view

Thing and feature

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
             }
        }
      }
    }
  }

tip 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 Things service 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 Bosch IoT Things service currently does not check the conformity of the feature properties with the definition.

tip 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 Bosch IoT Things service does not implement further processing for desiredProperties. Such functionality will come with future releases.

Examples for encoding special characters in a thing ID

Given a thing is created using the Device Provisioning API, see Bosch IoT Suite for Device Management. The thing ID is transferred in the JSON payload and might contain an empty space.

{
      "id": "com.bosch.example:my-device 4711",
      "hub": {
        "device": {
          "enabled": true
        },
        "credentials": {
          "type": "hashed-password",
          "secrets": [
            {
              "password": "yourPassword"
            }
          ]
        }
      },
      "things": {
        "thing": {
          "attributes": {
            "manufacturer": "Robert Bosch GmbH"
          }
        }
      }
}

Bosch IoT Things will persist the thing ID, and the policy ID with an empty space accordingly.

However, if the thing is requested directly via the Bosch IoT Things HTTP API, you need to take care of the correct URL encoding:

GET /things/com.bosch.example:my-device%204711

Corporate information Data protection notice Legal information Support Free plans