The front door says only what is true

A sweep of the README, CONTRIBUTING and the 0.9.0 changelog entry against the running app.

- Not every screen has a subcommand: the map, dashboard, live feed, watchtower, mesh walk
  and time machine live in the menu only. "Most screens".
- Not every command speaks --json: specimen refuses it. "Nearly every".
- On Windows the download is meshterm-windows-x64.exe, not a file called meshterm.
- Apple silicon is M1 and later; Intel Macs were sold until 2023.
- The global options list gains --ble-pin, --absolute and --platform, which it missed.
- The meshcore library speaks TCP too.
- The standalone builds are single files, so their licence texts are bundled inside, not
  in an archive to extract.
- 64-bit ARM covers the uConsole; the PicoCalc is 32-bit and installs from a checkout.
- --mock keeps its own history database; the caches it shares are not "none of it".

The README, CONTRIBUTING and the PR template disagreed on when a pull request needs an
issue first. All three now say what CONTRIBUTING said: small fixes can come straight in,
anything bigger waits for a yes. CONTRIBUTING drops "or discussion", since Discussions
are off, and points bug reporters at the form, the diagnostics file and Discord. The bug
form link goes to the form rather than its YAML.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5 committed 2026-09-21 11:28:24 -04:00
1 parent 5c2933595e
commit 9b2b4d784b
3 files changed
+44 -36

No files matched your search

