Skip to content

iTwin IoT Plugin

Overview

This plugin provide the mechanisms to rapidly integrate any LoRaWAN sensor data gathered via the Krucial K-Cell and Krucial Connect online cloud platform and Bentley iTwin digital twining platform. In addition to creating the plugin to link the two platforms and allow data transfer between them, the user has to provide additional configuration data for each LoRaWAN device. This is done via predefined fields in a LoRaWAN device profile as discussed below.

Pre-requisites

In the following instructions it is assumed that the user has a valid Krucial K-Cell contract and K-Cell along with access to the Bentley iTwin platform.

Setup

The following guide presumes that the user is utilising the Krucial connect application. The same configuration can be carried out using the Krucial Connect CLI or APIs. The user has to complete the following steps to integrate the two systems and start data flowing between systems:

  1. Generate Oauth Client ID and Secret on the iTwin platform.
  2. Create a new plugin on Krucial connect.
  3. Create valid codecs for you device(s).
  4. Create device profiles for devices on Krucial connect.
  5. Create a deployment and associate the deployment with the iTwin plugin.
  6. Add devices to deployment.
  7. Register deployment on iTwin

1. Generate oAuth credentials

To integrate both systems you first have to generate an OAuth client ID and client secret in the iTwin platform.

For additional details on authentication with the iTwin platform please see the Bentley Developer documentation

2. Create an iTwin plugin

Once you have the authentication details from Bentley iTwin from step 1:

  • Login to your Krucial Connect account
  • Select Plugins from the navigation menu to browse to the plugins section.
  • Press the "Add Plugin" button.
  • Give the plugin a name to identify different iTwin accounts or use cases.
  • From the dropdown list, select iTwin IoT Platform for the type
  • From the dropdown list, elect OAuth as the authentication type
  • Enter the Authentication endpoint "https://ims.bentley.com/connect/token"
  • Enter your client id and client secrete from iTwin
  • Press the "save" button.

You should now have a valid link between your Krucial Connect platform and Bentley iTwin that can be used on a deployment. The next step is to create valid device profiles for the sensing devices you will be using.

3. Create a codec

A LoRaWAN codec allows raw data transmitted from LoRaWAN devices to be encoded and decoded as it passes through the Krucial connect platform. They are also used to correctly parse and format your data for onward transmission to iTwin. Codecs must conform to the standard outlined by LoRa Alliance. Documentation for writing a codec to this specification can be found here: LoRa Alliance Payload Codec API Docs.

For the iTwin IoT plugin, the decoded packet must be a JSON object which contains a field named "iTwin-value". This value is used to ensure that the data is sent onwards to iTwin. An example is given below for the expected output data object:

"data": {
    [
        { "name": "sensor name", displayName: "Display Name", "iTwin-value": "your decoded value" }, 
        { "name": "sensor name", displayName: "Display Name", "iTwin-value": "your decoded value" } 
    ]
 }
Once you have created or downloaded a valid codec for each of your devices you can proceed to adding them to your devices profiles.

For additional details and examples of generating codecs for use with Krucial connect and iTwin please see the public gitHub repository connect-plugins

4. Creating a device profile for iTwin plugins

LoRaWAN device profiles are used to configure one or more LoRaWAN devices with a selection of LoRaWAN parameters. To support integration with the Bentley iTwin system we make use of the tags field to provide device specific information to iTwin. When used in conjunction with iTwin you will normally have one device profile and one codec per device type.

To create a device profile, navigate to device profiles in your Krucial Connect account and click the "Add Device Profile button".

Provide the device profile with a name then set the remaining fields as per the requirements for your LoRaWAN device. You will need to check with your device manufacturer for their recommended settings. The default configuration here may be appropriate for many devices:
Krucial OTAA Default Device Profile.

In the codec field enter the JavaScript code generated earlier.

