_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. For an overview of the evolution of ASCOM interfaces, see Interface Revision History document (PDF, external)

Methods

async Telescope.AbortSlew()

Stops a slew in progress.

Non-blocking: Returns immediately with Slewing = True until the slew 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 telescope is parked (AtPark = True)

  • NotConnectedException – If the device is not connected

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

Note

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

  • Effective only after a call to either one of the slew methods or to MoveAxis().

  • Does nothing if no slew/motion is in progress

  • In the case of MoveAxis() or SlewToAltAzAsync(), Tracking must be returned to the state before the slew stopped. Note that equatorial slews by definition always start and finish with Tracking on.

Telescope.Action(ActionName: str, ActionParameters)

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

Invoke the specified device-specific custom action

Parameters:

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

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

Returns:

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

Return type:

string

Raises:

Important

Note

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

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

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 (enum) – The mechanical axis about which rate information is desired TelescopeAxes

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 (enum TelescopeAxes) – The axis about which this info is desired

Returns:

Whether the mount may be moved about the requested axis

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 (str) – 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 (str) – 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 (str) – 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:

enum 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 (enum) – The mechanical axis about which motion is desired, see TelescopeAxes and

  • 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

Start slewing the mount to its park position.

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

Returns:

Nothing

Raises:

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

  • ParkedException – If the mount is parked (AtPark = True)

  • NotConnectedException – If the device is not connected

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

Note

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

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

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:

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

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

Raises:

Note

Telescope.SetPark()

Set the mount’s park position to 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

  • This method should only be implemented if the properties Altitude, Azimuth, RightAscension, Declination, and Slewing can be read while the scope is slewing.

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

  • This method should only be implemented if the properties Altitude, Azimuth, RightAscension, Declination, and Slewing can be read while the scope is slewing.

  • 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

Starts the process of taking the mount out of the Parked state. Non-blocking, unless already unparked (AtPark = False), this must return with Slewing = True until the unparking process completes, at which time both Slewing and AtPark must become False.

Returns:

Nothing

Raises:

Note

  • Asynchronous (non-blocking): Use the Slewing property to monitor the operation. When the mount has successfully unparked, Slewing becomes False and AtPark becomes False. See Asynchronous Operations in ASCOM.

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

Properties

property Telescope.AlignmentMode: enum Telescope.AlignmentModes

The mechanical construction of the mount (Alt/Az, Polar, German Polar), etc. Returns a value of type AlignmentModes.

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. See Note

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 describes the mechanical construction of the mount, not the coordinate system being used operationally. Thus AlignmentMode cannot be changed or set. 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

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

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

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

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

Return the telescope’s effective aperture (meters).

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

The mount is at the home position.

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

The mount is at the park position.

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) Park() operation. Using AtPark runs the risk that the mount will pass through the park position before finally completing the parking operation. See Asynchronous Operations in ASCOM

  • True if the mount is stopped in the Park position. Can be True only following successful completion of a Park() operation.

  • 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 enabling tracking while parked must raise an exception.

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

property Telescope.Azimuth: float

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

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

The mount can find its home position.

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

The mount can be parked.

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

The mount can be pulse guided.

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

The Declination tracking rate may be offset.

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

meth:PulseGuide() can be adjusted

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

The mount’s park position can be set.

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

The mount can be force-flipped via setting SideOfPier

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

The Right Ascension tracking rate may be offset

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

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

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

The mount can synchronously slew to equatorial coordinates.

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

The mount can synchronously slew to alt/az coordinates.

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

The mount can asynchronously slew to alt/az coordinates.

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

The mount can asynchronously slew to equatorial coordinates.

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

The mount can be synchronized to equatorial coordinates.

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

The mount can be synchronized to alt/az coordinates.

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

The mount can be unparked

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:

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

The mount’s current Declination (degrees, 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. 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 UTC (SI) second. See Notes and What are RightAscensionRate and DeclinationRate and how are they used?

Raises:

Attention

DeclinationRate read must be implemented.

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

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

Note

property Telescope.DoesRefraction: boolean

(Read/Write) The mount applies atmospheric refraction to corrections

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

The current equatorial coordinate system used by the mount

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

The telescope’s focal length in meters.

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.

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:

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

Raises:

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

Attention

Must be implemented, must not throw a PropertyNotImplementedException

Note

  • This is a single “short” integer indicating the version of this specific ASCOM universal interface definition. For 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

The mount is currently executing a PulseGuide() command.

Use this property to determine when a (non-blocking) pulse guide command has completed. See Notes and Asynchronous Operations in ASCOM.

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

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

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?

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

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.

Important

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

property Telescope.SiderealTime: float

Local apparent sidereal time (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. 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

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

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

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 lengthen 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.).

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

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

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

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

Raises:

Note

property Telescope.Tracking: boolean

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

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.

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]

Return a list of supported Telescope.DriveRates values

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

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

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

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