Home
Relevant source files
The following files were used as context for generating this wiki page:
The "Home" feature provides the dome with the ability to move to a predefined, fixed position. This is a fundamental capability exposed through the ASCOM interface, allowing client applications to reliably orient the dome. The driver manages the entire homing sequence, from command initiation to completion monitoring and error handling.
The driver reports its ability to perform this action via the CanFindHome property, which is hardcoded to return true. The homing process is initiated by calling the FindHome() method. The state of the dome relative to its home position is tracked by the AtHome property, which reads the HomeStatus flag from the configuration.
Sources: Driver/Pulsar_DomeDriver.cs:1521, Driver/Pulsar_DomeDriver.cs:1551-1558, Config/ConfigManager.cs:64
Homing Process Overview
The homing process is managed by the ExecuteDomeCommand helper method, which provides a standardized framework for long-running actions. When FindHome() is called, it delegates the entire operation to this central command executor.
This diagram illustrates the high-level flow when an ASCOM client initiates the homing sequence.
Command Initiation (FindHome)
The public FindHome() method is the entry point for the homing action. It encapsulates all the necessary parameters for the ExecuteDomeCommand helper, defining the specific command, timeouts, and success conditions for the homing operation.
Key actions performed by FindHome():
- Defines the serial command as
"GO H". - Sets the
DomeCommandIntenttoGoHome. - Specifies the timeout using the
RotationTimeoutvalue from the configuration. - Provides a lambda function
() => _config.HomeStatusto check if the dome is already at the home position, skipping the command if true. - Provides a lambda function for the
ActionWatchdogto determine success (_config.HomeStatusis true). - Configures GNS and MQTT messages for the start, success, and failure of the operation.
Sources: Driver/Pulsar_DomeDriver.cs:1802-1828
FindHome Parameters
The FindHome method passes a set of specific arguments to the generic ExecuteDomeCommand function.
| Parameter | Value / Logic | Source File |
|---|---|---|
command | "GO H" | Driver/Pulsar_DomeDriver.cs:1807 |
message | "Finding Home..." | Driver/Pulsar_DomeDriver.cs:1803 |
timeoutMs | _config.RotationTimeout | Driver/Pulsar_DomeDriver.cs:1804 |
intent | DomeCommandIntent.GoHome | Driver/Pulsar_DomeDriver.cs:1808 |
alreadyAtTarget | () => _config.HomeStatus | Driver/Pulsar_DomeDriver.cs:1809 |
updateConfigBeforeWatchdog | Sets DomeState to 9 (going home) and SlewingStatus to true. | Driver/Pulsar_DomeDriver.cs:1810-1814 |
checkStatus | Returns Success if _config.HomeStatus is true, otherwise InProgress. | Driver/Pulsar_DomeDriver.cs:1815-1820 |
mqttTopic | _mqttDomeStatus ("Dome/Dome/Status") | Driver/Pulsar_DomeDriver.cs:1821 |
mqttSuccess | "Dome is at home." | Driver/Pulsar_DomeDriver.cs:1822 |
mqttFail | "Dome failed to find home." | Driver/Pulsar_DomeDriver.cs:1823 |
State Monitoring and Completion
The driver determines the homing status through two primary mechanisms: the background polling loop and the ActionWatchdog.
1. Status Polling (ParseHomeStatus)
The background polling loop periodically calls DomeStatus(), which in turn calls ParseHomeStatus(). This method sends the HOME ? command to the controller. The controller is expected to respond with 1 if at home or 0 if not. This response directly updates the _config.HomeStatus boolean property.
Sources: Driver/Pulsar_DomeDriver.cs:1040-1065
This sequence diagram shows how the driver queries the home status.
2. Action Watchdog
When FindHome() is called, an ActionWatchdog instance is created and started. This watchdog runs in a separate task and periodically checks for completion or timeout.
- Success Condition: The watchdog repeatedly invokes the
checkStatusfunction provided byFindHome(). This function returnsWatchdogResult.Successonce_config.HomeStatusbecomestrue. - Timeout: If the
RotationTimeoutduration is exceeded before the success condition is met, the watchdog triggers aTimeoutresult. - Failure/Error: If the check returns an error state, it triggers a
FailureorErrorresult.
Upon timeout or failure, the watchdog is configured to call the ResetRoutineAsync to attempt automatic recovery of the dome controller. On success, it simply exits and allows normal operation to resume.
Sources: Helper/ActionWatchdog.cs:64-106, Driver/Pulsar_DomeDriver.cs:1815-1820
External System Integration
The homing process integrates with external notification systems if they are enabled in the settings.
GNS (Goodnight System)
If GNS is enabled (_config.UseGNS), messages are sent to the GNS named pipe to provide real-time feedback.
- Initiation: A "New" message
Finding Home...is sent with a calculated timeout. - Completion: A "Stop" message
Dome homed successfullyis sent upon successful completion. - Failure: An "Alarm" message is sent if the command fails or the watchdog times out.
Sources: GNS/GNS.cs:25-45, Driver/Pulsar_DomeDriver.cs:1803, Driver/Pulsar_DomeDriver.cs:901-903
MQTT
If MQTT is enabled (_config.UseMQTT), status updates are published to the MQTT broker.
- Initiation: A message is published to the
Dome/Dome/Statustopic indicating the start of the action. - Success: A message
"Dome is at home."is published to the same topic. - Failure: A message
"Dome failed to find home."is published.
Sources: MQTT/MqttPublisher.cs:92-120, Driver/Pulsar_DomeDriver.cs:1821-1823
Configuration
The behavior of the homing function is influenced by several settings configured through the SettingsForm and stored in the ASCOM profile.
| Setting | UI Control | Description | Source File |
|---|---|---|---|
RotationTimeout | txtBoxRotationTimeout | The maximum time (in seconds) allowed for the homing sequence to complete before a timeout occurs. | Config/ConfigManager.cs:208-224, UI/SettingsForm.cs:78 |
UseGNS | chkBoxGNS | Enables or disables sending notifications to the Goodnight System. | Config/ConfigManager.cs:274-285, UI/SettingsForm.cs:59 |
UseMQTT | chkBoxMQTT | Enables or disables publishing status updates to an MQTT broker. | Config/ConfigManager.cs:262-273, UI/SettingsForm.cs:55 |
Sources: Config/ConfigManager.cs, UI/SettingsForm.cs, UI/SettingsForm.Designer.cs