Contributing to the Project

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
• Diagnostics/FileLogger.cs
• MQTT/MqttPublisher.cs
• GNS/GNS.cs
• UI/SettingsForm.cs
• UI/SettingsForm.Designer.cs
• Helper/ResponseResult.cs
• Properties/AssemblyInfo.cs
• MQTT/WatchDogLogger.cs
• Properties/Resources.Designer.cs

This document provides a technical overview of the Pulsar ASCOM Dome Driver. The driver is designed to control a Pulsar dome via serial communication, offering robust error handling, status monitoring, and integration with external systems like MQTT and the Goodnight System (GNS). Its architecture is centered around a state-management and polling engine, with watchdog timers to ensure operational reliability.

The core functionality includes connecting to the dome controller, polling for status updates, executing commands (e.g., slewing, opening/closing shutter), and automatically recovering from errors. Recovery mechanisms include both soft (command-based) and hard (external process-based) resets of the controller hardware. This guide details the key components, their interactions, and the overall data flow, serving as a reference for developers contributing to the project.

1. System Architecture

The driver is composed of several key classes that manage configuration, communication, state, and error handling. The DomeDriver class is the central orchestrator, implementing the ASCOM IDomeV2 interface and coordinating all other components.

Sources: Driver/Pulsar_DomeDriver.cs, Config/ConfigManager.cs, Helper/ActionWatchdog.cs, Helper/SerialPortGuard.cs, MQTT/MqttPublisher.cs, GNS/GNS.cs

1.1. Core Component Diagram

The following diagram illustrates the primary classes and their relationships.

This diagram shows that DomeDriver is the central component, utilizing helper classes for specific functions: ConfigManager for settings, SerialPortGuard for communication, ActionWatchdog for monitoring, and MqttPublisher/GNS for external notifications.

Sources: Driver/Pulsar_DomeDriver.cs:28-86, Config/ConfigManager.cs, Helper/ActionWatchdog.cs, Helper/SerialPortGuard.cs, MQTT/MqttPublisher.cs, GNS/GNS.cs, Diagnostics/FileLogger.cs

2. Configuration Management

Configuration is managed by the ConfigManager class, which uses the ASCOM.Utilities.Profile object to store and retrieve settings from the Windows Registry. This provides persistence for driver settings between sessions. The settings are configured via the SettingsForm.

Sources: Config/ConfigManager.cs:39-44, UI/SettingsForm.cs:15-20

2.1. Key Configuration Parameters

The following settings are managed by ConfigManager and are configurable through the UI.

Setting	Type	Description	Source File
SerialPort	string	The COM port used to communicate with the dome controller.	Config/ConfigManager.cs:100-104
LogLocation	string	The directory path for storing log files.	Config/ConfigManager.cs:140-144
DebugLog / TraceLog	bool	Enables verbose logging for debugging and tracing purposes.	Config/ConfigManager.cs:228-248
UseMQTT	bool	Enables or disables publishing status updates to an MQTT broker.	Config/ConfigManager.cs:250-260
UseGNS	bool	Enables or disables sending notifications to the Goodnight System (GNS).	Config/ConfigManager.cs:262-272
SoftReset (InternalReset)	bool	Enables the software-based reset routine (RESTART command).	Config/ConfigManager.cs:106-116
HardReset (ExternalReset)	bool	Enables the hardware-based reset routine using an external executable.	Config/ConfigManager.cs:118-128
ResetExe	string	Path to the external executable used for the hard reset.	Config/ConfigManager.cs:146-150
ResetOnParameters	string	Command-line arguments for the ResetExe to turn the controller on.	Config/ConfigManager.cs:152-156
ResetOffParameters	string	Command-line arguments for the ResetExe to turn the controller off.	Config/ConfigManager.cs:158-162
ShutterTimeout	int	Timeout in milliseconds for shutter open/close operations.	Config/ConfigManager.cs:188-204
RotationTimeout	int	Timeout in milliseconds for dome rotation (slew, home, park) operations.	Config/ConfigManager.cs:206-222
ResetDelay	int	Delay in milliseconds to wait for the controller to come online after a hard reset.	Config/ConfigManager.cs:164-174
CycleDelay	int	Delay in milliseconds between turning the controller off and on during a hard reset.	Config/ConfigManager.cs:176-186

Sources: Config/ConfigManager.cs, UI/SettingsForm.cs, UI/SettingsForm.Designer.cs

3. Core Driver Logic

The DomeDriver class contains the primary logic for managing the dome's state, handling commands, and ensuring reliable operation.

Sources: Driver/Pulsar_DomeDriver.cs

3.1. State Management and Polling

The driver maintains the dome's current state (azimuth, shutter status, etc.) in the ConfigManager object. This state is continuously updated by a background polling loop.

• Polling Loop: The PollLoopAsync method runs in a background task, periodically calling DomeStatus() to query the controller. The polling interval is configured via _config._pollingIntervalMs.
• State Update: The DomeStatus() method sends commands (V, HOME ?, PARK ?) to the controller and parses the responses to update properties in ConfigManager, such as Azimuth, ShutterStatus, DomeState, HomeStatus, and ParkStatus.
• System Watchdog: A separate watchdog, StartWatchdog(), monitors the polling loop itself. If the _lastPollTimestamp is not updated within a threshold (_pollingStallThreshold), it assumes the polling loop has stalled and restarts it.

Sources: [Driver/Pulsar_DomeDriver.cs:531-641, 643-690, 810-998]

The following diagram shows the flow of the main polling loop.

3.2. Command Execution and Watchdogs

Long-running commands like slewing or moving the shutter are executed asynchronously and monitored by an ActionWatchdog.

1. Command Initiation: An ASCOM client calls a method like SlewToAzimuth().
2. ExecuteDomeCommand: This private helper method is called. It stops the polling loop, sends the appropriate command (e.g., ABS 180) to the controller via SendAndVerify, and then starts an ActionWatchdog.
3. ActionWatchdog: The watchdog is configured with a timeout, a status-checking function, and a reset routine. It runs in a separate task.
4. Status Checking: The watchdog periodically invokes its _checkStatus function, which reads the current dome state from ConfigManager to determine if the action has succeeded (e.g., _config.DomeState == 0 and azimuth is correct).
5. Polling Resumption: The polling loop is restarted immediately after the command is sent to monitor the progress of the action.
6. Completion/Timeout:
   • If the polling loop detects the target state is reached, it calls _actionWatchdog.MarkSuccess().
   • If the watchdog's timer expires before success is marked, it triggers the _resetRoutine, which initiates the Error Handling and Reset Mechanism.

Sources: Driver/Pulsar_DomeDriver.cs:1614-1690, 1692-1750, [Helper/ActionWatchdog.cs:64-142]

This sequence diagram shows the process for a SlewToAzimuth command.

4. Error Handling and Reset Mechanism

A key feature of this driver is its multi-tiered approach to recovering from hardware or communication failures. This is primarily managed by the ResetRoutineAsync method.

Sources: [Driver/Pulsar_DomeDriver.cs:1088-1249]

4.1. Reset Triggers

A reset can be triggered by:

• An ActionWatchdog timing out.
• A command failing to receive an expected acknowledgement (ACK).
• A manual call via the "Full Reset", "Soft Reset", or "Hard Reset" ASCOM actions.

Sources: Helper/ActionWatchdog.cs:109-116, [Driver/Pulsar_DomeDriver.cs:1645-1647, 2011-2033]

4.2. Reset Flow

The ResetRoutineAsync follows a specific sequence to attempt recovery.

4.3. Reset Types

• Soft Reset: If enabled (SoftReset is true), the driver sends a RESTART command to the controller. It then monitors the shutter status to confirm a reboot sequence has occurred and waits for the controller to become ready.
  Sources: [Driver/Pulsar_DomeDriver.cs:1286-1317]
• Hard Reset: If enabled (HardReset is true) and the soft reset fails or is disabled, the driver executes an external process (ResetExe). This process is expected to physically power-cycle the dome controller.
  1. The serial port is disconnected.
  2. The ResetExe is launched with ResetOffParameters.
  3. After a CycleDelay, the ResetExe is launched again with ResetOnParameters.
  4. After a ResetDelay, the driver attempts to reconnect to the serial port and waits for the controller to become ready.
     Sources: [Driver/Pulsar_DomeDriver.cs:1319-1385, 1410-1454]

After a successful reset, the ReplayLastCommand method is called to re-issue the command that was in progress before the failure.

Sources: [Driver/Pulsar_DomeDriver.cs:1456-1487]

5. Communication Interfaces

5.1. Serial Communication

All direct communication with the dome controller happens over a serial port. To prevent race conditions and ensure thread safety, all serial port access is mediated by the SerialPortGuard class.

• Semaphore Lock: The SerialPortGuard uses a SemaphoreSlim(1, 1) to ensure only one thread can write to or read from the port at a time.
• Command Dispatch: The Send method waits on the semaphore, discards any stale data in the serial buffers, writes the command, and reads the response with a fixed timeout.
• Busy Flags: It uses _setBusy and _clearBusy actions to signal to the DomeDriver when a command is actively being processed, which helps coordinate the polling loop.

Sources: [Helper/SerialPortGuard.cs:23-93]

5.2. MQTT Integration

If UseMQTT is enabled, the driver publishes status updates to an MQTT broker using the MqttPublisher class.

• Connection: MqttPublisher.InitializeAsync connects to the broker.
• Topics: Status messages are published to predefined topics:
  • Dome/DriverStatus: Driver connection status.
  • Dome/Dome/Status: Dome activity (e.g., slewing, idle).
  • Dome/Shutter/Status: Shutter activity (e.g., opening, closed).
  • Dome/Alarm: Critical failure notifications.
  • Dome/Watchdog: Heartbeat messages from the system watchdog.
• Publishing: The TryMQTTPublish helper method in DomeDriver provides a null-safe, non-blocking way to send messages.

Sources: Driver/Pulsar_DomeDriver.cs:81-86, 1521-1529, [MQTT/MqttPublisher.cs:59-101]

5.3. GNS (Goodnight System) Integration

If UseGNS is enabled, the driver sends notifications to the Goodnight System via a named pipe (GNSBridge). The GNS class formats messages according to the GNSType enum (e.g., Message, New, Alarm) and sends them. This is used to provide user-facing status updates and alerts.

Sources: GNS/GNS.cs:24-43, [Driver/Pulsar_DomeDriver.cs:89, 981-996]