Quick Start Guide

Relevant source files

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

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

This document provides a technical overview and quick start guide for the Pulsar_DomeDriver, an ASCOM dome driver designed to interface with the Pulsar dome controller. The driver communicates via a serial port and implements the IDomeV2 interface.

The driver's architecture emphasizes robustness and recovery. It features a continuous polling mechanism to monitor dome status, an action-specific watchdog to ensure commands complete successfully, and a system-level watchdog to monitor the health of the polling loop. A key feature is its automated reset routine, which can perform soft (command-based) or hard (external executable) resets of the controller in case of command timeouts or failures, followed by an attempt to replay the last command. The driver also supports optional integrations with MQTT for status publishing and GNS (Goodnight System) for user notifications.

Configuration

The driver is configured through the ASCOM setup dialog, which launches the SettingsForm. Configuration values are stored in the ASCOM profile registry.

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

Settings UI

The settings form provides a user interface to configure all major operational parameters.

This diagram shows the layout of the settings UI, which is divided into general settings, GNS settings, and reset settings.

Configuration Parameters

The following table details the configuration options managed by ConfigManager and exposed in the SettingsForm.

Parameter	UI Control	Description	Default Value	Source File
SerialPort	comboBoxSerialPort	The COM port for communicating with the dome controller.	""	Config/ConfigManager.cs:91-95
LogLocation	txtBoxLogLocation	The directory path for storing log files.	""	Config/ConfigManager.cs:127-131
UseMQTT	chkBoxMQTT	Enables or disables MQTT status publishing.	false	Config/ConfigManager.cs:235-245
DebugLog	chkBoxDebugLog	Enables verbose debug-level logging.	false	Config/ConfigManager.cs:213-223
TraceLog	chkBoxTraceLog	Enables highly verbose trace-level logging.	false	Config/ConfigManager.cs:225-233
UseGNS	chkBoxGNS	Enables or disables GNS notifications.	false	Config/ConfigManager.cs:247-257
GNSPath	txtBoxGNSLocation	Path to the GNS executable.	""	Config/ConfigManager.cs:259-263
SoftReset	checkBoxInternalReset	Enables the software-based RESTART command for recovery.	false	Config/ConfigManager.cs:97-107
HardReset	checkBoxExternalReset	Enables recovery via an external power-cycling executable.	false	Config/ConfigManager.cs:109-119
ResetExe	txtBoxExternalExe	Path to the external reset executable.	""	Config/ConfigManager.cs:133-137
ResetOnParameters	txtBoxOnParameters	Command-line arguments for the reset executable to turn power ON.	""	Config/ConfigManager.cs:139-143
ResetOffParameters	txtBoxOffParameters	Command-line arguments for the reset executable to turn power OFF.	""	Config/ConfigManager.cs:145-149
ShutterTimeout	txtBoxShutterTimeout	Timeout in milliseconds for shutter open/close operations.	90000	Config/ConfigManager.cs:173-188
RotationTimeout	txtBoxRotationTimeout	Timeout in milliseconds for dome rotation operations.	90000	Config/ConfigManager.cs:190-205
ResetDelay	txtBoxResetDelay	Delay in milliseconds to wait for the controller to boot after a hard reset.	5000	Config/ConfigManager.cs:151-161
CycleDelay	txtBoxCycleDelay	Delay in milliseconds between power-off and power-on during a hard reset.	5000	Config/ConfigManager.cs:163-171

Sources: Config/ConfigManager.cs, UI/SettingsForm.cs:20-88

System Architecture

The driver is built around a central DomeDriver class that orchestrates several helper components to manage state, communication, and error handling.

This diagram illustrates the primary classes and their relationships within the driver.

Core Operations

Connection and Polling

When the driver connects, it initializes the serial port, pings the controller, and starts two background processes: a status polling loop and a system watchdog.

1. Connection: The ConnectController method opens the configured serial port and sends a "PULSAR" command, expecting a "Y519" response to verify the connection.
2. Polling Loop: StartPolling initiates PollLoopAsync, which periodically calls DomeStatus to query the controller for its current state (azimuth, shutter status, etc.). The polling interval is configured via _config._pollingIntervalMs.
3. System Watchdog: StartWatchdog monitors the _lastPollTimestamp. If the polling loop stalls for more than _pollingStallThreshold (10 seconds), the watchdog restarts it. It also publishes a periodic MQTT heartbeat.

