### Value Trigger Setting Example (Temperature)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/descriptors.md

Shows an example of a Value Trigger Setting descriptor configuration for temperature. This descriptor enables power-efficient notifications by specifying threshold conditions for automatic alerts.

```text
Send notification only when temperature changes by ≥0.5°C
```

--------------------------------

### String Encoding Examples

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Explains the encoding for UTF-8 strings, noting their variable length, optional null termination, and support for multi-byte characters. Examples show byte representations for ASCII and multi-byte characters.

```plaintext
UTF-8 strings:
- Variable length (0–512 bytes typical)
- Null termination optional in GATT
- Multi-byte characters allowed
- Character encoding preserved

Example:
"Device" → 0x44 0x65 0x76 0x69 0x63 0x65 (6 bytes)
"温度" (temperature in Chinese) → 0xE6 0xB8 0xA9 0xE5 0xBA 0xA6 (6 bytes)
```

--------------------------------

### Property Lookup Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/README.md

Illustrates how to find a Bluetooth device property based on a requirement, such as temperature monitoring, and identifies the corresponding characteristic, type, and unit.

```text
Given: Temperature monitoring requirement
Find: api-reference/device-properties.md → Ambient Temperature category
Match: org.bluetooth.property.ambient_temperature
Type: org.bluetooth.characteristic.temperature (sint16, 0.01°C)
Unit: org.bluetooth.unit.temperature.celsius
```

--------------------------------

### Characteristic User Description Examples

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/descriptors.md

Provides examples of human-readable descriptions for GATT characteristics.

```text
"Device Name"
"Heart Rate in BPM"
"Room Temperature Sensor"
"Dimmer Level (0–100%)"
```

--------------------------------

### Report Reference Example (HID Input Report)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/descriptors.md

Provides an example of a Report Reference Descriptor for an HID input report, specifying Report ID 0x01 and Report Type 0x01 (input).

```text
Report ID: 0x01
Report Type: 0x01 (input)
→ First HID input report definition
```

--------------------------------

### MAC Address Encoding Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Details the 6-byte MAC address format, which is transmitted with the least significant byte first. The example shows how a standard address maps to the byte sequence.

```plaintext
6 bytes, LSB first:
Address: AA:BB:CC:DD:EE:FF
Bytes: AA BB CC DD EE FF (already in correct order for Bluetooth)
```

--------------------------------

### UUID Resolution Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/README.md

Demonstrates how to resolve a 16-bit UUID to its corresponding service definition and related information within the API reference.

```text
Given: 0x180D (16-bit UUID)
Find: api-reference/services.md
Match: "0x180D: Heart Rate Service"
Result: org.bluetooth.service.heart_rate (identifier)
Related: 3 characteristics, 1 property group
```

--------------------------------

### Sint32 Power Conversion Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Illustrates the conversion of a raw sint32 value representing power in Watts to kilowatts, horsepower, and BTU/h. This demonstrates unit scaling for power measurements.

```plaintext
Raw value: 0x000000FA = 250 W
Conversions:
  kW: 250 / 1000 = 0.25 kW
  hp: 250 / 746 ≈ 0.335 hp (mechanical)
  BTU/h: 250 × 3.41214 ≈ 852.8 BTU/h (heat)
```

--------------------------------

### Characteristic Interpretation Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/README.md

Shows how to interpret a characteristic value by decoding its format, unit, and scaling, using the Heart Rate Measurement characteristic as an example.

```text
Given: Characteristic value 0x48 from 0x2A37
Find: api-reference/characteristics.md → Heart Rate Measurement
Decode: Format uint8, unit BPM, no scaling
Result: 72 BPM
```

--------------------------------

### SFLOAT Encoding Example (Temperature)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Shows the encoding process for a SFLOAT value representing 23.50°C. It details the mantissa and exponent calculation and the final byte representation in little-endian format.

```text
Mantissa: 2350 = 0x092E (12-bit signed)
Exponent: –2 (0xE in 4-bit signed = subtract 2)
Encoding: 0x092E (value part) | (0xE << 12) = 0xE92E
Bytes in LE: 0x2E 0xE9
```

--------------------------------

### Enumeration Encoding Examples

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Demonstrates how sequential integers are used to represent named states or categories. Each integer maps to a specific meaning.

```plaintext
Example (Alert Level, uint8):
0x00: No Alert
0x01: Mild Alert
0x02: High Alert

Characteristic value: 0x01 → Mild Alert active
```

```plaintext
Example (Body Sensor Location, uint8):
0x00: Other
0x01: Chest
0x02: Wrist
0x03: Finger
0x04: Hand
0x05: Ear Lobe
0x06: Ear

Characteristic value: 0x02 → Wrist-worn sensor
```

--------------------------------

### UUID to Hex Conversion Examples

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/uuids-and-identifiers.md

Illustrates the conversion of common Bluetooth SIG identifiers to their 16-bit and 128-bit UUID hexadecimal representations.

```text
Heart Rate Service:
  Identifier: org.bluetooth.service.heart_rate
  16-bit UUID: 0x180D
  128-bit UUID: 0000180D-0000-1000-8000-00805F9B34FB
```

