mirror of
https://github.com/zjs81/meshcore-open.git
synced 2026-07-11 19:17:04 +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