Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• Properties/Resources.Designer.cs
• Driver/Pulsar_DomeDriver.cs
• UI/SettingsForm.Designer.cs
• Helper/ActionWatchdog.cs
• Diagnostics/FileLogger.cs
• GNS/GNS.cs
• Properties/AssemblyInfo.cs
• Config/ConfigManager.cs
• MQTT/MqttPublisher.cs
• UI/SettingsForm.cs
• Helper/ResponseResult.cs
• Helper/SerialPortGuard.cs
• MQTT/WatchDogLogger.cs

This document provides a technical overview of the Pulsar_DomeDriver, an ASCOM dome driver designed to interface with the Pulsar dome controller. The driver facilitates communication over a serial port, manages dome state through continuous polling, and executes commands such as slewing, parking, and controlling the shutter.

A key feature of this driver is its robust fault tolerance, which includes an automated reset mechanism for both software and hardware-level recovery from command failures or communication stalls. The driver also supports external integrations via MQTT for status publishing and the Goodnight System (GNS) for notifications.

System Architecture

The driver is built around the main DomeDriver class, which orchestrates several helper components to manage state, configuration, communication, and logging.

The diagram below illustrates the high-level architecture and the relationships between the primary classes.

This diagram shows the DomeDriver class as the central component, interacting with helper classes to perform its functions.
Sources: Driver/Pulsar_DomeDriver.cs, Config/ConfigManager.cs, Diagnostics/FileLogger.cs, Helper/SerialPortGuard.cs, Helper/ActionWatchdog.cs, MQTT/MqttPublisher.cs, GNS/GNS.cs

Configuration

Configuration is managed by the ConfigManager class, which reads and writes settings to the ASCOM profile. A graphical user interface, SettingsForm, is provided for user-friendly configuration.

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

Key Configuration Parameters

The following table details important settings that can be configured through the SettingsForm.

Setting	UI Control	Description	Source File
Serial Port	comboBoxSerialPort	The COM port for communicating with the dome controller.	UI/SettingsForm.cs:34
Log Location	txtBoxLogLocation	The directory where log files will be saved.	UI/SettingsForm.cs:46
Debug/Trace Log	chkBoxDebugLog, chkBoxTraceLog	Enables verbose logging for debugging and tracing.	UI/SettingsForm.cs:49-50
Use MQTT	chkBoxMQTT	Enables publishing status and alarms to an MQTT broker.	UI/SettingsForm.cs:48
Use GNS	chkBoxGNS	Enables sending notifications to the Goodnight System (GNS).	UI/SettingsForm.cs:52
Internal Reset	checkBoxInternalReset	Enables the software-based reset (RESTART command).	UI/SettingsForm.cs:59
External Reset	checkBoxExternalReset	Enables the hardware-based reset using an external executable.	UI/SettingsForm.cs:60
Reset Executable	txtBoxExternalExe	Path to the executable used for a hard reset.	UI/SettingsForm.cs:61
On/Off Parameters	txtBoxOnParameters, txtBoxOffParameters	Command-line arguments for the reset executable.	UI/SettingsForm.cs:67-70
Shutter Timeout	txtBoxShutterTimeout	Timeout in seconds for shutter open/close operations.	UI/SettingsForm.cs:73
Rotation Timeout	txtBoxRotationTimeout	Timeout in seconds for dome rotation (slew/home/park).	UI/SettingsForm.cs:74
Reboot Delay	txtBoxResetDelay	Delay in seconds to wait for the controller to come online after a hard reset.	UI/SettingsForm.cs:75
Cycle Delay	txtBoxCycleDelay	Delay in seconds between turning the controller power off and on during a hard reset.	UI/SettingsForm.cs:76

Sources: Config/ConfigManager.cs:100-247, UI/SettingsForm.cs:83-104

Operational Flow

Connection Lifecycle

Connecting the driver involves opening the serial port, creating a SerialPortGuard to manage access, and pinging the controller to verify communication. Once connected, a background polling task and a system watchdog are started.

The following sequence diagram illustrates the connection process.

Status Polling

After connecting, the driver starts a background polling loop (PollLoopAsync) that periodically queries the dome's status by sending a "V" command. This loop is responsible for updating all state variables, such as azimuth, shutter status, and dome motion.

A separate system watchdog (_systemWatchdogTask) runs every 5 seconds to ensure the polling loop has not stalled. If the last poll timestamp is older than 10 seconds, the watchdog will restart the polling mechanism.

This diagram shows the polling and watchdog logic.

Command Execution and Watchdog

All dome actions (e.g., SlewToAzimuth, OpenShutter) are dispatched through a centralized ExecuteDomeCommand method. This method sends the command to the controller and then starts an ActionWatchdog to monitor the command's progress and handle timeouts.

The ActionWatchdog checks the dome's status until it reaches the desired state (e.g., shutter is open, azimuth is reached) or until a timeout occurs. If a timeout happens, it can trigger the Fault Tolerance and Reset Mechanism.

Fault Tolerance and Reset Mechanism

A critical feature of the driver is its ability to automatically recover from failures. If an ActionWatchdog times out or a command fails to receive an acknowledgment, the ResetRoutineAsync method is invoked.

The reset routine follows a tiered approach:

1. Soft Reset: If enabled, it first attempts a "soft" reset by sending the RESTART command to the controller.
2. Hard Reset: If the soft reset is disabled or fails, it proceeds to a "hard" reset. This involves executing an external program (e.g., a script to control a smart plug) to power-cycle the dome controller.

After a successful reset, the driver attempts to replay the last command that failed.

External Integrations

MQTT

If enabled (UseMQTT is true), the driver uses the MqttPublisher class to connect to an MQTT broker. It publishes status updates, command progress, and critical alarms to predefined topics.

• Status Topics: Dome/DriverStatus, Dome/Dome/Status, Dome/Shutter/Status
• Alarm Topic: Dome/Alarm
• Watchdog Heartbeat: Dome/Watchdog

Sources: Driver/Pulsar_DomeDriver.cs:91-96, MQTT/MqttPublisher.cs, Driver/Pulsar_DomeDriver.cs:1411-1436

GNS (Goodnight System)

If enabled (UseGNS is true), the driver uses the GNS class to send formatted messages to the "GNSBridge" named pipe. This allows for integration with the Goodnight System for audible or visual notifications. Message types include Message, New, Alarm, Stop, and Cease.

Sources: GNS/GNS.cs, Config/ConfigManager.cs:229-238

ASCOM Interface

The driver implements the IDomeV2 ASCOM interface and exposes several standard capabilities.

Capability	Supported	Notes
CanFindHome	true	Executes the GO H command.
CanPark	true	Executes the GO P command.
CanSetAzimuth	true	Executes the ABS {azimuth} command.
CanSetShutter	true	Executes OPEN or CLOSE commands.
CanSetPark	true	Defines the current position as the park position.
CanSlave	false	Not implemented.
CanSyncAzimuth	false	Not implemented.

Sources: Driver/Pulsar_DomeDriver.cs:1667-1675

Custom Actions

In addition to standard ASCOM methods, the driver provides custom actions that can be invoked by name. These are primarily for manual intervention and testing.

Action Name	Description
Full Reset	Initiates the full ResetRoutineAsync, attempting soft then hard reset if necessary.
Soft Reset	Forces a soft reset only.
Hard Reset	Forces a hard reset only.

// Example of how actions are handled
public string Action(string actionName, string actionParameters = "")
{
    _logger?.Log($"Action called: {actionName}...", LogLevel.Info);

    if (actionName == "Full Reset")
    {
        Task.Run(async () => await ResetRoutineAsync());
        return "Reset initiated";
    }
    else if (actionName == "Soft Reset")
    {
        Task.Run(async () => await ResetRoutineAsync("soft"));
        return "Soft Reset executed";
    }
    // ...
}

Sources: Driver/Pulsar_DomeDriver.cs:2020-2045

Summary

The Pulsar_DomeDriver provides a comprehensive and resilient solution for controlling a Pulsar dome. Its architecture is designed for stability, with asynchronous operations, thread-safe communication via SerialPortGuard, and state management through continuous polling. The standout feature is the automated, multi-tiered reset mechanism, which ensures high availability by recovering from common hardware and communication faults. Integrations with MQTT and GNS further enhance its utility in an automated observatory environment.