Minimal NestJS bot for Meshtastic. Long-running service that TCP-connects to a Meshtastic serial bridge (raw socat pipe) at 192.168.1.4:4403, sends want_config_id on connect so the firmware streams its initial sync data, parses inbound protobuf frames, logs received text messages, and exposes HTTP endpoints to send text.

Local run

npm i
npm run start:dev

Docker

docker compose up -d --build

Exposed via Traefik only (no published ports) at http://bot.dev.kkhost.pl.

Endpoints

All API endpoints live under the /api prefix:

GET /api/status — { connected, myNodeNum, host, port }
POST /api/send — body { "text": "...", "to"?: <node number | node name | "!b" | "broadcast"> }, returns { id }. Numbers pass through as-is (integer in 1..0xffffffff); names resolve like GET /api/nodes/:id (exact long/short name, then unique substring) — unknown or ambiguous targets are a 400
GET /api/channels — the device's Meshtastic channels as { index, name, uplinkEnabled, downlinkEnabled }[] (psk/keys are redacted; empty until the initial sync completes)
GET /api/messages — message history, newest first: inbound text (dir:'rx', with from) and our sends (dir:'tx', with to + status). tx records start pending and move to delivered/failed (with human-readable ackError) when the routing ACK/NACK arrives; broadcasts stay pending because firmware strips want_ack before TX. In-memory only, last 100, reset on every bridge reconnect
GET /api/nodes — known mesh nodes as { num, longName?, shortName?, hwModel?, batteryLevel?, lastHeard: number|null, position?: { lat, lon, alt? } }[], sorted by node number. Collected during the initial sync plus live position updates; names/hwModel/battery appear only when reported, lastHeard is epoch seconds (null = never heard), and position only when both coordinates are known
GET /api/nodes/:id — one node looked up by exact node number (numbers or numeric strings), then case-insensitive exact long/short name, else the unique case-insensitive substring match; 404 when nothing or more than one node matches

Interactive API docs (Scalar) are served at /, with the OpenAPI JSON at /docs-json.

curl http://localhost:3000/api/status
curl -X POST http://localhost:3000/api/send -H 'content-type: application/json' -d '{"text":"hi"}'
curl -X POST http://localhost:3000/api/send -H 'content-type: application/json' -d '{"to":123456789,"text":"hello"}'
curl http://localhost:3000/api/channels
curl http://localhost:3000/api/messages
curl http://localhost:3000/api/nodes
curl http://localhost:3000/api/nodes/kamil

to omitted, "!b", or "broadcast" (case-insensitive) sends to the broadcast address 0xffffffff; anything else is a node number or name. DMs are unicast and wantAck-tracked via GET /api/messages; broadcasts stay pending because firmware strips want_ack before TX.

All sends always target channel index 2 (testowy) — never the primary channel. Override with MESH_SEND_CHANNEL.

Env vars

MESH_HOST (default 192.168.1.4) — bridge host
MESH_PORT (default 4403) — bridge port
MESH_RECONNECT_MS (default 5000) — reconnect interval in ms
MESH_SEND_CHANNEL (default 2) — channel index all sends target (testowy; never the primary channel)
PORT (default 3000) — HTTP listen port

Note: the serial bridge accepts only ONE client at a time — if another app is connected to the radio, this bot will not get a connection.