Merge dev into main

.github/workflows/test.yml

@@ -1,4 +1,4 @@
-name: Tests
+name: Build
 
 on:
   pull_request:
@@ -27,8 +27,8 @@ jobs:
       - name: Test PocketMeshServices
         run: swift test --package-path PocketMeshServices
 
-  xcode-tests:
-    name: Xcode Tests
+  xcode-build:
+    name: Xcode Build
     runs-on: macos-26
 
     steps:
@@ -54,39 +54,13 @@ jobs:
           deriveddata-directory: .derivedData
           delete-used-deriveddata-cache: true
 
-      - name: Boot simulator
+      - name: Build
         run: |
-          DEVICE_ID=$(xcrun simctl list devices available -j | python3 -c "
-          import json, sys
-          data = json.load(sys.stdin)
-          for runtime, devices in data['devices'].items():
-              for d in devices:
-                  if d['name'] == 'iPhone 16e' and d['isAvailable']:
-                      print(d['udid'])
-                      sys.exit(0)
-          sys.exit(1)
-          ")
-          xcrun simctl boot "$DEVICE_ID" || true
-
-      - name: Build for testing
-        run: |
-          xcodebuild build-for-testing \
+          xcodebuild build \
             -scheme PocketMesh \
-            -destination "platform=iOS Simulator,name=iPhone 16e" \
+            -destination "generic/platform=iOS Simulator" \
             -derivedDataPath .derivedData \
             CODE_SIGN_IDENTITY="-" \
             CODE_SIGNING_REQUIRED=NO \
             CODE_SIGNING_ALLOWED=NO \
-            COMPILER_INDEX_STORE_ENABLE=NO \
-            GCC_GENERATE_DEBUGGING_SYMBOLS=NO
-
-      - name: Run tests
-        run: |
-          xcodebuild test-without-building \
-            -scheme PocketMesh \
-            -destination "platform=iOS Simulator,name=iPhone 16e" \
-            -derivedDataPath .derivedData \
-            -resultBundlePath TestResults.xcresult \
-            -parallel-testing-enabled NO \
-            -enableCodeCoverage NO \
-            -collect-test-diagnostics never
+            COMPILER_INDEX_STORE_ENABLE=NO

CONTRIBUTING.md

@@ -5,7 +5,7 @@ To make the contribution process smooth and respectful of everyone's time, pleas
 ### Before Starting Work
 - **Discuss your idea first**: Reach out so we can coordinate. This helps avoid duplicate effort, as I might already be working on something similar.
 - [MeshCore Discord](https://discord.gg/bSuST8xvet) — look for the PocketMesh forum post.
-- Or message me on Matrix at @avion:matrix.org
+- Or message me on Matrix @avion:matrix.org
 
 ### Pull Request Requirements
 When submitting a PR, please:
@@ -21,7 +21,7 @@ If you're an experienced software engineer and did not rely heavily on AI for yo
 If you used AI extensively (which is totally fine, I built this entire project with AI despite not being a SWE and only having basic Python scripting experience), please follow these best practices to ensure high-quality results:
 
 1. **Choose the right model for planning**  
-   If you're not a software engineer and aren't comfortable creating detailed technical plans yourself, stick to the strongest reasoning models: **Claude Opus 4.5** or **GPT 5.2 (high/xhigh)**. These are decent at turning non-technical ideas into solid implementation plans. Other popular models (e.g., GLM 4.7, MiniMax 2.1) perform well when given a detailed plan, but struggle to create one from scratch in a large codebase.
+   If you're not a software engineer and aren't comfortable creating detailed technical plans yourself, stick to the strongest reasoning models: **Claude Opus** or **GPT Codex (high/xhigh)**. These are decent at turning non-technical ideas into solid implementation plans. Other popular models (e.g., GLM, MiniMax) perform well when given a detailed plan, but struggle to create one from scratch in a large codebase.
 
 2. **Plan thoroughly**  
    Ask the AI to use research agents/tools to gather context about the relevant parts of the codebase. Think of edge cases. Write the plan to an md file.
@@ -42,7 +42,7 @@ If you used AI extensively (which is totally fine, I built this entire project w
    Manually verify that everything works as expected. Test edge cases.
 
 8. **Submit the PR**  
-   You can ask the AI to draft the PR description. Feel free to use it directly, but adding a bit of your own voice is always appreciated!
+   In the description, include the reason you are making the changes. You can ask the AI to draft the PR description. Feel free to use it directly, but adding a bit of your own voice is always appreciated!
 
 
 ## Getting Started

MeshCore/Sources/MeshCore/Events/MeshEvent.swift

@@ -675,6 +675,7 @@ public struct RadioStats: Sendable, Equatable {
 /// - Bytes 12-15: UInt32 - direct_tx
 /// - Bytes 16-19: UInt32 - flood_rx
 /// - Bytes 20-23: UInt32 - direct_rx
+/// - Bytes 24-27: UInt32 - recv_errors (optional, present when frame >= 28 bytes)
 public struct PacketStats: Sendable, Equatable {
     /// Total packets received.
     public let received: UInt32
@@ -688,6 +689,8 @@ public struct PacketStats: Sendable, Equatable {
     public let floodRx: UInt32
     /// Total direct packets received.
     public let directRx: UInt32
+    /// Total RadioLib receive errors (CRC failures, malformed packets).
+    public let receiveErrors: UInt32
 
     /// Initializes a new packet statistics object.
     public init(
@@ -696,14 +699,16 @@ public struct PacketStats: Sendable, Equatable {
         floodTx: UInt32,
         directTx: UInt32,
         floodRx: UInt32,
-        directRx: UInt32
+        directRx: UInt32,
+        receiveErrors: UInt32 = 0
     ) {
         self.received = received
         self.sent = sent
         self.floodTx = floodTx
         self.directTx = directTx
         self.floodRx = floodRx
         self.directRx = directRx
+        self.receiveErrors = receiveErrors
     }
 }
 

MeshCore/Sources/MeshCore/MeshCore.docc/Articles/ManagingContacts.md

@@ -80,7 +80,7 @@ try await session.updateContact(
     publicKey: publicKey,
     type: 0,
     flags: 0,
-    outPathLength: -1,  // Flood routing
+    outPathLength: 0xFF,  // Flood routing (OUT_PATH_UNKNOWN)
     outPath: Data(),
     advertisedName: "New Contact",
     lastAdvertisement: Date(),

MeshCore/Sources/MeshCore/Models/Contact.swift

@@ -11,7 +11,13 @@ import Foundation
 ///
 /// ## Routing
 /// The ``outPath`` and ``outPathLength`` describe the routing path to reach
-/// this contact. A path length of -1 indicates flood routing (broadcast to all).
+/// this contact. A path length of `0xFF` indicates flood routing (broadcast to all).
+///
+/// The ``outPathLength`` byte uses bit packing to encode both the hash size and hop count:
+/// - Upper 2 bits (6-7): hash size mode (0=1-byte, 1=2-byte, 2=3-byte, 3=reserved)
+/// - Lower 6 bits (0-5): hop count (0-63)
+///
+/// Use ``pathHashSize``, ``pathHopCount``, and ``pathByteLength`` to decode these fields.
 ///
 /// ## Location
 /// If the contact shares its location, ``latitude`` and ``longitude``
@@ -42,8 +48,11 @@ public struct MeshContact: Sendable, Identifiable, Equatable {
     /// The operational flags for the contact.
     public let flags: ContactFlags
 
-    /// The length of the outbound routing path, where -1 indicates flood routing.
-    public let outPathLength: Int8
+    /// The encoded outbound path length byte.
+    ///
+    /// Uses bit packing: upper 2 bits = hash size mode, lower 6 bits = hop count.
+    /// A value of `0xFF` indicates flood routing (unknown path).
+    public let outPathLength: UInt8
 
     /// The outbound routing path data.
     public let outPath: Data
@@ -73,9 +82,30 @@ public struct MeshContact: Sendable, Identifiable, Equatable {
     /// Indicates whether this contact uses flood (broadcast) routing.
     ///
     /// Flood routing sends messages to all nodes in the network. This is used when
-    /// no direct path is known.
+    /// no direct path is known. Represented by `0xFF` on the wire.
     public var isFloodPath: Bool {
-        outPathLength == -1
+        outPathLength == 0xFF
+    }
+
+    /// The hash size per hop in bytes (1, 2, or 3), derived from the upper 2 bits of ``outPathLength``.
+    ///
+    /// Only meaningful when ``isFloodPath`` is `false`.
+    public var pathHashSize: Int {
+        decodePathLen(outPathLength)?.hashSize ?? 1
+    }
+
+    /// The number of hops in the path, derived from the lower 6 bits of ``outPathLength``.
+    ///
+    /// Only meaningful when ``isFloodPath`` is `false`.
+    public var pathHopCount: Int {
+        decodePathLen(outPathLength)?.hopCount ?? 0
+    }
+
+    /// The total byte length of the path data (`pathHopCount * pathHashSize`).
+    ///
+    /// Only meaningful when ``isFloodPath`` is `false`.
+    public var pathByteLength: Int {
+        decodePathLen(outPathLength)?.byteLength ?? 0
     }
 
     /// Initializes a new mesh contact with the specified properties.
@@ -85,7 +115,7 @@ public struct MeshContact: Sendable, Identifiable, Equatable {
     ///   - publicKey: The 32-byte public key data.
     ///   - type: Contact type identifier (chat, repeater, room).
     ///   - flags: Operational flags (favorite, telemetry permissions).
-    ///   - outPathLength: Length of the outbound path.
+    ///   - outPathLength: Encoded outbound path length byte.
     ///   - outPath: Outbound path data.
     ///   - advertisedName: Name advertised by the node.
     ///   - lastAdvertisement: Date of last advertisement.
@@ -97,7 +127,7 @@ public struct MeshContact: Sendable, Identifiable, Equatable {
         publicKey: Data,
         type: ContactType,
         flags: ContactFlags,
-        outPathLength: Int8,
+        outPathLength: UInt8,
         outPath: Data,
         advertisedName: String,
         lastAdvertisement: Date,

MeshCore/Sources/MeshCore/Models/DeviceInfo.swift

@@ -97,6 +97,11 @@ public struct DeviceCapabilities: Sendable, Equatable {
     public let version: String
     /// Whether client repeat mode is enabled (v9+ firmware).
     public let clientRepeat: Bool
+    /// The path hash mode (0=1-byte, 1=2-byte, 2=3-byte hashes). Firmware v10+.
+    public let pathHashMode: UInt8
+
+    /// The hash size per hop in bytes (1, 2, or 3), derived from ``pathHashMode``.
+    public var hashSize: Int { Int(pathHashMode) + 1 }
 
     /// Initializes a new device capabilities structure.
     public init(
@@ -107,7 +112,8 @@ public struct DeviceCapabilities: Sendable, Equatable {
         firmwareBuild: String,
         model: String,
         version: String,
-        clientRepeat: Bool = false
+        clientRepeat: Bool = false,
+        pathHashMode: UInt8 = 0
     ) {
         self.firmwareVersion = firmwareVersion
         self.maxContacts = maxContacts
@@ -117,6 +123,7 @@ public struct DeviceCapabilities: Sendable, Equatable {
         self.model = model
         self.version = version
         self.clientRepeat = clientRepeat
+        self.pathHashMode = pathHashMode
     }
 }
 

MeshCore/Sources/MeshCore/Protocol/PacketBuilder.swift

@@ -543,7 +543,7 @@ public enum PacketBuilder: Sendable {
     /// - Offset 1 (32 bytes): Public key
     /// - Offset 33 (1 byte): Type
     /// - Offset 34 (1 byte): Flags
-    /// - Offset 35 (1 byte): Out path length (signed Int8 as UInt8)
+    /// - Offset 35 (1 byte): Out path length (encoded: upper 2 bits = hash mode, lower 6 bits = hop count; 0xFF = flood)
     /// - Offset 36 (64 bytes): Out path (zero-padded)
     /// - Offset 100 (32 bytes): Advertised name (UTF-8, zero-padded)
     /// - Offset 132 (4 bytes): Last advert timestamp (UInt32 LE)
@@ -557,7 +557,7 @@ public enum PacketBuilder: Sendable {
         data.append(contact.publicKey.paddedOrTruncated(to: 32))           // 32 bytes
         data.append(contact.type.rawValue)                                   // 1 byte
         data.append(contact.flags.rawValue)                                  // 1 byte
-        data.append(UInt8(bitPattern: contact.outPathLength))               // 1 byte
+        data.append(contact.outPathLength)                                    // 1 byte
         data.append(contact.outPath.paddedOrTruncated(to: 64))              // 64 bytes
         data.append(contact.advertisedName.utf8PaddedOrTruncated(to: 32))   // 32 bytes
 
@@ -780,6 +780,19 @@ public enum PacketBuilder: Sendable {
         return data
     }
 
+    /// Builds a setPathHashMode command to configure the path hash size.
+    ///
+    /// - Parameter mode: Hash mode (0=1-byte, 1=2-byte, 2=3-byte hashes).
+    /// - Returns: The command packet data.
+    ///
+    /// ### Binary Format
+    /// - Offset 0 (1 byte): Command code `0x3D`
+    /// - Offset 1 (1 byte): Reserved `0x00`
+    /// - Offset 2 (1 byte): Mode value (0, 1, or 2)
+    public static func setPathHashMode(_ mode: UInt8) -> Data {
+        Data([CommandCode.setPathHashMode.rawValue, 0x00, mode])
+    }
+
     /// Builds a factoryReset command to wipe all settings and data from the device.
     ///
     /// - Returns: The command packet data.

MeshCore/Sources/MeshCore/Protocol/PacketCodes.swift

@@ -104,6 +104,8 @@ public enum CommandCode: UInt8, Sendable {
     case getAutoAddConfig = 0x3B
     /// Gets the allowed frequency ranges for client repeat mode (v9+).
     case getRepeatFreq = 0x3C
+    /// Sets the path hash mode (0=1-byte, 1=2-byte, 2=3-byte hashes).
+    case setPathHashMode = 0x3D
 }
 
 /// Defines the response codes received from the mesh device.