Skip to content

Latest commit

 

History

History
336 lines (291 loc) · 12.9 KB

BlueST-SDK.md

File metadata and controls

336 lines (291 loc) · 12.9 KB
Raw

BlueST SDK v2

BlueST is a multi-platform library (Android and iOS supported) that permits easy access to the data exported by a Bluetooth Low Energy (BLE) device that implements the BlueST protocol.

BlueST Protocol

Advertise

The library will show only the device that has a vendor-specific field formatted in the following way:

Length (Byte) 8 1 1 2 1 1 1 3 6
Name Board Name Length Advertising Type Manufacter ID SDK Version Device ID Firwmare ID Option bytes Device MAC (optional)
Value 0x09XXXXXXXXXXXXXX 0x09/0x0F 0xFF 0x30 + 0x00 (STM) 0x02 0xXX 0xXX 0xXXXXXX 0xXXXXXXXXXXXX

You should use a value between 0x90 and 0xFF for your custom board.

  • The Firmware ID is a byte that uniquely identifies the firmware that runs on a specific board. Since the values 0x00 and 0xFF are reserved, up to 254 different firmware types can be supported on any single board. The board/firmware capabilities are uniquely identified by the Device ID / Firmware ID combination. The client that needs to determine capabilities of the discovered board needs to use a lookup table where an extensive description of the firmware features can be found. This table will be in JSON format and can be obtained by the client using the procedure described later in this document. The meaning of the three bytes that follow the “Firmware ID” field in the advertisement frame depend on the firmware ID value.
Firmware ID Usage Comment
0x00 Reserved Used to extend the number of
firmware versions beyond 254
0x01-0xFE Assigned to official firwmare releases
0xFF Experimental firmware Not listed in official Database

The official database can be found at: https://github.com/STMicroelectronics/appconfig Looking the tag associated to BlueST-SDK version (example: V4.16.0 -> tag 4.16.0)

  • There are at most three option bytes available, whose meaning can be defined by the firmware developer to convey different types of information.
    The translation between each byte and its meaning is performed by the client, for example the mobile application, according to the mapping table defined in the JSON file. Each byte can be interpreted using one of the following options:
    • An integer, which can be adjusted using an offset and a scaling factor
    • A string enumeration, i.e. the byte is used as an index of a string array
    • An icon enumeration, i.e. the byte is used as an index of an array of icons

It should be noticed that option bytes are sent in the advertisement frame so they can be processed and visualized by client without establishing a BLE connection with the target. This can be useful to notify warning and alarms, to report status or specific measurements.
A client can visualize information carried in custom option bytes received by multiple targets simultaneously.

Integer format An example of an integer custom byte being used to report the battery level is shown below.

{ 

  "format": "int", 
  "name": "battery", 
  "negative_offset": 0, 
  "scale_factor": 10, 
  "type": "%" 
}

String enumeration format

{ 
  "format": "enum_string", 
  "name": "alarm", 
  "string_values": [ 
    { 
      "display_name": "No Alarm", 
      "value": 0 
    }, 
    { 
      "display_name": "Low Battery", 
      "value": 1 
    }, 
    { 
      "display_name": "SD Full", 
      "value": 2 
    } 
  ], 
  "type": "string" 
}

Icon enumeration format

{ 
    "format": "enum_icon", 
    "icon_values": [ 
      { 
        "comment": "icon for Log on going", 
        "icon_code": 1, 
        "value": 0 
      }, 
      { 
        "comment": "icon for low battery", 
        "icon_code": 4, 
        "value": 1 
      }, 
      { 
        "comment": "icon for SD full", 
        "icon_code": 10, 
        "value": 2 
      } 
    ], 
    "name": "status", 
    "type": "icon" 
}
  • The Device MAC field exposes the MAC ADDRESS of a device. This field is optional and useful only for obtaining the device MAC address on an iOS device.

For more information, see the user manual .

Characteristics/Features

The SDK is searching in all the services the know characteristics.

  • The features that have an UUID such as: XXXXXXXX-0001-11e1-ac36-0002a5d5c51b, and are called Basic Feature and a single bluetooth characteristics can export multiple of this basic features. The first 32bits are interpreted as the feature mask, if they are set to 1 it means that the characteristics is exporting the data of that feature. In case of multiple features mapped in a single characteristic, the data must be in the same order as the bit mask. The characteristic data format must be:
Length (Byte) 2 >1 >1
Name Timestamp First Feature Data Second Feature Data .....

The first 2 bytes are used to communicate a time stamp. This is especially useful for recognizing any data loss. Since the BLE packet max length is 20 bytes, the max size for a feature data field is 18 bytes.

  • The other ST characteristics have the format: XXXXXXXX-0002-11e1-ac36-0002a5d5c51b and are called Extended Feature. This features could not be exported on a single bluetooth caracteristic

  • The last ST characteristics have the format: XXXXXXXX-0003-11e1-ac36-0002a5d5c51b and are called General Purpose Feature. This features are not present inside the SDK but the Application is able to decode them parsing the Firmware model where there is a section that explains how this features must be read. For example

"characteristics": [
   {
   "name": "test_uint16",
   "uuid": "00000000-0003-11e1-ac36-0002a5d5c51b",
   "uuid_type": 3,
   "format_notify": [
     {
       "length": 2,
       "name": "timestamp"
     },
     {
       "length": 2,
       "name": "test_uint16",
       "type": "UInt16",
       "offset": 0.0,
       "scalefactor": 1.0,
       "min" : 100,
       "max" : 200,
       "unit": "m/s"
     }
   ]
 },
 {
   "name": "test_int32",
   "uuid": "00010000-0003-11e1-ac36-0002a5d5c51b",
   "uuid_type": 3,
   "format_notify": [
     {
       "length": 2,
       "name": "timestamp"
     },
     {
       "length": 4,
       "name": "test_int32",
       "type": "Int16",
       "offset": -100.0,
       "scalefactor": 0.02,
       "min" : -100,
       "max" : 300,
       "unit": "kg"
     }
   ]
 },
 {
   "name": "test_int8_uint32",
   "uuid": "00020000-0003-11e1-ac36-0002a5d5c51b",
   "uuid_type": 3,
   "format_notify": [
     {
       "length": 2,
       "name": "timestamp"
     },
     {
       "length": 1,
       "name": "test_int8",
       "type": "Int8",
       "offset": 16.0,
       "scalefactor": 10.0,
       "min":200,
       "unit": "km"
     },
     {
       "length": 4,
       "name": "test_uint32",
       "type": "UInt32",
       "offset": 100.0,
       "scalefactor": 100.0,
       "max": 10000
     }
   ]
 }
]

Special Service: [Debug]

If available, the debug service must have the UUID 00000000-000E-11e1-9ab4-0002a5d5c51b and will contains 2 characteristics:

  • 00000001-000E-11e1-ac36-0002a5d5c51b (Notify/Write) is used to send string commands to the board and to notify the user of the result.
  • 00000002-000E-11e1-ac36-0002a5d5c51b (Notify) is used by the board to notify the user of an error message.

Example

The SDK is compatible with different ST firmware as:

  • FP-SNS-ALLMEMS1: STM32 ODE function pack for IoT node with BLE connectivity, digital microphone, environmental and motion sensors
  • FP-ATR-BLE1: STM32Cube function pack for asset tracking using BLE connectivity for the SensorTile.box wireless multi sensor development kit. You can monitor and log the sensor data and communicate with the aws dashboard using the ST Asset Tracking app.
  • FP-SNS-STBOX1: STM32Cube function pack for the Pro Mode of the SensorTile.box wireless multi sensor development kit

And it is used in different application as: