diff --git a/README.md b/README.md index 0c6913b..753c2c6 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ home/ # kitchenowl, donetick, shlink, qui, dakboard bridges, doris-da dev/ # gitea, rackpeek ai/ # ollama, openwebui headscale/ # pilot self-hosted tailnet control plane + Headplane UI on PD -meshtastic/ # meshmonitor, mqtt-proxy, tileserver, meshtastic-map +meshtastic/ # meshmonitor, tileserver, meshtastic-map, and MeshCore/MeshMonitor integration notes automation/ # planned: gotify, n8n search/ # planned: qdrant docs/ # all homelab documentation diff --git a/docs/architecture/SERVICES_DIRECTORY.md b/docs/architecture/SERVICES_DIRECTORY.md index 4e73d23..579f958 100644 --- a/docs/architecture/SERVICES_DIRECTORY.md +++ b/docs/architecture/SERVICES_DIRECTORY.md @@ -2,7 +2,7 @@ All homelab services, their hosts, ports, and current status. -*Last updated: 2026-05-27* +*Last updated: 2026-06-13* ## Shared Databases (PD) @@ -100,7 +100,7 @@ OpenClaw is no longer treated as an active PD service in the operator inventory. | Service | Host | Port | Status | |---------|------|------|--------| -| MeshCore to MQTT relay | N.O.M.A.D. (10.5.30.7) | outbound MQTT only | ✅ Running as Docker container `mctomqtt` (`mctomqtt:latest`); config bind-mounted from `/etc/mctomqtt` | +| MeshCore companion observer | N.O.M.A.D. (10.5.30.7) | outbound MQTT only | ✅ Running as systemd service `meshcore-capture`; install root `/home/fizzlepoof/.meshcore-packet-capture`; direct serial connection to the Heltec companion node | ## Local file intake diff --git a/docs/reference/MESHTASTIC.md b/docs/reference/MESHTASTIC.md index ed11fe6..6af4aad 100644 --- a/docs/reference/MESHTASTIC.md +++ b/docs/reference/MESHTASTIC.md @@ -1,9 +1,14 @@ # Meshtastic Stack ## Overview -Self-hosted Meshtastic monitoring and management stack running on PlausibleDeniability. +Self-hosted MeshMonitor stack running on PlausibleDeniability, plus the current operator note for the separate NOMAD-side MeshCore companion observer. -Related NOMAD-side bridge note: a separate MeshCore-to-MQTT relay is running on N.O.M.A.D. as Docker container `mctomqtt` (`mctomqtt:latest`), with config bind-mounted from `/etc/mctomqtt`. The package also includes a systemd unit under `/opt/mctomqtt`, but that is not the active runtime on this host. +Related NOMAD-side bridge note: the legacy `mctomqtt` Docker relay was retired on 2026-06-13. N.O.M.A.D. now uses the LetsMesh companion observer flow via `meshcore-capture.service`, running from `/home/fizzlepoof/.meshcore-packet-capture` and connecting directly to the Heltec over `/dev/serial/by-id/...`. + +Important split: +- **PD** hosts the MeshMonitor web/UI stack. +- **NOMAD** owns the USB-attached Heltec companion observer via `meshcore-capture.service`. +- Do not assume MeshMonitor and the companion observer are the same runtime path. ## Stack Location `/mnt/docker-ssd/docker/compose/meshtastic/` @@ -12,29 +17,32 @@ Related NOMAD-side bridge note: a separate MeshCore-to-MQTT relay is running on | Container | Image | Port | Purpose | |-----------|-------|------|---------| -| meshmonitor | ghcr.io/yeraze/meshmonitor:4.2.0 | 8081→3001 | Main UI + backend | -| meshmonitor (virtual node) | — | 4404 | TCP virtual node server | -| meshmonitor-tileserver | maptiler/tileserver-gl-light | 8082→8080 | Offline map tiles | -| meshmonitor-mqtt-proxy | ghcr.io/ln4cy/mqtt-proxy:master | — | MQTT→TCP bridge | +| meshmonitor | ghcr.io/yeraze/meshmonitor:latest | 8081→3001, 4404→4404 | Main UI + backend; live compose publishes the virtual-node port directly from this container | +| meshmonitor (virtual node) | — | 4404 | TCP virtual node server exposed directly by the meshmonitor container | +| meshmonitor-tileserver | maptiler/tileserver-gl-light:latest | 8082→8080 | Offline map tiles | | meshmonitor-upgrader | docker:latest | — | Auto-upgrade watchdog | +Live runtime verified on 2026-06-13: +- `docker compose ps` on PD showed `meshmonitor`, `meshmonitor-tileserver`, and `meshmonitor-upgrader` running. +- Repo compose and live runtime now agree that there is no separate `meshmonitor-mqtt-proxy` sidecar in the active stack. + ## Architecture ``` -Meshtastic Node (10.5.1.172) - ↓ MQTT -meshmonitor-mqtt-proxy - ↓ TCP (port 4404) -meshmonitor virtual node server - ↓ -meshmonitor backend +Trusted-LAN mesh node (10.5.1.120) + ↓ direct node connection configured by MESHTASTIC_NODE_IP +meshmonitor backend on PD ↓ PostgreSQL (shared-postgres, db: meshmonitor) + +Separate path: +NOMAD Heltec companion observer (`meshcore-capture.service`) + ↓ upstream MQTT brokers (LetsMesh US / EU + NashMe) ``` ## Node Connection -- Node IP: `10.5.1.172` -- Connection type: MQTT via mqtt-proxy (not direct TCP) -- mqtt-proxy connects to meshmonitor's virtual node server on port 4404 +- PD MeshMonitor compose is currently configured with `MESHTASTIC_NODE_IP=10.5.1.120` +- MeshMonitor itself publishes port `4404` for the virtual-node path; there is no separate `meshmonitor-mqtt-proxy` service in the active stack +- NOMAD's companion observer is a different ingest path and should not be documented as a MeshMonitor sidecar ## Storage - Appdata: `/mnt/tank/docker/appdata/meshmonitor/data` → `/data` @@ -60,7 +68,7 @@ mkdir -p /mnt/docker-ssd/docker/compose/meshtastic/scripts ## Known Warnings - Node `!dd972536` has a low-entropy public key — this is a device configuration issue, not a meshmonitor bug -- Frequent connect/disconnect cycles in logs are normal when the MQTT proxy reconnects +- MeshMonitor logs can still show noisy reconnect/admin-session churn during node or radio instability; do not confuse that with the retired NOMAD `mctomqtt` path ## Tiles Map tiles stored in `./tiles/`. Currently includes `zurich_switzerland.mbtiles` (34MB). @@ -68,5 +76,4 @@ Tiles directory is gitignored. To add new tiles, download `.mbtiles` files and p ## TODO - [ ] Document all running meshtastic-map container config -- [ ] Document meshtastic-map-mosquitto and meshtastic-mqtt containers - [ ] Add healthcheck to meshmonitor container diff --git a/docs/servers/NOMAD.md b/docs/servers/NOMAD.md index 83e3035..62277fa 100644 --- a/docs/servers/NOMAD.md +++ b/docs/servers/NOMAD.md @@ -226,43 +226,26 @@ These are expected to be managed by Wings/Pelican rather than a local compose fi - Sorter service: `minerva-localsend-autosort.service` - Sorter script: `/home/fizzlepoof/.local/bin/minerva-localsend-autosort.py` -### MeshCore to MQTT relay -- Install date: 2026-05-18 -- Install root: `/opt/mctomqtt` -- Config root: `/etc/mctomqtt` -- Service account: `mctomqtt:mctomqtt` -- Installer metadata: `.version_info` reports `installer_version: 1.3.0.0-preview`, repo `Cisien/meshcoretomqtt`, branch `main`, commit `10f7c0e` -- Detected install type marker: `/opt/mctomqtt/.install_type` contains `docker` -- Runtime model: - - Active runtime is a standalone Docker container named `mctomqtt` - - Image: `mctomqtt:latest` - - Command: `python3 /opt/mctomqtt/mctomqtt.py` - - User: `mctomqtt` - - Restart policy: `unless-stopped` - - Network mode: `bridge` - - Config bind mount: `/etc/mctomqtt:/etc/mctomqtt:ro` - - Device passthrough: the Heltec serial device is mapped directly into the container at the same `/dev/serial/by-id/... ` path -- Systemd note: - - The packaged repo also includes `/opt/mctomqtt/mctomqtt.service`, but it is not the active runtime on NOMAD - - No installed unit was present in `/etc/systemd/system` or `/lib/systemd/system` - - The bundled unit expects `/opt/mctomqtt/venv/bin/python3`, but no `venv/` directory exists under `/opt/mctomqtt` - - Treat the systemd unit as an unused package artifact for this host unless the deployment model changes later -- Config layering: - - Base reference: `/etc/mctomqtt/config.toml` - - Preset overlay: `/etc/mctomqtt/config.d/10-meshmapper.toml` - - Local overrides: `/etc/mctomqtt/config.d/99-user.toml` -- Current local overrides observed: - - IATA region code set to `BNA` - - Serial device pinned to `/dev/serial/by-id/usb-Espressif_Systems_heltec_wifi_lora_32_v4__16_MB_FLASH__2_MB_PSRAM__441BF670B684-if00` - - Enabled broker targets include MeshMapper, LetsMesh US, and NashMe - - Credentials/secrets are stored inline in `99-user.toml`; do not mirror them into git-backed docs -- Container health observed during inspection: - - Logs show the relay loading all three config layers, opening the Heltec serial device, and connecting successfully to MeshMapper, NashMe, and LetsMesh US after restart - - The current container had been up about 5 minutes during inspection with `MQTT: 3/3`, zero failures, and live RX air-time reported - - An earlier start logged one DNS resolution failure for a broker label shown as `custom-2`, but the current running container recovered and all three named brokers connected cleanly -- Container logs / inspection: - - Use `docker logs mctomqtt` for runtime output - - Use `docker inspect mctomqtt` for bind mounts, device mappings, and restart policy +### MeshCore companion observer +- Current runtime: `meshcore-capture.service` (systemd) +- Install root: `/home/fizzlepoof/.meshcore-packet-capture` +- Service unit: `/etc/systemd/system/meshcore-capture.service` +- Runtime command: `/home/fizzlepoof/.meshcore-packet-capture/venv/bin/python3 /home/fizzlepoof/.meshcore-packet-capture/packet_capture.py` +- Connection mode: direct serial on the Heltec via `/dev/serial/by-id/usb-Espressif_Systems_heltec_wifi_lora_32_v4__16_MB_FLASH__2_MB_PSRAM__441BF670B684-if00` +- Observer role: + - NOMAD now uses the LetsMesh companion observer flow instead of the legacy `mctomqtt` relay + - The companion process connects to the Heltec locally, signs JWTs on-device, and publishes packet capture data upstream to MQTT brokers +- Service health observed on 2026-06-13: + - `systemctl status meshcore-capture` shows the service active/running + - Logs confirm successful serial connection to device name `Peachtree Mesh Monitor` + - Logs confirm MQTT connectivity to LetsMesh US, LetsMesh EU, and NashMe + - Packet capture mode is enabled and waiting for packets +- Initial-start caveat: + - One installer-start attempt failed with `No such file or directory` for the `/dev/serial/by-id/...` path + - A subsequent manual `systemctl start meshcore-capture` succeeded once the device path was present again +- Legacy relay retirement: + - The old standalone Docker container `mctomqtt` was retired on 2026-06-13 + - Backup of the retired relay files/config was saved under `/home/fizzlepoof/private/backups/mctomqtt-retire/20260613-174536` - Documentation linkage: - Related mesh stack notes live in [MESHTASTIC.md](../reference/MESHTASTIC.md) diff --git a/meshtastic/docker-compose.yaml b/meshtastic/docker-compose.yaml index 2e4f1cb..f256d6b 100644 --- a/meshtastic/docker-compose.yaml +++ b/meshtastic/docker-compose.yaml @@ -68,28 +68,6 @@ services: networks: - default - pangolin - mqtt-proxy: - image: ghcr.io/ln4cy/mqtt-proxy:master - container_name: meshmonitor-mqtt-proxy - restart: unless-stopped - environment: - - INTERFACE_TYPE=tcp - - TCP_NODE_HOST=meshmonitor - - TCP_NODE_PORT=4404 - - LOG_LEVEL=INFO - - TCP_TIMEOUT=300 - - CONFIG_WAIT_TIMEOUT=60 - - HEALTH_CHECK_ACTIVITY_TIMEOUT=300 - depends_on: - - meshmonitor - healthcheck: - test: ["CMD-SHELL", "test -f /tmp/healthy && find /tmp/healthy -mmin -1 | grep -q healthy"] - interval: 30s - timeout: 10s - retries: 3 - start_period: 60s - networks: - - default networks: ix-databases_shared-databases: external: true