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:

```bash
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

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

### 2. Clone / Copy This Directory to the Pi

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

### 3. Run the Installer

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

```bash
sudo systemctl edit --full kosmo-bridge
```

Update the `Environment=` lines, for example:

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

```bash
sudo systemctl daemon-reload
sudo systemctl restart kosmo-bridge
```

### 5. Monitor Logs

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

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

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

```bash
nmap -p 4403 192.168.1.0/24
```

### 3. Run the Bridge in TCP Mode

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