Developer Guide
Relevant source files
The following files were used as context for generating this wiki page:
- Driver/Pulsar_DomeDriver.cs
- Config/ConfigManager.cs
- Helper/ActionWatchdog.cs
- Helper/SerialPortGuard.cs
- UI/SettingsForm.cs
- UI/SettingsForm.Designer.cs
- MQTT/MqttPublisher.cs
- GNS/GNS.cs
- Diagnostics/FileLogger.cs
- Properties/AssemblyInfo.cs
- Helper/ResponseResult.cs
- MQTT/WatchDogLogger.cs
- Properties/Resources.Designer.cs
This document provides a technical overview of the Pulsar_DomeDriver, an ASCOM-compliant dome driver for the Pulsar dome controller. It details the software architecture, core components, communication protocols, and error recovery mechanisms. The driver is written in C# and communicates with the dome hardware via a serial port.
The driver's architecture is designed for robustness, featuring a multi-layered error handling and recovery system. This includes command-level watchdogs, a system-level polling monitor, and automated soft and hard reset routines. It also integrates with external systems for status reporting and notifications via MQTT and the Goodnight System (GNS).
1. System Architecture
The driver is composed of several key classes that work together to manage state, communication, and execution of commands. The DomeDriver class is the central orchestrator, implementing the IDomeV2 ASCOM interface and coordinating the other components.
Sources: Driver/Pulsar_DomeDriver.cs, Config/ConfigManager.cs, Helper/ActionWatchdog.cs
1.1. Core Components
The following diagram illustrates the primary classes and their relationships.
This class diagram shows the main components of the driver and their dependencies.
Sources: Driver/Pulsar_DomeDriver.cs:25-95, Config/ConfigManager.cs:38, Helper/SerialPortGuard.cs:13, Helper/ActionWatchdog.cs:11, MQTT/MqttPublisher.cs:13, GNS/GNS.cs:15
1.2. Component Descriptions
| Class | Description | Source File |
|---|---|---|
DomeDriver | The main class implementing the ASCOM IDomeV2 interface. It manages the connection, state, and coordinates all dome operations. | Driver/Pulsar_DomeDriver.cs |
ConfigManager | Handles loading and saving all configuration settings from the ASCOM Profile (Windows Registry). | Config/ConfigManager.cs |
SerialPortGuard | A thread-safe wrapper around the System.IO.Ports.SerialPort class. It uses a SemaphoreSlim to ensure that only one command is sent at a time. | Helper/SerialPortGuard.cs |
ActionWatchdog | Monitors long-running operations (e.g., slewing, shutter movement) for success, failure, or timeout. It can trigger a reset routine if an action fails. | Helper/ActionWatchdog.cs |
MqttPublisher | Manages the connection to an MQTT broker and publishes status updates and alarms. | MQTT/MqttPublisher.cs |
GNS | Sends notifications to the "Goodnight System" (GNS) via a named pipe for external monitoring. | GNS/GNS.cs |
FileLogger | Provides file-based logging with configurable levels (Trace, Debug, Info, etc.). | Diagnostics/FileLogger.cs |
SettingsForm | The Windows Form UI for configuring driver settings. | UI/SettingsForm.cs |
2. Key Workflows
2.1. Connection and Initialization
When an ASCOM client sets the Connected property to true, the driver initiates a connection sequence. This involves opening the serial port, pinging the controller, and starting background monitoring tasks.
This diagram shows the sequence of events when establishing a connection to the dome controller.
Sources: Driver/Pulsar_DomeDriver.cs:200-250, Driver/Pulsar_DomeDriver.cs:342-351
2.2. Command Execution and Monitoring
Executing a dome command, such as SlewToAzimuth, follows a structured, monitored process to ensure reliability. The ExecuteDomeCommand method orchestrates this flow.
This flowchart illustrates the generic command execution logic, including pre-checks, sending the command, and initiating a watchdog.
Sources: Driver/Pulsar_DomeDriver.cs:1750-1823
The ActionWatchdog is a critical part of this flow. It runs in a separate task, periodically checking the dome's status until the action is complete, times out, or fails.
This diagram shows the ActionWatchdog lifecycle, which can end in success or trigger a reset on failure.
Sources: Helper/ActionWatchdog.cs:78-132
2.3. Status Polling and System Watchdog
The driver maintains a background polling loop (PollLoopAsync) that continuously queries the dome controller for its status. This updates internal state variables like azimuth, shutter status, and dome state.
A separate system watchdog (_systemWatchdogTask) runs every 5 seconds to ensure the polling loop itself has not stalled. If the last poll timestamp is older than a threshold (10 seconds), it restarts the polling mechanism.
Sources: Driver/Pulsar_DomeDriver.cs:571-610, Driver/Pulsar_DomeDriver.cs:612-658
2.4. Error Handling and Reset Routine
The driver features a robust, multi-stage reset mechanism (ResetRoutineAsync) triggered by command timeouts or failures.
This diagram details the logic of the reset routine, showing the progression from a soft reset attempt to a hard power-cycle reset.
Sources: Driver/Pulsar_DomeDriver.cs:1225-1355, Driver/Pulsar_DomeDriver.cs:1388-1422, Driver/Pulsar_DomeDriver.cs:1424-1481
3. Configuration
All driver settings are managed by the ConfigManager class and stored in the ASCOM Profile, which typically corresponds to the Windows Registry under HKEY_CURRENT_USER\Software\ASCOM\Dome Drivers\Pulsar_DomeDriver. The SettingsForm provides a GUI to modify these values.
Sources: Config/ConfigManager.cs, UI/SettingsForm.cs
3.1. Key Configuration Settings
| Setting | UI Control | Description | Source File |
|---|---|---|---|
SerialPort | comboBoxSerialPort | The COM port for communicating with the dome controller. | Config/ConfigManager.cs:100-103 |
LogLocation | txtBoxLogLocation | The directory path where log files will be stored. | Config/ConfigManager.cs:136-139 |
DebugLog / TraceLog | chkBoxDebugLog / chkBoxTraceLog | Enables verbose logging for debugging purposes. | Config/ConfigManager.cs:211-229 |
UseMQTT | chkBoxMQTT | Enables/disables publishing status updates to an MQTT broker. | Config/ConfigManager.cs:231-240 |
UseGNS | chkBoxGNS | Enables/disables sending notifications via the Goodnight System. | Config/ConfigManager.cs:242-251 |
SoftReset | checkBoxInternalReset | Enables the software-based reset routine (RESTART command). | Config/ConfigManager.cs:105-115 |
HardReset | checkBoxExternalReset | Enables the hardware-based reset routine using an external executable. | Config/ConfigManager.cs:117-127 |
ResetExe | txtBoxExternalExe | Path to the external executable used for a hard reset. | Config/ConfigManager.cs:141-144 |
ResetOnParameters | txtBoxOnParameters | Command-line arguments for the reset executable to turn power ON. | Config/ConfigManager.cs:146-149 |
ResetOffParameters | txtBoxOffParameters | Command-line arguments for the reset executable to turn power OFF. | Config/ConfigManager.cs:151-154 |
ShutterTimeout | txtBoxShutterTimeout | Timeout in milliseconds for shutter open/close operations. | Config/ConfigManager.cs:181-195 |
RotationTimeout | txtBoxRotationTimeout | Timeout in milliseconds for dome rotation (slew/home/park) operations. | Config/ConfigManager.cs:197-210 |
ResetDelay | txtBoxResetDelay | Delay in milliseconds to wait for the controller to boot after a hard reset. | Config/ConfigManager.cs:156-166 |
CycleDelay | txtBoxCycleDelay | Delay in milliseconds between turning power off and on during a hard reset. | Config/ConfigManager.cs:168-178 |
4. Communication Protocols
4.1. Serial Communication
The primary communication with the dome controller is via a serial port, managed by the SerialPortGuard class. This class ensures thread-safe access to the port. Commands are terminated with a carriage return (\r).
Sources: Helper/SerialPortGuard.cs:34-40
Key Commands:
| Command | Expected Response | Description |
|---|---|---|
PULSAR | Y519 | Pings the controller to check for connectivity. |
V | Tab-delimited status string | Requests the full status of the dome and shutter. |
HOME ? | 0 or 1 | Queries the home status. |
PARK ? | 0 or 1 | Queries the park status. |
OPEN / CLOSE | A (ACK) | Commands the shutter to open or close. |
ABS {azimuth} | A (ACK) | Slews the dome to an absolute azimuth. |
GO H / GO P | A (ACK) | Commands the dome to the home or park position. |
STOP | A (ACK) | Aborts any ongoing movement. |
RESTART | (none) | Triggers a soft reboot of the controller. |
Sources: Driver/Pulsar_DomeDriver.cs:344, Driver/Pulsar_DomeDriver.cs:918, Driver/Pulsar_DomeDriver.cs:1050, Driver/Pulsar_DomeDriver.cs:1078, Driver/Pulsar_DomeDriver.cs:1829, Driver/Pulsar_DomeDriver.cs:1898, Driver/Pulsar_DomeDriver.cs:1924, Driver/Pulsar_DomeDriver.cs:1951, Driver/Pulsar_DomeDriver.cs:1400
4.2. MQTT Integration
If enabled (UseMQTT), the driver connects to an MQTT broker and publishes status updates. This is handled by the MqttPublisher class.
Key MQTT Topics:
| Topic | Purpose |
|---|---|
Dome/DriverStatus | General status of the driver (e.g., "Driver connected"). |
Dome/Dome/Status | Status of dome actions (e.g., "Dome is parked."). |
Dome/Shutter/Status | Status of shutter actions (e.g., "Shutter is open."). |
Dome/Alarm | Published when an unrecoverable error or critical failure occurs. |
Dome/Watchdog | A periodic heartbeat message from the system watchdog. |
Sources: Driver/Pulsar_DomeDriver.cs:90-95, MQTT/MqttPublisher.cs
4.3. GNS (Goodnight System) Integration
If enabled (UseGNS), the driver sends notifications to an external monitoring system called GNS. This is achieved by writing formatted strings to a named pipe called GNSBridge.
The GNSType enum defines the type of message to be sent:
Message: A simple informational message.New: A new long-running task with a timeout.Alarm: A critical alarm message.Stop: A message indicating a task has stopped/completed.Cease: A message to cancel a running task.
Sources: GNS/GNS.cs:9-17, GNS/GNS.cs:25-41