Installation and Registration

Relevant source files

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

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

The Pulsar_DomeDriver integrates with the ASCOM platform through standard COM registration. This process not only makes the driver discoverable by ASCOM-compliant client software but also establishes a set of initial configuration values in the Windows Registry. These settings, which control everything from serial port communication to advanced features like MQTT and GNS integration, are managed through a dedicated SettingsForm.

This document outlines the technical details of the driver's registration process, the initial configuration created, and the user interface for managing these settings. The core components involved are the DomeDriver class, which handles COM interop, the ConfigManager, which abstracts registry access, and the SettingsForm, which provides the user-facing configuration interface.

ASCOM COM Registration

The driver is registered as a COM component, allowing it to be used by the ASCOM platform. This is handled by methods decorated with [ComRegisterFunction] and [ComUnregisterFunction]. The unique identifier for this COM object is defined in AssemblyInfo.cs.

• GUID: 5096766c-f998-42bd-a22d-8f0a00ed4b51
• ProgId: Pulsar_DomeDriver

Sources: Driver/Pulsar_DomeDriver.cs:19-21, Properties/AssemblyInfo.cs:25

Registration Process

When the driver is registered (e.g., by an installer), the RegisterASCOM method is executed. This method performs two key actions:

1. It calls a helper function, RegUnregASCOM(true), which uses the ASCOM.Utilities.Profile class to register the driver with the ASCOM platform as a "Dome" device.
2. It instantiates a ConfigManager and calls the RegistryEntries() method to populate the Windows Registry with default configuration values for the driver.

This ensures that the driver is both discoverable and has a baseline configuration from the moment it is installed.

The following diagram illustrates the registration flow.

Unregistration Process

Conversely, the UnregisterASCOM method calls RegUnregASCOM(false), which removes the driver's registration from the ASCOM platform. It does not, however, remove the configuration settings from the registry.

Sources: Driver/Pulsar_DomeDriver.cs:2106-2110

// Driver/Pulsar_DomeDriver.cs:2088-2103
[ComRegisterFunction]
public static void RegisterASCOM(Type t)
{
    RegUnregASCOM(true);

    try
    {
        using var profile = new ASCOM.Utilities.Profile { DeviceType = "Dome" };
        var logger = new FileLogger("PulsarDome_Registration", LogLevel.Error); // Or null if logging isn't needed here

        var config = new ConfigManager(profile, logger);
        config.RegistryEntries();
    }
    catch (Exception ex)
    {
        System.Diagnostics.Debug.WriteLine($"Registry prepopulation failed: {ex.Message}");
    }
}

This code snippet shows the main registration function that sets up the driver.

Configuration Management

Configuration is managed through the ConfigManager class, which serves as an intermediary between the driver logic and the ASCOM Profile (stored in the Windows Registry).

Component Interaction

The DomeDriver instantiates the ConfigManager to access settings. When a user needs to change settings, the DomeDriver.SetupDialog() method creates and displays the SettingsForm, passing it a ConfigManager instance. The form reads the current configuration and, upon closing with "OK", writes the new values back through the ConfigManager.

Initial Registry Settings

Upon registration, the RegistryEntries method in ConfigManager is called to create a set of default values. These values ensure the driver has a valid state before any user configuration.

The following table details the keys, default values, and descriptions for the initial configuration.

Registry Key	Default Value	Description
SerialPort	"" (empty string)	The COM port for communicating with the dome controller.
LogLocation	"" (empty string)	The directory path for storing log files.
ResetExe	"" (empty string)	Path to the external executable for a hard reset.
ResetParameters	"" (empty string)	Note: This key appears in the code but seems to be superseded by ResetOnParameters and ResetOffParameters.
ExternalReset	false	Enables the external (hard) reset feature.
InternalReset	false	Enables the internal (soft) reset feature.
ShutterTimeout	90	Timeout in seconds for shutter operations.
RotationTimeout	90	Timeout in seconds for dome rotation.
ResetDelay	30	Delay in seconds after a hard reset before attempting reconnection.
CycleDelay	10	Delay in seconds between power-off and power-on commands during a hard reset.
DebugLog	false	Enables detailed debug-level logging.
TraceLog	false	Enables highly verbose trace-level logging.
MQTT	false	Enables MQTT message publishing.
GNS	false	Enables integration with the Good Night System (GNS).
GNSPath	"" (empty string)	Path to the GNS executable.
GNSDispatcherPath	"" (empty string)	Path to the GNS Dispatcher executable.

Sources: Config/ConfigManager.cs:331-352

Setup Dialog (SettingsForm)

The SettingsForm provides a graphical interface for users to modify the driver's configuration. It is launched when an ASCOM client requests the driver's setup dialog.

UI Components and Configuration

The form contains controls for all major configuration options. When the form loads (SettingsForm_Load), it populates the UI controls with values read from the ConfigManager.

Key UI elements include:

• comboBoxSerialPort: A dropdown to select the serial port.
• txtBoxLogLocation: A text box for the log file path.
• chkBoxMQTT, chkBoxDebugLog, chkBoxTraceLog, chkBoxGNS: Checkboxes to enable/disable features.
• groupBox1 (Reset): Contains controls for configuring soft and hard reset behavior, including timeouts and external executable paths.
• groupBox2 (GNS): Contains controls for enabling GNS and specifying executable paths.

When the user clicks the "OK" button (btnOK_Click), the values from the UI controls are written back to the ConfigManager, which persists them to the registry.