_images/Bug72.jpg

IDomeV3 Interface

class Dome

Interface: ASCOM.DeviceInterface.IDomeV3

ASCOM Standard IDomeV3 Interface

Important

This interface has some subtleties. Please see The Dome Interface seems complex and confusing. Help me.

Methods

async Dome.AbortSlew()

Immediately stops any part of the dome from moving, opening, or closing. See Notes.

Non-blocking: Returns immediately with Slewing = True until the dome movement has been stopped, at which time Slewing becomes = False. See Notes, and Asynchronous Operations in ASCOM.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Attention

Must be implemented, must not throw a MethodNotImplementedException.

Note

  • Asynchronous (non-blocking): Use the Slewing property to monitor stopping of the movement. When the dome has successfully stopped the movement, Slewing becomes False. See Asynchronous Operations in ASCOM

  • When motion stops, Slewing must become False, and slaving must have stopped as indicated by Slaved becoming False.

  • By “any part of the dome” is meant the dome itself, the roof, a shutter, clamshell leaves, a port, etc. Calling AbortSlew() must initiate stoppage of alt/az movement of the opening as well as stoppage of opening or closing.

Dome.Action(ActionName: str, ActionParameters)

Added in version 2: To replace deprecated CommandBlind(), CommandBool(), and CommandString() with more flexible extension mechanic.

Invoke the specified device-specific custom action

Parameters:

  • ActionName (str) – A name from SupportedActions that represents the action to be carried out.

  • ActionParameters (str) – List of required arguments or empty string if none are required.

Returns:

Action response. The meaning of returned strings is set by the driver author. See notes below.

Return type:

string

Raises:

Important

Note

  • Action names must be case insensitive, so for example SelectWheel, selectwheel and SELECTWHEEL all refer to the same action.

  • An example of a string response: Suppose filter wheels start to appear with automatic wheel changers; new actions could be QueryWheels and SelectWheel. The former returning a formatted list of wheel names and the second taking a wheel name and making the change, returning appropriate values to indicate success or failure.

async Dome.CloseShutter()

Start to close the shutter or otherwise shield the telescope from the sky

Non-blocking: Returns immediately with ShutterStatus = shutterClosing after successfully starting the operation. See Notes.

Raises:

  • MethodNotImplementedException – If the dome does not have a controllable shutter/roof. In this case CanSetShutter must be False.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Note

  • Asynchronous (non-blocking): ShutterStatus is the correct property to use for monitoring an in-progress shutter movement. A transition to shutterClosed indicates a successfully completed closure. If it returns with ShutterStatus = True, it means the shutter was already closed, another success.

  • If another app calls CloseShutter() while the shutter is already closing, the request must be accepted without error.

Attention

This operation is not cross-coupled in any way with the currently requested Azimuth and Altitude. Opening and closing are used to shield and expose the opening to the sky, wherever it is specified to be.

Dome.CommandBlind(Command: str, Raw: bool)

Deprecated since version 3: Use the more flexible Action() and SupportedActions mechanic. See Notes below.

Transmit an arbitrary string to the device and does not wait for a response.

Parameters:

  • Command (str) – The literal command string to be transmitted.

  • Raw (bool) – If True, command is transmitted ‘as-is’. If False, then protocol framing characters may be added prior to transmission.

Returns:

Nothing

Raises:

  • MethodNotImplementedException – If the method is not implemented

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Deprecated, may result in MethodNotImplementedException

Note

The CommandXXX methods are a historic mechanic that provides clients with direct and unimpeded access to change device hardware configuration. While highly enabling for clients, this mechanic is inherently risky because clients can fundamentally change hardware operation without the driver being aware that a change is taking / has taken place.

The newer Action and SupportedActions mechanic provides discrete, named, functions that can deliver any functionality required.They do need driver authors to make provision for them within the driver, but this approach is much lower risk than using the CommandXXX methods because it enables the driver to resolve conflicts between standard device interface commands and extended commandsprovided as Actions.The driver is always aware of what is happening and can adapt more effectively to client needs.

Dome.CommandBool(Command: str, Raw: bool)

