GNS Functionality
Relevant source files
The following files were used as context for generating this wiki page:
The Goodnight Notification System (GNS) is an optional messaging feature within the Pulsar Dome Driver. Its primary purpose is to dispatch status updates, alerts, and operational messages to an external application. This communication is achieved unidirectionally via a named pipe, allowing other processes to monitor the dome driver's state without direct integration.
The GNS functionality is managed by the GNS class, which is responsible for formatting and sending messages. The main DomeDriver class invokes GNS at key events, such as connection changes, command completions, and error states. The feature can be enabled or disabled through the driver's settings dialog.
Sources: GNS/GNS.cs, Driver/Pulsar_DomeDriver.cs
Architecture and Components
The GNS system is composed of several collaborating classes that handle configuration, message creation, and dispatching. The core communication mechanism is a named pipe named "GNSBridge".
Sources: GNS/GNS.cs:31
Component Interaction
The diagram below illustrates the relationship between the main components involved in the GNS functionality.
This diagram shows that the DomeDriver uses an instance of GNS to send messages. Both DomeDriver and GNS rely on ConfigManager to access configuration settings, which are managed through the SettingsForm.
Sources: GNS/GNS.cs:19, Driver/Pulsar_DomeDriver.cs:87, 140, UI/SettingsForm.cs:14
Configuration
GNS functionality is controlled by several settings stored in the ASCOM profile. These can be modified via the driver's setup dialog.
Sources: Config/ConfigManager.cs, UI/SettingsForm.cs, UI/SettingsForm.Designer.cs
Configuration Properties
The following properties in ConfigManager are used to configure GNS:
| Property | Type | Description | Source File |
|---|---|---|---|
UseGNS | bool | Enables or disables the entire GNS messaging system. | Config/ConfigManager.cs:254 |
GNSPath | string | The file path to the GNS executable. Managed by the UI. | Config/ConfigManager.cs:266 |
GNSDispatcherPath | string | The file path to the GNS Dispatcher executable. Managed by the UI. | Config/ConfigManager.cs:272 |
Settings UI
The settings are exposed in the SettingsForm within a dedicated "GNS" group box.
chkBoxGNS: A checkbox to enable or disable GNS. Toggling this controls theUseGNSproperty and the enabled state of other GNS-related controls.txtBoxGNSLocation: A text box to specify the path to the GNS executable (GNSPath).txtBoxGNSDispatherLocation: A text box for the GNS Dispatcher path (GNSDispatcherPath).
Sources: UI/SettingsForm.Designer.cs:424-463, UI/SettingsForm.cs:42-46, 88-90
Message Formatting and Types
Messages sent via GNS are formatted into a pipe-delimited string. The format depends on the message type, which is defined by the GNSType enum.
Sources: GNS/GNS.cs:9-17, 53-66
GNSType Enum
This enumeration defines the different kinds of messages that can be sent.
| Type | Description |
|---|---|
Message | A standard informational message. |
New | A new message that may have a timeout. |
Alarm | An alarm or critical error message. |
Stop | A message indicating an action has stopped or completed. |
Cease | A message indicating a forceful stop or cancellation (e.g., Abort). |
Sources: GNS/GNS.cs:9-17
Message Structure
The FormatMessage private method constructs the final string sent over the named pipe. It sanitizes the message by replacing | with ¦.
// Source: GNS/GNS.cs:53-66
private string FormatMessage(GNSType type, string message, int? timeoutSeconds)
{
string action = type.ToString().ToLowerInvariant();
string safeMessage = message?.Replace("|", "¦").Trim().TrimEnd('.') ?? "";
return type switch
{
GNSType.Message => $"{action}|{safeMessage}",
GNSType.New => $"{action}|{safeMessage}|{timeoutSeconds ?? 0}",
GNSType.Alarm => $"{action}|{safeMessage}|0",
GNSType.Stop => $"{action}|{safeMessage}|-1",
GNSType.Cease => $"{action}|{safeMessage}|-2",
_ => $"{action}|{safeMessage}"
};
}
Data Flow and Usage
The SendGNS method is the public entry point for dispatching a notification. It checks if GNS is enabled, formats the message, and sends it through the "GNSBridge" named pipe.
SendGNS Workflow
The following diagram shows the sequence of events when a GNS message is sent.
This flow ensures that messages are only sent when the feature is active and logs the dispatch for diagnostic purposes. If the pipe connection fails, an error is logged.
Sources: GNS/GNS.cs:25-50
Common GNS Triggers
GNS messages are sent from Pulsar_DomeDriver.cs during significant events:
-
Connection/Disconnection: A
Messagetype is sent when the driver connects or disconnects._GNS.SendGNS(GNSType.Message, "Dome driver connected")_GNS.SendGNS(GNSType.Message, "Dome driver disconnected")
Sources: Driver/Pulsar_DomeDriver.cs:222, 261
-
Reset Routines: Messages are sent to indicate the start of a reset, its completion, or failure.
Alarmtypes are used for unrecoverable failures._GNS.SendGNS(GNSType.Message, "Triggering ResetRoutine...")_GNS.SendGNS(GNSType.Alarm, "Unrecoverable failure...")
Sources: Driver/Pulsar_DomeDriver.cs:1067, 1143
-
Command Completion: A
Stoptype message is sent when a long-running action like homing, parking, or slewing completes successfully. This is triggered within theDomeStatuspolling method._GNS.SendGNS(GNSType.Stop, "Dome homed successfully")_GNS.SendGNS(GNSType.Stop, "Shutter opened successfully")
Sources: Driver/Pulsar_DomeDriver.cs:905-918
-
Abort Slew: An
Alarmis sent if the abort command fails, and aCeasemessage is sent on success._GNS.SendGNS(GNSType.Cease, "Abort succeeded.")_GNS.SendGNS(GNSType.Alarm, "Abort failed (no ACK). Resetting controller.")
Sources: Driver/Pulsar_DomeDriver.cs:1658, 1664
Summary
The GNS functionality provides a robust, one-way notification channel from the Pulsar Dome Driver to external systems. By leveraging named pipes, it decouples the driver from its monitoring tools. The system is highly configurable and provides detailed, type-specific messages for critical driver events, including connection status, command lifecycle, and error recovery, making it a valuable tool for automated observatory management.