Slewing and Azimuth Control
Relevant source files
The following files were used as context for generating this wiki page:The Slewing and Azimuth Control system is a core feature of the Pulsar Dome Driver, responsible for managing the rotational movement of the observatory dome. It provides the functionality for pointing the dome to a specific azimuth, finding the home position, parking the dome, and aborting any movement. The system is designed to be robust, using a combination of direct command execution, continuous status polling, and a watchdog mechanism to handle long-running actions and recover from potential stalls or errors.
This system is primarily implemented within the DomeDriver class, which orchestrates commands, state management, and error handling. It relies on ConfigManager for state variables and settings, SerialPortGuard for safe communication with the controller hardware, and ActionWatchdog to ensure that movement commands complete successfully within a specified timeout.
Core Architecture
The architecture for slewing and azimuth control is built around a few key components that work together to send commands, monitor progress, and manage state.
DomeDriver: The central class that implements the ASCOMIDomeV2interface. It contains the public methods (SlewToAzimuth,FindHome,Park,AbortSlew) that initiate dome movement. It also manages the polling loop and watchdog services.ConfigManager: A data-centric class that holds all configuration settings and real-time status variables for the dome. This includes the currentAzimuth,DomeState,SlewingStatus, and timeout settings likeRotationTimeout.SerialPortGuard: A helper class that ensures thread-safe, serialized access to theSerialPort. All commands to the dome controller are sent through this guard.ActionWatchdog: A crucial component for monitoring asynchronous, long-running operations like slewing. It ensures that a command either completes successfully or times out, triggering a recovery routine if necessary.- Polling Loop: A background task (
PollLoopAsync) that continuously queries the dome controller for its status, updating the state inConfigManager. This provides the feedback necessary to determine when a slew is complete.
Sources: Driver/Pulsar_DomeDriver.cs, Config/ConfigManager.cs, Helper/ActionWatchdog.cs, Helper/SerialPortGuard.cs
Component Interaction Diagram
This diagram illustrates the relationships between the main components involved in dome control.
Slewing Execution Flow
All dome movement commands (SlewToAzimuth, FindHome, Park) follow a standardized execution flow managed by the ExecuteDomeCommand method. This ensures consistent behavior, monitoring, and error handling for all rotational actions.
1. Initiating a Slew
When an ASCOM client calls SlewToAzimuth(double azimuth), the driver first validates the input. It then constructs the appropriate serial command (ABS {azimuth}) and invokes the generic ExecuteDomeCommand method to handle the rest of the process.
Sources: Driver/Pulsar_DomeDriver.cs:2030-2062
2. The ExecuteDomeCommand Process
This private method is the heart of the command execution logic. It performs the following steps:
- Sets Intent: Records the current action (e.g.,
DomeCommandIntent.SlewAzimuth) and sets aForceBusyflag to indicate movement. - Stops Polling: Temporarily pauses the background status polling loop to prevent conflicts during command transmission.
- Checks Target: Verifies if the dome is already at the desired position. If so, it exits early.
- Sends Command: Uses
SerialPortGuardto send the command to the controller and waits for an acknowledgment ("A"). - Updates State: If acknowledged, it updates the internal state (e.g., sets
DomeStateto moving). - Starts Watchdog: Initializes and starts an
ActionWatchdogwith a specific timeout and completion criteria. - Restarts Polling: Resumes the background status polling loop.
This flow is visualized in the diagram below.
3. Monitoring and Completion
Once a command is sent, the ActionWatchdog and the polling loop work together to monitor its completion.
- The
PollLoopAsynctask runs continuously, callingDomeStatus()at a fixed interval. DomeStatus()sends aVcommand to the controller.ParseDomeStatus()parses the multi-token response from the controller, updating state variables like_config.Azimuthand_config.DomeState.- The
ActionWatchdogperiodically executes acheckStatuslambda function, which inspects these updated state variables. For a slew, it checks if_config.DomeState == 0(Idle) and if the current azimuth is within the configuredAzimuthToleranceof the target. - If the condition is met, the watchdog marks the action as successful. If the timeout is reached before completion, it triggers a failure and initiates a recovery routine.
The following sequence diagram shows the complete flow for a SlewToAzimuth command.
Special Slewing Commands
Besides slewing to a specific azimuth, the driver supports homing, parking, and aborting.
| Command | ASCOM Method | Serial Command | Description |
|---|---|---|---|
| Homing | FindHome() | GO H | Commands the dome to move to its home position. The DomeState is set to 9 during this operation. |
| Parking | Park() | GO P | Commands the dome to move to its predefined park position. The DomeState is set to 1 (generic moving). |
| Abort | AbortSlew() | STOP | Immediately stops all dome and shutter movement. It cancels any active ActionWatchdog and sends the STOP command. |
Sources: Driver/Pulsar_DomeDriver.cs:2064-2092, 2094-2122, 2125-2165
State and Configuration
The behavior of the slewing system is controlled by several state variables and configuration parameters stored in ConfigManager.
Dome State (DomeState)
The DomeState property reflects the current rotational activity of the dome.
| Value | State | Description |
|---|---|---|
0 | Idle | The dome is stationary. |
1 | Slewing to target | The dome is moving to a specified azimuth or park position. |
9 | Slewing to home | The dome is moving to the home position. |
Sources: Config/ConfigManager.cs:52, Driver/Pulsar_DomeDriver.cs:927-933
Relevant Configuration
These settings, configured through the SettingsForm, directly impact slewing behavior.
| Parameter | Description | Default Value | Source File |
|---|---|---|---|
RotationTimeout | The maximum time (in ms) allowed for a rotation command (slew, home, park) to complete before the watchdog triggers a timeout. | 90000 | Config/ConfigManager.cs:208-222 |
AzimuthTolerance | The allowable error in degrees between the target and final azimuth for a slew to be considered successful. | 0 | Config/ConfigManager.cs:48 |
ParkAzimuth | The azimuth value for the park position. | 0 | Config/ConfigManager.cs:47 |
The RotationTimeout is configured in seconds in the UI and converted to milliseconds for internal use.
Sources: UI/SettingsForm.cs:100, UI/SettingsForm.Designer.cs:245-255
Status Parsing
The current azimuth and dome state are extracted from a detailed status string returned by the controller in response to the V command. The TryParseDomeTokens method is responsible for parsing this string.
// Relevant parsing logic from TryParseDomeTokens
// tokens is a string array from the controller's response
if (!double.TryParse(tokens[0], out double azimuth) || azimuth < 0 || azimuth > 360)
throw new ArgumentOutOfRangeException("Azimuth", azimuth, "Must be between 0 and 360");
if (!int.TryParse(tokens[1], out int state) || state < 0 || state > 9)
throw new ArgumentOutOfRangeException("State", state, "Must be between 0 and 9");
// ... update config ...
_config.Azimuth = azimuth;
_config.DomeState = state;
Sources: Driver/Pulsar_DomeDriver.cs:1038-1041, 1076-1078
Summary
The Slewing and Azimuth Control system in the Pulsar Dome Driver is a well-defined, stateful, and resilient mechanism. It abstracts the complexities of hardware communication and asynchronous operations behind the standard ASCOM interface. By using a generic command execution pattern combined with a dedicated watchdog and a continuous polling loop, it ensures that all dome movements are reliably initiated, monitored, and either completed successfully or handled gracefully in case of failure, providing a stable platform for automated observatory control.