The SBrick Protocol
===================
The advertisement data
----------------------
The advertisement data contains the full device name, and some
manufacturer specific data. The latter contains security and battery
voltage information, and is available in the "scan response" packets
in response to active scanning.
Vengit Limited manufacture specific data fields
-----------------------------------------------
We use manufacturer specific data in AD to advertise product type,
battery reading and other data currently not in the Bluetooth
specification.
The manufacturer specific data starts with a length octet, that
describes the whole length of this field. After the length octet, the
company identifier for Vengit limited follows in little endian order.
After these four bytes, the actual data payload follows.
<01> <98>
The manufacturer specific data records can be read as:
<1: data length (1-255)>
Every record begins with a length octet, and a record identifier octet
that determines the type of the record.
The manufacturer specific data field may be present in both
advertisement data, and scan response data packets, even at the same
time.
Vengit Limited manufacturer specific 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 F0
02 Device Identifier
02
Example, SBrick device ID: 07 02 0D 23 FC 19 87 63
03 Simple Security status
05
00: Freely accessible
01: Authentication needed for some functions
Example manufacturer specific data for SBrick, containing device ID with
hw/sw revision, with battery readings and device ID:
1A FF 01 98 06 00 00 04 00 04 02 04 01 0E 12 f0 07 02 0D 23 FC 19 87 63
02 03 00
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) is always "SBrick", and the appeareance (2a01) is
always 0384 a.k.a. "generic remote control", according to the Bluetooth
Specification.
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:
02 Reset DFU pointer
Resets the DFU flash pointer to zero. Can be used when reading back
firmware image. This is only useful for debugging / testing
purposes.
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.
The characteristic can also be read. The value read back is the DFU
pointer, or the number of bytes written into flash. The application
might want to check the DFU pointer, and compare it with the firmware
size. If the thow sizes are different, the deivce MUST be restarted
with the "0x12 Reboot" command, and the user must be informed about
the failure. The user flash is cleared upon reboot, and the firmware
upload can be attempted again.
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.
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 Remove control commands characteristic allows full control over
SBrick.
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 returned value can be read
from the characteristic. The central can also subscribe to notifications
on this characteristic, so renturn values will be sent promptly when
available.
Commands with no return values will issue no notification, and the
characteristic value will not change.
The "SUPER" note means that the operation require superwisor privileges.
All commands might throw exceptions. These exceptions manifest themselves
as BLE level errors, with error codes in the user-defined error range.
The possible exceptions are the following:
0x80 ERROR_LENGTH Invalid command length
0x81 ERROR_PARAM Invalid parameter
0x82 ERROR_COMMAND No such command
0x83 ERROR_NOAUTH No authentication needed
0x84 ERROR_AUTH Authentication error
0x85 ERROR_DOAUTH Authentication needed
0x86 ERROR_AUTHOR Authorization error
0x87 ERROR_THERMAL Thermal protection is active
The possible commands are following.
00 Break
00 ...
At least one, at most four channels can be given
(The default is all channels are freewheeling)
Return: -
01 Drive
01 ...
(The default is all channels are freewheeling)
Return: -
02 Need authentication?
02
If superwisor 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 superwisor password set.
Return:
00 - Not authenticated
01 - Authenticated
04 Get user ID
04
Returns the authenticated user ID.
Return: User ID if authenticated, undefined if not.
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 (SUPER)
06 00: clears superwisor password. This will "open" SBrick, anyone
connecting will get superwisor rights. Guest password will also
be cleared.
06 01: clear only guest password, rendering guests unable to
authenticate.
Return: -
07 Set password (SUPER)
07 <8 byte password>: set the password
Return: -
08 Set authentication timeout (SUPER)
08 <0.1 seconds x N, minimum 0.5, maximum 20 seconds, 1 byte>
Return: -
09 Get authentication timeout (SUPER)
09
Return: <1 byte auth timeout in 0.1 sec. ticks>
0A Get brick ID
0A
Return:
0B Quick Drive Setup
0B
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
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
The ADC channels are read at every 2 seconds. These values are stored
in variables, and this query simply reads those variables. Because of
this, ADC data can be up to 2 seconds old.
Temperature can be read on channel 0x0E, voltage on 0x00.
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 / 16 * 1.24 / 2047
Temperature can be calculated as: celsius = (ADC / 16 * 1240 / 2047) * 10/45 - 160
Where 160 is an offset
10 Send event
10
Events can be used to trigger patterns.
Event range: 0-31. Events 0-15 are reserved for system use.
Special events:
0: Boot
1: Connection established
2: Disconnected
16-31: User events
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 ...
(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: 2byte, the raw ADC value set for thermal limit
16 Write program
16 <1 byte offset>
The program memory is 256 bytes long.
Commands:
BRAKE 00(CH:3)(X:2)0
BRAKEPWM 00(CH:3)(X:2)1 | (PWM:8)
DRIVE 01(CH:3)(D:1)(X:2) | (PWM:8)
SHORTWAIT 100(T:5)
WAIT 101(T1:5) | (T2:8)
X 1100....
X 1101....
X 11100...
X 11101...
X 111100..
X 111101..
X 1111100.
LONGWAIT 1111101(T1:1) | (T2:8) | (T3:8)
JUMP 11111100 | (A:8)
X 11111101
STOP 11111111
Where "X" means a reserved command.
Example: 160048608A4C608AFC004800FF
- Write program to address 0
- DRIVE, channel 1, direction 0, power 0x60
- WAIT 10
- DRIVE, channel 1, direction 1, power 0x60
- WAIT 10
- JUMP 0
17 Read program
17 <1 byte offset> <1 byte data length>
The offset + data length must be at most 1024.
Data length must be at most 22 bytes.
Return:
18 Save program
18
Saves the current program to the upper half of the first flash page,
after erasing the whole page.
Interferes with OTA.
Return: -
19 Erase program
19
Erases the first user flash page. The command buffer will remain
unaffected.
Return: -
1A Set event
1A <1 byte event ID> <1 byte program memory offset>
Sets a program memory address for an event in the event table.
Return: -
1B Read event
1B <1 byte event ID>
Reads an address from the event table
Return: <1 byte program memory address>
1C Save events
1C
Saves the event table onto the flash
1D Start program
1C <1 byte address>
Start program at given address
1E Stop program
1E
Stops the currently running program
Quick Drive - 489a6ae0-c1ab-4c9c-bdb2-11d373c1b7fb
--------------------------------------------------
The purpose of this characteristic is to make remote contgrolling 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 expected, 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 freewheeling.
- 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.