This sequence diagram shows the driver connection and the startup of background tasks.

Dome Command Execution

All major dome actions (slew, open/close, home, park) are managed by the ExecuteDomeCommand helper method. This method provides a standardized, robust wrapper for sending commands and monitoring their completion.

The process is as follows:

1. The client calls an action, e.g., SlewToAzimuth(180).
2. ExecuteDomeCommand is invoked with parameters specific to the action (command string, timeout, success condition).
3. Polling is temporarily stopped to ensure exclusive serial port access.
4. The command (e.g., "ABS 180") is sent to the controller. An "A" (Acknowledge) response is expected.
5. If acknowledged, an ActionWatchdog is started. This watchdog monitors the dome's state until the success condition is met (e.g., _config.DomeState == 0) or a timeout occurs.
6. Polling is resumed. The polling loop provides the fresh status data that the ActionWatchdog uses to check for completion.
7. If the watchdog times out or detects an error, it triggers the ResetRoutineAsync.

This diagram shows the flow for executing a dome command.

Reset and Recovery

The driver's automatic recovery mechanism, ResetRoutineAsync, is a critical feature for unattended operation. It is triggered by the ActionWatchdog when a command fails to complete within its timeout or returns an error state.

The routine attempts recovery in two stages:

1. Soft Reset: If enabled (_config.SoftReset), it sends a RESTART command to the controller. It then waits for the controller to come back online, identified by a valid shutter status.
2. Hard Reset: If the soft reset is disabled or fails, and hard reset is enabled (_config.HardReset), the driver executes an external program (_config.ResetExe). This program is expected to power-cycle the dome controller. The driver disconnects the serial port, runs the executable with "OFF" parameters, waits for CycleDelay, runs it again with "ON" parameters, waits for ResetDelay, and then attempts to reconnect.

After a successful reset, the driver attempts to replay the last command that failed. If all reset attempts fail, an unrecoverable alarm is logged and sent via GNS and MQTT.

This flowchart illustrates the logic of the reset and recovery routine.

Supported Actions

In addition to standard ASCOM commands, the driver exposes custom actions that can be triggered by a client. These actions allow for manual initiation of the reset routines.

public ArrayList SupportedActions => new ArrayList
{
    "Full Reset",
    "Soft Reset",
    "Hard Reset"
};

Sources: Driver/Pulsar_DomeDriver.cs:2020-2027

External Integrations

MQTT

If enabled, the MqttPublisher class connects to a local MQTT broker (localhost:1883) and publishes status updates and alerts to various topics. This allows external systems to monitor the dome's state and driver health.

Key MQTT Topics:

• Dome/DriverStatus: Driver connection status.
• Dome/Dome/Status: Dome state, azimuth, etc.
• Dome/Shutter/Status: Shutter state.
• Dome/Alarm: Critical failure alarms.
• Dome/Watchdog: Periodic heartbeat from the system watchdog.

Sources: Driver/Pulsar_DomeDriver.cs:85-92, 1475-1502, MQTT/MqttPublisher.cs

GNS (Goodnight System)

If enabled, the GNS class sends formatted messages to the "GNSBridge" named pipe. This is used to provide real-time notifications to the user about dome operations, completions, and alarms.

GNS Message Types:

• Message: A simple informational message.
• New: A message with a specific timeout.
• Alarm: A critical alert that requires attention.
• Stop: Indicates a process has completed successfully.
• Cease: Indicates a process was aborted.

Sources: Driver/Pulsar_DomeDriver.cs:95, GNS/GNS.cs

Summary

The Pulsar Dome Driver is a comprehensive ASCOM driver that provides reliable control over a Pulsar dome. Its architecture is designed for resilience, featuring multi-layered watchdogs and an automated, two-stage reset-and-recovery mechanism. By integrating status polling, command-specific action monitoring, and optional MQTT/GNS notifications, the driver is well-suited for robust, unattended observatory operations. Initial setup is handled through a standard ASCOM configuration dialog, allowing users to tailor communication, logging, and recovery parameters to their specific hardware setup.