EmComm Field Node Provisioner v1.0.5

EmComm Field Node Provisioner v1.0.5

The first public release. The provisioner does exactly what v1.0.4 did: same
steps, same checks, same files written. What changed is everything around it. The
repository is now written for someone arriving without context, and two helper
scripts are licensed so they can be reused on their own.

Licensing

The provisioner is licensed under GPL-3.0-or-later (LICENSE). Two standalone helper
scripts — scripts/fetch_map_tiles.py and scripts/diagnose_qmapshack_maps.py — are
licensed under the MIT License (LICENSE-MIT), so they can be reused in tools that cannot
take on GPL-3.0. Organizations whose policy does not permit GPL-3.0 software can request
separate terms: see "Alternative licensing" in README.md.

File	v1.0.4	v1.0.5
deploy_emcomm_node_gui.py	GPL-3.0-or-later	GPL-3.0-or-later
scripts/fetch_map_tiles.py	GPL-3.0-or-later	MIT
scripts/diagnose_qmapshack_maps.py	GPL-3.0-or-later	MIT

• LICENSE is unchanged.
• Both license files are in the tarball.
• Each MIT script carries the full permission text in its own header.

Neither license is a license to transmit.

A README for someone arriving cold

• New order: what a node does, the quick start, and where the documentation is come first. Platform and detail follow.
• Dock trigger: now scoped to the step it belongs to, with every caveat intact.
• Checklist link: the Pre-Deployment Config Checklist is linked from the README. It wasn't before.
• Fix: an empty table in scripts/Packages/README.md that rendered as a blank box now shows its contents.

American English throughout

Prose, comments, docstrings and on-screen text now use US spelling. Not synchronised
is left as written wherever it quotes chronyc tracking, because that is what the
program prints.

A v1.0.5 run log reads slightly differently from a v1.0.4 one ("canceled", "centered").
The steps and their results are the same.

For contributors

The repository gains CONTRIBUTING.md, SECURITY.md and two issue forms, one for a
failed run and one for a field report.

• Run logs: the forms ask for the run log and, in the same place, ask you to scrub it first: callsign, grid square, device serial numbers, home paths.
• Security: SECURITY.md treats anything that could key a transmitter unintentionally as a security issue.

None of these files is in the tarball. They're for working on the repository, not for
running a node.

Upgrading from v1.0.4

Nothing needs to be re-run. No step, check or configuration format changed, so a node
provisioned with v1.0.4 is already what v1.0.5 would produce. Replace your copy to pick
up the documentation and licensing. The version on the summary screen and in the run log
becomes 1.0.5.

Verifying this download

1f581c6d8e35cc8107ec9d5bd55c1b43e098a4434bc550d9149bd959081a3fc7  emcomm-field-node-1.0.5.tar.gz

Download the tarball, its .sig and SHA256SUMS, then follow "Verifying a release
download" in README.md:

sha256sum -c SHA256SUMS
ssh-keygen -Y verify -f allowed_signers -I release@emcomm-field-node \
    -n file -s emcomm-field-node-1.0.5.tar.gz.sig \
    < emcomm-field-node-1.0.5.tar.gz

Both should pass; the second prints Good "file" signature. If either fails, do not
run the provisioner — report it on the issue tracker.

The tarball is a git archive of tag v1.0.5, so its contents can be compared against
the tag directly.

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.
• 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 through 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, with two helper scripts under MIT.

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.

EmComm Field Node Provisioner v1.0.3

EmComm Field Node Provisioner v1.0.3

Offline maps now reach QMapShack.

• Settings are written to ~/.config/QLandkarte/, the directory QMapShack reads
• The map directory is registered and both tile sources are listed
• The first view opens on your operating area, with a UTM grid
• Tile sources resolve paths by substitution instead of a script

Correction

This release registers the map sources; it does not activate one on the
QMapShack version Linux Mint ships. 1.17.1 reads the legacy map\active
key, and this tree writes only the map2\... group that 1.20 and later use.
On a stock node the sources appear in the map list and the topographic layer
draws after you select it once — not on first launch.

The bullet above originally read "a map source is set to draw", and the
verification note below read "topographic layer active". Both were recorded from
a session where the layer had been selected by hand. The tiles, the path
substitution, the view centering and the UTM grid were not in doubt and are
unchanged — only the activation claim was wrong, and a listed source looks
much like an active one at a glance.

