XDK API  3.6.0
Documentation
Virtual XDK Application Guide

XDK is presented in a playful fashion on a mobile device that is connected to XDK via BLE. Interacting with the physical XDK will manipulate the virtual XDK.


With version 3.0.0, XDK Workbench ships virtual XDK demo application as an additional example application VirtualXdkDemo.

To be able to use this demo, simply follow this steps:

The web links to get the Android/iOS App is given below:
Android App: Click_Here
iOS App: Click_Here

1.Virtual XDK application user guide:

The XDK user can interact with the physical XDK by moving the XDK or stimulating the sensors. These interactions are transmitted via Bluetooth LE to the Virtual XDK app on a iOS or Android based mobile device (phone or tablet). The current state of the sensors is visualized in the app user interface. The following section will introduce the user into the app usage. The displayed information and available user actions are explained.

1.1 Calibrating XDK

After starting the virtual XDK application on XDK, the sensors need to be calibrated. This has to be done after each startup of XDK, no matter if initiated by XDK Workbench (clicking reboot or flash) or by switching XDK off and on. Calibrating the sensors can be done by moving XDK in a figure of eight for 5 to 10 times.The following video illustrates the process Click_Here

1.2 App Startup

On app startup and whenever no connection to a device could be established, the Scanning for Devices Dialog will be shown.

1.3 Scan for Devices

When scanning for devices, the app will actively scan for any Bluetooth Low Energy device within reach. As long as the app is in scanning mode, the scanning for devices dialog will be shown.

1.3.1 Scanning for Devices Dialog

The dialog lists all Bluetooth Low Energy devices discovered within reach of the Bluetooth receiver. The received Bluetooth device name and address is listed in the dialog. The dialog will be closed immediately once the app is connected to a device. It will reopen when the connection is lost or has been manually closed by the Scan for Devices button.

1.4 Connecting to an XDK Device

A connection to a device is established by tapping on one of the devices listed in the Scanning for Devices Dialog. The dialog will disappear when the device is connected. The connection will be closed once the user taps on the Scan for Devices button or when the application is closed. Please note: You can connect to any device supporting the Bluetooth Low Energy protocol, but the app will only visualize the data from an XDK device which broadcasts in the expected format.

1.5 Live Update Mode

Once the connection with the XDK device is established, the app will signal the device to start sending notifications containing the sensor values. The sensor values will be immediately visualized by the central 3D model and the gauges arranged around it. In the center of the screen, a 3D model visualizes the current rotation of the XDK as indicated by the gyroscope and accelerometer sensors.

The following sensor values are shown on the left side:

The following sensor values are shown on the right side:

The following sensor values are shown on the Lower side:

The status of 3 LEDs is visualized (if it is on or off). Also, when a button on XDK is pressed it will be darker rendered in the app.

virtualxdk-01.jpg
Virtual XDK Mobile Application: Current measurement screen
virtualxdk-02.jpg
Virtual XDK Mobile Application: LEM Sensor config screen

1.5.1 The Settings Dialog

With this dialog, you can change basic settings for the app. You can show or hide the settings dialog by tapping on the cogwheel in the lower left corner of the screen.

1.5.1.1 Reset XDK

Pressing this button will immediately disconnect and reboot the physical XDK.

1.5.1.2 Reset Position

This button resets the rotation position of the device to a standard position. Pressing the physical button 1 on the XDK device has the same effect.

1.5.1.3 Scan for Devices

To disconnect the currently connected device, go to the Settings dialog and select Scan for Devices. When the device is successfully disconnected, the Scanning for Devices Dialog will be shown again.

1.5.1.4 Refresh Rate

The number next to the slider indicates the Bluetooth notification update frequency in Hertz. This controls how frequently the device will send value updates. The frequency can be adjusted using the slider. A higher number will reduce the latency between XDK sensor value updates and their visualization in the app, but the data transfer will be more brittle.

1.5.1.5 Device Name

This label indicates the name of the currently connected device, as advertised by the Bluetooth Low Energy protocol.

1.5.1.6 Device Address

