Akita-Meshtastic-Meshcore-Bridge/docs/usage.md

# Usage Guide

This guide explains how to run and interact with the Akita Meshtastic-Meshcore Bridge (AMMB).

## Prerequisites

Ensure you have completed the steps in the [Installation](README.md#installation) section of the main README, including:
1.  Cloning the repository.
2.  Setting up a Python virtual environment (recommended).
3.  Installing dependencies (`pip install -r requirements.txt`).
4.  Creating and configuring your `config.ini` file.

## Running the Bridge

1.  **Navigate to the project root directory** in your terminal or command prompt (the directory containing `run_bridge.py`).
2.  **Activate your virtual environment** (if you created one):
    * Linux/macOS: `source venv/bin/activate`
    * Windows: `.\venv\Scripts\activate`
3.  **Run the bridge script:**
    ```bash
    python run_bridge.py
    ```

## Expected Output

Upon successful startup, you should see log messages similar to this in your console:

YYYY-MM-DD HH:MM:SS,mmm - MainThread - INFO - utils - Starting Akita Meshtastic-Meshcore Bridge (Serial Refactor)YYYY-MM-DD HH:MM:SS,mmm - MainThread - INFO - config_handler - Configuration loaded successfully from config.iniYYYY-MM-DD HH:MM:SS,mmm - MainThread - INFO - utils - Logging level set to INFOYYYY-MM-DD HH:MM:SS,mmm - MainThread - INFO - bridge - Initializing AMMB...YYYY-MM-DD HH:MM:SS,mmm - MainThread - INFO - meshtastic_handler - Attempting connection to Meshtastic on /dev/ttyUSB0...YYYY-MM-DD HH:MM:SS,mmm - Meshtastic Input - INFO - meshtastic.serial_interface - Connected to radio... (Meshtastic connection details) ...YYYY-MM-DD HH:MM:SS,mmm - MainThread - INFO - meshtastic_handler - Connected to Meshtastic device. Node ID: 0xdeadbeef ('!deadbeef')YYYY-MM-DD HH:MM:SS,mmm - MainThread - INFO - meshtastic_handler - Meshtastic receive callback registered.YYYY-MM-DD HH:MM:SS,mmm - MainThread - INFO - meshcore_handler - Attempting connection to Meshcore on /dev/ttyS0 at 9600 baud...YYYY-MM-DD HH:MM:SS,mmm - MainThread - INFO - meshcore_handler - Connected to Meshcore device on /dev/ttyS0YYYY-MM-DD HH:MM:SS,mmm - MainThread - INFO - bridge - Starting handler threads...YYYY-MM-DD HH:MM:SS,mmm - MainThread - INFO - bridge - Bridge threads started. Running... (Press Ctrl+C to stop)
* The bridge will attempt to connect to both the Meshtastic and MeshCore devices based on your `config.ini`.
* If a connection fails initially (e.g., device not plugged in), it will log a warning or error and periodically retry in the background.
* Once running, it will log messages received and sent on both networks (depending on your `LOG_LEVEL`).

## Monitoring

* **Console Logs:** Keep an eye on the terminal where you ran `python run_bridge.py`. This is the primary way to see what the bridge is doing, including received messages, sent messages, connection attempts, and errors.
* **Log Level:** If you need more detailed information for troubleshooting, stop the bridge (`Ctrl+C`), edit `config.ini`, set `LOG_LEVEL = DEBUG`, and restart the bridge. Remember to set it back to `INFO` or `WARNING` for normal operation to avoid excessive output.

## Stopping the Bridge

* Press `Ctrl+C` in the terminal where the bridge is running.
* The bridge will detect this signal and attempt a graceful shutdown, closing connections and stopping threads. You should see shutdown messages in the log.

## Troubleshooting Common Issues

* **`Error connecting to Meshtastic device: [Errno 2] No such file or directory: '/dev/ttyUSB0'` (or similar)**
    * **Cause:** The specified `MESHTASTIC_SERIAL_PORT` in `config.ini` is incorrect, or the device is not connected/detected by the OS.
    * **Solution:** Verify the port name using `meshtastic --port list` or OS tools. Ensure the device is plugged in and drivers are installed. Check permissions (Linux users might need to be in the `dialout` group: `sudo usermod -a -G dialout $USER`).

* **`Error connecting to Meshcore device: [Errno 2] No such file or directory: '/dev/ttyS0'` (or similar)**
    * **Cause:** The specified `MESHCORE_SERIAL_PORT` in `config.ini` is incorrect, or the device is not connected/detected.
    * **Solution:** Verify the port name using OS tools. Ensure the device is plugged in and drivers are installed. Check permissions.

* **`serial.SerialException: Could not configure port: (5, 'Input/output error')` (or similar permission error)**
    * **Cause:** The user running the script doesn't have permission to access the serial port.
    * **Solution (Linux):** Add your user to the `dialout` group: `sudo usermod -a -G dialout $USER`. You may need to log out and log back in for the change to take effect.

* **No messages received from Meshcore / Gibberish received from Meshcore:**
    * **Cause 1:** Incorrect `MESHCORE_BAUD_RATE` in `config.ini`. It *must* match the MeshCore device's setting.
    * **Cause 2:** Incorrect `MESHCORE_PROTOCOL` selected, or the MeshCore device is not sending data in the expected format (e.g., sending plain text when `json_newline` is expected).
    * **Cause 3:** Wiring issue between the computer and the MeshCore device.
    * **Solution:** Verify baud rate. Verify the protocol setting and the actual data format being sent by MeshCore. Check physical connections. Use the `meshcore_simulator.py` example or another serial terminal program to test communication directly with the MeshCore device.

* **Messages dropped (`Queue is full` warnings):**
    * **Cause:** Messages are arriving faster than they can be sent out on the other network, or the destination network/device is unresponsive.
    * **Solution:** Investigate potential bottlenecks on the destination network. Consider increasing `MESSAGE_QUEUE_SIZE` in `config.ini` if temporary bursts are expected, but this won't solve underlying rate issues.

* **JSONDecodeError / UnicodeDecodeError:**
    * **Cause:** The bridge received data over the MeshCore serial port that was not valid JSON (when using `json_newline` protocol) or not valid UTF-8 text.
    * **Solution:** Ensure the MeshCore device is sending correctly formatted, UTF-8 encoded JSON strings, terminated by a newline. Check the `Meshcore RX: Received non-JSON data` or `Received non-UTF8 data` log messages for clues.