```text
Heart Rate Measurement Characteristic:
  Identifier: org.bluetooth.characteristic.heart_rate_measurement
  16-bit UUID: 0x2A37
  128-bit UUID: 00002A37-0000-1000-8000-00805F9B34FB
```

--------------------------------

### Characteristic Aggregate Format Example (Blood Pressure)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/descriptors.md

Shows an example of the Characteristic Aggregate Format Descriptor, referencing format descriptors for systolic, diastolic, and MAP values.

```text
Aggregate Format Descriptor Value:
- 0x2904 (Systolic Format Descriptor)
- 0x2904 (Diastolic Format Descriptor)
- 0x2904 (MAP Format Descriptor)
```

--------------------------------

### Uint32 Pressure Conversion Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Shows how to convert a raw uint32 value representing pressure in Pascals to other common units like hPa, bar, and psi. This involves simple division or multiplication.

```plaintext
Raw value: 0x0001869F = 99999 (Pa)
Typical conversions:
  hPa: 99999 / 100 = 999.99 hPa
  bar: 99999 / 100000 = 0.99999 bar
  psi: 99999 / 6894.76 ≈ 14.50 psi
```

--------------------------------

### Custom 128-bit GATT UUID Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/GATT_PROTOCOL_OVERVIEW.md

Provides an example of a 128-bit UUID format used for vendor-specific or custom GATT attributes.

```plaintext
128-bit UUIDs: For vendor-specific or custom attributes
550E8400-E29B-41D4-A716-446655440000 (example custom service)
```

--------------------------------

### GATT Handle Assignment Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/GATT_PROTOCOL_OVERVIEW.md

Demonstrates how handles are assigned sequentially to GATT attributes, noting that they are not guaranteed to be contiguous.

```plaintext
Primary Service (Handle 0x0001)
  Characteristic (Handle 0x0002)
    Value (Handle 0x0003)
    CCCD (Handle 0x0004)
Primary Service (Handle 0x0010) — Gap because first service has few characteristics
  Characteristic (Handle 0x0011)
    Value (Handle 0x0012)
```

--------------------------------

### Unit Scaling Examples

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Illustrates how raw integer values are scaled to represent physical quantities like temperature, power, and percentage. Note the implied decimal places and data types.

```plaintext
Temperature (sint16 with 0.01°C resolution):
Raw value: 0x0B8C = 2956 (signed 16-bit)
Actual value: 2956 × 0.01 = 29.56°C

Raw value: 0xFD7E = –658 (signed 16-bit)
Actual value: –658 × 0.01 = –6.58°C
```

```plaintext
Power (sint32 with 1W resolution):
Raw value: 0x00000321 = 801
Actual value: 801 W
```

```plaintext
Percentage (uint16 with 0.01% resolution):
Raw value: 0x0000 = 0
Actual value: 0.00%

Raw value: 0x27FF = 10239
Actual value: 102.39% (over 100%)

Raw value: 0x2710 = 10000
Actual value: 100.00%
```

--------------------------------

### Bluetooth SFLOAT Temperature Conversion Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Demonstrates the conversion of raw bytes representing a Bluetooth SFLOAT value into a temperature in degrees Celsius. This involves interpreting mantissa and exponent bits.

```plaintext
Bytes: 0xA0 0x06
Little-endian interpretation:
  Lower byte (0xA0): mantissa bits 0–7 = 0xA0
  Upper byte (0x06): mantissa bits 8–11 = 0x006, exponent = 0x06 >> 4 = 0x0
  Mantissa: 0x06A0 = 1696 (12-bit signed)
  Exponent: 0x06 >> 4 = 0 (but sign extended from 4-bit signed)
  
  Actually: 0x06A0 in 12-bit = 1696
            Exponent = 0
  Value = 1696 × 2^0 = 1696 (units depend on characteristic)
  
For temperature with 0.01°C resolution: 1696 × 0.01 = 16.96°C
```

--------------------------------

### Characteristic Extended Properties Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/descriptors.md

Illustrates the condition for enabling Reliable Write using the Characteristic Extended Properties descriptor.

```text
If Reliable Write enabled (0x0001):
  Client must use "Prepare Write" followed by "Execute Write"
  with same sequence number
```

--------------------------------

### Date/Time Encoding Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Shows the byte structure for representing date and time information, including year, month, day, hour, minute, and second. Note the little-endian format for the year.

```plaintext
Byte 0–1: Year (uint16, 1582–9999)
Byte 2: Month (uint8, 1–12)
Byte 3: Day (uint8, 1–31)
Byte 4: Hour (uint8, 0–23)
Byte 5: Minute (uint8, 0–59)
Byte 6: Second (uint8, 0–59)

Example (2024-07-15 14:30:45):
0xE8 0x07 = 2024 (year, LE)
0x07 = 7 (month)
0x0F = 15 (day)
0x0E = 14 (hour)
0x1E = 30 (minute)
0x2D = 45 (second)
Bytes: E8 07 07 0F 0E 1E 2D
```

--------------------------------

### Heart Rate Service Discovery Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/descriptors.md

Illustrates a typical sequence for discovering services, characteristics, and their associated descriptors for a Heart Rate Service. This includes reading format, CCCD, and user description, followed by enabling notifications.

