Architecture & Control

Physical devices, messaging, automation and supervision.

Control layers and physical states

Logic
How it works

Division of responsibilities

The system does not give one computer unlimited responsibility for everything. N.I.N.A. is responsible for astronomical tasks such as exposures, slews, plate solving, focusing and sequencing. Home Assistant Green provides operational supervision and alarm logic. N.I.N.A.’s Safety Monitor also reads the UPS/incoming-mains state: loss of mains makes the monitor Unsafe even if Solo weather remains Safe, starting the N.I.N.A. roof-closing sequence while the UPS still supplies backup power. A Denkovi network controller bridges many physical contacts and relay outputs. Shelly modules provide additional independent inputs, power measurement and switching. Windows and Raspberry Pi computers run supporting services, while MQTT carries small state and event messages between applications.

This architecture matters because a command, the physical effect and confirmation of that effect are different things. For example, a roof-close request is only an instruction. Confirmation must come from the closed-limit contact, and even that confirmation should be treated cautiously if the software bridge carrying the reading has stopped working.

What the Denkovi controller actually measures

The Denkovi board exposes digital outputs (DO), digital inputs (DI) and analogue inputs (AI). Outputs command accessories such as the roof control path, equipment power and ancillary devices. Inputs report the roof's fully closed (FCCL) and fully open (FCOP) limit switches, motor operation, access and safety signals, including power and the physical STOP. Analogue channels provide supplementary measurements.

The important design decision is to read the controller as a whole after relevant events, not to assume that sending a command automatically updates the dashboard. When neither limit switch is asserted, the roof is not confirmed at an end position: it may be moving or there may be a fault. It is incorrect to infer “open” merely because it is “not closed.”

A separate Shelly Plus i4 input receives the Hydreon RG-11 rain detector, which is physically inside the observatory. Water detected there means moisture has entered the enclosure and the instruments may already be getting wet. This local emergency path is separate from the CloudWatcher Solo weather assessment: after the input remains in its rain-alarm state for 10 consecutive seconds, Home Assistant immediately starts emergency closure if the roof is not confirmed closed, even when the Solo still reports Safe.

The laser, IR barrier and physical STOP are electrical safety devices, not software safety checks. N.I.N.A. and Home Assistant can request a roof pulse, but neither can bypass the separate electrical permissive and interruption circuits; these protections continue to act if either application or its automation has a software problem. A laser points at the 10Micron mount's parked position and changes a Denkovi digital input (DI) only when the mount is in that position. That DI activates a Denkovi relay whose contacts close the electrical permissive circuit for the separate Denkovi relay that sends the roof-motion pulse. If the laser does not detect the parked mount, the permissive circuit stays open and a pulse requested from either N.I.N.A. or HA cannot reach the roof motor controller. N.I.N.A.'s main and emergency sequences activate the laser check before commanding the roof and deactivate it after roof travel.

An internal IR barrier runs parallel to the roof rack at approximately operator-head height and interrupts roof travel if someone enters its path. The roof motor's 24 VAC movement supply, switched through a dual-pole relay wired with the motor and sensor circuits, energises the barrier while the roof moves. An indoor buzzer and an exterior flashing light also come on during movement and go off when the roof stops. The physical STOP is another electrical control: it interrupts roof movement without relying on N.I.N.A., Home Assistant or network software.

The server, observatory PC and Raspberry Pi have distinct jobs

The observatory PC is close to the Denkovi integration and also runs supporting local services. The Windows server is the host for emergency execution, certain 10Micron utilities and associated software agents. The Raspberry Pi AllSky processes sky photographs independently of the photographic PC; its Python tasks include Clouds Advisor and meteor candidate detection.

HASS.Agent exposes selected Windows information to Home Assistant and can run a preconfigured task when the safety system calls it. Importantly, Home Assistant does not need to send arbitrary script code over the network every time: it requests the execution of a task that is already installed on the server.

This also allows the emergency sequence to start from a fresh N.I.N.A. process rather than relying on the currently running photographic sequence to remain responsive.

Denkovi Python bridge and MQTT communication

Logic
How it works

Python bridge for controller events

On the observatory PC, a persistent Python bridge connects the Denkovi board to the MQTT broker used by Home Assistant. Its operating logic has four ways to acquire updated data:

  1. Home Assistant command: when HA sends a command to change a relay through the controller's REST interface, it also publishes a short refresh request on MQTT. The Python process receives it, reads the controller's DI, DO and AI registers and publishes the new values for HA.
  2. N.I.N.A. command: when N.I.N.A. operates a relevant Denkovi-controlled accessory, its MQTT integration can request the same refresh. From the Python bridge's perspective, a refresh requested by N.I.N.A. and one requested by Home Assistant are processed in the same way.
  3. Hardware event: the Denkovi can send UDP traps when its digital inputs change. The Python bridge listens for these events and immediately performs a complete read, rather than waiting for the next scheduled poll.
  4. Fallback polling: in normal operation a full controller poll is performed approximately every 300 seconds. This provides a recovery path if an event notification or refresh request is missed.

