Gateway Software Protocol Adapter

The Gateway Software Protocol Adapter is part of the Bosch IoT Hub service offering. Its purpose is to provide connectivity of gateways running Bosch IoT Gateway Software to the Bosch IoT Suite. It represents the gateway as well as all connected edge devices and their capabilities as things with features in the Bosch IoT Things service.

In the Gateway Runtime, the gateway resources, including all connected edge device and their capabilities, are represented as Functional Items. These Functional Items are depicted by the Gateway Software Protocol Adapter as features, belonging to a thing in the Bosch IoT Things service. This is accomplished via sending properly formatted Ditto messages through Bosch IoT Hub event points.

The message payload of the events sent by the protocol adapter is a command, which allows direct consumption of these events by the Bosch IoT Thing service and building of so-called digital twins of the connected edge devices.


Table of contents

General design

The diagram below illustrates how a gateway running Bosch IoT Gateway Software and its Functional Items (FIs) are mapped as things and features in the Things service.

images/confluence/download/attachments/894247350/29072019-mapping-gateway-things.png

As shown on the image above, the Gateway Runtime is represented as a Gateway Thing in the context of Bosch IoT Things. Every edge device (represented as Device FI) is mapped to a separate Edge Device Thing. All corresponding Functional Items are represented as features of the related thing.

Gateway Runtime to Thing - mapping structure

The diagram below represents the mapping structure between the Gateway Runtime, a Device Functional Item (Device FI), and their corresponding things. All name/tags, properties and attributes of a Functional Item are mapped to the feature properties of their corresponding thing.

As the Gateway Runtime is represented as Gateway Thing, all functional items available in the Gateway Runtime which are not associated with edge devices, are represented as features of the Gateway Thing.

images/confluence/download/attachments/894247350/gatewayToThingMapping.png

Thing

Typically, a thing entity is structured as follows:

  • Thing ID - (String) - composed of namespace and name separated by a colon (:) character.
    The namespace needs to fit the requirements described at Namespace.
    The name will differ, depending on your use case:

  • The thing ID for a gateway is <namespace>:<serial number>.

  • The thing ID for an edge device (represented as Device Functional Item) is <namespace>:<gateway serial number>:<Device FI ID>.

  • Features
    The thing features are constructed from the corresponding Functional Items. The Device functional item is mapped to a special feature that represent
    the generic info for the device. The other functional items related to the device (so called device items) are also represent as features. Please refer to
    the graphic above for visual comprehension.

Feature

Typically, a thing feature is structured as follows:

  • Feature ID - (String)
    The feature ID is based on the ID of the particular functional Item related to the device (see Functional Item ID to Feature ID Mapping tip below).

  • Properties
    The Feature properties are split into three types - Attributes, Configuration and Status properties.

    • Functional item attributes are mapped to the Attributes properties

    • Writeable functional Item properties are mapped to the Configuration properties

    • Readable functional Item properties are mapped to the Status properties

Functional Item UID to Feature ID Mapping

The ID of the special feature related to a Device Functional Item is "DeviceInfo".

The IDs of the rest of the features representing the other functional items related to the device (the so called device items) in general are using the following format:

"ShortInterfaceName" or "ShortInterfaceName_...".

where ShortInterfaceName is the last segment оf the corresponding Functional Item UID, e.g. da:item:Cameras:1:Configuration will be mapped to Configuration.

Note: The upper rule is not valid at the moment for feature IDs of device items created for some protocols e.g. Z-Wave.

In the mentioned IDs of Things and Features the following character symbols need to be encoded:

ID Encoding
'/' = %2F '?' = %3F '#' = %23 '*' = %2A
',' = %2C ' ' = %20 '%' = %25 '"' = %22

These 8 characters as well as control characters (hex 00-1F and 7F-FF) have to be encoded similar to URL-encoding by replacing them with %XX, where XX is the hex code of the character.
See Eclipse Ditto encoding helper for details.

All other characters can be used without any encoding; thus you don't have to use "full" URL-encoding style to write these IDs.

Example mapping

