diff --git a/CHANGELOG.md b/CHANGELOG.md index 07e7c08..bac514e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 522b5bb..709c00f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. diff --git a/README.md b/README.md index 1a35854..e1db878 100644 --- a/README.md +++ b/README.md @@ -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. Discord

-> 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).

Watch the demo: MeshTerm showing every route a channel message took to arrive @@ -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. \ No newline at end of file +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. \ No newline at end of file