Initial commit
This commit is contained in:
pe1hvh
2
.gitattributes
vendored
Normal file
2
.gitattributes
vendored
Normal file
@@ -0,0 +1,2 @@
|
|||||||
|
# Auto detect text files and perform LF normalization
|
||||||
|
* text=auto
|
||||||
9
.gitignore
vendored
Normal file
9
.gitignore
vendored
Normal file
@@ -0,0 +1,9 @@
|
|||||||
|
.venv/
|
||||||
|
venv/
|
||||||
|
__pycache__/
|
||||||
|
*.pyc
|
||||||
|
logs/*.log
|
||||||
|
logs/*.txt
|
||||||
|
.DS_Store
|
||||||
|
.idea/
|
||||||
|
.vscode/
|
||||||
21
LICENSE
Normal file
21
LICENSE
Normal file
@@ -0,0 +1,21 @@
|
|||||||
|
MIT License
|
||||||
|
|
||||||
|
Copyright (c) 2025 PE1HVH
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
341
README.md
Normal file
341
README.md
Normal file
@@ -0,0 +1,341 @@
|
|||||||
|
# MeshCore GUI
|
||||||
|
|
||||||
|
A graphical user interface for MeshCore mesh network devices via Bluetooth Low Energy (BLE).
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Why This Project Exists
|
||||||
|
|
||||||
|
MeshCore devices like the SenseCAP T1000-E can be managed through two interfaces: USB serial and BLE (Bluetooth Low Energy). The official companion apps communicate with devices over BLE, but they are mobile-only. If you want to manage your MeshCore device from a desktop or laptop, the usual approach is to **flash USB-serial firmware** via the web flasher. However, this replaces the BLE Companion firmware, which means you can no longer use the device with mobile companion apps (Android/iOS).
|
||||||
|
|
||||||
|
This project provides a **native desktop GUI** that connects to your MeshCore device over BLE — no firmware changes required. Your device stays on BLE Companion firmware and remains fully compatible with the mobile apps. The application is written in Python using cross-platform libraries and runs on **Linux, macOS and Windows**.
|
||||||
|
|
||||||
|
> **Note:** This application has only been tested on Linux (Ubuntu 24.04). macOS and Windows should work since all dependencies (`bleak`, `nicegui`, `meshcore`) are cross-platform, but this has not been verified. Feedback and contributions for other platforms are welcome.
|
||||||
|
|
||||||
|
Under the hood it uses `bleak` for Bluetooth Low Energy (which talks to BlueZ on Linux, CoreBluetooth on macOS, and WinRT on Windows), `meshcore` as the protocol layer, and `NiceGUI` for the web-based interface.
|
||||||
|
|
||||||
|
> **Linux users:** BLE on Linux can be temperamental. BlueZ occasionally gets into a bad state, especially after repeated connect/disconnect cycles. If you run into connection issues, see the [Troubleshooting Guide](docs/TROUBLESHOOTING.md). On macOS and Windows, BLE is generally more stable out of the box.
|
||||||
|
|
||||||
|
## TODO
|
||||||
|
|
||||||
|
- **Message route visualization** — Display message paths on the map showing the route (hops) each message has taken through the mesh network
|
||||||
|
- **Message persistence** — Store sent and received messages to disk so chat history is preserved across sessions
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- **Real-time Dashboard** - Device info, contacts, messages and RX log
|
||||||
|
- **Interactive Map** - Leaflet map with markers for own position and contacts
|
||||||
|
- **Channel Messages** - Send and receive messages on channels
|
||||||
|
- **Direct Messages** - Click on a contact to send a DM
|
||||||
|
- **Message Filtering** - Filter messages per channel via checkboxes
|
||||||
|
- **Threaded Architecture** - BLE communication in separate thread for stable UI
|
||||||
|
|
||||||
|
## Screenshot
|
||||||
|
|
||||||
|
<img width="1002" height="532" alt="Screenshot from 2026-02-03 10-23-25" src="https://github.com/user-attachments/assets/7bc56b94-407c-4e20-aa30-8b2e0f03f820" />
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Python 3.10+
|
||||||
|
- Bluetooth Low Energy compatible adapter (built-in or USB)
|
||||||
|
- MeshCore device with BLE Companion firmware
|
||||||
|
|
||||||
|
### Platform support
|
||||||
|
|
||||||
|
| Platform | BLE Backend | Status |
|
||||||
|
|---|---|---|
|
||||||
|
| Linux (Ubuntu/Debian) | BlueZ/D-Bus | ✅ Tested |
|
||||||
|
| macOS | CoreBluetooth | ⬜ Untested |
|
||||||
|
| Windows 10/11 | WinRT | ⬜ Untested |
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
### 1. System dependencies
|
||||||
|
|
||||||
|
**Linux (Ubuntu/Debian):**
|
||||||
|
```bash
|
||||||
|
sudo apt update
|
||||||
|
sudo apt install python3-pip python3-venv bluetooth bluez
|
||||||
|
```
|
||||||
|
|
||||||
|
**macOS:**
|
||||||
|
```bash
|
||||||
|
# Python 3.10+ via Homebrew (if not already installed)
|
||||||
|
brew install python
|
||||||
|
```
|
||||||
|
No additional Bluetooth packages needed — macOS has CoreBluetooth built in.
|
||||||
|
|
||||||
|
**Windows:**
|
||||||
|
- Install [Python 3.10+](https://www.python.org/downloads/) (check "Add to PATH" during installation)
|
||||||
|
- No additional Bluetooth packages needed — Windows 10/11 has WinRT built in.
|
||||||
|
|
||||||
|
### 2. Clone the repository
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/pe1hvh/meshcore-gui.git
|
||||||
|
cd meshcore-gui
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Create virtual environment
|
||||||
|
|
||||||
|
**Linux / macOS:**
|
||||||
|
```bash
|
||||||
|
python3 -m venv venv
|
||||||
|
source venv/bin/activate
|
||||||
|
```
|
||||||
|
|
||||||
|
**Windows:**
|
||||||
|
```cmd
|
||||||
|
python -m venv venv
|
||||||
|
venv\Scripts\activate
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Install Python packages
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install nicegui meshcore bleak
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
### 1. Activate the virtual environment
|
||||||
|
|
||||||
|
**Linux / macOS:**
|
||||||
|
```bash
|
||||||
|
cd meshcore-gui
|
||||||
|
source venv/bin/activate
|
||||||
|
```
|
||||||
|
|
||||||
|
**Windows:**
|
||||||
|
```cmd
|
||||||
|
cd meshcore-gui
|
||||||
|
venv\Scripts\activate
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Find your BLE device address
|
||||||
|
|
||||||
|
**Linux:**
|
||||||
|
```bash
|
||||||
|
bluetoothctl scan on
|
||||||
|
```
|
||||||
|
Look for your MeshCore device and note the MAC address (e.g., `literal:AA:BB:CC:DD:EE:FF`).
|
||||||
|
|
||||||
|
**macOS / Windows:**
|
||||||
|
```bash
|
||||||
|
python -c "
|
||||||
|
import asyncio
|
||||||
|
from bleak import BleakScanner
|
||||||
|
async def scan():
|
||||||
|
devices = await BleakScanner.discover(5.0)
|
||||||
|
for d in devices:
|
||||||
|
if 'MeshCore' in (d.name or ''):
|
||||||
|
print(f'{d.address} {d.name}')
|
||||||
|
asyncio.run(scan())
|
||||||
|
"
|
||||||
|
```
|
||||||
|
On macOS the address will be a UUID (e.g., `12345678-ABCD-...`) rather than a MAC address.
|
||||||
|
|
||||||
|
### 3. Configure channels
|
||||||
|
|
||||||
|
Open `meshcore_gui.py` and adjust `CHANNELS_CONFIG` to your own channels:
|
||||||
|
|
||||||
|
```python
|
||||||
|
CHANNELS_CONFIG = [
|
||||||
|
{'idx': 0, 'name': 'Public'},
|
||||||
|
{'idx': 1, 'name': '#test'},
|
||||||
|
{'idx': 2, 'name': 'MyChannel'},
|
||||||
|
{'idx': 3, 'name': '#local'},
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tip:** Use `meshcli` to determine your channels:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
meshcli -d literal:AA:BB:CC:DD:EE:FF
|
||||||
|
> get_channel 0
|
||||||
|
> get_channel 1
|
||||||
|
# etc.
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Start the GUI
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python meshcore_gui.py literal:AA:BB:CC:DD:EE:FF
|
||||||
|
```
|
||||||
|
|
||||||
|
Replace `literal:AA:BB:CC:DD:EE:FF` with the MAC address of your device.
|
||||||
|
|
||||||
|
### 5. Open the interface
|
||||||
|
|
||||||
|
The GUI opens automatically in your browser at `http://localhost:8080`
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
| Setting | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `DEBUG` | Set to `True` for verbose logging |
|
||||||
|
| `CHANNELS_CONFIG` | List of channels (hardcoded due to BLE timing issues) |
|
||||||
|
| BLE Address | Command line argument |
|
||||||
|
|
||||||
|
## Functionality
|
||||||
|
|
||||||
|
### Device Info
|
||||||
|
- Name, frequency, SF/BW, TX power, location, firmware version
|
||||||
|
|
||||||
|
### Contacts
|
||||||
|
- List of known nodes with type and location
|
||||||
|
- Click on a contact to send a DM
|
||||||
|
|
||||||
|
### Map
|
||||||
|
- OpenStreetMap with markers for own position and contacts
|
||||||
|
- Shows your own position (blue marker)
|
||||||
|
- Automatically centers on your own position
|
||||||
|
|
||||||
|
### Channel Messages
|
||||||
|
- Select a channel in the dropdown
|
||||||
|
- Type your message and click "Send"
|
||||||
|
- Received messages appear in the messages list
|
||||||
|
- Filter messages via the checkboxes
|
||||||
|
|
||||||
|
### Direct Messages (DM)
|
||||||
|
- Click on a contact in the contacts list
|
||||||
|
- A dialog opens where you can type your message
|
||||||
|
- Click "Send" to send the DM
|
||||||
|
|
||||||
|
### RX Log
|
||||||
|
- Received packets with SNR and type
|
||||||
|
|
||||||
|
### Actions
|
||||||
|
- Refresh data
|
||||||
|
- Send advertisement
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────┐ ┌─────────────────┐
|
||||||
|
│ Main Thread │ │ BLE Thread │
|
||||||
|
│ (NiceGUI) │ │ (asyncio) │
|
||||||
|
│ │ │ │
|
||||||
|
│ ┌───────────┐ │ │ ┌───────────┐ │
|
||||||
|
│ │ GUI │◄─┼──┬──┼─►│ BLEWorker │ │
|
||||||
|
│ └───────────┘ │ │ │ └───────────┘ │
|
||||||
|
│ │ │ │ │ │ │
|
||||||
|
│ ▼ │ │ │ ▼ │
|
||||||
|
│ ┌───────────┐ │ │ │ ┌───────────┐ │
|
||||||
|
│ │ Timer │ │ │ │ │ MeshCore │ │
|
||||||
|
│ │ (500ms) │ │ │ │ │ BLE │ │
|
||||||
|
│ └───────────┘ │ │ │ └───────────┘ │
|
||||||
|
└─────────────────┘ │ └─────────────────┘
|
||||||
|
│
|
||||||
|
┌──────┴──────┐
|
||||||
|
│ SharedData │
|
||||||
|
│ (thread- │
|
||||||
|
│ safe) │
|
||||||
|
└─────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
- **BLEWorker**: Runs in separate thread with its own asyncio loop
|
||||||
|
- **SharedData**: Thread-safe data sharing between BLE and GUI
|
||||||
|
- **MeshCoreGUI**: NiceGUI interface in main thread
|
||||||
|
- **Communication**: Via queue (GUI→BLE) and shared state with flags (BLE→GUI)
|
||||||
|
|
||||||
|
## Known Limitations
|
||||||
|
|
||||||
|
1. **Channels hardcoded** - The `get_channel()` function in meshcore-py is unreliable via BLE
|
||||||
|
2. **send_appstart() sometimes fails** - Device info may remain empty with connection problems
|
||||||
|
3. **Initial load time** - GUI waits for BLE data before the first render is complete
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Linux
|
||||||
|
|
||||||
|
For comprehensive Linux BLE troubleshooting (including the `EOFError` / `start_notify` issue), see [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).
|
||||||
|
|
||||||
|
#### Quick fixes
|
||||||
|
|
||||||
|
##### GUI remains empty / BLE connection fails
|
||||||
|
|
||||||
|
1. First disconnect any existing BLE connections:
|
||||||
|
```bash
|
||||||
|
bluetoothctl disconnect literal:AA:BB:CC:DD:EE:FF
|
||||||
|
```
|
||||||
|
2. Wait 2 seconds:
|
||||||
|
```bash
|
||||||
|
sleep 2
|
||||||
|
```
|
||||||
|
3. Restart the GUI:
|
||||||
|
```bash
|
||||||
|
python meshcore_gui.py literal:AA:BB:CC:DD:EE:FF
|
||||||
|
```
|
||||||
|
|
||||||
|
##### Bluetooth permissions
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo usermod -a -G bluetooth $USER
|
||||||
|
# Log out and back in
|
||||||
|
```
|
||||||
|
|
||||||
|
### macOS
|
||||||
|
|
||||||
|
- Make sure Bluetooth is enabled in System Settings
|
||||||
|
- Grant your terminal app Bluetooth access when prompted
|
||||||
|
- Use the UUID address from BleakScanner, not a MAC address
|
||||||
|
|
||||||
|
### Windows
|
||||||
|
|
||||||
|
- Make sure Bluetooth is enabled in Settings → Bluetooth & devices
|
||||||
|
- Run the terminal as a regular user (not as Administrator — WinRT BLE can behave unexpectedly with elevated privileges)
|
||||||
|
|
||||||
|
### All platforms
|
||||||
|
|
||||||
|
#### Device not found
|
||||||
|
|
||||||
|
Make sure the MeshCore device is powered on and in BLE Companion mode. Run the BleakScanner script from the Usage section to verify it is visible.
|
||||||
|
|
||||||
|
#### Messages not arriving
|
||||||
|
|
||||||
|
- Check if your channels are correctly configured
|
||||||
|
- Use `meshcli` to verify that messages are arriving
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
|
### Debug mode
|
||||||
|
|
||||||
|
Set `DEBUG = True` in the script for verbose logging:
|
||||||
|
|
||||||
|
```python
|
||||||
|
DEBUG = True
|
||||||
|
```
|
||||||
|
|
||||||
|
### Project structure
|
||||||
|
|
||||||
|
```
|
||||||
|
meshcore-gui/
|
||||||
|
├── meshcore_gui.py # Main application
|
||||||
|
├── README.md # This file
|
||||||
|
└── docs/
|
||||||
|
├── TROUBLESHOOTING.md # BLE troubleshooting guide (Linux)
|
||||||
|
└── MeshCore_GUI_Design.docx # Design document
|
||||||
|
```
|
||||||
|
|
||||||
|
## Disclaimer
|
||||||
|
|
||||||
|
This is an **independent community project** and is not affiliated with or endorsed by the official [MeshCore](https://github.com/meshcore-dev) development team. It is built on top of the open-source `meshcore` Python library and `bleak` BLE library.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT License - see LICENSE file
|
||||||
|
|
||||||
|
## Author
|
||||||
|
|
||||||
|
**PE1HVH** - [GitHub](https://github.com/pe1hvh)
|
||||||
|
|
||||||
|
## Acknowledgments
|
||||||
|
|
||||||
|
- [MeshCore](https://github.com/meshcore-dev) - Mesh networking firmware and protocol
|
||||||
|
- [meshcore_py](https://github.com/meshcore-dev/meshcore_py) - Python bindings for MeshCore
|
||||||
|
- [meshcore-cli](https://github.com/meshcore-dev/meshcore-cli) - Command line interface
|
||||||
|
- [NiceGUI](https://nicegui.io/) - Python GUI framework
|
||||||
|
- [Bleak](https://github.com/hbldh/bleak) - Cross-platform Bluetooth Low Energy library
|
||||||
BIN
docs/MeshCore_GUI_Design.docx
Normal file
BIN
docs/MeshCore_GUI_Design.docx
Normal file
Binary file not shown.
182
docs/TROUBLESHOOTING.md
Normal file
182
docs/TROUBLESHOOTING.md
Normal file
@@ -0,0 +1,182 @@
|
|||||||
|
# MeshCore GUI - BLE Troubleshooting Guide
|
||||||
|
|
||||||
|
## The Problem
|
||||||
|
|
||||||
|
BLE connection to MeshCore device fails with `EOFError` during `start_notify` on the UART TX characteristic. The error originates in `dbus_fast` (the D-Bus library used by `bleak`) and looks like this:
|
||||||
|
|
||||||
|
```
|
||||||
|
File "src/dbus_fast/_private/unmarshaller.py", line 395, in dbus_fast._private.unmarshaller.Unmarshaller._read_sock_with_fds
|
||||||
|
EOFError
|
||||||
|
```
|
||||||
|
|
||||||
|
Basic BLE connect works fine, but subscribing to notifications (`start_notify`) crashes.
|
||||||
|
|
||||||
|
## Diagnostic Steps
|
||||||
|
|
||||||
|
### 1. Check adapter status
|
||||||
|
|
||||||
|
```bash
|
||||||
|
hciconfig -a
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: `UP RUNNING`. If it shows `DOWN`, reset with:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo hciconfig hci0 down
|
||||||
|
sudo hciconfig hci0 up
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Check if adapter is detected
|
||||||
|
|
||||||
|
```bash
|
||||||
|
lsusb | grep -i blue
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Test basic BLE connection (without notify)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -c "
|
||||||
|
import asyncio
|
||||||
|
from bleak import BleakClient
|
||||||
|
async def test():
|
||||||
|
async with BleakClient('literal:AA:BB:CC:DD:EE:FF') as c:
|
||||||
|
print('Connected:', c.is_connected)
|
||||||
|
asyncio.run(test())
|
||||||
|
"
|
||||||
|
```
|
||||||
|
|
||||||
|
If this works but meshcli/meshcore_gui fails, the problem is specifically `start_notify`.
|
||||||
|
|
||||||
|
### 4. Test start_notify in isolation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -c "
|
||||||
|
import asyncio
|
||||||
|
from bleak import BleakClient
|
||||||
|
UART_TX = '6e400003-b5a3-f393-e0a9-e50e24dcca9e'
|
||||||
|
async def test():
|
||||||
|
async with BleakClient('literal:AA:BB:CC:DD:EE:FF') as c:
|
||||||
|
def cb(s, d): print(f'RX: {d.hex()}')
|
||||||
|
await c.start_notify(UART_TX, cb)
|
||||||
|
print('Notify OK!')
|
||||||
|
await asyncio.sleep(2)
|
||||||
|
asyncio.run(test())
|
||||||
|
"
|
||||||
|
```
|
||||||
|
|
||||||
|
If this also fails with `EOFError`, the issue is confirmed at the BlueZ/D-Bus level.
|
||||||
|
|
||||||
|
### 5. Test notifications via bluetoothctl (outside Python)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bluetoothctl
|
||||||
|
scan on
|
||||||
|
# Wait for device to appear
|
||||||
|
connect literal:AA:BB:CC:DD:EE:FF
|
||||||
|
# Wait for "Connection successful"
|
||||||
|
menu gatt
|
||||||
|
select-attribute 6e400003-b5a3-f393-e0a9-e50e24dcca9e
|
||||||
|
notify on
|
||||||
|
```
|
||||||
|
|
||||||
|
If `connect` fails with `le-connection-abort-by-local`, the problem is at the BlueZ or device level. No Python fix will help.
|
||||||
|
|
||||||
|
## The Solution
|
||||||
|
|
||||||
|
In our case, the root cause was a stale BLE pairing state between the Linux adapter and the T1000-e device. The fix requires a clean reconnect sequence:
|
||||||
|
|
||||||
|
### Step 1 - Remove the device from BlueZ
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bluetoothctl
|
||||||
|
remove literal:AA:BB:CC:DD:EE:FF
|
||||||
|
exit
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2 - Hard power cycle the MeshCore device
|
||||||
|
|
||||||
|
Physically power off the T1000-e (not just a software reset). Wait 10 seconds, then power it back on.
|
||||||
|
|
||||||
|
### Step 3 - Scan and reconnect from scratch
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bluetoothctl
|
||||||
|
scan on
|
||||||
|
```
|
||||||
|
|
||||||
|
Wait until the device appears: `[NEW] Device literal:AA:BB:CC:DD:EE:FF MeshCore-PE1HVH T1000e`
|
||||||
|
|
||||||
|
Then immediately connect:
|
||||||
|
|
||||||
|
```
|
||||||
|
connect literal:AA:BB:CC:DD:EE:FF
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4 - Verify notifications work
|
||||||
|
|
||||||
|
```
|
||||||
|
menu gatt
|
||||||
|
select-attribute 6e400003-b5a3-f393-e0a9-e50e24dcca9e
|
||||||
|
notify on
|
||||||
|
```
|
||||||
|
|
||||||
|
If this succeeds, disconnect cleanly:
|
||||||
|
|
||||||
|
```
|
||||||
|
notify off
|
||||||
|
back
|
||||||
|
disconnect literal:AA:BB:CC:DD:EE:FF
|
||||||
|
exit
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 5 - Verify channels with meshcli
|
||||||
|
|
||||||
|
```bash
|
||||||
|
meshcli -d literal:AA:BB:CC:DD:EE:FF
|
||||||
|
> get_channels
|
||||||
|
```
|
||||||
|
|
||||||
|
Confirm output matches `CHANNELS_CONFIG` in `meshcore_gui.py`, then:
|
||||||
|
|
||||||
|
```
|
||||||
|
> exit
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 6 - Start the GUI
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd ~/Documents/Share/Web/meshcore-linux
|
||||||
|
source venv/bin/activate
|
||||||
|
python meshcore_gui.py literal:AA:BB:CC:DD:EE:FF
|
||||||
|
```
|
||||||
|
|
||||||
|
## Things That Did NOT Help
|
||||||
|
|
||||||
|
| Action | Result |
|
||||||
|
|---|---|
|
||||||
|
| `sudo systemctl restart bluetooth` | No effect |
|
||||||
|
| `sudo hciconfig hci0 down/up` | No effect |
|
||||||
|
| `sudo rmmod btusb && sudo modprobe btusb` | No effect |
|
||||||
|
| `sudo usbreset "8087:0026"` | No effect |
|
||||||
|
| `sudo reboot` | No effect |
|
||||||
|
| Clearing BlueZ cache (`/var/lib/bluetooth/*/cache`) | No effect |
|
||||||
|
| Recreating Python venv | No effect |
|
||||||
|
| Downgrading `dbus_fast` / `bleak` | No effect |
|
||||||
|
| Downgrading `linux-firmware` | No effect |
|
||||||
|
|
||||||
|
## Key Takeaway
|
||||||
|
|
||||||
|
When `start_notify` fails with `EOFError` but basic BLE connect works, the issue is almost always a stale BLE state between the host adapter and the peripheral device. The fix is:
|
||||||
|
|
||||||
|
1. **Remove** the device from bluetoothctl
|
||||||
|
2. **Hard power cycle** the peripheral device
|
||||||
|
3. **Re-scan** and reconnect from scratch
|
||||||
|
|
||||||
|
## Recommended Startup Sequence
|
||||||
|
|
||||||
|
For the most reliable BLE connection, always follow this order:
|
||||||
|
|
||||||
|
1. Ensure no other application holds the BLE connection (BT manager, bluetoothctl, meshcli)
|
||||||
|
2. Verify the device is visible: `bluetoothctl scan on`
|
||||||
|
3. Check channels: `meshcli -d <BLE_ADDRESS>` → `get_channels` → `exit`
|
||||||
|
4. Start the GUI: `python meshcore_gui.py <BLE_ADDRESS>`
|
||||||
737
docs/ble_capture_workflow_t_1000_e_uitleg.md
Normal file
737
docs/ble_capture_workflow_t_1000_e_uitleg.md
Normal file
@@ -0,0 +1,737 @@
|
|||||||
|
# BLE Capture Workflow T1000-e — Uitleg & Achtergrond
|
||||||
|
|
||||||
|
> **Bron:** `ble_capture_workflow_t_1000_e.md`
|
||||||
|
>
|
||||||
|
> Dit document is een **verdiepingsdocument** bij het originele technische werkdocument. Het biedt:
|
||||||
|
> - Didactische uitleg van BLE-concepten en terminologie
|
||||||
|
> - Achtergrondkennis over GATT-services en hun werking
|
||||||
|
> - Context om toekomstige BLE-projecten beter te begrijpen
|
||||||
|
>
|
||||||
|
> **Doelgroep:** Mezelf, als referentie voor de lange termijn.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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:
|
||||||
|
|
||||||
|
- 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
|
||||||
|
|
||||||
|
**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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Begrippen en afkortingen uitgelegd
|
||||||
|
|
||||||
|
### 2.1 BLE — Bluetooth Low Energy
|
||||||
|
|
||||||
|
BLE is een **zuinige variant van Bluetooth**, ontworpen voor apparaten die maanden of jaren op een batterij moeten werken.
|
||||||
|
|
||||||
|
| Eigenschap | Klassiek Bluetooth | BLE |
|
||||||
|
|------------|-------------------|-----|
|
||||||
|
| Stroomverbruik | Hoog | Zeer laag |
|
||||||
|
| Datasnelheid | Hoog | Laag |
|
||||||
|
| Typisch gebruik | Audio, bestanden | Sensoren, IoT, MeshCore |
|
||||||
|
|
||||||
|
**Analogie:** Klassiek Bluetooth is als een telefoongesprek (constant verbonden, veel energie). BLE is als SMS'jes sturen (kort contact wanneer nodig, weinig energie).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.2 GATT — Generic Attribute Profile
|
||||||
|
|
||||||
|
GATT is de **structuur** waarmee BLE-apparaten hun data aanbieden. Zie het als een **digitaal prikbord** met een vaste indeling:
|
||||||
|
|
||||||
|
```
|
||||||
|
Service (categorie)
|
||||||
|
└── Characteristic (specifiek datapunt)
|
||||||
|
└── Descriptor (extra configuratie)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Voorbeeld voor MeshCore:**
|
||||||
|
|
||||||
|
```
|
||||||
|
Nordic UART Service (NUS)
|
||||||
|
├── RX Characteristic → berichten van radio naar computer
|
||||||
|
└── TX Characteristic → berichten van computer naar radio
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.3 NUS — Nordic UART Service
|
||||||
|
|
||||||
|
NUS is een **standaard BLE-service** ontwikkeld door Nordic Semiconductor. Het simuleert een ouderwetse seriële poort (UART) over Bluetooth.
|
||||||
|
|
||||||
|
- **RX** (Receive): Data die je **ontvangt** van het apparaat
|
||||||
|
- **TX** (Transmit): Data die je **verstuurt** naar het apparaat
|
||||||
|
|
||||||
|
Let op: RX/TX zijn vanuit het perspectief van de computer, niet van de radio.
|
||||||
|
|
||||||
|
#### Is NUS een protocol?
|
||||||
|
|
||||||
|
**Nee.** NUS is een **servicespecificatie**, geen protocol. Dit is een belangrijk onderscheid:
|
||||||
|
|
||||||
|
| Niveau | Wat is het | Voorbeeld |
|
||||||
|
|--------|-----------|-----------|
|
||||||
|
| **Protocol** | Regels voor communicatie | BLE, ATT, GATT |
|
||||||
|
| **Service** | Verzameling van gerelateerde characteristics | NUS, Heart Rate Service |
|
||||||
|
| **Characteristic** | Specifiek datapunt binnen een service | RX, TX |
|
||||||
|
|
||||||
|
**Analogie met een restaurant:**
|
||||||
|
|
||||||
|
| Concept | Restaurant-analogie |
|
||||||
|
|---------|---------------------|
|
||||||
|
| **Protocol (GATT)** | De regels: je bestelt bij de ober, eten komt uit de keuken |
|
||||||
|
| **Service (NUS)** | Een specifieke menukaart (bijv. "ontbijtmenu") |
|
||||||
|
| **Characteristics** | De individuele gerechten op dat menu |
|
||||||
|
|
||||||
|
Mensen zeggen vaak "we gebruiken het NUS-protocol", maar strikt genomen is **GATT** het protocol en is **NUS** een service die via GATT wordt aangeboden.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.4 Andere GATT-services (officieel en custom)
|
||||||
|
|
||||||
|
NUS is slechts één van vele BLE-services. De **Bluetooth SIG** (de organisatie achter Bluetooth) definieert tientallen officiële services. Daarnaast kunnen fabrikanten eigen (custom) services maken.
|
||||||
|
|
||||||
|
#### Officiële services (Bluetooth SIG)
|
||||||
|
|
||||||
|
Deze services hebben een **16-bit UUID** en zijn gestandaardiseerd voor interoperabiliteit:
|
||||||
|
|
||||||
|
| Service | UUID | Toepassing |
|
||||||
|
|---------|------|------------|
|
||||||
|
| **Heart Rate Service** | 0x180D | Hartslagmeters, fitnessapparaten |
|
||||||
|
| **Battery Service** | 0x180F | Batterijniveau rapporteren |
|
||||||
|
| **Device Information** | 0x180A | Fabrikant, modelnummer, firmwareversie |
|
||||||
|
| **Blood Pressure** | 0x1810 | Bloeddrukmeters |
|
||||||
|
| **Health Thermometer** | 0x1809 | Medische thermometers |
|
||||||
|
| **Cycling Speed and Cadence** | 0x1816 | Fietssensoren |
|
||||||
|
| **Environmental Sensing** | 0x181A | Temperatuur, luchtvochtigheid, druk |
|
||||||
|
| **Glucose** | 0x1808 | Bloedglucosemeters |
|
||||||
|
| **HID over GATT** | 0x1812 | Toetsenborden, muizen, gamepads |
|
||||||
|
| **Proximity** | 0x1802 | "Find My"-functionaliteit |
|
||||||
|
| **Generic Access** | 0x1800 | **Verplicht** — apparaatnaam en uiterlijk |
|
||||||
|
|
||||||
|
#### Custom/vendor-specific services
|
||||||
|
|
||||||
|
Fabrikanten kunnen eigen services definiëren met een **128-bit UUID**. Voorbeelden:
|
||||||
|
|
||||||
|
| Service | Fabrikant | Toepassing |
|
||||||
|
|---------|-----------|------------|
|
||||||
|
| **Nordic UART Service (NUS)** | Nordic Semiconductor | Seriële poort over BLE |
|
||||||
|
| **Apple Notification Center** | Apple | iPhone notificaties naar wearables |
|
||||||
|
| **Xiaomi Mi Band Service** | Xiaomi | Fitnesstracker communicatie |
|
||||||
|
| **MeshCore Companion** | MeshCore | Radio-communicatie (gebruikt NUS) |
|
||||||
|
|
||||||
|
#### Het verschil: 16-bit vs. 128-bit UUID
|
||||||
|
|
||||||
|
| Type | Lengte | Voorbeeld | Wie mag het maken? |
|
||||||
|
|------|--------|-----------|-------------------|
|
||||||
|
| **Officieel (SIG)** | 16-bit | `0x180D` | Alleen Bluetooth SIG |
|
||||||
|
| **Custom** | 128-bit | `6e400001-b5a3-f393-e0a9-e50e24dcca9e` | Iedereen |
|
||||||
|
|
||||||
|
De NUS-service gebruikt bijvoorbeeld deze 128-bit UUID:
|
||||||
|
```
|
||||||
|
6e400001-b5a3-f393-e0a9-e50e24dcca9e
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Waarom dit relevant is
|
||||||
|
|
||||||
|
In het MeshCore-project gebruiken we **NUS** (een custom service) voor de communicatie. Maar als je met andere BLE-apparaten werkt — zoals een hartslagmeter of een slimme thermostaat — dan gebruiken die vaak **officiële SIG-services**.
|
||||||
|
|
||||||
|
Het principe blijft hetzelfde:
|
||||||
|
1. Ontdek welke services het apparaat aanbiedt
|
||||||
|
2. Zoek de juiste characteristic
|
||||||
|
3. Lees, schrijf, of abonneer op notify
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.5 Notify vs. Read
|
||||||
|
|
||||||
|
Er zijn twee manieren om data van een BLE-apparaat te krijgen:
|
||||||
|
|
||||||
|
| Methode | Werking | Wanneer gebruiken |
|
||||||
|
|---------|---------|-------------------|
|
||||||
|
| **Read** | Jij vraagt actief om data | Eenmalige waarden (bijv. batterijstatus) |
|
||||||
|
| **Notify** | Apparaat stuurt automatisch bij nieuwe data | Continue datastroom (bijv. berichten) |
|
||||||
|
|
||||||
|
**Analogie:**
|
||||||
|
- **Read** = Je belt iemand en vraagt "hoe gaat het?"
|
||||||
|
- **Notify** = Je krijgt automatisch een WhatsApp-bericht als er nieuws is
|
||||||
|
|
||||||
|
Voor MeshCore-captures gebruik je **Notify** — je wilt immers weten wanneer er een bericht binnenkomt.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.6 CCCD — Client Characteristic Configuration Descriptor
|
||||||
|
|
||||||
|
De CCCD is de **aan/uit-schakelaar voor Notify**. Technisch gezien:
|
||||||
|
|
||||||
|
1. Jouw computer schrijft een `1` naar de CCCD
|
||||||
|
2. Het apparaat weet nu: "deze client wil notificaties"
|
||||||
|
3. Bij nieuwe data stuurt het apparaat automatisch een bericht
|
||||||
|
|
||||||
|
**Het cruciale punt:** Slechts **één client tegelijk** kan de CCCD activeren. Een tweede client krijgt de foutmelding:
|
||||||
|
|
||||||
|
```
|
||||||
|
Notify acquired
|
||||||
|
```
|
||||||
|
|
||||||
|
Dit betekent: "iemand anders heeft notify al ingeschakeld."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.7 Pairing, Bonding en Trust
|
||||||
|
|
||||||
|
Dit zijn drie afzonderlijke stappen in het BLE-beveiligingsproces:
|
||||||
|
|
||||||
|
| Stap | Wat gebeurt er | Analogie |
|
||||||
|
|------|----------------|----------|
|
||||||
|
| **Pairing** | Apparaten wisselen cryptografische sleutels uit | Je maakt kennis en wisselt telefoonnummers |
|
||||||
|
| **Bonding** | De sleutels worden permanent opgeslagen | Je slaat het nummer op in je contacten |
|
||||||
|
| **Trust** | Het systeem vertrouwt het apparaat automatisch | Je zet iemand in je favorieten |
|
||||||
|
|
||||||
|
Na deze drie stappen hoef je niet elke keer opnieuw de pincode in te voeren.
|
||||||
|
|
||||||
|
**Controle in Linux:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bluetoothctl info literal:AA:BB:CC:DD:EE:FF | egrep -i "Paired|Bonded|Trusted"
|
||||||
|
```
|
||||||
|
|
||||||
|
Verwachte output:
|
||||||
|
|
||||||
|
```
|
||||||
|
Paired: yes
|
||||||
|
Bonded: yes
|
||||||
|
Trusted: yes
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.8 Ownership — Het kernprobleem
|
||||||
|
|
||||||
|
**Ownership** is een informele term die aangeeft: "welke client heeft op dit moment de actieve GATT-sessie met notify?"
|
||||||
|
|
||||||
|
**Analogie:** Denk aan een walkietalkie waarbij maar één persoon tegelijk kan luisteren:
|
||||||
|
|
||||||
|
- Als GNOME Bluetooth Manager al verbonden is → die is de "eigenaar"
|
||||||
|
- Als jouw Python-script daarna probeert te verbinden → krijgt het geen toegang
|
||||||
|
|
||||||
|
**Typische "eigenaren" die problemen veroorzaken:**
|
||||||
|
|
||||||
|
- GNOME Bluetooth GUI (draait vaak op de achtergrond)
|
||||||
|
- `bluetoothctl connect` (maakt bluetoothctl de eigenaar)
|
||||||
|
- Telefoon met Bluetooth aan
|
||||||
|
- Andere BLE-apps
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.9 BlueZ
|
||||||
|
|
||||||
|
**BlueZ** is de officiële Bluetooth-stack voor Linux. Het is de software die alle Bluetooth-communicatie afhandelt tussen je applicaties en de hardware.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.10 Bleak
|
||||||
|
|
||||||
|
**Bleak** is een Python-bibliotheek voor BLE-communicatie. Het bouwt voort op BlueZ (Linux), Core Bluetooth (macOS) of WinRT (Windows).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. BLE versus Classic Bluetooth
|
||||||
|
|
||||||
|
Een veelvoorkomende vraag: zijn BLE en "gewone" Bluetooth hetzelfde? Het antwoord is **nee** — het zijn verschillende technologieën die wel dezelfde naam en frequentieband delen.
|
||||||
|
|
||||||
|
### 3.1 Twee smaken van Bluetooth
|
||||||
|
|
||||||
|
Sinds Bluetooth 4.0 (2010) zijn er **twee afzonderlijke radiosystemen** binnen de Bluetooth-standaard:
|
||||||
|
|
||||||
|
| Naam | Technische term | Kenmerken |
|
||||||
|
|------|-----------------|-----------|
|
||||||
|
| **Classic Bluetooth** | BR/EDR (Basic Rate / Enhanced Data Rate) | Hoge datasnelheid, continue verbinding, meer stroom |
|
||||||
|
| **Bluetooth Low Energy** | BLE (ook: Bluetooth Smart) | Lage datasnelheid, korte bursts, zeer zuinig |
|
||||||
|
|
||||||
|
**Cruciaal:** Dit zijn **verschillende radioprotocollen** die niet rechtstreeks met elkaar kunnen communiceren.
|
||||||
|
|
||||||
|
### 3.2 Protocol én hardware
|
||||||
|
|
||||||
|
Bluetooth (zowel Classic als BLE) omvat **meerdere lagen** — het is niet alleen een protocol, maar ook hardware:
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────┐
|
||||||
|
│ SOFTWARE │
|
||||||
|
│ ┌───────────────────────────────────┐ │
|
||||||
|
│ │ Applicatie (jouw code) │ │
|
||||||
|
│ ├───────────────────────────────────┤ │
|
||||||
|
│ │ Profielen / GATT Services │ │
|
||||||
|
│ ├───────────────────────────────────┤ │
|
||||||
|
│ │ Protocollen (ATT, L2CAP, etc.) │ │
|
||||||
|
│ ├───────────────────────────────────┤ │
|
||||||
|
│ │ Host Controller Interface (HCI) │ │ ← Grens software/firmware
|
||||||
|
│ └───────────────────────────────────┘ │
|
||||||
|
├─────────────────────────────────────────┤
|
||||||
|
│ FIRMWARE │
|
||||||
|
│ ┌───────────────────────────────────┐ │
|
||||||
|
│ │ Link Layer / Controller │ │
|
||||||
|
│ └───────────────────────────────────┘ │
|
||||||
|
├─────────────────────────────────────────┤
|
||||||
|
│ HARDWARE │
|
||||||
|
│ ┌───────────────────────────────────┐ │
|
||||||
|
│ │ Radio (2.4 GHz transceiver) │ │
|
||||||
|
│ ├───────────────────────────────────┤ │
|
||||||
|
│ │ Antenne │ │
|
||||||
|
│ └───────────────────────────────────┘ │
|
||||||
|
└─────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.3 Waar zit het verschil?
|
||||||
|
|
||||||
|
Het verschil zit op **meerdere lagen**, niet alleen protocol:
|
||||||
|
|
||||||
|
| Laag | Classic (BR/EDR) | BLE | Verschil in hardware? |
|
||||||
|
|------|------------------|-----|----------------------|
|
||||||
|
| **Radio** | GFSK, π/4-DQPSK, 8DPSK | GFSK | **Ja** — andere modulatie |
|
||||||
|
| **Kanalen** | 79 kanalen, 1 MHz breed | 40 kanalen, 2 MHz breed | **Ja** — andere indeling |
|
||||||
|
| **Link Layer** | LMP (Link Manager Protocol) | LL (Link Layer) | **Ja** — andere state machine |
|
||||||
|
| **Protocollen** | L2CAP, RFCOMM, SDP | L2CAP, ATT, GATT | Nee — software |
|
||||||
|
|
||||||
|
### 3.4 Dual-mode apparaten
|
||||||
|
|
||||||
|
De overlap zit in apparaten die **beide** ondersteunen:
|
||||||
|
|
||||||
|
| Apparaattype | Ondersteunt | Voorbeeld |
|
||||||
|
|--------------|-------------|-----------|
|
||||||
|
| **Classic-only** | Alleen BR/EDR | Oude headsets, auto-audio |
|
||||||
|
| **BLE-only** (Bluetooth Smart) | Alleen BLE | Fitnesstrackers, sensoren, T1000-e |
|
||||||
|
| **Dual-Mode** (Bluetooth Smart Ready) | Beide | Smartphones, laptops, ESP32 |
|
||||||
|
|
||||||
|
**Jouw smartphone** is dual-mode: hij kan praten met je klassieke Bluetooth-koptelefoon (BR/EDR) én met je MeshCore T1000-e (BLE).
|
||||||
|
|
||||||
|
### 3.5 Praktijkvoorbeelden
|
||||||
|
|
||||||
|
| Scenario | Wat wordt gebruikt |
|
||||||
|
|----------|-------------------|
|
||||||
|
| Muziek naar je koptelefoon | **Classic** (A2DP profiel) |
|
||||||
|
| Hartslag van je smartwatch | **BLE** (Heart Rate Service) |
|
||||||
|
| Bestand naar laptop sturen | **Classic** (OBEX/FTP profiel) |
|
||||||
|
| MeshCore T1000-e uitlezen | **BLE** (NUS service) |
|
||||||
|
| Handsfree bellen in auto | **Classic** (HFP profiel) |
|
||||||
|
| Slimme lamp bedienen | **BLE** (eigen GATT service) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. BLE kanaalindeling en frequency hopping
|
||||||
|
|
||||||
|
### 4.1 De 40 BLE-kanalen
|
||||||
|
|
||||||
|
De 2.4 GHz ISM-band loopt van **2400 MHz tot 2483.5 MHz** (83.5 MHz breed).
|
||||||
|
|
||||||
|
BLE verdeelt dit in **40 kanalen van elk 2 MHz**:
|
||||||
|
|
||||||
|
```
|
||||||
|
2400 MHz 2480 MHz
|
||||||
|
│ │
|
||||||
|
▼ ▼
|
||||||
|
┌──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┐
|
||||||
|
│00│01│02│03│04│05│06│07│08│09│10│11│12│13│14│15│16│17│18│19│...→ 39
|
||||||
|
└──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┘
|
||||||
|
└──────────────────────────────────────────────────────┘
|
||||||
|
2 MHz per kanaal
|
||||||
|
```
|
||||||
|
|
||||||
|
**Totaal:** 40 × 2 MHz = **80 MHz** gebruikt
|
||||||
|
|
||||||
|
### 4.2 Advertising vs. data kanalen
|
||||||
|
|
||||||
|
De 40 kanalen zijn niet allemaal gelijk:
|
||||||
|
|
||||||
|
| Type | Kanalen | Functie |
|
||||||
|
|------|---------|---------|
|
||||||
|
| **Advertising** | 3 (nrs. 37, 38, 39) | Apparaten vinden, verbinding starten |
|
||||||
|
| **Data** | 37 (nrs. 0-36) | Daadwerkelijke communicatie na verbinding |
|
||||||
|
|
||||||
|
De advertising-kanalen zijn strategisch gekozen om **Wi-Fi-interferentie** te vermijden:
|
||||||
|
|
||||||
|
```
|
||||||
|
Wi-Fi kanaal 1 Wi-Fi kanaal 6 Wi-Fi kanaal 11
|
||||||
|
│ │ │
|
||||||
|
▼ ▼ ▼
|
||||||
|
────████████─────────────█████████────────────████████────
|
||||||
|
|
||||||
|
BLE: ▲ ▲ ▲
|
||||||
|
Ch.37 Ch.38 Ch.39
|
||||||
|
|
||||||
|
(advertising kanalen zitten tússen de Wi-Fi kanalen)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.3 Vergelijking met Classic Bluetooth
|
||||||
|
|
||||||
|
| Aspect | Classic (BR/EDR) | BLE |
|
||||||
|
|--------|------------------|-----|
|
||||||
|
| **Aantal kanalen** | 79 | 40 |
|
||||||
|
| **Kanaalbreedte** | 1 MHz | 2 MHz |
|
||||||
|
| **Totale bandbreedte** | 79 MHz | 80 MHz |
|
||||||
|
| **Frequency hopping** | Ja, alle 79 | Ja, 37 datakanalen |
|
||||||
|
|
||||||
|
Classic heeft **meer maar smallere** kanalen, BLE heeft **minder maar bredere** kanalen.
|
||||||
|
|
||||||
|
### 4.4 Frequency hopping: één kanaal tegelijk
|
||||||
|
|
||||||
|
**Belangrijk inzicht:** Je gebruikt altijd maar **één kanaal tegelijk**. De 40 kanalen zijn er voor **frequency hopping** — het afwisselend wisselen van kanaal om interferentie te vermijden:
|
||||||
|
|
||||||
|
```
|
||||||
|
Tijd →
|
||||||
|
┌───┐ ┌───┐ ┌───┐ ┌───┐
|
||||||
|
Ch. 12 │ ▓ │ │ │ │ │ │ ▓ │
|
||||||
|
└───┘ └───┘ └───┘ └───┘
|
||||||
|
┌───┐ ┌───┐ ┌───┐ ┌───┐
|
||||||
|
Ch. 07 │ │ │ ▓ │ │ │ │ │
|
||||||
|
└───┘ └───┘ └───┘ └───┘
|
||||||
|
┌───┐ ┌───┐ ┌───┐ ┌───┐
|
||||||
|
Ch. 31 │ │ │ │ │ ▓ │ │ │
|
||||||
|
└───┘ └───┘ └───┘ └───┘
|
||||||
|
↑ ↑ ↑ ↑
|
||||||
|
Pakket 1 Pakket 2 Pakket 3 Pakket 4
|
||||||
|
```
|
||||||
|
|
||||||
|
Dit is **geen parallelle communicatie** — het is serieel met wisselende frequentie.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Twee betekenissen van "serieel"
|
||||||
|
|
||||||
|
Wanneer we zeggen "NUS is serieel", kan dit verwarring veroorzaken. Het woord "serieel" heeft namelijk **twee verschillende betekenissen** in deze context.
|
||||||
|
|
||||||
|
### 5.1 Radio-niveau: altijd serieel
|
||||||
|
|
||||||
|
**Alle** draadloze communicatie is serieel op fysiek niveau — je hebt maar **één radiokanaal tegelijk** en bits gaan **na elkaar** de lucht in:
|
||||||
|
|
||||||
|
```
|
||||||
|
Radiogolf: ▁▂▃▄▅▆▇█▇▆▅▄▃▂▁▂▃▄▅▆▇█▇▆▅▄▃▂▁
|
||||||
|
|
||||||
|
Bits: 0 1 1 0 1 0 0 1 1 1 0 1 0 0 1 0 → één voor één
|
||||||
|
```
|
||||||
|
|
||||||
|
De 40 kanalen zijn voor **frequency hopping**, niet voor parallel versturen. Dit geldt voor **alle** BLE-services — NUS, Heart Rate, Battery, allemaal.
|
||||||
|
|
||||||
|
### 5.2 Data-niveau: NUS simuleert een seriële poort
|
||||||
|
|
||||||
|
Wanneer we zeggen "NUS is een seriële service", bedoelen we iets anders:
|
||||||
|
|
||||||
|
**NUS simuleert een oude seriële poort (RS-232/UART):**
|
||||||
|
|
||||||
|
```
|
||||||
|
Historisch (jaren '80-'00):
|
||||||
|
|
||||||
|
Computer Apparaat
|
||||||
|
┌──────┐ Seriële kabel ┌──────┐
|
||||||
|
│ COM1 │←────────────────→│ UART │
|
||||||
|
└──────┘ (RS-232) └──────┘
|
||||||
|
|
||||||
|
Bytes: 0x48 0x65 0x6C 0x6C 0x6F ("Hello")
|
||||||
|
└─────────────────────┘
|
||||||
|
Geen structuur, gewoon een stroom bytes
|
||||||
|
```
|
||||||
|
|
||||||
|
**NUS bootst dit na over BLE:**
|
||||||
|
|
||||||
|
```
|
||||||
|
Vandaag:
|
||||||
|
|
||||||
|
Computer Apparaat
|
||||||
|
┌──────┐ BLE (NUS) ┌──────┐
|
||||||
|
│ App │←~~~~~~~~~~~~~~~~~~~~→│ MCU │
|
||||||
|
└──────┘ (draadloos) └──────┘
|
||||||
|
|
||||||
|
Gedraagt zich alsof er een seriële kabel zit
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.3 Vergelijking: serieel vs. gestructureerd
|
||||||
|
|
||||||
|
| Aspect | NUS (serieel) | Heart Rate (gestructureerd) |
|
||||||
|
|--------|---------------|----------------------------|
|
||||||
|
| **Radio** | Serieel, frequency hopping | Serieel, frequency hopping |
|
||||||
|
| **Data** | Ongestructureerde bytestroom | Vaste velden met betekenis |
|
||||||
|
| **Wie bepaalt formaat?** | Jij (eigen protocol) | Bluetooth SIG (specificatie) |
|
||||||
|
|
||||||
|
### 5.4 Analogie: snelweg met rijstroken
|
||||||
|
|
||||||
|
Denk aan een **snelweg met 40 rijstroken** (de kanalen):
|
||||||
|
|
||||||
|
- Je mag maar **één rijstrook tegelijk** gebruiken
|
||||||
|
- Je wisselt regelmatig van rijstrook (frequency hopping, om botsingen te vermijden)
|
||||||
|
- De **vracht** die je vervoert kan verschillen:
|
||||||
|
|
||||||
|
| Service | Vracht-analogie |
|
||||||
|
|---------|-----------------|
|
||||||
|
| **NUS** | Losse spullen door elkaar (flexibel, maar jij moet uitzoeken wat wat is) |
|
||||||
|
| **Heart Rate** | Gestandaardiseerde pallets (iedereen weet wat waar zit) |
|
||||||
|
|
||||||
|
De **snelweg werkt hetzelfde** — het verschil zit in hoe je de vracht organiseert.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Seriële vs. gestructureerde services (verdieping)
|
||||||
|
|
||||||
|
Een belangrijk onderscheid dat vaak over het hoofd wordt gezien: **niet alle BLE-services werken hetzelfde**. Er zijn fundamenteel twee benaderingen.
|
||||||
|
|
||||||
|
### 6.1 Seriële services (stream-gebaseerd)
|
||||||
|
|
||||||
|
**NUS (Nordic UART Service)** is ontworpen om een **seriële poort te simuleren**:
|
||||||
|
|
||||||
|
- Continue datastroom van ruwe bytes
|
||||||
|
- Geen opgelegde structuur
|
||||||
|
- Jij bepaalt zelf het formaat en de betekenis
|
||||||
|
|
||||||
|
**Analogie:** Een seriële service is als een **telefoonlijn** — je kunt alles zeggen wat je wilt, in elke taal, zonder vaste regels.
|
||||||
|
|
||||||
|
```
|
||||||
|
Voorbeeld NUS-data (MeshCore):
|
||||||
|
0x01 0x0A 0x48 0x65 0x6C 0x6C 0x6F ...
|
||||||
|
└── Betekenis bepaald door MeshCore protocol, niet door BLE
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6.2 Gestructureerde services (veld-gebaseerd)
|
||||||
|
|
||||||
|
De meeste officiële SIG-services werken **anders** — ze definiëren **exact** welke bytes wat betekenen:
|
||||||
|
|
||||||
|
**Analogie:** Een gestructureerde service is als een **belastingformulier** — elk vakje heeft een vaste betekenis en een voorgeschreven formaat.
|
||||||
|
|
||||||
|
#### Voorbeeld: Heart Rate Measurement
|
||||||
|
|
||||||
|
```
|
||||||
|
Byte 0: Flags (bitfield)
|
||||||
|
├── Bit 0: 0 = hartslag in 1 byte, 1 = hartslag in 2 bytes
|
||||||
|
├── Bit 1-2: Sensor contact status
|
||||||
|
├── Bit 3: Energy expended aanwezig?
|
||||||
|
└── Bit 4: RR-interval aanwezig?
|
||||||
|
|
||||||
|
Byte 1(-2): Heart rate waarde
|
||||||
|
Byte N...: Optionele extra velden (afhankelijk van flags)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Concreet voorbeeld:**
|
||||||
|
|
||||||
|
```
|
||||||
|
Ontvangen bytes: 0x00 0x73
|
||||||
|
|
||||||
|
0x00 = Flags: 8-bit formaat, geen extra velden
|
||||||
|
0x73 = 115 decimaal → hartslag is 115 bpm
|
||||||
|
```
|
||||||
|
|
||||||
|
Je krijgt dus niet de tekst "115", maar een binair pakket dat je moet **parsen** volgens de specificatie.
|
||||||
|
|
||||||
|
#### Voorbeeld: Battery Level
|
||||||
|
|
||||||
|
Eenvoudiger — slechts **1 byte**:
|
||||||
|
|
||||||
|
```
|
||||||
|
Ontvangen byte: 0x5A
|
||||||
|
|
||||||
|
0x5A = 90 decimaal → batterij is 90%
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Voorbeeld: Environmental Sensing (temperatuur)
|
||||||
|
|
||||||
|
```
|
||||||
|
Ontvangen bytes: 0x9C 0x08
|
||||||
|
|
||||||
|
Little-endian 16-bit signed integer: 0x089C = 2204
|
||||||
|
Resolutie: 0.01°C
|
||||||
|
Temperatuur: 2204 × 0.01 = 22.04°C
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6.3 Vergelijkingstabel
|
||||||
|
|
||||||
|
| Aspect | Serieel (NUS) | Gestructureerd (SIG) |
|
||||||
|
|--------|---------------|----------------------|
|
||||||
|
| **Data-indeling** | Vrij, zelf bepalen | Vast, door specificatie |
|
||||||
|
| **Wie definieert het formaat?** | Jij / de fabrikant | Bluetooth SIG |
|
||||||
|
| **Waar vind je de specificatie?** | Eigen documentatie / broncode | bluetooth.com/specifications |
|
||||||
|
| **Parsing** | Eigen parser bouwen | Standaard parser mogelijk |
|
||||||
|
| **Interoperabiliteit** | Alleen eigen software | Elke conforme app/device |
|
||||||
|
| **Flexibiliteit** | Maximaal | Beperkt tot spec |
|
||||||
|
| **Complexiteit** | Eenvoudig te starten | Spec lezen vereist |
|
||||||
|
|
||||||
|
### 6.4 Voorbeelden van gestructureerde services
|
||||||
|
|
||||||
|
| Service | Characteristic | Data-formaat |
|
||||||
|
|---------|----------------|--------------|
|
||||||
|
| **Battery Service** | Battery Level | 1 byte: 0-100 (percentage) |
|
||||||
|
| **Heart Rate** | Heart Rate Measurement | Flags + 8/16-bit HR + optionele velden |
|
||||||
|
| **Health Thermometer** | Temperature Measurement | IEEE-11073 FLOAT (4 bytes) |
|
||||||
|
| **Blood Pressure** | Blood Pressure Measurement | Compound: systolisch, diastolisch, MAP, pulse |
|
||||||
|
| **Cycling Speed & Cadence** | CSC Measurement | 32-bit tellers + 16-bit tijd |
|
||||||
|
| **Environmental Sensing** | Temperature | 16-bit signed, resolutie 0.01°C |
|
||||||
|
| **Environmental Sensing** | Humidity | 16-bit unsigned, resolutie 0.01% |
|
||||||
|
| **Environmental Sensing** | Pressure | 32-bit unsigned, resolutie 0.1 Pa |
|
||||||
|
|
||||||
|
### 6.5 Wanneer welke aanpak?
|
||||||
|
|
||||||
|
| Situatie | Aanbevolen aanpak |
|
||||||
|
|----------|-------------------|
|
||||||
|
| Eigen protocol (MeshCore, custom IoT) | **Serieel** (NUS of eigen service) |
|
||||||
|
| Standaard use-case (hartslag, batterij) | **Gestructureerd** (SIG-service) |
|
||||||
|
| Interoperabiliteit met bestaande apps vereist | **Gestructureerd** (SIG-service) |
|
||||||
|
| Complexe, variabele datastructuren | **Serieel** met eigen protocol |
|
||||||
|
| Snel prototype zonder spec-studie | **Serieel** (NUS) |
|
||||||
|
|
||||||
|
### 6.6 Waarom MeshCore NUS gebruikt
|
||||||
|
|
||||||
|
MeshCore koos voor NUS (serieel) omdat:
|
||||||
|
|
||||||
|
1. **Flexibiliteit** — Het Companion Protocol heeft eigen framing nodig
|
||||||
|
2. **Geen passende SIG-service** — Er is geen "Mesh Radio Service" standaard
|
||||||
|
3. **Bidirectionele communicatie** — NUS biedt RX én TX characteristics
|
||||||
|
4. **Eenvoud** — Geen complexe SIG-specificatie implementeren
|
||||||
|
|
||||||
|
Het nadeel: je kunt niet zomaar een willekeurige BLE-app gebruiken om met MeshCore te praten — je hebt software nodig die het MeshCore Companion Protocol begrijpt.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Het OSI-model in context
|
||||||
|
|
||||||
|
Het document plaatst het probleem in een **lagenmodel**. Dit helpt begrijpen *waar* het probleem zit:
|
||||||
|
|
||||||
|
| Laag | Naam | In dit project | Probleem hier? |
|
||||||
|
|------|------|----------------|----------------|
|
||||||
|
| 7 | Applicatie | MeshCore Companion Protocol | Nee |
|
||||||
|
| 6 | Presentatie | Frame-encoding (hex) | Nee |
|
||||||
|
| **5** | **Sessie** | **GATT client ↔ server sessie** | **★ JA** |
|
||||||
|
| 4 | Transport | ATT / GATT | Nee |
|
||||||
|
| 2 | Data Link | BLE Link Layer | Nee |
|
||||||
|
| 1 | Fysiek | 2.4 GHz radio | Nee |
|
||||||
|
|
||||||
|
**Conclusie:** Het ownership-probleem zit op **laag 5 (sessie)**. De firmware en het protocol zijn niet het probleem — het gaat om wie de sessie "bezit".
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. De workflow samengevat
|
||||||
|
|
||||||
|
### 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:
|
||||||
|
|
||||||
|
- ✅ MeshCore BLE companion **werkt correct** op Linux
|
||||||
|
- ✅ De firmware **blokkeert notify niet**
|
||||||
|
- ✅ 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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12. 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/)
|
||||||
|
- Bluetooth SIG GATT Specifications: [bluetooth.com/specifications/specs](https://www.bluetooth.com/specifications/specs/)
|
||||||
|
- Nordic Bluetooth Numbers Database: [GitHub](https://github.com/NordicSemiconductor/bluetooth-numbers-database)
|
||||||
|
- GATT Uitleg (Adafruit): [learn.adafruit.com](https://learn.adafruit.com/introduction-to-bluetooth-low-energy/gatt)
|
||||||
|
- Bleak documentatie: [bleak.readthedocs.io](https://bleak.readthedocs.io/)
|
||||||
|
- BlueZ: [bluez.org](http://www.bluez.org/)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> **Document:** `ble_capture_workflow_t_1000_e_uitleg.md`
|
||||||
|
> **Gebaseerd op:** `ble_capture_workflow_t_1000_e.md`
|
||||||
1105
meshcore_gui.py
Normal file
1105
meshcore_gui.py
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user