Hardware profiles and upgrades¶
The checked-in example profile is a synthetic Pi 5 hardware template.
The four serials 90000001–90000004 represent distinct HF, VHF, aviation and
SATCOM receivers. Models, route ranges, service ports, the reserved hub cascade
and the HF upconverter’s 125 MHz translation are illustrative relationships
to verify against actual hardware before using a private customized copy.
Existing installations¶
Normal --install upgrades read and validate the installed configuration:
/etc/rtl_tcp/receiver inventory;/etc/rfsentry/routes.d/and/etc/rfsentry/spurs.d/;/etc/sdr-demand.confand its USB-domain/accessory directories;- installed health, propagation and Chrony settings.
The upgrade does not republish these profile files or the profile firmware fragment. Installed public identity retains its existing precedence. Software and service upgrades still follow the existing active-client/restart procedure; this policy does not make a full installation safe during acquisition.
Edit or restore installed hardware settings explicitly before upgrading. A
partial installed inventory fails validation rather than falling back to a
public example. Supplying --profile-dir to an existing installation is rejected
before installation work: this option is not a silent hardware-replacement mode.
The selected public --profile does not replace installed hardware on upgrades.
Fresh installation or recovery onto an unconfigured host¶
Prepare a private profile directory with the same layout as the selected public
example (etc/ and boot/firmware/). Keep it outside Git, for example under the
already-ignored config/local/ directory or in private operator storage.
mkdir -p config/local
test ! -e config/local/hardware-profile && \
cp -a profiles/example config/local/hardware-profile
# Review/customize this copy: rename serial files and update every reference,
# verify USB paths, receiver roles, accessories, routes and firmware policy.
Supply your separately reviewed network identity as before:
./install.sh --check --profile-dir config/local/hardware-profile \
--appliance-config config/local/appliance.conf
sudo ./install.sh --install --profile-dir config/local/hardware-profile \
--appliance-config config/local/appliance.conf
A fresh install without --profile-dir stops rather than installing the public
example implicitly. Configuration checks establish consistency, not physical
power switching, RF coverage or qualification of the operator's replacement
hardware. Explicitly review route verification flags before enabling reception.
--check --profile NAME still validates a public example. --check --profile-dir
DIR validates a private copy without deploying it. The normal check path enables
repository Git hooks but does not write appliance configuration.
Private profiles are valid deployment inputs, not publication inputs. Ignore rules do not remove tracked or historical copies. Keep them out of package, public-asset and diagnostic upload trees; see publication checks.
Network health in the field¶
Choose the health target before disconnecting from your usual network. The example probes the IPv4 default gateway. The WAN can be offline while that gateway still answers. On a direct Pi-to-laptop link there may be no default gateway, or the peer may block ICMP. An unreachable target can trigger an interface reconnect, a NetworkManager restart and, on supported Wi-Fi, a driver reload. With the example settings the Pi can request a reboot after four minutes of sustained failure, up to three attempts.
For a field LAN with a reliable local peer, set INTERFACE to the actual
interface and TARGETS to a local address that reliably answers ping. For
example, a lab on a documentation subnet could use:
For observation only, keep HEALTH_STACK_ENABLED=yes and set both controls
in the private profile’s etc/sdr-health.conf (installed: /etc/sdr-health.conf):
The reboot budget is independent of interface remediation. Check
sdr-healthctl status for the effective interface, target and health state.
Systemd’s hardware watchdog has its own policy.
Historical evidence and live checks¶
Sanitized evidence retains measured results and original source revisions, but substituted serials, antenna labels and opaque producer/stream/run identifiers are not original observations. Such records identify the transformation and its independent-verification limits. Sanitization is not a new qualification. Source-content hashes, dependency pins, artifact digests, durations, ordering and measured counters retain their original meaning.
The live API acceptance utility obtains expected device identities from the
already-configured receiver.list inventory and its declared verified routes.
It compares session results against that configuration, checks receiver presence
and requires distinct HF/VHF receivers for two-lane tests. It does not infer an
expected identity from the session being tested. No live acquisition campaign is
needed merely to edit the public example inventory.
Upgrade preservation contract¶
Verified against install.sh, scripts/installer-profile.sh, the configuration
publisher and QoS installer:
| State | Normal upgrade behavior |
|---|---|
| Inventory, routes/spurs, demand/USB/accessories, health, propagation, Chrony | Validate installed inputs; guarded profile-copy blocks do not republish them |
| Boot firmware fragment | Profile firmware installation is skipped on an existing hardware installation |
| Appliance identity | Installed appliance.conf wins unless explicitly replaced with --appliance-config; .example is never imported |
| API policy | Publisher merges managed identity keys and missing defaults while preserving explicit unrelated settings |
| TLS/PKI | Valid matching trust material is reused; invalid/incompatible material is validated/prepared transactionally before service stops |
| QoS | Existing qos.conf survives; service/rule integration is updated |
| Token and UUID | Existing nonempty token and existing UUID are retained; missing state is created; ownership/permissions may be repaired |
| Continuous jobs | Stream/record directories are ensured; definitions, identities and enabled intent are not seeded from the example |
| Software and managed integration | Binaries, services, dataset updater configs, watchdog/status and modprobe/journald integration may be updated |
This is not byte-for-byte preservation of all /etc. Full installation stops
services and interrupts acquisition even with --no-start; without it, enabled
jobs resume and interactive clients must reconnect. Retired explicit profile
selectors fail before writes; an existing-install --profile-dir is rejected
rather than silently replacing hardware policy. No compatibility alias is supplied.
Operator convenience copies ~/README.md and ~/WEBSDR.MD are generated from
single repository sources and link to the installed static documentation tree.
Source/layout and detectable destination problems are rejected during preflight;
missing built pages are rejected before services stop. Existing backup and copy
semantics remain. Tests use synthetic temporary trees and stubbed operations;
they do not simulate every package, disk, permission race or hardware failure.