Dome Class

The Dome interface is designed to provide an enclosure-independent way of managing access to the sky for the telescope within. Enclosures vary widely in their design, with roll-off roofs and classic rotating domes being only two of the possibilities.

Thus, this interface focuses on providing the telescope with access to the sky at a given sky location specified by alt/az coordinates. For additional help, see The Dome Interface seems complex and confusing. Help me. For some history, see the Dome Interface Standard in the History of ASCOM and Alpaca Development (external)

Master Interfaces Reference

These green boxes in each interface member each have a link to the corresponding member definition in Master IDomeV3 Interface (external). The information in this Alpyca document is provided for your convenience. If there is any question, the info in ASCOM Master Interface Definitions (external) is the official specification.

class alpaca.dome.Dome(address: str, device_number: int, protocol: str = 'http')

Bases: Device

ASCOM Standard IDomeV2 Interface

Initialize Dome object.

Parameters:

  • address (str) – IP address and port of the device (x.x.x.x:pppp)

  • device_number (int) – The index of the device (usually 0)

  • protocol (str, optional) – Only if device needs https. Defaults to “http”.

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

AbortSlew() → None

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

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – If a communications failure occurs, or if the AbortSlew() request itself fails in some way. This exception may be encountered on any call to the device.

Note

  • When this call succeeds, Slewing will become False, and slaving will have stopped as indicate 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() will stop alt/az movement of the opening as well as stopping opening or closing.

Master Interfaces Reference

Dome.AbortSlew() (external)

Action(ActionName: str, *Parameters) → str

Invoke the specified device-specific custom action

Common to all devices

Parameters:

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

  • *Parameters – List of required parameters or [] if none are required.

Returns:

String result of the action.

Raises:

Note

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

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for Action(), find this specific device’s specification, and see Action() there.

CloseShutter() → None

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, and How can I tell if my asynchronous request failed after being started?

Raises:

Note

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.

Master Interfaces Reference

Dome.CloseShutter() (external)

CommandBlind(Command: str, Raw: bool) → None

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

Common to all devices

Parameters:

  • Command – The literal command string to be transmitted.

  • Raw – If true, command is transmitted ‘as-is’. If false, then protocol framing characters may be added prior to transmission.

Raises:

Attention

Deprecated, will most likely result in NotImplementedException

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for CommandBlind(), find this specific device’s specification, and see CommandBlind() there.

CommandBool(Command: str, Raw: bool) → bool

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

Common to all devices

Returns:

The True/False response from the command

Parameters:

  • Command – The literal command string to be transmitted.

  • Raw – If true, command is transmitted ‘as-is’. If false, then protocol framing characters may be added prior to transmission.

Raises:

Attention

Deprecated, will most likely result in NotImplementedException

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for CommandBlind(), find this specific device’s specification, and see CommandBlind() there.

CommandString(Command: str, Raw: bool) → str

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

Common to all devices

Returns:

The string response from the command

Parameters:

  • Command – The literal command string to be transmitted.

  • Raw – If true, command is transmitted ‘as-is’. If false, then protocol framing characters may be added prior to transmission.

Raises:

Attention

Deprecated, will most likely result in NotImplementedException

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for CommandString(), find this specific device’s specification, and see CommandString() there.

Connect() → None

Connect to the device asynchronously.

Common to all devices

Returns:

Nothing

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

  • Non-Blocking Use Connecting to indicate completion.

  • Natively present only in Platform 7 (2024) devices, but this library emulates Connect()/Disconnect()/Connecting mechanic for older devices.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for Connect(), find this specific device’s specification, and see Connect() there.

Disconnect() → None

Disconnect from the device asynchronously.

Common to all devices

Returns:

Nothing

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

  • Non-Blocking Use Connecting to indicate completion.

  • Natively present only in Platform 7 (2024) devices, but this library emulates Connect()/Disconnect()/Connecting mechanic for older devices.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for Disconnect(), find this specific device’s specification, and see Disconnect() there.

FindHome()

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

Non-blocking: See Notes, and How can I tell if my asynchronous request failed after being started?

Raises:

Note

Master Interfaces Reference

Dome.FindHome() (external)

OpenShutter() → None

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, and How can I tell if my asynchronous request failed after being started?

Raises:

Note

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.

Master Interfaces Reference

Dome.OpenShutter() (external)

Park() → None

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 will already be True). See Notes, and How can I tell if my asynchronous request failed after being started?

Raises:

Note

Master Interfaces Reference

Dome.Park() (external)

SetPark() → None

Set current position of dome to be the park position

Raises:

Master Interfaces Reference

Dome.SetPark() (external)

SlewToAltitude(Altitude: float) → None

Start slewing the opening to the given altitude (degrees).

Non-blocking: Returns immediately with Slewing = True if the slewing operation has successfully been started. See Notes, and How can I tell if my asynchronous request failed after being started?