+8 -9
View File
@@ -25,8 +25,8 @@ what the mesh is doing.
- **Run it two ways, and it behaves the same either way.** Type `meshterm` on its own and
you get a full-screen menu you drive with the arrow keys. Type a command instead —
`meshterm contacts`, `meshterm info` — and it prints an answer and exits, which is what you
want in a script. Add `--json` to any command and the answer comes back as data for
another program to read.
want in a script. Add `--json` to nearly any command and the answer comes back as data
for another program to read.
- **It listens all the time, and writes down what it hears.** Radios on a mesh announce
themselves. From the moment yours is connected, MeshTerm notes down every announcement it
@@ -51,13 +51,12 @@ what the mesh is doing.
- **It talks to your radio however your radio talks.** USB cable, Bluetooth, or over the
network. It finds the ones it can find on its own and asks you to pick. If a connection
drops it reconnects by itself. No radio yet? `meshterm --mock` runs the whole program
against a simulated mesh, and keeps that pretend mesh in a history of its own, so none
of it ever turns up beside your real one.
against a simulated mesh, and records what it hears in a history database of its own,
apart from your real one.
- **It runs on the small machines too.** The PicoCalc gets a layout of its own, built
for its 53-column screen, with its own fonts, colours and on-screen key labels — not just
the desktop screen squeezed. The uConsole has room for the full desktop layout, and runs
that.
for its 53-column screen, with its own fonts, colours and on-screen key labels. The
uConsole has room for the full desktop layout, and runs that.
- **It works with no internet.** Map tiles are kept on disk once fetched, and when there is
no network at all the map falls back to a plain grid. Nothing about MeshTerm needs to
@@ -73,11 +72,11 @@ what the mesh is doing.
### Getting it
One file to download, with nothing else to install, for Windows, macOS (both Intel and
Apple silicon) and Linux (including 64-bit ARM, so handhelds are covered). If you would
Apple silicon) and Linux (including 64-bit ARM, which covers the uConsole). If you would
rather use Python, `pipx install` works too. The README has the exact commands.
MeshTerm is free and open source under the Apache 2.0 licence. The name and the logo are
not — see `NOTICE` — so a fork is welcome, under its own name.
not covered by the licence (see `NOTICE`), so a fork is welcome under its own name.
[Unreleased]: https://github.com/jpmartineau/MeshTerm/compare/v0.9.0...HEAD
[0.9.0]: https://github.com/jpmartineau/MeshTerm/releases/tag/v0.9.0
+9 -4
View File
@@ -25,8 +25,8 @@ this repository.
seen, etc.), UX standards for screens/dialogs/menus, and where the reusable building
blocks live in code (`ui/menus.py`, `ui/markdown.py`, `ui/widgets.py`, `ui/theme.py`).
New code should read like it always belonged here.
- For anything bigger than a small fix, open an issue first to talk it through before
writing a lot of code — saves both of us a rewrite.
- Small fixes can go straight to a pull request. For anything bigger, open an issue
first and wait for a yes before writing a lot of code — saves both of us a rewrite.
## Making a change
@@ -61,7 +61,12 @@ this repository.
Open a GitHub issue. For bugs, include what you expected, what happened, and enough to
reproduce it — device/platform, MeshCore firmware version if relevant, and steps.
The [bug form](https://github.com/jpmartineau/MeshTerm/issues/new?template=bug.yml) asks
for all of this. Attach the file that `meshterm diagnostics --out bug.md` writes. No
GitHub account? Post it in the #bugs forum on [Discord](https://discord.gg/AZwe5Uvb3S)
instead.
---
Questions about any of this, licensing included, are welcome as a GitHub issue or
discussion before you put work in.
Questions about any of this, licensing included, are welcome as a GitHub issue before you
put work in.
+27 -23
View File
@@ -8,7 +8,7 @@ network (TCP) companion.
MeshTerm is interactive by default: a modern, keyboard-driven TUI built on
[Rich](https://github.com/Textualize/rich) and
[prompt_toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit). It is also
fully scriptable — **every screen has a mirror `meshterm` subcommand** — so the same
fully scriptable — **most screens have a mirror `meshterm` subcommand** — so the same
capabilities drive both an evening of exploring the mesh and a cron job. Every packet the
radio overhears is recorded to a local SQLite database, so the longer you run it, the more
your mesh's history is worth.
@@ -23,8 +23,9 @@ your mesh's history is worth.
<a href="https://discord.gg/AZwe5Uvb3S"><img alt="Discord" src="https://img.shields.io/badge/chat-Discord-5865F2"></a>
</p>
> MeshTerm is a side project, not a product. Bug reports are very welcome — but please
> open an issue before writing a pull request. [More on how it's run](#how-this-project-is-run).
> MeshTerm is a side project, run by one person. Bug reports are very welcome. Small fixes
> can go straight to a pull request; for anything bigger, please open an issue first.
> [More on how it's run](#how-this-project-is-run).
<p align="center">
<a href="https://meshterm.net/#demo"><img src="https://meshterm.net/assets/demo-play.png" alt="Watch the demo: MeshTerm showing every route a channel message took to arrive" width="840"></a>
@@ -90,7 +91,7 @@ chmod +x meshterm
./meshterm
```
That's the Apple silicon build — every Mac since 2020. On an **Intel** Mac, swap `arm64`
That's the build for Apple silicon Macs (M1 and later). On an **Intel** Mac, swap `arm64`
for `x64`. And if you already downloaded it with a browser, you don't have to start over:
`xattr -d com.apple.quarantine meshterm` clears the flag.
@@ -116,8 +117,9 @@ then open Windows Terminal or PowerShell, `cd` to your downloads, and run it:
Windows says *"Windows protected your PC"* the first time. Click **More info → Run anyway**.
Whichever you took, you now have a file called `meshterm` — put it somewhere on your
`PATH` and it's just `meshterm` from anywhere.
Whichever you took, you now have a single file: `meshterm` on macOS and Linux,
`meshterm-windows-x64.exe` on Windows. Put it somewhere on your `PATH` (renamed to
`meshterm.exe` on Windows) and it's just `meshterm` from anywhere.
> **These builds aren't code-signed**, which is why macOS and Windows both push back the
> first time; signing costs real money on both platforms and this is a free side project.
@@ -242,17 +244,17 @@ contacts; **Watch** is the dashboard, the live feed, the watchtower and the time
and **This app** is MeshTerm itself — preferences, diagnostics, and the written pages.
Nearly every one of them has a mirror `meshterm` subcommand — the same registry builds
the menu and the CLI, so they can't drift apart. The live pictures stay in the menu,
where their meaning is.
the menu and the CLI, so they can't drift apart. The live screens, such as the map and
the dashboard, are only in the menu.
**[What MeshTerm does](docs/features.md)** is the full catalogue: every screen, what it
does, and its scripted equivalent where one exists.
## Scripting it
Every command speaks `--json`, and the global options — `--profile/-p`, `--port`,
`--ble`, `--tcp`, `--mock`, `--db`, `--json`, `--quiet/-q` — may be typed before or
after the subcommand.
Nearly every command speaks `--json`, and the global options — `--profile/-p`, `--port`,
`--ble`, `--ble-pin`, `--tcp`, `--mock`, `--db`, `--json`, `--absolute`, `--quiet/-q`,
`--platform` — may be typed before or after the subcommand.
```bash
# Every repeater's public key, for a script
@@ -280,18 +282,19 @@ MeshTerm is one person working evenings and weekends. I'd rather tell you that u
than have you guess from how long things take.
**Issues are welcome — all of them.** Bugs, questions, "is this supposed to do that". The
[bug form](.github/ISSUE_TEMPLATE/bug.yml) asks for a fair bit, and that's on purpose: how
well a problem is described really does decide whether I can do anything with it. If I can
reproduce it, I'll usually chase it. If I can't, I'm mostly guessing.
[bug form](https://github.com/jpmartineau/MeshTerm/issues/new?template=bug.yml) asks for a
fair bit, and that's on purpose: how well a problem is described really does decide whether
I can do anything with it. If I can reproduce it, I'll usually chase it. If I can't, I'm
mostly guessing.
**Ask before you write a pull request.** Open an issue first and wait for a yes. I'm not
being precious — MeshTerm has firm house rules about how screens get built (they're in
**Ask before you write a big pull request.** Small fixes can go straight to a pull
request. For anything bigger, open an issue first and wait for a yes. I'm not being
precious — MeshTerm has firm house rules about how screens get built (they're in
[CLAUDE.md](CLAUDE.md)), and I'd hate for you to spend a weekend on something I then ask
you to rewrite. A quick conversation first saves us both.
**I can't promise timelines.** Some things get fixed the same night. Some sit for a month
because life happened. If your issue goes quiet, a nudge is completely fine — it's not
rude, it's helpful.
because life happened. If your issue goes quiet, please give it a nudge. That helps me.
**Where to report things.** Either works:
@@ -346,7 +349,7 @@ respective project for the authoritative terms):
| Library | Role | License |
| --- | --- | --- |
| [meshcore](https://pypi.org/project/meshcore/) | Companion-device protocol (serial / BLE) | MIT |
| [meshcore](https://pypi.org/project/meshcore/) | Companion-device protocol (serial / BLE / TCP) | MIT |
| [pycryptodome](https://www.pycryptodome.org/) | AES/HMAC for decrypting overheard channel packets | BSD-2-Clause / Public Domain |
| [pyserial](https://github.com/pyserial/pyserial) | Serial-port enumeration and I/O | BSD-3-Clause |
| [bleak](https://github.com/hbldh/bleak) | Bluetooth LE scanning + connection | MIT |
@@ -375,7 +378,8 @@ is Microsoft's Cascadia Mono PL, redistributed unmodified under the SIL Open Fon
[CascadiaMono-OFL.txt](meshterm/assets/fonts/CascadiaMono-OFL.txt) and stays its only
license.
Each standalone build carries `LICENSE`, `NOTICE` and a generated `THIRD-PARTY-NOTICES.txt`
(every dependency's own license text) inside the archive, and the same three files sit
beside the downloads on the [releases page](https://github.com/jpmartineau/MeshTerm/releases)
so you don't have to extract one just to read them.
Each standalone build is a single file with `LICENSE`, `NOTICE` and a generated
`THIRD-PARTY-NOTICES.txt` (every dependency's own license text) bundled inside it. The same
three files are also attached to each release on the
[releases page](https://github.com/jpmartineau/MeshTerm/releases), so you can read them
without running anything.