The SBrick BLE protocol

The SBrick BLE ...
(0 ratings)
Created by Tamás Fábián | January 9, 2015 | Last updated by Tamás Fábián April 7, 2015 (view change)

The SBrick Protocol 17
======================


The advertisement data
----------------------

The advertisement data contains the full device name, and some manufacturer 
specific data.

Manufacturer specific data contains security, battery voltage, and 
potentionally other peaces of information, and is available in the 
"advertisement data" and "scan response" packets in response to active 
scanning. Manufacturer specific data may be presen in BOTH packages.


Vengit Limited manufacture specific data fields
-----------------------------------------------

SBrick uses manufacturer specific data to advertise product type, battery 
reading and other data currently not in the Bluetooth specification.

The manufacturer specific data starts with a length octet describing the whole 
length of this field. After the length octet, the field type octet and company 
identifier octets for Vengit follows in little endian order. After these four 
bytes, the actual data payload follows.

< LENGTH > <FF> <98> <01> < DATA PAYLOAD >

The manufacturer specific data records in the data payload can be read as:

<1: data length (1-255)> < Data >

Every record begins with a length octet, and a record identifier octet 
determining the type of the record.

The data payload contains zero or more records. These records are also used in
notifications to signal device and command status.

SBrick Data Records
-------------------

00 Product type
    00 <1: Product ID> <2: HW major/minor version> <2: FW major/minor version>
        00 - SBrick
    Example 1: 02 00 00 - Product SBrick
    Example 2: 06 00 00 04 00 04 01 - Product SBrick, HW 4.0, FW 4.1


01 BlueGiga ADC sensor raw reading
    01 <1: channel> <2: raw sensor reading>
    Example, battery reading '12f0' on SBrick: 04 01 00 12 F0
    Example, temperature reading '12f0': 04 01 0e 12 F002 Device Identifier
    02 < Device identifier string >
    Example, SBrick device ID: 07 02 0D 23 FC 19 87 63


03 Simple Security status
    05 <1: status code >
    00: Freely accessible
    01: Authentication needed for some functions


04 Command response
    04 <1: return code > <n-2: return value >

    The return codes are the following:

    00: Successful operation
    01: Invalid data length
    02: Invalid parameter
    03: No such command
    04: No authentication needed
    05: Authentication error
    06: Authentication needed
    08: Thermal protection is active
    09: The system is in a state where the command does not make sense

    The return vale can be zero or more bytes, and contain information related
    to the execution of the command. The documentation of each command describes
    what kind of data is returned, if any.


05 Thermal protection status
    05 < status >

    Status may be:
    1: temperature is over / just went over the safe limit
    0: temperature is below / just went below the safe limit

06 Voltage measurement
    06 < measurement data >

    Measurement data may contain measurements over multiple channels.

    Each measurement is described over 2 bytes.

    The 3 upper nibbles contain the 12 bit raw ADC data.

    The low nibble contains the channel number.

    The two nibbles of the second byte are the first and second decimal places
    after the decimal points respectively.

    Channel numbers are the following:

    In case of SBrick "plus" (hardware 6), the channels are the following:

    0: Port 0 (A), C1
    1: Port 0 (A), C2
    2: Port 1 (C), C1
    3: Port 1 (C), C2
    4: Port 2 (B), C1
    5: Port 2 (B), C2
    6: Port 3 (D), C1
    7: Port 3 (D), C2
    8: battery voltage
    9: internal temperature


Example manufacturer specific data for SBrick, containing device ID with
hw/sw revision, with battery readings and device ID:

1A FF 98 01
06 00 00 04 00 04 02
04 01 0E 12 f0
07 02 0D 23 FC 19 87 63
02 03 00

Example data sent in a notification on the Remote Control Commands 
characteristic. It contains a command acknowledgement with no data returned,
and raw ADC reading of "12F0" on channel 00:

02 04 00 04 01 00 12 F0

The GATT database
-----------------

The following service and characteristics are accessible:

 1. Generic GAP service
 2. Device information service
 5. OTA service
 6. Remote control service


Generic GAP service - 1800
--------------------------

Only contains the device name and appeareance characteristics.
The device name (2a00), and the appeareance (2a01) is
always 0384 a.k.a. "generic remote control", according to the Bluetooth
Specification.

The device name is "SBrick" out of the box, but can be changed either by
issueing the appropriate remote control command, or by writing this
characteristic.


Device information - 180a
-------------------------

Contains mandatory device information fields.

Model number string - 00: "SBrick". Same as the "Product type" above.

Firmware revision string 
Hardware revision string
Software revision string
    These are version information strings. The "firmware" and "software"
    revision string are always the same.

    The revision string consist of a major and a minor revision,
    separated by a dot. (Example: 4.1 - Major is 4, minor is 1.)

    A firmware is ONLY compatible with a hardware, if their MAJOR
    REVISION NUMBER IS EXACTLY THE SAME.

Manufacturer string - "Vengit Ltd."

OTA service - 1d14d6ee-fd63-4fa1-bfa4-8f47b42119f0
--------------------------------------------------

The OTA service is compatible with BlueGiga's OTA solution, one can
use BLEGui to upload a new firmware.


OTA control - f7bf3564-fb6d-4e53-88a4-5e37e0326063
--------------------------------------------------

This characteristic can be used to send OTA-specific commands:

03 Reboot into DFU mode
    After successfully transmitting the firmware image, the device can
    be booted into DFU mode with this command. In this mode, the device
    checks the flash memory for a firmware image, and calculates the
    checksum. If the checksum is correct, the firmware image is
    transferred into the program memory. This procedure takes
    approximately five seconds. After this, the firmware clears up the
    user flash. During flash clearing, the ID LED blinks quickly for
    about one and a half seconds.

For every command a notification is sent on the Quick Drive characteristic as
an acknowledgement.

OTA data - 984227f3-34fc-4045-a5d0-2c581f81a153
-----------------------------------------------

This characteristic can be used to transfer the firmware image in 20 byte 
packages.

After successfully uploading the firmware, the application MUST issue a command 
"0x03 Reboot into DFU mode" on the control characteristic to restart the device 
into DFU mode.

This characteristic can also be read to check the written firmare, or 
blank-check the flash. One must reset the DFU pointer with comman 0x02 on the 
control characteristic before attempting  a readback. This feature is probably 
not that useful fin normal circumstances, as it was developed to aid 
development / debugging.

For every command a notification is sent on the Quick Drive characteristic as
an acknowledgement.


Remote control service - 4dc591b0-857c-41de-b5f1-15abda665b0c
-------------------------------------------------------------

This service contains two characteristics:

* Quick Drive: allows remote control with small data packets. Very
  limited functionality.
* Remote control commands: allows full control, more verbose and slower
  than quick drive.

The Quick Drive characteristic should be used in situations where
multiple channels must be updated quickly. It uses less bandwidth
than issueing commands at the Remote control commands characteristic.

The Remote control commands characteristic allows full control over
SBrick.

The Remote control commands characteristic supports notifications. Subscribing
to this characteristic will enable notifications on various events, including
the acknowledgement of every write on the OTA, Quick Drive, and Remote control
commands characteristics.


Notification payload
--------------------

SBrick can acknowledge every remote control, quick drive, or OTA command or
data packet. Besides acknowledgements, SBrick can also send information
periodically and autonomously.

To reduce bandwidth, latency and jitter, a single notification might include
several pieces of information, including:

- A single byte indicating boolean properties, such as wether the notification
acknowledges a write to the SBrick or not.
- The result of the last command if there were any, including any error codes.
- A/D data sent autonomously or after a read command.

The data included in the notification is formatted according to the "SBrick 
Data Records" section.


Remote control commands - 2b8cbcc-0e25-4bda-8790-a15f53e6010f
-------------------------------------------------------------

Commands can be issued by writing data to this characteristic. A command
always starts with the command identifier byte, after wich parameters
may follow. A single BLE write operation can only send a single command.

Certain commands can return a value. The central can also subscribe to 
notifications on this characteristic, so acknowledgements with return values
and other information can be sent by the SBrick.

The "OWNER" note means that the operation require owner privileges.

The possible commands are following.

00 Break
    00 < channel1 > < channel2 > ...
    At least one, at most four channels can be given
    (The default is all channels are freewheeling)

    Return: -


01 Drive
    01 < channel1 > < direction1 > < power1 > ...
    (The default is all channels are freewheeling)

    Return: -


02 Need authentication?
    02
    If owner password is set, this will return true.

    This exact information is reflected in the "simple security"
    field in manufacturer specific data.

    Return:
        00 - Authentication not needed
        01 - Authentication needed


03 Is authenticated?
    03
    Returns wether the current session is authenticated. This will always
    return true, if there's no owner password set.

    Return:
        00 - Not authenticated
        01 - Authenticated


04 Get user ID
    04
    Returns the authenticated user ID. If the user is not authenticated,
    then a BLE error is returned.

    Return: User ID if authenticated. 


05 Authenticate
    05 <1 byte user ID> <8 byte password>
    New sessions are unauthenticated if password set.
    New sessions are authenticated if password is not set.

    Return: -


06 Clear password (OWNER)
    06 00: clears owner password. This will "open" SBrick, anyone
        connecting will get owner rights. Guest password will also
        be cleared.

    06 01: clear only guest password, rendering guests unable to
           authenticate.

    Return: -


07 Set password (OWNER)
    07 < User ID > <8 byte password>: set the password

    00: owner
    01: guest

    Guest password can only be set if there is a password set for the
    owner too (e.g. "need authentication?" returns 1)

    Return: -


08 Set authentication timeout (OWNER)
    08 <0.1 seconds x N, minimum 1, maximum 25.5 seconds, 1 byte>

    Sets the authentication timeout. This value is saved to the
    persistent store, and loaded at boot time.

    Return: -


09 Get authentication timeout (OWNER)
    09

    Return: <1 byte auth timeout in 0.1 sec. ticks>


0A Get brick ID
    0A

    Return: < BRICK ID, 6 byte BlueGiga ID >


0B  Quick Drive Setup
    0B < channel-number1 > < channel-number2 >
    At least one, at most five channels can be given.
    Default: First five channels adcending order

    Return: -

0C  Read Quick Drive Setup
    0C
    Return: <5 byte quick drive setup>


0D Set watchdog timeout
    0D < timeout in 0.1 secs, 1 byte >

    The purpose of the watchdog is to stop driving in case of an
    application failure.

    Watchdog starts when the first DRIVE command is issued during a
    connection.

    Watchdog is stopped when all channels are either set to zero drive,
    or are braking.

    The value is saved to the persistent store.

    The recommended watchdog frequency is 0.2-0.5 seconds, but a smaller
    and many larger settings are also available.

    Writing a zero disables the watchdog.

    By default watchdog is set to 5, which means a 0.5 second timeout.

    Return: -

0E Get watchdog timeout
    0E
    Return: < 1 byte watchdog timeout >


0F Query ADC
    0F < ADC channel ID, 00 throug 09 >

    The ADC channels are read approximately five times a second. These values 
    are stored in variables, and this query simply reads those variables. 
    Temperature and battery voltage measurements are always taken. Use the 
    command "2C Set up periodic voltage measurement" to measure port pins on 
    SBrick Plus (hardware version 11) models.

    Temperature can be read on channel 0x09, voltage on 0x08.

    Return:
        2 byte, little endian, 12 bit resolution ADC reading on given channel.
        Value is stored MSB. (Must be divided by 16)

        All ADC channels are using the internal 1.24V reference.

        The PSU voltage is dropped through a 10:1 voltage divider.
        VPSU = (ADC * 0.83875) / 2047.0

        Temperature can be calculated as: celsius = ADC / 118.85795 - 160
        Where 160 is an offset


11 Erase user flash on next reboot (compromises OTA!)
    11
    Return: -


12 Reboot
    12

    After issueing this command, the remote device will gracefully
    terminate the connection, and reboot in normal (non-DFU) mode.

    To reboot in DFU mode and possibly update firmware, use the OTA
    service.

    Return: -


13 Break with PWM support
    13 < channel1 > < power1 > < channel2 > < power2 > ...
    (The default is all channels are freewheeling)
    Return: -


14 Set thermal limit
    14 <2 byte ADC value>

    Sets the thermal protection limit.

    Return: -


15 Read thermal limit
    15
    Return: 2 bytes, the raw ADC value set for thermal limit


1F Set PWM counter value
    1F <2 byte value to be written to T1CC0H/L registers>
    Sets the PWM  counter value by writing into the TIMER1 control registers.
    Certain TIMER1 register values are also recalculated to keep the PWM
    duty cycle as constant across changes as possible.

    The default PWM value is 31874 (decimal)


20 Get PWM counter value
    20
    Returns the 2 byte TIMER1 T1CC0H/L value.
    Return <2 byte T1CC0H/L value>


21 Save PWM counter value
    21
    Saves PWM counter value to flash


22 Get channel status
    22
    Returns the current drive level of a channel
    Return < brake status bits, 1 byte, 1:brake on, 0: brake off > <1 byte direction flags> <5 byte channel drive values from 0 to 4>


23 Is guest password set (OWNER)
    23
    Return: 1 or 0


24 Set connection parameters
    24 < interval min *1.25ms, 2 bytes > < interval max *1.25ms, 2 bytes > < slave latency, 2 bytes > < timeout *10ms, 2 bytes >
    Return: <1 byte return value of Bluegiga BLE stack function "connection_update">


25 Get connection parameters
    25
    Return: < connection interval * 1.25ms, 2 bytes >< slave latency, 2 bytes >< timeout * 10ms, 2 bytes >


26 Set release on reset
    26 <1 byte, 0, or 1>

    1: Default: the channel drive values are set to zero, non-braking,
    and default "0" direction (clockwise with LEGO motors)

    0: The channels are left in whatever state the controlling application
    set them. This option itself is preserved throughout connections.


27 Get release on reset
    27
    Return: <1 byte, 0 or 1>


28 Read power cycle counter
    28
    Return: <4 bytes, uint32>


29 Read uptime counter
    28
    Return: <4 bytes, uint32>


2A Set device name
    2A < Device name, 1-10 bytes min-max. >
    Return: -


2B Get device name
    2B
    Return < Device name, 1-10 bytes min-max. >


2C Set up periodic voltage measurement
    2C < list of channels >

    Each byte in the parameter list defines a channel number to measure.

    An empty list disables any active periodic measurement.

    Return: -

2D Get voltage measurement setup
    2D

    Return: list of measured channels


2E Set up periodic voltage notifications
    2E < list of channels >

    Each byte in the parameter list defines a channel of which to send notifications.

    An empty list disables any active periodic notification.

    Return: -


2F Get voltage notification setup
    2F

    Return: list of measured channels


Quick Drive - 489a6ae0-c1ab-4c9c-bdb2-11d373c1b7fb
--------------------------------------------------

The purpose of this characteristic is to make remote controlling possible using 
as little bandwidth as possible. A two-channel race car can be controlled by 
sending only two bytes: one for the accelerator and one for steering.

One can write (no response) 0-5 byte data packets to this characteristic to 
drive channels.

The characteristic can be thought of as a five byte register. Each byte in the 
register conrtols one channel. With the 0x0A "Quick Drive Setup" command, one 
can configure which byte controls which channel. The default is that byte 0 
controls channel 0, byte 1 conrtols channel 1, and so on.

Quick Drive is the recommended way to control models where low latency is 
required, and there might be dozens of models in the same area.

Since each channel is driven with one byte, the direction and the PWM 
information must be fitted into that single byte. This is done in the following 
way:

Example: "Drive forward (clockwise) 255"

  1  1  1  1  1  1  1  0 <- Direction bit
  _  _  _  _  _  _  _  _
MSb                   LSb

Example:

writing the byte string 00FFFE00 will turn channel #1 CCW full speed,
channel #2 CW full speed, and set channels #0 and #3 braking.

- Braking happens when the value is set to zero (less the direction bit).

- When the value is 2 (less the direction bit), it is modified to 0.

- When the value is 0xFE (less the direction bit), it is modified to 0xFF

The last two modification make full and zero throttle possible.

BLE Bluetooth protocol SBrick

0 Child Pages
10 comments
  • gabor meszaros likes this
  • David Wegmuller
    David Wegmuller AS Laurent pointed out, there is a typo in the remote control service.
    The full UUID is: 02b8cbcc0e254bda8790a15f53e6010f (the first digit, 0 is missing).
    March 29, 2015 - 2 like this
  • Tamás Fábián
    Tamás Fábián Hi everyone, a new version of the protocol description has been published. All the mentioned errors were fixed.
    January 19, 2016
  • Zoltan Feher
    Zoltan Feher hey, I've upgraded my sbrick to v17, and i can see that this description is also updated. but it has some errors.
    in the advertisement data, there is no adc sensor raw reading now!
    December 14, 2016
  • Zoltan Feher
    Zoltan Feher after upgrading, there are no notifications on the remote control characteristics. does a changelog exist what is changed in the protocol?
    December 14, 2016