kosmo-connect/firmware/infrastructure-node/bridge-daemon/README.md

KosmoConnect Bridge Daemon

A Python daemon that bridges a local Meshtastic mesh network to the KosmoConnect cloud MQTT broker.

What It Does

1. Mesh → Cloud

   • Receives text messages from the mesh and publishes them to kosmo/mesh/inbound
   • Detects JSON environmental data packets (sent as text) and forwards them to kosmo/ingest/enviro
   • Forwards position updates to kosmo/position/position
   • (Future) Will handle custom KOSMO_ENVIRO_APP portnum packets from enviro-node firmware

2. Cloud → Mesh

   • Subscribes to kosmo/mesh/outbound/#
   • Injects text messages into the mesh, tagged with [Web] prefix so users know the origin

Hardware Requirements

• Raspberry Pi (3B+ or 4 recommended) running Raspberry Pi OS or similar Debian-based Linux
• Meshtastic device with USB-serial interface (e.g., LILYGO T-Beam, RAK4631, or your T-Deck in USB-serial mode) connected via USB
• Reliable internet backhaul (WiFi or Ethernet)

Quick Start (Local Dev)

You can test the daemon on your laptop without a Pi by using the Mosquitto broker from the backend stack:

cd firmware/infrastructure-node/bridge-daemon
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Option A: USB serial device
export MESHTASTIC_DEVICE=/dev/ttyUSB0   # or /dev/ttyACM0 on Linux, COM3 on Windows, /dev/cu.usbserial-* on macOS
export MQTT_HOST=localhost
export MQTT_PORT=1883
python3 -m src.main

# Option B: Network-connected device (e.g., T-Deck on WiFi)
export MESHTASTIC_HOST=192.168.1.45
export MESHTASTIC_TCP_PORT=4403
export MQTT_HOST=localhost
export MQTT_PORT=1883
python3 -m src.main

Raspberry Pi Production Setup

1. Install Dependencies

sudo apt update
sudo apt install -y python3-venv python3-pip git

2. Clone / Copy This Directory to the Pi

cd /opt
sudo git clone https://your-repo/kosmo-connect.git
# or rsync the bridge-daemon folder

3. Run the Installer

cd /opt/kosmo-connect/firmware/infrastructure-node/bridge-daemon
sudo ./install.sh

4. Configure the Service

Edit the systemd service to point to your actual MQTT broker:

sudo systemctl edit --full kosmo-bridge

Update the Environment= lines, for example:

Environment="MQTT_HOST=your-broker.example.com"
Environment="MQTT_PORT=1883"
Environment="MQTT_USER=kosmo"
Environment="MQTT_PASS=your_secure_password"
Environment="MESHTASTIC_DEVICE=/dev/ttyUSB0"
Environment="GATEWAY_NODE_ID=!yourgateway01"

Save and reload:

sudo systemctl daemon-reload
sudo systemctl restart kosmo-bridge

5. Monitor Logs

sudo journalctl -u kosmo-bridge -f

Environment Variables

Variable	Default	Description
MQTT_HOST	localhost	MQTT broker hostname
MQTT_PORT	1883	MQTT broker port
MQTT_USER	(empty)	MQTT username
MQTT_PASS	(empty)	MQTT password
MESHTASTIC_DEVICE	/dev/ttyUSB0	Serial path to the Meshtastic radio (used when MESHTASTIC_HOST is empty)
MESHTASTIC_HOST	(empty)	IP address or hostname of a network-connected Meshtastic device
MESHTASTIC_TCP_PORT	4403	TCP port for the Meshtastic network API
GATEWAY_NODE_ID	(empty)	Identifier for this bridge in the cloud

Finding the Serial Port

On the Pi, plug in your T-Beam or T-Deck and run:

ls -l /dev/ttyUSB* /dev/ttyACM* /dev/serial/by-id/

Use the path that appears when the device is connected.

Using T-Deck Over WiFi (No USB Cable)

Your T-Deck can connect to your home WiFi and expose the Meshtastic TCP API on port 4403.

1. Enable WiFi on the T-Deck

Using the Meshtastic app or CLI:

meshtastic --host <t-deck-ip> --set wifi_ssid "YourNetwork" --set wifi_psk "YourPassword"

Or via the on-screen menu if your T-Deck firmware supports it.

2. Find the T-Deck IP Address

Check your router's DHCP client list, or use a network scanner:

nmap -p 4403 192.168.1.0/24

3. Run the Bridge in TCP Mode

export MESHTASTIC_HOST=192.168.1.45
export MESHTASTIC_TCP_PORT=4403
export MQTT_HOST=your-broker.example.com
python3 -m src.main

The bridge will connect over TCP instead of USB-serial. This is perfect for keeping the T-Deck portable while the Pi sits near your router.

Testing with T-Deck

When the bridge is running (serial or TCP):

1. Send a text message from any mesh node
2. Check kosmo/mesh/inbound on your MQTT broker — the message should appear within seconds
3. Publish a message to kosmo/mesh/outbound/!{target_node_id} — the target node should receive it prefixed with [Web]

Troubleshooting

• Permission denied on /dev/ttyUSB0: Add the kosmo user to the dialout group:

  sudo usermod -a -G dialout kosmo
  sudo systemctl restart kosmo-bridge
  

• MQTT connection refused: Verify your broker is reachable from the Pi (nc -vz MQTT_HOST MQTT_PORT)
• Meshtastic device not found over serial: Check cables and power supply; some devices need a powered USB hub on the Pi
• T-Deck TCP connection refused: Ensure the T-Deck is on the same network and the TCP API port (4403) is not blocked by a firewall