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:
1 parent
5c2933595e
commit
9b2b4d784b
3 files changed
+44
-36
No files matched your search
+8
-9
@@ -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
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user