The device address of the currently connected device is displayed here, as advertised by the Bluetooth Low Energy protocol.

1.5.1.7 XDK Software Version

This label displays the software version of the device firmware.

1.5.2 Calibrate display

For humidity, temperature, air pressure and light it is possible to calibrate display. Calibrating is useful for fine adjustments of the display according to current values of sensors. In order to calibrate type on the corresponding sensor icon, the calibrate dialog will appear.

1.5.2.1 Setting minimum and maximum values

By using Minimum and Maximum sliders you can adjust the range of displayed values, so that the display will be scaled within the chosen range.

1.5.2.2 Using predefined ranges

You can also automatically set the values of Minimum and Maximum by typing on ranges buttons. For example for temperature there are 3 predefined ranges: +-1, +-5, +-10. The current value of sensor will be then used to adjust Minimum and Maximum values according to the formulas given below as an example, thus the current value will be uses as the middle value for the display.
Example:

1 Minimum = CurrentValue - Range
2 Maximum = CurrentValue + Range

1.5.2.3 Resetting range

In order to reset Minimum and Maximum values to the default range type, click on the Reset button.

1.5.3 Resetting XDKs reference position

The Virtual XDK application will always show XDK in the initial position (look from upwards, buttons facing top of the screen). Virtual XDK does not know the relative orientation of the physical XDK and your mobile device. To align those two, place the physical XDK in parallel to the mobile device and press button 1 on XDK. The virtual XDK application will record an offset and apply it to all subsequent measurements. Pressing button 1 again will update the offset.

2.Virtual XDK embedded Firmware design

This section explains how does the embedded firmware designed for this application The XDK Firmware has the following tasks:

2.1 XDK Initialization

After startup, the XDK firmware calls a function Init() which initialize required subsystems of the application like Ble stack , Sensors, HMI like button and
initialize the timers for the sensor sampling, the high data rate service and for test purposes,a sensor simulation timer.

2.2 XDK BLE Profiles, Services, Characteristics and Attributes

BLE uses Profiles,Services,Characteristics and Attributes for exchanging data between server and client. Here the embedded device acts as a BLE server.
The Information concerning the services, characteristics and attributes are stored in the so called "Attribute Database" inside the BLE stack. This database
is initialized before starting the BLE stack.

Note
More information about the introduced services etc.and the concerning data can be found under the section 3.Overview XDK UUID's Services, Characteristics and Attribute Types and
The packaging of the high data rate characteristics can be found under the section 4.Data format for High priority data service

2.3 XDK Gathering sensor data

There are 2 functions gathering and handling the sensor data.

3.Overview XDK UUID's Services, Characteristics and Attribute Types

This section gives information related to the BLE services and characteristic UUID used for this virtual XDK application

3.1 Accelerometer Sensor Service:

Service Characteristic Attribute-Type UUID
XDK-Accelerometer NA NA 5a211d40-7166-11e4-82f8-0800200c9a66
NA Accelerometer X-Axis int16_t 5a211d41-7166-11e4-82f8-0800200c9a66
NA Accelerometer Y-Axis int16_t 5a211d42-7166-11e4-82f8-0800200c9a66
NA Accelerometer Z-Axis int16_t 5a211d43-7166-11e4-82f8-0800200c9a66

3.2 Gyro Sensor Service:

Service Characteristic Attribute-Type UUID
XDK-Gyro NA NA aca96a40-74a4-11e4-82f8-0800200c9a66
NA Gyro X-Axis int16_t aca96a41-74a4-11e4-82f8-0800200c9a66
NA Gyro Y-Axis int16_t aca96a42-74a4-11e4-82f8-0800200c9a66
NA Gyro Z-Axis int16_t aca96a43-74a4-11e4-82f8-0800200c9a66

3.3 Light Sensor Service:

Service Characteristic Attribute-Type UUID
XDK-LightSensor NA NA 38eb02c0-7540-11e4-82f8-0800200c9a66
NA Light Sensor Millilux uint32_t 38eb02c1-7540-11e4-82f8-0800200c9a66

