_images/Bug72.jpg

ITelescope V4 Interface

class Telescope

Bases: ASCOM.DeviceInterface

ASCOM Standard ITelescope V4 Interface

Important

All mounts that can be slewed must implement asynchronous slewing. ASCOM COM drivers must also implement synchronous slewing for backward compatiblity. See Synchronous Slewing in the Telescope Interface. Clients must use asynchronous slewing methods if at all possible, use of synchronous slewing methods is deprecated in ITelescope V4.

Revision History

Members added, deprecated, or changed are indicated by a legend at the top of that member indicating the InterfaceVersion at which the change occurred. For this interface, only changes after InterfaceVersion = 2 (2004) are indicated. Telescope V1.x existed over 20 years ago during the period where ASCOM was experimental and subject to developmental changes.

Methods

async Telescope.AbortSlew()

Stops any motion in progress: slewing, parking, find-home, and move-axis.

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

Returns:

Nothing

Raises:

  • MethodNotImplementedException – If no actions at all are supported

  • ParkedException – If the mount is parked (ITelescopeV4 and later).

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

Note

Telescope.Action(ActionName: str, ActionParameters)

Added in version 3: To replace deprecated CommandBlind(), CommandBool(), and CommandString() with a 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.

Telescope.AxisRates(Axis: TelescopeAxes)

Determine the rates at which the telescope may be moved about the specified axis by the MoveAxis() method. See MoveAxis() and What does MoveAxis() do and how do I use it? for details.

Parameters:

Axis (TelescopeAxes) – The mechanical axis about which rate information is desired

Returns:

A list or collection of Rate objects, each of which specifies a minimum and a maximum angular rate (degrees/second) at which the given axis of the mount may be moved.

Return type:

A list or collection of Rate objects

Raises:

  • InvalidValueException – If an invalid Axis is specified.

  • 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 MethodNotImplementedException;

Note

Telescope.CanMoveAxis(Axis: TelescopeAxes)

The mount can be moved about the given mechanical axis. See MoveAxis() for details.

Parameters:

Axis (TelescopeAxes) – The axis about which this information is required

Returns:

True if the mount can move about the requested axis, else False

Return type:

boolean

Raises:

  • InvalidValueException – If an invalid Axis is specified.

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

Note

See MoveAxis() for details.

Telescope.CommandBlind(Command: str, Raw: boolean)

Deprecated since version 4: 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 (string) – The literal command string to be transmitted.

  • Raw (boolean) – 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.

Telescope.CommandBool(Command: str, Raw: boolean)

Deprecated since version 4: 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 (string) – The literal command string to be transmitted.

  • Raw (boolean) – 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.

Telescope.CommandString(Command: str, Raw: boolean)

Deprecated since version 4: 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 (string) – The literal command string to be transmitted.

  • Raw (boolean) – 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 Telescope.Connect()

Added in version 4: 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.

Telescope.DestinationSideOfPier(RightAscension: float, Declination: float)
Parameters:

  • RightAscension (float) – The destination right ascension (hours)

  • Declination (float) – The destination declination (degrees, positive North)

Returns:

The PierSide indicating the pointing state in which the mount will be if slewed to the given coordinates at this instant of time.

Return type:

PierSide

Provided so apps can manage GEM flipping during an image sequence. See SideOfPier, What is DestinationSideOfPier and why would I want to use it? and What is the meaning of “pointing state” in the docs for SideOfPier

Raises:

  • MethodNotImplementedException – If the method is not implemented

  • InvalidValueException – If an invalid RightAscension or Declination is specified

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

async Telescope.Disconnect()

Added in version 4: 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 Telescope.FindHome()

Changed in version 4: Formally defined as asynchronous

Start moving the mount to the “home” position.

Non-blocking: Returns immediately with Slewing = True if the homing operation has successfully been started, or Slewing = False which means the mount is already at its home position (and of course AtHome will already be True). See Notes, and Asynchronous Operations in ASCOM.

Returns:

Nothing

Raises:

Note

Asynchronous (non-blocking): Use the Slewing property to monitor the operation’s progress. When the mount has successfully reached its home position, Slewing becomes False and AtHome becomes True. See Asynchronous Operations in ASCOM

async Telescope.MoveAxis(Axis: TelescopeAxes, Rate: float)

Changed in version 4: Formally defined as asynchronous

Start motion of the mount about the given mechanical axis at the given non-zero angular rate or, for a zero angular rate, stop MoveAxis() movement about the axis and resume any configured tracking movement. See TelescopeAxes and What does MoveAxis() do and how do I use it?.

Non-blocking: Must return immediately with Slewing = True for Rate > 0 after successfully starting the axis rotation operation. Rate = 0 stops motion immediately.

Parameters:

  • Axis (TelescopeAxes) – The mechanical axis about which motion is desired

  • Rate (float) – The rate of rotation desired (degrees/second)

Returns:

Nothing

Raises:

Attention

A call with Rate = 0 is required to stop motion and return to the previous tracking state of that axis. See What does MoveAxis() do and how do I use it?