```text
Example: Heart Rate Service Discovery

1. Discover primary service 0x180D
2. Discover characteristics:
   - 0x2A37 (Heart Rate Measurement) with Notify
   - 0x2A38 (Body Sensor Location) with Read
   - 0x2A39 (Heart Control Point) with Write
3. For 0x2A37:
   - Discover descriptors
   - Read 0x2904 (format: uint8, BPM unit)
   - Read 0x2902 (CCCD: initially 0x0000)
   - Read 0x2901 (description: "Heart Rate Measurement")
4. Write 0x0001 to CCCD → enable notifications
5. Receive heart rate values via notifications
```

--------------------------------

### Valid Range Descriptor Example (Temperature)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/descriptors.md

Demonstrates the Valid Range descriptor for a temperature characteristic, specifying a lower bound of 15.00°C and an upper bound of 35.00°C using sint16 format.

```text
Format: sint16 (0.01°C units)
Valid Range Lower: 0x05DC (1500 = 15.00°C)
Valid Range Upper: 0x0DAC (3500 = 35.00°C)
```

--------------------------------

### Peripheral Preferred Connection Parameters Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/characteristics.md

Specifies the connection parameters that the peripheral device prefers. This characteristic is read-only and includes minimum and maximum connection intervals, slave latency, and supervision timeout.

```text
0x2A04: Peripheral Preferred Connection Parameters
ID: org.bluetooth.characteristic.gap.peripheral_preferred_connection_parameters

Connection parameters preferred by the peripheral device.

**Permissions**: Read

**Format**:
- Connection Interval Min (uint16, units 1.25ms)
- Connection Interval Max (uint16, units 1.25ms)
- Slave Latency (uint16)
- Supervision Timeout (uint16, units 10ms)

**Example**: For 50ms minimum, 100ms maximum: `(0x0028, 0x0050, 0x0000, 0x0064)`
```

--------------------------------

### FLOAT Encoding Example (Pressure)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Illustrates the encoding for a FLOAT value representing 101325 Pa. It shows the mantissa, exponent, and the resulting byte sequence in little-endian order.

```text
Mantissa: 0xF44E0
Exponent: 0x11
Encoding: 0x11F44E0
Bytes in LE: 0xE0 0x44 0xF4 0x11
```

--------------------------------

### Bitmask Encoding Examples

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Shows how individual bits within a byte or word represent specific states or features. Reserved bits must be zero.

```plaintext
Example (Device Status, uint8):
Bit 0: Online (1 = online, 0 = offline)
Bit 1: Fault (1 = fault detected)
Bit 2: Running (1 = device active)
Bits 3–7: Reserved (must be 0)

Raw value: 0x05 = 0b00000101
→ Online=1, Fault=0, Running=1
→ "Online and running, no fault"
```

```plaintext
Example (Capabilities, uint16):
Bit 0: Feature A available
Bit 1: Feature B available
Bit 2: Extended mode
Bits 3–15: Reserved

Raw value: 0x0007 = 0b0000000000000111
→ Features A, B, and extended mode available
```

--------------------------------

### Heart Rate Encoding Example (72 BPM)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Encodes a heart rate of 72 BPM with no optional fields, demonstrating the basic structure.

```Markdown
Flags: 0x00 (uint8 format, no optional fields)
HR Value: 0x48 = 72
Total: 0x00 0x48 (2 bytes)
```

--------------------------------

### Example Device Features Bitmask

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/gss-characteristics.md

Illustrates a uint16 bitmask for device features, where each bit signifies a specific feature's availability or state. Useful for encoding multiple boolean states efficiently.

```plaintext
Example: Device Features (uint16)
Bit 0: Feature A available
Bit 1: Feature B available
Bit 2: Feature C enabled
...
```

--------------------------------

### Service Data Format Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/assigned-numbers.md

Service Data types (0x16, 0x20, 0x21) consist of a UUID (16, 32, or 128 bits) followed by a service-specific payload. An example is the heart rate service data (0x180D) followed by the HR value.

```text
Example: Heart rate service data (0x180D) followed by HR value
```

--------------------------------

### 16-bit UUID Encoding Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Shows the encoding for a 16-bit UUID, which is a 16-bit unsigned integer represented in little-endian format.

```plaintext
16-bit UUID (uint16, little-endian):
Service 0x1800 (GAP)
Bytes: 0x00 0x18
```

--------------------------------

### Characteristic Format Example (Heart Rate)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/descriptors.md

Illustrates the Characteristic Format Descriptor for a heart rate measurement, specifying uint8 format, no exponent scaling, and beats per minute unit.

```text
Format: 0x04 (uint8)
Exponent: 0x00 (no scaling)
Unit: 0x2724 (beats per minute)
Name Space: 0x01 (Bluetooth)
Description: 0x0000 (no additional description)
```

--------------------------------

### Bluetooth Little-Endian Encoding Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Illustrates how a 32-bit unsigned integer is represented in little-endian byte order. Bluetooth consistently uses this format for multi-byte values.

```plaintext
Value: 0x12345678 (uint32)
Bytes in LE: 0x78 0x56 0x34 0x12
```

--------------------------------