3.4 Noise Sensor Service:

Service Characteristic Attribute-Type UUID
XDK-NoiseSensor NA NA 01033830-754c-11e4-82f8-0800200c9a66
NA Noise Sensor DbSpl uint8_t 01033831-754c-11e4-82f8-0800200c9a66

3.5 Magnetometer Sensor Service:

Service Characteristic Attribute-Type UUID
XDK-MagnetometerSensorNA NA 651f4c00-7579-11e4-82f8-0800200c9a66
NA Magnetometer Sensor X-Axis int16_t 651f4c01-7579-11e4-82f8-0800200c9a66
NA Magnetometer Sensor Y-Axis int16_t 651f4c02-7579-11e4-82f8-0800200c9a66
NA Magnetometer Sensor Z-Axis int16_t 651f4c03-7579-11e4-82f8-0800200c9a66
NA Magnetometer Sensor Resistance int16_t 651f4c04-7579-11e4-82f8-0800200c9a66

3.6 Environment Sensor Service:

Service Characteristic Attribute-Type UUID
XDK-EnvironmentSensor NA NA 92dab060-7634-11e4-82f8-0800200c9a66
NA Pressure Sensor uint32_t 92dab061-7634-11e4-82f8-0800200c9a66
NA Temperature Sensor int32_t 92dab062-7634-11e4-82f8-0800200c9a66
NA Humidity Sensor uint32_t 92dab063-7634-11e4-82f8-0800200c9a66

3.7 High Data Rate Service:

Service Characteristic Attribute-Type UUID
XDK High Data Rate Service NA NA c2967210-7ba4-11e4-82f8-0800200c9a66
NA High Priority Array uint8_t[20] c2967211-7ba4-11e4-82f8-0800200c9a66
NA Low Priority Array uint8_t[20] c2967212-7ba4-11e4-82f8-0800200c9a66

3.8 Control XDK Service:

Service Characteristic Attribute-Type UUID
XDK Control ServiceNA NA 55b741d0-7ada-11e4-82f8-0800200c9a66
NA Start Sensor Sampling and Notifications uint8_t 55b741d1-7ada-11e4-82f8-0800200c9a66
NA Change Sensor Sampling Rate uint32_t 55b741d2-7ada-11e4-82f8-0800200c9a66
NA Reboot XDK uint8_t 55b741d3-7ada-11e4-82f8-0800200c9a66
NA Get Firmware Version uint32_t 55b741d4-7ada-11e4-82f8-0800200c9a66

4.Data format for High priority data service

This section gives information of the data format of High priority given from the XDK device to virtual XDK application

4.1 High Priority Data:

Bytes Data
0 & 1Accelerometer x-Axis
2 & 3Accelerometer y-Axis
4 & 5Accelerometer z-Axis
6 & 7Gyro x-Axis
8 & 9Gyro y-Axis
10 & 11Gyro z-Axis

4.2 Low Priority Data – Message 1:

Bytes Data
0Message ID 0x01
1,2,3&4Light Sensor
5Noise Sensor (Reserved)
6,7,8&9 Pressure Sensor
10,11,12& 13Temperature Sensor
14,15,16&17Humidity Sensor
18SD-Card detect status
19Button status – encoded as bit-field: Bit 0: Button 1; Bit 1: Button 2

4.3 Low Priority Data – Message 2:

Bytes Data
0Message ID 0x02
1&2Magnetometer x-Axis
3&4Magnetometer y-Axis
5&6 Magnetometer z-Axis
7&8 Magnetometer Resistance
9LED status – encoded as bit-field: Bit 0: yellow LED; Bit 1: orange LED; Bit 2: red LED
10 to 13RMS voltage of LEM sensor in micro Volts
14Lemsensor Connection status - true(1): connected; false(0): disconnected
15 to 18RMS Value of Noise sensor in millivolts

All rights reserved. The use is subject to the XDK SDK EULA by Bosch Connected Devices and Solutions GmbH.
This documentation file has been automatically generated on Thu Mar 14 2019 19:12:49 by doxygen 1.8.8