BlueST SDK

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 1 1 1 1 4 6
Name Length Field Type Protocol Version Device Id Feature Mask Device MAC (optional)
Value 0x07/0xD 0xFF 0x01 0xXX 0xXXXXXXXX 0xXXXXXXXXXXXX

a custom bitmask is defined for the SensorTile.box board:

Bit 31 30 29 28 27 26 25 24
Feature FFT Amplitude ADPCM Sync Switch MEMS Norm ADPC Audio MicLevel Audio Classification RFU
Bit 23 22 21 20 19 18 17 16
Feature Acc Gyro Mag Pressure Humidity Temperature Battery Second Temperature
Bit 15 14 13 12 11 10 9 8
Feature RFU Euler Angle RFU SD Logging RFU AccEvent EventCounter Sensor Fusion Compact
Bit 7 6 5 4 3 2 1 0
Feature Sensor Fusion Motion intensity Compass Activity Carry Position RFU MemsGesture Pedometer

To see how the data is exported by pre-defined features, consult the export method Feature.ExtractResult Feature.extractData(long,byte[],int). within the feature class definition.

Characteristics/Features

A bluetooth characteristics can export multiple features. The SDK is searching in all the services the know characteristics. The features that are present in the advertise feature mask have an UUID such as: XXXXXXXX-0001-11e1-ac36-0002a5d5c51b, and are called "Basic Feature" The first 32bits are interpreted as the feature mask, if they are set to 1 it meas that the characteristics is exporting the data of that feature.

The other ST characteristics have the format: XXXXXXXX-0002-11e1-ac36-0002a5d5c51b and are called "extended 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 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.

To see how to define a new Feature or how to add a new UUID to a defined feature see [here](#### How to add a new Feature)

Remote Feature

This type of Feature are created for handle the case when the node collect information from other boards the user want to know also how produced the data.

For this type of feature a node ID is attach at the beginning of a standard feature update message.

For this type of feature the characteristic data format must be:

Length 2 2 >1
Name NodeID Remote timestamp Feature Data .....

Special Services

Debug

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

Configuration

This service is used to communicate commands to the ST characteristics. If available, the configuration service must have the UUID 00000000-000F-11e1-9ab4-0002a5d5c51b and will contain 2 characteristics:

Example

The SDK is compatible with different ST firmware as:

And it is used in different application as:

How to install the library

As an external library

  1. Clone the repository
  2. Add the BlueSTSDK directory as a submodule of your project: File->Import Module

As a git submodule

  1. Add the repository as a submodule:

    $ git submodule add https://github.com/STMicroelectronics/BlueSTSDK_Android.git BlueSTSDK
  2. Add the SDK as a project submodule in the settings.gradle file, adding the line: 
    include ':BlueSTSDK:BlueSTSDK'

Main library actors

Manager

This is a singleton class that starts/stops the discovery process and stores the retrieved nodes. Before starting the scanning process, it is also possible to define a new deviceId and to register/add new features to already-defined devices

The Manager will notify a node discovery through the Manager.ManagerListener class. Note that each callback is performed asynchronously by a background thread.

Node

This class represents a remote device.

From this class you can recover what features are exported by a node and read/write data from/to the device. The node will export all the features that are set to 1 in the advertise message. Once the device is connected, scanning and enabling of available characteristics are performed. At this point it is possible to request/send data related to the discovered features.

A node notifies its RSSI (signal strength) through the Node.BleConnectionParamUpdateListener class. A node notifies any change of its state through the Node.NodeStateListener class.

A node can be in one of following states:

Note that each callback is performed asynchronously by a background thread.

Feature

This class represents data exported by the node.

Each Feature has an array of Field that describes the data exported.

Data are received from a BLE characteristic and contained in a class Feature.Sample. The user is notified of data using a listener pattern.

The data exported by the Sample can be extracted using the static utility methods of the class.

Note that each callback is performed asynchronously by a background thread.

Available features can be retrieved from Features package.

How to add a new Feature

  1. Extend the class Feature:
    1. Create an array of Feature.Field that will describe the data exported by the new feature
    2. Create a constructor that accepts only the node as a parameter. From this constructor call the super constructor, passing the feature name and the feature field.
    3. Implement the method Feature.ExtractResult Feature.extractData(long,byte[],int).
    4. Create a utility static method that extracts the data from the Feature.Sample class

  2. Register the feature before the node connection using the ConnectionOption class:

            UUIDToFeatureMap myMap = new UUIDToFeatureMap();
        map.put(UUID.fromString("00002a37-0000-1000-8000-00805f9b34fb"), FeatureHeartRate.class);

    ConnectionOption.ConnectionOptionBuilder optionsBuilder = ConnectionOption.builder()
                .setFeatureMap(myMap);
    ConnectionOption options = optionsBuilder.build();

    node.connect(context,options)

    or

    Node node=...
UUIDToFeatureMap map = new UUIDToFeatureMap();
map.put(UUID.fromString("00002a37-0000-1000-8000-00805f9b34fb"), FeatureHeartRate.class);
node.addExternalCharacteristics(map)

    To reuse one Basic Feature register use the manager class:

    // add the feature to the Nucleo device
byte deviceId = (byte) 0x80;
SparseArray<Class<? extends Feature>> temp = new SparseArray<>();
// the feature will be mapped in the characteristic 
// 0x10000000-0001-11e1-ac36-0002a5d5c51b
temp.append(0x10000000,MyNewFeature.class);
try {
    Manager.addFeatureToNode(deviceId,temp);
} catch (InvalidFeatureBitMaskException e) {
    e.printStackTrace();
}

    Log

    The SDK defines some class that will log the feature data. Using the class FeatureLogCSVFile each feature will have its file, and the data logged will be:

    • Node address (on Android) or name (on iOS)
    • Timestamp, the message id
    • RawData, the data received by the feature extractData method
    • one colunm for each data extracted by the feature

Docs

You can find the documentation at this link: JavaDoc

License

COPYRIGHT(c) 2015 STMicroelectronics

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of STMicroelectronics nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.