BLE data spec
This chapter outlines the Bluetooth Low Energy (BLE) data specification for controlling the device's LED ring, accessing sensor values, checking network information, retrieving device information and sensor configuration parameters.
Control
LED Animations service is used to control the device's LED ring.
Demonstration Animation
Demonstration Animation characteristic is used to set the predefined animation for the LED ring. This characteristic expects data in the following format (LED Ring Data):
| Field | Data Type | Description |
|---|---|---|
| mode | signed 8-bit integer | Mode of LED animation |
| duration | unsigned 32-bit integer | Duration of the animation (in milliseconds) |
| speed | unsigned 8-bit integer | Speed of animation |
| brightness | unsigned 8-bit integer | Brightness level of the LED |
| colors | array of three unsigned 32-bit integers | RGB colours for the LED animation |
mode can be one of the following values:
| Mode Identifier | Mode ID | Description |
|---|---|---|
| CLEAR_ANIMATION | -1 | Stops any ongoing LED animation |
| FX_MODE_STATIC | 0 | Static LED animation |
| FX_MODE_BLINK | 1 | Blinking LED animation |
| FX_MODE_BREATH | 2 | Breathing LED animation |
| FX_MODE_COLOUR_WIPE | 3 | Colour wipe LED animation |
| FX_MODE_COLOUR_WIPE_RANDOM | 4 | Random colour wipe LED animation |
| FX_MODE_RANDOM_COLOUR | 5 | Random colour LED animation |
| FX_MODE_COLOUR_SWEEP | 6 | Colour sweep LED animation |
| FX_MODE_DYNAMIC | 7 | Dynamic LED animation |
| FX_MODE_RAINBOW | 8 | Rainbow LED animation |
| FX_MODE_RAINBOW_CYCLE | 9 | Rainbow cycle LED animation |
| FX_MODE_SCAN | 10 | Scanning LED animation |
| FX_MODE_DUAL_SCAN | 11 | Dual scanning LED animation |
| FX_MODE_FADE | 12 | Fading LED animation |
| FX_MODE_THEATER_CHASE | 13 | Theater chase LED animation |
| FX_MODE_THEATER_CHASE_RAINBOW | 14 | Rainbow theater chase LED animation |
| FX_MODE_RUNNING_LIGHTS | 15 | Running lights LED animation |
| FX_MODE_SAW | 16 | Saw LED animation |
| FX_MODE_TWINKLE | 17 | Twinkling LED animation |
| FX_MODE_DISSOLVE | 18 | Dissolving LED animation |
| FX_MODE_DISSOLVE_RANDOM | 19 | Random dissolving LED animation |
| FX_MODE_SPARKLE | 20 | Sparkling LED animation |
| FX_MODE_FLASH_SPARKLE | 21 | Flash sparkling LED animation |
| FX_MODE_HYPER_SPARKLE | 22 | Hyper sparkling LED animation |
| FX_MODE_STROBE | 23 | Strobing LED animation |
| FX_MODE_STROBE_RAINBOW | 24 | Rainbow strobing LED animation |
| FX_MODE_MULTI_STROBE | 25 | Multi strobe LED animation |
| FX_MODE_BLINK_RAINBOW | 26 | Rainbow blinking LED animation |
| FX_MODE_ANDROID | 27 | Android LED animation |
| FX_MODE_CHASE_COLOUR | 28 | Colour chasing LED animation |
| FX_MODE_CHASE_RANDOM | 29 | Random chasing LED animation |
| FX_MODE_CHASE_RAINBOW | 30 | Rainbow chasing LED animation |
| FX_MODE_CHASE_FLASH | 31 | Flash chasing LED animation |
| FX_MODE_CHASE_FLASH_RANDOM | 32 | Random flash chasing LED animation |
| FX_MODE_CHASE_RAINBOW_WHITE | 33 | White rainbow chasing LED animation |
| FX_MODE_COLOURFUL | 34 | Colourful LED animation |
| FX_MODE_TRAFFIC_LIGHT | 35 | Traffic light LED animation |
| FX_MODE_COLOUR_SWEEP_RANDOM | 36 | Random colour sweep LED animation |
| FX_MODE_RUNNING_COLOUR | 37 | Running colour LED animation |
| FX_MODE_RUNNING_RED_BLUE | 38 | Running red-blue LED animation |
| FX_MODE_RUNNING_RANDOM | 39 | Random running LED animation |
| FX_MODE_LARSON_SCANNER | 40 | Larson scanner LED animation |
| FX_MODE_COMET | 41 | Comet LED animation |
| FX_MODE_FIREWORKS | 42 | Fireworks LED animation |
| FX_MODE_RAIN | 43 | Rain LED animation |
| FX_MODE_MERRY_CHRISTMAS | 44 | Merry Christmas LED animation |
| FX_MODE_FIRE_FLICKER | 45 | Fire flicker LED animation |
| FX_MODE_GRADIENT | 46 | Gradient LED animation |
| FX_MODE_LOADING | 47 | Loading LED animation |
| FX_MODE_POLICE | 48 | Police LED animation |
| FX_MODE_POLICE_ALL | 49 | All-police LED animation |
| FX_MODE_TWO_DOTS | 50 | Two dots LED animation |
| FX_MODE_TWO_AREAS | 51 | Two areas LED animation |
| FX_MODE_CIRCUS_COMBUSTUS | 52 | Circus combustus LED animation |
| FX_MODE_HALLOWEEN | 53 | Halloween LED animation |
| FX_MODE_TRICOLOUR_CHASE | 54 | Tricolour chasing LED animation |
| FX_MODE_TRICOLOUR_WIPE | 55 | Tricolour wipe LED animation |
| FX_MODE_TRICOLOUR_FADE | 56 | Tricolour fade LED animation |
| FX_MODE_LIGHTNING | 57 | Lightning LED animation |
| FX_MODE_ICU | 58 | ICU LED animation |
| FX_MODE_MULTI_COMET | 59 | Multi-comet LED animation |
| FX_MODE_DUAL_LARSON_SCANNER | 60 | Dual Larson scanner LED animation |
| FX_MODE_RANDOM_CHASE | 61 | Random chasing LED animation |
| FX_MODE_OSCILLATE | 62 | Oscillating LED animation |
| FX_MODE_PRIDE_2015 | 63 | Pride 2015 LED animation |
| FX_MODE_JUGGLE | 64 | Juggling LED animation |
| FX_MODE_PALETTE | 65 | Palette LED animation |
| FX_MODE_FIRE_2012 | 66 | Fire 2012 LED animation |
| FX_MODE_COLOURWAVES | 67 | Colour waves LED animation |
| FX_MODE_BPM | 68 | BPM LED animation |
| FX_MODE_FILLNOISE8 | 69 | Fill noise 8 LED animation |
| FX_MODE_NOISE16_1 | 70 | Noise 16_1 LED animation |
| FX_MODE_NOISE16_2 | 71 | Noise 16_2 LED animation |
| FX_MODE_NOISE16_3 | 72 | Noise 16_3 LED animation |
| FX_MODE_NOISE16_4 | 73 | Noise 16_4 LED animation |
| FX_MODE_COLOURTWINKLE | 74 | Colour twinkle LED animation |
| FX_MODE_LAKE | 75 | Lake LED animation |
| FX_MODE_METEOR | 76 | Meteor LED animation |
| FX_MODE_METEOR_SMOOTH | 77 | Smooth meteor LED animation |
| FX_MODE_RAILWAY | 78 | Railway LED animation |
| FX_MODE_RIPPLE | 79 | Ripple LED animation |
| FX_MODE_TWINKLEFOX | 80 | Twinkle fox LED animation |
| FX_MODE_TWINKLECAT | 81 | Twinkle cat LED animation |
| FX_MODE_HALLOWEEN_EYES | 82 | Halloween eyes LED animation |
| FX_MODE_STATIC_PATTERN | 83 | Static pattern LED animation |
| FX_MODE_TRI_STATIC_PATTERN | 84 | Tricolour static pattern LED animation |
| FX_MODE_SPOTS | 85 | Spots LED animation |
| FX_MODE_SPOTS_FADE | 86 | Fading spots LED animation |
| FX_MODE_GLITTER | 87 | Glitter LED animation |
| FX_MODE_CANDLE | 88 | Candle LED animation |
| FX_MODE_STARBURST | 89 | Starburst LED animation |
| FX_MODE_EXPLODING_FIREWORKS | 90 | Exploding fireworks LED animation |
| FX_MODE_BOUNCINGBALLS | 91 | Bouncing balls LED animation |
| FX_MODE_SINELON | 92 | Sinelon LED animation |
| FX_MODE_SINELON_DUAL | 93 | Dual sinelon LED animation |
| FX_MODE_SINELON_RAINBOW | 94 | Rainbow sinelon LED animation |
| FX_MODE_POPCORN | 95 | Popcorn LED animation |
| FX_MODE_DRIP | 96 | Drip LED animation |
| FX_MODE_PLASMA | 97 | Plasma LED animation |
| FX_MODE_PERCENT | 98 | Percentage LED animation |
| FX_MODE_RIPPLE_RAINBOW | 99 | Rainbow ripple LED animation |
| FX_MODE_HEARTBEAT | 100 | Heartbeat LED animation |
| FX_MODE_SUNRISE | 101 | Sunrise LED animation |
| FX_MODE_FLOW | 102 | Flow LED animation |
In BLE GATT communication, data should be in little-endian format and padding zeros should be added if necessary to conform to specified data type. Here is an example of static blue animation that lasts 10 seconds:
| Field | Value | Formatted Data | Note |
|---|---|---|---|
| mode | 0 | 00 | - |
| duration | 10000 | 10270000 | 10000 ms = 0x2710, padding zeros added |
| speed | 0 | 00 | - |
| brightness | 200 | C8 | - |
| colors | [ff, 0, 0] | [ff000000, 00000000, 00000000] | blue colour: 0xff, don't care, don't care |
Here's the final packet that would be sent to the Demonstration Animation characteristic (0x5543) of the LED Animations service (0x5541) in little-endian hex format:
001027000000C8ff0000000000000000000000
Sensor Colour Scheme
Sensor Colour Scheme characteristic is used to set the colour scheme for the LED ring based on the value of selected sensor. This characteristic expects data in the following format (Sensor Colour Scheme):
| Field | Data Type | Description |
|---|---|---|
| Sensor ID | unsigned 32-bit integer | Selected sensor |
| Rules | array of three Sensor Colour Scheme Rule rules | Array of rules for the colour scheme based on the sensor value |
Sensor ID can be one of the following values:
| Description | Value |
|---|---|
| Temperature | 0 |
| VOC | 1 |
| Humidity | 2 |
| Light sensor | 3 |
| Microphone | 4 |
| Motion sensor | 8 |
| CO2 sensor | 9 |
Here's breakdown of Sensor Colour Scheme Rule:
| Field | Data Type | Description |
|---|---|---|
| Operator Type | unsigned 8-bit integer | Operator type for the rule |
| Value | signed 32-bit integer | Value for the rule |
| LED Data | LED Ring Data | LED data for the rule |
Operator Type can be one of the following values:
| Description | Value |
|---|---|
| EQUAL | 0 |
| LESS | 1 |
| GREATER | 2 |
| OTHERWISE | 3 |
In BLE GATT communication, data should be in little-endian format and padding zeros should be added if necessary to conform to specified data type. Here is an example of colour scheme:
- Temperature T:
- T < 20°C : blue
- T < 24 °C : orange
- Otherwise: red
| Field | Value | Formatted Data | Note |
|---|---|---|---|
| Sensor ID | 0 | 00000000 | Temperature sensor |
Sensor Colour Scheme Rule | [ { "operator": "less", "value": 20, "LED Ring Data": "static blue animation" }, { "operator": "less", "value": 24, "LED Ring Data": "static orange animation" }, { "operator": "otherwise", "value": "don't care, LED Ring Data: static red animation" } ] | 01 14000000 00 ffffffff C8 C8 ff000000 00000000 00000000 01 18000000 00 ffffffff C8 C8 00a5ff00 00000000 00000000 03 00000000 00 ffffffff C8 C8 0000ff00 00000000 00000000 | Explained below |
Here's breakdown of the first Sensor Colour Scheme Rule data (Temperature T < 20°C: Blue) in little-endian hex format:
| Field | Value | Formatted Data | Note |
|---|---|---|---|
| Operator Type | 1 | 01 | Less |
| Value | 20 | 14000000 | 20 (0x14) in little-endian hex format |
LED Ring Data | { "mode": 0, "duration": "max", "speed": 200, "brightness": 200, "colors": ["ff", "don't care", "don't care"] } | 00 ffffffff C8 C8 ff000000 00000000 00000000 | Static blue animation |
The data for the second and third rule is formatted in the same way as the data for the first rule.
Rule 2 (Temperature T < 24°C: Orange) in little-endian hex format: 01 18000000 00 ffffffff C8 C8 00a5ff00 00000000 00000000
Rule 3 (Otherwise: Red) in little-endian hex format: 03 00000000 00 ffffffff C8 C8 0000ff00 00000000 00000000
When Sensor ID gets combined with these three rules, here's the final data:
00000000 01 14000000 00 ffffffff C8 C8 ff000000 00000000 00000000 01 18000000 00 ffffffff C8 C8 00a5ff00 00000000 00000000 03 00000000 00 ffffffff C8 C8 0000ff00 00000000 00000000
And here's the final packet that would be sent to the Sensor Colour Scheme characteristic (0x5542) of the LED Animations service (0x5541) in little-endian hex format:
00000000011400000000ffffffffC8C8ff0000000000000000000000011800000000ffffffffC8C800a5ff000000000000000000030000000000ffffffffC8C80000000000ff000000000000
Sensor Values
Environmental Sensing service exposes sensor values. These values are updated every second.
| Characteristic | Data Type | Note |
|---|---|---|
| Temperature | signed 16-bit integer | Multiplied by 100, needed to conform to the GATT temperature characteristic format (e.g. 25.02°C is represented as 2502). |
| Humidity | unsigned 16-bit integer | Multiplied by 100, needed to conform to the GATT humidity characteristic format (e.g. 63% is represented as 6300). |
| Illuminance | unsigned 32-bit integer | Multiplied by 100, needed to send floating value as unsigned 32-bit integer over GATT (e.g. 150.32 lux is represented as 15032). |
| VOC | signed 32-bit integer | - |
| Noise | unsigned 8-bit integer | - |
| Presence | signed 8-bit integer | Vacant = 1, Occupied = 4 |
| CO2 | unsigned 16-bit integer | - |
Device Information
Device Information service exposes following information about the sensor:
| Characteristic | Data Type | Note |
|---|---|---|
| Manufacturer Name | String | "Sauter" |
| Model Number String | String | e.g. FMS197F121A (Black gateway, with CO2) |
| Serial Number String | String | Production serial number |
| Hardware Revision String | String | Hardware index of device |
| Firmware Revision String | String | Firmware version of device |
| Production Date | String | YYWW format, e.g. 2314 |
Provisioning
Provisioning service exposes following network information:
| Characteristic | Data Type | Note |
|---|---|---|
| Ethernet Connection State | boolean | 0 = disconnected, 1 = connected |
| Reset Device | boolean | 1 = will erase flash and reboot the device |
| Scanned Wi-Fi Networks List | array of Wi-Fi Access Point Info Data | |
| Network Mode | unsigned 8-bit integer | 0 = undefined, 1 = BLE Mesh, 2 = IoT Ethernet, 3 = IoT Wi-Fi, 4 = IoT Ethernet and Wi-Fi |
| Wi-Fi Connection State | boolean | 0 = disconnected, 1 = connected |
Here's breakdown of Wi-Fi Access Point Info Data:
| Field | Data Type | Description |
|---|---|---|
| BSSID | 6-char String | BSSID of the network |
| SSID | 31-char String | SSID of the network |
| RSSI | unsigned 8-bit integer | Signal strength |
| Security Mode | unsigned 8-bit integer | 0 = open, 1 = secure |
Calibration
Calibration service exposes calibration parameters for temperature, PIR and light sensors:
| Characteristic | Data Type | Note |
|---|---|---|
| Temperature Emissivity | unsigned 8-bit integer | In percentages, from 0 to 100 |
| PIR Sensitivity | unsigned 8-bit integer | 0 = low, 1 = medium, 2 = high |
| Light Parameters | structure of two floats | Slope and intercept |