Shutter Control
Relevant source files
The following files were used as context for generating this wiki page:
The Shutter Control system is a core feature of the Pulsar Dome Driver, providing the functionality to open and close the observatory dome's shutter. It is exposed through the standard ASCOM IDomeV2 interface. The system is designed for robustness, integrating command execution, status polling, and a watchdog mechanism to handle timeouts and errors, which is critical for unattended operation.
Operations are managed by sending commands to the controller and then monitoring the shutter's state until the action is complete. An ActionWatchdog supervises each operation, ensuring that if the shutter fails to reach its target state within a configurable timeout, a recovery process is initiated. Status updates and alerts are dispatched via MQTT and GNS for external monitoring.
Sources: Driver/Pulsar_DomeDriver.cs:1768-1855, Helper/ActionWatchdog.cs, Config/ConfigManager.cs:72-74
Core Operations
The primary shutter operations are OpenShutter() and CloseShutter(). Both methods are part of the IDomeV2 implementation and serve as the entry points for controlling the shutter.
Sources: Driver/Pulsar_DomeDriver.cs:1768-1855
Command Execution Flow
Both OpenShutter() and CloseShutter() delegate their logic to a generalized ExecuteDomeCommand method. This centralizes the process of sending a command and monitoring its completion.
The flow is as follows:
- The
DomeCommandIntentis set to eitherOpenShutterorCloseShutter. - The driver's main polling loop is temporarily stopped to prevent conflicting serial communication.
- A check is performed to see if the shutter is already in the desired state. If so, the operation is skipped.
- The corresponding command (
OPENorCLOSE) is sent to the dome controller. - The driver waits for a standard acknowledgement response (
"A") from the controller. - If acknowledged, an
ActionWatchdogis started to monitor the operation's progress. - The main polling loop is restarted.
This diagram illustrates the sequence for an OpenShutter command.
Status Monitoring
The driver continuously monitors the shutter's state through a polling mechanism. The ShutterStatus property provides the current state to the ASCOM client.
Sources: Driver/Pulsar_DomeDriver.cs:1506-1522
Shutter State
The shutter's state is represented by the ASCOM.DeviceInterface.ShutterState enum, which is derived from an internal integer status code received from the controller. The PollLoopAsync task periodically calls DomeStatus(), which sends a "V" command to the controller. The response is parsed by ParseDomeStatus(), and the _config.ShutterStatus field is updated.
The following table maps the internal integer codes to the ASCOM ShutterState.
Internal Code (_config.ShutterStatus) | ASCOM ShutterState | Description |
|---|---|---|
0 | shutterOpen | The shutter is fully open. |
1 | shutterClosed | The shutter is fully closed. |
2 | shutterOpening | The shutter is in the process of opening. |
3 | shutterClosing | The shutter is in the process of closing. |
4 | shutterError | An error occurred (e.g., both limit switches active). |
5 | shutterError | Unknown state (neither open nor closed). |
6 | shutterError | Not fitted or rebooting. |
Sources: Driver/Pulsar_DomeDriver.cs:1510-1521, Config/ConfigManager.cs:72-74, Driver/Pulsar_DomeDriver.cs:910-928
This state diagram shows the possible transitions for the shutter.
Action Watchdog and Error Handling
The ActionWatchdog class is a critical component for ensuring the reliability of shutter operations. An instance of this class is created for every OpenShutter and CloseShutter command to monitor its execution.
The watchdog is configured with:
- A timeout (
_config.ShutterTimeout). - A status check function (
checkStatus) that evaluates the current_config.ShutterStatus. - A reset routine (
ResetRoutineAsync) to be called on failure. - MQTT topics for reporting success or failure.
If the checkStatus function does not return Success within the specified timeout, the watchdog triggers the _resetRoutine, which attempts to recover the controller.
The checkStatus function for shutter operations is defined as a lambda expression within the OpenShutter and CloseShutter methods. For example, when opening, success is ShutterStatus == 0, while 4 or 5 indicate an error or failure.
// Example checkStatus lambda for OpenShutter
checkStatus: () => _config.ShutterStatus switch
{
0 => ActionWatchdog.WatchdogResult.Success,
4 => ActionWatchdog.WatchdogResult.Error,
5 => ActionWatchdog.WatchdogResult.Failure,
_ => ActionWatchdog.WatchdogResult.InProgress
},
Sources: Driver/Pulsar_DomeDriver.cs:1786-1793, Helper/ActionWatchdog.cs:33-62
The following flowchart illustrates the logic within the ActionWatchdog.
Sources: Helper/ActionWatchdog.cs:64-123
Configuration
Shutter control behavior can be modified through settings configured in the SettingsForm.
| Setting | Description | UI Control | ConfigManager Property | Default Value |
|---|---|---|---|---|
| Shutter Timeout | The maximum time in seconds allowed for a shutter open or close operation before a timeout is triggered. | txtBoxShutterTimeout | ShutterTimeout | 90000 ms |
The timeout value is entered in seconds in the UI but is converted to milliseconds for internal use within the driver.
Sources: Config/ConfigManager.cs:192-209, UI/SettingsForm.cs:107, UI/SettingsForm.cs:127-131, UI/SettingsForm.Designer.cs:175-182
Summary
The shutter control system in the Pulsar Dome Driver is a resilient mechanism designed for automated environments. It pairs direct hardware commands with a robust ActionWatchdog that monitors for successful completion. By using configurable timeouts and an automated reset routine, it can detect and attempt to recover from failures without user intervention. Integration with MQTT and GNS ensures that external systems are kept informed of the shutter's status, making it a reliable component for robotic observatories.
Sources: Driver/Pulsar_DomeDriver.cs, Helper/ActionWatchdog.cs, GNS/GNS.cs