Skip to content

BLE_PROTOCOL.md

Latest commit

 

History

History
228 lines (181 loc) · 8.79 KB

BLE_PROTOCOL.md

File metadata and controls

228 lines (181 loc) · 8.79 KB

📡 BLE Protocol Documentation

Overview

The BLE (Bluetooth Low Energy) protocol is the primary transport mechanism for data exchange in Linked. This document describes the protocol specification, data format, and connection flow.

BLE Service Definition

Service UUID

Service UUID: 6E400001-B5A3-F393-E0A9-E50E24DCCA9E (Linked Exchange Service)

Characteristics

Characteristic UUID Properties Description
TX 6E400002-B5A3-F393-E0A9-E50E24DCCA9E Write, Write No Response Send data to peer
RX 6E400003-B5A3-F393-E0A9-E50E24DCCA9E Notify, Read Receive data from peer
Control 6E400004-B5A3-F393-E0A9-E50E24DCCA9E Write, Notify Control commands

Connection Flow

┌─────────────────┐                              ┌─────────────────┐
│    Device A     │                              │    Device B     │
│   (Initiator)   │                              │   (Responder)   │
└────────┬────────┘                              └────────┬────────┘
         │                                                │
         │  1. Start Advertising                          │
         │  ◄─────────────────────────────────────────────┤
         │                                                │
         │  2. Scan & Discover                            │
         ├────────────────────────────────────────────────►
         │                                                │
         │  3. Connect Request                            │
         ├────────────────────────────────────────────────►
         │                                                │
         │  4. Connection Established                     │
         │◄───────────────────────────────────────────────►
         │                                                │
         │  5. Discover Services                          │
         ├────────────────────────────────────────────────►
         │                                                │
         │  6. Services Discovered                        │
         │◄────────────────────────────────────────────────
         │                                                │
         │  7. Subscribe to RX Notifications              │
         ├────────────────────────────────────────────────►
         │                                                │
         │  8. Exchange Handshake                         │
         │◄───────────────────────────────────────────────►
         │                                                │
         │  9. Data Transfer                              │
         │◄───────────────────────────────────────────────►
         │                                                │
         │  10. Transfer Complete                         │
         │◄───────────────────────────────────────────────►
         │                                                │
         │  11. Disconnect                                │
         ├────────────────────────────────────────────────►
         │                                                │
         ▼                                                ▼

Data Packet Format

Header (8 bytes)

┌─────────────────────────────────────────────────────────┐
│  Byte 0-1  │  Byte 2  │  Byte 3-4  │  Byte 5-6  │ Byte 7│
├────────────┼──────────┼────────────┼────────────┼───────┤
│   Magic    │   Type   │  Sequence  │   Length   │  CRC  │
│   0x4C4B   │          │   Number   │            │       │
└─────────────────────────────────────────────────────────┘

Packet Types

Type Value Description
HANDSHAKE 0x01 Initial handshake
HANDSHAKE_ACK 0x02 Handshake acknowledgment
DATA 0x03 Data payload
DATA_ACK 0x04 Data acknowledgment
COMPLETE 0x05 Transfer complete
ERROR 0xFF Error occurred

Payload Structure

{
  "version": "1.0",
  "timestamp": 1702234567890,
  "deviceId": "uuid-string",
  "dataType": "profile|contact|custom",
  "payload": {
    // Actual data based on dataType
  },
  "signature": "base64-encoded-signature"
}

Handshake Protocol

Step 1: Initiator sends HANDSHAKE

{
  "version": "1.0",
  "deviceId": "initiator-uuid",
  "capabilities": ["profile", "contact", "file"],
  "mtu": 512,
  "publicKey": "base64-encoded-key"
}

Step 2: Responder sends HANDSHAKE_ACK

{
  "version": "1.0",
  "deviceId": "responder-uuid",
  "capabilities": ["profile", "contact"],
  "mtu": 256,
  "publicKey": "base64-encoded-key",
  "negotiatedMtu": 256
}

Data Transfer Protocol

Chunking Strategy

BLE has MTU limitations (typically 20-512 bytes). Data is chunked:

Total Data: 2048 bytes
Negotiated MTU: 256 bytes
Header Size: 8 bytes
Payload per packet: 248 bytes
Total packets needed: ceil(2048/248) = 9 packets

Packet Sequence

Packet 1: [Header: seq=0, len=248] [Payload: bytes 0-247]
Packet 2: [Header: seq=1, len=248] [Payload: bytes 248-495]
...
Packet 9: [Header: seq=8, len=64]  [Payload: bytes 1984-2047]

Acknowledgment Flow

Device A                          Device B
    │                                 │
    │─── DATA (seq=0) ──────────────►│
    │◄── DATA_ACK (seq=0) ───────────│
    │                                 │
    │─── DATA (seq=1) ──────────────►│
    │◄── DATA_ACK (seq=1) ───────────│
    │                                 │
    │         ... ...                 │
    │                                 │
    │─── DATA (seq=N, final) ───────►│
    │◄── DATA_ACK (seq=N) ───────────│
    │                                 │
    │─── COMPLETE ──────────────────►│
    │◄── COMPLETE ───────────────────│

Error Handling

Timeout Values

Operation Timeout Retry Count
Scan 30 seconds 1
Connect 10 seconds 3
Service Discovery 5 seconds 2
Data ACK 2 seconds 5

Error Codes

Code Name Description
0x01 CONNECTION_FAILED Unable to establish connection
0x02 SERVICE_NOT_FOUND Linked service not found
0x03 HANDSHAKE_FAILED Handshake rejected
0x04 TRANSFER_TIMEOUT Data transfer timed out
0x05 CHECKSUM_MISMATCH Data integrity check failed
0x06 VERSION_MISMATCH Incompatible protocol version

Security Considerations

Encryption

  1. BLE Level: Use BLE Secure Connections (LE Secure Connections)
  2. App Level: AES-256 encryption for payload
  3. Key Exchange: ECDH (Elliptic Curve Diffie-Hellman)

Data Integrity

  1. CRC-8 in packet header for quick validation
  2. SHA-256 hash of complete payload for final verification

Privacy

  1. Random MAC address rotation
  2. No persistent device identifiers in advertising data
  3. User consent required before any data exchange