diff --git a/docs/ble_capture_workflow_t_1000_e_explanation.md b/docs/ble_capture_workflow_t_1000_e_explanation.md index 12566ff..5172531 100644 --- a/docs/ble_capture_workflow_t_1000_e_explanation.md +++ b/docs/ble_capture_workflow_t_1000_e_explanation.md @@ -13,15 +13,15 @@ ## 1. What is this document about? -The original document describes how to "listen in" on the BLE communication of a **MeshCore T1000-e** radio from a Linux computer. It explains: +This document explains the BLE concepts and terminology behind communicating with a **MeshCore T1000-e** radio from a Linux computer. It covers: -- What steps are needed to set up a connection -- Why it often goes wrong (and how to prevent that) -- How to save raw protocol data for analysis +- How BLE connections work and how they differ from Classic Bluetooth +- The GATT service model and the Nordic UART Service (NUS) used by MeshCore +- Why BLE session ownership matters and how it can cause connection failures **The key message in one sentence:** -> Only **one listener at a time** can be connected to the T1000-e. If something else is already connected, your capture will fail. +> Only **one BLE client at a time** can be connected to the T1000-e. If something else is already connected, your connection will fail. --- @@ -609,119 +609,19 @@ The document places the problem in a **layer model**. This helps understand *whe --- -## 8. The workflow summarised +## 8. Conclusion -### 8.1 One-time preparation - -```bash -# Start bluetoothctl -bluetoothctl - -# Activate Bluetooth -power on -agent on -default-agent -scan on - -# Wait until device is visible, then pair -pair AA:BB:CC:DD:EE:FF -# Enter PIN code (e.g. 123456) - -# Trust the device -trust AA:BB:CC:DD:EE:FF -quit -``` - -### 8.2 Before each capture - -1. **Phone Bluetooth OFF** -2. **Close GNOME Bluetooth GUI** -3. **Explicitly disconnect:** - -```bash -bluetoothctl disconnect AA:BB:CC:DD:EE:FF -``` - -4. **Verify that nothing is connected:** - -```bash -bluetoothctl info AA:BB:CC:DD:EE:FF | egrep -i "Connected" -# Expected: Connected: no -``` - -### 8.3 Starting a capture - -```bash -python tools/ble_observe.py \ - --address AA:BB:CC:DD:EE:FF \ - --pre-scan-seconds 10 \ - --connect-timeout 30 \ - --notify \ - --notify-seconds 30 \ - --notify-start-timeout 30 \ - --disconnect-timeout 15 \ - --capture captures/session_$(date -u +%Y-%m-%d_%H%M%S).raw -``` - ---- - -## 9. Common mistakes - -| Mistake | Consequence | Solution | -|---------|------------|----------| -| GNOME Bluetooth Manager open | `Notify acquired` | Close the GUI | -| Ran `bluetoothctl connect` | Tool fails at notify | Always `disconnect` first | -| Phone Bluetooth on | Phone claims the connection | Turn off phone BT | -| Multiple scripts at once | First one wins, rest fail | One tool at a time | - ---- - -## 10. Visual overview (sequence diagram) - -``` -┌──────┐ ┌───────┐ ┌───────┐ ┌───────┐ -│ User │ │ Linux │ │ BlueZ │ │ Radio │ -└──┬───┘ └───┬───┘ └───┬───┘ └───┬───┘ - │ │ │ │ - │ pair/trust │ │ │ - │────────────>│────────────────────────-->│ (one-time) - │ │ │ │ - │ │ No active connection │ - │ │ │ │ - │ start tool │ │ │ - │────────────>│ │ │ - │ │ connect() │ │ - │ │────────────>│────────────>│ - │ │ │ │ - │ │start_notify │ │ - │ │────────────>│────────────>│ - │ │ │ │ - │ │ notify (data frames) │ - │ │<────────────│<────────────│ - │ │ │ │ - │ │ stop_notify │ │ - │ │────────────>│────────────>│ - │ │ │ │ - │ │ disconnect │ │ - │ │────────────>│────────────>│ - │ │ │ │ -``` - ---- - -## 11. Conclusion - -The document demonstrates that: +The key takeaways from this document: - ✅ MeshCore BLE companion **works correctly** on Linux - ✅ The firmware **does not block notify** - ✅ The only requirement is: **exactly one active BLE client per radio** -When you follow this workflow, captures are reproducible and further protocol analysis becomes possible. +Understanding the ownership model and BLE fundamentals described here is essential for working with any BLE-connected MeshCore device. --- -## 12. References +## 9. References - MeshCore Companion Radio Protocol: [GitHub Wiki](https://github.com/meshcore-dev/MeshCore/wiki/Companion-Radio-Protocol) - Bluetooth SIG Assigned Numbers (official services): [bluetooth.com/specifications/assigned-numbers](https://www.bluetooth.com/specifications/assigned-numbers/) diff --git a/docs/ble_capture_workflow_t_1000_e_uitleg.md b/docs/ble_capture_workflow_t_1000_e_uitleg.md index 165632b..001c0bb 100644 --- a/docs/ble_capture_workflow_t_1000_e_uitleg.md +++ b/docs/ble_capture_workflow_t_1000_e_uitleg.md @@ -13,15 +13,15 @@ ## 1. Waar gaat dit document over? -Het originele document beschrijft hoe je op een Linux-computer kunt "meeluisteren" naar de BLE-communicatie van een **MeshCore T1000-e** radio. Het legt uit: +Dit document legt de BLE-concepten en terminologie uit achter de communicatie met een **MeshCore T1000-e** radio vanaf een Linux-computer. Het behandelt: -- Welke stappen nodig zijn om een verbinding op te zetten -- Waarom het vaak misgaat (en hoe je dat voorkomt) -- Hoe je ruwe protocol-data kunt opslaan voor analyse +- Hoe BLE-verbindingen werken en hoe ze verschillen van Classic Bluetooth +- Het GATT-servicemodel en de Nordic UART Service (NUS) die MeshCore gebruikt +- Waarom BLE-sessie-ownership belangrijk is en hoe het verbindingsproblemen kan veroorzaken **De kernboodschap in één zin:** -> Er mag maar **één luisteraar tegelijk** verbonden zijn met de T1000-e. Als iets anders al verbonden is, faalt jouw capture. +> Er mag maar **één BLE-client tegelijk** verbonden zijn met de T1000-e. Als iets anders al verbonden is, faalt jouw verbinding. --- @@ -609,119 +609,19 @@ Het document plaatst het probleem in een **lagenmodel**. Dit helpt begrijpen *wa --- -## 8. De workflow samengevat +## 8. Conclusie -### 8.1 Eenmalige voorbereiding - -```bash -# Start bluetoothctl -bluetoothctl - -# Activeer Bluetooth -power on -agent on -default-agent -scan on - -# Wacht tot device zichtbaar is, dan pairen -pair literal:AA:BB:CC:DD:EE:FF -# Voer pincode in (bijv. 123456) - -# Vertrouw het apparaat -trust literal:AA:BB:CC:DD:EE:FF -quit -``` - -### 8.2 Vóór elke capture - -1. **Telefoon Bluetooth UIT** -2. **GNOME Bluetooth GUI SLUITEN** -3. **Expliciet disconnecten:** - -```bash -bluetoothctl disconnect literal:AA:BB:CC:DD:EE:FF -``` - -4. **Controleer dat niemand verbonden is:** - -```bash -bluetoothctl info literal:AA:BB:CC:DD:EE:FF | egrep -i "Connected" -# Verwacht: Connected: no -``` - -### 8.3 Capture starten - -```bash -python tools/ble_observe.py \ - --address literal:AA:BB:CC:DD:EE:FF \ - --pre-scan-seconds 10 \ - --connect-timeout 30 \ - --notify \ - --notify-seconds 30 \ - --notify-start-timeout 30 \ - --disconnect-timeout 15 \ - --capture captures/session_$(date -u +%Y-%m-%d_%H%M%S).raw -``` - ---- - -## 9. Veelgemaakte fouten - -| Fout | Gevolg | Oplossing | -|------|--------|-----------| -| GNOME Bluetooth Manager open | `Notify acquired` | GUI sluiten | -| `bluetoothctl connect` gedaan | Tool faalt bij notify | Altijd `disconnect` eerst | -| Telefoon Bluetooth aan | Telefoon claimt verbinding | Telefoon BT uit | -| Meerdere scripts tegelijk | Eerste wint, rest faalt | Één tool tegelijk | - ---- - -## 10. Visueel overzicht (sequentiediagram) - -``` -┌──────┐ ┌───────┐ ┌───────┐ ┌───────┐ -│ User │ │ Linux │ │ BlueZ │ │ Radio │ -└──┬───┘ └───┬───┘ └───┬───┘ └───┬───┘ - │ │ │ │ - │ pair/trust │ │ │ - │────────────>│────────────────────────-->│ (eenmalig) - │ │ │ │ - │ │ Geen actieve verbinding│ - │ │ │ │ - │ start tool │ │ │ - │────────────>│ │ │ - │ │ connect() │ │ - │ │────────────>│────────────>│ - │ │ │ │ - │ │start_notify │ │ - │ │────────────>│────────────>│ - │ │ │ │ - │ │ notify (data frames) │ - │ │<────────────│<────────────│ - │ │ │ │ - │ │ stop_notify │ │ - │ │────────────>│────────────>│ - │ │ │ │ - │ │ disconnect │ │ - │ │────────────>│────────────>│ - │ │ │ │ -``` - ---- - -## 11. Conclusie - -Het document bewijst dat: +De belangrijkste inzichten uit dit document: - ✅ MeshCore BLE companion **werkt correct** op Linux - ✅ De firmware **blokkeert notify niet** -- ✅ Het enige vereiste is: **exact één actieve BLE client per radio** +- ✅ Het enige vereiste is: **exact één actieve BLE-client per radio** -Wanneer je deze workflow volgt, zijn captures reproduceerbaar en is verdere protocol-analyse mogelijk. +Het begrijpen van het ownership-model en de BLE-fundamenten uit dit document is essentieel voor het werken met elk BLE-verbonden MeshCore-apparaat. --- -## 12. Referenties +## 9. Referenties - MeshCore Companion Radio Protocol: [GitHub Wiki](https://github.com/meshcore-dev/MeshCore/wiki/Companion-Radio-Protocol) - Bluetooth SIG Assigned Numbers (officiële services): [bluetooth.com/specifications/assigned-numbers](https://www.bluetooth.com/specifications/assigned-numbers/)