### Appearance Characteristic Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/characteristics.md

Defines the device appearance using a 16-bit enum value, which helps in presenting the device category in a user interface. Permissions are Read-only. Refer to appearance_values.yaml for a comprehensive list of codes.

```text
0x2A01: Appearance
ID: org.bluetooth.characteristic.gap.appearance

Device appearance code (16-bit enum). Defines device category for UI presentation.

**Permissions**: Read

**Format**: Unsigned 16-bit integer

**Example Values**:
- 0x0000: Unknown
- 0x0040: Watch (generic)
- 0x0041: Watch (sports)
- 0x0080: Heart Rate Sensor
- 0x00C3: Pulse Oximeter
```

--------------------------------

### Days Since Epoch Encoding Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Encodes the number of days since the Unix epoch (1970-01-01) using a 16-bit unsigned integer.

```plaintext
Days since 1970-01-01

Example: 19896 = 2024-07-15
Bytes: 78 4D
```

--------------------------------

### Number of Digitals Descriptor Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/descriptors.md

Illustrates the use of the Number of Digitals descriptor to indicate the count of digital inputs or outputs within a characteristic. This descriptor is an unsigned 8-bit value.

```text
Characteristic: Digital Input States (8 GPIO pins)
Number of Digitals: 0x08 (8 inputs)
```

--------------------------------

### Unix Timestamp Encoding Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Represents time as the number of seconds elapsed since the Unix epoch (1970-01-01 00:00:00 UTC). This is a 32-bit unsigned integer.

```plaintext
Seconds since 1970-01-01 00:00:00 UTC

Example: 1721080245 = 2024-07-15 14:30:45 UTC
Bytes: B5 F8 6A 67
```

--------------------------------

### Device Name Characteristic Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/characteristics.md

Represents the human-readable name of a Bluetooth device. It can be up to 248 bytes in UTF-8 format and is exposed by the GAP service for discovery. Permissions can include Read and optional Write.

```text
0x2A00: Device Name
ID: org.bluetooth.characteristic.gap.device_name

Human-readable device name (up to 248 bytes UTF-8). Exposed by GAP service for discovery.

**Permissions**: Read, Write (optional)

**Example Value**: "My Fitness Tracker"
```

--------------------------------

### 128-bit UUID Conversion Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/uuids-and-identifiers.md

Illustrates how a 16-bit assigned UUID value is converted into a full 128-bit UUID using the Bluetooth base UUID. The 16-bit value is placed in the first two bytes, and the rest is the base UUID suffix.

```text
Assigned UUID:    0x1800
128-bit UUID:     00001800-0000-1000-8000-00805F9B34FB
```

--------------------------------

### Heart Rate Encoding Example (300 BPM with RR)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Encodes a heart rate of 300 BPM with RR intervals, showing uint16 HR value and variable RR interval encoding.

```Markdown
Flags: 0x11 (0x01 = uint16 format, 0x10 = RR intervals present)
HR Value: 0x2C 0x01 = 300 (little-endian uint16)
RR Intervals: 0xF0 0x03 0x10 0x04 = 1008, 1040 (ms, variable count)
```

--------------------------------

### GATT Characteristic Properties Bitmask Example (Battery Level)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/GATT_PROTOCOL_OVERVIEW.md

Shows the properties byte for a Battery Level characteristic. A value of 0x12 indicates both Read and Notify capabilities are enabled, allowing the client to request the current value and receive notifications on changes.

```GATT
Properties byte: 0x12 (bits 1 and 4 set)
→ Read and Notify capabilities
→ Client can request current value (Read)
→ Client can receive notifications on change
```

--------------------------------

### Project Overview and Navigation

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Documents providing project context, overview, and guidance for navigating the documentation.

```APIDOC
## Project Overview and Navigation

### Project Overview
- **Document:** `PROJECT_OVERVIEW.md`
- **Content:** General overview of the project and its specifications.

### README
- **Document:** `README.md`
- **Content:** Comprehensive README file serving as a navigation guide to all documentation.
```

--------------------------------

### Sample Appearance Codes

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/assigned-numbers.md

Provides a list of sample device appearance codes and their corresponding descriptions, illustrating the mapping between numerical codes and device types.

```text
0x0000: Generic Unknown
0x0040: Watch (Generic)
0x0041: Watch (Sports)
0x0080: Heart Rate Sensor (Generic)
0x0081: Heart Rate Sensor (Chest Belt)
0x00C3: Pulse Oximeter (Generic)
0x0100: Blood Pressure (Generic)
0x0101: Blood Pressure (Arm Cuff)
0x0102: Blood Pressure (Wrist)
0x0180: Thermometer (Generic)
0x0181: Thermometer (Ear)
0x0200: Generic Keyboard
0x0201: Keyboard (Numeric Keypad)
0x0280: Mouse
0x0400: Barometer
0x0500: Glucose Meter
0x0600: Running Footpod
0x0C00: Cycling Computer (Generic)
0x0C41: Cycling Power Meter (Crank)
0x0C42: Cycling Power Meter (Hub)
0x1400: Generic Smart Watch
0x1401: Smart Watch Sports
0x2000: Generic Light Fixture
0x2001: Light Fixture Dimmable
0x2002: Light Fixture Color
```