Note

  • Asynchronous (non-blocking): Clients must use the Slewing property to determine if the mount is moving, however you must explicitly call MoveAxis() with a zero rate to stop motion about the given axis.

  • When the motion is stopped the scope will be set to the previous TrackingRate or to no movement, depending on the previous state of the Tracking property.

  • A mount may support multiple rate ranges (via AxisRates()) on each of its multiple TelescopeAxes

  • This is a complex feature and relates to the mount’s mechanical axes. See TelescopeAxes and What does MoveAxis() do and how do I use it?.

  • The meaning of positive vs negative values as applies to rotation directions about the axes is purposely left undefined. App developers need to provide adaptation to various mount geometries and control systems and their rotation directions. See What does MoveAxis() do and how do I use it?.

Important

async Telescope.Park()

Changed in version 4: Formally defined as asynchronous

Move the telescope to its park position, stop all motion (or restrict to a small safe range), and set AtPark to True.

Non-blocking: Returns immediately with:

  • Slewing = False and AtPark = True if the the mount is already in its parked state.

  • Slewing = True and AtPark = False if the park operation has successfully started but has not yet completed.

While the park operation is underway, Slewing must return True until the driver determines that the park is complete, at which point the driver must set AtPark to True before setting Slewing to False.

See Notes, and Asynchronous Operations in ASCOM.

Returns:

Nothing

