Daemon, Driver and Config Inventory#

This page is the concrete inventory the COO specification asks each instrument to provide: what daemons exist, what hardware each owns, which driver it uses, and what it exposes. It describes the current main branch and needs updating whenever a daemon is added.

Daemon inventory#

Daemons are split by reusability, not by subsystem. daemons/generic/ holds daemons whose behaviour is fully determined by config and which are therefore shared across subsystems; daemons/<subsystem>/ holds daemons tied to one subsystem’s hardware or to mechanism-specific logic. The PDU daemons in daemons/hspower/ are as config-driven as the generic daemons, but every instance of them belongs to the hspower service, so they sit there with their shared pdu_base.py base class.

Daemon	Driver	Hardware	Deployed instances
`generic/filterwheel`	`thorlabs.fw102c`	Thorlabs FW102C filter wheel	`hsfei_atcfw`, `hscal_hkcalfwheel1/2`, `hscal_hkgcellfwheel`, `hscal_yjcalfwheel1/2`
`generic/lakeshore`	`lakeshore.lakeshore`	Lakeshore 336/224 temperature controller	`hsfei_atctherm`, `hscal_gcellheater1/2`
`hscal/srs_thermal`	`srs.ptc10`	SRS PTC10 thermal controller	`hscal_hkettherm`, `hscal_yjettherm`
`generic/inficon`	`inficon.inficonvgc502`	Inficon VGC502 vacuum gauge controller	`hsfei_atcpress`
`generic/camera`	`tracking_camera.TrackingCamera`	H2RG on an STA Archon, through `camera_interface_tracking`	`hsfei_atcam`
`hsfei/pi-daemon`	`pi.PIControllerBase`	PI C-663 / C-863 / E-754 motion controllers	`hsfei_atcl`, `hsfei_atcp`, `hsfei_feipo`, `hsfei_lsm`, `hsfei_ms`
`hsfei/adc`	`newport.smc100pp`	Newport SMC100PP ADC prism rotators	`hsfei_adc`
`hsfei/atccryo`	`sunpower.sunpower_cryocooler`	Sunpower cryocooler	`hsfei_atccryo`
`hsfei/piaa-gimbalmount`	`thorlabs.ppc102`	Thorlabs PPC102 piezo gimbal mount	`hsfei_piaagimb`, `hsfei_piaagimr`
`hsfei/xeryon`	`xeryon.XeryonController`	Xeryon XD-M-3 piezo motion controllers	`hsfei_hkfam`, `hsfei_piaadeploy`, `hsfei_yjfam`
`hscal/smc8_attenuator`	`standa.smc8`	Standa SMC8 (libximc) attenuator	`hscal_hketatten`
`hspower/eaton_pdu`	`pdu.src.emat08_10`	Eaton EMAT08-10 networked PDU	`hspower_fei3/4`, `hspower_cal1`–`4`, `hspower_fib1`, `hspower_bspec1`, `hspower_rspec1`
`hsfibers/trunkfiberbox`	`fib.TrunkInterfaceBox`	FIB trunk interface box, over MQTT 5	`hsfibers_trunkfiberbox`

Thirty-five instances are currently defined under systemd/instances/, running twelve distinct daemon scripts — the config-driven design paying off directly.

Subsystem view#

`hsfei` — Front End Instrument#

The FEI is the most complete subsystem, covering the pickoff and acquisition path, the ADC, the PIAA gimbal mounts, and the ATC (acquisition and tracking camera) environment.

Instance	Mechanism
`hsfei_feipo`	FEI pickoff
`hsfei_ms`	mask selector (two daisy-chained PI stages, H and V)
`hsfei_lsm`	lens selector mechanism
`hsfei_atcl`	ATC lens stage
`hsfei_atcp`	ATC pickoff stage
`hsfei_adc`	atmospheric dispersion corrector, two prism rotators
`hsfei_piaagimb` / `hsfei_piaagimr`	PIAA gimbal mounts, blue and red
`hsfei_piaadeploy`	PIAA lens deploy, blue and red in/out
`hsfei_yjfam` / `hsfei_hkfam`	fiber alignment mechanisms, blue and red
`hsfei_atcfw`	ATC filter wheel
`hsfei_atctherm`	ATC temperature control
`hsfei_atcpress`	ATC vacuum pressure
`hsfei_atccryo`	ATC cryocooler
`hsfei_atcam`	ATC camera, the only instance on `feiserver`

`hscal` — Calibration#

