This offer is only addressed to commercial customers including freelancers and entrepreneurs. All prices are exclusive of value added tax (VAT).
  • Share via email
  • Subscribe to blog alert

Cross-Domain Development Kit (XDK) Cloud Connectivity

What you will learn

This guide will help you to connect your Cross-Domain Development Kit (XDK) to the Bosch IoT Suite. The XDK rapid prototyping device comes with various built-in sensors, see datasheet. Once your device is registered with the Bosch IoT Suite, you can access the device sensor data over the API. 

In this example, you will use the Bosch IoT Suite infrastructure. You will learn how to register your XDK, flash it with a firmware using the XDK Workbench, and access its values over the API.

Accessing the device data opens up new opportunities to remotely monitor and to process the device data in your custom applications.

Duration

This tutorial will take you about 2 hours, depending on how familiar you are with the SDK and with the concepts of the Bosch IoT Suite.

What you need to prepare and download

Hardware

Software

  • Download the latest XDK Workbench (please make sure you use version 3.7)
    https://developer.bosch.com/web/xdk/downloads
  • A 2.4 GHz Wi-Fi network within range of the device
  • A web browser that is up to date and does not block cookies

Tasks to complete

Setting the ground

Back to the tasks ▲

This section will guide you through the steps of the preparation process:

Subscribe to a Bosch IoT Suite package

Subscribe to the Bosch IoT Suite for Device Management to create your own instance.

  1. Use the Bosch IoT Suite portal as an entry point.
  2. Click My Account (My Bosch ID) and Sign in with your Bosch ID.

    Sign in with My Bosch ID

    1. In case you do not have an account yet, register a new one (Sign up for an account).
    2. After logging in you will be re-directed to the Suite.
  3. In the Service Subscriptions view

    1. Click + New Subscription.
    2. Select Bosch IoT Suite for Device Management.
    3. Select a service plan (e.g. Free on AWS)
    4. Set your Instance Name (this must be unique).
    5. Click Subscribe and confirm the cost summary page by clicking Subscribe again.
    6. The Status will be Provisioning while the service subscription is being created.
      If the Status is not Active after some seconds, click the Refresh button.

You now have successfully subscribed your own package instance.

Tip

In case you have a package subscription already, feel free to skip this step and proceed with “1. Provision your XDK”.

Free service plan

Free service instances are for evaluation purposes only, and therefore, cannot be upgraded to a paid plan at a later moment.

To subscribe to a paid service plan, please start the subscription process via the AWS Marketplace.

Access credentials

To have a look at the access credentials of your package instance, click Show Credentials.

Register your namespace

For your instance, you need at least one default namespace to allocate the digital twins of your physical devices accordingly.

  1. Start at the Developer Console > Namespaces.
  2. Click the plus icon to add a namespace
  3. Enter a namespace name in the field.
    The namespace can be anything, as long as it conforms to the reverse domain name notation, e.g. my.first.namespace, as in our case.
    However, it needs to be unique, i.e. you cannot register the exact same namespace for multiple instances.
  4. The search index fields are set to the defaults which are most convenient for the Device Management package to work properly,
    1. More search index fields can be added later if needed.
    2. The required fields are the minimum necessary and cannot be deactivated
  5. Confirm with Save.

Your namespace can henceforth be used for your things and their policies.

Namespace

The namespace makes your thing ID and policy ID globally unique.

1. Provision your XDK

Back to the tasks ▲

Before the XDK device can upload its data into the Bosch IoT Suite, you will need to register it.

Given you use the developer console for provisioning, you can easily choose to use the Eclipse Vorto model.

xdk vorto based

  1. Click the Provisioning entry in the left sidebar.
  2. The opened view shows the 3 steps required for provisioning:
    1. Settings: provide essential settings (this step is already selected and the related view is opened, too)
    2. Preview: view/manage the data which will be used to provision the device and send the request
    3. Connect device: prepare the connection of  your device by saving response data and configuration properties
  3. From the drop-down, choose Use Vorto information model.
  4. Select the row of the model XDK (version 2.0.0).
  5. Click Select in the details view.
  6. The default type Stand-alone-device is ok.
  7. Set thing/device ID: First, select a namespace.
  8. Enter a unique name. The full identifier that our Hub and Things service will register is "your.namespace:your-device-name".
  9. Provide credentials for your device: enter a password in plain text. This will be used by the physical XDK when trying to connect to the Bosch IoT Suite.
  10. Confirm with Next.
  11. The preview is optional, just confirm provisioning with Send request.

    preview

  12. Click the Provisioning entry in the left sidebar. Click Save response and store the file provisioning.json safely on your local machine for the time when the physical device is set up.
  13. Click the Go to thing button, if you want to see the digital twin of your XDK at the Things tab.

    save json

Preparations

We assume you have already a valid subscription on a Bosch IoT Suite package, otherwise please get yourself a free instance. See Subscribe the Bosch IoT Suite package.

