Rotator Class

The Rotator V3 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 in PA for you as well as other apps that might be using the rotator.

Master Interfaces Reference

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

class alpaca.rotator.Rotator(address: str, device_number: int, protocol: str = 'http')

Bases: Device

ASCOM Standard IRotatorV3 interface.

Initialize the Rotator object.

Parameters:

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

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

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

Raises:

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

Action(ActionName: str, *Parameters) → str

Invoke the specified device-specific custom action

Common to all devices

Parameters:

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

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

Returns:

String result of the action.

Raises:

Note

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

Master Interfaces Reference

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

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

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

Common to all devices

Parameters:

  • Command – The literal command string to be transmitted.

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

Raises:

Attention

Deprecated, will most likely result in NotImplementedException

Master Interfaces Reference

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

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

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

Common to all devices

Returns:

The True/False response from the command

Parameters:

  • Command – The literal command string to be transmitted.

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

Raises:

Attention

Deprecated, will most likely result in NotImplementedException

Master Interfaces Reference

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

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

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

Common to all devices

Returns:

The string response from the command

Parameters:

  • Command – The literal command string to be transmitted.

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

Raises:

Attention

Deprecated, will most likely result in NotImplementedException

Master Interfaces Reference

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

Connect() → None

Connect to the device asynchronously.

Common to all devices

Returns:

Nothing

Raises:

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

Note

  • Non-Blocking Use Connecting to indicate completion.

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

Master Interfaces Reference

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

Disconnect() → None

Disconnect from the device asynchronously.

Common to all devices

Returns:

Nothing

Raises:

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

Note

  • Non-Blocking Use Connecting to indicate completion.

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

Master Interfaces Reference

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

Halt() → None

Immediately stop any rotator motion due to a previous movement call.

Raises:

Note

  • You should try to call this method aftr initialization to see if halting is supported by your device. You can use this info to possibly disable a Halt button in your user interface.

Master Interfaces Reference

Rotator.Halt() (external)

Move(Position: float) → None

Starts rotation relative to the current position (degrees)

Non-blocking: Returns immediately with IsMoving = True if the operation has successfully been started, or if it returns with IsMoving = False, it will already be at the requested position, also a success. See Notes, and How can I tell if my asynchronous request failed after being started?

Also See Notes for details on absolute versus relative movement.

Parameters:

Position – The angular amount (degrees) to move relative to the current position.

Raises:

  • InvalidValueException – The given position change results in a position outside 0 <= position < 360.

  • NotConnectedException – If the device is not connected

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

Note

  • Asynchronous: The method returns as soon as the rotation operation has been successfully started, with the IsMoving property True. After the requested angle is successfully reached and motion stops, the IsMoving property becomes False. See How can I tell if my asynchronous request failed after being started?

  • Calling Move causes 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.

Master Interfaces Reference

Rotator.Move() (external)

MoveAbsolute(Position: float) → None

Starts rotation to the new position (degrees)

Non-blocking: Returns immediately with IsMoving = True if the operation has successfully been started, or if it returns with IsMoving = False, it will already be at the requested position, also a success. See Notes, and How can I tell if my asynchronous request failed after being started?

Parameters:

Position – The requested angle, degrees.

Raises:

  • InvalidValueException – The given position is 0 <= position < 360.

  • NotConnectedException – If the device is not connected

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

Note

  • Asynchronous: The method returns as soon as the rotation operation has been successfully started, with the IsMoving property True. After the requested angle is successfully reached and motion stops, the IsMoving property becomes False. See How can I tell if my asynchronous request failed after being started?

  • Calling Move causes the TargetPosition property to change to the value of the Position parameter (modulo 360 degrees), then starts rotation to TargetPosition. Position includes the effect of any previous Sync() operation.

Master Interfaces Reference

Rotator.MoveAbsolute() (external)

MoveMechanical(Position: float) → None

Starts rotation to the given mechanical position (degrees)

Non-blocking: Returns immediately with IsMoving = True if the operation has successfully been started, or if it returns with IsMoving = False, it will already be at the requested position, also a success. See Notes, and How can I tell if my asynchronous request failed after being started?

Parameters:

Position – The requested angle, degrees.

Raises:

  • InvalidValueException – The given position is 0 <= position < 360. [or does it just apply modulo 360? Then what is an “invalid” value?]

  • NotConnectedException – If the device is not connected

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