The resulting MQTT states are read by Home Assistant and represented as entities on the dashboard and in automations. This arrangement reduces unnecessary continuous traffic toward the controller while preserving a fast response to significant events.

Example — roof motor stops: the motor input changes on the Denkovi. Its trap prompts the Python bridge to read the board. MQTT updates reach Home Assistant, which can then show the new motor state alongside the roof limit contacts. A second refresh after a N.I.N.A. operation gives another chance to confirm the final hardware state.

Data freshness: MQTT messages can be delayed or missed. A retained state is not proof that the controller remains live; heartbeats and periodic polling provide independent confirmation.

MQTT: small messages, clearly separated roles

MQTT is a publish/subscribe messaging system, not a replacement for the device drivers themselves. The observatory uses it to share information such as a request for controller refresh, a changed device state, a program heartbeat and whether an observing sequence is active. Separate topics support separate responsibilities.

A typical control cycle:

  1. Home Assistant issues the physical output command via the appropriate controller interface.
  2. HA publishes a refresh notification.
  3. The Python bridge queries the controller and publishes the measured result.
  4. HA updates the corresponding entities and evaluates any automations that depend on them.
  5. The controller's own event notifications and periodic polling provide additional update opportunities.

Some state messages are retained so a restarting subscriber can recover the last reported state. Retained data is useful but must not be confused with live proof. For a safety-relevant state, a retained message without a functioning heartbeat is insufficient.

Watchdogs and data validity

Logic
How it works

Heartbeat and watchdog supervision

The Denkovi bridge starts automatically under Windows and publishes a heartbeat message. Home Assistant treats an absent heartbeat as a software-health problem, rather than assuming the controller is healthy simply because its last known values are visible.

The dashboard monitoring distinguishes three practical cases:

  • Observatory PC not reachable: the PC, its power or its network may have failed; the Python bridge cannot be trusted to refresh the Denkovi values.
  • PC reachable, Denkovi not reachable: the fault is more likely to be the controller or its network path.
  • Both devices reachable, heartbeat missing: the probable issue is the Python process, its MQTT connection or the associated Windows task.

the alarm is generated after the bridge heartbeat has been unavailable for 30 seconds; the heartbeat entity itself has its own expiry period. A local Windows watchdog checks the specific Python process every five minutes and attempts to start it again if absent. These are complementary: the watchdog tries to repair, Home Assistant detects and reports.

The same “local recovery + external supervision” philosophy is applied to other services, including the 10Micron updater and Jeedom.

What happens when an application stops responding?

The design uses more than one observation for each important subsystem. A computer ping answers “is this host reachable?”; a process heartbeat answers “is this application still publishing?”; an electrical measurement answers “is power present?”; a roof limit switch answers “did the moving mechanism reach its end position?” None of these alone answers every question.

Where possible, notifications distinguish problem detected, automatic recovery attempted and service restored. Not all recovery attempts are guaranteed to work; some faults still require human inspection. The important achievement is that the system can report a specific likely failure rather than simply displaying “offline.”

Home Assistant automations

Logic
How it works

Home Assistant: an operational supervisor

The automation layer covers much more than the roof. It reports door openings and closings, roof motor operation, limit switches, the physical STOP, two ventilation circuits, incoming power, protected electrical circuits and UPS changes. It monitors computers, bridge heartbeats, 10Micron services, cloud-related software and AllSky publication. It also maintains SQM statistics, remote maintenance state and alerts for abnormal conditions.

Not all conditions use the same delay. For example, the rain input is filtered over 10 consecutive seconds, the “all Denkovi outputs off” emergency uses 30 seconds, and the separate Unsafe backup grants N.I.N.A. five minutes to close normally before forcing a new emergency process. These differences are deliberate: a transient input disturbance, a prolonged unsafe environmental condition and a failed roof closure are different problems.

Home Assistant automation catalogue

Home Assistant applies monitoring, notification and control automations across the observatory.

Roof, alarms and emergency action

Automation What activates it What it does
Telegram – roof motor active / inactive (2 rules) Motor-status input changes Sends matching motor start/stop notifications.
Telegram – roof state Either end-position limit switch becomes asserted Reports the fully open or fully closed end position.
Telegram – physical STOP Real STOP state changes Reports when the stop is pressed or released.
Emergency – internal rain Shelly rain input OFF for 10 s, roof not closed Sends urgent Telegram and starts the independent emergency chain.
Safety – Solo Unsafe Solo Unsafe and roof not closed, with maintenance exclusions clear Allows N.I.N.A. 5 min for normal closing; rechecks and invokes emergency only if still needed.
Emergency – telephone escalation Emergency-script state changes OFF→ON Waits 5 min; calls Twilio and reports only if the closed switch still says roof not closed.
Emergency – all Denkovi DO off All outputs OFF for 30 s, roof not closed Sends urgent Telegram and invokes the same emergency chain.
Maintenance reminder Every 30 min while STOP or remote maintenance is active Warns that the normal Solo Unsafe backup is excluded.
Roof Pulse – Maintenance Roof pulse button actually pressed Activates the HA remote-maintenance flag.

