HERMES System Architecture

This section provides an architecture-level description of HERMES as implemented by the software components referenced in Section 3.3.8. The focus is the HF data plane (store-and-forward payload transport over HF) and the radio/modem control plane that makes that possible on commodity HF transceivers.

Topology and station roles

HERMES is commonly deployed as a star topology network with two roles:

• Gateway station: has Internet access and orchestrates synchronization with remote stations.
• Remote station: provides local services (WiFi + web UI + email) and exchanges data with the gateway over HF.

Inter-station exchange is asynchronous (store-and-forward): payloads are queued locally and later transported over an HF link during scheduled communication windows (often initiated by the gateway in round-robin fashion).

Reference architecture (v2 / sBitx + VARA-compatible TNC + UUCP)

The reference implementation described in this document corresponds to HERMES v2 (sBitx-based radio control) and a VARA-compatible TCP TNC interface on localhost. In this model the station is composed of the following main processes:

• Radio control daemon: sbitx_controller (from hermes-net/trx_v2-userland), started by systemd as sbitx.service. It controls RF hardware and exposes a shared-memory control/status interface used by other services.
• Modem/TNC: either VARA HF (proprietary) or an open modem that implements the same VARA-style TCP TNC control/data sockets (e.g. hermes-modem). The control socket is typically on TCP 8300 and the data socket on 8301 (base port + 1).
• UUCP transport: GNU UUCP (uucico + spool under /var/spool/uucp), which provides store-and-forward job management and email transport integration.
• UUCP-to-modem bridge: uucpd (daemon) + uuport (pipe helper) from hermes-net/uucpd. This is the key component that turns the modem/TNC into an UUCP “port”.
• Gateway orchestration (gateway-only): a scheduler such as caller.sh (installed as caller.service) that triggers uucico -S <station> calls according to a schedule and station list.

Station component diagram

User devices (WiFi/LAN)
        |
      HTTP(S)
        v
 +--------------------+         +-----------------------+
 | Web UI / REST API  | <-----> | Mail stack (Postfix,  |
 | (external repos)   |         | Dovecot, etc)         |
 +--------------------+         +-----------+-----------+
                                             |
                                             v
                                     +-------+-------+
                                     | UUCP spool    |
                                     | /var/spool/uucp|
                                     +-------+-------+
                                             |
                                    uucico/uuport (per session)
                                             |
                               SysV SHM ring buffers (uucpd <-> uuport)
                                             |
                                             v
                                    +--------+--------+
                                    | uucpd (daemon)  |
                                    | VARA-style TNC   |
                                    +--------+--------+
                                             |
                 TCP control+data (8300/8301)|
                                             v
                                   +---------+---------+
                                   | Modem / TNC        |
                                   | (VARA or open)     |
                                   +---------+---------+
                                             |
                                   PTT ON/OFF + audio I/O
                                             |
                           SysV SHM control API (sbitx_controller)
                                             v
                                   +---------+---------+
                                   | sbitx_controller  |
                                   +-------------------+

Service orchestration (systemd)

On Debian-based HERMES images these components are typically started by systemd. Reference unit files are shipped in hermes-net/system_services/init/. Some helper units for the Wine-based VARA modem are shipped by hermes-installer under hermes-installer/conf/x11vnc/. The most relevant ones for the HF data plane are:

sbitx.service
  ExecStart=/usr/bin/sbitx_controller

# VARA HF (Wine + GUI): headless X server + VNC helper units
x11.service
  ExecStart=xvfb-run ... -n 69 -l xstartup

vnc.service
  ExecStart=x11vnc -display WAIT:69 ...

uucpd.service
  ExecStart=/usr/bin/uucpd -a 127.0.0.1 -p 8300 -r vara -o shm -f 2750p -m

caller.service   (gateway-only scheduler)
  ExecStart=/usr/bin/caller.sh

# Open modem (hermes-modem) alternative:
modem.service
  ExecStart=/usr/bin/mercury -v

uucpd-mercury.service   (typically installed as uucpd.service)
  ExecStart=/usr/bin/uucpd -a 127.0.0.1 -p 8300 -r vara -o shm -m -F

Interfaces: ports, paths and IPC

The HERMES reference architecture uses a small set of explicit interfaces. The most important ones are summarized below.

Dynamic behavior (message and call flows)

Outbound session (gateway calls a remote station)

1. Payloads (emails/messages/files) are queued locally and end up as UUCP jobs in the UUCP spool.
2. The gateway scheduler (e.g. caller.sh) triggers an UUCP session: uucico -S <remote>.
3. uucico starts in master mode and invokes uuport (configured as a type pipe UUCP port).
4. uuport attaches to uucpd's shared memory buffers and becomes uucico's byte-stream “modem”.
5. uucpd maintains a persistent TCP connection to the modem/TNC. When it sees outgoing bytes and is not connected, it issues a CONNECT <local> <remote> command on the TNC control socket.
6. The modem/TNC drives the RF transmit/receive turn-taking and signals PTT ON/PTT OFF on the control socket. uucpd translates these into actual radio keying (serial CAT or shared-memory keying via sbitx_controller).
7. Once connected, bytes flow bidirectionally: uucico $\leftrightarrow$ uuport $\leftrightarrow$ uucpd $\leftrightarrow$ modem/TNC $\leftrightarrow$ HF RF link.

Inbound session (remote answers an incoming call)

1. The modem/TNC is kept in listen mode by uucpd (LISTEN ON).
2. When a remote station calls in, the modem/TNC reports CONNECTED ... on the control socket.
3. uucpd detects this as an inbound connection and forks /usr/sbin/uucico in slave mode, wiring its stdin/stdout to the same shared buffers used by uuport.
4. The UUCP protocol runs and the spool is updated (receive jobs delivered; pending jobs may be sent back).

Variants

• Open modem (hermes-modem): provides a VARA-style TCP TNC interface, so from uucpd perspective it behaves like VARA and uses the same integration path (control/data sockets, PTT ON/OFF messages).
• ARDOP (legacy): supported by uucpd using its -r ardop mode; kept mainly for compatibility with older deployments.
• HERMES v1 (uBitx): legacy radio control uses ubitx_controller and different service units (see hermes-net/system_services/init).

Architecture reference sources

The architecture above is grounded in the following source trees and artifacts:

• hermes-net/uucpd (bridge daemon uucpd + port helper uuport + modem integration code)
• hermes-net/trx_v2-userland (sbitx_controller shared-memory control API)
• hermes-net/system_services/init (reference systemd unit files such as sbitx.service, uucpd.service, caller.service)
• hermes-modem (open modem implementing VARA-style TCP TNC)