main now writes both key groups, and the layer has been observed drawing
unselected on a separate node running the hand-ported equivalent of that fix,
not yet on an EmComm node. It ships in the next release.

Verified on a VM

Offline maps drawing from local tiles with no network, on a VM carrying a
20,000-tile pyramid: sources listed, topographic layer drawing once selected,
view on the operating area, UTM grid with metric readout.

Not verified

Anything needing a radio on the air. Verification checks the filesystem, not RF.

Upgrading from v1.0.2

Clear ~/.config/QLandkarteGT/ if present — nothing read it.

Re-run the map step, then App profiles + ALE channel plan, in that order.
Tiles already on disk are skipped, so the map step costs seconds.

Before you deploy a node

configs/ ships empty by design — supply your own profiles, and read the
placeholder contract in configs/README.md first. Then work the
Pre-Deployment Config Checklist.

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

EmComm Field Node Provisioner v1.0.2

EmComm Field Node Provisioner v1.0.2

Adds mesh peer positions on the map, makes the dock automation's untested status
impossible to miss, and fixes an SDR tool that was missing on exactly the nodes
that needed it.

What's changed

New: Meshtastic → GPX bridge. When both Meshtastic and QMapShack are installed,
a user service (emcomm-mesh-gpx.service) polls the node database every 120s and
writes EMCOMM_Data/Meshtastic/mesh_nodes.gpx for import into a QMapShack project.
Peer positions reach the map as a file, not a live feed — gpsd's client protocol
carries no waypoint object, so $GPWPL peer sentences cannot get there, and
QMapShack reads TCP NMEA rather than gpsd. Installed only when QMapShack is present;
skipped with a message otherwise. It never holds the serial port: each poll opens,
reads and closes, and skips a cycle if something else has the radio, so it cannot
block an interactive meshtastic command.

Meshtastic CLI now installs to the user site. python3 -m pip install --user --break-system-packages meshtastic replaces the virtualenv. The meshtastic console
script lands on ~/.local/bin and is importable by the system python3 the bridge
runs under.

rtl-sdr is installed by either SDR step. rtl_test is the command this node's
own documentation tells you to run when checking dongle contention, and it was absent
on a node that selected SatDump or dump1090 without system packages — the check the
docs prescribe was "command not found". Verification now asserts rtl_test is on
PATH, not merely that a package is installed.

Dock-triggered autostart is stated as a future feature. It is being designed for a
Panasonic CF-30 in a Havis DS-PAN-111 dock; that is a design target, not a tested
configuration. The step still installs and stays selectable, but it now says what it
is at the moment it runs, the options-screen label carries the mark, and verification
carries a row that warns rather than four rows that pass. A run with that step selected
therefore finishes as "complete — review warnings".

Corrected: what claims the Meshtastic USB port. Earlier guidance said gpsd matches
USB-serial bridge chips and would take the port. On Debian and Mint it does not — the
generic PL2303/FTDI/CP210x rules in /usr/lib/udev/rules.d/60-gpsd.rules are commented
out. Measured on a Seeed Wio Tracker L1 Pro: nothing claims the port. ModemManager flags
the board and declines it. NMEA output still stays off, but because the integration it
exists for does not work, not because of contention.

One login gates three things

PATH, group membership and user services are all read at login, so a fresh node needs a
logout or reboot before any of this works — and each symptom points away from the shared
cause: meshtastic reads as "command not found" (~/.local/bin joins PATH from
~/.profile only if it existed at login), the CLI hits permission errors (dialout not
yet in effect), and the GPX service has not started (enabled, deliberately not started).
The verification screen now says so on the way out.

Verified on hardware

• SatDump 1.2.2 builds under the provisioner; RTL-SDR visible in the recorder, live spectrum
• dump1090 tracking live traffic — 61 aircraft, 198 msg/sec — startable on demand and
  releasing the dongle cleanly
• DVB-T blacklist survives an unplug/replug: the device comes back unclaimed and ready
• Reboot leaves the dongle usable — confirmed on a Toughbook, bare metal, cold boot with
  the dongle attached
• Meshtastic CLI reaches a Wio Tracker L1 Pro first try, no service contending for the port

Not verified

• Dock-triggered autostart has never been observed firing — on any hardware, including
  the reference Toughbook and dock. It installs and verifies present; whether a dock event
  launches anything is unknown. Opt-in, and nothing else depends on it.