--------------------------------

### GATT Error Response Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/GATT_PROTOCOL_OVERVIEW.md

An example of a GATT Error Response where a client attempts to write an invalid value to a characteristic. The server responds with an error indicating the specific handle and an application-specific error code for 'out of range'.

```text
Client writes 99 to Battery Level (valid range 0–100)
Server → Client: Error Response, handle 0x000A, error code 0x80 (out of range)
```

--------------------------------

### Enable Indications (Write to CCCD)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/GATT_PROTOCOL_OVERVIEW.md

Subscribe to confirmed updates by writing the value 0x0002 to the CCCD. The server will send Handle Value Indications, and the client must confirm each.

```text
Client → Server: Write attribute 0x0004 (CCCD) with value 0x0002
Server → Client: Write Response (success)
[Server sends updates via Handle Value Indication, client confirms each]
```

--------------------------------

### Peripheral Privacy Flag Characteristic Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/characteristics.md

A boolean flag indicating whether the device is currently in privacy mode. Permissions include Read and optional Write.

```text
0x2A02: Peripheral Privacy Flag
ID: org.bluetooth.characteristic.gap.peripheral_privacy_flag

Boolean indicating whether device is in privacy mode.

**Permissions**: Read, Write (optional)

**Format**: Boolean (0 = public, 1 = private)
```

--------------------------------

### Software Revision String (0x2A28)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/characteristics.md

Returns the device's software/application version as a UTF-8 string. Supports read operations.

```APIDOC
## Software Revision String (0x2A28)

### Description
Software/application version string.

### Permissions
Read

### Format
UTF-8 string
```

--------------------------------

### 128-bit UUID Encoding Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Illustrates the encoding for a 128-bit UUID, which uses a base UUID with the 16-bit UUID substituted in the first two bytes. It is represented in little-endian format.

```plaintext
128-bit UUID (16 bytes, little-endian):
Base + 16-bit UUID substitution in bytes 0–1
Example: 0x180D (Heart Rate) becomes:
0D 18 00 00 00 00 10 00 80 00 00 80 5F 9B 34 FB
```

--------------------------------

### Device Property Hierarchy

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/device-properties.md

Illustrates the hierarchical structure of device properties, showing how services group related properties under a device.

```text
Device
├── Service 1
│   ├── Property A (Temperature)
│   ├── Property B (Humidity)
│   └── Property C (Pressure)
├── Service 2
│   ├── Property D (Power)
│   └── Property E (Energy)
└── Service 3
    ├── Property F (Battery)
    └── Property G (Status)
```

--------------------------------

### Hardware Revision String (0x2A27)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/characteristics.md

Provides the device's hardware version as a UTF-8 string. Supports read operations.

```APIDOC
## Hardware Revision String (0x2A27)

### Description
Hardware version string.

### Permissions
Read

### Format
UTF-8 string (e.g., "PCB Rev B")
```

--------------------------------

### Device Properties (DP) Documentation

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Reference for 203 Device Properties (DP) definitions across 15 group categories, covering properties like ambient temperature, electrical input, and general device information. Includes property types and access patterns.

```APIDOC
## Device Properties (DP) Documentation

### Description
This document provides a comprehensive reference for 203 Device Properties (DP) definitions, organized into 15 distinct group categories. It details property types, unit references, and access patterns relevant to various industry-specific deployments.

### Property Group Categories
- Ambient Temperature, Device Operating Temperature
- Electrical Input, Energy Management
- Environmental, General Device Information
- Light Control, Lighting
- Occupancy, Photometry, Power Supply Output
- Warranty and Service, Water and Moisture
- Motion Detection, Luminaire

### Key Information
- Property types and unit references
- Property access patterns
- Industry-specific deployments
```

--------------------------------

### Firmware Revision String (0x2A26)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/characteristics.md

Returns the device's firmware version as a UTF-8 string. Supports read operations.

```APIDOC
## Firmware Revision String (0x2A26)

### Description
Firmware version string.

### Permissions
Read

### Format
UTF-8 string (e.g., "v2.1.4")
```

--------------------------------

### Client Characteristic Configuration Descriptor (CCCD) Behavior

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/descriptors.md

Demonstrates the typical interaction flow for enabling and disabling notifications using the CCCD.

```text
Server State: "Heart Rate Measurement" characteristic has Notify permission
  ↓
Client connects
  ↓
Client reads 0x2902 CCCD → value is 0x0000 (notifications off)
  ↓
Client writes 0x0001 to 0x2902 CCCD
  ↓
Server begins sending Heart Rate Measurement notifications
  ↓
Client writes 0x0000 to 0x2902 CCCD
  ↓
Server stops sending notifications
```

--------------------------------

### Model Number String (0x2A24)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/characteristics.md

Returns the device's model number as a UTF-8 string. Supports read operations.

```APIDOC
## Model Number String (0x2A24)

### Description
Device model number as UTF-8 string.

### Permissions
Read

### Format
UTF-8 string (up to 248 bytes)

### Example
"Model XYZ-v2.1"
```

--------------------------------