Check your work

In the Things view, you can open the features and see their names, as defines in the Eclipse Vorto model. Each of the XDK sensors is represented here.

xdk is now registered

In the next step, you will learn to setup the XDK in a way that it is able to send its sensor readings to the cloud. You will add functionalities to this empty digital twin.

2. Flash your XDK

Back to the tasks ▲

In this section, you will make use of the XDK Workbench to prepare the firmware which will be flashed to the XDK device.  

Setup the XDK Workbench

In order to connect to the Bosch IoT Suite, the XDK needs to be flashed with a specific firmware package called BoschIoTSuite:

  • Download the latest XDK Workbench (please make sure you use version 3.7).
    https://developer.bosch.com/web/xdk/downloads
  • Install it on your local machine. You will need admin rights.
  • Open the XDK Workbench, and select BoschIoTSuite from the Welcome screen.
    If you do not see the Welcome screen, you can access it via Help > Welcome.

Prepare the SD card

The credentials for your WiFi and your device will need to be stored at the root level of the SD card.

  1. Add the file provisioning.json
    This is the file, which you have downloaded at the end of the provisioning process.
    It holds all information needed to authenticate the XDK device to the Bosch IoT Suite, especially to the MQTT adapter of Bosch IoT Hub.
  2. Add a file config.json
    Copy this file example and add your WiFi credentials:

    {
       "wlan":{
          "isenterprise":0,
          "isenterprisecertval":0,
          "ssid":"MySSID",
          "username":"username",
          "password":"password",
          "isstatic":0,
          "ipaddr":"0.0.0.0",
          "gwaddr":"0.0.0.0",
          "dnsaddr":"0.0.0.0",
          "mask":"0.0.0.0"
       },
       "sntp":{
          "serverurl":"0.de.pool.ntp.org",
          "serverport":123
       }
    }
  3. Power down your XDK and insert the SD card containing the two files.
  4. Then power it up in bootloader mode.

XDK bootloader mode

To make sure the XDK is in bootloader mode, press and hold button 1 (marked with one dot) while flipping the ON/OFF switch to the ON position.

Flash your XDK device

  • Connect the XDK to your PC using the USB cable from the package.
    The XDK’s green LED will turn on to confirm that the XDK battery is charging.
  • Select BoschIoTSuite project in the Workbench and click Flash in the XDK Devices window.
  • The Workbench will now flash the XDK device with the firmware.
    The progress will be logged to the console.

XDK workbench 3.7

tip Client ID limitation

The MQTT 3.1 specification limits the client ID to 23 characters.
This is the default MQTT version used by the XDK Workbench 3.7. Therefore please make sure that your “<namespace> + <device id>” is within this limit.

If you want to use a longer client ID, you can also enable the MQTT 3.1.1 protocol in the XDK Workbench:

  • Open the ServalMqttAgent.c file
  • Change the “MQTT_VERSION_NUMBER” definition from “3” to “4”

XDK Workbench Console

The Workbench Console logs all info it gets from the XDK, as long as it is connected via the USB cable.

SD card can be reused

Once you have successfully connected the XDK to the Bosch IoT Suite and you see the sensor readings at the Developer Console, you can remove the SD card from the XDK as it is no longer needed.

The XDK firmware now knows the credentials of how to re-connect in case it runs out of battery and is re-started at a later point in time.

Check your work

  • Any problems with the connection will be logged to the console as well.
  • Upon successful connection, the XDK sensor values are transmitted to the Bosch IoT Suite.
  • When you remove the USB cable the green LED will be turned off, but don’t worry, the XDK should be still running.

3. Access your XDK sensor data

Back to the tasks ▲

Now, that the hard work was done, all the XDK sensor values are reported to your cloud infrastructure.

Each sensor measurement transmitted to the cloud will update the XDK values stored in the digital twin layer.

To check that everything went well, the developer console gets informed via the Things HTTP API – i.e. it behaves like a web application consuming the data reported by the XDK. The revision number is increased with each change (event) applied on the thing entity. Upon success all feature values are updated in regular time intervals.

Access your XDK sensor data

Only the latest values are stored

Bosch IoT Things will not store the full history of data reported by each sensor, but only the latest value of each.

Further reading

The XDK community is happy to share knowledge on all XDK questions.

https://developer.bosch.com/web/xdk/

Professional and commercial use

For using the XDK cloud connectivity in professional and commercial scenarios, do not hesitate to get in touch with us.

We would also offer to discuss further integration and usage options and next steps after building your first prototype towards series engineering and mass production to bring your product to life.

Please contact us via https://developer.bosch-iot-suite.com/support/.

4. Change your XDK configuration remotely

Back to the tasks ▲

The current firmware supports to remotely configure the XDK by setting two attributes: sensorPostInterval and enabledSensors. In this section you will be guided through the following examples:

Limitation of the free plan