The calibration unit covers the HK (red) and YJ (blue) calibration paths and the gas cell.

Instance	Mechanism
`hscal_hkcalfwheel1` / `2`	HK calibration filter wheels
`hscal_yjcalfwheel1` / `2`	YJ calibration filter wheels
`hscal_hkgcellfwheel`	gas cell filter wheel
`hscal_gcellheater1` / `2`	gas cell heaters
`hscal_hkettherm` / `hscal_yjettherm`	etalon thermal control
`hscal_hketatten`	HK etalon attenuator

`hsfibers`: FIB#

The FIB PCBs run their own firmware and are reached over MQTT 5 through the mosquitto broker on hispec.caltech.edu. The daemon is read only: its driver can only send allowlisted queries, so it cannot turn on a laser or move a switch.

Instance	Mechanism
`hsfibers_trunkfiberbox`	trunk interface box: MEMS switches, routes, lasers, attenuators, photodiodes, all read only

`hspower` — power distribution#

Every networked PDU in the instrument is one hspower instance, and they all live in this one service rather than with the subsystem they power, so that outlet control is in a single place. Each is named for where the unit is. Every deployed unit is an Eaton (hspower/eaton_pdu) today; see below for how to add a daemon for another PDU.

Instance	PDU
`hspower_fei1` / `hspower_fei2`	FEI, two units (`feieaton1`, `feieaton2`)
`hspower_cal1` – `hspower_cal4`	CAL, four units
`hspower_fib1`	FIB
`hspower_bspec1`	BSPEC (`blueeaton1`)
`hspower_rspec1`	RSPEC

The addresses for the CAL, FIB and RSPEC units are not documented anywhere in the repo yet, so those configs carry a TODO and no ip_address; such an instance starts and serves its keywords, reporting missing PDU connection parameters through its error keyword, and connects once an address is filled in. outlet_count is likewise a placeholder of 8 in every config until each unit is confirmed as an EMAT-08 or an EMAT-10 — it decides how many outlet keyword blocks the daemon registers.

The Telnet login is not in the configs. They name the environment variables holding it (hardware.username_env, hardware.password_env, both pointing at HISPEC_PDU_* today), which systemd supplies from root-only /etc/hispec/secrets.env — the same arrangement the keygrabber uses for its InfluxDB token. An inline hardware.username / hardware.password still works for a bench test and logs a warning against committing it.

Each PDU family gets its own daemon script, and each subclasses PduDaemon in daemons/hspower/pdu_base.py: eaton_pdu for the Eaton EMAT-08/10 over Telnet, and dli_pdu for the DLI DC3 over SSH. The base class does everything common to every PDU: config, credentials, connecting, the status keyword and the outlet basics (state<n>, name<n>, switchable<n>). The script fills in how to talk to its hardware and registers whatever else that PDU can do, which for the Eaton is per-outlet metering and auto-restart, and for the DLI per-outlet power cycling.

Supporting another PDU means copying eaton_pdu, filling in its hardware methods, and keeping only the extras the new PDU has. The steps are at the top of pdu_base.py.

Placeholder subsystems#

daemons/hscryo, daemons/hstt and daemons/hscam exist as empty placeholders for the cryostat, tip-tilt and detector subsystems. The spectrograph itself has no daemon directory yet.

Keyword inventory#

Keywords every daemon has#

Inherited from LibbyDaemon and registered without the daemon asking:

Keyword	Type	Access	Meaning
`uptime`	int	read	Whole seconds since the daemon started serving.
`lasterror`	string	read / clear	The most recent message passed to `logger.error()`. Write `null` to clear. Makes a locally-logged failure remotely visible.
`keys.list`	service	read	Registered keyword names, `%` wildcard supported.
`keys.describe`	service	read	Full metadata for one keyword: type, access, units, description, timeout.

Registered by HISPEC daemons themselves, by near-universal convention:

Keyword	Type	Access	Meaning
`isconnected`	bool	read / write	Whether the daemon holds a live connection to its controller. Writing `true`/`false` connects or disconnects.
`error`	string	read	Last error string recorded by the daemon’s own error state.
`shutdown`	trigger	write	Stop this daemon gracefully.

Per-daemon keywords#

Motion daemons (pi-daemon, adc, filterwheel, smc8_attenuator) share a vocabulary:

Keyword	Meaning
`positionvalue`	Current position in the mechanism’s configured units. Writable to move.
`positionnamed`	Current position as a configured name; writable to move to a named position.
`ismoving`	Motion in progress.
`isreferenced`	Stage has been homed. Writable to home.
`isloopclosed`	Servo loop closed. Writable.
`softmin` / `softmax`	Daemon-enforced limits, writable at runtime.
`hardmin` / `hardmax`	Controller limits, read-only.
`halt`	Trigger — stop motion on all axes.

Multi-axis daemons suffix the per-axis keywords and add an aggregate. A mechanism with more than one stage registers positionvalue<suffix>, ismoving<suffix> and so on — the PI daemon uses the stage name from config (positionvalueh, positionvaluev for the mask selector), the ADC uses the stage number (positionvalue1, positionvalue2). Alongside those, the daemon registers unsuffixed consolidated keywords covering the whole mechanism: isreferenced is true when all stages are referenced and writing it homes every stage, ismoving is true when any stage is moving, isloopclosed aggregates likewise and one write closes every loop. A single-stage config registers the bare names directly, so a client that only cares about the mechanism as a whole uses the same keyword either way.

Thermal daemons (lakeshore, srs_thermal) generate their keywords from config. Each entry in sensors: produces one read-only temperature keyword under the name the config chose; each entry in heaters: produces a writable setpoint and <name>_output plus, for the Lakeshore, <name>_status and one keyword per PID term.

atccryo exposes cryocooler state — cold_head_temp, reject_temp, target_temp, measured_power, commanded_power, control_mode, cooler_error — plus pid_<term> keywords for the control loop.

inficon exposes pressure1, pressure2, temperature, units and units_code. The gauge’s pressure unit is settable from its front panel, so each pressure read fetches the unit alongside the value and reports it on that reading rather than trusting a cached one.

piaa-gimbalmount carries the largest keyword set: X/Y positions in both position and voltage units, per-axis and combined loop-closed state, and a full soft/hard limit matrix in both units — softmaxx, softminvolty, hardmaxx and so on.

eaton_pdu registers device-level keywords (model, firmware, manufacturer, serial, outletcount, status) plus a per-outlet block of state<n>, name<n>, switchable<n>, current<n>, power<n>, energy<n>, autorestart<n> and resetstatistics<n>. The first three outlet keywords and model/firmware come from pdu_base.py; the rest are the Eaton’s own. The outlet count comes from config. An outlet listed in the optional hardware.outlet_names map (outlet number to a name; characters other than letters, digits and underscores become underscores) uses _<name> in place of <n>, so outlet 1 named arclamp gets state_arclamp; unlisted outlets keep the number.

dli_pdu registers the same base keywords (model, firmware, outletcount, status, state<n>, name<n>, switchable<n>) plus cycle<n>, a trigger that power cycles the outlet, and cycledelay<n>, the read-only off time of that cycle in seconds. Outlet names work as for eaton_pdu.

Config inventory#

config/<subsystem>/<instance>.yaml, one file per instance, forty-four files at present — thirty-five of them backing a deployed systemd instance. config/example/ holds templates for daemons not yet deployed.

Config is the source of truth for:

Parameter group	Owner	Runtime mutability
`peer_id`, `group_id`	config only	fixed at startup
`hardware.*` (address, port, units, step size)	config only	fixed at startup
`limits.soft_*`	config, overridable	writable via `softmin`/`softmax` keywords; not persisted
`limits.hard_*`	controller, or config where the controller cannot report them	read-only
`named_positions`	config only	fixed at startup
`sensors` / `heaters` / `stages`	config only	fixed at startup; determines which keywords exist
`logging.level`, `logging.file`	config only	fixed at startup

The one writable-at-runtime group is soft limits. A runtime change to softmin/softmax lives only in the daemon process and is lost on restart, which is worth knowing before relying on one during AIT.

Adding a daemon#

The mechanics, in the order they are done:

Add the vendor driver as a submodule under src/hispec/driver/ if it is not already vendored.
If an existing daemon covers the hardware, skip to step 4 — most new mechanisms need no new Python.
Otherwise write daemons/<subsystem>/<name>: subclass HispecDaemon, register keywords in on_start, disconnect in on_stop, and give it an argparse -c/--config entry point that calls from_config_file(...) then serve().
Add config/<subsystem>/<instance>.yaml.
Add systemd/instances/<instance>.env naming the script and the deployed config path.
Add the row to the instance table in Running the HISPEC Daemons with systemd and to the daemon inventory above.
Commit, then on the host git pull and hispec deploy <instance>, which copies both files into /etc/hispec, enables and starts it.