an0n.eu/meshcore-gui1
1
0
Fork 0
forked from iarv/meshcore-gui
Code Pull Requests Activity

Remove obsolete capture tool sections from BLE explanation docs

Browse Source 
The ble_observe.py capture tool has been removed from the project.
Updated both NL and EN versions of the BLE explanation document:
- Rewrote intro (section 1) to focus on BLE concepts rather than captures
- Removed sections 8 (workflow), 9 (common mistakes), 10 (sequence diagram)
- Updated conclusion to remove capture references
- Renumbered remaining sections (conclusion → 8, references → 9)
This commit is contained in:
pe1hvh
2026-02-03 14:39:40 +01:00
parent 379388e71d
commit 8c106fb7de
2 changed files with 19 additions and 219 deletions
Download Patch File Download Diff File Expand all files Collapse all files

118
docs/ble_capture_workflow_t_1000_e_explanation.md
View File

@@ -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/)

120
docs/ble_capture_workflow_t_1000_e_uitleg.md
View File

@@ -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/)