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 events 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 C - Use the Bosch IoT Hub HTTP API - to simulate a new device needs to be registered implicitly
Step A - Register a Gateway via Developer Console
Navigate to https://accounts.bosch-iot-suite.com/subscriptions/
Go to Developer Console > tab Provisioning
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 Bosch IoT Hub and its digital twin representation in Bosch IoT Things.
{ "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.
{ "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.
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 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.