phase4-ble

Prompt file imported from ramonsss/MQTT_Projeto_Vena (.github/prompts/phase4-ble.prompt.md). Copyright stays with the author.

Fase 4 — BLE: Comunicação Local e Provisioning

Objetivo: Adicionar BLE GATT ao firmware ESP32 (NimBLE) e ao app Flutter (flutter_reactive_ble) para monitoramento local sem internet, provisioning Wi-Fi e pareamento. A tela de detalhe passa a exibir dados de BLE e MQTT simultaneamente, unificados no SQLite, com badge indicando a fonte.

Pré-requisito: Fase 3 concluída (app Flutter com login Google, listagem de devices, MQTT live, histórico REST, testes T1–T10 passando, Google Sign-In funcional com google-services.json).

Decisões técnicas (resolver ANTES de codificar)

Contratos

BLE GATT Service — Vena Service

Backend REST (novos ou alterados)

Checklist de implementação

A. Firmware — NimBLE GATT

B. Firmware — Provisioning Wi-Fi via BLE

C. Flutter — Package & Permissões

D. Flutter — Core BLE Service

E. Flutter — Feature Pairing (refactor do wizard existente)

F. Flutter — Device Detail (BLE + MQTT merge)

G. Backend — Provisioning endpoint

Firmware — Estrutura do BleManager

// BleManager.h (simplificado)
#pragma once
#include <NimBLEDevice.h>
#include <functional>

struct WifiCredentials {
    String ssid;
    String psk;
    String jwt;
};

using ProvisionCallback = std::function<void(const WifiCredentials&)>;

class BleManager {
public:
    void init(const char* deviceName, const char* deviceId, const char* pairingCode);
    void startAdvertising();
    void stopAdvertising();
    bool isConnected();
    void notifyTelemetry(const char* jsonPayload);
    void updateWifiStatus(bool connected, const char* ssid, const char* ip, int rssi);
    void setProvisionCallback(ProvisionCallback cb);

private:
    NimBLEServer* _server = nullptr;
    NimBLECharacteristic* _telemetryChar = nullptr;
    NimBLECharacteristic* _wifiStatusChar = nullptr;
    NimBLECharacteristic* _provisionChar = nullptr;
    NimBLECharacteristic* _deviceInfoChar = nullptr;
    NimBLECharacteristic* _pairingCodeChar = nullptr;
    ProvisionCallback _provisionCb = nullptr;
    bool _connected = false;
};

Flutter — State Machine BLE

┌───────────────────────────────────────────────────────────────────┐
│                    BLE Connection State Machine                     │
│                                                                   │
│  ┌──────┐   scan()   ┌──────────┐  found   ┌────────────┐       │
│  │ idle │ ──────────▶ │ scanning │ ────────▶ │ discovered │       │
│  └──────┘             └──────────┘           └─────┬──────┘       │
│      ▲                     │ timeout                │ connect()    │
│      │                     ▼                        ▼              │
│      │              ┌───────────┐            ┌────────────┐       │
│      │              │  timeout  │            │ connecting │       │
│      │              │  (retry?) │            └─────┬──────┘       │
│      │              └───────────┘                  │ success      │
│      │                                             ▼              │
│      │                                      ┌────────────┐       │
│      │ disconnect()                         │  connected  │       │
│      │◀─────────────────────────────────────│ (bonded)    │       │
│      │                                      └─────┬──────┘       │
│      │                                             │ subscribe    │
│      │              ┌───────────┐                  ▼              │
│      │◀─── error ──│   error    │◀─────── ┌────────────┐        │
│      │              │ (backoff) │          │ streaming  │        │
│      │              └───────────┘          │ (notify)   │        │
│      │                                     └────────────┘        │
│      │                                             │              │
│      │◀────── disconnect / leave screen ───────────┘              │
└───────────────────────────────────────────────────────────────────┘

Fluxo de Provisioning — Diagrama

┌───────┐        ┌───────────┐        ┌────────┐        ┌─────────┐
│  App  │        │ ESP32 BLE │        │Backend │        │ Broker  │
└───┬───┘        └─────┬─────┘        └───┬────┘        └────┬────┘
    │                   │                  │                   │
    │ 1. Scan QR        │                  │                   │
    │ (device_id +      │                  │                   │
    │  pairing_code)    │                  │                   │
    │                   │                  │                   │
    │ 2. BLE scan       │                  │                   │
    │──────────────────▶│ (advertising)    │                   │
    │ 3. Connect        │                  │                   │
    │──────────────────▶│                  │                   │
    │ 4. Bond (Just Works)                 │                   │
    │◀─────────────────▶│                  │                   │
    │                   │                  │                   │
    │ 5. Read device_info                  │                   │
    │──────────────────▶│                  │                   │
    │◀──────────────────│ {device_id, fw}  │                   │
    │                   │                  │                   │
    │ 6. POST /devices/provision           │                   │
    │  {device_id, pairing_code}           │                   │
    │─────────────────────────────────────▶│                   │
    │◀─────────────────────────────────────│                   │
    │ 7. Recebe device_jwt                 │                   │
    │                   │                  │                   │
    │ 8. Write wifi_provisioning           │                   │
    │  {ssid, psk, jwt} │                  │                   │
    │──────────────────▶│                  │                   │
    │                   │ 9. Salva NVS     │                   │
    │                   │ 10. Connect WiFi │                   │
    │                   │─────────────────────────────────────▶│
    │                   │ 11. MQTT connect(device_jwt)          │
    │                   │─────────────────────────────────────▶│
    │                   │                  │                   │
    │ 12. Read wifi_status (poll)          │                   │
    │──────────────────▶│                  │                   │
    │◀──────────────────│ {connected:true} │                   │
    │                   │                  │                   │
    │ 13. POST /devices/{id}/claim         │                   │
    │─────────────────────────────────────▶│                   │
    │◀─────────────────────────────────────│ 200 OK            │
    │                   │                  │                   │
    │ 14. Disconnect BLE │                 │                   │
    │──────────────────▶│                  │                   │
    │                   │                  │                   │
    │ 15. Navigate → /devices              │                   │

