# Bluetooth Discovery

Mecanismul de descoperire şi conectare a dispozitivelor Bluetooth.

## Arhitectură

### Components

1. **BluetoothManager**: coordonează CBCentralManager şi descoperirile

2. **BluetoothRadio**: interfață spre Core Bluetooth low-level

3. **BluetoothSerial**: comunicare pe caracteristici UART

4. **MeterCapabilities**: detectează tip meter (UM25C, UM34C, TC66C)

## Scanning

### Lifecycle

```

User opens app

  ↓

SceneDelegate calls appData.activateCloudDeviceSync()

  ↓

BluetoothManager starts CBCentralManager

  ↓

CBCentralManager begins scanning

  ↓

didDiscoverPeripheral → filter by service UUIDs

  ↓

Check device profile (class, capabilities)

  ↓

Add to discoveredMeters list (UI refresh)

```

### Service UUIDs

```swift

let targetServices = [

    CBUUID(string: "FFF0"),    // UM25C, UM34C

    CBUUID(string: "180D"),    // TC66C (generic service)

]

```

- **MUST**: Scan cu service UUIDs specifice (nu scan generic)

- **SHOULD**: Filter prin manufacturer data dacă posibil

- **REASON**: Reduce energy drain, reduce noise

### Advertisement parsing

Meter advertise-ază:

- Device name: de ex "UM25C-XXXX" sau "TC66-XXXX"

- Services: FFF0 (UM series) sau 180D (TC66)

- Manufacturer data: RDTech identifier

```swift

if let manufacturerData = advertisement[CBAdvertisementDataManufacturerDataKey] as? Data {

    let manufacturerId = manufacturerData.withUnsafeBytes { $0.load(as: UInt16.self) }

    if manufacturerId == 0x5449 { // RDTech

        // Possible UM meter

    }

}

```

- **SHOULD**: Parse manufacturer data pentru identificare rapidă

- **MAY**: Use device name ca fallback (less reliable)

### Device identification

```swift

func identifyMeterType(name: String, services: [CBUUID]) -> Model {

    if name.contains("UM25C") || services.contains(FFF0) {

        return .UM25C

    } else if name.contains("UM34C") || services.contains(FFF0) {

        return .UM34C

    } else if name.contains("TC66") || services.contains(180D) {

        return .TC66C

    }

    return .unknown

}

```

- **MUST**: Trebuie să identific corect tipul de meter

- **SHOULD**: Use name + services (redundant checks)

- **MUST**: Fallback la `.unknown` dacă uncertain

## Connection

### Initiation

```

User taps meter in list

  ↓

AppData calls meter.connect()

  ↓

BluetoothManager calls cbCentralManager.connect(peripheral)

  ↓

didConnect: state → peripheralConnected

  ↓

Discover services & characteristics

```

### Service/Characteristic discovery

```swift

// For UM series (FFF0)

let targetService = CBUUID(string: "FFF0")

let readCharacteristic = CBUUID(string: "FFF1")  // read measurements

let writeCharacteristic = CBUUID(string: "FFF2") // send commands

// For TC66 (180D)

let heartRate = CBUUID(string: "2A37")  // uses standard HRM characteristic

```

- **MUST**: Discover services → discover characteristics (ordered)

- **MUST**: Find expected characteristics, fail if not found

- **SHOULD**: Subscribe to notifications pentru updates

- **TIMEOUT**: 5s max pentru service discovery

### State transitions

```

peripheralConnected

  ↓

discoveringServices (discovering FFF0 / 180D)

  ↓

discoveringCharacteristics (discovering FFF1, FFF2 / 2A37)

  ↓

peripheralReady (services + characteristics found)

  ↓

comunicating ↔ dataIsAvailable (steady state)

```

- **MUST**: Stare monotonă crescătoare (no rollback)

- **SHOULD**: Log state transitions

- **MUST**: Fail gracefully dacă characteristics nu sunt găsite

## Communication

### Measurement requests

**UM series** (UM25C, UM34C):

```swift

// Send command to FFF2 (write characteristic)

let command = UMProtocol.buildMeasurementRequest()

peripheral.writeValue(command, for: writeCharacteristic, type: .withResponse)

// Receive on FFF1 (read characteristic)

// Parse payload (voltage, current, power, temperature, etc.)

let measurement = UMProtocol.parseMeasurement(data)

```

**TC66C**:

```swift

// Uses standard HRM (Heart Rate Measurement) characteristic

// Value format: flags byte + heart_rate_value (2 bytes)

// Repurposed for power data: MSB = watts, LSB = amps (approximation)

let measurement = TC66Protocol.parseMeasurement(data)

```

- **MUST**: Parse protocol-specific payloads

- **MUST**: Validate checksum (if applicable)