A device profile that will be used for a device on a iTwin Plugin deployment will also need to have a set of device profile tags that will contain additional information required to connect with iTwin. Each device will have an ITWIN_DEVICE_SDE and ITWIN_SENSOR_SDE tage.

  • ITWIN_DEVICE_SDE - is defined as a single string value which represents a iTwin device type that is used to store the various sensors.
  • ITWIN_SENSOR_SDE - contains integrationId, value, unit and metric fields expected by iTwin.

All iTwin device types can be retrieved using the following curl command:

    curl -X 'GET' 'https://iiot.bentley.com/api/devices/types' 
    -H 'accept: application/json' -H "Authorization: Bearer <token>"

Note - a valid Bearer token is needed for this curl command. Please refer to the authorization documentation for iTwin: iTwin Auth docs.

ITWIN_SENSOR_SDE is defined as an array of objects that must meet the following structure:

    {
        "integration_id": "value from iTwin",
        "name": "name of sensor",
        "unit": "unit of measurement",
        "metric": "metric for unit of measurement"
    }
The integration_id field is the type of sensor that is being used. Again this is defined by iTwin and all sensor types can be retrieved by using the following curl command: 

    curl -X 'GET' 'https://iiot.bentley.com/api/sensor/types' 
    -H 'accept: application/json' -H "Authorization: Bearer <token>"

The name of the sensor is used on iTwin to identify individual sensors on a device (give this a generic name). Please ensure this is given a sensible value to ensure iTwin IoT can be used effectively. The unit and metric for the sensor are defined to ensure that decoding of data is in the control of the end user. Please ensure that the data being decoded in the payload codec for the device matches the unit that is used to integrate the sensor on iTwin. All supported units and metrics for a sensor are returned with the types from the above curl command.

If the device only has one sensor - please ensure that the object is still wrapped in []. See an example for a NWave Parking Sensor below:

{
    "ITWIN_DEVICE_SDE": "DEMO_DEVICE_SDE",
    "ITWIN_SENSOR_SDE": [
      [
        {
            "integrationId": "DISCREET_SDE",
            "name": "parking sensor",
            "unit": "raw_value",
            "metric": "UNITLESS"
        }
      ]
    ]
}
Once all of the above has been completed. Click the "save" button.

5. Creating a deployment

Once a plugin has been created, a deployment can be created to house all the sensors that will be used. To create a deployment go to deployments and press the "Add Deployment" button. Give the deployment a name, select the gateway that the deployment will use from the gateway dropdown menu, and select your newly created plugin from the plugin dropdown menu. Now press the save button.

Click on the row in the table corresponding to your newly created deployment and this should take you to the deployment management screen. Here you will see details on your iTwin plugin configuration, K-Cell and any devices on the deployment.

6 . Creating a device

Press the "Manage Devices" button located within the "Devices" panel. This will take you to the deployment device management screen. Once on this page press the "Add Device to Deployment" button.

Give the device a name (this name is used by iTwin to display the device - give it a specific name), enter the devEUI of the device (this is a 16 digit identifier for the device). Select the appropriate device profile for the device and enter the app key for the device. Then press the "save" button.

Repeat these steps for each device to be added to the deployment.

7. Register the deployment with iTwin IoT

Once all devices have been added, the deployment is ready to be integrated to iTwin. This done by going to the iTwin system and registering a new connection.

Once logged into iTwin click "connectivity" on the sidebar, once loaded click the "+ connection" button. Select "Krucial" and enter the K-Cell serial number into the form. Enter your authentication token. This can be captured by going to developer tools on any web browser and selecting any of the requests sent to the Sigma API. Once all of the above has been entered click the "connect" button.

To verify that the connection has been established with iTwin check that all devices are visible in the "Connectivity" screen. You can also go to deployments and clicking the "View Plugin Config" button within the "Plugins" panel. This will take you to the deployment plugin management screen. If the "Config" part of the table has been populated then the connection to iTwin has been successful.

Once the connection has been established, any devices you add to the deployment will automatically be added to iTwin. Please ensure that all devices are set up correctly with the correct device profile details once the connection has been established.