• The GPX bridge has never been driven by a radio. Its GPX output, conditional install
  and failure paths are tested against recorded node data; a live mesh has not been in the
  loop. Whether QMapShack notices the file changing on disk is assumed false and documented
  as an assumption.
• The user-site Meshtastic install has not been through a provisioning run. PEP 668
  enforcement is a distro patch; confirm the console script lands at
  ~/.local/bin/meshtastic on first use.
• Anything needing a radio on the air. Verification checks the filesystem, not RF.

Upgrading from v1.0.1

Re-running the Meshtastic step replaces the old virtualenv wrapper with pip's own console
script at the same path. The previous EMCOMM_Apps/meshtastic-venv/ directory is not
removed and is no longer used — delete it by hand if you want the space back. A node that
does not re-run that step is unaffected and keeps working.

Before you deploy a node

configs/ ships empty by design — supply your own profiles, and read the placeholder
contract in configs/README.md first. Then work the Pre-Deployment Config Checklist.

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

v1.0.1

What's Changed

• Put the release version on the summary screen and the run log by @stevejun1986 in #20
• Make a long summary reachable instead of silently clipped by @stevejun1986 in #22
• Port four dump1090 fixes from the hand-ported equivalent by @stevejun1986 in #23
• SatDump: separate "a binary exists" from "make install succeeded" by @stevejun1986 in #25
• SatDump: tell the operator to launch it once before going offline by @stevejun1986 in #27
• Install rtl-sdr, so the check this repository documents exists by @stevejun1986 in #28
• Pin the SatDump source build to an upstream tag by @stevejun1986 in #29
• Say who holds the RTL-SDR dongle, and stop the kernel taking it by @stevejun1986 in #30
• Gate SatDump's TLE fetch suppression on a curated set existing by @stevejun1986 in #32

Known untested: dock-triggered autostart

The dock-trigger step installs a udev rule, a dispatcher, a systemd user unit and an
autostart sequence, and post-deployment verification confirms all four are present.

No dock insertion has ever been observed firing that chain — on any hardware,
including the reference Panasonic CF-30 in a Havis DS-PAN-111 dock. The step installs
cleanly and verifies cleanly; whether docking actually launches anything is unverified.

It is opt-in and off unless selected, and nothing else depends on it. Every other step
— packages, profiles, offline maps, the document server, Direwolf, Meshtastic, SatDump,
dump1090 — is unaffected.

If you have the hardware, TESTING.md has a section that walks the chain link by link,
including a way to exercise most of it without a dock. Reports welcome.

Verifying this download

sha256 bd1dcbc82f377581a63635d0766d4a97380355edf3adb0bc655f3f0e89eafc47

emcomm-field-node-1.0.1.tar.gz.sig is a detached signature over the tarball.

Full Changelog: v1.0.0...v1.0.1

v1.0.0

This release marks the first complete run in testing for all intended software and background scripts. Further testing and refinement may be needed moving forward.

EmComm Field Node Provisioner v1.0.0

First release. A single Python/Tkinter script that turns a clean Linux Mint
install into an offline-capable emergency communications workstation — digital modes,
HF logging, offline maps and reference library, SDR, mesh — in one pass, verified on
the way out.

README.md covers the stack, requirements and setup. This note covers what has
actually been exercised, because that is what you cannot see from a file listing.

Verified on hardware

One machine, one operator. Everything below was observed working on a real node with
an RTL-SDR attached:

• Provisioning completes and the post-run verification reports honestly
• dump1090 tracking live traffic, startable on demand and releasing the dongle cleanly
• SatDump built from source, dongle visible in the recorder, full TLE set loaded
• Offline maps, document server and knowledgebase serving with the network pulled

Not verified

• Dock-triggered autostart has never been observed firing — on any hardware,
  including the reference Toughbook and dock. It installs and verifies present; whether
  a dock event launches anything is unknown. Opt-in, and nothing else depends on it.
• Anything needing a radio on the air. Verification checks the filesystem, not RF.

Before you deploy a node

configs/ ships empty by design — supply your own profiles, and read the placeholder
contract in configs/README.md first. Then work the Pre-Deployment Config Checklist;
it covers every step that needs hardware, a radio, or a network connection before a
node goes out.

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

Full Changelog: https://github.com/stevejun1986/emcomm-field-node/commits/v1.0.0