The Cap's GPS moves the node, and is no longer offered as a companion

The Cardputer Zero's Cap carries a GPS on the header's UART, which the
device screen listed as "~ n/a" (pyserial's name for a port with no USB
identity): a companion to connect to, and with nothing remembered, the
lone port a command-line connect would pick. A wiring now names its
board's GPS (`gps_port`, `gps_baud`; the Cap's is /dev/serial0 at
115200), and wherever that radio is listed, its GPS port is not: the
device screen, `meshterm devices`, and autodetect.

The radio node reads it the way MeshCore companion firmware reads a
board's GPS: `gps` (off until switched on, remembered in prefs.json)
and `gps_interval` (0, every fix, once a second), reported and set as
custom variables, which is where Device config already shows them. A
valid RMC or GGA fix becomes the node's position, the one its
self-info reports and, with Share location on, its adverts carry. The
last fix is saved as the node shuts down. Standard library only, as
the node's contract asks; NMEA checksums are checked.

On MeshTerm's side, our own self-info is now refreshed behind the
answer after a minute, like the contacts, so screens opened after the
node moves show where it is; and the connect-time settings offer no
longer flags a position the running GPS moved.

Checked on the Cardputer: the ttyS0 row is gone from `meshterm
devices`; `config custom gps 1` opens the port, is saved, and reads
back on; the real-terminal test passes there.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5.5 committed 2026-10-05 22:02:05 -04:00
1 parent c78a802ac6
commit 49d3eff212
14 files changed
+790 -34

No files matched your search

