Bosch IoT Device Management - will be discontinued by mid 2024

Automatic thing creation for gateways authenticating with device certificates

In this example, we assume that this time you want your gateways, which authenticate with device certificates, to be automatically registered with our services.

While some of the steps are similar to the previous tutorial, there are some important differences.

In addition to your Bosch IoT Device Management instance, you would also need permissions 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 you don't want to register your device explicitly, but instead create the "trust" via a device certificate, that is accepted by the device connectivity layer (i.e. Bosch IoT Hub).

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

Step A - Configure a CA certificate for your tenant

Navigate to https://accounts.bosch-iot-suite.com/subscriptions/ > Go to Developer Console. The Bosch IoT Suite console will open in a new browser tab where you can perform the following steps:

  1. Click Certificates in the left sidebar.
    (If this item is not visible in the left menu bar, open the section Services and features, and click the star icon in the Certificates tile to pin the entry to the left menu bar.)

  2. Click the + icon get the Add root certificate entry fields.

  3. Enter a unique name for the certificate.

  4. Click the Load PEM file button.
    Select the PEM file from the local folder where you store it and confirm with Open to upload it from your workstation.
    The certificate entry field is pre-filled with the Base64 encoded certificate.

  5. Enable the automatic provisioning, by activating the toggle button Auto-provisioning enabled.

  6. Allow the provisioning of a device as a gateway, by activating the toggle button Provision devices as gateways.

  7. Enter a template for the generation of the device ID during automatic provisioning in the field Device ID template.
    To build the device ID, you should add the namespace, use : as a separator, and extract information of the client certificate using the placeholder: {{subject-dn}} or {{subject-cn}}).
    The resulting device ID must have the namespace as prefix, e.g.: my.namespace:{{subject-cn}}.

    Since your subscription could potentially have multiple namespaces, please notice that the Device ID template must contain one specific namespace within your subscription.

  8. Click the Add button.

images/confluence/download/attachments/1813982442/Add_RootCertificate_withCallouts.png

Step B - Configure the Devices via Bosch IoT Hub connection

  1. From the left navigation of the Bosch IoT Suite console click Connections.
    (If this item is not visible in the left menu bar, open the section Services and features, and click the star icon in the Connections tile to pin the entry to the left menu bar.)

  2. Open the connection "Devices via Bosch IoT Hub"

  3. Click Edit to access the details.

  4. In the General section, part Gateway or stand-alone device, check the checkbox for Enable automatic thing creation for gateway or stand-alone devices.

  5. Optionally, adjust the Thing template of how the implicitly-registered things should look like.

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

    • By default the policy will have the entries DEVICE, DEFAULT and DEVICE-MANAGEMENT, just like if you would provision the device via the Device Provisioning API.

    • Additionally you can define other entries or use the function to copy another policy, which already exists.


    • Scroll back to the top of the connection and Save the changes.

    images/confluence/download/attachments/1813982442/automatic-stand-alone-thing-creation.png



Step C - Use Eclipse Mosquitto - to simulate a new device that needs to be registered implicitly

  • The mosquitto_pub command is installed. See Eclipse Mosquitto.

  • Download the server certificate for MQTT TLS encryption.

    curl -o ISRGRootX1.crt https://letsencrypt.org/certs/isrgrootx1.pem

  • Send an event from the gateway on behalf of the device to simulate device registration.

  • The content of the message must respect the thing's notation (Eclipse Ditto protocol format). In our case the request body looks like this:

    mosquitto_pub -h mqtt.bosch-iot-hub.com -p 8883 -t event/{tenant-id}/{device-id} -m
    '{
    "topic": "your.namespace/device-implicitly-registererd-01/things/twin/commands/modify",
    "path": "/attributes/manufacturer",
    "value": "my company"
    }'
    -q 1 --cert demo-certs/certs/gateway-cert.pem --key demo-certs/certs/gateway-key.pem --cafile ISRGRootX1.crt

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.

Both the gateway and the device, on behalf of which the gateway sends a message, are automatically provisioned and respective things are created.

The automatically created thing for the device will have the ID your.namespace:device-implicitly-registererd-01 and the automatically created thing for the gateway will have the ID based on the provided template, in our example it will be your.namespace:subject-dn.

{
"thingId": "your.namespace:device-implicitly-registererd-01",
"policyId": "your.namespace:device-implicitly-registererd-01",
"attributes": { "manufacturer" : "my company"},
"_modified": "2021-07-10T19:45:41.659137924Z",
"_revision": 1,
"_policy": { "This will be structured like provided in the template stored in the connection." }
}


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.

Step D - Device side actions - configure Bosch IoT Edge cloud agent to use certificates

Device communication at the edge can be enabled by Bosch IoT Edge if used in combination with Bosch IoT Device Management. Communication of Bosch IoT Edge to the cloud is realized by a cloud agent. The cloud agent is the main coordination center which forwards the local and remote messages. The mandatory information required for configuring the cloud agent to use the certificates on the device side is further described in the Bosch IoT Edge Cloud connectivity guide.

One way to acquire the device ID from certificates is with the so called device ID pattern. This pattern goes through resolving and results in the desired device ID, which then can be used to enable the device auto-registration process.

To provide the required information below usе the respective options:

  • Path to the gateway certificate and key pair with options -cert and -key

  • Pattern used to obtain the device ID from the provided gateway certificate with option -deviceIdPattern

  • Path to the provisioning file containing mandatory data such as tenant ID and connectivity details with option -provisioningFile

  • Path to the Hub certificate with option -cacert


cloudagent -cert demo-certs/certs/gateway-cert.pem -key demo-certs/certs/gateway-key.pem -deviceIdPattern "com.bosch.demo:{​{subject-dn}​}​" -provisioningFile provisioning.json -cacert ISRGRootX1.crt


The deviceIdPattern is case-sensitive and must be in lowercase, thus only {{subject-dn}} and {{subject-cn}} could be used in patterns definition.

If the cloud agent can not be started successfully it might be because of conflicting IDs (e.g. both deviceIdPattern and deviceId are provided).
In such a case check:

  • the starting options - i.e. don't additionally use deviceId as a command line option,

  • and the provisioning file - i.e remove the deviceId at JSON path hub/credentials/deviceId.

The submission of the Hub certificate and provisioning file path can be skipped, if their default file names are used, and if the certificates are located in the same directory with the cloud agent.

Note that with Cloud Agent 1.3.x the supported patterns on device side are {{subject-CN}} and {{subject-DN}}, as this was the original requirement.
Once the Cloud Agent 1.4.0 version is released, the lower case will be the correct one.