### GATT Characteristics Documentation

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Specifications for over 500 GATT characteristics, including those for health measurements, device information, environmental sensors, and fitness equipment. It details parameter tables, permissions, and examples.

```APIDOC
## GATT Characteristics Documentation

### Description
This document details over 500 GATT characteristic specifications, essential for various Bluetooth applications. It covers characteristics for health measurements, device information, environmental sensing, and fitness equipment, along with their parameters, permissions, and usage examples.

### Characteristic Categories
- Temperature, pressure, humidity
- Health measurements (glucose, blood pressure, heart rate, SpO2)
- Device information strings
- HID input/output/feature reports
- Fitness characteristics (cycling, running)
- Environmental sensors

### Included Details
- Parameter tables
- Permissions
- Examples
```

--------------------------------

### Repository Structure Overview

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/PROJECT_OVERVIEW.md

This snippet outlines the directory structure of the Bluetooth SIG Specification Database repository, detailing the organization of assigned numbers, core protocol definitions, Generic Sensor Service (GSS) characteristics, and Device Properties (DP).

```tree
    /workspace/home/public/
    ├── assigned_numbers/              # Assigned identifiers and base UUIDs
    │   ├── core/                      # Core Bluetooth protocol assignments
    │   │   ├── ad_types.yaml          # Advertisement data type codes
    │   │   ├── appearance_values.yaml # Device appearance classifications
    │   │   ├── class_of_device.yaml   # CoD values for classic Bluetooth
    │   │   ├── coding_format.yaml     # Audio codec format definitions
    │   │   ├── formattypes.yaml       # Data format type definitions
    │   │   ├── namespace.yaml         # Namespace value enumeration
    │   │   ├── psm.yaml               # Protocol/Service Multiplexer values
    │   │   └── [13 other core files]
    │   ├── company_identifiers/       # Bluetooth manufacturer IDs
    │   ├── mesh/                      # Mesh profile assignments
    │   ├── profiles_and_services/     # Service and profile identifiers
    │   ├── service_discovery/         # SDP-related identifiers
    │   └── uuids/                     # 128-bit UUID definitions
    │       ├── service_uuids.yaml     # 75 GATT service definitions
    │       ├── characteristic_uuids.yaml  # 504 characteristic definitions
    │       ├── descriptors.yaml       # GATT descriptor definitions
    │       ├── units.yaml             # Unit of measurement definitions
    │       └── [10 other UUID files]
    ├── gss/                           # Generic Sensor Service characteristics (277 specs)
    │   └── org.bluetooth.characteristic.*.yaml
    ├── dp/                            # Device Properties
    │   ├── property_groups.yaml       # Property category definitions
    │   ├── property_ids.yaml          # All property ID assignments
    │   └── properties/                # Individual property definitions (203 specs)
    │       └── org.bluetooth.property.*.yaml
    └── .git/                          # Version control
```

--------------------------------

### Enable Notifications (Write to CCCD)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/GATT_PROTOCOL_OVERVIEW.md

Subscribe to unsolicited characteristic updates by writing the value 0x0001 to the CCCD. The server will then send Handle Value Notifications.

```text
Client → Server: Write attribute 0x0004 (CCCD of Heart Rate Measurement) with value 0x0001
Server → Client: Write Response (success)
[Server subsequently sends heart rate values via Handle Value Notification]
```

--------------------------------

### Reconnection Address Characteristic Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/characteristics.md

Provides a static Bluetooth address for reconnection, particularly when the device is in privacy mode. This characteristic requires Write permissions if privacy mode is enabled and is formatted as a 6-byte Bluetooth address.

```text
0x2A03: Reconnection Address
ID: org.bluetooth.characteristic.gap.reconnection_address

Static address for reconnection after privacy mode. 6 bytes.

**Permissions**: Write (if privacy mode enabled)

**Format**: 6-byte Bluetooth address
```

--------------------------------

### Service Changed Characteristic

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/characteristics.md

The Service Changed characteristic is used to notify clients when the GATT services on the server have been added or removed. It supports indicate permissions and requires start and end handles to define the changed range.

```APIDOC
## Characteristic: Service Changed

### Description
Range indication notification when GATT services are added/removed.

### UUID
`0x2A05`

### ID
`org.bluetooth.characteristic.gatt.service_changed`

### Permissions
Indicate (notification-style)

### Format
- Start Handle (uint16)
- End Handle (uint16)

### Typical Usage
Server notifies clients when attribute database changes.
```

--------------------------------

### API Reference Documentation

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

The API reference documentation is organized into several documents covering services, characteristics, descriptors, device properties, data types, units, and error codes. It provides detailed specifications, including UUIDs, field tables, format details, and permission information.