+26 -1
View File
@@ -172,4 +172,29 @@ A new node starts on MeshCore's US/Canada settings (910.525 MHz). Anywhere else,
them on **Device config** before you send anything. The node's key, contacts, and channels
are kept in `~/.meshterm/radio/spidev0.1/`.
The Cap also carries a GPS. MeshTerm doesn't read it yet.
#### The Cap's GPS
The Cap also carries a GPS, and MeshTerm can keep your node's position up to date from it.
It's off until you switch it on, the same as on MeshCore firmware. To switch it on:
1. Open **Device config**.
2. Under **Custom variables**, set **GPS** to on.
3. Apply.
Once the GPS has a fix, it becomes your node's position. Out in the open, the first fix
usually takes about a minute. Indoors, it may never come.
Two things don't change:
- **Whether your adverts include your position is still up to you.** That's the **Share
location** setting on Device config. With it off, the GPS still moves your node on
MeshTerm's own map, but nobody else sees where you are.
- **Moving your node on the map by hand doesn't stick while the GPS is on.** The next fix
puts it back where the GPS says you are. Switch the GPS off first.
**GPS interval** sets how often the position is updated, in seconds. It's 0 to start with,
which means every fix, about once a second. MeshTerm remembers your last fix when it quits,
so the next start begins where you were.
The GPS talks to the Cardputer over a serial port, the way a companion on a USB cable
does. It isn't a companion, though, so the device screen doesn't list it.
+1
View File
@@ -288,6 +288,7 @@ en_pins = [27] # the AIO v2 needs this
| `use_dio2_rf`, `use_dio3_tcxo` | `true`, `true` | Whether DIO2 drives the RF switch and DIO3 a TCXO (both on for the AIO). |
| `is_waveshare` | `false` | The Waveshare HAT's wiring quirks, which the radio library knows about. |
| `python` | `""` (empty) | An interpreter to run the node under, when the one MeshTerm would find on its own isn't the one you want. Empty lets MeshTerm look. |
| `gps_port`, `gps_baud` | `""`, `9600` | A GPS receiver on the same board: its serial port (empty for none) and its speed. The node runs it the way MeshCore firmware runs a board's GPS, switched on from Device config's **GPS** row, and the device screen stops listing the port as a companion. The Cardputer Zero's Cap needs no profile, but this is what one would say: `"/dev/serial0"`, `115200`. |
An unknown key, or one of the wrong type, stops MeshTerm at startup with the profile
named — a misspelt pin is never silently ignored.
+5 -1
View File
@@ -666,8 +666,12 @@ class AppContext:
await self._settle_connection()
return self._device
from .core.spiradio import without_radio_ports
resolution = resolve_device(
discover_devices(),
# Never the radio's own GPS port: on a Cardputer Zero with nothing remembered it
# was the lone port, and a lone port is connected to without asking.
without_radio_ports(discover_devices(), self.settings.profiles),
self.device_store.load(),
explicit_port=self.port_override,
profile=self.profile,
+9
View File
@@ -114,6 +114,13 @@ class SpiWiring:
is_waveshare: The Waveshare HAT's wiring quirks, which the radio library knows.
python: An interpreter to run the node under, when the one MeshTerm would find
is not the one you want. Empty to let MeshTerm look.
gps_port: The serial port of a GPS receiver on the same board, or empty for none.
The node runs it the way MeshCore firmware runs a board's GPS — a ``gps``
switch and a ``gps_interval`` on Device config — and the port is the radio's,
so the device screen doesn't offer it as a companion. The Cardputer Zero's Cap
has one on ``/dev/serial0``.
gps_baud: The receiver's line speed. NMEA's own default is 9600; the Cap's runs at
115200.
"""
bus_id: int = 1
@@ -135,6 +142,8 @@ class SpiWiring:
use_dio3_tcxo: bool = True
is_waveshare: bool = False
python: str = ""
gps_port: str = ""
gps_baud: int = 9600
#: Keys this table once took and must never take again under another meaning (see
#: :data:`meshterm.core.preferences.RETIRED`). ``preamble_length`` was never wiring: it is
+277 -7
View File
@@ -22,11 +22,19 @@ state directory the parent names instead:
================= =============================================================
``identity.key`` the node's private seed — its identity on the mesh
``prefs.json`` name, radio settings, TX power, position, the other prefs
``prefs.json`` name, radio settings, TX power, position, the other prefs —
and, on a board with a GPS, its switch and interval
``channels.json`` the channel table, slot by slot
``contacts.json`` the contact list
================= =============================================================
**What firmware would do with a GPS, this does.** A board whose wiring names a GPS port
(the Cardputer Zero's Cap) gets the two settings MeshCore's companion firmware gives a
board with a receiver — ``gps`` to run it and ``gps_interval`` to pace it — reported and
set as custom variables, which is where MeshTerm's Device config already looks for them.
While it runs, a valid fix becomes the node's position: the one its self-info reports
and, when the node shares its location, its adverts carry (:class:`Gps`).
**Talking to the parent.** The parent reads exactly one JSON line from this process's
stdout: ``{"event": "ready", "port": …, "public_key": …}`` once the frame server is
listening, or ``{"event": "error", "kind": …, "message": …}`` if the radio could not be
@@ -46,12 +54,15 @@ from __future__ import annotations
import argparse
import asyncio
import dataclasses
import functools
import json
import logging
import operator
import os
import signal
import sys
import threading
import time
from pathlib import Path
from typing import Any
@@ -362,8 +373,6 @@ def prepare_board(wiring: dict) -> list[tuple[Path, str]]:
"""
previous = set_leds(list(wiring.get("leds") or ()), root=LEDS)
if previous:
import time
time.sleep(POWER_SETTLE_S)
try:
if int(wiring.get("pi4io_bus", -1)) >= 0:
@@ -378,6 +387,227 @@ def prepare_board(wiring: dict) -> list[tuple[Path, str]]:
return previous
# --- the GPS beside the chip ---------------------------------------------------------------
#: The custom variables a board with a GPS answers to, by MeshCore firmware's own names.
GPS_VARS = ("gps", "gps_interval")
#: The firmware's ceiling on ``gps_interval`` (``constrain(…, 0, 86400)``): one day.
GPS_INTERVAL_MAX_S = 86400
#: NMEA allows a sentence 82 characters; a partial line well past that is noise on the wire,
#: not a sentence still arriving, and is dropped rather than grown.
_NMEA_MAX = 512
def nmea_fix(line: str) -> tuple[float, float] | None:
"""The position one NMEA sentence reports as a valid fix, as ``(lat, lon)``, or ``None``.
Two sentences carry a fix, from any constellation's talker (``GP``, ``GN``, ``GL``,
``GA``, ``GB``…): RMC, valid when its status is ``A``, and GGA, valid when its fix
quality isn't ``0``. Everything else is ``None`` — another sentence, a sentence whose
checksum doesn't match (a byte lost on the wire), a field that isn't a coordinate, and
the no-fix sentences a receiver sends until it has one.
"""
line = line.strip()
body, star, given = line.removeprefix("$").partition("*")
if not line.startswith("$") or not star or len(given) < 2:
return None
try:
if int(given[:2], 16) != functools.reduce(operator.xor, body.encode("ascii", "replace"), 0):
return None
except ValueError:
return None
fields = body.split(",")
kind = fields[0][-3:]
if kind == "RMC" and len(fields) > 6 and fields[2] == "A":
coords = fields[3:7]
elif kind == "GGA" and len(fields) > 6 and fields[6] not in ("", "0"):
coords = fields[2:6]
else:
return None
try:
return _degrees(coords[0], coords[1], "NS", 2), _degrees(coords[2], coords[3], "EW", 3)
except ValueError:
return None
def _degrees(value: str, hemisphere: str, hemispheres: str, degree_digits: int) -> float:
"""NMEA's ``ddmm.mmmm`` (``dddmm.mmmm`` east–west) and its hemisphere, as signed degrees."""
if len(hemisphere) != 1 or hemisphere not in hemispheres or len(value) <= degree_digits:
raise ValueError(value)
minutes = float(value[degree_digits:])
unsigned = int(value[:degree_digits]) + minutes / 60
if not 0 <= minutes < 60 or unsigned > (90 if degree_digits == 2 else 180):
raise ValueError(value)
return -unsigned if hemisphere == hemispheres[1] else unsigned
def _saved_int(saved: dict, key: str, default: int) -> int:
"""``saved[key]`` as an int, or ``default`` where it is missing or isn't one."""
try:
return int(saved.get(key, default))
except (TypeError, ValueError):
return default
class Gps:
"""The board's GPS receiver, run the way MeshCore companion firmware runs one.
Two settings, under the firmware's names and with its defaults: ``gps``, off until it is
switched on and remembered across restarts, and ``gps_interval``, the seconds between
position updates — ``0``, the default, takes every fix, which is the firmware's one a
second. The receiver's NMEA is read on the node's own event loop (a few sentences a
second is nothing beside the radio), and a valid fix is written into the node's
preferences, which is where its self-info frame and its adverts both read the position
from. Firmware keeps a fix in RAM only; here the position is saved with the node's other
preferences whenever they are, and once more as the node shuts down, so a restart
indoors begins from the last fix rather than from a position set by hand long ago.
Attributes:
port: The receiver's serial port.
baud: Its line speed.
enabled: Whether ``gps`` is on.
interval_s: ``gps_interval``.
node: The companion whose position a fix moves; set once it exists.
moved: Whether a fix has moved the position since the preferences were last saved.
"""
def __init__(self, port: str, baud: int, saved: Any = None) -> None:
"""Take the port and speed from the wiring, and the two settings from ``prefs.json``."""
saved = saved if isinstance(saved, dict) else {}
self.port = port
self.baud = baud
self.enabled = _saved_int(saved, "gps_enabled", 0) == 1
self.interval_s = min(max(_saved_int(saved, "gps_interval", 0), 0), GPS_INTERVAL_MAX_S)
self.node: Any = None
self.moved = False
self._fd: int | None = None
self._pending = b""
self._next_at = 0.0
self._fixed = False
@property
def running(self) -> bool:
"""Whether the receiver's port is open and being read."""
return self._fd is not None
def custom_vars(self) -> dict[str, str]:
"""The two settings as the firmware reports them: ``gps`` says whether it *runs*."""
return {"gps": "1" if self.running else "0", "gps_interval": str(self.interval_s)}
def saved(self) -> dict[str, int]:
"""The two settings as ``prefs.json`` keeps them, under the firmware's field names."""
return {"gps_enabled": int(self.enabled), "gps_interval": self.interval_s}
def set_var(self, name: str, value: str) -> bool:
"""Set ``gps`` or ``gps_interval``; ``False`` refuses the value, changing nothing."""
value = value.strip()
if name == "gps" and value in ("0", "1"):
if value == "1":
try:
self.start()
except OSError as exc:
log.warning("GPS on %s did not open: %s", self.port, exc)
return False
else:
self.stop()
self.enabled = value == "1"
return True
if name == "gps_interval":
try:
seconds = int(value)
except ValueError:
return False
self.interval_s = min(max(seconds, 0), GPS_INTERVAL_MAX_S)
self._next_at = 0.0 # the new pace counts from the next fix
return True
return False
def start(self) -> None:
"""Open the port raw at the receiver's speed and read it on the running loop.
Raises:
OSError: The port can't be opened or set up (missing, not ours, not a tty).
"""
if self._fd is not None:
return
import termios
import tty
speed = getattr(termios, f"B{self.baud}", None)
if speed is None:
raise OSError(f"{self.baud} is not a line speed this system has")
fd = os.open(self.port, os.O_RDONLY | os.O_NOCTTY | os.O_NONBLOCK)
try:
tty.setraw(fd)
attrs = termios.tcgetattr(fd)
attrs[4] = attrs[5] = speed # input and output speed
attrs[2] |= termios.CLOCAL | termios.CREAD
termios.tcsetattr(fd, termios.TCSANOW, attrs)
termios.tcflush(fd, termios.TCIFLUSH)
asyncio.get_running_loop().add_reader(fd, self._readable)
except termios.error as exc:
os.close(fd)
raise OSError(f"{self.port} is not a serial port ({exc})") from None
except BaseException:
os.close(fd)
raise
self._fd, self._pending, self._next_at, self._fixed = fd, b"", 0.0, False
log.info("GPS on %s at %d baud", self.port, self.baud)
def stop(self) -> None:
"""Stop reading and close the port; the position keeps the last fix."""
fd, self._fd = self._fd, None
if fd is None:
return
try:
asyncio.get_running_loop().remove_reader(fd)
except RuntimeError: # no loop left to remove it from: closing is enough
pass
os.close(fd)
log.info("GPS on %s stopped", self.port)
def _readable(self) -> None:
"""Read what the port has; a port that hangs up or fails is stopped, not retried."""
try:
chunk = os.read(self._fd, 4096) # type: ignore[arg-type]
except BlockingIOError:
return
except OSError as exc:
log.warning("GPS on %s failed: %s", self.port, exc)
self.stop()
return
if not chunk: # hung up: it would read as ready forever
log.warning("GPS on %s hung up", self.port)
self.stop()
return
self.feed(chunk)
def feed(self, chunk: bytes, now: float | None = None) -> None:
"""Take bytes as they arrive and act on each whole sentence among them."""
*lines, self._pending = (self._pending + chunk).split(b"\n")
if len(self._pending) > _NMEA_MAX:
self._pending = b""
for raw in lines:
fix = nmea_fix(raw.decode("ascii", "replace"))
if fix is not None:
self._take(fix, time.monotonic() if now is None else now)
def _take(self, fix: tuple[float, float], now: float) -> None:
"""Make ``fix`` the node's position, once per interval."""
if self.node is None or now < self._next_at:
return
if not self._fixed: # once a start, and never where: a log is pasted into issues
log.info("GPS has a fix")
self._fixed = True
prefs = self.node.prefs
if (prefs.latitude, prefs.longitude) != fix:
prefs.latitude, prefs.longitude = fix
self.moved = True
self._next_at = now + max(self.interval_s, 1)
def _persist_contacts(store: Any, path: Path) -> None:
"""Snapshot the contact list after every change, the way the firmware writes flash."""
@@ -475,7 +705,13 @@ async def _serve( # noqa: PLR0913 - the library modules run_node imported, hand
spreading_factor=seed.get("spreading_factor", 7),
coding_rate=seed.get("coding_rate", 5),
)
apply_saved_prefs(prefs, _read_json(state / "prefs.json"))
saved_prefs = _read_json(state / "prefs.json")
apply_saved_prefs(prefs, saved_prefs)
gps = (
Gps(str(wiring["gps_port"]), int(wiring.get("gps_baud") or 9600), saved_prefs)
if wiring.get("gps_port")
else None
)
SX1262Radio = sx1262.SX1262Radio
kwargs = radio_kwargs(inspect.signature(SX1262Radio.__init__).parameters, wiring, prefs)
@@ -511,7 +747,7 @@ async def _serve( # noqa: PLR0913 - the library modules run_node imported, hand
state, lambda: identity_mod.LocalIdentity().get_signing_key_bytes()
)
identity = identity_mod.LocalIdentity(seed_bytes)
node = _persistent_companion(companion_mod.CompanionRadio, state)(
node = _persistent_companion(companion_mod.CompanionRadio, state, gps)(
radio,
identity,
node_name=prefs.node_name,
@@ -540,6 +776,13 @@ async def _serve( # noqa: PLR0913 - the library modules run_node imported, hand
)
await node.start()
if gps is not None:
gps.node = node
if gps.enabled:
try:
gps.start()
except OSError as exc: # the radio still works; `gps` reads 0 until it opens
log.warning("GPS on %s did not open: %s", gps.port, exc)
public_key = node.get_public_key()
server = companion_mod.CompanionFrameServer(
bridge=node,
@@ -566,6 +809,10 @@ async def _serve( # noqa: PLR0913 - the library modules run_node imported, hand
await _until_told_to_stop()
finally:
log.info("shutting down")
if gps is not None:
gps.stop()
if gps.moved:
node._save_prefs() # the last fix, so a restart begins where the node was
for step in (server.stop, node.stop):
try:
await step()
@@ -598,11 +845,13 @@ def apply_preamble(radio: Any, symbols: int) -> None:
log.warning("could not apply the new preamble while listening: %s", exc)
def _persistent_companion(base: type, state: Path) -> type:
def _persistent_companion(base: type, state: Path, gps: Gps | None = None) -> type:
"""``CompanionRadio`` with its preferences written to ``prefs.json`` on every change.
``_save_prefs`` is the library's own hook for exactly this ("subclasses that need
persistence … should override this method"), called after every preference setter.
With a ``gps``, the board's two GPS settings are among its custom variables, as the
firmware lists them, and are saved beside the preferences the library knows.
"""
class PersistentCompanion(base): # type: ignore[misc, valid-type]
@@ -617,9 +866,30 @@ def _persistent_companion(base: type, state: Path) -> type:
apply_preamble(self._radio, preamble_for_sf(sf))
return ok
def get_custom_vars(self) -> dict[str, str]:
"""The library's variables, and a GPS board's two as firmware reports them."""
found = super().get_custom_vars()
if gps is not None:
found.update(gps.custom_vars())
return found
def set_custom_var(self, name: str, value: str) -> bool:
"""Set a variable; ``gps`` and ``gps_interval`` run the receiver and are saved."""
if gps is None or name not in GPS_VARS:
return super().set_custom_var(name, value)
if not gps.set_var(name, value):
return False
self._save_prefs()
return True
def _save_prefs(self) -> None:
try:
_write_json(state / "prefs.json", prefs_to_json(self.prefs))
saved = prefs_to_json(self.prefs)
if gps is not None:
saved.update(gps.saved())
_write_json(state / "prefs.json", saved)
if gps is not None:
gps.moved = False
except Exception as exc: # noqa: BLE001 - a failed save must not fail the setter
log.warning("could not save prefs: %s", exc)
+48 -10
View File
@@ -45,7 +45,7 @@ from pathlib import Path
from .config import DeviceProfile, SpiWiring
from .connection import DeviceCommandError, MeshCoreDevice
from .discovery import DiscoveredDevice, spi_device
from .discovery import TRANSPORT_SERIAL, DiscoveredDevice, spi_device
_log = logging.getLogger(__name__)
@@ -211,7 +211,9 @@ def gpio_chip(wiring: SpiWiring) -> int:
#: pins (reset, interrupt) reach the chip only while ``ext_usb_gpio_fun`` routes them to GPIO
#: rather than to USB. Its PI4IOE5V6408 at 0x43 on I2C 1 enables the RF path from pin P0,
#: which Meshtastic's Cardputer variant drives the same way. DIO2 switches the antenna and
#: DIO3 feeds a 1.8 V TCXO, as on the AIO.
#: DIO3 feeds a 1.8 V TCXO, as on the AIO. Its GPS talks NMEA at 115200 on the header's
#: UART, which is the Pi's ``serial0`` (``/dev/ttyS0`` on the Zero) — powered, like the
#: radio, by ``ext_5v_out``, so it speaks only while the node runs.
CARDPUTER_ZERO_CAP = SpiWiring(
bus_id=0,
cs_id=1,
@@ -222,6 +224,8 @@ CARDPUTER_ZERO_CAP = SpiWiring(
pi4io_bus=1,
pi4io_address=0x43,
pi4io_high=(0,),
gps_port="/dev/serial0",
gps_baud=115200,
)
@@ -283,6 +287,20 @@ def spi_radios(
One SPI :class:`~meshterm.core.discovery.DiscoveredDevice` per radio not in ``listed``.
"""
seen = {d.stable_id for d in listed}
radios: list[DiscoveredDevice] = []
for wiring, name in _present_wirings(profiles):
device = spi_device(wiring, name=name)
if device.stable_id in seen:
continue
seen.add(device.stable_id)
radios.append(device)
return radios
def _present_wirings(
profiles: Mapping[str, DeviceProfile] | None,
) -> list[tuple[SpiWiring, str]]:
"""Each radio on this machine's SPI bus as ``(wiring, name)``: profiles first, then boards."""
wirings = [(p.spi or SpiWiring(), p.name) for p in (profiles or {}).values() if p.is_spi]
wirings = [(w, name) for w, name in wirings if spi_present(w)]
covered = {wiring.spidev for wiring, _name in wirings}
@@ -290,14 +308,32 @@ def spi_radios(
if builtin.wiring.spidev not in covered and builtin.present():
wirings.append((builtin.wiring, builtin.name))
covered.add(builtin.wiring.spidev)
radios: list[DiscoveredDevice] = []
for wiring, name in wirings:
device = spi_device(wiring, name=name)
if device.stable_id in seen:
continue
seen.add(device.stable_id)
radios.append(device)
return radios
return wirings
def without_radio_ports(
devices: Iterable[DiscoveredDevice], profiles: Mapping[str, DeviceProfile] | None
) -> list[DiscoveredDevice]:
"""``devices`` less the serial ports a radio on the SPI bus owns — its board's GPS.
A board's GPS answers a port scan like any serial device, and with nothing to name it
(no USB identity, so pyserial calls it ``n/a``) it was listed beside the radio as a
companion to connect to: on a Cardputer Zero with its Cap, a row of its own above or
below the Cap, and with nothing remembered, the one port a command-line connect would
pick. It is the radio's node that reads it, so wherever that radio is listed, the port
is not. Matched by the port's real path, since a wiring names the stable alias
(``/dev/serial0``) and the scan the device it points at (``/dev/ttyS0``).
"""
owned = {
os.path.realpath(wiring.gps_port)
for wiring, _name in _present_wirings(profiles)
if wiring.gps_port
}
return [
d
for d in devices
if not (d.transport == TRANSPORT_SERIAL and d.port and os.path.realpath(d.port) in owned)
]
# --- finding a Python with the radio library -----------------------------------------------
@@ -652,6 +688,8 @@ async def start_node(wiring: SpiWiring, state: Path, *, node_name: str) -> NodeP
"use_dio2_rf": wiring.use_dio2_rf,
"use_dio3_tcxo": wiring.use_dio3_tcxo,
"is_waveshare": wiring.is_waveshare,
"gps_port": wiring.gps_port,
"gps_baud": wiring.gps_baud,
},
"seed": {"node_name": node_name, **DEFAULT_SEED},
}
+43 -9
View File
@@ -14,7 +14,9 @@ screens feel like it stalled.
None of that data actually changes mid-navigation:
* **self-info** and **path-hash mode** change only when the config editor writes them;
* **self-info** changes when the config editor writes it, and otherwise only in its
position, which a node with a GPS running moves by itself as it travels;
* **path-hash mode** changes only when the config editor writes it;
* **channel slots** change only when the channel editor saves one;
* **channel-slot capacity** is a fixed firmware build constant — it never changes at all
within a connection, so it is simply held for the session and only dropped on a reconnect;
@@ -27,6 +29,8 @@ copy instantly. The two rules that keep the cache honest:
* **Contacts** use *stale-while-revalidate*: a read past :data:`_CONTACTS_TTL_S` returns the
cached list immediately and refreshes it in the background, so navigation is never blocked
on the slow call, yet newly-heard contacts still appear within a TTL of the next screen.
**Self-info** does the same past :data:`_SELF_INFO_TTL_S`, so a screen opened after the
node has moved shows where it is now.
* Everything else is held until an in-app write **invalidates** it (see
:meth:`invalidate_self_info`, :meth:`invalidate_channels`, …); the writer is the only thing
that can change it, so it is also the only thing that needs to drop the cache.
@@ -58,6 +62,12 @@ if TYPE_CHECKING:
#: this age still returns instantly from cache; the refresh happens behind it.
_CONTACTS_TTL_S = 90.0
#: How long the node's own self-info is served before a read also refreshes it behind the
#: answer (seconds). Only the position moves without the app writing it — a GPS updating
#: it as the node travels — and one small frame a minute keeps every screen opened after a
#: move honest about where the node is, at no cost to navigation.
_SELF_INFO_TTL_S = 60.0
def _aware(when: datetime | None) -> datetime | None:
"""Read a stored timestamp as UTC, so two of them can be compared.
@@ -95,6 +105,7 @@ class DeviceState:
self._contacts: list[Contact] | None = None
self._contacts_at: float = 0.0
self._self_info: dict | None = None
self._self_info_at: float = 0.0
self._path_hash_mode: int | None = None
self._channels: list[ChannelSlot] | None = None
self._channels_epoch = 0
@@ -250,23 +261,46 @@ class DeviceState:
except Exception as exc: # noqa: BLE001 - a stale list is fine; never surface here
self._ctx.log.debug("devstate: background contacts refresh failed: %s", exc)
# -- self-info (held until an in-app write invalidates it) ------------------
# -- self-info (stale-while-revalidate; an in-app write invalidates it) -------
async def self_info(self) -> dict:
"""Return the node's own self-info, cached until the config editor invalidates it.
"""Return the node's own self-info, cached and refreshed lazily like the contacts.
The first call reads it from the radio; later calls return the cached copy at once,
and past :data:`_SELF_INFO_TTL_S` also re-read it in the background, for the position
a GPS moves. The config editor still invalidates it outright when it writes.
Returns:
The self-info payload (identity, radio tuning, coordinates, tx power). Raises like
:meth:`~meshterm.core.connection.Device.get_self_info` if the fetch fails; the
failure is not cached, so the next call retries.
:meth:`~meshterm.core.connection.Device.get_self_info` if the first fetch fails;
the failure is not cached, so the next call retries.
"""
if self._self_info is None:
async with self._self_info_lock:
if self._self_info is None:
device = await self._ctx.device()
self._self_info = dict(await device.get_self_info())
return await self._fetch_self_info()
if time.monotonic() - self._self_info_at > _SELF_INFO_TTL_S:
self._spawn(self._refresh_self_info_quietly())
return self._self_info
async def _fetch_self_info(self) -> dict:
"""Read the self-info from the device and cache it (blocking, deduplicated)."""
async with self._self_info_lock:
if (
self._self_info is not None
and time.monotonic() - self._self_info_at <= _SELF_INFO_TTL_S
):
return self._self_info
device = await self._ctx.device()
self._self_info = dict(await device.get_self_info())
self._self_info_at = time.monotonic()
return self._self_info
async def _refresh_self_info_quietly(self) -> None:
"""Background self-info refresh: a failure keeps the copy already held."""
try:
await self._fetch_self_info()
except Exception as exc: # noqa: BLE001 - a stale copy is fine; never surface here
self._ctx.log.debug("devstate: background self-info refresh failed: %s", exc)
def peek_self_info(self) -> dict | None:
"""The self-info already in hand, or ``None`` — never a radio read.
+4 -2
View File
@@ -26,7 +26,7 @@ from ..core.discovery import (
discover_devices,
)
from ..core.selection import DeviceSelectionError
from ..core.spiradio import spi_radios
from ..core.spiradio import spi_radios, without_radio_ports
from .base import Tool, ToolResult, register
if TYPE_CHECKING: # pragma: no cover - typing only
@@ -77,7 +77,9 @@ class DevicesTool(Tool):
scan_ble = params.get("ble", True)
devices = await discover_all(ble=scan_ble) if scan_ble else discover_devices()
# A radio on the SPI bus is attached the way a serial port is, but nothing
# enumerates it: it is listed from its device node, as the device screen lists it.
# enumerates it: it is listed from its device node, as the device screen lists it
# — and the port its board's GPS answers on is listed as part of it, not beside it.
devices = without_radio_ports(devices, ctx.settings.profiles)
devices += spi_radios(ctx.settings.profiles, devices)
known = ctx.device_store.load_all()
remembered = ctx.device_store.load()
+3 -2
View File
@@ -54,7 +54,7 @@ from ..core.discovery import (
serial_device,
tcp_device,
)
from ..core.spiradio import spi_radios
from ..core.spiradio import spi_radios, without_radio_ports
from ..persistence.logging import log_file_for
from .logo import load_logo
from .menus import Lane, align_icons, column_header
@@ -402,7 +402,8 @@ async def prompt_device(
Built in one place because two callers need it now -- the loop below, and the
rescan that redraws the rows under the reader while the splash is open.
"""
scanned = wired + wireless
# A port a radio on the SPI bus owns (the Cap's GPS) is that radio's, not a companion.
scanned = without_radio_ports(wired, profiles) + wireless
remembered = store.load()
# The full registry (not just the single last device) so *every* confirmed companion
# can be named, highlighted, and sorted to the top — keyed by stable_id. Reloaded each
+27
View File
@@ -20,6 +20,8 @@ remembered for it — so a firmware radio you don't manage through MeshTerm is n
from __future__ import annotations
from typing import TYPE_CHECKING
from rich.text import Text
from ..context import AppContext
@@ -29,6 +31,9 @@ from ..core.settings_store import SettingDrift, adopt, restore, settings_drift
from .menus import menu_rows
from .tui import Separator
if TYPE_CHECKING:
from ..core.connection import Device
# The offer's actions, returned by the startup select.
_RESTORE = "restore"
_ADOPT = "adopt"
@@ -54,6 +59,19 @@ def _position_undefined(snapshot: dict) -> bool:
return not usable_fix(lat, lon)
async def _gps_running(device: Device) -> bool:
"""Whether the device reports its GPS running (the firmware's ``gps`` variable is ``1``).
Asked only when a position has drifted, and best-effort: firmware without the variables,
or a failed read, is a device with no GPS to weigh.
"""
try:
found = await device.get_custom_vars()
except Exception: # noqa: BLE001 - optional read; absence means no GPS
return False
return str(found.get("gps", "")).strip() == "1"
async def offer_remembered_settings(ctx: AppContext) -> None:
"""Offer to reconcile the connected device's settings with MeshTerm's saved copy.
@@ -104,6 +122,15 @@ async def offer_remembered_settings(ctx: AppContext) -> None:
if not drifted:
return
# A device whose GPS is running moves its own position as it travels, so a fix unlike
# the saved one is a reading, not a setting that drifted: neither restored nor asked
# about, or every connect away from home would offer to put the node back there. (One
# with no fix yet was handled above: the saved position holds until the first fix.)
if any(d.key in _POSITION_KEYS for d in drifted) and await _gps_running(device):
drifted = [d for d in drifted if d.key not in _POSITION_KEYS]
if not drifted:
return
choice = await _prompt(ctx, drifted)
keys = [d.key for d in drifted]
try:
+22 -1
View File
@@ -16,7 +16,7 @@ from datetime import datetime, timezone
from types import SimpleNamespace
from meshterm.core.models import Contact
from meshterm.services.device_state import _CONTACTS_TTL_S, DeviceState
from meshterm.services.device_state import _CONTACTS_TTL_S, _SELF_INFO_TTL_S, DeviceState
class FakeDevice:
@@ -152,6 +152,27 @@ def test_contacts_refresh_in_background_past_ttl() -> None:
asyncio.run(run())
def test_self_info_refreshes_in_background_past_ttl() -> None:
"""A node with a GPS moves itself, so past its TTL our own self-info is read again.
The read past the TTL still answers at once with the copy in hand; the next screen gets
the position the node reports now.
"""
dev = FakeDevice()
ds = _devstate(dev)
async def run() -> None:
first = await ds.self_info()
assert await ds.self_info() is first and dev.self_info_calls == 1 # within the TTL
ds._self_info_at = time.monotonic() - _SELF_INFO_TTL_S - 1
assert await ds.self_info() is first # served at once, not blocked on the re-read
await asyncio.gather(*list(ds._tasks))
assert dev.self_info_calls == 2
assert await ds.self_info() is not first # the fresh copy from here on
asyncio.run(run())
def test_heard_time_takes_the_later_of_the_device_and_our_own_receptions() -> None:
"""A contact's heard time is the latest of the device's advert time and our evidence.
+233
View File
@@ -12,10 +12,14 @@ that a channel written through MeshTerm is still there after the node restarts.
from __future__ import annotations
import ast
import asyncio
import dataclasses
import json
import os
import sys
from pathlib import Path
from types import SimpleNamespace
from typing import Any
import pytest
@@ -237,3 +241,232 @@ def test_a_retune_resends_the_preamble_to_the_listening_chip() -> None:
chip.calls.clear()
radionode.apply_preamble(radio, 16) # unchanged: the chip is left listening undisturbed
assert chip.calls == []
# --- the GPS beside the chip ---------------------------------------------------------------
def _sentence(body: str) -> str:
"""``body`` as a whole NMEA sentence, its checksum computed rather than copied."""
check = 0
for byte in body.encode("ascii"):
check ^= byte
return f"${body}*{check:02X}"
#: What the Cap's receiver sent on the Cardputer before it had a fix, byte for byte.
_NO_FIX = [
"$GNRMC,,V,,,,,,,,,,N,V*37",
"$GNGGA,,,,,,0,00,25.5,,,,,,*64",
"$GNGSA,A,1,,,,,,,,,,,,,25.5,25.5,25.5,1*01",
]
#: A fix in Montreal, as an RMC: the west longitude is the sign worth checking.
_MONTREAL = _sentence("GNRMC,010203.00,A,4532.1274,N,07342.5219,W,0.1,,051026,,,A,V")
@pytest.mark.parametrize(
("line", "fix"),
[
# NMEA's own textbook sentences, checksums as published.
(
"$GPRMC,123519,A,4807.038,N,01131.000,E,022.4,084.4,230394,003.1,W*6A",
(48.1173, 11.516667),
),
(
"$GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47",
(48.1173, 11.516667),
),
(_MONTREAL, (45.535457, -73.708698)),
(
_sentence("GNGGA,010203.00,3352.0000,S,15112.0000,E,1,09,0.9,40,M,,M,,"),
(-33.866667, 151.2),
),
],
)
def test_a_valid_fix_is_read_from_either_sentence(line: str, fix: tuple) -> None:
"""RMC and GGA both carry a fix, from any talker, south and west negative."""
got = radionode.nmea_fix(line)
assert got is not None and got == pytest.approx(fix, abs=1e-6)
@pytest.mark.parametrize(
"line",
[
*_NO_FIX,
_MONTREAL.replace("4532", "4533"), # a byte changed on the wire: checksum fails
_MONTREAL[:-2], # cut off inside its checksum
_sentence("GNRMC,010203.00,A,4560.0000,N,07342.5219,W,,,051026,,,A,V"), # 60 minutes
_sentence("GNRMC,010203.00,A,4532.1274,X,07342.5219,W,,,051026,,,A,V"), # no hemisphere
_sentence("GNVTG,,,,,,,,,N"),
"",
"garbage",
],
)
def test_anything_but_a_valid_fix_is_none(line: str) -> None:
"""No fix yet, a damaged sentence, and every other sentence leave the position alone."""
assert radionode.nmea_fix(line) is None
def _gps_node(lat: float = 0.0, lon: float = 0.0) -> Any:
"""A stand-in companion: all a fix touches is its preferences' two coordinates."""
return SimpleNamespace(prefs=SimpleNamespace(latitude=lat, longitude=lon))
def test_a_fix_becomes_the_node_s_position_once_per_interval() -> None:
"""The firmware's pacing: the first fix at once, then one per ``gps_interval``."""
gps = radionode.Gps("/dev/serial0", 115200, {"gps_interval": 30})
gps.node = _gps_node()
north = _sentence("GNRMC,010204.00,A,4532.2274,N,07342.5219,W,,,051026,,,A,V")
gps.feed(("\r\n".join([*_NO_FIX, _MONTREAL]) + "\r\n").encode(), now=100.0)
assert (gps.node.prefs.latitude, gps.node.prefs.longitude) == pytest.approx(
(45.535457, -73.708698), abs=1e-6
)
assert gps.moved
gps.feed(f"{north}\r\n".encode(), now=129.0) # inside the interval: held
assert gps.node.prefs.latitude == pytest.approx(45.535457, abs=1e-6)
gps.feed(f"{north}\r\n".encode(), now=130.0)
assert gps.node.prefs.latitude == pytest.approx(45.537123, abs=1e-6)
def test_an_interval_of_zero_takes_every_fix_once_a_second() -> None:
"""``0`` is the firmware's default and its one second, not a flood of writes."""
gps = radionode.Gps("/dev/serial0", 115200)
gps.node = _gps_node()
gga = _sentence("GNGGA,010203.00,4532.1274,N,07342.5219,W,1,09,0.9,40,M,,M,,")
gps.feed(f"{_MONTREAL}\r\n".encode(), now=10.0)
gps.node.prefs.latitude = 0.0 # so a second take would show
gps.feed(f"{gga}\r\n".encode(), now=10.5) # the same second's other sentence
assert gps.node.prefs.latitude == 0.0
gps.feed(f"{gga}\r\n".encode(), now=11.0)
assert gps.node.prefs.latitude == pytest.approx(45.535457, abs=1e-6)
def test_a_sentence_split_across_reads_is_read_whole() -> None:
"""A read ends wherever the UART's buffer did, which is rarely at a newline."""
gps = radionode.Gps("/dev/serial0", 115200)
gps.node = _gps_node()
data = f"{_MONTREAL}\r\n".encode()
gps.feed(data[:20], now=1.0)
assert not gps.moved
gps.feed(data[20:], now=1.0)
assert gps.moved
def test_the_settings_come_and_go_by_the_firmware_s_names() -> None:
"""``gps_enabled`` and ``gps_interval`` in ``prefs.json``; ``gps`` says what *runs*."""
gps = radionode.Gps("/dev/serial0", 115200, {"gps_enabled": 1, "gps_interval": "45"})
assert (gps.enabled, gps.interval_s) == (True, 45)
assert gps.saved() == {"gps_enabled": 1, "gps_interval": 45}
# Switched on but not (yet) open: a port that failed at start reads off, honestly.
assert gps.custom_vars() == {"gps": "0", "gps_interval": "45"}
junk = radionode.Gps("/dev/serial0", 115200, {"gps_enabled": "yes", "gps_interval": None})
assert (junk.enabled, junk.interval_s) == (False, 0)
@pytest.mark.parametrize(
("value", "accepted", "interval"),
[("60", True, 60), ("0", True, 0), ("99999", True, 86400), ("-5", True, 0), ("soon", False, 7)],
)
def test_the_interval_is_bounded_as_the_firmware_bounds_it(
value: str, accepted: bool, interval: int
) -> None:
"""``constrain(…, 0, 86400)``, and a value that isn't a number refused outright."""
gps = radionode.Gps("/dev/serial0", 115200, {"gps_interval": 7})
assert gps.set_var("gps_interval", value) is accepted
assert gps.interval_s == interval
def test_switching_on_a_port_that_will_not_open_is_refused(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""The companion answers an error, and the switch stays where it was."""
gps = radionode.Gps("/dev/serial0", 115200)
def refuse() -> None:
raise OSError("[Errno 13] Permission denied: '/dev/serial0'")
monkeypatch.setattr(gps, "start", refuse)
assert gps.set_var("gps", "1") is False
assert gps.enabled is False
assert gps.set_var("gps", "maybe") is False
assert gps.set_var("gps", "0") is True and gps.enabled is False
@dataclasses.dataclass
class _GpsPrefs:
"""Enough of ``NodePrefs`` for a position."""
node_name: str = "MeshTerm"
latitude: float = 0.0
longitude: float = 0.0
class _Library:
"""The two custom-variable methods of the library's companion, and its preferences."""
def __init__(self) -> None:
self.prefs = _GpsPrefs()
self._custom_vars: dict[str, str] = {"other": "x"}
def get_custom_vars(self) -> dict[str, str]:
return dict(self._custom_vars)
def set_custom_var(self, name: str, value: str) -> bool:
self._custom_vars[name] = value
return True
def test_a_gps_board_lists_its_two_variables_and_saves_them(tmp_path: Path) -> None:
"""Device config finds ``gps`` where firmware puts it, and a change outlives a restart."""
gps = radionode.Gps("/dev/serial0", 115200)
node = radionode._persistent_companion(_Library, tmp_path, gps)()
gps.node = node
assert node.get_custom_vars() == {"other": "x", "gps": "0", "gps_interval": "0"}
assert node.set_custom_var("gps_interval", "120") is True
saved = json.loads((tmp_path / "prefs.json").read_text(encoding="utf-8"))
assert saved == {
"node_name": "MeshTerm",
"latitude": 0.0,
"longitude": 0.0,
"gps_enabled": 0,
"gps_interval": 120,
}
assert node.set_custom_var("gps_interval", "soon") is False # refused: nothing saved
assert node.set_custom_var("other", "y") is True # not the GPS's: the library's own
assert node.get_custom_vars()["other"] == "y"
def test_a_board_with_no_gps_lists_none(tmp_path: Path) -> None:
"""Firmware lists ``gps`` only where it found a receiver; so does the node."""
node = radionode._persistent_companion(_Library, tmp_path)()
assert node.get_custom_vars() == {"other": "x"}
node._save_prefs()
assert "gps_enabled" not in json.loads((tmp_path / "prefs.json").read_text(encoding="utf-8"))
@pytest.mark.skipif(not hasattr(os, "openpty"), reason="needs a POSIX pseudo-terminal")
def test_the_receiver_is_read_from_a_real_terminal() -> None:
"""The port is opened raw at its speed and read on the loop, as the Cap's UART is."""
master, slave = os.openpty()
port = os.ttyname(slave)
gps = radionode.Gps(port, 115200)
gps.node = _gps_node()
async def run() -> None:
assert gps.set_var("gps", "1") is True
assert gps.custom_vars()["gps"] == "1"
os.write(master, f"{_NO_FIX[0]}\r\n{_MONTREAL}\r\n".encode())
for _ in range(50):
if gps.moved:
break
await asyncio.sleep(0.02)
gps.set_var("gps", "0")
try:
asyncio.run(run())
finally:
os.close(master)
os.close(slave)
assert gps.node.prefs.latitude == pytest.approx(45.535457, abs=1e-6)
assert not gps.running and gps.custom_vars()["gps"] == "0"
+50
View File
@@ -156,3 +156,53 @@ def test_offer_stays_quiet_when_nothing_is_remembered(tmp_path: Path, monkeypatc
shown = _run(_ctx(store, device), monkeypatch)
assert shown == [] and device.coords_writes == []
class _GpsDevice(_ScriptedDevice):
"""A companion with a GPS, reporting its ``gps`` switch as the firmware does."""
def __init__(self, *, gps: str, **kwargs) -> None: # noqa: ANN003
super().__init__(**kwargs)
self._gps = gps
async def get_custom_vars(self) -> dict[str, str]:
return {"gps": self._gps, "gps_interval": "0"}
def test_offer_leaves_a_position_the_gps_moved_alone(tmp_path: Path, monkeypatch) -> None:
"""With its GPS running, a node somewhere else is a reading: no prompt and no write."""
store = SettingsStore(tmp_path / "settings.json")
store.remember(_PUB, "adv_lat", _LAT)
store.remember(_PUB, "adv_lon", _LON)
device = _GpsDevice(gps="1", adv_lat=46.813878, adv_lon=-71.207981)
shown = _run(_ctx(store, device), monkeypatch)
assert shown == [] and device.coords_writes == []
assert store.settings(_PUB) == {"adv_lat": _LAT, "adv_lon": _LON}
def test_offer_still_asks_about_a_moved_position_with_the_gps_off(
tmp_path: Path, monkeypatch
) -> None:
"""A GPS that isn't running moved nothing, so a different position is a real conflict."""
store = SettingsStore(tmp_path / "settings.json")
store.remember(_PUB, "adv_lat", _LAT)
store.remember(_PUB, "adv_lon", _LON)
device = _GpsDevice(gps="0", adv_lat=46.813878, adv_lon=-71.207981)
shown = _run(_ctx(store, device), monkeypatch)
assert len(shown) == 1 and {d.key for d in shown[0]} == {"adv_lat", "adv_lon"}
def test_a_gps_with_no_fix_yet_still_gets_the_saved_position(tmp_path: Path, monkeypatch) -> None:
"""Before its first fix the node reports none, and the saved one holds until it comes."""
store = SettingsStore(tmp_path / "settings.json")
store.remember(_PUB, "adv_lat", _LAT)
store.remember(_PUB, "adv_lon", _LON)
device = _GpsDevice(gps="1", adv_lat=0.0, adv_lon=0.0)
shown = _run(_ctx(store, device), monkeypatch)
assert shown == [] and device.coords_writes[-1] == (_LAT, _LON)
+42 -1
View File
@@ -23,7 +23,7 @@ from meshterm.core import spiradio
from meshterm.core.admin_store import AdminStore
from meshterm.core.config import DeviceProfile, Settings, SpiWiring
from meshterm.core.device_store import DeviceStore
from meshterm.core.discovery import TRANSPORT_SPI, spi_device
from meshterm.core.discovery import TRANSPORT_SPI, DiscoveredDevice, spi_device
from meshterm.persistence.repository import Repository
# --- wiring --------------------------------------------------------------------------------
@@ -304,6 +304,47 @@ def test_the_cardputer_cap_wiring_is_the_one_the_hardware_answered_on() -> None:
assert cap.leds == ("ext_5v_out=1", "ext_usb_gpio_fun=0")
assert (cap.pi4io_bus, cap.pi4io_address, cap.pi4io_high) == (1, 0x43, (0,))
assert cap.use_dio2_rf and cap.use_dio3_tcxo
# Its GPS, read at 115200 on the header's UART while the Cap was powered.
assert (cap.gps_port, cap.gps_baud) == ("/dev/serial0", 115200)
def test_a_board_s_gps_comes_from_the_table() -> None:
"""A GPS beside the radio is wiring too: a port and the speed it talks at."""
wiring = SpiWiring.from_toml({"gps_port": "/dev/ttyAMA0", "gps_baud": 38400})
assert (wiring.gps_port, wiring.gps_baud) == ("/dev/ttyAMA0", 38400)
assert (SpiWiring().gps_port, SpiWiring().gps_baud) == ("", 9600) # none, NMEA's speed
with pytest.raises(ValueError, match="gps_baud = 'fast' is not a int"):
SpiWiring.from_toml({"gps_baud": "fast"})
@pytest.fixture()
def serial0(monkeypatch: pytest.MonkeyPatch) -> None:
"""``/dev/serial0`` as Raspberry Pi OS makes it: a link to the UART the scan reports."""
links = {"/dev/serial0": "/dev/ttyS0"}
monkeypatch.setattr(spiradio.os.path, "realpath", lambda p: links.get(p, p))
#: The Cap's GPS as pyserial reports it: a header UART with no USB identity, so "n/a".
_GPS_PORT = DiscoveredDevice(port="/dev/ttyS0", description="n/a", hwid="n/a")
_USB_BOARD = DiscoveredDevice(port="/dev/ttyACM0", description="T1000-E", vid=0x239A)
def test_the_cap_s_gps_is_part_of_the_radio_not_a_companion(cardputer: Path, serial0) -> None: # noqa: ANN001
"""The port the Cap's GPS answers on is left out wherever the Cap is listed."""
assert spiradio.without_radio_ports([_GPS_PORT, _USB_BOARD], {}) == [_USB_BOARD]
def test_the_same_port_on_another_pi_is_left_listed(cardputer: Path, serial0) -> None: # noqa: ANN001
"""No Cardputer, no Cap: whatever answers on that UART is somebody else's to choose."""
cardputer.rmdir()
assert spiradio.without_radio_ports([_GPS_PORT, _USB_BOARD], {}) == [_GPS_PORT, _USB_BOARD]
def test_a_profile_s_gps_port_is_its_radio_s(cardputer: Path, serial0) -> None: # noqa: ANN001
"""A profile naming its own GPS claims that port, and the shipped Cap's is not assumed."""
mine = replace(spiradio.CARDPUTER_ZERO_CAP, gps_port="/dev/ttyACM0")
profiles = {"cap": DeviceProfile(name="cap", transport="spi", spi=mine)}
assert spiradio.without_radio_ports([_GPS_PORT, _USB_BOARD], profiles) == [_GPS_PORT]
# --- finding a Python for the node ---------------------------------------------------------