EmComm Field Node Provisioner v1.0.4

EmComm Field Node Provisioner v1.0.4

The offline map now draws on first launch, and the radio interface is declared
instead of guessed at.

Offline maps draw without being clicked

v1.0.3 registered the map sources but could not activate one on the QMapShack
version Linux Mint ships. 1.17.1 reads the legacy map\active key; that tree
wrote only the map2\... group, which 1.20 introduced. The sources appeared in
the Maps tab and the canvas stayed empty until the operator selected a layer —
a quiet failure that looks like success, because a listed source and an active
one are hard to tell apart at a glance.

Both key groups are written now, and the zoom index with them.

Observed on hardware, on a separate node running the hand-ported equivalent of
this step: logged out, logged back in, opened QMapShack 1.17.1, clicked nothing —
the topographic layer drew, centered on the operating area, at the seeded zoom. It
has not yet been observed on an EmComm node.

A second fault landed alongside it. The saved-view check matched a literal
View 1 while QSettings writes View%201, so on any node where QMapShack had
already been opened once, a re-run wrote a second posFocus over the
operator's own saved view. Both spellings are recognized now.

The radio interface is declared, not guessed

PTT CM108 never keyed a Digirig Mobile. The Mobile is a USB hub carrying
two devices — a CM108-based sound card and a CP2102 serial bridge — and its
PTT is an open-collector switch on that serial port's RTS line, not a CM108
GPIO. The chip that makes CM108 look like the obvious answer is the audio
chip. The card index shipped beside it, plughw:1,0, was also a guess, and
moves whenever another USB audio device appears.

Both values now come from configs/radio.conf, which you fill in:

ADEVICE=plughw:CARD=Device,DEV=0
PTT_DEVICE=/dev/serial/by-id/usb-Silicon_Labs_CP2102_..._-if00-port0
PTT_METHOD=RTS

configs/radio.conf.sample ships with the values empty and explains where each
one comes from. The filled-in file is excluded from version control, because a
by-id path carries the interface's serial number.

Declared, never probed. Opening a serial port asserts its control lines,
and this interface keys a transmitter from one of them — so nothing in the
provisioner scans ttyUSB* looking for a radio. It reads your declaration,
substitutes it, and checks the paths exist. To help you fill the file in, the
step reports what it can see read-only: /proc/asound/cards and a listing of
/dev/serial/by-id/.

Use a by-id path, not /dev/ttyUSB0. A GPS receiver and a radio interface
both enumerate as ttyUSB*, and which one gets ttyUSB0 depends on the order
they were plugged in. Verification warns on a numbered path.

ModemManager is kept off the interface

ModemManager probes an unknown serial port by writing AT commands to it.
Writing opens the port, opening asserts RTS, and RTS is what keys the
transmitter — so a probe is capable of putting a station on the air that nobody
asked to transmit.

The Direwolf step now writes a udev rule excluding the declared interface,
matched on the ID_SERIAL that udev builds the by-id path from. The match is
derived from configs/radio.conf, so the rule is written without scanning the
bus and without opening anything.

It applies at the next device event, not retroactively — which is one more
reason to get the node configured with no radio attached.

Direwolf: three faults a bench run found

All three were found on a bench run of a separate node running the hand-ported
equivalent of this step. They need a node that already has direwolf installed,
which is why a clean machine never showed them:

• The configuration block sat behind apt's exit status, so a run where apt
  returned non-zero wrote no direwolf.conf at all — on a machine that already
  had direwolf and could use one. The install and the configuration are two
  things; the config is now written whenever direwolf is present.
• "Direwolf install failed" asserted a cause from an exit code. A non-zero apt
  exit says the transaction ended badly, not that the package is absent or
  broken. It now reports the status and says so.
• apt's own output was captured and then discarded, while the message pointed
  at a log that had nothing in it. The last twelve lines are printed now.

A white paper ships in the archive

EmComm_Field_Node_Whitepaper.pdf — what a field node is for, who deploys one,
what a provisioned node can do, and an explicit account of what has been
observed on hardware versus what has been written and checked but never
exercised. The markdown source and its renderer ship beside it.

Upgrading from v1.0.3

• Re-run App profiles + ALE channel plan to pick up the map activation fix.
  That is the step that registers the map sources; tiles already on disk are
  untouched, so it costs seconds.
• For the radio binding: copy configs/radio.conf.sample to
  configs/radio.conf, fill in ADEVICE and PTT_DEVICE, then re-run
  Direwolf. arecord -l and ls -l /dev/serial/by-id/ give you both
  values without plugging anything in.
• Nothing needs reinstalling, and no provisioned node is broken by this release.

Not verified

• No radio has been keyed, by this release or any other. The audio and PTT
  bindings are declared, substituted and path-checked. Nothing in this project
  has put a signal on the air, and the ModemManager rule preventing a stray
  keying event is reasoning rather than an observation.
• Dock-triggered autostart has never fired, on any hardware. It installs
  and verifies, and ships documented as a future feature.
• Verification checks the filesystem, not radio frequency. No automated
  check covers anything requiring a transmitter or an antenna.

Before you deploy a node

configs/ and docs/ ship empty by design — supply your own profiles and
document set, and read the placeholder contract in configs/README.md first.
Then work the Pre-Deployment Config Checklist; sections 3 and 4 cover the
audio device and PTT keying, including why the radio stays disconnected until
the node is configured.

Issues and field reports welcome. GPL-3.0-or-later.