Merge BLE + MQTT — Diagrama

┌────────────────────────────────────────────────────────────┐
│  Device Detail Screen                                       │
│                                                            │
│  ┌──────────────┐     ┌──────────────────┐                │
│  │ BLE Service  │     │  MQTT Service    │                │
│  │ (2s notify)  │     │  (5s publish)    │                │
│  └──────┬───────┘     └────────┬─────────┘                │
│         │                      │                           │
│         ▼                      ▼                           │
│  ┌─────────────┐       ┌─────────────┐                    │
│  │ BLE Handler │       │ MQTT Handler│                    │
│  │ source='ble'│       │ source='mqtt'│                   │
│  └──────┬──────┘       └──────┬──────┘                    │
│         │                      │                           │
│         └──────────┬───────────┘                           │
│                    ▼                                        │
│         ┌──────────────────┐                               │
│         │  Drift SQLite    │                               │
│         │  latest_states   │  UPSERT WHERE new.ts > old.ts │
│         │  telemetry_cache │                               │
│         └────────┬─────────┘                               │
│                  │ Stream                                   │
│                  ▼                                          │
│         ┌──────────────────┐                               │
│         │ latestState      │                               │
│         │ Provider         │                               │
│         │ (Riverpod)       │                               │
│         └────────┬─────────┘                               │
│                  ▼                                          │
│         ┌──────────────────┐                               │
│         │       UI         │                               │
│         │ Temp + Badge     │                               │
│         │ [BLE] ou [MQTT]  │                               │
│         └──────────────────┘                               │
└────────────────────────────────────────────────────────────┘

Testes

Critérios de aceite (DoD)

Armadilhas conhecidas

Ordem de execução recomendada

 1. [Firmware]    A1-A2: Adicionar NimBLE ao platformio.ini + config.h (UUIDs, defines)
 2. [Firmware]    A3-A5: Criar BleManager (init, advertising, GATT service, characteristics)
 3. [Firmware]    A6-A7: Integrar BleManager no main.cpp + callbacks
 4. [Firmware]    B1-B3: WifiProvisioner (NVS save/load) + lógica condicional no boot
 5. [Validate]    Testar com nRF Connect: advertising visível, read device_info, notify telemetry
 6. [Flutter]     C1-C3: Adicionar packages + permissões Android/iOS
 7. [Flutter]     D1-D3: BleService + UUIDs + models
 8. [Flutter]     D4-D6: Providers BLE + message handler + permission handler
 9. [Flutter]     F1-F2: BLE live provider + merge no latestStateProvider
10. [Flutter]     F3-F5: UI badge BLE/MQTT + lifecycle
11. [Flutter]     E1-E6: Wizard pairing refactor (QR → BLE scan → provision → claim)
12. [Backend]     G1-G3: Endpoint POST /devices/provision + device JWT
13. [Tests]       T1-T7: Unit tests core BLE
14. [Tests]       T8-T11: Widget tests + integration test merge
15. [Tests]       T12: Firmware unit test BleManager
16. [E2E]         Smoke test: provisioning completo + live BLE + merge com MQTT

Métricas de sucesso (smoke test final)

1. Advertising: ESP32 liga, aparece como Vena-XXXX no nRF Connect e no app.
2. Provisioning completo: ESP32 sem Wi-Fi → app faz scan QR → conecta BLE → provisiona → ESP32 fica online (MQTT ativo).
3. BLE live: tela de detalhe mostra temperatura atualizando a cada ~2s com badge "BLE" enquanto perto do device.
4. MQTT fallback: afastar-se do device (BLE desconecta) → badge muda para "MQTT" → dados continuam chegando via broker.
5. Merge correto: aproximar novamente → badge volta para "BLE"; dado mais recente (por ts) sempre prevalece.
6. Pairing novo device: QR de device virgem → provisioning Wi-Fi → claim → aparece na lista.
7. Reconexão: desligar/religar ESP32 → app reconecta BLE em <30s sem intervenção.
8. RAM estável: ESP.getFreeHeap() reportado em serial > 50KB após 10min de operação (BLE + Wi-Fi + MQTT).
9. Permissões: negar Bluetooth → app mostra dialog explicativo com botão para Settings; conceder → scan funciona.

Dependências novas

Flutter (pubspec.yaml)

dependencies:
  flutter_reactive_ble: ^5.3.1
  permission_handler: ^11.3.1

Firmware (platformio.ini)

lib_deps =
    ...existing...
    h2zero/NimBLE-Arduino@^2.1.0

Backend (sem novas deps — apenas novos endpoints)

Escopo explicitamente FORA desta fase

• OTA via BLE — complexidade alta, pouco valor no MVP. Firmware update manual por USB.
• Múltiplas conexões BLE simultâneas — uma por vez é suficiente para UX de produtor.
• BLE Mesh — desnecessário; cada Vena opera independentemente.
• Notificações push baseadas em BLE proximity — fase posterior (FCM + geofencing).
• Criptografia customizada no payload BLE — bonding/encryption nativo do BLE 4.2+ é suficiente.
• BLE em background contínuo no app — bateria proibitiva. MQTT cobre dados remotos; BLE é para interação ativa.