This offer is only addressed to commercial customers including freelancers and entrepreneurs. All prices exclude all taxes.
Subscribe Find out first about new and important news
  • Share via email
  • Subscribe to blog alert

Deploying Bosch IoT Gateway Software for device connectivity with the Bosch IoT Suite services

The aim of this tutorial is to provide a short manual describing how to connect supported DCF devices to a Bosch IoT Gateway Software framework instance and how to transmit the telemetry data of the connected device to the Bosch IoT Suite.

This tutorial is split into two main parts:

I. Deployment and configuration

1. Obtaining an evaluation version of Bosch IoT Gateway Software

A link to a 30-day evaluation trial of Bosch IoT Gateway Software can be found on the Bosch IoT Suite homepage.

After completing the registration form, it takes approximately one working week for the system to send an email with the download link to the specified address.

2. Choosing a target platform

All instructions in this tutorial refer to a Debian-based Linux platform. To use the Bosch IoT Gateway Software with a different operating system and environment, it is possible to follow the same approach described here, but you will have to modify the used commands accordingly.

3. Deploying a Java VM on the target

The Bosch IoT Gateway Software is an extensible application framework written in Java that requires an available Java virtual machine in the same operating environment. If not already available, a Java VM can be deployed on a Debian-based target platform using the following command:

sudo apt-get install oracle-java8-jdk

If necessary, look up the Java installation location and append it as a JAVA_HOME property in the global user profile:

echo export JAVA_HOME=”<java location>” | sudo tee -a /etc/profile

4. Deploying a Bosch IoT Gateway Software image on the target

There are several ways of deploying a Bosch IoT Gateway Software image on a target platform. On systems with a graphical or textual user environment, you can usually follow the product installation wizard and install the image in the preferred target location. For headless systems, the usual way is to perform the installation on another system (host), compress the installed image, and transfer it to the target.

The following steps are based on a headless target platform that can be accessed remotely via SSH. The SSH connection is used to copy and install the compressed image file:

  • Log in via SSH on the target and create a dedicated folder for deploying the image:
sudo mkdir -p /opt/BIGS/RELEASES

sudo chown <username> /opt/BIGS/RELEASES
  • Transfer the image from the host via SSH and extract it into the dedicated folder on the target:

tar xzf /<image location>/9.x.y.tgz

5. Start the framework instance for a first time

The first time a standard Bosch IoT Gateway Software framework instance is started, only the core set of framework modules are installed and started. Additional modules can be manually installed using the built-in framework console command “kitman”, for example. The following steps show how to find and install all additional modules required for this tutorial.

  • Start the framework for the first time:
cd /opt/BIGS/RELEASES/9.x.y/runtime/osgi/bin/vms/jdk


Note: You can exit and stop the framework at any time with the following command:

  • Install the “OSGi R5 Compendium Bundles” module kit:

This module kit contains several OSGi compendium bundle implementations for the Bosch IoT Gateway Software.

fw>$kitman.i "OSGi R5 Compendium Bundles"

Installing, please wait…  
	… <skipped> …
Kit OSGi R5 Compendium Bundles installed.
  • Install the “Functional Item Management” module kit:

Functional items are the preferred way of describing connected IoT devices (including operations, properties, units etc.) in the Bosch IoT Gateway Software.

fw>$kitman.i "Functional Item Management Web Admin"

Installing, please wait…  
	… <skipped> …
Kit Functional Item Management Web Admin installed.

The above action also installs the web-based administration module for the framework as a dependency. See “Management via Web Console” for more information on how to use it for administering the underlying Bosch IoT Gateway Software framework.

  • Install the “Device Access” module kit:

This module defines a layer for abstracting the physical method of connecting and communicating with IoT devices via the Bosch IoT Gateway Software.

fw>$kitman.i "Device Access Web Admin"

Installing, please wait...  
… <skipped> …
Kit Device Access Web Admin installed.
  • Install the “History” module kit:

This module provides methods of storing and caching history and bulk data received from IoT devices attached to the Bosch IoT Gateway Software.

fw>$kitman.i "History"

Installing, please wait...  
… <skipped> …
Kit History installed.

Note: Make sure that an SQLite shared library is available in the system environment, since the current implementation of the history module relies on it.

  • Install the “Bluetooth LE DA Support” module kit:

The modules from this kit provide support for Bluetooth Low Energy devices in the Bosch IoT Gateway Software. In addition, device access abstraction layer mapping is readily available for all standard GATT services and characteristics, as well as an API for mapping custom services.

fw>$kitman.i "Bluetooth LE DA Support"

Installing, please wait...  
… <skipped> …
Kit Bluetooth LE DA Support installed.

Note: Make sure that the BlueZ protocol stack (version 5.50 or higher required) is installed in the system environment, since the Bluetooth module implementation uses the installed D-Bus API.

6. Registering the instance as a device in the Bosch IoT Hub

In order to push telemetry data available in the Gateway Software upstream to a Bosch IoT Hub service consumer, the framework instance must be registered as a Hub device. One way to do so using the Device Manager REST API of the OSGi Adapter service is shown in this tutorial.

Prior to using the Device Manager API, you must first carry out authorization using the device registry credentials provided by your Hub service instance. Use the “Authorize” button at the right corner of the Swagger UI to open the login frame, and enter the device registry credentials there.

As the next step, select the “/provisioning/register” REST call to register the framework instance as a Hub device. The framework must be registered as a device in one of your Bosch IoT Things service namespaces. Therefore, as the value of the unique “deviceId” device identifier parameter, you need to specify both the Things namespace and the new unique device name as follows:

<namespace>:<device name>

For example:


In the request body, specify the password for the new device as the value of the “devicePass” parameter. The combination of device ID and password allows the authentication of the framework instance with the Hub service via the OSGi Adapter.

Execute the REST call, and, if successful (response code 201), a set of configuration parameters is received in response (included in the response body). Copy and save all parameters to a local file called “osgi.adapter.prs”, since they are required for proper authorization and communication with the Hub service instance.

Transfer the “osgi.adapter.prs” configuration parameter file to the target platform and save it in the following framework folder:


In order to instruct the framework to load the OSGi Adapter configuration file on startup, you will need a separate startup file:

cd /opt/BIGS/RELEASES/9.x.y/runtime/osgi/bin/vms

cat > << EOF
export EXTPRS="$EXTPRS;../osgi.adapter.prs"

chmod 755 /opt/BIGS/RELEASES/9.x.y/runtime/osgi/bin/vms/

Restart the framework instance to apply the new configuration changes.

7. Provisioning the framework instance with an OSGi Adapter module

At the time of writing this document, the OSGi Adapter framework module was not part of the official Bosch IoT Gateway Software evaluation release and must be downloaded separately from the Device Manager REST API provided by the OSGi Adapter service.

The current way of downloading the module files is by invoking the “/provisioning/addon” REST call. Execute the call and save the module archive file provided in the “dm.things.agent-x.y.z.esa” response on the local file system.

The next step is to deploy the OSGi Adapter “dm.things.agent-x.y.z.esa” module archive on the Bosch IoT Gateway Software instance. To do this, transfer the ESA file module to a known location on the target system, and install it on the framework as described below:

fw>$sub.install <archive_path>/dm.things.agent-x.y.z.esa 0 -s
Successfully installed subsystem:3

Installation is complete. It is now possible to access the Bosch IoT Gateway Software instance and all devices attached to it through the services of the Bosch IoT Suite.

II. Connecting and managing supported DCF devices

1. Connecting a Bosch XDK device

  • Prerequisites:

This tutorial assumes that you already have a Bosch XDK device, you are already registered with an account on the XDK developers’ portal, and you have downloaded and installed the latest XDK SDK development environment.

  • Flashing and configuring the XDK for connection with the Bosch IoT Gateway Software:

In other words, you have to prepare an SD card and create a configuration file instructing the XDK firmware how to join the WLAN environment and how to connect to the framework instance.

You will need a FAT32-formatted SD card with a plain file system structure where all folders (including hidden ones) have been removed. Otherwise, the XDK firmware will not be able to find and read its configuration file.

Next, create a file called “config.txt” on the SD card and enter your access configuration settings there as shown below:

# Wifi access point connection settings
WLAN.PASS=<Your WLAN Password>
# Address and port of the Bosch IoT Gateway's XDK adapter
SERVER.IPV4=<The IPv4 address of the framework in your WLAN network>
# Frequency for sending sensor measurements data (in seconds)

Place the SD card in the card slot of your XDK.

Using the XDK SDK, flash the firmware image available here on your XDK.

  • Deploying the XDK DA module bundle on the Bosch IoT Gateway Software instance:

Download the module file here and copy it to the following folder on the target:


Start the framework instance and, in the command prompt, install the bundle by entering the following command:

fw>$i -s
  • Turning on the XDK and checking that the framework console output is successfully connected:
Creating device for XDK with UID: xx:xx:xx:xx:xx:xx

2. Pairing a Bluetooth Low energy device

  • Remarks:

At the moment, this tutorial only describes how to pair and manage BLE devices using the Functional Item Manager user interface available in the Bosch IoT Gateway Software. With the official GA release of the Gateway Software Adapter, this tutorial will be replaced with steps for pairing and managing BLE device using the APIs from Bosch IoT Things.

For simplification, this tutorial assumes the Bosch IoT Gateway Software instance is running on a localhost and its WebUI is available on HTTP port 8080. Replace both in the URL below according to your network setup.

All subsequent steps assume that the Functional Item Manager WebUI is open in a web browser.

  • Locate an available BLE controller:

On the main FIM page, look for a da:device with a “BLE Controller” tag, and then open its FI management page:

  • Run a BLE device scan:

On the controller FI management page, locate and execute the “start” operation.

After successful execution, the controller FI property “started” switches to “true”. Then go back to the main FIM page.

  • Pair a detected BLE device:

When the BLE controller is in discovery mode, the selected BLE device on the opposite side must be put into pairing mode. Otherwise, the controller will not find it.

Note: Please check the user manual of the device you are trying to pair. For example, a Bosch TDL device requires a short (1 sec) button press whereas a Bosch CISS is automatically put into pairing mode when powered on.

The example below shows a Bosch TDL device in pairing mode that has been detected by the BLE controller:

To pair the newly detected device, simply open its FI management page, and execute the “pair” operation:

When successfully paired, the “deviceState” property switches to “Connected”:

3. Managing a Bosch TDL BLE device

After a TDL device has been paired and connected, several functional items are registered and displayed on the main FIM page:

The major use scenarios based on the registered functional items are described below:

  • Unlocking a connected TDL device

Some of the TDL functions require unlocking the device prior to using them. This includes functions such as system configuration, thresholds configuration, and logging stop.

Entering the configured 4-digit PIN using the “PIN Dashboard” functional item is necessary to unlock a TDL (default setting is 0000 for new devices).

  • Invoking TDL operations and modifying configuration settings

The various configuration settings and system operations available on a TDL device can be accessed from the “System Dashboard” functional item.

Note: As mentioned above, all configuration fields and most operations require successful PIN authentication. Otherwise, a status error is displayed requesting the unlocking of the device with the correct PIN.

  • Changing a threshold settings

Threshold setting configurations are split into multiple functional items depending on the sensor type and threshold type.

The example below sets a new value for the maximum temperature threshold.

  • Starting and stopping bulk data logging

The starting or stopping of bulk data logging can be activated by toggling the “toggleLogging” operation on the “System dashboard” functional item. Please note that, after a connected TDL has been instructed to begin bulk data logging, it is calibrated and then automatically disconnects.

  • Viewing the violations summary

