AAG CloudWatcher (Solo)
The AAG CloudWatcher Solo is Starship's primary safety source. It's a self-contained weather station with a built-in web server that exposes a CGI endpoint returning the current readings (cloud, rain, wind, temperature, humidity, sky brightness, pressure) together with the Solo's own safe/unsafe verdict.
Starship reads the Solo but never commands it. The Solo has a relay output (its switch field) that Starship deliberately leaves alone — the Solo's own logic, and the hardwired interlock between the Solo and your roof, stay authoritative.
Connecting to the Solo
The Solo hosts its CGI at a .local or fixed-IP address. On most networks it's reachable by the hostname aagsolo, which maps via mDNS / local DNS to the Solo's IP.
In Settings → AAG CloudWatcher (Solo) (the [solo] section of the config), set:
- Host (
host, defaultaagsolo) — the hostname or IP that resolves to your Solo. A raw IP such as192.168.1.42works too. - Poll interval (
poll_interval_s, default30) — how often Starship fetches a fresh reading, in seconds. - Timeout (
timeout_s, default5) — how long to wait for the Solo to answer before treating the fetch as a failure. This must be shorter than the poll interval.
Starship polls http://<host>/cgi-bin/cgiLastData on the configured interval, parses the key=value text payload, and publishes solo.reading events on the internal bus (with solo.stale and solo.error events when a reading is old or the fetch fails).
What the Solo reports
The Solo returns its own per-sensor verdicts, each of which is SAFE, WARNING, or UNSAFE:
- Cloud
- Wind
- Rain
- Humidity
- Light / daylight
- Pressure
The Solo's overall verdict is SAFE only when every sub-sensor is SAFE. Starship trusts that headline verdict for the Solo's own sensors.
What it contributes to the Safety Supervisor
The Safety Supervisor is the only part of Starship allowed to declare the overall safety state; the Sequencer, Scheduler, and scripting all act on its verdict. The Supervisor treats the Solo as its primary source and adds its own meta-rules on top of the Solo's verdict:
- Fail-closed. If the Solo has never reported, or Starship loses contact with it, the state is UNKNOWN / UNSAFE — never "no data, keep going."
- No contact. If no reading arrives for the primary-loss timeout (
safety.primary_loss_timeout_s, default 60 s), the verdict goes UNSAFE. - Stale reading. If the Solo's newest reading is older than ~90 seconds by the Solo's own clock, it's treated as stale and forces UNSAFE.
- Reported unsafe. If the Solo's overall verdict is unsafe, Starship is UNSAFE, and the reason names which sensors are in WARNING or UNSAFE.
- Asymmetric recovery (dwell). SAFE → UNSAFE is instant. Coming back the other way, the Solo must report SAFE continuously for the dwell window (
safety.unsafe_to_safe_dwell_s, default 120 s) before the Supervisor releases UNSAFE. During that window the state shows WARNING with a countdown, so the roof doesn't flap on marginal skies.
Any of unsafe / stale / no-contact pushes the Supervisor verdict toward UNSAFE (or UNKNOWN, which is treated the same for gating).
Sustained-loss escalation (on by default)
A short loss of the Solo link gives an UNSAFE that auto-recovers once the link returns. A long one does not: after safety.weather_loss_emergency_s seconds of continuous loss or silence (default 1800 = 30 minutes) the Supervisor escalates to a latched EMERGENCY (park + close, manual reset) instead of auto-recovering, so a dead weather link can't leave the rig working under unknown skies all night. This counts only loss/silence — a plain reported-unsafe (rain, cloud) still auto-recovers on the dwell.
- A positive value is the number of seconds of loss before the escalation.
0does not turn it off.0means "use the built-in default", which is 30 minutes.- To turn the escalation off, set a negative value (for example
-1). Only do this if something else protects the rig when the weather source is dead.
Poll-thread watchdog
Because the Supervisor is event-driven, it only ticks when the Solo driver publishes an event. A separate health-monitor watchdog ([health] → solo_heartbeat_enabled, on by default) notices if the Solo poll thread has gone silent — no solo.reading or solo.error for a few poll intervals — and drives the same emergency safe-state, so a silently dead poll thread can't leave the rig unguarded. Tune the silence threshold with solo_heartbeat_poll_multiple (multiple of the poll interval, default 3×) and solo_heartbeat_min_age_s (an absolute floor).
Other weather sources: ASCOM / Alpaca SafetyMonitor and ObservingConditions
New in v23. A rig is no longer limited to the CloudWatcher Solo. An ASCOM or Alpaca SafetyMonitor or ObservingConditions device can feed the Safety supervisor too, beside the Solo or instead of it.
Setting one up
These are set in config.toml; there is no Settings page for them yet. Restart Starship after changing them.
- Give the device its role, the same way as any other device:
[ascom.safetymonitor]or[ascom.observingconditions]with aprog_id, or[alpaca.safetymonitor]or[alpaca.observingconditions]withhostandport. - Set
auto_connect = truefor that device, and make sure the transport itself ([ascom]or[alpaca]) is enabled. If it is not, the log warns that the source is NOT watching the sky. - For an ObservingConditions device, set at least one limit under
[weather](below).
The device then joins the supervisor as an additional source, like an extra CloudWatcher: if it reports unsafe, the verdict is UNSAFE. Coming back to SAFE needs every source safe for the whole dwell.
What each device gives
- A SafetyMonitor gives its own verdict (
IsSafe). Starship takes it as it is. - An ObservingConditions device gives numbers only: cloud cover, sky temperature, wind speed, wind gust, humidity, rain rate, dew point. Starship judges them against your limits.
Limits for ObservingConditions: [weather]
max_cloud_cover_pct- cloud cover above this is unsafe.max_sky_temperature_c- a sky temperature above this means cloud.max_wind_kmh/max_gust_kmh- wind speed and gust.max_humidity_pct- relative humidity.max_rain_rate_mmh- rain rate.min_dew_margin_c- the smallest allowed gap between air temperature and dew point.
The rules:
- A limit left blank is not judged. Set only the ones you want.
- A limit you set, whose value the device does not supply, makes the source NOT safe. A sensor you asked for and cannot read is unknown, and unknown is not safe.
- With no limit set at all the device is never safe. It has nothing to judge by.
When the device stops answering
[weather] max_age_s(default 30) - a reading older than this is unknown, not safe.[weather] fail_closed(default true) - a weather device that is lost, unknown, or has never answered counts as NOT SAFE. Set it tofalseand a lost device is only reported, like a backup CloudWatcher. This is separate from[solo] extra_fail_closed, which is for extra Solos.
A device that cannot be read is never published as safe.
A rig with no Solo: [safety] primary_source
primary_source says which source is the primary one: the source whose loss is always UNSAFE and to which the sustained-loss escalation above applies.
"solo"(default) - the CloudWatcher at[solo] host."safetymonitor"- the ASCOM / Alpaca SafetyMonitor."observingconditions"- the ASCOM / Alpaca ObservingConditions device.
With one of the last two, the Solo is not polled unless [solo] extra_hosts lists it. If the chosen device is not set up, safety stays UNKNOWN, which is not safe. The dashboard's safety card shows which source is the primary.
These sources are new in v23. Before you rely on one, check it the simple way: make the device report unsafe (or unplug it) with the roof closed, and see that the verdict goes UNSAFE.
Manual mode (monitoring off)
For a portable / no-observatory / no-weather-sensor rig where a person is present, set safety.enabled = false. In this mode the Supervisor doesn't arm, the Solo isn't polled, and the verdict reads DISABLED — which never blocks anything (roof-open included). The UI shows "MANUAL MODE / monitoring off" rather than a red UNSAFE, and it's the operator's job to keep the rig safe.
Current readings on the dashboard
The Status / Safety page shows the latest Solo reading, live-updated over the WebSocket (solo.reading) and available at GET /api/solo/last:
- Overall safe/unsafe plus the per-sensor states (cloud, wind, rain, humidity, light, pressure)
- Sky-minus-ambient temperature (the cloud indicator), ambient temperature, and dew point
- Relative humidity
- Wind speed and gust
- Rain counter (lower = wetter)
- Sky brightness (SQM, mag/arcsec²)
- Absolute and relative pressure
- Solo firmware version
- Time since the last reading, and a stale flag
- A plain-language list of the reasons the Solo is reporting unsafe
Notes
The driver is read-only and straightforward Python. If the Solo's behaviour ever needs adjusting for your firmware or units, it's a small module you can fork, fix, and send back as a PR.