Parameters:

Altitude – The requested altitude of the opening

Raises:

Note

  • Asynchronous (non-blocking): Use the Slewing property to monitor the operation. When the 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 See How can I tell if my asynchronous request failed after being started?

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

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 is used to position the opening to the sky.

Master Interfaces Reference

Dome.SlewToAltitude() (external)

SlewToAzimuth(Azimuth: float) → None

Start slewing the opening to the given azimuth (degrees).

Non-blocking: Returns immediately with Slewing = True if the slewing operation has successfully been started. See Notes, and How can I tell if my asynchronous request failed after being started?

Parameters:

Azimuth – The requested azimuth of the opening. See Notes.

Raises:

Note

  • Asynchronous (non-blocking): Use the Slewing property to monitor the operation. When the 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 See How can I tell if my asynchronous request failed after being started?

  • 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.

Attention

If the shutter is closed, this method will 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 is used to re-position the opening to the sky. This may extend the time needed to complete the OpenShutter() operation.

Master Interfaces Reference

Dome.SlewToAzimuth() (external)

SyncToAzimuth(Azimuth: float) → None

Synchronize the current azimuth of the dome (degrees) to the given azimuth.

Raises:

Master Interfaces Reference

Dome.SyncToAzimuth() (external)

property Altitude: float

Dome altitude (degrees) of the opening to the sky.

Raises:

  • NotImplementedException – If the dome does not support vertical (altitude) control / placement of its observing opening (including a roll-off roof). In this case CanSetAltitude will 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. The device did not successfully complete the request.

Note

  • The specified altitude (referenced to the dome center/equator) is of the opening to the sky through which the optics receive light.

  • It is up to the dome control and driver to determine how best to locate the dome aperture in order to expose the specified alt/az area to the sky, including positioning clamshell leaves, split shutters, etc. Your app need not know how this is happening, just that the alt/az area of the sky will be visible.

  • 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.

Attention

An ASCOM Dome device does not include transformations for mount/optics to azimuth and altitude. It is prohibited for a stand-alone Dome control device to require cross-linking to query a telescope directly. Your app will need to provide the dome-centered alt/az given the geometry of the mount and optics in use. See also the Slaved property for details on slaving (telescope motion tracking). Only an integrated mount/dome system will offer both a Telescope and a Dome interface, and be capable of slaving.

Master Interfaces Reference

Dome.Altitude (external)

property AtHome: bool

The dome is in the home position.

Note

This is normally used following a findhome() operation. The value is reset with any azimuth slew operation that moves the dome away from the home position. athome() may also become true durng 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.

Returns:

True if dome is in the home position.

Master Interfaces Reference

Dome.AtHome (external)

property AtPark: bool

The telescope has successfully reached its park position.

Raises:

Note

Set only following a park() operation and reset with any slew operation.

Returns:

True if the dome is in the programmed park position.

Master Interfaces Reference

Dome.AtPark (external)

property Azimuth: float

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:

  • NotImplementedException – If the dome does not support directional (azimuth) control / placement of its observing opening (including roll-off roof). In this case CanSetAzimuth will 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. The device did not successfully complete the request.

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.

  • You can detect a roll-off roof by CanSetAzimuth being False.

  • It is up to the dome control and driver to determine how best to locate the dome aperture in order to expose the specified alt/az area to the sky, including positioning clamshell leaves, split shutters, etc. Your app need not know how this is happening, just that the alt/az area of the sky will be visible.

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

Attention

An ASCOM Dome device does not include transformations for mount/optics to azimuth and altitude. It is prohibited for a stand-alone Dome control device to require cross-linking to query a telescope directly. Your app will need to provide the dome-centered alt/az given the geometry of the mount and optics in use. See also the Slaved property for details on slaving (telescope motion tracking). Only an integrated mount/dome system will offer both a Telescope and a Dome interface, and be capable of slaving.

Master Interfaces Reference

Dome.Azimuth (external)

property CanFindHome: bool

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. The device did not successfully complete the request.

Master Interfaces Reference

Dome.CanFindHome (external)

property CanPark: bool

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. The device did not successfully complete the request.

Master Interfaces Reference

Dome.CanPark (external)

property CanSetAltitude: bool

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. The device did not successfully complete the request.

Master Interfaces Reference

Dome.CanSetAltitude (external)

property CanSetAzimuth: bool

The opening’s azimuth can be set via SetAzimuth()

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Master Interfaces Reference

Dome.CanSetAzimuth (external)

property CanSetPark: bool

The 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. The device did not successfully complete the request.

Master Interfaces Reference

Dome.CanSetPark (external)

property CanSetShutter: bool

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. The device did not successfully complete the request.

Master Interfaces Reference

Dome.CanSetShutter (external)

property CanSlave: bool

The opening can be slaved to the telescope/optics via Slaved (see Notes)

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

  • If this is True, then the exposed Dome interface is part of an integrated mount/dome control system that offers automatic slaving.

