This example provides a prototype of a real world device integration - based on the Octopus board (ESP8266). It shows how to subscribe to Bosch IoT Suite for Asset Communication and how to use its API to provision a device.
The octopus will be able to connect automatically to a given wireless internet access, to send telemetry data to the Things service, and to react to messages which can be sent by a web application.
The device will send telemetry data to the Things service, and will react to messages, which can be sent by a web application, e.g. octopus-frontend.
The example is divided into the following steps:
- About the Octopus board
- Subscribe to the Bosch IoT Suite for Asset Communication
- Register the device via Device Provisioning API
- Prepare the Octopus device with Arduino
The Octopus board is created by Guido Burger. Its original purpose was to be used as a teaching tool for hackatons in secondary schools in Germany. It features a number of sensors, and the ability to connect sensors, inputs, and actuators in a relatively simple way.
You can buy it in the Fab-Lab.eu Tindie shop where you also find more information and the source code for the schematics. While Guido Burger offers some boards in his Tindie store, overall the Octopus board is a not-for-profit activity. The Octopus board is a small board based on a ESP8266 chip that can be programmed e.g. using the Arduino IDE. The special thing about this board is, that it already contains components that makes it a ready-to-run starter-kit to experiment with the Internet of Things. Here you can see a detailed description of the official Octopus board used for the "Nationaler IT Gipfel".
Source: Tindimedia
For example, the Bosch IoT Suite edition board contains the following sensors:
- Bosch Sensortec BNO055 9-axis absolute orientation sensor – provides acceleration, gyroscope, spatial positioning, magnetic field etc.
- Bosch Sensortec BME680 environmental sensor – provides temperature, humidity, air pressure, altitude, air quality
All services can be booked online at Bosch IoT Suite portal. For your subscription, you will need a Bosch ID for authentication. If you don't have a Bosch ID yet, feel free to register a new account. Once you are successfully registered, you will be redirected to the Bosch IoT Suite portal.
You will need to subscribe to the Bosch IoT Suite for Asset Communication package - a ready-to-use integration of Bosch IoT Hub and Bosch IoT Things. In order to book your Bosch IoT Suite for Asset Communication, please stick to the Getting Started.
Once you have an own service instance of the package, you can define a namespace for your solution. All things and policies are required to be created with a namespace. In order to set a namespace, go to your Service Subscription page of the Bosch IoT Suite. Click Go to Things Dashboard and navigate to the Namespace tab. There, you can type in your namespace in the dedicated input field.
The namespace
must conform to the reserve domain name notation:
- must start with a lower- or uppercase character from a-z
- can use dots
(.)
to separate characters - a dot
(.)
must be followed by a lower- or uppercase character from a-z - numbers can be used
- underscore can be used
Furthermore, you will get a pre-configured connection between Hub and Things. You can see it at the Things dashboard, on tab Connections/Integrations.
We will use the telemetry, event as well as the command & control pattern of the Bosch IoT Hub.
With just one request at our API, you will be able to register a device (in the context of the Bosch IoT Hub service) and create a digital twin representation of this device (in the context of the Bosch IoT Things service) in thing notation.
In order to do so, you will need a Suite authorization token and a valid request body for your device registration.
Get a new Suite auth token by following the steps of the Create a Suite Auth Client section of the package documentation. Upon request, the client will issue a token, which is valid 60 minutes.
Copy the token to your clipboard.
Subsequently, open the Bosch IoT Suite - Device Provisioning API, where you can execute your device registration.
You will need to do the following steps:
- Authorize your API request via Suite authorization token, by clicking on the Authorize button on the upper right corner and paste the token into the dedicated input field.
- Provide your service-instance-id on the required input-field. You can find your service-instance-id under the Show Credentials button of your Service Subscription page in the Bosch IoT Suite.
- Edit the request body to send a valid message to the server.
Your request body should contain the following information:
{
"id": "<your-namespace>:<your-device-id>",
"hub": {
"device": {
"enabled": true
},
"credentials": {
"type": "hashed-password",
"secrets": [
{
"password": "<any-password>"
}
]
}
},
"things": {
"thing": {
"definition": "com.bosch.iot.suite.example.octopussuiteedition:OctopusSuiteEdition:1.1.0",
"attributes": {
"manufacturer": "<my-awesome-company>"
},
"features": {
"acceleration": {
"definition": [
"com.bosch.iot.suite.example.octopussuiteedition:Accelerometer:1.1.0"
]
},
"ambient_temperature": {
"definition": [
"com.bosch.iot.suite.example.octopussuiteedition:Temperature:1.1.0"
]
},
"orientation": {
"definition": [
"com.bosch.iot.suite.example.octopussuiteedition:MultipleAxisJoystick:1.1.0"
]
},
"linear_acceleration": {
"definition": [
"com.bosch.iot.suite.example.octopussuiteedition:Accelerometer:1.1.0"
]
},
"magnetometer": {
"definition": [
"com.bosch.iot.suite.example.octopussuiteedition:Magnetometer:1.1.0"
]
},
"gravity": {
"definition": [
"com.bosch.iot.suite.example.octopussuiteedition:Accelerometer:1.1.0"
]
},
"temperature": {
"definition": [
"com.bosch.iot.suite.example.octopussuiteedition:Temperature:1.1.0"
]
},
"humidity": {
"definition": [
"com.bosch.iot.suite.example.octopussuiteedition:Humidity:1.1.0"
]
},
"pressure": {
"definition": [
"com.bosch.iot.suite.example.octopussuiteedition:Barometer:1.1.0"
]
},
"angular_velocity": {
"definition": [
"com.bosch.iot.suite.example.octopussuiteedition:Gyrometer:1.1.0"
]
},
"voltage": {
"definition": [
"com.bosch.iot.suite.example.octopussuiteedition:Voltage:1.1.0"
]
}
}
}
}
}
You will need to edit the following placeholders:
- "id": "
<your-namespace>:<your-device-id>
" - Use your created namespace followed by:
and your specific thing name. - "password": "
any-password
" - Type in a secure password in plain text. It will be hashed on our server. - "manufacturer": "
<my-awesome-company>
" - Type in your company Name.
Click Execute to submit the request.
Upon success, you have created a device in the context of Bosch IoT Hub associated with credentials, and an empty digital twin in thing notation associated with a default policy.
- An Arduino or another developer board like "Funduino" etc.
This example will work with an Octopus-board,
however, most of the code will work with every other board with an ESP8266 on it. - Download the Arduino IDE
If you are behind a proxy, configure the proxy settings.
File > Preferences > Network and add SSL certificates (e.g. xxx.crt) to ${ArduinoDirectory}\java\lib\security\cacerts using keytool
- Add the ESP8266 Platform to the IDE, see ESP8266 Arduino Platform (tested with 2.6.0 and 2.7.4).
- Install the following libraries (Sketch > Include Library > Manage Libraries)
- Adafruit BME680 (tested with 2.0.1)
- Adafruit BME280 (tested with 2.2.2)
- Adafruit BNO055 (tested with 1.3.0)
- Adafruit NeoPixel (tested with 1.4.0)
- Adafruit Unified Sensor (tested with 1.1.2)
- PubSubClient (tested with 2.7.0)
- ArduinoJson (tested with 6.18.5)
- ESP8266-ping (tested with 2.0.1)
- IMPORTANT: Edit the file
${ArduinoDirectory}/libraries/pubsubclient/src/PubSubClient.h
and set theMQTT_MAX_PACKET_SIZE
to2048
. - Change the Board (Tools > Board > Adafruit Feather HUZZAH ESP8266)
Attach the Octopus board to your development machine via USB cable.
In case you never used the board before, first of all try to find out on which COM port it communicates. In case the driver is not installed yet, check https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers. In Arduino select Tools > Port > the port of your device. Then, open the Arduino serial monitor, which will later display what the device is sending.
The Arduino Sketch we have prepared publishes the sensor information via the Bosch IoT Hub to Bosch IoT Things.
Open octopus-hub/octopus-hub.ino
in your Arduino IDE.
All properties relevant for the connection to our cloud services have to be set in octopus-hub/settings.h
.
You can use octopus-hub/settings-template.h
as a template. Replace all XXX
placeholders with your configuration properties and write your credentials within the " "
quotation marks.
The Arduino IDE knows the board as "Adafruit Feather HUZZAH ESP8266”.
Use the Arduino tooling to verify that the project compiles. Otherwise, fix the issues.
Use the Arduino tooling to flash the Octopus.
Upon success, the Octopus LEDs should be blue and green.
The device will connect automatically to Bosch IoT Hub, which forwards the data to Bosch IoT Things.
The prepared Arduino sketch will connect to the Bosch IoT Hub with TLS standard, send and receive MQTT messages, read sensors data, and depending on incoming messages (from the web application) it will set new values for the LED on the board.
At the Things dashboard, navigate to the Things tab, there your new digital twin should be visible. As long as the simulator sends data, the chart view should show the changes.
The simulator will also open up a receiver which can react on incoming messages (from a web application), and set new values for the LED on the simulated board.
You can try it out either at the Developer Console, or you can try out the example "octopus-frontend".
Feel free to play with the code. Happy coding!