BLE Configuration Schema Documentation¶

This document provides a comprehensive guide to the BLE (Bluetooth Low Energy) configuration schema. The schema defines the structure and content of BLE services, characteristics, and their data fields.

Table of Contents¶

Global Options
Services
Characteristics
Data Fields
Value Tables
Custom Types
Full Example Configuration

Global Options¶

Global options are settings that apply to the entire BLE configuration.

Description¶

Provides a human-readable description of the BLE configuration.

Attribute	Type	Required	Example
description	string	No	"Fitness Tracker BLE Codec Configuration Example"

Byte Order¶

Defines the endianness of the bytes. The default is little.

Attribute	Type	Required	Example
byteorder	string	No	"little"

Example:

description: "Fitness Tracker BLE Codec Configuration Example"
byteorder: "little"

Services¶

Services are collections of characteristics that provide specific functionality in a BLE device.

Structure¶

Attribute	Type	Required	Example
uuid	string	Yes	"0000180D-0000-1000-8000-00805F9B34FB"
characteristics	list	Yes	["heart_rate_measurement", "body_sensor_location"]

Explanation¶

uuid: A unique identifier for the service.
characteristics: A list of characteristics that belong to this service.

Example:

services:
  heart_rate_service:
    uuid: "0000180D-0000-1000-8000-00805F9B34FB"
    characteristics:
      - heart_rate_measurement
      - body_sensor_location

Characteristics¶

Characteristics are attributes that describe specific properties and behaviors of a service.

Structure¶

Attribute	Type	Required	Example
uuid	string	Yes	"00002A37-0000-1000-8000-00805F9B34FB"
service_uuid	string	Yes	"0000180D-0000-1000-8000-00805F9B34FB"
properties	list	Yes	["read", "notify"]
data	dict	Yes	See Data Fields section

Explanation¶

uuid: A unique identifier for the characteristic.
service_uuid: The UUID of the service this characteristic belongs to.
properties: Properties that describe the behavior of the characteristic (e.g., read, write, notify, indicate).
data: The actual data fields within the characteristic.

Example:

characteristics:
  heart_rate_measurement:
    uuid: "00002A37-0000-1000-8000-00805F9B34FB"
    service_uuid: "0000180D-0000-1000-8000-00805F9B34FB"
    properties: ["notify"]
    data:
      heart_rate:
        datatype: "uint8"
        offset: 0
        length: 1
        units: "bpm"
      energy_expended:
        datatype: "uint16"
        offset: 1
        length: 2
        array_size: 2
        units: "kJ"

Data Fields¶

Data fields describe the raw data payload of a characteristic. Each field specifies the datatype, offset, length, and other optional attributes.

Structure¶

Attribute	Type	Required	Example
datatype	string	Yes	"uint8", "float"
value_table	string	No	"BodySensorLocation"
offset	integer	Yes	0
length	integer	Yes	1
default	integer/float/string	No	0, 0.0, "default"
units	string	No	"bpm", "kJ"
min	integer	No	0
max	integer	No	255
array_size	integer	No	2

Explanation¶

datatype: The type of the data field (e.g., uint8, int32, float, string, enum).
value_table: The value table for enumerations (optional).
offset: The offset of the data field in the characteristic value.
length: The length of the data field in bytes.
default: The default value of the data field (optional).
units: The units of the data field (optional).
min: The minimum value for the data field (optional).
max: The maximum value for the data field (optional).
array_size: The size of the array (if applicable, optional).

Example:

data:
  heart_rate:
    datatype: "uint8"
    offset: 0
    length: 1
    units: "bpm"
  energy_expended:
    datatype: "uint16"
    offset: 1
    length: 2
    array_size: 2
    units: "kJ"

Value Tables¶

Value tables define enumerations for data fields, mapping integer keys to string values.

Structure¶

Attribute	Type	Required	Example
Value Table Key	integer	Yes	0, 1, 2
Value Table Value	string	Yes	"OTHER", "CHEST"

Explanation¶

Value Table Key: Integer keys representing different enumeration values.
Value Table Value: String values corresponding to the integer keys.

Example:

value_tables:
  body_sensor_location:
    0: "OTHER"
    1: "CHEST"
    2: "WRIST"
    3: "FINGER"
    4: "HAND"
    5: "EAR_LOBE"
    6: "FOOT"

Custom Types¶

Custom types define complex data structures that can be reused in multiple characteristics. Each custom type is a dictionary of subfields.

Structure¶

Attribute	Type	Required	Example
datatype	string	Yes	"uint16", "UserPreferences"
offset	integer	Yes	0, 2
length	integer	Yes	2, 1
default	integer/float/string	No	0, 0.0
units	string	No	"seconds"
min	integer	No	0
max	integer	No	255
array_size	integer	No	2

Explanation¶

datatype: The type of the subfield.
offset: The offset of the subfield in the custom type.
length: The length of the subfield in bytes.
default: The default value of the subfield (optional).
units: The units of the subfield (optional).
min: The minimum value for the subfield (optional).
max: The maximum value for the subfield (optional).
array_size: The size of the array (if applicable, optional).

Example:

custom_types:
  user_preferences:
    mode:
      datatype: "uint8"
      offset: 0
      length: 1
    units:
      datatype: "uint8"
      offset: 1
      length: 1
    theme:
      datatype: "uint8"
      offset: 2
      length: 1
    notifications:
      datatype: "uint8"
      offset: 3
      length: 1

Full Example Configuration¶

Here is a full example configuration for a BLE device:

fitness_profile.yml¶

# Here is an example BLE codec configuration file. It contains the following:
#
# Services:
# - UUID: A unique identifier for the service.
# - Characteristics: A list of characteristics that belong to this service.
#
# Characteristics:
# - UUID: A unique identifier for the characteristic.
# - Service UUID: A associated unique identifier for the characteristics services.
# - Properties: A set of properties that describe the behavior of the characteristic (e.g., read, write, notify, indicate).
# - Fields: The actual data contained in the characteristic. Essentially a representation of the raw bytes payload
#
# Characteristics Fields:
# - Type: The data type of the field
# - Offset: The offset of the field in the characteristic value
# - Length: The length of the field in bytes
# - Default: The default value of the field
# - Unit: The unit of the field
# - Min: The minimum value for the field (if applicable)
# - Max: The maximum value for the field (if applicable)
# - Array Size: The array size for the field (if applicable)
description: "Fitness Tracker BLE Codec Configuration Example"
byteorder: "little"

services:
  heart_rate_service:
    uuid: "0000180D-0000-1000-8000-00805F9B34FB"
    characteristics:
      - heart_rate_measurement
      - body_sensor_location

  fitness_service:
    uuid: "00001826-0000-1000-8000-00805F9B34FB"
    characteristics:
      - step_count
      - calories_burned
      - distance_traveled
      - fitness_goal
      - user_settings

characteristics:
  heart_rate_measurement:
    uuid: "00002A37-0000-1000-8000-00805F9B34FB"
    service_uuid: "0000180D-0000-1000-8000-00805F9B34FB"
    properties: ["read", "notify"]
    fields:
      heart_rate:
        datatype: "uint8"
        offset: 0
        length: 1
        unit: "bpm"
      energy_expended:
        datatype: "uint16"
        offset: 1
        length: 2
        array_size: 2
        unit: "kJ"

  body_sensor_location:
    uuid: "00002A38-0000-1000-8000-00805F9B34FB"
    service_uuid: "0000180D-0000-1000-8000-00805F9B34FB"
    properties: ["read"]
    fields:
      location:
        datatype: "enum"
        value_table: "body_sensor_location"
        offset: 0
        length: 1

  step_count:
    uuid: "00002A53-0000-1000-8000-00805F9B34FB"
    service_uuid: "00001826-0000-1000-8000-00805F9B34FB"
    properties: ["read", "notify"]
    fields:
      steps:
        datatype: "uint32"
        offset: 0
        length: 4
        unit: "steps"

  calories_burned:
    uuid: "00002A66-0000-1000-8000-00805F9B34FB"
    service_uuid: "00001826-0000-1000-8000-00805F9B34FB"
    properties: ["read", "notify"]
    fields:
      calories:
        datatype: "uint16"
        offset: 0
        length: 2
        unit: "kcal"

  distance_traveled:
    uuid: "00002A67-0000-1000-8000-00805F9B34FB"
    service_uuid: "00001826-0000-1000-8000-00805F9B34FB"
    properties: ["read", "notify"]
    fields:
      distance:
        datatype: "float"
        offset: 0
        length: 4
        unit: "meters"

  fitness_goal:
    uuid: "00002A7E-0000-1000-8000-00805F9B34FB"
    service_uuid: "00001826-0000-1000-8000-00805F9B34FB"
    properties: ["read", "write"]
    fields:
      daily_steps_goal:
        datatype: "uint32"
        offset: 0
        length: 4
        unit: "steps"
      daily_calories_goal:
        datatype: "uint16"
        offset: 4
        length: 2
        unit: "kcal"
      daily_distance_goal:
        datatype: "float"
        offset: 6
        length: 4
        unit: "meters"

  user_settings:
    uuid: "00002A80-0000-1000-8000-00805F9B34FB"
    service_uuid: "00001826-0000-1000-8000-00805F9B34FB"
    properties: ["read", "write"]
    fields:
      age:
        datatype: "uint8"
        offset: 0
        length: 1
        unit: "years"
      weight:
        datatype: "uint8"
        offset: 1
        length: 1
        unit: "kg"
      height:
        datatype: "uint8"
        offset: 2
        length: 1
        unit: "cm"
      preferences:
        datatype: "user_preferences"
        offset: 3
        length: 4

value_tables:
  body_sensor_location:
    0: "OTHER"
    1: "CHEST"
    2: "WRIST"
    3: "FINGER"
    4: "HAND"
    5: "EAR_LOBE"
    6: "FOOT"

custom_types:
  user_preferences:
    mode:
      datatype: "uint8"
      offset: 0
      length: 1
    units:
      datatype: "uint8"
      offset: 1
      length: 1
    theme:
      datatype: "uint8"
      offset: 2
      length: 1
    notifications:
      datatype: "uint8"
      offset: 3
      length: 1