Deprecated since version 3: Use the more flexible Action() and SupportedActions mechanic. See Notes below.

Transmit an arbitrary string to the device and wait for a boolean response.

Parameters:

  • Command (str) – The literal command string to be transmitted.

  • Raw (bool) – If True, command is transmitted ‘as-is’. If False, then protocol framing characters may be added prior to transmission.

Returns:

True/False response from the command

Return type:

boolean

Raises:

  • MethodNotImplementedException – If the method is not implemented

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Deprecated, may result in MethodNotImplementedException

Note

The CommandXXX methods are a historic mechanic that provides clients with direct and unimpeded access to change device hardware configuration. While highly enabling for clients, this mechanic is inherently risky because clients can fundamentally change hardware operation without the driver being aware that a change is taking / has taken place.

The newer Action and SupportedActions mechanic provides discrete, named, functions that can deliver any functionality required.They do need driver authors to make provision for them within the driver, but this approach is much lower risk than using the CommandXXX methods because it enables the driver to resolve conflicts between standard device interface commands and extended commandsprovided as Actions.The driver is always aware of what is happening and can adapt more effectively to client needs.

Dome.CommandString(Command: str, Raw: bool)

Deprecated since version 3: Use the more flexible Action() and SupportedActions mechanic. See Notes below.

Transmit an arbitrary string to the device and wait for a string response.

Parameters:

  • Command (str) – The literal command string to be transmitted.

  • Raw (bool) – If True, command is transmitted ‘as-is’. If False, then protocol framing characters may be added prior to transmission.

Returns:

String response from the command

Return type:

string

Raises:

  • MethodNotImplementedException – If the method is not implemented

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Deprecated, may result in MethodNotImplementedException

Note

The CommandXXX methods are a historic mechanic that provides clients with direct and unimpeded access to change device hardware configuration. While highly enabling for clients, this mechanic is inherently risky because clients can fundamentally change hardware operation without the driver being aware that a change is taking / has taken place.

The newer Action and SupportedActions mechanic provides discrete, named, functions that can deliver any functionality required.They do need driver authors to make provision for them within the driver, but this approach is much lower risk than using the CommandXXX methods because it enables the driver to resolve conflicts between standard device interface commands and extended commandsprovided as Actions.The driver is always aware of what is happening and can adapt more effectively to client needs.

async Dome.Connect()

Added in version 3: Preferred asynchronous connection mechanic. See Important section below.

Connect to the device asynchronously. Use this to connect to a device rather than setting Connected to True.

Returns:

Nothing

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Important

  • Non-Blocking. On return, Connecting must be True unless already connected. Connection has successfully completed when Connecting becomes (or is) False.

  • This is a mandatory method and must not throw a MethodNotConnectedException.

  • Use this to connect to a device rather than setting Connected to True.

async Dome.Disconnect()

Added in version 3: Preferred asynchronous connection mechanic. See Important section below.

Disconnect from the device asynchronously. Use this to disconnect from a device rather than setting Connected to False.

Returns:

Nothing

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Important

  • Non-Blocking. On return, Connecting must be True unless already disconnected. Disconnect has successfully completed when Connecting becomes (or is) False.

  • This is a mandatory method and must not throw a MethodNotImplementedException.

  • Use this to disconnect from a device rather than setting Connected to False.

async Dome.FindHome()

Start a search for the dome’s home position and synchronize Azimuth.

Non-blocking: Returns immediately with Slewing = True if the homing operation has successfully been started, or Slewing = False which means the home position has already been found (and of course AtHome must already be True). See Notes.

Raises:

  • MethodNotImplementedException – If the dome does not support homing.

  • SlavedException – If Slaved is True

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Note

  • Asynchronous (non-blocking): Use the Slewing property to monitor the operation. When the home position has been successfully reached, Azimuth is synchronized to the apppropriate value, Slewing becomes False and AtHome becomes True.

  • Do not use AtHome to indicate completion, as it may become True during homing operations even if homing has not completed.

  • Calling FindHome if the Dome it at home must be harmless.

async Dome.OpenShutter()

Start to open shutter or otherwise expose telescope to the sky.

