From f533362f8aa2b7a8fbf4e2d4769ee48e92280927 Mon Sep 17 00:00:00 2001 From: l5y <220195275+l5yth@users.noreply.github.com> Date: Tue, 16 Dec 2025 08:54:31 +0100 Subject: [PATCH] chore: update readme (#561) --- AGENTS.md | 4 ++++ README.md | 31 ++++++++++++++++++++++++------- 2 files changed, 28 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 07e5771..936e914 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,11 +17,15 @@ The repository splits runtime and ingestion logic. `web/` holds the Sinatra dash `data/` hosts the Python Meshtastic ingestor plus migrations and CLI scripts. API fixtures and end-to-end harnesses live in `tests/`. Dockerfiles and compose files support containerized workflows. +`matrix/` contains the Rust Matrix bridge; build with `cargo build --release` or `docker build -f matrix/Dockerfile .`, and keep bridge config under `matrix/Config.toml` when running locally. + ## Build, Test, and Development Commands Run dependency installs inside `web/`: `bundle install` for gems and `npm ci` for JavaScript tooling. Start the app with `cd web && API_TOKEN=dev ./app.sh` for local work or `bundle exec rackup -p 41447` when integrating elsewhere. Prep ingestion with `python -m venv .venv && pip install -r data/requirements.txt`; `./data/mesh.sh` streams from live radios. `docker-compose -f docker-compose.dev.yml up` brings up the full stack. +Container images publish via `.github/workflows/docker.yml` as `potato-mesh-{service}-linux-$arch` (`web`, `ingestor`, `matrix-bridge`), using the Dockerfiles in `web/`, `data/`, and `matrix/`. + ## Coding Style & Naming Conventions Use two-space indentation for Ruby and keep `# frozen_string_literal: true` at the top of new files. Keep Ruby classes/modules in `CamelCase`, filenames in `snake_case.rb`, and feature specs in `*_spec.rb`. diff --git a/README.md b/README.md index 035f304..b57c149 100644 --- a/README.md +++ b/README.md @@ -7,13 +7,20 @@ [![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/l5yth/potato-mesh/issues) [![Matrix Chat](https://img.shields.io/badge/matrix-%23potatomesh:dod.ngo-blue)](https://matrix.to/#/#potatomesh:dod.ngo) -A federated Meshtastic-powered node dashboard for your local community. _No MQTT clutter, just local LoRa aether._ +A federated, Meshtastic-powered node dashboard for your local community. +_No MQTT clutter, just local LoRa aether._ -* Web app with chat window and map view showing nodes, neighbors, telemetry, and messages. - * API to POST (authenticated) and to GET nodes and messages. - * Shows new node notifications (first seen) in chat. +* Web dashboard with chat window and map view showing nodes, positions, neighbors, + trace routes, telemetry, and messages. + * API to POST (authenticated) and to GET nodes, messages, and telemetry. + * Shows new node notifications (first seen) and telemetry logs in chat. * Allows searching and filtering for nodes in map and table view. + * Federated: _automatically_ froms a federation with other communities running + Potato Mesh! * Supplemental Python ingestor to feed the POST APIs of the Web app with data remotely. + * Supports multiple ingestors per instance. +* Matrix bridge that posts Meshtastic messages to a defined matrix channel (no + radio required). * Mobile app to _read_ messages on your local aether (no radio required). Live demo for Berlin #MediumFast: [potatomesh.net](https://potatomesh.net) @@ -58,6 +65,7 @@ RACK_ENV="production" \ APP_ENV="production" \ API_TOKEN="SuperSecureTokenReally" \ INSTANCE_DOMAIN="https://potatomesh.net" \ +MAP_CENTER="53.55,13.42" \ exec ruby app.rb -p 41447 -o 0.0.0.0 ``` @@ -68,6 +76,7 @@ exec ruby app.rb -p 41447 -o 0.0.0.0 * Provide a strong `API_TOKEN` value to authorize POST requests against the API. * Configure `INSTANCE_DOMAIN` with the public URL of your deployment so vanity links and generated metadata resolve correctly. +* Don't forget to set a `MAP_CENTER` to point to your local region. The web app can be configured with environment variables (defaults shown): @@ -134,7 +143,9 @@ The web app contains an API: * GET `/api/messages?limit=100&encrypted=false&since=0` - returns the latest 100 messages newer than the provided unix timestamp (defaults to `since=0` to return full history; disabled when `PRIVATE=1`) * GET `/api/telemetry?limit=100` - returns the latest 100 telemetry data * GET `/api/neighbors?limit=100` - returns the latest 100 neighbor tuples +* GET `/api/traces?limit=100` - returns the latest 100 trace-routes caught * GET `/api/instances` - returns known potato-mesh instances in other locations +* GET `/api/ingestors` - returns active potato-mesh python ingestors that feed data * GET `/metrics`- metrics for the prometheus endpoint * GET `/version`- information about the potato-mesh instance * POST `/api/nodes` - upserts nodes provided as JSON object mapping node ids to node data (requires `Authorization: Bearer `) @@ -142,6 +153,7 @@ The web app contains an API: * POST `/api/messages` - appends messages provided as a JSON object or array (requires `Authorization: Bearer `; disabled when `PRIVATE=1`) * POST `/api/telemetry` - appends telemetry provided as a JSON object or array (requires `Authorization: Bearer `) * POST `/api/neighbors` - appends neighbor tuples provided as a JSON object or array (requires `Authorization: Bearer `) +* POST `/api/traces` - appends caught traces routes provided as a JSON object or array (requires `Authorization: Bearer `) The `API_TOKEN` environment variable must be set to a non-empty value and match the token supplied in the `Authorization` header for `POST` requests. @@ -190,9 +202,7 @@ node records and parsing new incoming messages. Enable debug output with `DEBUG= specify the connection target with `CONNECTION` (default `/dev/ttyACM0`) or set it to an IP address (for example `192.168.1.20:4403`) to use the Meshtastic TCP interface. `CONNECTION` also accepts Bluetooth device addresses (e.g., -`ED:4D:9E:95:CF:60`) and the script attempts a BLE connection if available. The -ingestor will still honor the legacy `POTATOMESH_INSTANCE` variable when -`INSTANCE_DOMAIN` is unset to ease upgrades from earlier deployments. To keep +`ED:4D:9E:95:CF:60`) and the script attempts a BLE connection if available. To keep private channels out of the web UI, set `HIDDEN_CHANNELS` to a comma-separated list of channel names (for example `HIDDEN_CHANNELS="Secret,Ops"`); packets on those channels are discarded instead of being sent to `/api/messages`. @@ -205,12 +215,19 @@ Docker images are published on Github for each release: docker pull ghcr.io/l5yth/potato-mesh/web:latest # newest release docker pull ghcr.io/l5yth/potato-mesh/web:v0.5.5 # pinned historical release docker pull ghcr.io/l5yth/potato-mesh/ingestor:latest +docker pull ghcr.io/l5yth/potato-mesh/matrix-bridge:latest ``` Feel free to run the [configure.sh](./configure.sh) script to set up your environment. See the [Docker guide](DOCKER.md) for more details and custom deployment instructions. +## Matrix Bridge + +A matrix bridge is currently being worked on. It requests messages from a configured +potato-mesh instance and forwards it to a specified matrix channel; see +[matrix/README.md](./matrix/README.md). + ## Mobile App A mobile _reader_ app is currently being worked on. Stay tuned for releases and updates.