feat: update documentation and configuration for enhanced MeshCore Companion support

README.md

@@ -13,7 +13,7 @@ This bridge enables interoperability, allowing messages, sensor data (with appro
 - **Multiple External Transports:** Supports connecting to the external system via:  
   - **Direct Serial:** Interfaces directly with devices (like MeshCore) via standard RS-232/USB serial ports.  
   - **MQTT:** Connects to an MQTT broker to exchange messages with IoT platforms or other MQTT clients.  
-- **Configurable Serial Protocol:** Supports different serial communication protocols via `config.ini`. Includes a `raw_serial` handler specifically for MeshCore Companion Mode (Binary).  
+- **Configurable Serial Protocol:** Supports different serial communication protocols via `config.ini`. Includes `raw_serial` and `companion_radio` handlers for MeshCore Companion Mode (Binary + framed USB protocol).  
 - **Robust Connection Management:** Automatically attempts to reconnect if connections are lost.
 
 ### Enhanced Features
@@ -49,6 +49,7 @@ Copy `examples/config.ini.example` to `config.ini` and edit it.
   - `COMPANION_HANDSHAKE_ENABLED = True` (send initial device query/app start)
   - `COMPANION_CONTACTS_POLL_S = 0` (poll contacts/adverts; 0 disables)
   - `COMPANION_DEBUG = False` (enable raw byte logging)
+  - `SERIAL_AUTO_SWITCH = True` (auto-switch between `json_newline` and `raw_serial` on repeated decode failures)
 
 - **For MQTT:**  
   Set `EXTERNAL_TRANSPORT = mqtt` and configure broker details. Optionally enable TLS/SSL for secure connections.
@@ -66,7 +67,7 @@ Copy `examples/config.ini.example` to `config.ini` and edit it.
   python run_bridge_async.py
 
 The async entry point supports:
-  - Async Meshcore integration (meshcore_py)
+  - Async Meshcore integration (meshcore_py) with `CONTACT_MSG_RECV` and `CHANNEL_MSG_RECV` subscriptions
   - Async MQTT (asyncio-mqtt)
   - Async REST API (FastAPI, if enabled)
 

docs/configuration.md

@@ -1,6 +1,6 @@
 # Configuration Guide
 
-**Last Updated: December 31, 2025**
+**Last Updated: February 7, 2026**
 
 The Akita Meshtastic Meshcore Bridge (AMMB) uses a configuration file named `config.ini` located in the project's root directory. Copy `examples/config.ini.example` to `config.ini` and modify it according to your setup.
 
@@ -52,9 +52,16 @@ These settings are only used when `EXTERNAL_TRANSPORT = serial`.
     * **Supported Values:**
         * `json_newline`: Messages are newline-terminated UTF-8 JSON strings (default for structured data)
         * `raw_serial`: Raw binary/text bytes forwarded as hex (for MeshCore Companion Mode)
+        * `companion_radio`: MeshCore Companion USB framing protocol (for MeshCore radios)
     * **Required:** Yes (when using serial transport)
     * **Default:** `json_newline`
 
+* **`SERIAL_AUTO_SWITCH`**
+    * **Description:** Automatically switches between `json_newline` and `raw_serial` after repeated decode failures.
+    * **Values:** `True`, `False`
+    * **Required:** No
+    * **Default:** `True`
+
 ### MQTT Transport Settings
 
 These settings are only used when `EXTERNAL_TRANSPORT = mqtt`.

examples/config.ini.example

@@ -40,7 +40,12 @@ SERIAL_BAUD_RATE = 9600
 #                 (Use this if your device talks Text/JSON)
 #   raw_serial:   Reads raw binary/text bytes and forwards them as Hex.
 #                 (Use this for MeshCore Companion Mode or binary protocols)
-SERIAL_PROTOCOL = json_newline  # Use json_newline for text/JSON, raw_serial for binary/hex
+#   companion_radio: MeshCore Companion USB framing protocol (recommended for MeshCore radios)
+SERIAL_PROTOCOL = json_newline  # Use json_newline for text/JSON, raw_serial for binary/hex, companion_radio for MeshCore USB framing
+
+# Auto-switch between json_newline and raw_serial after repeated decode failures.
+# Set False to disable protocol auto-detection.
+SERIAL_AUTO_SWITCH = True
 
 
 # --- MQTT Transport Settings ---
@@ -107,6 +112,15 @@ MQTT_TLS_CA_CERTS =
 # Allow insecure TLS connections (not recommended for production)
 MQTT_TLS_INSECURE = False
 
+# --- MeshCore Companion Settings ---
+# Only applies when SERIAL_PROTOCOL = companion_radio
+# Send initial device query/app start on connect
+COMPANION_HANDSHAKE_ENABLED = True
+# Poll contacts/adverts periodically (0 disables polling)
+COMPANION_CONTACTS_POLL_S = 0
+# Enable raw byte logging for companion protocol
+COMPANION_DEBUG = False
+
 # --- Logging Settings ---
 
 # Logging level for console output. Controls verbosity.

requirements-dev.txt

@@ -6,5 +6,6 @@
 pytest>=7.0.0,<8.0.0
 pytest-cov>=4.0.0,<5.0.0
 pytest-mock>=3.10.0,<4.0.0
+pytest-asyncio>=0.23.0,<1.0.0
 flake8>=6.0.0,<7.0.0
 mypy>=1.0.0,<2.0.00