Dev companion v2

docs/mkdocs.yml

@@ -96,6 +96,7 @@ markdown_extensions:
 nav:
   - Home: index.md
   - Node Usage Guide: node.md
+  - Companion Guide: companion.md
   - API Reference:
       - Core: api/core.md
       - Protocol: api/protocol.md

examples/discover_nodes.py

@@ -177,9 +177,7 @@ def main():
     if args.radio_type == "kiss-tnc":
         print(f"Serial port: {args.serial_port}")
 
-    asyncio.run(
-        discover_nodes(args.radio_type, args.serial_port, args.timeout, args.filter)
-    )
+    asyncio.run(discover_nodes(args.radio_type, args.serial_port, args.timeout, args.filter))
 
 
 if __name__ == "__main__":

scripts/test_modem_crypto.py

@@ -9,14 +9,14 @@
 - Encryption/decryption
 """
 
-import sys
 import os
+import sys
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
 
-from pymc_core.hardware.kiss_modem_wrapper import KissModemWrapper
-from pymc_core.protocol.identity import Identity, LocalIdentity
-from pymc_core.protocol.crypto import CryptoUtils
+from pymc_core.hardware.kiss_modem_wrapper import KissModemWrapper  # noqa: E402
+from pymc_core.protocol.crypto import CryptoUtils  # noqa: E402
+from pymc_core.protocol.identity import Identity, LocalIdentity  # noqa: E402
 
 
 def test_modem_crypto(port: str = "/dev/cu.usbmodem1101"):
@@ -149,7 +149,7 @@ def test_modem_crypto(port: str = "/dev/cu.usbmodem1101"):
             modem_decrypted = modem.decrypt_data(key, mac, ciphertext)
             if modem_decrypted:
                 # Trim padding (modem pads to block size)
-                modem_decrypted = modem_decrypted[:len(plaintext)]
+                modem_decrypted = modem_decrypted[: len(plaintext)]
                 print(f"Modem decrypted: {modem_decrypted}")
 
                 if modem_decrypted == plaintext:
@@ -178,7 +178,7 @@ def test_modem_crypto(port: str = "/dev/cu.usbmodem1101"):
         # Decrypt with modem
         modem_decrypted2 = modem.decrypt_data(key, python_mac, python_ciphertext)
         if modem_decrypted2:
-            modem_decrypted2 = modem_decrypted2[:len(plaintext)]
+            modem_decrypted2 = modem_decrypted2[: len(plaintext)]
             print(f"Modem decrypted Python ciphertext: {modem_decrypted2}")
 
             if modem_decrypted2 == plaintext:

src/pymc_core/__init__.py

@@ -21,5 +21,17 @@
     "__version__",
 ]
 
+# Conditional import for CompanionRadio
+try:
+    from .companion.companion_radio import CompanionRadio
+
+    _COMPANION_AVAILABLE = True
+except ImportError:
+    _COMPANION_AVAILABLE = False
+    CompanionRadio = None
+
+if _COMPANION_AVAILABLE:
+    __all__.append("CompanionRadio")
+
 
 # End of mesh package exports

src/pymc_core/companion/__init__.py

@@ -0,0 +1,103 @@
+"""
+MeshCore Companion Radio - Python-native implementation.
+
+Provides contact management, messaging with offline queue, advertisement
+broadcasting, channel management, path tracking, signing, telemetry,
+statistics, and device configuration on top of MeshNode.
+"""
+
+from .channel_store import ChannelStore
+from .companion_bridge import CompanionBridge
+from .companion_radio import CompanionRadio
+from .constants import (
+    ADV_TYPE_CHAT,
+    ADV_TYPE_REPEATER,
+    ADV_TYPE_ROOM,
+    ADV_TYPE_SENSOR,
+    ADVERT_LOC_NONE,
+    ADVERT_LOC_SHARE,
+    AUTOADD_CHAT,
+    AUTOADD_OVERWRITE_OLDEST,
+    AUTOADD_REPEATER,
+    AUTOADD_ROOM,
+    AUTOADD_SENSOR,
+    DEFAULT_MAX_CHANNELS,
+    DEFAULT_MAX_CONTACTS,
+    DEFAULT_OFFLINE_QUEUE_SIZE,
+    MSG_SEND_FAILED,
+    MSG_SEND_SENT_DIRECT,
+    MSG_SEND_SENT_FLOOD,
+    STATS_TYPE_CORE,
+    STATS_TYPE_PACKETS,
+    STATS_TYPE_RADIO,
+    TELEM_MODE_ALLOW_ALL,
+    TELEM_MODE_ALLOW_FLAGS,
+    TELEM_MODE_DENY,
+    TXT_TYPE_CLI_DATA,
+    TXT_TYPE_PLAIN,
+    TXT_TYPE_SIGNED_PLAIN,
+    BinaryReqType,
+)
+from .contact_store import ContactStore
+from .frame_server import CompanionFrameServer
+from .message_queue import MessageQueue
+from .models import AdvertPath, Channel, Contact, NodePrefs, PacketStats, QueuedMessage, SentResult
+from .path_cache import PathCache
+from .stats_collector import StatsCollector
+
+__all__ = [
+    # Main classes
+    "CompanionRadio",
+    "CompanionBridge",
+    "CompanionFrameServer",
+    # Stores
+    "ContactStore",
+    "ChannelStore",
+    "MessageQueue",
+    "PathCache",
+    "StatsCollector",
+    # Models
+    "Contact",
+    "Channel",
+    "NodePrefs",
+    "SentResult",
+    "PacketStats",
+    "AdvertPath",
+    "QueuedMessage",
+    # ADV Types
+    "ADV_TYPE_CHAT",
+    "ADV_TYPE_REPEATER",
+    "ADV_TYPE_ROOM",
+    "ADV_TYPE_SENSOR",
+    # Text Types
+    "TXT_TYPE_PLAIN",
+    "TXT_TYPE_CLI_DATA",
+    "TXT_TYPE_SIGNED_PLAIN",
+    # Telemetry Modes
+    "TELEM_MODE_DENY",
+    "TELEM_MODE_ALLOW_FLAGS",
+    "TELEM_MODE_ALLOW_ALL",
+    # Location Policy
+    "ADVERT_LOC_NONE",
+    "ADVERT_LOC_SHARE",
+    # Auto-Add Config
+    "AUTOADD_OVERWRITE_OLDEST",
+    "AUTOADD_CHAT",
+    "AUTOADD_REPEATER",
+    "AUTOADD_ROOM",
+    "AUTOADD_SENSOR",
+    # Message Send Result
+    "MSG_SEND_FAILED",
+    "MSG_SEND_SENT_FLOOD",
+    "MSG_SEND_SENT_DIRECT",
+    # Binary request types
+    "BinaryReqType",
+    # Stats Types
+    "STATS_TYPE_CORE",
+    "STATS_TYPE_RADIO",
+    "STATS_TYPE_PACKETS",
+    # Defaults
+    "DEFAULT_MAX_CONTACTS",
+    "DEFAULT_MAX_CHANNELS",
+    "DEFAULT_OFFLINE_QUEUE_SIZE",
+]

src/pymc_core/companion/binary_parsing.py

@@ -0,0 +1,150 @@
+"""Parse binary response payloads by request type (BinaryReqType)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from .constants import BinaryReqType
+
+logger = logging.getLogger(__name__)
+
+
+def parse_binary_response(
+    request_type: int,
+    data: bytes,
+    pubkey_prefix: str = "",
+    context: Optional[dict] = None,
+) -> Optional[dict]:
+    """Parse response_data by request_type. Returns dict or None."""
+    if request_type == BinaryReqType.STATUS and len(data) >= 52:
+        return _parse_status(data, pubkey_prefix=pubkey_prefix or None)
+    if request_type == BinaryReqType.TELEMETRY and len(data) >= 0:
+        return _parse_telemetry(data)
+    if request_type == BinaryReqType.MMA and len(data) >= 4:
+        return _parse_mma(data[4:])  # skip 4-byte header
+    if request_type == BinaryReqType.ACL:
+        return _parse_acl(data)
+    if request_type == BinaryReqType.NEIGHBOURS:
+        return _parse_neighbours(data, context or {})
+    if request_type == BinaryReqType.OWNER_INFO and len(data) >= 4:
+        return _parse_owner_info(data)
+    return {"raw_hex": data.hex(), "request_type": request_type}
+
+
+def _parse_status(data: bytes, pubkey_prefix: Optional[str] = None, offset: int = 0) -> dict:
+    """Parse status response (52 bytes)."""
+    res = {}
+    if pubkey_prefix is None and len(data) >= 8:
+        res["pubkey_pre"] = data[2:8].hex()
+        offset = 8
+    else:
+        res["pubkey_pre"] = pubkey_prefix or ""
+    res["bat"] = int.from_bytes(data[offset : offset + 2], byteorder="little")
+    res["tx_queue_len"] = int.from_bytes(data[offset + 2 : offset + 4], byteorder="little")
+    res["noise_floor"] = int.from_bytes(
+        data[offset + 4 : offset + 6], byteorder="little", signed=True
+    )
+    res["last_rssi"] = int.from_bytes(
+        data[offset + 6 : offset + 8], byteorder="little", signed=True
+    )
+    res["nb_recv"] = int.from_bytes(data[offset + 8 : offset + 12], byteorder="little")
+    res["nb_sent"] = int.from_bytes(data[offset + 12 : offset + 16], byteorder="little")
+    res["airtime"] = int.from_bytes(data[offset + 16 : offset + 20], byteorder="little")
+    res["uptime"] = int.from_bytes(data[offset + 20 : offset + 24], byteorder="little")
+    res["sent_flood"] = int.from_bytes(data[offset + 24 : offset + 28], byteorder="little")
+    res["sent_direct"] = int.from_bytes(data[offset + 28 : offset + 32], byteorder="little")
+    res["recv_flood"] = int.from_bytes(data[offset + 32 : offset + 36], byteorder="little")
+    res["recv_direct"] = int.from_bytes(data[offset + 36 : offset + 40], byteorder="little")
+    res["full_evts"] = int.from_bytes(data[offset + 40 : offset + 42], byteorder="little")
+    res["last_snr"] = (
+        int.from_bytes(data[offset + 42 : offset + 44], byteorder="little", signed=True) / 4
+    )
+    res["direct_dups"] = int.from_bytes(data[offset + 44 : offset + 46], byteorder="little")
+    res["flood_dups"] = int.from_bytes(data[offset + 46 : offset + 48], byteorder="little")
+    res["rx_airtime"] = int.from_bytes(data[offset + 48 : offset + 52], byteorder="little")
+    return res
+
+
+def _parse_telemetry(data: bytes) -> dict:
+    """Telemetry: Cayenne LPP or raw. Dict has raw_hex; optional LPP if cayennelpp available."""
+    out: dict = {"raw_hex": data.hex()}
+    try:
+        from cayennelpp import LppFrame
+
+        frame = LppFrame.from_bytes(data)
+        out["lpp"] = [
+            {"channel": d.channel, "type": d.type_id, "value": d.data} for d in frame.data
+        ]
+    except Exception:
+        logger.debug("Optional LPP parse failed for telemetry", exc_info=True)
+    return out
+
+
+def _parse_mma(data: bytes) -> dict:
+    """MMA: LPP min/max/avg or raw."""
+    out: dict = {"raw_hex": data.hex()}
+    try:
+        from cayennelpp import LppFrame
+
+        frame = LppFrame.from_bytes(data)
+        out["mma"] = [{"channel": d.channel, "type": d.type_id, "data": d.data} for d in frame.data]
+    except Exception:
+        logger.debug("Optional LPP parse failed for MMA", exc_info=True)
+    return out
+
+
+def _parse_owner_info(data: bytes) -> dict:
+    """Parse GET_OWNER_INFO response: tag(4) + 'version\\nname\\nowner' (variable)."""
+    try:
+        text = data[4:].decode("utf-8", errors="replace").strip()
+        parts = text.split("\n", 2)
+        return {
+            "tag": int.from_bytes(data[:4], "little"),
+            "version": parts[0] if len(parts) > 0 else "",
+            "node_name": parts[1] if len(parts) > 1 else "",
+            "owner_info": parts[2] if len(parts) > 2 else "",
+            "raw_text": text,
+        }
+    except Exception:
+        logger.debug("Owner info parse failed, returning fallback", exc_info=True)
+        return {"raw_hex": data.hex(), "request_type": BinaryReqType.OWNER_INFO}
+
+
+def _parse_acl(buf: bytes) -> dict:
+    """ACL: 7-byte entries (key 6 + perm 1)."""
+    res = []
+    i = 0
+    while i + 7 <= len(buf):
+        key = buf[i : i + 6].hex()
+        perm = buf[i + 6]
+        if key != "000000000000":
+            res.append({"key": key, "perm": perm})
+        i += 7
+    return {"acl": res}
+
+
+def _parse_neighbours(data: bytes, context: dict) -> dict:
+    """Neighbours: count(2) + results_count(2) + entries (pubkey_prefix + secs_ago(4) + snr(1))."""
+    if len(data) < 4:
+        return {"raw_hex": data.hex()}
+    pk_plen = context.get("pubkey_prefix_length", 6)
+    neighbours_count = int.from_bytes(data[0:2], "little", signed=True)
+    results_count = int.from_bytes(data[2:4], "little", signed=True)
+    neighbours_list = []
+    i = 4
+    for _ in range(results_count):
+        if i + pk_plen + 4 + 1 > len(data):
+            break
+        pubkey = data[i : i + pk_plen].hex()
+        i += pk_plen
+        secs_ago = int.from_bytes(data[i : i + 4], "little", signed=True)
+        i += 4
+        snr = int.from_bytes(data[i : i + 1], "little", signed=True) / 4
+        i += 1
+        neighbours_list.append({"pubkey": pubkey, "secs_ago": secs_ago, "snr": snr})
+    return {
+        "neighbours_count": neighbours_count,
+        "results_count": results_count,
+        "neighbours": neighbours_list,
+    }