Skip to content
HamSCIPublic

About

Signal Monitor Daemon for HamSCI

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Sigmond

SigMonD (Signal Monitor Daemon) is the installer, lifecycle manager, and coordinator for the HamSCI SDR observation suite.

Sigmond manages a family of independent clients that share the DASI2 station hardware. DASI2 is the NSF-funded Distributed Array of Small Instruments, Track 2 project — a station is a ka9q-radio receiver on an RX888 SDR (GPSDO-disciplined, TS-1 time-injected) plus a magnetometer. Each client records a different signal type — WSPR, FT8/FT4, HF time standards, magnetic field, CODAR, HFDL, beacon TEC, meteor scatter — and sigmond handles the parts that require coordination between them: installation, service lifecycle, log aggregation, diagnostics, timing-authority distribution, the shared SQLite sink, and resource (CPU) arbitration.

Install a station

Two ways, both current:

  • A dedicated mini-PC, from the USB image. The image turns the machine into a Proxmox host with the station in a VM; you answer a few questions and it does the rest. Follow sigmond-appliance INSTALL.md.
  • A Linux machine you already run (bare metal). Sigmond installs from these repositories onto your own Debian. Follow docs/install-bare-metal.md.

Who are you? Station host → Operator guide · Scientist wanting a signal recorded → Scientist guide · Developer → CONTRIBUTING.md. Full map: docs/README.md.

Architecture at a glance

Sigmond / DASI2 station architecture

The DASI2 hardware kit (DXE antenna → RX888 SDR, disciplined by an LB-GPSDO and time-injected by a TS-1, plus a magnetometer) feeds ka9q-radio (radiod), which multicasts per-channel RTP streams. Every RF client subscribes via ka9q-python; mag-recorder is the one client that reads its sensor directly (USB-I²C) rather than through radiod.

  • Core clients: hf-timestd (timing authority — publishes the RTP↔UTC offset and tier that the other RF clients label against), wspr-recorder, psk-recorder, mag-recorder, meteor-scatter, hamsci-physics, hfdl-recorder, codar-sounder.
  • Additional clients: hf-tec, superdarn-sounder.

Decoded spots and products land in a shared SQLite sink (/var/lib/sigmond/sink.db), and hs-uploader ships them upstream. WSPR, FT4/FT8 and MSK144 spots go to wsprdaemon.org, which forwards copies to wsprnet.org and pskreporter.info; GRAPE and magnetometer products go to PSWS / HamSCI. hfdl-recorder and codar-sounder send their timing rows to wsprdaemon.org the same way. hfdl-recorder can also feed airframes.io directly through dumphfdl; that feed stays off until the operator turns it on. Sigmond is the oversight layer wrapping the whole software stack: install, configure, lifecycle, CPU-pinning, and the shared sink.

The diagram source is docs/architecture.svg (editable vector, drops straight into slides); a raster copy is at docs/architecture.png.

What you need

Hardware:

  • An HF antenna
  • An RX-888 (or other SDR supported by ka9q-radio)
  • A GPS disciplined oscillator (e.g. Leo Bodnar GPSDO) providing 10 MHz + PPS
  • A Linux computer (Debian 12+ or Ubuntu 22.04+)

Full list with models, what is optional, and what B4 runs: docs/hardware/shopping-list.md

Software prerequisites:

  • Python 3.11 or later
  • git
  • systemd
  • chrony (for time-standard work)

Quick start

These are the bare-metal steps with their details; docs/install-bare-metal.md puts them in order with what each does to your machine. For the USB image, see Install a station.

1. Install sigmond

Sigmond installs at /opt/git/sigmond/sigmond/, peer to its managed components. Clone and install from there:

sudo mkdir -p /opt/git/sigmond
sudo chown $USER /opt/git/sigmond
git clone https://github.com/HamSCI/sigmond /opt/git/sigmond/sigmond
cd /opt/git/sigmond/sigmond
./install.sh