Attention

An ASCOM Dome device does not include transformations for mount/optics to azimuth and altitude. It is prohibited for a stand-alone Dome control device to require cross-linking to query a telescope directly. Your app will need to provide the dome-centered alt/az given the geometry of the mount and optics in use. See also the Slaved property for details on slaving (telescope motion tracking).

Master Interfaces Reference

Dome.CanSlave (external)

property CanSyncAzimuth: bool

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. The device did not successfully complete the request.

Master Interfaces Reference

Dome.CanSyncAzimuth (external)

property Connected: bool

(Read/Write) Retrieve or set the connected state of the device.

Common to all devices

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.

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

  • 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.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for Connected, find this specific device’s specification, and see Connected there.

property Connecting: bool

Returns True while the device is undertaking an asynchronous Connect() or Disconnect() operation.

Common to all devices

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

  • Use this property to determine when an (async) Connect() or Disconnect() has completed, at which time it will transition from True to False.

  • Natively present only in Platform 7 (2024) devices, but this library emulates Connect()/Disconnect()/Connecting mechanic for older devices.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for Connecting, find this specific device’s specification, and see Connecting there.

property Description: str

Description of the device such as manufacturer and model number.

Common to all devices

Raises:

  • NotConnectedException – If the device status is unavailable

  • DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

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

  • The description length will 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.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for Description, find this specific device’s specification, and see Description there.

property DeviceState: List[dict]

List of key-value pairs representing the operational properties of the device

Common to all devices

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for DeviceState, find this specific device’s specification, and see DeviceState there.

property DriverInfo: List[str]

Descriptive and version information about the ASCOM driver

Common to all devices

Returns:

Python list of strings (see Notes)

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

  • This describes the driver not the device. See the Description property for information on the device itself

  • The return is a Python list of strings, the total length of which may be hundreds to thousands of characters long. It is intended to display detailed information on the ASCOM (COM or Alpaca) driver, including version and copyright data. . To get the driver version in a parse-able string, use the DriverVersion property.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for DriverInfo, find this specific device’s specification, and see DriverInfo there.

property DriverVersion: str

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

Common to all devices

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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. Note: on systems with a comma as the decimal point you may need to make accommodations to parse the value.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for DriverVersion, find this specific device’s specification, and see DriverVersion there.

property InterfaceVersion: int

ASCOM Device interface definition version that this device supports.

Common to all devices

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

Note

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

  • This value is cached internally after first retrieval since it is repeatedly used if emulating Connect/Disconnect semantics on older (pre - Platform 7) devioces.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for InterfaceVersion, find this specific device’s specification, and see InterfaceVersion there.

property Name: str

The short name of the driver, for display purposes.

Common to all devices

Raises:

DriverException – If the driver cannot successfully complete the request. This exception may be encountered on any call to the device.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for Name, find this specific device’s specification, and see Name there.

property ShutterStatus: ShutterState

Status of the dome shutter or roll-off roof.

Raises:

Note

  • This property is the correct way to monitor an in-progress shutter movement. It will be shutterOpening' immediately after returning from an :meth:`OpenShutter() call, and shutterClosing' immediately after returning from a :meth:`CloseShutter() call.

Master Interfaces Reference

Dome.ShutterStatus (external)

property Slaved: bool

(Read/Write) Indicate or set whether the dome is slaved to the telescope.

Raises:

  • NotImplementedException – If the dome controller is not par of an integrated dome/telescope control system which offers controllable dome slaving. In this case CanSlave will 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. The device did not successfully complete the request.

Attention

An ASCOM Dome device does not include transformations for mount/optics to azimuth and altitude. It is prohibited for a stand-alone Dome control device to require cross-linking to query a telescope directly. Your app will need to provide the dome-centered alt/az given the geometry of the mount and optics in use. See also the Slaved property for details on slaving (telescope motion tracking).

Master Interfaces Reference

Dome.Slaved (external)

property Slewing: bool

Any part of the dome is moving, opening, or closing. See Notes.

Raises:

  • NotConnectedException – If the device is not connected

  • DriverException – If the device cannot successfully complete a previous movement request. This exception may be encountered on any call to the device.

Note

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

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

Master Interfaces Reference

Dome.Slewing (external)

property SupportedActions: List[str]

The list of custom action names supported by this driver

Common to all devices

Returns:

Python list of strings (see Notes)

Raises:

DriverException – An error occurred that is not described by one of the more specific ASCOM exceptions. The device did not successfully complete the request.

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 Action() names exactly, without additional descriptive text. However, returned names may use any casing because the ActionName parameter of Action() is case insensitive.

Master Interfaces Reference

Alpyca uses a common Device class but this is not available in the ASCOM Master Interface Definitions (external). To see the reference info for SupportedActions, find this specific device’s specification, and see SupportedActions there.