_images/Bug72.jpg

IRotatorV4 Class

class Rotator

Bases: ASCOM.DeviceInterface

ASCOM Standard IRotator V4 Interface

The Rotator V4 interface provides for a common offset between its mechanical angle, plus the angle at which an attached imager may be mounted, and the equatorial position angle (PA) on the sky. By calling Sync() with a known current PA (from plate solving etc.), you can cause the rotator (and imager) to work directly in PA for you as well as other apps that might be using the rotator. See What are the Angles that Rotator uses, and How Do They Relate?.

Important

It is vital that an instrument rotator prevent wrapping of cables going to the imager. This must be transparent to the rotation commands coming from the application, allowing the application to freely move the rotator between any two angles without limits or “dead zones”.

Methods

Rotator.Action(ActionName: str, ActionParameters)

Added in version 2: Recommended over (now) deprecated CommandBlind(), CommandBool(), and CommandString() as 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.

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

Added in version 2: Member added as part of common interface elements.

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 (bool) – If True, command is transmitted ‘as-is’. If False, then protocol framing characters may be added prior to transmission.

Returns:

Nothing

Raises:

  • MethodNotImplementedException – If the method is not implemented

  • NotConnectedException – If the device is not connected

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

Attention

Deprecated, may result in MethodNotImplementedException

Note

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

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

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

Added in version 2: Member added as part of common interface elements.

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 (bool) – If True, command is transmitted ‘as-is’. If False, then protocol framing characters may be added prior to transmission.

Returns:

True/False response from the command

Return type:

boolean

Raises:

  • MethodNotImplementedException – If the method is not implemented

  • NotConnectedException – If the device is not connected

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

Attention

Deprecated, may result in MethodNotImplementedException

Note

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

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

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

Added in version 2: Member added as part of common interface elements.

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 (bool) – If True, command is transmitted ‘as-is’. If False, then protocol framing characters may be added prior to transmission.

Returns:

String response from the command

Return type:

string

Raises:

  • MethodNotImplementedException – If the method is not implemented

  • NotConnectedException – If the device is not connected

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

Attention

Deprecated, may result in MethodNotImplementedException

Note

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

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

async Rotator.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.

Note

New in Rotator V4

async Rotator.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.

Note

New in Rotator V4

Rotator.Halt()

Immediately stop any rotator motion due to a previous Move() or MoveAbsolute() call.

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

Must be short-lived synchronous. The client may still check IsMoving to see when it actually stops if this takes some time.

Note

  • Some Rotators may not support this function, in which case MethodNotImplemented exception must be raised.

  • Recommendation: Host software should call this method upon initialization and,if it fails, disable the Halt button in the user interface.

Rotator.Move(Position: float)

Changed in version 3: Clarified that this method must be implemented

Starts rotation relative to the current position (degrees). See What are the Angles that Rotator uses, and How Do They Relate?.

Non-blocking: Must return immediately with IsMoving = True if the operation has successfully been started (unless it is already at the requested position). After the requested angle is successfully reached and motion stops, the IsMoving property must become False.

Important

It is vital that an instrument rotator prevent wrapping of cables going to the imager. This must be transparent to the rotation commands coming from the application, allowing the application to freely move the rotator between any two angles without limits or “dead zones”.

Parameters:

Position (float) – Relative position to move in degrees from current Position. See What are the Angles that Rotator uses, and How Do They Relate?.

Raises:

  • InvalidValueException – If Position is invalid.

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

Note

  • Asynchronous: The method returns as soon as the rotation operation has been successfully started, with the IsMoving property True (unless already at the requested position). After the requested angle is successfully reached and motion stops, the IsMoving property must become False.

  • Calling Move() must cause the TargetPosition property to change to the sum of the current angular position and the value of the Position parameter (modulo 360 degrees), then starts rotation to TargetPosition. Position includes the effect of any previous Sync() operation.

  • See What are the Angles that Rotator uses, and How Do They Relate?.

Rotator.MoveAbsolute(Position: float)

Changed in version 3: Clarified that this method must be implemented

Starts rotation to the given Position (degrees). See What are the Angles that Rotator uses, and How Do They Relate?.

Non-blocking: Must return immediately with IsMoving = True if the operation has successfully been started (unless it is already at the requested position). After the requested angle is successfully reached and motion stops, the IsMoving property must become False.

Important

It is vital that an instrument rotator prevent wrapping of cables going to the imager. This must be transparent to the rotation commands coming from the application, allowing the application to freely move the rotator between any two angles without limits or “dead zones”.

Parameters:

Position (float) – New position in degrees. See What are the Angles that Rotator uses, and How Do They Relate?.

Raises:

  • InvalidValueException – If Position is invalid.

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

Note

Rotator.MoveMechanical(Position: float)

Added in version 3: Member added

Starts rotation to the given mechanical Position (degrees). See What are the Angles that Rotator uses, and How Do They Relate?.

Non-blocking: Must return immediately with IsMoving = True if the operation has successfully been started (unless it is already at the requested position). After the requested angle is successfully reached and motion stops, the IsMoving property must become False.

Important

It is vital that an instrument rotator prevent wrapping of cables going to the imager. This must be transparent to the rotation commands coming from the application, allowing the application to freely move the rotator between any two angles without limits or “dead zones”.