install.sh creates a sigmond system user that owns /opt/git/sigmond/*, adds you to the sigmond group so you can edit sources as yourself, sets up /opt/git/sigmond/sigmond/venv, and symlinks smd to /usr/local/bin/smd. Open a new shell after install (or newgrp sigmond) to pick up the group membership.

Running under Proxmox? install.sh detects KVM guests and offers to configure the Proxmox host (PCIe passthrough, CPU isolation, vfio, hookscript) before installing sigmond — one prompt, one host reboot, automatic resume. See docs/installation-guide.md "Running under Proxmox VE? Read this first."

2. Bring up the station

One command installs, configures and starts a whole station on this machine. It works the same on bare metal and inside a VM:

smd bringup dasi2 --callsign AC0G --grid EM38ww --reporter AC0G/S \
                  --psws-station-id S000418 \
                  --psws-instrument hf-timestd=367 \
                  --psws-instrument mag-recorder=401

Use your own callsign, grid square, reporter ID and PSWS ids. The PSWS flags matter only if you upload to PSWS: one station ID for the site, and one instrument ID per product under it (the RX888 for hf-timestd, the magnetometer for mag-recorder). Bring-up writes them to /etc/sigmond/site-profile.toml and into each recorder's config; smd config psws sets them later. dasi2, the default profile, gives you a local radiod, hf-timestd (GRAPE), WSPR, FT4/FT8, meteor scatter, HFDL and CODAR timing, and the magnetometer. base stops at radiod and timing; client decodes from radiods on other machines; see "Decode-only host" below. Bring-up skips, with a warning, anything whose hardware it cannot find on the USB bus.

Bring-up also sets up remote access when it runs on bare metal. It runs sigmond-rac activate, which registers the machine with the gateway and starts its tunnel. A Proxmox appliance VM skips this step, because its host carries the machine's remote access. If registration fails, bring-up still finishes, and a retry timer keeps trying.

The machine's remote-access name puts the callsign and the hostname together in upper case, as in AC0G-SIGMA or AC0G-B2. A hostname that already starts with <CALL>- stands alone. Once sigmond-rac activate records the name, the name sticks. A hostname of localhost, or one equal to the callsign, gives no default; pass --site.

smd remote status shows whether remote access is on, and smd remote on or smd remote off switches it. Type these as yourself, never with sudo. The switch changes system files, so smd asks for root through sudo on its own and may ask for your password.

A machine that runs only radiod and ka9q-web never runs bring-up. On such a machine, run this once:

sudo /opt/git/sigmond/sigmond/scripts/rac/sigmond-rac activate --site AC0G-B1

The design explains the channels, the ports and the exit codes.

Add --dry-run to see every step first. Add --non-interactive to accept radiod's defaults instead of answering its questions.

If the station uploads to PSWS, put each instrument's ID in /etc/sigmond/site-profile.toml and render it into the client configs:

[psws.instruments]
"hf-timestd"   = "<GRAPE instrument id>"
"mag-recorder" = "<magnetometer instrument id>"
smd config render

Decode-only host

A decode-only host runs no radiod of its own. It decodes from radiods on other machines on the LAN. Name each radiod it should use; the option may repeat:

smd bringup client --callsign AC0G --grid EM38ww \
    --remote-radiod ac0g-b1-a-status.local --remote-radiod ac0g-b1-b-status.local

Bring-up browses the LAN for radiods and prints every one it finds, with its host and advertised name. An unattended install (--non-interactive, or no terminal) binds only the radiods you name, and with none named it stops after printing the list, so you can choose from it. A named radiod that does not answer stops bring-up before it installs anything.

On a terminal with no radiods named, bring-up proposes the ones whose advertised name starts with your callsign, so a radiod that advertises "AC0G @EM38ww B1-a longwire" belongs to AC0G. The first word must equal the callsign; a radiod that advertises a reporter ID such as "AC0G/S RX-888 Mk2" never gets proposed. Check the proposal before you accept it: every radiod on your LAN that advertises your callsign gets proposed, whichever machine it runs on. Bring-up prints one line for each radiod it would keep, with the radiod's host, its advertised name and the reason, then asks before it binds them.

Each kept radiod gets one instance of each per-reporter recorder the profile carries. The client profile carries two: wspr-recorder (WSPR) and psk-recorder (FT4/FT8). It also installs hfdl-recorder and codar-sounder, which run one instance per radiod named in their own config files; smd start starts one for each. Bring-up names the instances after the radiod: ac0g-b1-a-status.local gives the reporter ID AC0G/B1A. With a single radiod, --reporter still sets the name. With several, --reporter counts as an error, because one name cannot cover two instances.

hf-timestd takes its timing from one radiod. With one kept radiod it uses that one. With several, name it with --timing-radiod <status name>. Without that, bring-up installs hf-timestd, leaves it idle and says so.

Bring-up records each radiod with smd admin sources bind, and you can run it yourself:

smd admin sources bind ac0g-b1-a-status.local --reporter AC0G/B1A [--timing]

The verb writes the radiod into /etc/sigmond/coordination.toml. For each recorder enabled here (or each one named with --clients), it makes the instance, selects the radiod as its source and points the instance's config at it. --timing binds hf-timestd to the same radiod. Running it twice changes nothing.

No verb renames an instance yet. To give one a new name, bind its radiod again under the new reporter ID, start the new instance, then retire the old one:

smd admin sources bind ac0g-b1-a-status.local --reporter AC0G/LOOP \
    --clients psk-recorder
smd admin instance enable psk-recorder AC0G/LOOP
smd admin instance disable psk-recorder AC0G/B1A
smd admin instance remove psk-recorder AC0G/B1A

The old name's entry stays in coordination.toml until you delete it by hand.

Receivers

The [[receiver]] list in /etc/sigmond/site-profile.toml is the one record of which radiod each reporter ID listens to. Bring-up, smd check and smd admin instance list all read it.

[[receiver]]
reporter_id = "AC0G/B1A"
radiod = "ac0g-b1-a-status.local"
injector = true
antenna = "20 m longwire"

[[receiver]]
reporter_id = "AC0G/B1B"
radiod = "ac0g-b1-b-status.local"

Read the list back, then apply it:

smd admin receiver list
smd admin receiver apply

apply binds every declared receiver. It adds and updates. It never removes an instance, a sources file or recorded data. It sets an instance's upload flag only when the receiver decides it, through upload = or same_antenna_as, and only once the client has a config. Otherwise the flag stays as smd config upload left it.

A receiver with no clients key runs one instance of each per-reporter recorder (wspr-recorder, psk-recorder, meteor-scatter) that this host enables or has installed. clients = ["psk-recorder"] narrows it to the ones you name. apply --clients a,b sets that default set for one run; bring-up passes its profile's recorders this way.

Two commands write the list for you. smd admin sources bind <status> --reporter <ID> records the receiver, then binds it. To add one receiver for one client, run:

smd admin instance add <client> <reporter> --radiod <status>

Several receivers may share one radiod. Each receiver after the first on a radiod must name same_antenna_as, the reporter ID of a receiver on that radiod. Such a receiver keeps its spots local unless you set upload = true. At most one receiver per radiod carries injector = true, and at most one on the whole host, because hf-timestd binds to that receiver's radiod.

With a list declared, bring-up plans from it. It needs no --remote-radiod or --reporter, because the list already names every radiod and reporter ID. Bring-up accepts flags that match the list, so you can re-run the same command after a failure. It refuses flags that disagree with the list; edit the list instead.

Several receivers put several instances of each recorder on one host. Before it installs anything, bring-up adds up their cost against the CPUs left over after radiod. When the host falls short, bring-up stops and says by how much. Narrow a receiver's clients = [...], or pass --ignore-capacity. Under --dry-run the shortfall prints as a warning and the plan still shows.

On a station that already runs instances, smd config render --init builds the list from them. It reads each instance's sources file and makes one receiver per reporter ID. It prints what it wrote, and it names every instance it left out and why: an empty or unreadable sources file, a key that is not a radiod, a client that takes no per-reporter instance, or a reporter whose instances point at two radiods. If the adopted list fails validation, it writes nothing and says what to fix. A profile that already declares receivers stays as it is. --dry-run prints the result and writes nothing.

The steps below build the same station a piece at a time, for when you want to choose each part yourself.

3. See what's available

smd component list --catalog
━━━ catalog — known clients ━━━

  Servers (2)
    ✓  ka9q-radio             ka9q-radio SDR daemon — receives and multicasts RF channels
    ✓  ka9q-web               Web interface for ka9q-radio (radiod status UI)

  Clients (8)
    ✓  codar-sounder          Opportunistic ionospheric sounder using CODAR chirp transmissions  contract=0.8
    ✓  hf-tec                 HF PRN-coded beacon recorder for ionospheric specification  contract=0.8
    ✓  hf-timestd             HF time-standard analyzer (WWV/WWVH/CHU/BPM)  contract=0.8
    ✓  hfdl-recorder          HFDL (High Frequency Data Link) recorder — one dumphfdl subprocess per band  contract=0.8
    ✓  mag-recorder           RM3100 magnetometer recorder + PSWS uploader  contract=0.8
    ✓  meteor-scatter         Meteor-scatter ping recorder/decoder (jt9 --msk144)  contract=0.7
    ✓  psk-recorder           FT4/FT8 spot recorder for PSKReporter  contract=0.8
    ✓  wspr-recorder          WSPR/FST4W audio recorder (period-aligned WAVs)  contract=0.8

  Infra (3)
    ✓  gpsdo-monitor          Leo Bodnar GPSDO health monitor + mDNS advertiser
    ✓  igmp-querier           Robust IGMP querier for radiod multicast on home switches
    ✓  sigmond-rac            Remote Access Channel (frpc reverse tunnel)

Setting up a new host end to end? See the greenfield install runbook for the full ordered walkthrough (identity → radiod → wisdom → tuning → clients → validate).

4. Install clients

Install whichever clients you need. Each client's installer handles everything: creates a service user, Python venv, config template, and systemd units.

smd install hf-timestd
smd install psk-recorder

Run smd as yourself, never under sudo. It asks for root itself when a step needs it, and it refuses to run under sudo.

Use --dry-run to preview what would happen without making changes:

smd install wspr-recorder --dry-run

5. Configure

Each client owns its own config file. After installation, edit the config for your station:

Client Config file
radiod /etc/radio/*.conf
hf-timestd /etc/hf-timestd/timestd-config.toml
psk-recorder /etc/psk-recorder/psk-recorder-config.toml
wspr-recorder /etc/wspr-recorder/wspr-recorder.toml
mag-recorder /etc/mag-recorder/mag-recorder-config.toml
codar-sounder /etc/codar-sounder/codar-sounder-config.toml
hfdl-recorder /etc/hfdl-recorder/hfdl-recorder-config.toml
hf-tec /etc/hf-tec/hf-tec-config.toml
meteor-scatter /etc/meteor-scatter/meteor-scatter-config.toml

Sigmond's own coordination config lives at /etc/sigmond/topology.toml. Copy the example to get started:

sudo cp /opt/git/sigmond/sigmond/etc/topology.example.toml /etc/sigmond/topology.toml
sudo vi /etc/sigmond/topology.toml

Enable or disable components by setting enabled = true or false.

Using the TUI (recommended)

Instead of editing config files manually, you can use the interactive TUI:

smd tui

The TUI provides:

  • Install screen — browse and install components from the catalog
  • Topology screen — enable/disable components with live validation
  • Overview screen — system health dashboard
  • Logs screen — view and filter service logs
  • CPU affinity screen — configure CPU core isolation
  • CPU frequency screen — monitor and control CPU frequencies
  • Environment screen — discover and probe network peers (KIWISDRs, GPSDOs)
  • GPSDO screen — monitor Leo Bodnar GPSDO health
  • Validate screen — cross-client harmonization checks
  • Lifecycle screen — start/stop/restart services
  • Apply screen — reconcile services with current config
  • List (Software versions) screen — per-component status (git ref, upstream divergence, version policy) with Update All / per-component update buttons; replaces the old separate Update screen
  • Backup/Restore screens — backup and restore configuration

Keybindings: t = topology, i = install, v = validate, q = quit

6. Start services

smd start

This starts all enabled components in the topology. To start a single component (the component name is now a positional argument; an optional second positional selects a single instance):

smd start psk-recorder

7. Check health

smd status

Shows systemd unit state for every managed service, plus inventory data from each installed client: version, channel count, active frequencies, and any issues.

Command reference

smd's verbs are grouped the same way smd --help and the TUI present them. Run smd <verb> --help (or smd admin <verb> --help) for the full options on any verb.

Lifecycle — operate on running services. Without a component name they act on all enabled components; a positional component (and optional instance) narrows the scope.

Command Description
smd start [<component> [<instance>]] Start managed services
smd stop [<component> [<instance>]] Stop managed services
smd restart [<component> [<instance>]] Restart with reset-failed
smd reload [--via=auto|systemd|socket] [<component>] Reload via SIGHUP or restart
smd status [<component>] Service health + client inventory
smd enable <name>... Set enabled = true in topology
smd disable <name>... Set enabled = false and stop the units
smd apply Reconcile running services with current config

Install & components

Command Description
smd install [<client>] Install + configure a client, or run the full-suite install
smd bringup Guided station bring-up from a catalog profile (installs dormant when hardware is absent)
smd adopt <name> Adopt detected hardware or a discovered source — the only verb that starts anything; asks first (--dry-run, --yes)
smd component list [--catalog] Per-component status (lifecycle + git ref + version policy); --catalog lists what's installable
smd component update [<name>] Pull latest and reapply per topology version policy (root)
smd component add|remove <name> Clone/remove a component repo and its topology entry
smd config show|migrate Inspect or migrate coordination config
smd config init|edit <client> Run a client's first-run wizard or edit flow
smd update [--apply] [--latest] Plan an update (dry run by default); --apply performs it. --latest takes every component to the tip of its main branch and pins the station there; it serves test stations
smd version Each component's commit, against the image and upstream
smd sink status|upload|fill|off The site sink switch: whether this station sends its data
smd config reporters [--uploader-call NAME] The name this machine uploads under
smd remote status|on|off Remote access for the fleet admin

Observe & diagnose — most diagnostics now live under the admin group.

Command Description
smd watch <target> Live tail for wspr, psk, hfdl, codar, hf-tec, mag, ka9q, radiod, uploads, verifier
smd admin log [<client>] [--files] [--level L] Follow journal (or --files for file logs); --level sets the client's level via coordination.env + SIGHUP
smd admin diag [net|cpu-affinity|cpu-freq] Network / CPU diagnostics; cpu-freq --radiod-max-mhz N --other-max-mhz N --save keeps the caps across reboots
smd admin validate Cross-client harmonization rules
smd admin environment list|probe|describe Situational awareness of network peers (KIWISDRs, GPSDOs, NTP)
smd admin verifier|storage|sources|timing|radiod|instance|rac … Specialized maintenance — see smd admin --help
smd tui Launch the interactive TUI configurator

CLI v2 note. The verb surface was reorganized into component / admin / config groups. The old flat verbs smd list, smd log, smd diag, smd validate, and smd environment no longer exist — use smd component list and smd admin {log,diag,validate,environment} instead. smd install and smd apply remain available at the top level. Lifecycle scope is now positional (smd start psk-recorder); the old --components X,Y flag still works but is deprecated. Full mapping in docs/CLI-V2-SPEC.md.

Monitoring

Live status

smd status

For each installed client, status shows the systemd unit state plus data from the client's contract inventory: version, git commit, number of channels, active modes, and any reported issues.

Log viewing

Follow the systemd journal for a client:

smd admin log psk-recorder

Tail the client's file logs (spot logs, decode output):

smd admin log psk-recorder --files

Runtime log level

Change a client's verbosity without restarting:

smd admin log psk-recorder --level DEBUG

This writes PSK_RECORDER_LOG_LEVEL=DEBUG to /etc/sigmond/coordination.env and sends SIGHUP to the client's systemd units. The client re-reads the environment and adjusts its logger.

To set a default level for all clients (no SIGHUP — restart or SIGHUP each client to apply):

smd admin log --level WARNING

Debugging

Run diagnostics

smd admin diag

Checks:

  • Network reachability (wsprnet.org, wsprdaemon services)
  • Dependency versions against pinned commits
  • Per-client self-validation (<client> validate --json)
  • Service health

Check multicast / IGMP readiness

smd admin diag net        # unprivileged; uses /proc/net/igmp state
smd admin diag net   # adds passive raw-socket listen for queriers

Classifies your network for multi-host radiod safety and tells you whether to stay host-local (ttl=0), enable a querier, or avoid a Wi-Fi path. See docs/networking.md for the full guide.

Cross-client validation

smd admin validate

Runs harmonization rules across all enabled clients: CPU core isolation, frequency coverage vs. radiod sample rate, radiod reference resolution, and timing chain verification.

Adding a discretionary client later

The additional clients (hf-tec, superdarn-sounder) are installed at your discretion. Installing a client enables it — there is no separate enable step:

# See what's available
smd component list --catalog

# Install it — this also enables it in topology
smd install hf-tec

# Configure it for your station (first-run wizard, or $EDITOR fallback)
smd config init hf-tec

# Start it
smd start hf-tec

# Verify
smd status

The forward path is just install → configure → start — there is no separate enable step. smd install enables the component, and naming a component to smd start enables it too if it was installed-but-disabled. The only off-switch you need is smd disable <name>, which takes a component offline reversibly (stops its units and clears the topology flag); smd start <name> brings it back. Pass smd install --no-enable to install without enabling (e.g. to stage config first).

Available clients

Clients fall into two groups. Core clients are the DASI2 grant station's primary instruments — they install and run by default (the dasi2 profile: hf-timestd, wspr-recorder, psk-recorder, mag-recorder, meteor-scatter, hamsci-physics, hfdl-recorder, codar-sounder, plus the gmag-webui and station-web pages). Additional clients extend the same station to other HF science and are installed at your discretion — either all at once during guided bring-up (smd bringup dasi2 --with-optional) or one at a time (smd install <name>, which installs and enables it). See Adding a discretionary client later.

Core client What it does Repo
radiod ka9q-radio SDR daemon — receives RF and multicasts IQ channels ka9q/ka9q-radio
hf-timestd HF time-standard analyzer (WWV/WWVH/CHU/BPM) — also the suite's timing authority (publishes the RTP↔UTC offset + tier other clients label against) HamSCI/hf-timestd
wspr-recorder WSPR/FST4W recorder + decoder — uploads to wsprdaemon.org, which forwards to wsprnet.org HamSCI/wspr-recorder
psk-recorder FT4/FT8 spot recorder — decodes; wsprdaemon.org forwards its spots to PSKReporter HamSCI/psk-recorder
mag-recorder RM3100 magnetometer recorder (USB-I²C, non-radiod) — daily datasets to PSWS HamSCI/mag-recorder
meteor-scatter Meteor-scatter ping decoder (jt9 --msk144) → local sink + hs-uploader HamSCI/meteor-scatter
hfdl-recorder HFDL (High Frequency Data Link) recorder — one dumphfdl subprocess per band. Sends ground-station squitter timing to wsprdaemon.org; the airframes.io feed stays off unless you turn it on HamSCI/hfdl-recorder
codar-sounder Opportunistic ionospheric sounder using CODAR chirp transmissions HamSCI/codar-sounder
hamsci-physics Ionospheric science products (TEC/dTEC, TID, GRAPE/PSWS) from hf-timestd observations mijahauan/hamsci-physics
Additional client What it does Repo
hf-tec HF PRN-coded beacon recorder for ionospheric specification (TEC) HamSCI/hf-tec
superdarn-sounder Passive SuperDARN coherent-radar monitor (detection / identification) HamSCI/superdarn-sounder

Infrastructure components

Component What it does Repo
igmp-querier IGMPv2 querier daemon — keeps multicast streams alive on LANs without a router HamSCI/igmp-querier
sigmond-rac Remote Access Channel — frpc reverse tunnel to gw2.wsprdaemon.org for admin SSH/web behind NAT HamSCI/sigmond-rac
gpsdo-monitor Leo Bodnar GPSDO health monitor + mDNS advertiser HamSCI/gpsdo-monitor

The RF clients use ka9q-python to receive RTP streams from radiod; mag-recorder is the exception — it reads its magnetometer directly over USB-I²C, not through radiod. Each client runs in its own Python venv and manages its own systemd services. Decoded spots / products are written to the shared SQLite sink (/var/lib/sigmond/sink.db) and shipped upstream by hs-uploader.

Why a station is worth more as part of a network: each DASI2 node already carries several GPS-co-registered ionospheric instruments — hf-timestd (dTEC), hf-tec (coded-beacon absolute TEC), codar-sounder (oblique sounding / MUF), hfdl-recorder (dense opportunistic paths), and mag-recorder (the geomagnetic driver) — so a single node is already a multi-modal observatory. Replicated across the map, the mesh becomes a distributed-aperture instrument that can image travelling ionospheric disturbances, sense TEC gradients by differencing receivers that share a transmitter, and feed tomographic TEC — and it is resilient to the steady loss of the HF time standards it listens to (CHU included). See docs/STATION-NETWORK-CAPABILITIES.md.

How it works

Sigmond follows a layered architecture:

  1. Catalog — static registry of known clients (etc/catalog.toml). Answers "what could be installed on this host?"
  2. Installer — clones a client repo and delegates to its install.sh. Each client's installer is authoritative; sigmond never duplicates it.
  3. Topology — per-host config (/etc/sigmond/topology.toml). Declares which components are enabled.
  4. Lifecycle — resolves systemd units from each client's deploy.toml, expands templated units, discovers instances, and drives start/stop/restart/reload.
  5. Logging — aggregates logs across clients via the client contract's log_paths and log_level fields.
  6. Harmonization — cross-client validation rules that catch conflicts (CPU overlap, multicast collisions, missing dependencies).

Each client conforms to the HamSCI client contract, which defines a standard interface: inventory --json, validate --json, deploy.toml, systemd unit conventions, and logging discipline.

Development

smd core is stdlib-only; the TUI and test suite need a dev venv:

uv sync --extra tui --extra dev        # creates .venv/ with textual, rich, pytest

For prereqs, clone layout, running smd from the tree, tests, and docs checks, see docs/contributor/dev-setup.md ★.

Project

About

Signal Monitor Daemon for HamSCI

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages