1 Commits
Author SHA1 Message Date
tthandClaude Opus 5.5 0143e21875 1.0.1: --list-ports, setup per operating system
image / build (arm64) (push) Successful in 38s
image / build (amd64) (push) Successful in 45s
image / release (push) Successful in 3s
ci / test (push) Successful in 1m8s
- `meshcore-exporter --list-ports` lists the USB serial ports on Linux,
  macOS and Windows with description, USB ID and serial number (and the
  /dev/serial/by-id/ name on Linux), so the companion can be found without
  knowing where a given OS puts it.
- README: which way to go per OS. Docker Desktop on macOS and Windows does
  not pass USB devices into containers, so the Docker stack with a USB board
  is Linux only (WSL2 with usbipd-win); macOS and Windows run the exporter
  with pipx. AGENTS.md: find the OS first, ports via --list-ports.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 22:31:46 +01:00
4 changed files with 91 additions and 7 deletions

No files matched your search

+11 -3
View File
@@ -35,9 +35,17 @@ README.md has the full reference. This file is the procedure and the rules.
README section 3 (a dedicated companion identity over TCP). Changing their
openHop config.yaml is a change to their node: show the block, let them
apply it.
2. USB companion: `ls -l /dev/serial/by-id/`. Use the by-id path, never
`/dev/ttyACM0` (it changes after a replug). Its group:
`stat -c '%G %g' <that path>`.
**Find out the operating system first.** Docker Desktop on macOS and
Windows cannot pass a USB device into a container: there, use section 2
(pipx) for the exporter, never the Docker stack with a USB board.
WSL2 needs the board attached with usbipd-win first.
2. USB companion: `meshcore-exporter --list-ports` (any OS; installed with
pipx, or `python3 meshcore_exporter.py --list-ports` from the checkout).
On Linux use the `/dev/serial/by-id/...` path it prints, never
`/dev/ttyACM0` (it changes after a replug); its group:
`stat -c '%G %g' <that path>`. macOS: `/dev/cu.usbmodem...`, Windows:
`COMn`. Not listed = not plugged in, a charge-only cable, or (VM/WSL) not
passed through: say so, do not guess another port.
3. Ask for the repeater name exactly as it appears in the MeshCore app, and
its admin or guest password (MeshCore uses only the first 15 characters).
4. Fill `stack/.env` from `stack/.env.example` (or a `repeaters.toml`).
+31 -3
View File
@@ -39,7 +39,25 @@ telemetry. Docs below are Czech; `meshcore-exporter --help` is English.*
- **Rádio nesmí mít zároveň připojenou jinou aplikaci** (telefon, Meshy,
meshcli). Companion obslouží jen jednoho klienta; vyhrazená deska je
nejjednodušší.
- Linux (amd64 nebo arm64). Docker pro variantu 1, Python 3.10+ pro variantu 2 (soubor `--config` chce 3.11+).
- Počítač, na kterém exportér poběží (cesta podle systému níž).
- Python 3.10+ pro variantu 2 (soubor `--config` chce 3.11+).
### Podle systému
| systém | doporučená cesta | port companionu |
|---|---|---|
| Linux, Raspberry Pi (64bit) | [1. Docker stack](#1-kompletní-stack-docker) | `/dev/serial/by-id/usb-…` |
| macOS | [2. Jen exportér](#2-jen-exportér) přes `pipx`, Prometheus a Grafana zvlášť | `/dev/cu.usbmodem…` |
| Windows | [2. Jen exportér](#2-jen-exportér) přes `pipx`, Prometheus a Grafana zvlášť | `COM3` apod. |
| Windows s WSL2 | jako Linux, desku do WSL předejte přes [usbipd-win](https://learn.microsoft.com/windows/wsl/connect-usb) | `/dev/ttyACM0` |
| cokoli s openHopem | [3. Bez vyhrazené desky](#3-bez-vyhrazené-desky-openhop) | žádný, TCP |
**Docker Desktop na macOS a Windows neumí předat USB zařízení do kontejneru**,
varianta 1 s deskou na USB tam nepojede. Který port je companion, vypíše na
každém systému `meshcore-exporter --list-ports` (popis desky, USB ID, sériové
číslo; na Linuxu i trvalé jméno z `/dev/serial/by-id/`, které se po
přepojení nezmění, na rozdíl od `/dev/ttyACM0`). Na Linuxu je ověřené vše,
na macOS a Windows zatím ne; hlášení, jak to dopadlo, je vítané.
## 1. Kompletní stack (Docker)
@@ -53,6 +71,9 @@ docker compose up -d
docker compose logs -f exporter # čekejte na "OK bat=…"
```
Jen Linux (včetně Raspberry Pi a WSL2 s usbipd): na macOS a Windows Docker
desku do kontejneru nepředá, tam použijte [2.](#2-jen-exportér).
Grafana poběží na `http://<počítač>:3000` (uživatel `admin`, heslo
z `.env`), dashboard **MeshCore — repeater** je domovská stránka. První
čísla jsou tam do minuty, grafy rychlostí (duty cycle, trend baterie) se
@@ -61,7 +82,7 @@ naplní za pár hodin (počítají se z okna 3 h, proměnná dashboardu **Okno**
Data drží Prometheus 400 dní (`PROMETHEUS_RETENTION` v `.env`).
Aktualizace: `docker compose pull && docker compose up -d`. Stack jede na
`latest`; na konkrétní verzi z [Releases](https://git.rfa.cz/tth-pub/meshcore-exporter/releases)
ho připnete řádkem `MC_VERSION=1.0.0` v `.env`.
ho připnete řádkem `MC_VERSION=1.0.1` v `.env`.
## 2. Jen exportér
@@ -69,10 +90,16 @@ Z Pythonu:
```bash
pipx install git+https://git.rfa.cz/tth-pub/meshcore-exporter
meshcore-exporter --list-ports # který port je companion
meshcore-exporter --serial /dev/serial/by-id/usb-… --repeaters muj-rpt --password … --check
meshcore-exporter --serial /dev/serial/by-id/usb-… --repeaters muj-rpt --password …
```
Na macOS je port `/dev/cu.usbmodem…`, na Windows `COM3` apod. (podle
`--list-ports`). Trvale spuštěný exportér tam zajistí `launchd`, resp. Plánovač
úloh, nebo služba přes [NSSM](https://nssm.cc/); Prometheus a Grafana mají
instalátory pro oba systémy.
Nebo kontejner (`latest-amd64` / `latest-arm64`, nebo verze z Releases,
např. `1.0.0-amd64`; jeden tag = jedna architektura):
@@ -153,6 +180,7 @@ Přepínač má přednost před proměnnou a ta před souborem.
| `--rf-timeout` | `MC_RF_TIMEOUT` | 30 | čekání na jednu odpověď |
| `--listen`, `--port` | `MC_LISTEN`, `MC_METRICS_PORT` | 0.0.0.0, 9200 | kde vystavit metriky |
| `--check` | — | — | přečte každý repeater jednou, vypíše hodnoty a skončí |
| `--list-ports` | — | — | vypíše USB sériové porty (Linux, macOS, Windows) a skončí |
**Jméno** repeateru musí sedět s tím, co rozesílá v advertu. **Pubkey**
je potřeba, jen když companion repeater nikdy neslyšel (pak plných 64 hex).
@@ -190,7 +218,7 @@ na meshcore.repeater.cz.
| příznak | příčina |
|---|---|
| `the companion does not answer` | špatný port, rádio drží jiná aplikace, nebo na desce není companion firmware |
| `the companion does not answer` | špatný port (`--list-ports`), rádio drží jiná aplikace, nebo na desce není companion firmware |
| `Permission denied` na portu | uživatel/kontejner není ve skupině portu (`MC_SERIAL_GID`, `dialout`/`uucp`) |
| `no contact '…' on the companion` | companion advert repeateru ještě neslyšel: počkejte, nebo dejte plný pubkey |
| `login failed` | špatné heslo — **MeshCore bere jen prvních 15 znaků**, delší heslo se tiše usekne —, nebo odpověď nedoletěla |
+32 -1
View File
@@ -33,7 +33,7 @@ import time
from dataclasses import dataclass
from typing import Any
__version__ = "1.0.0"
__version__ = "1.0.1"
MIN_INTERVAL = 900
DEFAULT_INTERVAL = 3600
@@ -161,6 +161,7 @@ def build_parser() -> argparse.ArgumentParser:
p.add_argument(
"--check", action="store_true", help="read every repeater once, print the values and exit (0 = all answered)"
)
p.add_argument("--list-ports", action="store_true", help="list the serial ports of this computer (any OS) and exit")
p.add_argument("--log-level", default=env("MC_LOG_LEVEL", "INFO"), help="[MC_LOG_LEVEL]")
p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
return p
@@ -546,9 +547,39 @@ def _i(v: float | None) -> str:
return "?" if v is None else f"{v:.0f}"
def list_ports() -> int:
"""Serial ports with what identifies the board: Linux, macOS and Windows alike.
On Linux the stable /dev/serial/by-id/ name is shown too: /dev/ttyACM0 may
become /dev/ttyACM1 after a replug, the by-id name stays.
"""
from serial.tools import list_ports as lp
by_id: dict[str, str] = {}
base = "/dev/serial/by-id"
if os.path.isdir(base):
for name in os.listdir(base):
by_id[os.path.realpath(os.path.join(base, name))] = os.path.join(base, name)
every = sorted(lp.comports(), key=lambda p: p.device)
ports = [p for p in every if p.vid is not None] # USB only: a companion is a USB device
if not ports:
print("no USB serial ports found -- is the companion plugged in (and, in a VM/WSL, passed through)?")
return 1
for p in ports:
ids = f"{p.vid:04x}:{p.pid:04x}" if p.vid is not None and p.pid is not None else "-"
print(f"{p.device}\n {p.description or '-'} [usb {ids}, serial {p.serial_number or '-'}]")
if os.path.realpath(p.device) in by_id:
print(f" use: {by_id[os.path.realpath(p.device)]}")
if len(every) > len(ports):
print(f"({len(every) - len(ports)} non-USB serial ports not shown)")
return 0
def main(argv: list[str] | None = None) -> int:
args = build_parser().parse_args(argv) # --help / --version exit here, before any import
logging.basicConfig(level=args.log_level.upper(), format="%(asctime)s %(levelname)s %(message)s")
if args.list_ports:
return list_ports()
try:
s = resolve(args)
except (ValueError, OSError) as e:
+17
View File
@@ -144,3 +144,20 @@ def test_contacts_fetched_once_per_round(monkeypatch):
for t in s.targets:
assert asyncio.run(ex.contact(mc, t))["adv_name"] == t.name
assert calls == [mx.CONTACTS_TIMEOUT]
def test_list_ports_skips_non_usb(monkeypatch, capsys):
from types import SimpleNamespace
pytest.importorskip("serial")
from serial.tools import list_ports
fake = [
SimpleNamespace(device="/dev/ttyS0", description="n/a", vid=None, pid=None, serial_number=None),
SimpleNamespace(device="COM7", description="XIAO nRF52840", vid=0x2886, pid=0x8044, serial_number="AB12"),
]
monkeypatch.setattr(list_ports, "comports", lambda: fake)
assert mx.list_ports() == 0
out = capsys.readouterr().out
assert "COM7" in out and "2886:8044" in out and "AB12" in out and "/dev/ttyS0" not in out
assert "1 non-USB" in out