mirror of
https://github.com/zjs81/meshcore-open.git
synced 2026-07-26 05:26:37 +10:00
clean
This commit is contained in:
PacoX
@@ -1,130 +0,0 @@
|
|||||||
# Add Support for Multi-Byte Routing Paths
|
|
||||||
|
|
||||||
## Summary
|
|
||||||
|
|
||||||
Adds support for variable-length multi-byte routing paths in MeshCore Open, enabling the app to scale from small meshes (256 unique nodes, 1-byte hashes) to very large networks (65K+ nodes with 2-byte hashes, 16M+ with 3-byte hashes).
|
|
||||||
|
|
||||||
The implementation detects device capability via byte 81 in `RESP_CODE_SELF_INFO` (firmware v1.10+). This approach is similar to how meshcore-py handles multi-byte paths, though meshcore-py reads the capability from `DEVICE_INFO` instead.
|
|
||||||
|
|
||||||
## Behavior Changes
|
|
||||||
|
|
||||||
- **Device capability detection**: App now reads byte 81 from `RESP_CODE_SELF_INFO` to detect supported path hash width (1, 2, 3, or 4 bytes)
|
|
||||||
- **Path resolution**: Contact names now resolved correctly for multi-byte paths via `PathHelper.resolvePathNames(hashByteWidth)`
|
|
||||||
- **Path entry UI**: Chat path dialog and custom path entry now support comma-separated hex prefixes matching device capability (e.g., `A1B2,C1C2` for 2-byte mode)
|
|
||||||
- **Backward compatible**: Defaults to 1-byte mode (v1.13 and earlier firmware) when capability byte unavailable
|
|
||||||
|
|
||||||
## BLE Protocol Changes (Explicit)
|
|
||||||
|
|
||||||
**Path Encoding** (firmware byte 81, device capability):
|
|
||||||
- Single byte packs hop count (bits 5-0) + hash mode (bits 7-6)
|
|
||||||
- Hash modes: 0=1-byte, 1=2-byte, 2=3-byte, 3=4-byte
|
|
||||||
- Supported by firmware v1.10+ (v1.13 and earlier hardcoded to mode 0)
|
|
||||||
- No wire format changes; purely capability detection
|
|
||||||
|
|
||||||
**Frame Parsing** (unchanged):
|
|
||||||
- `RESP_CODE_CONTACT` byte 32 still contains path length (hop_count | mode << 6)
|
|
||||||
- Bytes 33-96 contain path data (interpretation varies by hash width)
|
|
||||||
- No impact on existing 1-byte deployments
|
|
||||||
|
|
||||||
## Changes
|
|
||||||
|
|
||||||
### Protocol & Encoding
|
|
||||||
- **Path encoding**: Single byte packs both hop count (bits 5-0) and hash mode (bits 7-6)
|
|
||||||
- **Hash modes**: 0 (1-byte), 1 (2-byte), 2 (3-byte), 3 (4-byte)
|
|
||||||
- **Total path bytes** = hopCount × hashByteWidth
|
|
||||||
- **Firmware detection**: Device reports capability via byte 81 in `RESP_CODE_SELF_INFO` (v1.10+)
|
|
||||||
|
|
||||||
### Code Changes
|
|
||||||
|
|
||||||
#### 1. **Connector (`meshcore_connector.dart`)**
|
|
||||||
- Added `_pathHashByteWidth` field, initialized to 1 (default mode)
|
|
||||||
- Added `pathHashByteWidth` getter for UI and frame builders
|
|
||||||
- Device capability detection on `RESP_CODE_SELF_INFO`:
|
|
||||||
```dart
|
|
||||||
if (frame.length >= 82) {
|
|
||||||
final mode = (frame[81] & 0xFF).clamp(0, 2);
|
|
||||||
_pathHashByteWidth = mode + 1;
|
|
||||||
} else {
|
|
||||||
_pathHashByteWidth = 1; // Fallback for v1.13 and earlier firmware
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 2. **Path Helper (`path_helper.dart`)**
|
|
||||||
- Updated `resolvePathNames()` to accept `hashByteWidth` parameter
|
|
||||||
- Groups path bytes according to width: `for (int i = 0; i < pathBytes.length; i += width)`
|
|
||||||
- Matches contact public key prefixes using `listEquals()` for multi-byte comparison
|
|
||||||
- Returns formatted path string with node names or hex fallback
|
|
||||||
|
|
||||||
#### 3. **Path Selection Dialog (`path_selection_dialog.dart`)**
|
|
||||||
- Removed unused variables that triggered analyzer warnings
|
|
||||||
- Dialog now supports multibyte path entry via `pathHashByteWidth` parameter
|
|
||||||
- UI hints user about expected format based on device capability
|
|
||||||
|
|
||||||
#### 4. **UI Updates**
|
|
||||||
- Chat screen now displays: "Custom path entry follows the device's current hash width"
|
|
||||||
- Path selection dialog accepts comma-separated hex prefixes (e.g., `A1B2,C1C2` for 2-byte mode)
|
|
||||||
- Backward compatible: existing 1-byte paths work unchanged
|
|
||||||
|
|
||||||
### Testing
|
|
||||||
- Added comprehensive test suite in `path_helper_test.dart`:
|
|
||||||
- 1-byte mode with repeater/room node name resolution
|
|
||||||
- 2-byte mode with multi-byte prefix matching
|
|
||||||
- Fallback hex display when contacts not found
|
|
||||||
- All tests passing (229 total, 0 failures)
|
|
||||||
|
|
||||||
### Documentation
|
|
||||||
- New dedicated page: `documentation/routing-paths.md`
|
|
||||||
- Path encoding format and byte calculation
|
|
||||||
- Device capability detection flow
|
|
||||||
- Path usage in different message types
|
|
||||||
- Contact path storage and parsing examples
|
|
||||||
- Updated `documentation/README.md` to link routing paths documentation
|
|
||||||
- Updated `documentation/chat-and-messaging.md` with UI path entry notes
|
|
||||||
- Updated `docs/BLE_PROTOCOL.md` with reference pointer
|
|
||||||
|
|
||||||
### Quality
|
|
||||||
- `flutter analyze`: ✅ No issues
|
|
||||||
- `flutter test`: ✅ 229 tests passing
|
|
||||||
- Backward compatible: ✅ Defaults to 1-byte mode (v1.13 support)
|
|
||||||
- No breaking changes to existing APIs
|
|
||||||
|
|
||||||
## Screenshots & UI Testing
|
|
||||||
|
|
||||||
### Path Selection Dialog (Multi-Byte Mode)
|
|
||||||
- **Before**: Only accepts single hex bytes (e.g., `A1,B2,C3`)
|
|
||||||
- **After**: Now accepts hex prefixes matching device capability (e.g., `A1B2,C1C2` for 2-byte; `A1B2C1,D1D2D3` for 3-byte)
|
|
||||||
- **Behavior**: Dialog automatically adjusts validation based on `pathHashByteWidth` from connected device
|
|
||||||
- **Fallback**: Invalid entries show snackbar with error message (unchanged)
|
|
||||||
|
|
||||||
### Chat Screen Path Display
|
|
||||||
- **Before**: "Custom path" label
|
|
||||||
- **After**: Includes hint "Custom path entry follows the device's current hash width"
|
|
||||||
- **Visual**: No appearance changes; purely informational text
|
|
||||||
|
|
||||||
### Path History / Path Management
|
|
||||||
- Shows resolved contact names for all path widths
|
|
||||||
- Hex fallback (e.g., "A1B2 → C1C2") when contacts not in list
|
|
||||||
- Works seamlessly across 1-byte and multi-byte networks
|
|
||||||
|
|
||||||
## Linked Issues
|
|
||||||
|
|
||||||
<!-- Link to any related issues or PRs here -->
|
|
||||||
- Relates to: Multi-byte path support in MeshCore firmware v1.10+
|
|
||||||
- Supersedes: Any previous path scaling limitations
|
|
||||||
- Reference: meshcore-py handles multi-byte paths via same firmware capability
|
|
||||||
|
|
||||||
## Related PRs & References
|
|
||||||
|
|
||||||
- **Reference implementation**: [meshcore-py](https://github.com/nonik0/meshcore-py) also handles multi-byte paths using same firmware capability
|
|
||||||
- **Firmware support**: MeshCore v1.10+ reports path hash mode in byte 81 of `RESP_CODE_SELF_INFO` (v1.13 and earlier hardcoded to 1-byte)
|
|
||||||
- **Protocol reference**: `docs/BLE_PROTOCOL.md` and `documentation/routing-paths.md`
|
|
||||||
- **MeshCore companion radio**: Implements path mode selection via `set path.hash.mode` CLI command
|
|
||||||
|
|
||||||
## Migration & Deployment Notes
|
|
||||||
|
|
||||||
- **No action required for users**: App automatically detects device capability
|
|
||||||
- **Existing 1-byte deployments**: Continue to work unchanged
|
|
||||||
- **New multi-byte devices**: Automatically detected and supported
|
|
||||||
- **Mixed networks**: 1-byte and multi-byte nodes coexist seamlessly
|
|
||||||
- **Firmware v1.13 and earlier**: Fallback to 1-byte mode (no change to behavior)
|
|
||||||
- **Firmware v1.10+**: Multi-byte paths enabled automatically on first connection
|
|
||||||
Reference in New Issue
Block a user