```APIDOC
## API Reference

This section details the available API reference documents:

### Services
- **Document:** `api-reference/services.md`
- **Content:** Documentation for 75 services, including detailed specifications.

### Characteristics
- **Document:** `api-reference/characteristics.md`
- **Content:** Documentation for 500+ characteristics, with detailed field tables.

### Descriptors
- **Document:** `api-reference/descriptors.md`
- **Content:** Documentation for 26 standard descriptors, including format and permission details.

### GSS Characteristics
- **Document:** `api-reference/gss-characteristics.md`
- **Content:** Documentation for 277 GSS characteristics, with structure and unit information.

### Device Properties
- **Document:** `api-reference/device-properties.md`
- **Content:** Documentation for 203 device properties, organized in 15 categories.

### Units
- **Document:** `api-reference/uuids-and-identifiers.md` (also contains UUID References)
- **Content:** Definitions for 415+ units (temperature, electrical, light, etc.) and 1000+ UUID references.

### Data Types and Encodings
- **Document:** `DATA_FORMATS_AND_TYPES.md`
- **Content:** Specification of data types and encodings, including 30+ examples of data type usage (integer, float, composite types).
```

--------------------------------

### Lighting and Illumination Properties

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/device-properties.md

Properties for light output, illuminance, light color temperature, and light color index. Used for ambient light sensing and brightness/color control.

```properties
- org.bluetooth.property.light_output
- org.bluetooth.property.illuminance
- org.bluetooth.property.light_color_temperature
- org.bluetooth.property.light_color_index
```

--------------------------------

### Service Changed Characteristic Example

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/characteristics.md

Notifies clients when GATT services on the server have been added or removed. It indicates a range of handles that have changed and is typically used by the server to inform clients about attribute database modifications. Permissions are Indicate.

```text
0x2A05: Service Changed
ID: org.bluetooth.characteristic.gatt.service_changed

Range indication notification when GATT services are added/removed.

**Permissions**: Indicate (notification-style)

**Format**:
- Start Handle (uint16)
- End Handle (uint16)

**Typical Usage**: Server notifies clients when attribute database changes.
```

--------------------------------

### Discover Primary Services (ATT Find By Type Value Request)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/GATT_PROTOCOL_OVERVIEW.md

Use this request to discover all primary services or services by a specific type. The response lists service declarations with their handles and UUIDs.

```text
Client → Server: Find primary services
Server → Client: 
  Service 0x180D (Heart Rate) at handles 0x0001–0x0008
  Service 0x180F (Battery) at handles 0x0009–0x000E
  Service 0x1800 (GAP) at handles 0x000F–0x0015
```

--------------------------------

### Data Format Types Table

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/assigned-numbers.md

A table detailing the characteristic value format codes used in Bluetooth service and characteristic definitions. It includes the format code, type name, size in bytes, value range, and a brief example.

```markdown
| Format Code | Type | Size | Range | Example |
|------------|------|------|-------|---------|
| 0x00 | Reserved | — | — | — |
| 0x01 | Boolean | 1 | 0–1 | On/Off |
| 0x02 | 2bit | 1 | 0–3 | State enum |
| 0x03 | nibble | 1 | 0–15 | Status |
| 0x04 | uint8 | 1 | 0–255 | Counter |
| 0x05 | uint12 | 2 | 0–4095 | Percent |
| 0x06 | uint16 | 2 | 0–65535 | Larger value |
| 0x07 | uint24 | 3 | 0–16M | Extended count |
| 0x08 | uint32 | 4 | 0–4B | Large counter |
| 0x09 | uint48 | 6 | 0–281T | Very large |
| 0x0A | uint64 | 8 | 0–18E18 | Huge values |
| 0x0B | uint128 | 16 | 0–2^128 | UUID/hash |
| 0x0C | sint8 | 1 | –128 to +127 | Signed byte |
| 0x0D | sint12 | 2 | –2048 to +2047 | Signed value |
| 0x0E | sint16 | 2 | –32K to +32K | Temperature |
| 0x0F | sint24 | 3 | –8M to +8M | Extended signed |
| 0x10 | sint32 | 4 | ±2.1B | Wide range |
| 0x11 | sint48 | 6 | ±140T | Extended |
| 0x12 | sint64 | 8 | ±9E18 | Timestamp |
| 0x13 | sint128 | 16 | ±2^127 | Large signed |
| 0x14 | float32 | 4 | ±3.4e38 | IEEE 754 |
| 0x15 | float64 | 8 | ±1.7e308 | Double precision |
| 0x16 | SFLOAT | 2 | ±2e±38 | Sensor data |
| 0x17 | FLOAT | 4 | ±3.4e±38 | Extended float |
| 0x18 | DUInt16 | 2 | — | Decade encoding |
| 0x19 | UTF8S | var | — | UTF-8 string |
| 0x1A | UTF16S | var | — | UTF-16 string |
| 0x1B | Struct | var | — | Composite |
```

--------------------------------

### Warranty and Lifecycle Properties

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/device-properties.md

Properties for device warranty, warranty end date, device runtime, and warranty runtime. Used for warranty verification and product lifecycle management.

```properties
- org.bluetooth.property.device_warranty
- org.bluetooth.property.device_warranty_end_date
- org.bluetooth.property.device_runtime
- org.bluetooth.property.warranty_runtime
```

--------------------------------

### GATT Characteristic Properties Bitmask Example (Heart Rate)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/GATT_PROTOCOL_OVERVIEW.md

Illustrates the properties byte for a Heart Rate Measurement characteristic. A value of 0x10 indicates only the Notify capability is enabled, meaning the server sends updates and the client implicitly acknowledges them.