The threshold violation summaries are split between multiple functional items for each of the sensor thresholds.

Note: Viewing the violation summaries does not require the logging to be stopped and can be used to take a quick look at the TDL status.

  • Retrieving the bulk data history

The bulk data log of a connected TDL device can be retrieved with the help of the “Bulk transfer dashboard” functional item.

Note: All bulk data events that were retrieved from a TDL device will be stored in the history database of the Bosch IoT Gateway Software that the TDL is connected to. To access the information via Bosch IoT Things, you must use the “HistoryAdmin” twin associated with that Gateway Software instance and not the features of the TDL twins.

4. Managing a Bosch CISS BLE device

In contrast to the TDL, a CISS device performs measurements and streams the selected sensor values in real time. Therefore, it requires a live connection to a BLE server such as the Bosch IoT Gateway Software in order to transfer the data to an end user application attached to the Bosch IoT Suite.

Connecting a CISS device to the Bosch IoT Gateway Software triggers the registration of a number of functional items representing the various device functionalities.

The major use case scenarios based on the registered functional items are described below:

  • Selecting a sensor set and toggling the streaming of measurements

The sensors and measurement interval can be selected in the “Configuration dashboard” functional item.

The same functional item is used to enable or disable streaming and in turn instructs the CISS to start or discontinue the streaming of measurement data.

  • Viewing the sensor measurement values

Like the TDL threshold summary, the CISS sensor measurement data is split between multiple functional items.

As an example, the current status of the temperature sensor on a connected and streaming CISS device:

5. Accessing a Bosch CISS BLE device twin on Bosch IoT Things

This short topic contains a few examples of using the Bosch IoT Things service for accessing the temperature sensor value of a CISS BLE device connected to a Bosch IoT Gateway Instance. For more information, please refer to the official Bosch IoT Things documentation.

  • Go to the Swagger UI of your Things instance and log in with your credentials
  • Once authorized, you can use the Search API to find your CISS sensor. In this example, we use the BLE address of the CISS device as a filter criterion:

Open the “/search/things” GET API and specify the Things namespace used by your Bosch IoT Gateway Software instance:


Then use the filter field to show only devices with an attribute equal to the address of the CISS sensor:

filter: eq(attributes/address, “5F:03:55:E5:33:53”)

If the namespace and filter were correct, execute the request to return all information the twin has about your CISS device:

  "items": [
      "thingId": "<… skipped …>",
      "policyId": "",
      "attributes": {
<… skipped …>
        "hardware__version": "CISS_R2.0000",
        "address": "5F:03:55:E5:33:53", 
<… skipped …>
  • Using the “/things” GET API and the information from the search query, it is now possible to look specifically for the temperature sensor value part of the twin content:

To do this, you have to specify the Thing ID assigned to your CISS device (available in the information retrieved from the search query):


Then filter the temperature sensor value feature only (again available in the information retrieved from the search query):

fields: ?fields=thingId,features/da%3Aitem%3ABluetoothLE%3AE4%3AA7%3AA0%3AAD%3A64%3A24%2F5F%3A03%3A55%3AE5%3A33%3A53%2F7500%2F2%3ASensor/properties/status/value/value

Executing the query returns the current value of the temperature sensor available in the Things twin for your CISS device:

    "features": {
      "da%3Aitem%3ABluetoothLE%3AE4%3AA7%3AA0%3AAD%3A64%3A24%2F5F%3A03%3A55%3AE5%3A33%3A53%2F7500%2F2%3ASensor": {
        "properties": {
          "status": {
            "value": {
              "value": {
                "value": "25.7"
Cookie Information

This website uses cookies for reasons of functionality, comfort, and statistics. If you consent to this use of cookies, please click ”Ok“. If you like to disable the cookies for webtracking, please click here. For more information see our Privacy Policy