Note

  • Asynchronous: The method returns as soon as the rotation operation has been successfully started, with the IsMoving property True. After the requested angle is successfully reached and motion stops, the IsMoving property becomes False. See How can I tell if my asynchronous request failed after being started?

  • Calling MoveMechanical causes the TargetPosition property to change to the value of the Position parameter then starts rotation to TargetPosition. This moves without regard to the SyncOffset, that is, to the mechanical rotator angle.

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

Master Interfaces Reference

Rotator.MoveMechanical() (external)

Sync(Position: float) → None

Syncs the rotator to the specified position angle (degrees) without moving it.

Parameters:

Position – The requested angle, degrees.

Raises:

  • InvalidValueException – The given position is 0 <= position < 360. [or does it just apply modulo 360? Then what is an “invalid” value?]

  • NotConnectedException – If the device is not connected

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

Note

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

Master Interfaces Reference

Rotator.Sync() (external)

property CanReverse: bool

The rotator supports the Reverse method (see Notes)

Raises:

  • NotConnectedException – If the device is not connected

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

Note

  • For IRotatorV3 drivers and later(InterfaceVersion >= 3) CanReverse is always True.

  • For more info on reversal see the Reverse property.

Master Interfaces Reference

Rotator.CanReverse (external)

property Connected: bool

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

Common to all devices

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

Raises:

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

Note

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

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

Master Interfaces Reference

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

property Connecting: bool

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

Common to all devices

Raises:

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

Note

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

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

Master Interfaces Reference

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

property Description: str

Description of the device such as manufacturer and model number.

Common to all devices

Raises:

  • NotConnectedException – If the device status is unavailable

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

Note

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

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

Master Interfaces Reference

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

property DeviceState: List[dict]

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

Common to all devices

Raises:

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

Master Interfaces Reference

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

property DriverInfo: List[str]

Descriptive and version information about the ASCOM driver

Common to all devices

Returns:

Python list of strings (see Notes)

Raises:

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

Note

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

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

Master Interfaces Reference

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

property DriverVersion: str

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

Common to all devices

Raises:

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

Note

  • This must be in the form “n.n”. It should not to be confused with the InterfaceVersion property, which is the version of this specification supported by the driver. Note: on systems with a comma as the decimal point you may need to make accommodations to parse the value.

Master Interfaces Reference

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

property InterfaceVersion: int

ASCOM Device interface definition version that this device supports.

Common to all devices

Raises:

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

Note

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

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

Master Interfaces Reference

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

property IsMoving: bool

The rotator is currently moving to a new 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. The device did not successfully complete the request.

Note

  • This is the correct property to use to determine successful completion of a (non-blocking) Move() request. IsMoving will be True immediately upon returning from a Move() call, and will remain True until successful completion, at which time IsMoving will become False.

Master Interfaces Reference

Rotator.IsMoving (external)

property MechanicalPosition: bool

The raw mechanical position (deg) of the rotator

Raises:

  • NotConnectedException – If the device is not connected

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

Note

Value is in degrees counterclockwise from the rotator’s mechanical index.

Master Interfaces Reference

Rotator.MechanicalPosition (external)

property Name: str

The short name of the driver, for display purposes.

Common to all devices

Raises:

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

Master Interfaces Reference

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

property Position: bool

This returns the position (deg) of the rotator allowing for sync 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. The device did not successfully complete the request.

Note

  • Position is in degrees counterclockwise

  • 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 will be equal to MechanicalPosition. Once called, however, the offset will remain across driver starts and device reboots.

Master Interfaces Reference

Rotator.Position (external)

property Reverse: bool

(Read/Write) Set or indicate rotation direction reversal.

Raises:

  • NotConnectedException – If the device is not connected

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

Note

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.

Master Interfaces Reference

Rotator.Reverse (external)

property StepSize: float

The minimum rotation step size (deg)

Raises:

  • NotImplementedException – If this property is not available from the device

  • NotConnectedException – If the device is not connected

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

Master Interfaces Reference

Rotator.StepSize (external)

property SupportedActions: List[str]

The list of custom action names supported by this driver

Common to all devices

Returns:

Python list of strings (see Notes)

Raises:

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

Note

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

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

Master Interfaces Reference

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

property TargetPosition: float

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

Note

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

Master Interfaces Reference

Rotator.TargetPosition (external)