- **SHOULD**: Handle invalid/truncated payloads gracefully

- **TIMEOUT**: 3s per measurement request

### Write commands

UM series supports commands:

- Request measurement: `0x00 0xF0 0xA0 0x1B` (+ checksum)

- Set time: `0x02 ...` (timestamp)

- Set calibration: (advanced)

```swift

peripheral.writeValue(

    command,

    for: writeCharacteristic,

    type: .withResponse  // MUST: wait for ACK

)

```

- **MUST**: Use `.withResponse` pentru command-uri critice

- **MAY**: Use `.withoutResponse` pentru bulk writes

- **SHOULD**: Validate response ACK

## Disconnection handling

### Intentional disconnect

```

User taps "Disconnect"

  ↓

meter.disconnect()

  ↓

BluetoothManager calls cbCentralManager.cancelPeripheralConnection()

  ↓

didDisconnect: state → peripheralNotConnected

```

- **MUST**: Anulează pending operations

- **MUST**: Anulează auto-reconnect logic

- **MUST**: Eliberează callbacks

### Unintentional disconnect (BT drop)

```

BT device disconnects (out of range / powered off / interference)

  ↓

didDisconnect event (didDisconnect reason: optional)

  ↓

state → peripheralNotConnected

  ↓

Auto-reconnect logic starts (with backoff)

```

- **MUST**: Detecta unintentional drops (log reason dacă available)

- **SHOULD**: Incepe auto-reconnect cu backoff exponential

- **MUST**: Anulează dacă user disconnect manual (flag)

## Auto-reconnect

### Backoff strategy

```

Attempt 1: 1s delay

Attempt 2: 2s delay

Attempt 3: 4s delay

Attempt 4: 8s delay

Attempt 5: 16s delay

Attempt 6: 32s delay

Attempt 7+: 60s delay (capped)

Max attempts: 3

```

- **MUST**: Exponential backoff (2^n, capped at 60s)

- **MUST**: Max 3 consecutive retry-uri

- **MUST**: Stop retry dacă user disconnect manual

- **SHOULD**: Log fiecare retry attempt

### Trigger conditions

- **MUST**: Activate automatic reconnect doar dacă user conectase anterior

- **MUST**: Disable dacă user disconnect manual

- **MUST**: Disable dacă app goes background > 10 min

- **SHOULD**: Resume reconnect dacă app returns foreground

## Testing

### Unit tests

```swift

test_scanFiltersByServiceUUIDs()

test_deviceIdentification_UM25C()

test_deviceIdentification_UM34C()

test_deviceIdentification_TC66C()

test_connectionStateTransitions()

test_serviceDiscovery_UM25C()

test_characteristicDiscovery_UM25C()

test_measurementParsing_ValidPayload()

test_measurementParsing_InvalidPayload()

test_disconnectCleansUp()

test_unintentionalDropDetected()

test_autoReconnectBackoff_Exponential()

test_autoReconnectStops_OnManualDisconnect()

```

### Integration tests

- [ ] Scan detects available meters

- [ ] Device type identified correctly

- [ ] Connect → service discover → ready (full flow)

- [ ] Measurement received and parsed

- [ ] Unintentional drop detected + reconnect

- [ ] Auto-reconnect respects backoff timing

- [ ] Manual disconnect stops auto-reconnect

## Error handling

### Scan errors

```

Error: CBError.unknown

Error: CBError.managerStatePoweredOff

Error: CBError.invalidParameters

```

Handling:

- Retry scan periodically

- Notify UI: "Bluetooth unavailable"

### Connection errors

```

Error: peripheral not found

→ Retry with backoff

Error: timeout (no services found)

→ Disconnect + retry

Error: security/pairing required

→ Notify user: "Pair device in Settings"

```

### Communication errors

```

Error: write failed

→ Retry measurement request

Error: invalid payload

→ Log error, skip measurement

Error: characteristic not found

→ Disconnect + mark incompatible

```

## Dependencies

- `CoreBluetooth`: CBCentralManager, CBPeripheral

- `UMProtocol`: payload parsing for UM series

- `TC66Protocol`: payload parsing for TC66C

- `MeterCapabilities`: device type detection

- `AppData`: orchestration

## References

- [UMProtocol.swift](../../USB%20Meter/Model/UMProtocol.swift)

- [TC66Protocol.swift](../../USB%20Meter/Model/TC66Protocol.swift)

- [BluetoothManager.swift](../../USB%20Meter/Model/BluetoothManager.swift)

- [External documentation](https://sigrok.org/wiki/RDTech_UM_series)

- [TC66C reverse-engineering notes](../Research%20Resources/Payload%20Notes/TC66C%20Transport%20and%20Payload%20Working%20Note.md)