Driver Core
Relevant source files
The following files were used as context for generating this wiki page:
The Pulsar_DomeDriver is an ASCOM-compliant dome driver designed to interface with the Pulsar dome controller hardware. Its core responsibility is to manage serial communication, translate ASCOM commands into hardware-specific instructions, and maintain a consistent state of the dome's physical properties (azimuth, shutter status, etc.). A key feature of this driver is its robust error handling, which includes automated command watchdogs and a multi-level (soft/hard) reset routine to recover from hardware stalls or communication failures.
The driver is architected around the central DomeDriver class, which orchestrates several helper components for configuration, logging, communication, and external notifications. It operates on a continuous polling model to refresh dome status and uses asynchronous tasks for long-running operations and monitoring, ensuring the ASCOM interface remains responsive. The driver also supports optional integrations with MQTT for IoT-based status reporting and GNS (Goodnight System) for audible and visual alerts.
Sources: Driver/Pulsar_DomeDriver.cs:1-171, Config/ConfigManager.cs:38-92
Core Components
The driver's functionality is modularized into several distinct classes, each handling a specific concern. The DomeDriver class acts as the central orchestrator.
This diagram shows the main DomeDriver class and its composition of helper classes for managing configuration, logging, serial port access, command monitoring, and external notifications.
Sources: Driver/Pulsar_DomeDriver.cs:20-89, Config/ConfigManager.cs, Helper/SerialPortGuard.cs, Helper/ActionWatchdog.cs, MQTT/MqttPublisher.cs, GNS/GNS.cs, Diagnostics/FileLogger.cs
Key Component Descriptions
| Class | Description | Source File |
|---|---|---|
DomeDriver | The main ASCOM driver class. Implements IDomeV2 and orchestrates all operations. | Driver/Pulsar_DomeDriver.cs |
ConfigManager | Manages driver settings and runtime state. Reads/writes configuration to the ASCOM profile. Holds volatile state like azimuth and shutter status. | Config/ConfigManager.cs |
SerialPortGuard | A thread-safe wrapper around SerialPort that uses a SemaphoreSlim to prevent concurrent access to the hardware communication channel. | Helper/SerialPortGuard.cs |
ActionWatchdog | Monitors long-running dome actions (e.g., slewing, opening shutter). Triggers a reset routine on timeout or failure. | Helper/ActionWatchdog.cs |
FileLogger | Provides file-based logging with configurable levels (Info, Debug, Trace). | Diagnostics/FileLogger.cs |
MqttPublisher | (Optional) Publishes driver status, dome state, and alarms to an MQTT broker. | MQTT/MqttPublisher.cs |
GNS | (Optional) Sends notifications to the Goodnight System (GNS) for audible/visual alerts. | GNS/GNS.cs |
SettingsForm | The UI for configuring driver settings, which are then persisted by ConfigManager. | UI/SettingsForm.cs |
Connection and Communication
Connection to the dome controller is managed through the Connected property in the DomeDriver class. Setting it to true initiates the connection sequence, while false triggers disconnection.
Sources: Driver/Pulsar_DomeDriver.cs:174-273
Connection Sequence
The following diagram illustrates the process of establishing a connection with the dome controller.
This sequence shows that on connection, the driver opens the serial port, creates a SerialPortGuard to manage access, and sends a "PULSAR" ping command. A successful connection requires receiving the exact "Y519" response.
Sources: Driver/Pulsar_DomeDriver.cs:192-273, Driver/Pulsar_DomeDriver.cs:337-348, Helper/SerialPortGuard.cs:25-83
Serial Communication
All serial communication is funneled through the SerialPortGuard class. It uses a SemaphoreSlim to ensure that only one command is sent at a time, preventing message corruption. The SendAndVerify method in DomeDriver provides a higher-level interface for sending commands and validating their responses against expected values.
The ResponseMode enum dictates how a response is handled:
Blind: Send command, don't wait for a response.Raw: Send command, return the raw string response.MatchExact: Send command, return true if the response exactly matches a single expected string.MatchAny: Send command, return true if the response matches any of a list of expected strings.
Sources: Helper/SerialPortGuard.cs:1-98, Driver/Pulsar_DomeDriver.cs:1411-1509, Config/ConfigManager.cs:15-22
State Management and Polling
Once connected, the driver starts a background polling task (PollLoopAsync) that periodically queries the dome controller for its status. This ensures the driver's state properties (e.g., Azimuth, ShutterStatus) are kept up-to-date.
Polling Loop
This flow shows the polling loop continuously calling DomeStatus, which sends commands to the hardware (V, HOME ?, PARK ?) and parses the responses to update the state variables stored in ConfigManager.
Sources: Driver/Pulsar_DomeDriver.cs:427-603, Driver/Pulsar_DomeDriver.cs:800-994
System Watchdog
A separate watchdog task (StartWatchdog) runs in parallel to the polling loop. It serves two purposes:
- MQTT Heartbeat: Publishes an "Alive" message periodically if MQTT is enabled.
- Polling Stall Detection: Checks if the time since the last successful poll (
_lastPollTimestamp) exceeds a threshold (_pollingStallThreshold, 10 seconds). If it does, the watchdog assumes the polling loop has stalled and restarts it.
Sources: Driver/Pulsar_DomeDriver.cs:605-661
Command Execution and Monitoring
Dome actions like slewing or opening the shutter are handled by the ExecuteDomeCommand method. This generic method centralizes command dispatch, state updates, and the initiation of an ActionWatchdog to monitor the command's execution.
Action Watchdog Flow
When a command like OpenShutter is called, it delegates to ExecuteDomeCommand, which in turn starts an ActionWatchdog.
This diagram illustrates how a command is sent and then monitored. The ActionWatchdog runs asynchronously, periodically calling a checkStatus function provided by the DomeDriver. This function evaluates the current dome state (updated by the polling loop) to determine if the action has succeeded, failed, or is still in progress. If the action doesn't complete within its timeout, the watchdog triggers the reset routine.
Sources: Driver/Pulsar_DomeDriver.cs:1757-1834, Helper/ActionWatchdog.cs:49-130, Driver/Pulsar_DomeDriver.cs:1887-1918
Error Handling and Reset Routine
A primary feature of the driver is its ability to automatically recover from errors. This is handled by the ResetRoutineAsync method, which can perform a soft or hard reset.
Reset Logic
The reset routine first attempts a "soft" reset by sending a RESTART command to the controller. If that fails or is disabled, it proceeds to a "hard" reset. The hard reset involves disconnecting the serial port and executing an external process (defined in settings) to power-cycle the controller hardware before reconnecting. After a successful reset, the driver attempts to replay the last command that failed.
Sources: Driver/Pulsar_DomeDriver.cs:1001-1153, Driver/Pulsar_DomeDriver.cs:1189-1252
Configuration
Driver settings are managed by ConfigManager and stored in the ASCOM profile. They are configured via the SettingsForm.
| Setting | Description | UI Control (SettingsForm) | ConfigManager Property |
|---|---|---|---|
| Serial Port | The COM port for the dome controller. | comboBoxSerialPort | SerialPort |
| Log File Location | The directory to store log files. | txtBoxLogLocation | LogLocation |
| Debug/Trace Logging | Enables verbose logging for diagnostics. | chkBoxDebugLog/chkBoxTraceLog | DebugLog/TraceLog |
| Use MQTT | Enables publishing status to an MQTT broker. | chkBoxMQTT | UseMQTT |
| Use GNS | Enables sending alerts to the Goodnight System. | chkBoxGNS | UseGNS |
| Internal (Soft) Reset | Enables the RESTART command for recovery. | checkBoxInternalReset | SoftReset |
| External (Hard) Reset | Enables power-cycling via an external executable for recovery. | checkBoxExternalReset | HardReset |
| Reset Executable | Path to the .exe used for the hard reset. | txtBoxExternalExe | ResetExe |
| Reset On/Off Params | Command-line arguments for the reset executable. | txtBoxOnParameters/txtBoxOffParameters | ResetOnParameters/ResetOffParameters |
| Shutter Timeout (s) | Max time to wait for shutter open/close before timing out (in seconds). | txtBoxShutterTimeout | ShutterTimeout |
| Rotation Timeout (s) | Max time to wait for a slew/home/park action to complete (in seconds). | txtBoxRotationTimeout | RotationTimeout |
| Reboot Delay (s) | Time to wait after a hard reset for the controller to boot (in seconds). | txtBoxResetDelay | ResetDelay |
| Cycle Delay (s) | Time to wait between power-off and power-on during a hard reset (in seconds). | txtBoxCycleDelay | CycleDelay |
Sources: Config/ConfigManager.cs:94-255, UI/SettingsForm.cs:20-130, UI/SettingsForm.Designer.cs
Summary
The Pulsar Dome Driver core provides a resilient and feature-rich interface to the dome hardware. It combines standard ASCOM functionality with a sophisticated, multi-layered error recovery system. The architecture effectively decouples concerns like communication, state management, and command monitoring, using asynchronous operations to maintain responsiveness. The inclusion of configurable reset routines and optional integrations with MQTT and GNS makes it a robust solution for automated observatory control.
Sources: Driver/Pulsar_DomeDriver.cs