Automatic thing creation for egde devices via a gateway device
In this example, you will learn how your devices connected via a gateway can be automatically registered with our services.
You will need a Bosch IoT Device Management instance, and permissions to edit the pre-configured "Devices via Bosch IoT Hub" connection.
By default, all devices and gateways which want to communicate to 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 events via the gateway, and your connection should be enabled to register them automatically.
To prepare such a setup, please proceed with the steps described below in following sections:
Step A - Register a Gateway via the Bosch IoT Suite UI
Change to Subscriptions on the left sidebar and select your relevant subscription from the list
Then, open Provisioning from the left navigation
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".
Result
You have created a gateway device in the context of the device connectivity layer (Bosch IoT Hub) and its digital twin representation in the digital twin layer (Bosch IoT Things).
{ "enabled": true, "authorities": [ "auto-provisioning-enabled" ], "device-id": "example.iot.dm:gw-01"}Note, that such a gateway thing has the Info attribute "gateway": true.
{ "thingId": "example.iot.dm:gw-01", "policyId": "example.iot.dm: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. example.iot.dm:gw-01
Edit the request body with the new authorities option "auto-provisioning-enabled"
{ "enabled": true, "authorities": [ "auto-provisioning-enabled" ], "device-id": "example.iot.dm:gw-01"}Step B - Configure the Hub-Things connection
Open Connections from the left navigation
Select the connection Devices via Bosch IoT Hub
The General section is expanded by default
Scroll down to the subsection Edge or virtual device via gateway
Check whether the checkbox for Enable automatic thing creation for edge or virtual devices via gateway is checked.
If it is not, click the Edit button next to the connection name and check this checkbox, then click Save.
Optionally, you can also adjust the template for the automatically registered things (see the Thing template section on the screenshot above).
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 that a new device has 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. example.iot.dm_gw-01@t515xxx_hub
Tip: You can copy it from the Bosch IoT Suite UI > 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. example.iot.dm: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": "example.iot.dm:device-01-via-gw-01", "policyId": "example.iot.dm:device-01-via-gw-01", "attributes": { "Info": { "gatewayId": "example.iot.dm:gw-01" } }, "_modified": "2020-09-10T19:45:41.659137924Z", "_revision": 1, "_policy": { "this will be a copy of policy example.iot.dm:gw-01" } }}Please take into account that the protocol adapters of Bosch IoT Hub have a caching mechanism in place for devices and their credentials. This means that 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.