The following code block represents an example Edge Thing mapping:

{
"thingId": "NAMESPACE:GATEWAY_ID[::DEVICE_FI_ID]",
"attributes": {
"thing.type": EdgeDevice
"mapping.version": {Version of FI to thing mapping},
"device.id": {DEVICE_FI_UID},
"gateway.id": {GATEWAY_ID},
},
  "features": {
"{DeviceInfo}": {
"definition": ["{VORTO_NAMESPACE}:{VORTO_TYPE}:{VORTO_VERSION}"],
"properties": {
"attributes": {
... {DEVICE_FI_ATTRIBUTES} ...
},
  "configuration": {
"name": {DEVICE_FI_NAME}
"tags": {DEVICE_FI_TAGS}
... Readable and Writable Device Functional Item Properties ...
},
"status": {
... Readable Only Device Functional Item Properties ...
}
}
},
"{FEATURE_ID}": {
"definition": ["{VORTO_NAMESPACE}:{VORTO_TYPE}:{VORTO_VERSION}"],
  "properties": {
"attributes": {
... {FI_ATTRIBUTES} ...
},
"configuration": {
"name": {FI_NAME}
"tags": {FI_TAGS}
... Readable and Writable Functional Item Properties ...
},
"status": {
... Readable Only Functional Item Properties ...
}
}
}
}
}

Synchronization flow between a gateway and its digital twin

When it comes to the behavior of the Gateway Software Protocol Adapter upon state changes and their reflections in the Bosch IoT Things service:

  • The digital twin in the Things service is created when a gateway is connected for the first time.

    • A thing is created for every newly connected gateway and for every edge device connected via gateway.

    • A feature is created for every newly discovered Functional Item related to Gateway Runtime or edge device.

    • The ModifyThing commands are used for these types of updates.

  • If changes in a gateway's state occur while the gateway is connected, they are sent as events and reflected accordingly in the digital twin representation.

    • All changes that occur in connected gateways and their Functional Items are sent as ditto commands and applied instantly to their respective things/features.

    • In these types of updates more fine grained commands like ModifyFeature and ModifyFeatureProperties are used.

  • If the gateway is not connected, all changes are buffered and applied once a connection is established.

Command & Control

The Gateway Software Protocol Adapter also supports invoking of operations on the Functional Items of connected gateways - by sending of properly formatted messages via the Bosch IoT Things/Hub service. Command-and-control functionalities are handled via Ditto messages, as described in the Talking to Features paragraph of the Ditto documentation. After the message is received, the Gateway Runtime sends a response in the form of a JSON binding representation.

Messages to/from a thing and a featureMessages can be sent via the Bosch IoT Things HTTP API by:

POST /things/{thing-id}/features/{feature-id}/inbox/messages/{operation-id}
Content-Type: application/json
 
<operation-arguments>

The <operation-arguments> are operation arguments encoded as a JSON object containing pairs of argument names to argument values.

Example: {arg1_name: arg1_value, arg2_name: arg2_value, ...., argN_name: argN_value}, where each arg<N>_value can be a number, string, array or object - depending on the corresponding Java type of the Functional Item operation argument.
If the Functional Item argument is a bean, it is represented as a JSON object.

Find an example at the Things documentation > How to make sure my message payload follows a specific order?

The result of the FI operation is returned as a response of the Thing REST call - formatted as JSON number, string, array or object - depending of the Java type of the operation result.

Setting a property

Any changes of thing properties (e.g. Feature properties) that are initiated through the Bosch IoT Things API itself will not be reflected on the edge device.
All property modifications should be executed via commands as shown below.

Setting a property on a digital twin is done through a command, following the pattern:

$set.configuration/<property-name>

Example:

$set.configuration/name with payload {"new_value":<new value>}

Setting a policy

In order to avoid accidental changes of attributes that should be altered only by the Gateway Software Protocol Adapter (and thus lose sync between the digital twin and edge device), please get familiar with the policy concept.

Recommendation

Find an example of an additional policy entry which allows writing attributes, except a specific path at Create a policy entry for your backend application.