Power, ventilation and access

Automation What activates it What it does
Two door-open and two door-closed notifications (4 rules) Door contact changes Sends the corresponding access-state message.
Two fan-status notifications (2 rules) Server/board fan input changes Reports fan on/off.
Mains input and ICT power notifications (2 rules) Power contact state changes Reports power loss or restoration.
UPS input overvoltage Voltage exceeds 253 V for 5 s Sends an overvoltage warning.
UPS voltage back to normal Voltage below 253 V for 30 s Sends recovery notification.
Observatory UPS on battery / back online (2 rules) UPS operating status changes Reports source transfer and return.
House UPS on battery / back online (2 rules) Separate UPS operating status changes Reports source transfer and return.
Shelly supply off / periodic reminder / restored (3 rules) Supply switch goes OFF, remains OFF at five-minute checks, or turns ON Reports risk to the observatory PC and its battery-backed operation.
PC power and battery Power source changes or battery crosses a defined band Reports meaningful transitions rather than every percentage change.
SwitchBot battery SwitchBot crosses a battery band Reports maintenance needs.
PC power recovery UPS returns Online After 60 s, checks network and PC reachability; if necessary requests a SwitchBot power press.

Process health and service recovery

Automation What activates it What it does
HA restart notification suppression Home Assistant starts Enables a temporary 90 s notification-blocking flag used by selected automations.
Server HASS.Agent health Agent heartbeat unavailable for 3 min while server responds Warns and repeats periodically; reports recovery.
Observatory PC reachability PC ping changes OFF or ON Diagnoses loss using supply state and reports restoration.
Denkovi Python bridge health Bridge heartbeat unavailable for 30 s Distinguishes unreachable PC, unreachable controller and probable Python/MQTT failure.
10Micron weather-updater health Updater heartbeat unavailable for 2 min while mount is reachable Reports likely Python-service failure and recovery.
Jeedom health Jeedom heartbeat unavailable for 2 min Reports Jeedom failure and recovery.
Ajax session health Ajax session OFF for 2 min Reports that ARM/DISARM through the command bridge may be unavailable; reports recovery.
AAG Solo/Raspberry API health API-related value unavailable for 2 min Distinguishes Raspberry, Solo and API-layer failures, then reports restoration.
AllSky Cloudflare R2 upload Publication-health state DOWN for 5 min Reports failed public-image upload and recovery.
10Micron Clock Sync health Watchdog and synchronization status changes Reports synchronization faults and their recovery.

Weather, intelligence and astronomy

Automation What activates it What it does
AAG Solo rain notification Solo rain status remains rainy or dry for 3 min Sends onset/cessation messages, separately from the much faster RG-11 emergency.
AAG Solo configuration synchronisation HA startup or sensor-configuration state change Refreshes dashboard settings with values read from Solo.
Clouds Advisor Telegram confirmation User acts on a proposal message Retrieves proposal; requests explicit second confirmation; applies or cancels a validated request.
SQM reset Sun drops below −18° Starts a new night-darkness peak record.
SQM peak tracking SQM measurement updates during astronomical night Saves a new maximum and its timestamp when appropriate.
SQM end-of-night report Sun rises above −18° Sends the measured peak and time.
10Micron model-building mode Operator changes mode or five-minute refresh is due Publishes blocking state for the Python atmospheric updater.
10Micron clock-offset report Each hour while the mount is reachable Reports the measured synchronization offset.

Related notification rules are grouped by function; Home Assistant evaluates each trigger individually.

Remote monitoring interfaces

Logic
How it works

Remote dashboards and physical interfaces

A dedicated Android tablet uses Fully Kiosk Browser to display the Home Assistant dashboard. Its battery level and network availability are themselves monitored. The Overview groups command tiles into Roof, Server/PC, Setup 1, Setup 2, Utilities, Lighting, Alarm and Smart Plugs. Separate cards report the roof and door contacts, motor and fans, weather, UPS, power and energy, and the network and power state of the PCs. Commands and feedback are distinct: a tile can request an action, while a sensor or status card reports what the equipment actually did.

The tablet is an instrument panel, not a safety dependency. The roof-closing protections remain active when the display is asleep, the user is away or the tablet is offline. An internal Python proxy supports an authenticated configuration interface.