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 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:

   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.