Automatic thing creation for egde devices via a gateway device

In this example, we assume that you want your devices connected via a gateway to be automatically registered with our services.

You will need a Bosch IoT Device Management instance, and permission to edit the pre-configured "Devices via Bosch IoT Hub" connection.

By default, all devices and gateways which want to communicate to the Bosch IoT Suite need to be registered.
In this case, however, we assume that only the gateway is registered explicitly, and that the devices behind the gateway need to be registered implicitly.
Most probably, the edge devices will only send an event via the gateway, and your connection should be enabled to register them automatically.


To prepare such a setup, please proceed the steps described in following sections:

Step A - Register a Gateway via Developer Console

At Provisioning > Settings > Select how the device is connected use the drop-down and select Gateway device.

Check the checkbox for "Enable automatic provisioning of edge devices".

images/confluence/download/attachments/1842650526/gw-allows-implicit-provisioning.png


Result

You have created a gateway device in the context of Bosch IoT Hub and its digital twin representation in Bosch IoT Things.


Device in Bosch IoT Hub
{
"enabled": true,
"authorities": [
"auto-provisioning-enabled"
],
"device-id": "org.example.namespace:gw-01"
}


Note, that such a gateway thing has the Info attribute "gateway": true.

Thing in Bosch IoT Things
{
"thingId": "org.example.namespace:gw-01",
"policyId": "org.example.namespace:gw-01",
"attributes": {
"Info": {
"displayName": "",
"gateway": true
}
},
"_modified": "2020-09-10T19:44:41.659137924Z",
"_revision": 1,
"_policy": { ... }
}
}

In case your gateway device has already been provisioned without auto-provisioning-enabled,
and you need to enable the implicit provisioning feature at a later point in time, please use the Bosch IoT Hub - Management API to adjust the device settings.

  • Navigate to Bosch IoT Hub - Management API

  • Authorize with a Suite OAuth token

  • Use a PUT/registration/{tenant-id}/{device-id} request for the update

  • Set the tenant ID to your Bosch IoT Hub tenant ID

  • Set the device ID of the provisioned gateway e.g. org.example.acp:gw-01

  • Edit the request body with the new authorities option "auto-provisioning-enabled"

{
"enabled": true,
"authorities": [
"auto-provisioning-enabled"
],
"device-id": "org.example.acp:gw-01"
}

Step B - Configure the Hub-Things connection

  • Navigate to https://accounts.bosch-iot-suite.com/subscriptions/

  • Go to Developer Console > tab Connections

  • The Connections/Integrations will open in a new browser tab

  • Open the connection Devices via Bosch IoT Hub > Edit

  • Check the checkbox for Enable automatic thing creation for edge or virtual devices via gateway.
    images/confluence/download/attachments/1842650526/automatic-thing-creation-device-via-gateway.png

  • Optionally, adjust the template of how the things registered automatically should look like.

    • By default we will create a thing with the given device ID

    • For the policy of the device via gateway we use the function to copy the policy of the gateway.

    • The Info attribute, will document the gateway ID.

    • Additionally you can define an inline policy (_policy - with the complete structure) or use the function to copy another policy, which already exists.

Step C - Use the Bosch IoT Hub HTTP API - to simulate a new device needs to be registered implicitly

  • Navigate to Bosch IoT Hub - HTTP Adapter

  • At this step you need to authorize as the gateway.

    • username: <namespace>_<device-name>@<hub-tenant-ID>

    • password: as set by yourself at the provisioning time

    • e.g. org.example.acp_gw-01@t515xxx_hub
      Tip
      : You can copy it from the Developer Console > Things > gw-01 > Device section

  • Select PUT ​/event​/{tenant-id}​/{device-id} Publish an Event (Gateway Mode)

  • Set the tenant ID, e.g. t515xxx_hub

  • Set the device ID, e.g. org.example.acp:device-01-via-gw-01

  • The payload is not relevant at this step, as the new thing will be structured as given in the template - see step B

Result

The result is forwarded to Bosch IoT Things. Due to the fact that it is passed through the connection configured at step B, a payload mapping will be applied.

The implicitly created thing will have the ID org.example.acp:device-01-via-gw-01.


{
"thingId": "org.example.namespace:device-01-via-gw-01",
"policyId": "org.example.namespace:device-01-via-gw-01",
"attributes": {
"Info": {
"gatewayId": "org.example.acp:gw-01"
}
},
"_modified": "2020-09-10T19:45:41.659137924Z",
"_revision": 1,
"_policy": { "this will be a copy of policy org.example.acp:gw-01" }
}
}

Please take into account that the protocol adapters of the Bosch IoT Hub have a caching mechanism in place for devices and their credentials. That means if you make changes in the device's or credentials' properties, it takes some time until the protocol adapters apply the changes. Currently the cache setting is configured to 10 minutes.