Non-blocking: Returns immediately with ShutterStatus = ShutterOpening if the opening has successfully been started. See Notes.

Raises:

  • MethodNotImplementedException – If the dome does not have a controllable shutter/roof. In this case CanSetShutter must be False.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Note

  • Asynchronous (non-blocking): ShutterStatus is the correct property to use for monitoring an in-progress shutter movement. A transition to shutterOpen indicates a successfully completed opening. If OpenShutter() returns with ShutterStatus = shutterOpen then the shutter was already open, which is also a success.

  • If another app calls OpenShutter() while the shutter is already opening, the request must be accepted without error.

Attention

This operation is not cross-coupled in any way with the currently requested Azimuth and Altitude. Opening and closing are used to shield and expose the opening to the sky, wherever it is specified to be.

Dome.Park()

Start slewing the dome to its park position.

Non-blocking: Returns immediately with Slewing = True if the park operation has successfully been started, or Slewing = False which means the dome is already parked (and of course AtPark must already be True). See Notes.

Raises:

  • MethodNotImplementedException – If the dome does not support parking. In this case CanPark must be False.

  • ParkedException` – If AtPark is True

  • SlavedException – If Slaved is True

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Note

  • Asynchronous (non-blocking): Use the Slewing property to monitor the operation. When the park position has been successfully reached, Slewing becomes False and AtPark becomes True.

  • Do not use AtPark to indicate completion, as it may become True during parking operations even if parking has not completed.

  • An app should check AtPark before calling Park().

Dome.SetPark()

Set current azimuth posaition of dome to be the park position

Raises:

  • MethodNotImplementedException – If the dome does not support the setting of the park position. In this case CanSetPark must be False.

  • SlavedException – If Slaved is True

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Dome.SetupDialog()

Launches a configuration dialogue box for the driver. The call will not return until the user clicks OK or cancels manually.

Please note that this method is only valid for COM drivers. Alpaca devices should provide configuration through the Alpaca HTML endpoints and should not implement a SetupDialog endpoint.

Returns:

Nothing

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a MethodNotImplementedException

Note

  • Blocking It is permissible that the configuration dialog is modal, and for the driver not to respond to other calls while this dialog is open.

Dome.SlewToAltitude(Altitude: float)

Start slewing so that requested viewing altitude (degrees) is available for observing. See The Dome Interface seems complex and confusing. Help me..

Non-blocking: Returns immediately with Slewing = True if the slewing operation has successfully been started. See Notes.

Parameters:

Altitude (float) – The desired viewing altitude (degrees, horizon zero and increasing positive to 90 degrees at the zenith)

Raises:

Note

  • Asynchronous (non-blocking): Use the Slewing property to monitor the operation. When the requested Altitude has been successfully reached, Slewing becomes False. If SlewToAltitude() returns with Slewing = False then the opening was already at the requested altitude, which is also a success

  • The specified altitude (referenced to the dome center/equator) is of the position of the opening.

  • The specified altitude should be interpreted by the device as the position on the sky that the observer wishes to observe. The device has detailed knowledge of the physical structure and must coordinate shutters, roofs or clamshell segments to open an aperture on the sky that satisfies the observer’s request.

Attention

If the opening is closed, this method must still complete, with the dome controller accepting the requested position as its Altitude property. Later, when opening, via OpenShutter(), the last received/current Altitude must be used to position the opening to the sky.

Changes

  • The Attention block above

  • Added SlavedException

Dome.SlewToAzimuth(Azimuth: float)

Start slewing so that requested viewing azimuth (degrees) is available for observing. See The Dome Interface seems complex and confusing. Help me..

Non-blocking: Returns immediately with Slewing = True if the slewing operation has successfully been started. See Notes.

Parameters:

Azimuth (float) – Desired viewing azimuth (degrees, North zero and increasing clockwise. i.e., 90 East,180 South, 270 West)

Raises:

Note

  • Asynchronous (non-blocking): Use the Slewing property to monitor the operation. When the requested Azimuth has been successfully reached, Slewing becomes False. If SlewToAzimuth() returns with Slewing = False then the opening was already at the requested azimuth, which is also a success

  • Azimuth has the usual sense of True North zero and increasing clockwise i.e. 90 East, 180 South, 270 West.

  • The specified azimuth (referenced to the dome center/equator) is of the position of the opening.

  • The specified azimuth should be interpreted by the device as the position on the sky that the observer wishes to observe. The device has detailed knowledge of the physical structure and must coordinate shutters, roofs or clamshell segments to open an aperture on the sky that satisfies the observer’s request.

Attention

If the shutter is closed, this method must still complete, with the dome controller accepting the requested position as its Azimuth property. Later, when the shutter is opened via OpenShutter(), the last received/current Azimuth must be used to re-position the opening to the sky. This may extend the time needed to complete the OpenShutter() operation.

Changes

  • The Attention block above

  • Added SlavedException

Dome.SyncToAzimuth(Azimuth: float)

Synchronize the current azimuth of the dome (degrees) to the given azimuth. See The Dome Interface seems complex and confusing. Help me.

Parameters:

Azimuth (float) – Target azimuth (degrees, North zero and increasing clockwise. i.e., 90 East,180 South, 270 West)

Raises:

Changes

  • Added SlavedException

Properties

property Dome.Altitude: float

The altitude (degrees, horizon zero and increasing positive to 90 zenith) of the part of the sky that the observer wishes to observe. See The Dome Interface seems complex and confusing. Help me.

Raises:

  • PropertyNotImplementedException – If the dome does not support vertical (altitude) control / placement of its observing opening (such Asynchronous a roll-off roof). In this case CanSetAltitude must be False.

  • NotConnectedException – If the device is not connected.

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Note

  • The specified altitude (referenced to the dome center/equator) is of the opening to the sky through which the optics receive light. see The Dome Interface seems complex and confusing. Help me.

  • See ~Dome.SlewToAltitude for operational details.

  • Do not use Altitude as a way to determine if a (non-blocking) SlewToAltitude() has completed. The Altitude may transit through the requested position before finally settling, and may be slightly off when it stops. Use the Slewing property.

property Dome.AtHome: bool

The dome is in its home position. See FindHome() and The Dome Interface seems complex and confusing. Help me.

Raises:

  • PropertyNotImplementedException – If the dome does not support finding home. In this case CanFindHome must be False.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Note

  • This should not be used to determine completion of an (async) FindHome() operation. Use Slewing() for this. The AtHome value is reset with any azimuth slew operation that moves the dome away from the home position. AtHome may also become True during normal slew operations, if the dome passes through the home position and the dome controller hardware is capable of detecting that; or at the end of a slew operation if the dome comes to rest at the home position.

  • The home position is normally defined by a hardware sensor positioned around the dome circumference and represents a fixed, known azimuth reference.

  • Applications should not rely on the reported azimuth position being identical each time AtHome becomes True. For some devices, the home position may encompass a small range of azimuth values, rather than a discrete value, since dome inertia, the resolution of the home position sensor and/or the azimuth encoder may be insufficient to return the exact same azimuth value on each occasion. On the other hand some dome controllers always force the azimuth reading to a fixed value whenever the home position sensor is active.

property Dome.AtPark: bool
Returns:

True if the dome is in the programmed park position. See The Dome Interface seems complex and confusing. Help me.

Raises:

  • PropertyNotImplementedException – If the dome does not support parking. In this case:attr:~Dome.CanPark must be False.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Note

  • This should not be used to determine completion of an (async) Park() operation. Use Slewing() for this. The AtPark value is reset with any azimuth slew operation that moves the dome away from the park position. AtPark may also become True during normal slew operations, if the dome passes through the park position and the dome controller hardware is capable of detecting that; or at the end of a slew operation if the dome comes to rest at the park position.

  • Set following a Park() operation and reset with any slew operation.

  • Applications should not rely on the reported azimuth position being identical each time AtPark becomes true. For some devices, the park position may encompass a small range of azimuth values, rather than a discrete value, since dome inertia, the resolution of the park position sensor and/or the azimuth encoder may be insufficient to return the exact same azimuth value on each occasion. On the other hand some dome controllers always force the azimuth reading to a fixed value whenever the park position sensor is active.

property Dome.Azimuth: float
Retuns:

Dome azimuth (degrees) of the opening to the sky

This this does not include the geometric transformations needed for mount and optics configurations. See The Dome Interface seems complex and confusing. Help me.

Raises:

  • PropertyNotImplementedException – If the dome does not support directional (azimuth) control / placement of its observing opening (such as a roll-off roof). In this case CanSetAzimuth must be False.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Note

  • Azimuth has the usual sense of True North zero and increasing clockwise i.e. 90 East, 180 South, 270 West.

  • The specified azimuth (referenced to the dome center/equator) is of the opening to the sky through which the optics receive light. See The Dome Interface seems complex and confusing. Help me..

  • You can detect a roll-off roof by seeing that CanSetAzimuth is False.

  • See ~Dome.SlewToAzimuth for operational details.

  • Do not use Azimuth as a way to determine if a (non-blocking) SlewToAzimuth() has complete. The Azimuth may transit through the requested position before finally settling, and may be slightly off when it stops. Use the Slewing property.

property Dome.CanFindHome: bool
Returns:

True if the dome can find its home position via FindHome()

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

property Dome.CanPark: bool
Returns:

True if the dome can be programmatically parked via Park()

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

property Dome.CanSetAltitude: bool
Returns:

True if the opening’s altitude can be set via SetAltitude().

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

property Dome.CanSetAzimuth: bool
Returns:

True opening’s azimuth can be set via SlewToAzimuth().

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

property Dome.CanSetPark: bool
Returns:

True if dome park position can be set via SetPark().

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

property Dome.CanSetShutter: bool
Returns:

The shutter can be opened and closed via OpenShutter() and CloseShutter().

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

property Dome.CanSlave: bool
Returns:

The opening can be slaved to the telescope/optics via Slaved. Only for integrated control systems, see The Dome Interface seems complex and confusing. Help me.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

property Dome.CanSyncAzimuth: bool
Returns:

True if the opening’s azimuth position can be synched via SyncToAzimuth().

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

property Dome.Connected: boolean

Changed in version 3: Writing to change connection state superseded by asynchronous Connect(), Disconnect(), and Connecting.

(Read/Write) Retrieve or set the connected state of the device. Writing is deprecated, use the newer Connect() and Disconnect() methods, and the newer Connecting property. See remarks below.

Set True to connect to the device hardware. Set False to disconnect from the device hardware. You can also read the property to check whether it is connected. This reports the current hardware state. See Notes below.

Returns:

True if connected to the hardware, else false.

Return type:

boolean

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Deprecation Notice

Property-write is deprecated as of Dome V3. Starting with Platform 7 and the interface revisions contained therein, writing to Connected is discouraged. To connect and disconnect, use the newer non-blocking Connect() and Disconnect() methods, with the new Connecting property serving as the completion property.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • Do not use a NotConnectedException here, that exception is for use in other methods that require a connection in order to succeed.

  • The Connected property sets and reports the state of connection to the device hardware. For a hub this means that Connected will be True when the first driver connects and will only be set to False when all drivers have disconnected. A second driver may find that Connected is already True and setting Connected to False does not report Connected as False. This is not an error because the physical state is that the hardware connection is still True.

  • Multiple calls setting Connected to True or False will not cause an error.

property Dome.Connecting: Boolean

Added in version 3: Preferred asynchronous connection mechanic. See Important section below.

Returns:

Returns True while the device is undertaking an asynchronous connect or disconnect operation.

Return type:

boolean

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • This is the correct property for determing when the non-blocking methods Connect() or Disconnect() have completed. Completion is when Connecting becomes False after calling either of these methods.

property Dome.Description: String
Returns:

Description of the device such as manufacturer and model number. Any ASCII characters may be used.

Return type:

string

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • This describes the device, not the driver. See the DriverInfo property for information on the ASCOM driver.

  • The description length must be a maximum of 64 characters so that it can be used in FITS image headers, which are limited to 80 characters including the header name.

property Dome.DeviceState: List[StateValue]

Added in version 3: To allow reduction of status polling

Returns:

List of StateValue objects representing the operational properties of this device. See What is the “read all” feature and what are its rules?.

Return type:

List

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

This device must return the following operational properties if they are known:

Note

Attention

Must be implemented, must not throw a PropertyNotImplementedException

property Dome.DriverInfo: String
Returns:

Descriptive and version information about the ASCOM driver

Return type:

string

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

This string may contain line endings and may be hundreds to thousands of characters long.It is intended to display detailed information on the ASCOM driver, including version and copyright data. See the Description property for information on the device itself.To get the driver version in a parse-able string, use the DriverVersion property.

property Dome.DriverVersion: String
Returns:

String containing only the major and minor version of the driver.

Return type:

string

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • This must be in the form “n.n”. It should not to be confused with the InterfaceVersion property, which is the version of this specification supported by the driver.

  • On systems with a comma as the decimal point you may need to make accommodations to parse the value.

property Dome.InterfaceVersion: Short
Returns:

ASCOM Device interface definition version that this device supports. Should return 3 for this interface version.

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • This is a single “short” integer indicating the version of this specific ASCOM universal interface definition. For IDomeV3, this must be 3. It should not to be confused with the DriverVersion property, which is the major.minor version of the driver for this device.

property Dome.Name: String
Returns:

The short name of the driver, for display purposes.

Return type:

string

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

The Description property is used to return info about the device rather than the driver.

property Dome.ShutterStatus: enum ShutterState
Returns:

Status of the dome shutter or roll-off roof: ShutterState. See The Dome Interface seems complex and confusing. Help me.

Raises:

  • PropertyNotImplementedException – If the dome does not have a controllable shutter/roof. In this case CanSetShutter must be False.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Note

This property is the correct way to monitor an in-progress shutter movement. It must be ShutterOpening immediately after returning from an OpenShutter() call, and shutterClosing immediately after returning from a CloseShutter() call.

property Dome.Slaved: bool

(Read/Write) Indicate or set whether the dome is slaved to the telescope. Only for integrated telescope/dome systems. See The Dome Interface seems complex and confusing. Help me.

Raises:

  • PropertyNotImplementedException – If the dome controller is not part of an integrated dome/telescope control system which offers controllable dome slaving. In this case CanSlave must be False.

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

property Dome.Slewing: bool
Returns:

True if Any part of the dome is moving, opening, or closing. See Notes and The Dome Interface seems complex and confusing. Help me.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes hardware or communication errors.

Note

  • This is the correct property to use to determine successful completion of a (non-blocking) SlewToAzimuth() and/or SlewToAltitude() request. Slewing must be True immediately upon returning from either of these calls, and must remain True until successful completion, at which time Slewing must become False.

  • By “any part of the dome” is meant the roof, a shutter, clamshell leaves, a port, etc. This must be True during alt/az movement of the opening as well as opening or closing.

property Dome.SupportedActions: COM: ArrayList of String elements, Alpaca: Array of String

Returns the list of custom action names supported by this driver, to be used with Action(),

Returns:

The list of custom action names supported by this driver

Return type:

COM: ArrayList of String elements, Alpaca: Array of String

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. Include sufficient detail in the message text to enable the issue to be accurately diagnosed by someone other than yourself. Includes communication errors.

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • This method, combined with Action(), is the supported mechanic for adding non-standard functionality.

  • SupportedActions is a “discovery” mechanism that enables clients to know which Actions a device supports without having to exercise the Actions themselves. This mechanism is necessary because there could be people / equipment safety issues if actions are called unexpectedly or out of a defined process sequence. It follows from this that SupportedActions must return names that match the spelling of custom action names exactly, without additional descriptive text. However, returned names may use any casing because the ActionName parameter of Action() is case insensitive.

Enumerated Constants

ShutterState: integer

Indicates the current state of the shutter or roof. Valid values are as follows:

Symbol

Val

Description

shutterOpen

0

The shutter or roof is open

shutterClosed

1

The shutter or roof is closed

shutterOpening

2

The shutter or roof is opening

shutterClosing

3

The shutter or roof is closing

shutterError

4

The shutter or roof has encountered a problem