In case you have booked a free plan, don’t let the XDK run day and night, as each changed value from the device to the Things service is counted as one transaction and the free plan is limited.

Example calculation: If your device sends out a message (<1 kB) each 30 seconds, you will have a monthly traffic of 86.400 transactions (i.e. 30 days x 24 hours x 60 min x 2) – which is within the free plan quota, given that the subscription really hosts one device only.

However, if you exceed these limits, the free plan might get blocked, and you will need to wait until the next calendar month.

Changing the interval – how often you need telemetry data

The attribute name must be exactly sensorPostInterval.

The value is an integer, and will be interpreted as the number of seconds to wait until the next message is sent.

Example

Change XDK configuration - Sensor interval

Attribute field entry

Make sure you don’t set the number into quotation marks.

E.g. "30" will not work as you might expect.

Select which sensors you need data from

The attribute name must be exactly enabledSensors.

The value is a JSON object holding the sensor names and a boolean – true to enable – false to disable – sending the sensor readings.

{
    "illuminance": true,
    "rotation": true,
    "humidity": true,
    "temperature": true,
    "pressure": true,
    "acceleration": true,
    "magneticStrength": true
}

Example

With some sensors disabled.

Setting the attribute values

Example - setting the attributes.

Result

Example - receiving data from the device.

tip XDK operation

In case you have booked a free plan, don’t let the XDK run day and night, as each changed value from the device to the Things service is counted as one transaction and the free plan is limited.

Example calculation

If your device sends out a message (<1 kB) each 30 seconds, you will have a monthly traffic of 86.400 transactions (i.e. 30 days x 24 hours x 60 min x 2) – which is within the free plan quota, given that the subscription really hosts one device only. However, if you exceed these limits, the free plan might get blocked, and you will need to wait until the next calendar month.

Attribute field entry

Make sure you don’t nest the JSON snippet given above into quotation marks.

E.g. "{ etc. }" will not work as you might expect.

Icon illustrating troubleshooting.

Troubleshooting

Back to the tasks ▲

This section contains troubleshooting tips that you can try on your own.

However, feel free to contact us in case you encounter other pitfalls
https://developer.bosch-iot-suite.com/support/
.

Check your SDK (XDK Workbench)

The XDK Workbench is a software developer kit equipped with XDK-specific packages.

Download the latest Workbench at https://developer.bosch.com/web/xdk/downloads.

Please note that version 3.7 or later is required.

Check for connectivity problems

  • WiFi problems are shown on the XDK Workbench console →  check the setting in config.txt
  • Connection from the board to Bosch IoT Hub not open
    • Check the setting in provisioning.json for the right configuration
    • In case your XDK will not be able to establish a connection to the Bosch IoT Suite
      • Either try again with provisioning the XDK with a short name (e.g. namespace + name max. 14 characters), and flash again your device.
        This limits only apply for XDK devices flashed with a firmware which uses a MQTT version 3.1 client, but not for the Bosch IoT Suite infrastructure in general.
        Or
      • If you want to use a longer client ID, you can also enable the MQTT 3.1.1 protocol in the XDK Workbench:
        • Open the ServalMqttAgent.c file
        • Change the “MQTT_VERSION_NUMBER” from “3” to “4”
  • Connection from Bosch IoT Hub to Bosch IoT Things not open  → check Things dashboard > Connections/Integrations
  • In case the telemetry data arrived at the Things service but could not be applied, navigate to Things dashboard > Connections > your connection > Metrics.
    The errors should be visible there.

Check for authorization problems

Devices via Bosch IoT Hub connection

Make sure that the authorization subject of the connection target is the same as within the policy.

Bosch IoT Things dashboard does not show the XDK at the Things tab

By default, if you have created the XDK in the context of the Bosch IoT Suite  OAuth token, the XDK should also be visible at the Things UI.

However, in doubt just see what is stored in the policy, or add explicitly your Bosch ID in it.

Check the XDK

The XDK comes with four different LEDs that are used to indicate its current status.

Here is an overview of the meaning of each LED:

Purpose Red Orange Yellow Green
Software on XDK is running (but it is not connected yet) Blinking every 1s
Connecting to Bosch IoT Suite Blinking every 1s On Blinking every 1s
Connection to Bosch IoT Suite failed Steady Blinking every 1s
Connection to Bosch IoT Suite established Steady
Sending data to Bosch IoT Suite Blinking every 1s Steady
Receiving data from Bosch IoT Suite Blinking every 1s Steady
Configuration load error (e.g. missing or malformed config.json or provisioning.json file on SD card) On On On
Your XDK is being charged via USB cable. On

If the USB cable had connected the XDK to your computer but the green LED is still off:

  • The battery is already fully charged,
  • Or your computer’s USB port did not recognize the plugged-in device;
    • the USB slot is not active;
    • the cord is placed incorrectly in the micro USB port, etc.
Animated GIF of the XDK blinking.
XDK works well