Raises:

  • MethodNotImplementedException – If the method is not implemented (and CanPark = 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 communication errors.

Note

  • When a mount supports parking, one or more Parked states may be offered by the manufacturer / driver. It is the astronomer’s responsibility to select an appropriate state for their needs by configuring the mount and driver. The Park command will deliver whatever state has been selected by the astronomer.

  • Parking should put the telescope into a state where its pointing accuracy must not be lost if it is power-cycled (without moving it).

  • It is permissible for the mount to require power cycling before being unparked (with Unpark()) and used.

  • Parking a mount that is already parked (AtPark = True) is harmless and must always be successful.

async Telescope.PulseGuide(Direction: GuideDirections, Duration: int)

Changed in version 4: Formally defined as asynchronous

Moves the mount in the specified angular direction for the specified time (ms). The directions are in the Equatorial coordinate system only, regardless of the mount’s AlignmentMode. The distance moved depends on the GuideRateDeclination and GuideRateRightAscension, as well as Duration. See What Does PulseGuide() Do? I’m Confused..

Non-blocking: See Notes, and Asynchronous Operations in ASCOM

Parameters:

  • Direction (GuideDirections) – Equatorial axis and direction of guide motion

  • Duration (int) – The duration of the guide-rate motion (milliseconds)

Raises:

Note

Telescope.SetPark()

Set the mount’s Parked state to be at its current position.

Returns:

Nothing

Raises:

  • MethodNotImplementedException – If the method is not implemented (CanPark is False)

  • InvalidOperationException – If the pulse guide cannot be effected e.g. if the mount is slewing (Slewing) is True, or is not tracking (Tracking is 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 communication errors.

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

Telescope.SlewToAltAz(Azimuth: float, Altitude: float)

Deprecated since version 4: Use SlewToAltAzAsync(). See Deprecation Notice below.

Move the mount synchronously to the given local horizontal coordinates, return only when slew is complete. See Synchronous Slewing in the Telescope Interface.

Deprecation Notice

This method is deprecated for clients as of ITelescope V4. Use SlewToAltAzAsync(). ASCOM COM mounts that can slew to local horizontal coordinates at all must implement this, however, to prevent a breaking change. ASCOM Alpaca mounts should not implement this and should return False for CanSlewAltAz, and MethodNotConnectedException if called by the client. See Synchronous Slewing in the Telescope Interface.

Parameters:

  • Azimuth (float) – Destination azimuth coordinate (degrees, North-referenced, positive East/clockwise)

  • Altitude (float) – Destination altitude coordinate (degrees, positive up).

Returns:

Nothing

Raises:

Note

  • It is impossible for the mount to be slewed to an Alt/Az coordinate if Tracking = True since the mount would instantly move away from the requested Alt/Az coordinates due to the equatorial tracking motion. Hence the requirement for raising InvalidOperationException if Tracking = True

async Telescope.SlewToAltAzAsync(Azimuth: float, Altitude: float)

Changed in version 4: If the mount can slew to local horizontal coordinates, it must implement this method.

Start a slew to the given local horizontal coordinates.

Non-blocking: Returns immediately. See Notes, and Asynchronous Operations in ASCOM

Parameters:

  • Azimuth (float) – Destination azimuth coordinate (degrees, North-referenced, positive East/clockwise)

  • Altitude (float) – Destination altitude coordinate (degrees, positive up).

Returns:

Nothing

Raises:

Note

Asynchronous (non-blocking): Use the Slewing property to monitor the operation. When the requested coordinates have been successfully* reached, Slewing becomes False. If SlewToAltAzAsync() returns with Slewing = False then the mount was already at the requested coordinates, which is also a success. See Asynchronous Operations in ASCOM.

  • It is impossible for the mount to be slewed to an Alt/Az coordinate if Tracking = True since the mount would instantly move away from the requested Alt/Az coordinates due to the equatorial tracking motion. Hence the requirement for raising InvalidOperationException if Tracking = True

Important

As of ITelescope V4 if the mount can slew to local horizontal coordinates, it must implement this method.

Telescope.SlewToCoordinates(RightAscension: float, Declination: float)

Deprecated since version 4: Use SlewToCoordinatesAsync(). See Deprecation Notice below.

Move the mount to the given equatorial coordinates per EquatorialSystem, return only when slew is complete. See Synchronous Slewing in the Telescope Interface.

Deprecation Notice

This method is deprecated for clients as of ITelescope V4. Use SlewToCoordinatesAsync(). ASCOM COM Mounts that can slew to equatorial coordinates at all must continue to implement this, however, to prevent a breaking change. ASCOM Alpaca mounts should not implement this and should return False for CanSlew, and MethodNotConnectedException if called by the client. See Synchronous Slewing in the Telescope Interface.`.

Parameters:
Returns:

Nothing

Raises:
async Telescope.SlewToCoordinatesAsync(RightAscension: float, Declination: float)

Changed in version 4: If the mount can slew to equatorial coordinates, it must implement this method.

Start a slew to the given given equatorial coordinates per EquatorialSystem.

Non-blocking: Returns immediately. See Notes, and Asynchronous Operations in ASCOM

Parameters:
Returns:

Nothing

Raises:

Note

Asynchronous (non-blocking): Use the Slewing property to monitor the operation. When the requested coordinates have been successfully* reached, Slewing becomes False. If SlewToCoordinatesAsync() returns with Slewing = False then the mount was already at the requested coordinates, which is also a success. See Asynchronous Operations in ASCOM.

Telescope.SlewToTarget()

Deprecated since version 4: Use SlewToTargetAsync(). See Deprecation Notice below.

Move the mount to the TargetRightAscension and TargetDeclination coordinates per EquatorialSystem, return only when slew is complete. See Synchronous Slewing in the Telescope Interface.

Returns:

Nothing

Deprecation Notice

This method is deprecated for clients as of ITelescope V4. Use SlewToTargetAsync(). ASCOM COM Mounts that can slew to equatorial coordinates at all must continue to implement this, however, to prevent a breaking change. ASCOM Alpaca mounts should not implement this and should return False for CanSlew, and MethodNotConnectedException if called by the client. See Synchronous Slewing in the Telescope Interface.`.

Raises:
async Telescope.SlewToTargetAsync()

Changed in version 4: If the mount can slew to equatorial coordinates, it must implement this method.

Start an asynchronous slew to the coordinates in TargetRightAscension and TargetDeclination per EquatorialSystem

Non-blocking: Returns immediately with Slewing = True if the slewing operation has successfully been started. See Notes, and Asynchronous Operations in ASCOM

Returns:

Nothing

Raises:

Note

Asynchronous (non-blocking): Use the Slewing property to monitor the operation. When the requested coordinates have been successfully* reached, Slewing becomes False. If SlewToTargetAsync() returns with Slewing = False then the mount was already at the requested coordinates, which is also a success. See Asynchronous Operations in ASCOM.

Telescope.SyncToAltAz(Azimuth: float, Altitude: float)

Match the mount’s local horizontal coordinates to the given local horizontal coordinates.

Parameters:

  • Azimuth (float) – Destination azimuth coordinate (degrees, North-referenced, positive East/clockwise)

  • Altitude (float) – Destination altitude coordinate (degrees, positive up).

Returns:

Nothing

Raises:

Note

May throw DriverException if Tracking is True.

Telescope.SyncToCoordinates(RightAscension: float, Declination: float)

Match the mount’s equatorial coordinates with the given equatorial coordinates

Parameters:
Returns:

Nothing

Raises:

Note

May throw DriverException if Tracking is False.

Telescope.SyncToTarget()

Match the mount’s equatorial coordinates with the coordinates in TargetRightAscension and TargetDeclination.

Returns:

Nothing

Raises:

Note

May throw DriverException if Tracking is False.

async Telescope.Unpark()

Changed in version 4: Formally defined as asynchronous

Takes telescope out of the Parked state. The state of Tracking after unparking is undetermined. Valid only after Park().

Non-blocking: Returns immediately with:

  • Slewing = False and AtPark = False if the the mount is already in its unparked state.

  • Slewing = True and AtPark = True if the unpark operation has successfully started but has not yet completed.

While the unpark operation is underway, Slewing must return True until the driver determines that the unpark is complete, at which point the driver must set AtPark to False before setting Slewing to False.

See Notes, and Asynchronous Operations in ASCOM.

Returns:

Nothing

Raises:

  • MethodNotImplementedException – If the method is not implemented (and CanPark = 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 communication errors.

Note

  • Unparking a mount that is not parked (AtPark = False) is harmless and must always be successful.

Properties

property Telescope.AlignmentMode: enum Telescope.AlignmentModes
Returns:

The mechanical construction of the mount and the orientation of its axes (Alt/Az, Polar, German Polar), etc.

Return type:

Telescope.AlignmentModes

Raises:

  • PropertyNotImplementedException – If the property 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.

Note

This property is read-only; it cannot be changed at run-time because it reflects the design of the mount. Regardless of their AlignmentMode all mounts may operate in equatorial (RA/Dec) and/or local horizontal (Alt/Az) coordinate systems. AlignmentMode is unrelated to the coordinate systems in use by the mount.

Note

This property describes the mechanical construction of the mount, not the coordinate system being used operationally. Thus AlignmentMode cannot be changed or set by client applications. Astronomical mounts all have the ability to to read back and slew using equatorial (RA and Dec) coordinates, and most may also read back and slew using local horizontal (Alt and Az) coordinates, independent of their mechanical construction.

The AlignmentMode does not restrict a mount’s ability to be pointed/slewed via equatorial and/or local horizontal coordinates and/or to read back RA/Dec and/or Alt/Az (e.g. a push-to Dobsonian may display both RA/Dec and Alt/Az).

property Telescope.Altitude: float
Returns:

The Altitude (degrees) above the horizon at which the mount is currently pointing (local horizontal coordinates).

Return type:

float

Raises:

  • PropertyNotImplementedException – If the property 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.

property Telescope.ApertureArea: float
Returns:

The telescope’s effective aperture area (square meters).

Return type:

float

Raises:

  • PropertyNotImplementedException – If the property 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.

Note

  • The area takes into account any obstructions; it is the actual light-gathering area.

property Telescope.ApertureDiameter: float
Returns:

The telescope’s effective aperture (meters).

Return type:

float

Raises:

  • PropertyNotImplementedException – If the property 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.

property Telescope.AtHome: boolean
Returns:

The mount is at the home position.

Return type:

boolean

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

This property must be implemented.

Note

  • Slewing is the correct property to use to determine successful completion of the (non-blocking) FindHome() operation. Using AtHome runs the risk that the mount will pass through the home position before finally completing the homing operation. See Asynchronous Operations in ASCOM

  • True if the mount is stopped in the Home position. Can be True only following a FindHome() operation.

  • AtHome must become False immediately upon any slewing operation

  • Must always be False if the mount does not support homing. Use CanFindHome to determine if the mount supports homing.

property Telescope.AtPark: boolean
Returns:

True if the telescope has been put into the parked state by the Park() method. Set False by calling the Unpark() method.

Return type:

boolean

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

This property must be implemented.

Note

  • ASCOM clients should note that Slewing is the most reliable way determine successful completion of the (non-blocking) Park() and Unpark() operations. Some drivers tie the state of AtPark to specific mount coordinates and using AtPark runs the risk that the mount will pass through and overshoot the configured Park position before returning to the expected park position. See Asynchronous Operations in ASCOM

  • Clients should be prepared for the the possibility that the mount may report AtPark as True on initial connection.

  • When parked, the mount must be stationary or restricted to a small safe range of movement. Tracking must be False.

  • You must take the mount out of park by calling Unpark().

  • Attempts to slew, move or enable tracking while parked must raise a ParkedException.

  • Must always be False if the mount does not support parking. Use CanPark to determine if the mount supports parking.

property Telescope.Azimuth: float
Returns:

The azimuth (degrees) at which the mount is currently pointing (local horizontal coordinates).

Return type:

float

Raises:

  • PropertyNotImplementedException – If the property 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.

Note

  • Azimuth is per the usual alt/az coordinate convention: degrees North-referenced, positive East/clockwise.

property Telescope.CanFindHome: boolean
Returns:

The mount can find its home position.

Return type:

boolean

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

This property must be implemented.

Note

property Telescope.CanPark: boolean
Returns:

The mount can be parked.

Return type:

boolean

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.

Note

property Telescope.CanPulseGuide: boolean
Returns:

The mount can be pulse guided.

Return type:

boolean

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.

Note

property Telescope.CanSetDeclinationRate: boolean
Returns:

The Declination tracking rate may be offset.

Return type:

boolean

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.

Note

property Telescope.CanSetGuideRates: boolean
Returns:

The mount can adjust pulse guide rates.

Return type:

boolean

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

This property must be implemented.

Note

property Telescope.CanSetPark: boolean
Returns:

The position of the mount’s Parked state can be set.

Return type:

boolean

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

This property must be implemented.

Note

property Telescope.CanSetPierSide: boolean
Returns:

The mount can be force-flipped via setting SideOfPier

Return type:

boolean

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

This property must be implemented.

Note

  • See SideOfPier.

  • This applies to both German and simple/fork mounts. See What is the meaning of “pointing state” in the docs for SideOfPier. On a fork mount, if the imaging payload cannot pass through the fork, this must return False. Circumpolar locations “under” the pole require either the fork to roll over more than 180 degrees, or the imaging payload to pass through the fork. This is the equivalent of flipping on a german equatorial mount.

property Telescope.CanSetRightAscensionRate: boolean
Returns:

The Right Ascension tracking rate may be offset.

Return type:

boolean

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

This property must be implemented.

Note

property Telescope.CanSetTracking: boolean
Returns:

The mount’s sidereal tracking may be turned on and off

Return type:

boolean

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

This property must be implemented.

Note

property Telescope.CanSlew: boolean
Returns:

The mount can synchronously slew to equatorial coordinates.

Return type:

boolean

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

This property must be implemented.

Note

See SlewToCoordinates(), SlewToCoordinatesAsync(), SlewToTarget(), and SlewToTargetAsync()

Attention

Synchronous methods are deprecated in this version (V4) of ITelescope and Clients should not use them. ASCOM COM Driver authors however must implement synchronous methods, if the mount can slew, to ensure backward compatibility. See Synchronous Slewing in the Telescope Interface.

property Telescope.CanSlewAltAz: boolean
Returns:

The mount can synchronously slew to alt/az coordinates.

Return type:

boolean

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

This property must be implemented.

Note

See SlewToAltAz() and SlewToAltAzAsync()

Attention

Synchronous methods are deprecated in this version (V4) of ITelescope and Clients should not use them. ASCOM COM Driver authors however must implement synchronous methods, if the mount can slew, to ensure backward compatibility. See Synchronous Slewing in the Telescope Interface.

property Telescope.CanSlewAltAzAsync: boolean
Returns:

The mount can asynchronously slew to alt/az coordinates.

Return type:

boolean

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

This property must be implemented.

Note

  • See SlewToAltAzAsync()

  • Clients should always use asynchronous slewing if available (CanSlewAltAzAsync = True) because synchronous mthods are deprecated in this version (V4) of ITelescope, and will not be implemented at all by Alpaca devices.

  • If the mount can slew, driver authors must implement asynchronous slewing.

property Telescope.CanSlewAsync: boolean
Returns:

The mount can asynchronously slew to equatorial coordinates.

Return type:

boolean

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

This property must be implemented.

Note

  • See SlewToCoordinatesAsync() and SlewToTargetAsync()

  • Clients should always use asynchronous slewing if available (CanSlewAltAzAsync = True) because synchronous mthods are deprecated in this version (V4) of ITelescope, and will not be implemented at all by Alpaca devices.

  • If the mount can slew, driver authors must implement asynchronous slewing.

property Telescope.CanSync: boolean
Returns:

The mount can be synchronized to equatorial coordinates.

Return type:

boolean

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

This property must be implemented.

Note

property Telescope.CanSyncAltAz: boolean
Returns:

The mount can be synchronized to alt/az coordinates.

Return type:

boolean

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

This property must be implemented.

Note

property Telescope.CanUnpark: boolean
Returns:

The mount can be unparked

Return type:

boolean

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

This property must be implemented.

Note

property Telescope.Connected: boolean

Changed in version 4: 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 Telescope V4. 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

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 Telescope.Connecting: Boolean

Added in version 4: Preferred asynchronous connection mechanic. See notes below.

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.

  • New in ITelescope V4

property Telescope.Declination: float
Returns:

The mount’s current Declination (degrees, see Notes)

Return type:

float

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

This property must be implemented.

Note

property Telescope.DeclinationRate: float

Changed in version 4: Formalized to clarify that these rates apply only when the mount is tracking at sidereal rate.

(Read/Write) Read or set a secular rate of change to the mount’s Declination in arc seconds per SI second. See Notes and What are RightAscensionRate and DeclinationRate and how are they used?

Returns:

The current declination rate offset (arc seconds per SI second).

Return type:

float

Raises:

Attention

DeclinationRate read must be implemented, write must be implemented when CanSetDeclinationRate is True.

Note

  • DeclinationRate is an offset from 0 (no change in declination), given in arc seconds per UTC (clock) second.

  • The supported range for this property is mount-specific.

  • Offset tracking is most commonly used to track a solar system object such as a minor planet or comet.

  • If offset tracking is in effect (non-zero), and a slew is initiated, the mount must continue to update the slew destination coordinates at the given offset rate.

  • Reading this property must return a value of zero if TrackingRate is not driveSidereal.

  • See What are RightAscensionRate and DeclinationRate and how are they used?

property Telescope.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 Telescope.DeviceState: List[StateValue]
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[ StateValue ]

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

Note

property Telescope.DoesRefraction: boolean

(Read/Write) The mount applies atmospheric refraction corrections

Returns:

True if the mount applies atmospheric refraction corrections internally, else False.

Return type:

boolean

Raises:

  • PropertyNotImplementedException – If this property 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

DoesRefraction read must be implemented.

Note

  • If the driver does not know whether the attached telescope does its own refraction, and if the driver does not itself calculate refraction, this property (if implemented) must raise DriverException when read.

  • If the mount indicates that it can apply refraction, yet you wish to calculate your own (more accurate) correction, try setting this to False then, if successful, supply your own refracted coordinates.

  • If you set this to True, and the mount (already) does refraction, or if you set this to False, and the mount (already) does not do refraction, no exception must be raised.

property Telescope.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 Telescope.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 Telescope.EquatorialSystem: enum Telescope.EquatorialCoordinateType
Returns:

The current equatorial coordinate system used by the mount

Return type:

EquatorialCoordinateType

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

This property must be implemented.

Note

  • See EquatorialCoordinateType

  • Most mounts use topocentric coordinates. Some high-end research mounts use J2000 coordinates.

property Telescope.FocalLength: float
Returns:

The telescope’s focal length in meters.

Return type:

float

Raises:

  • PropertyNotImplementedException – If the property 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.

property Telescope.GuideRateDeclination: float

(Read/Write) The current rate of change of Declination (deg/sec) for guiding, typically via PulseGuide. See Notes.

Returns:

The current declination guide rate (deg/sec).

Return type:

float

Raises:

  • InvalidValueException – If an invalid guide rate is set

  • PropertyNotImplementedException – If the property 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.

Note

  • This is the rate for both hardware/relay guiding and for PulseGuide

  • The mount may not support separate right ascension and declination guide rates. If so, setting either rate must set the other to the same value.

  • This value must be set to a default upon startup.

property Telescope.GuideRateRightAscension: float

(Read/Write) The current rate of change of Right Ascension (deg/sec) for guiding, typically via PulseGuide. See Notes.

Raises:

  • InvalidValueException – If an invalid guide rate is set

  • PropertyNotImplementedException – If the property 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.

Note

  • This is the rate for both hardware/relay guiding and for PulseGuide.

  • The mount may not support separate right ascension and declination guide rates. If so, setting either rate must set the other to the same value.

  • This value is in degrees per second, not in hours per second.

  • This value must be set to a default upon startup.

property Telescope.InterfaceVersion: Short
Returns:

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

Return type:

short

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 example, for ICameraV4, this must be 4. It should not to be confused with the DriverVersion property, which is the major.minor version of the driver for this device.

  • Clients can detect legacy V1 drivers by trying to read this property. If the driver raises an error, it is a V1 driver. V1 did not specify this property. A driver may also return a value of 1.In other words, a raised error or a return value of 1 indicates that the driver is a V1 driver.

property Telescope.IsPulseGuiding: boolean
Returns:

True if the mount is currently executing a PulseGuide() command.

Return type:

boolean

Raises:

  • PropertyNotImplementedException – If the property is not implemented (CanPulseGuide is 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 communication errors.

Note

property Telescope.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 Telescope.RightAscension: float
Returns:

The mount’s current right ascension (hours) in the current EquatorialSystem. See What are the equatorial coordinate reference frames?.

Return type:

float

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

This property must be implemented.

property Telescope.RightAscensionRate: float

Changed in version 4: Formalized to clarify that these rates apply only when the mount is tracking at sidereal rate.

(Read/Write) Read or set a secular rate of change to the mount’s RightAscension (seconds of RA per sidereal second). See Notes and What are RightAscensionRate and DeclinationRate and how are they used?

Returns:

The current right ascension rate offset (seconds of RA per sidereal second).

Return type:

float

Raises:

Attention

RightAscensionRate read must be implemented.

Note

  • To convert a given rate in (the more common) units of sidereal seconds per UTC (clock) second, multiply the value by 0.9972695677 (the number of UTC seconds in a sidereal second) then set the property. See What are RightAscensionRate and DeclinationRate and how are they used?

  • The supported range for this property is mount-specific.

  • Offset tracking is most commonly used to track a solar system object such as a minor planet or comet.

  • If offset tracking is in effect (non-zero), and a slew is initiated, the mount must continue to update the slew destination coordinates at the given offset rate.

  • Reading this property must return a value of zero if TrackingRate is not driveSidereal.

  • Use the Tracking property to stop and start sidereal tracking.

property Telescope.SideOfPier: enum PierSide

(Read/Write) Start a change of, or return, the mount’s pointing state. Returns a value of type:attr:Telescope.PierSide. See What is the meaning of “pointing state” in the docs for SideOfPier

Non-blocking write: Writing to change pointing state returns immediately with Slewing = True if the state change (e.g. GEM flip) operation has successfully been started. See Notes, and Asynchronous Operations in ASCOM

Returns:

The current mount pointing state.

Return type:

Telescope.PierSide

Raises:

  • PropertyNotImplementedException – If the mount does not report its pointing state, at all, or if it doesn’t support changing pointing state (e.g.force-flipping) by writing to SideOfPier (CanSetPierSide = False).

  • InvalidValueException – If an invalid Telescope.PierSide value is set

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

Note

  • Asynchronous (non-blocking) if writing SideOfPier to force a pointing state change (e.g. forced GEM flip): Use the Slewing property to monitor the operation. When the pointing state change has been successfully completed, Slewing becomes False. If writing SideOfPier returns with Slewing = False then the mount was already in the requested pointing state, which is also a success. See Asynchronous Operations in ASCOM

Note

  • Please note that “SideofPier” is a misnomer and that this method actually refers to the mount’s pointing state. For German Equatorial mounts there is a complex relationship between pointing state and the physical side of the pier on which the mount resides.

  • Example: Suppose the mount is tracking on the east side of the pier, counterweights down, observing a target on the celestial equator at hour angle +3.0.Now suppose that the observer wishes to observe a new target at hour angle -9.0. All the mount needs to do is to rotate the declination axis, through the celestial pole where the hour angle will change from +3.0 to -9.0, and keep going until it gets to the required declination at hour angle -9.0. Other than tracking, the RA axis has not moved.

    In this example the mount is still physically on the east side of the pier but the pointing state will have changed when the declination axis moved through the celestial pole.

Note

Please note that the PierSide enum is named PointingState in the ASCOM Library. See the Library Documentation

Important

Please see What is the meaning of “pointing state” in the docs for SideOfPier.

property Telescope.SiderealTime: float
Returns:

Local apparent sidereal time (hours)

Return type:

float

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

This property must be implemented

Note

  • Local Apparent Sidereal Time is the sidereal time used for pointing mounts, and thus must be calculated from the Greenwich Mean Sidereal time, longitude, nutation in longitude and True ecliptic obliquity.

  • It is required for a mount to calculate this from its source of UTCDate and SiteLongitude.

Important

See UTCDate for vital information on mount time sources and operating modes.

property Telescope.SiteElevation: float

(Read/Write) The observing site’s elevation (meters) above mean sea level. See Managing a Telescope Mount’s Knowledge of Time and Place

Returns:

The elevation of the observing site (meters)

Return type:

float

Raises:

  • PropertyNotImplementedException – If the property is not implemented at all, or if writing to the property is not implemented. See Notes.

  • InvalidValueException – If the given value is outside the range -300 through 10000 meters.

  • InvalidOperationException – When SiteElevation is read and the mount cannot provide this property itself and a value has not yet been established by writing to the property before reading it, but has not. See Notes.

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

Note

See Managing a Telescope Mount’s Knowledge of Time and Place

property Telescope.SiteLatitude: float

(Read/Write) The latitude (degrees) of the observing site. See Managing a Telescope Mount’s Knowledge of Time and Place

Returns:

The latitude of the observing site (degrees)

Return type:

float

Raises:

  • PropertyNotImplementedException – If the property is not implemented at all, or if writing to the property is not implemented. See Notes.

  • InvalidValueException – If the given value is outside the range -90 through +90 degrees latitude.

  • InvalidOperationException – When SiteLatitude is read and the mount cannot provide this property itself and a value has not yet been established by writing to the property before reading it, but has not. See Notes.

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

Note

See Managing a Telescope Mount’s Knowledge of Time and Place

property Telescope.SiteLongitude: float

(Read/Write) The longitude (degrees, positive east) of the observing site. See Managing a Telescope Mount’s Knowledge of Time and Place

Returns:

The longitude of the observing site (degrees)

Return type:

float

Raises:

  • PropertyNotImplementedException – If the property is not implemented at all, or if writing to the property is not implemented. See Notes.

  • InvalidValueException – If the given value is outside the range -90 through +90 degrees latitude.

  • InvalidOperationException – When SiteLongitude is read and the mount cannot provide this property itself and a value has not yet been established by writing to the property before reading it, but has not. See Notes.

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

Note

See Managing a Telescope Mount’s Knowledge of Time and Place

Attention

West longitude is negative.

property Telescope.SlewSettleTime: int

(Read/Write) The post-slew settling time (seconds).

Artificially lengthens all slewing operations, delaying setting Slewing to False even though the slew actually completes. Useful for mounts or buildings that require additional mechanical settling time after a slew to stabilize (pier wobble, etc.).

Returns:

The post-slew settling time (seconds)

Return type:

int

Raises:

  • PropertyNotImplementedException – If the property is not implemented

  • InvalidValueException – If the given value is negative or preposterously high (driver dependent).

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

property Telescope.Slewing: boolean
Returns:

True if the mount is in motion resulting from a slew, parking, find-home, or a move-axis. See Asynchronous Operations in ASCOM

Return type:

boolean

Raises:

  • PropertyNotImplementedException – If the property is not implemented (no slewing capabilites of the mount)

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

Note

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

Added in version 3: To replace deprecated CommandBlind, CommandBool, and CommandString with a more flexible extension mechanic. See Notes below.

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.

property Telescope.TargetDeclination: float

(Read/Write) Set or return the declination (degrees, positive North) for the target of an equatorial slew or sync operation. See Notes and What are the equatorial coordinate reference frames?.

Returns:

The target declination (degrees)

Return type:

float

Raises:

Note

property Telescope.TargetRightAscension: float

(Read/Write) Set or return the right ascension (hours, positive North) for the target of an equatorial slew or sync operation. See Notes and What are the equatorial coordinate reference frames?.

Returns:

The target right ascension (hours)

Return type:

float

Raises:

Note

property Telescope.Tracking: boolean

(Read/Write) The on/off state of the mount’s sidereal tracking drive. See Notes.

Returns:

True if tracking is enabled, else False

Return type:

boolean

Raises:

  • PropertyNotImplementedException – If writing to the property (tracking control) is not implemented (if CanSetTracking is False)

  • NotConnectedException – If the device is not connected

  • ParkedException – When Tracking is set True and the telescope is parked (AtPark is True). Introduced in ITelescopeV4

  • 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

Reading must be implemented and must not throw a PropertyNotImplementedException.

Note

property Telescope.TrackingRate: enum DriveRates

(Read/Write) The current (sidereal) tracking rate of the mount, from Telescope.DriveRates. See Notes.

Returns:

The current tracking rate

Return type:

DriveRates

Raises:

  • InvalidValueException – If the value being written is not one of the DriveRates or if the requested rate is not supported by the mount (not all are).

  • PropertyNotImplementedException – If writing to the property (changing tracking rate) is not implemented at all.

  • 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

Reading the tracking rate must be supported.

property Telescope.TrackingRates: List[DriveRates]
Returns:

A list of supported drive rates.

Return type:

List[ DriveRates ]

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.

Note

  • At a minimum, this list must contain an item for driveSidereal

property Telescope.UTCDate: datetime

(Read/Write) The UTC date/time of the mount’s time source. See Managing a Telescope Mount’s Knowledge of Time and Place

Returns:

The current UTC date/time of the mount’s time source.

Return type:

datetime

Raises:

  • InvalidValueException – If an illegal datetime value is written to the property.

  • InvalidOperationException – When UTCDate is read and the mount cannot provide this property itself and a value has not yet been established by writing to the property.

  • PropertyNotImplementedException – If writing to the property (changing the mount’s UTC date-time) 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

Reading this property must be implemented.

Note

Enumerated Constants

Telescope.AlignmentModes: Integer

The alignment mode (geometry) of the mount. See AlignmentMode.

Symbol

Val

Description

algAltAz

0

Altitude-Azimuth type mount

algPolar

1

Polar (equatorial) mount other than German equatorial

algGermanPolar

2

German equatorial type mount
Telescope.DriveRates: Integer

Well-known mount tracking rates. See TrackingRate.

Symbol

Val

Description

driveSidereal

0

Sidereal tracking rate (15.041 arcseconds per second)

driveLunar

1

Lunar tracking rate (14.685 arcseconds per second)

driveSolar

2

Solar tracking rate (15.0 arcseconds per second)

driveKing

3

King tracking rate (15.0369 arcseconds per second)
Telescope.EquatorialCoordinateType: Integer

Equatorial coordinate systems used by mounts. See What are the equatorial coordinate reference frames?

Symbol

Val

Description

equOther

0

Custom or unknown equinox and/or reference frame.

equTopocentric

1

Topocentric coordinates.

equJ2000

2

J2000 equator/equinox

equJ2050

3

J2050 equator/equinox

equB1950

4

B1950 equinox, FK4 reference frame
Telescope.GuideDirections: Integer

The direction in which a PulseGuide() guide-rate motion is to be made. These are not mechanical axes these are directions in the equatorial coordinate system. See the Note below and the What Does PulseGuide() Do? I’m Confused.

Symbol

Val

Description

guideNorth

0

North (+ declination)

guideSouth

1

South (- declination)

guideEast

2

East (+ right ascension)

guideWest

3

West (- right ascension)

Note

The North/South directions are references to equatorial coordinates and must be independent of the pointing state (flip state) of the mount. See What Does PulseGuide() Do? I’m Confused.

Telescope.PierSide: Integer

The pointing states of mounts. See What is the meaning of “pointing state” in the docs for SideOfPier

Symbol

Val

Description

pierEast

0

Normal pointing state

pierWest

1

Through the pole pointing state

pierUnknown

-1

Unknown or indeterminate

Note

Please note that the PierSide enum is named PointingState in the ASCOM Library. See the Library Documentation for further information.

Telescope.TelescopeAxes: Integer

These are the mechanical axes of the mount See MoveAxis() and What does MoveAxis() do and how do I use it?. The direction of rotation (plus or minus) is left undefined and dependent on the mount’s mechanical construction. See Notes.

Symbol

Val

Description

axisPrimary

0

Primary mechanical axis

axisSecondary

1

Secondary mechanical axis

axisTertiary

2

Tertiary mechanical axis

Note

  • The meaning of primary, secondary, and tertiary axis varies with the mount mechanical geometry. These are not equatorial coordinate axes, they are mechanical axes.

  • Typically, Primary may be the right ascension or the azimuth mechanical axis

  • Typically Secondary may be the declination or the altitude mechanical axis

  • Tertiary may refer to rotation about the optical axis or to some other axis for special geometries.

  • The meaning of positive vs negative values as applies to rotation directions about the axes is purposely left undefined. App developers need to provide adaptation to various mount geometries and control systems and their rotation directions. See What does MoveAxis() do and how do I use it?.