Parameters:

Position (float) – New mechanical position in degrees. See What are the Angles that Rotator uses, and How Do They Relate?.

Raises:

  • InvalidValueException – If Position is invalid.

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

Note

  • Asynchronous: The method returns as soon as the rotation operation has been successfully started, with the IsMoving property True (unless already at the requested position). After the requested angle is successfully reached and motion stops, the IsMoving property becomes False.

  • Calling MoveAbsolute() causes the TargetPosition property to change to the Position parameter then starts rotation to TargetPosition.

  • See What are the Angles that Rotator uses, and How Do They Relate?.

  • This method is to address requirements that need a physical rotation angle such as taking sky flats.

Rotator.Sync(Position: float)

Added in version 3: Member added

Syncs the rotator to the specified position angle without moving it. See What are the Angles that Rotator uses, and How Do They Relate?.

Parameters:

Position (float) – Synchronised rotator position angle. See What are the Angles that Rotator uses, and How Do They Relate?.

Returns:

Nothing

Raises:

  • InvalidValueException – If Position is invalid.

  • 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

Note

  • Must be short-lived and synchronous.

  • Once this method has been called and the sync offset determined, both the MoveAbsolute() method and the Position property must function in synced coordinates rather than mechanical coordinates. The sync offset must persist across driver starts and device reboots.

  • The offset should be persistent across device startup and shutdown. It represents a mechanical offset that should not change.

  • See What are the Angles that Rotator uses, and How Do They Relate?.

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

Properties

property Rotator.CanReverse: Boolean

Added in version 2: Member added

Returns:

The direction of rotation can be set via the Reverse property

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

Must be implemented, must always return True.

Note

property Rotator.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 Rotator 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 Rotator.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.

property Rotator.Description: String

Added in version 2: Member added

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

Added in version 4: To allow reduction of status polling

Returns:

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

Return type:

List

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

Note

property Rotator.DriverInfo: String

Added in version 2: Member added

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 Rotator.DriverVersion: String

Added in version 2: Member added

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 Rotator.InterfaceVersion: Short

Added in version 2: Member added

Returns:

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 IRotatorV4, this will 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 Rotator.IsMoving: boolean

Changed in version 3: Clarified that this method must be implemented

Returns:

The rotator is currently moving to a new 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

Must be implemented.

Note

  • This is the correct property to use to determine successful completion of a (non-blocking) Move(), MoveAbsolute(), or MoveMechanical() request. IsMoving must be True immediately upon returning from any of these three movement calls (unless already at the requested position), and must remain True until successful completion, at which time IsMoving must become False.

property Rotator.MechanicalPosition: float

Added in version 3: Member added

Returns:

The raw mechanical position of the rotator in degrees, relative to the optics. See Sync() and What are the Angles that Rotator uses, and How Do They Relate?.

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 hardware or communication errors.

Attention

  • Must be implemented

  • Applications must not use this as a way to determine if a (non-blocking) MoveMechanical() has completed. The MechanicalPosition may transit through the requested position before finally settling. Use the IsMoving property.

Note

property Rotator.Name: String

Added in version 2: Member added

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 Rotator.Position: float

Changed in version 3: Clarified that this method must be implemented

Returns:

Current instantaneous Rotator position, allowing for any sync offset, in degrees. See What are the Angles that Rotator uses, and How Do They Relate?.

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 hardware or communication errors.

Attention

Applications must not use this as a way to determine if a (non-blocking) Move() or MoveAbsolute() has completed. The Position may transit through the requested position before finally settling. Use the IsMoving property.

Note

  • The Sync() method may used to make Position indicate equatorial position angle. This can account for not only an offset in the rotator’s mechanical position, but also the angle at which an attached imager is mounted.

  • If Sync() has never been called, Position must be equal to MechanicalPosition. Once called, however, the offset must remain across driver starts and device reboots.

  • For more info see What are the Angles that Rotator uses, and How Do They Relate?.

property Rotator.Reverse: boolean

Changed in version 3: Clarified that this method must be implemented

Returns:

(Read/Write) Set or indicate rotation direction reversal. See What are the Angles that Rotator uses, and How Do They Relate?.

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 hardware or communication errors.

Attention

Must be implemented

Note

Rotation is normally in degrees counterclockwise as viewed from behind the rotator, looking toward the sky. This corresponds to the direction of equatorial position angle. Set this property True to cause rotation opposite to equatorial PositionAngle, i.e. clockwise. See What are the Angles that Rotator uses, and How Do They Relate?

property Rotator.StepSize: float
Returns:

The minimum rotation step size (degrees)

Return type:

float

Raises:

  • PropertyNotImplementedException – If the rotator does not know its step size.

  • NotConnectedException – If the device is not connected

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

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

Added in version 2: Recommended over (now) deprecated CommandBlind(), CommandBool(), and CommandString() as more flexible extension mechanic.

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 Rotator.TargetPosition: float

Changed in version 3: Clarified that this method must be implemented

Returns:

The destination position angle for Move() a and MoveAbsolute().

Return type:

float

Note

This will contain the new Position, including any Sync() offset, immediately upon return from a call to Move(), MoveAbsolute()