```GATT
Properties byte: 0x10 (bit 4 set)
→ Notify capability only
→ Client can enable notifications via CCCD
→ Server initiates updates
→ Client acknowledges receipt implicitly
```

--------------------------------

### Handle Value Indication (Server → Client)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/GATT_PROTOCOL_OVERVIEW.md

Server sends solicited updates when a characteristic value changes, requiring client confirmation. This is used for critical updates and ensures reliability through retries until confirmed.

```text
Server → Client: Handle Value Indication, handle 0x000B (Alert), value 0x02 (high alert)
Client → Server: Confirmation
```

--------------------------------

### Reserved Values for Humidity (uint16)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Illustrates reserved and special values for humidity measurements encoded as uint16.

```Markdown
0x0000–0x27FE: Valid values (0.00–101.98%)
0x27FF: Special "above 100%"
0xFFFF: Not known / sensor error
```

--------------------------------

### Discover Descriptors (ATT Find Information Request)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/GATT_PROTOCOL_OVERVIEW.md

Use this request to find all descriptors of a characteristic. The response includes descriptor types (UUIDs) and their handles.

```text
Client → Server: Find information (handles 0x0003–0x0005)
Server → Client:
  0x2902 (CCCD) at handle 0x0004
  0x2904 (Format) at handle 0x0005
```

--------------------------------

### GATT Services Documentation

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Documentation for 75 GATT services, including common profiles like GAP, GATT, Heart Rate, and Environmental Sensing. It details service organization and UUID allocation ranges.

```APIDOC
## GATT Services Documentation

### Description
This document provides detailed specifications for 75 GATT services, covering a wide range of Bluetooth profiles and use cases. It includes information on service organization by category and UUID allocation ranges.

### Services Documented
- GAP
- GATT
- Heart Rate
- Glucose
- Temperature
- Battery
- Blood Pressure
- HID
- Environmental Sensing
- Cycling Power
- Weight Scale
- Pulse Oximetry

### Key Information
- Service organization by category
- UUID allocation ranges
```

--------------------------------

### Temperature Monitoring Properties

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/device-properties.md

Properties for monitoring ambient, device operating, water, and surface temperatures. Typical use is environmental monitoring and device health.

```properties
- org.bluetooth.property.ambient_temperature
- org.bluetooth.property.device_operating_temperature
- org.bluetooth.property.water_temperature
- org.bluetooth.property.surface_temperature
```

--------------------------------

### Signed Integer Encoding (sint8)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DATA_FORMATS_AND_TYPES.md

Demonstrates two's complement representation for negative numbers in sint8. Shows the encoding for -1, minimum (-128), and maximum (+127).

```text
–1 in sint8: 0xFF (255 unsigned = –1 signed)
–128 in sint8: 0x80 (minimum)
+127 in sint8: 0x7F (maximum)
```

--------------------------------

### Manufacturer Name String (0x2A29)

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/characteristics.md

Provides the name of the company that manufactures the device as a UTF-8 string. Supports read operations.

```APIDOC
## Manufacturer Name String (0x2A29)

### Description
Company name that manufactures the device.

### Permissions
Read

### Format
UTF-8 string

### Example
"XYZ Electronics Inc."
```

--------------------------------

### Data Format Conventions

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/api-reference/characteristics.md

Details on the data formats used for Bluetooth characteristics, including numeric types and special formats like SFLOAT.

```APIDOC
## Data Format Conventions

### Numeric Types
| Format | Size | Range | Precision |
|--------|------|-------|-----------|
| uint8 | 1 byte | 0–255 | 1 |
| uint16 | 2 bytes | 0–65535 | 1 |
| uint32 | 4 bytes | 0–4.3B | 1 |
| sint8 | 1 byte | –128 to +127 | 1 |
| sint16 | 2 bytes | –32768 to +32767 | 1 |
| sint32 | 4 bytes | ±2.1B | 1 |
| SFLOAT | 2 bytes | ±2E±38 | ~0.1% |
| FLOAT | 4 bytes | ±3.4E±38 | ~0.01% |

### Special Formats
**SFLOAT (Short Float)**: 4-bit exponent, 12-bit mantissa. Used for sensor data with variable magnitude.

**Reserved Exponent/Mantissa**: 0xFFFF = value not known, 0x8000 = NRES, 0x0000 = zero
```

--------------------------------

### UUIDs and Identifiers Documentation

Source: https://github.com/bluetooth-sig/public/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Details on Bluetooth UUID architecture (16/32/128-bit), base UUID derivation, and allocation of UUIDs for services, characteristics, and descriptors. Includes units reference and naming conventions.

```APIDOC
## UUIDs and Identifiers Documentation

### Description
This document outlines the architecture of Bluetooth UUIDs, including 16, 32, and 128-bit formats, and the process for deriving base UUIDs. It details the allocation of UUIDs for services, characteristics, and descriptors, along with a comprehensive units reference and identifier naming conventions.

### UUID Architecture
- 16/32/128-bit UUIDs
- Base UUID derivation

### UUID Allocations
- Service UUIDs (75)
- Characteristic UUIDs (504)
- Descriptor UUIDs (26)
- Service class UUIDs (260+)

### Other References
- Units reference (415+)
- Identifier naming conventions
```