Rotator Interface Standard 1.0
Programmer's Reference

Written by Dan Azari, RC Optical Systems
Adopted 25-April-2006

Introduction

This document describes the interface used by low-level rotator "driver" components as part of the Astronomy Common Object Model (ASCOM). Components that implement this interface can provide way for programs to control various rotaor via a standard set of properties and methods.

This specification covers a simple, low-level rotator control interface for reading and writing positions, slewing, synchronizing and access to common controller functions. The characteristics of this interface comply with the ASCOM Quality Guidelines, assuring consistent behavior and compatibility with the widest possible variety of Windows Automation clients.

Implementation and Conventions

All of the methods and properties specified must be present in any conforming driver's interface. However, some methods and properties may not actually be implemented; they will raise a "not implemented" error when called or accessed.

Positions are defined as positive CCW at the image plane. Depending on the number of optical reflections, the mechanical direction sense may reverse. The absolute position coordinate by be relative to startup position if homing is not supported, relative to a mechanical known position if homing is supported, or represent equatorial position angle if synchronized.

Usage

To control a particular rotator type, a program would create an instance of the driver for that rotator type, then use the standard properties and methods described in this document to effect control of that scope. Thus any program or script that uses the standard driver interface automatically gains access to any rotator type for which a driver exists. For more information on ASCOM, see the ASCOM Home Page.

For best results

This will display best if you have Internet Explorer 5 or later, text size set to "smaller", and the following fonts installed:

Arial
Verdana
Lucida Console

Rotator.IsMoving Property

Rotator.IsMoving (read-only, Boolean)

True if the Rotator is currently moving to a new position. False if the Rotator is stationary.

Syntax

Rotator.IsMoving

The property syntax has these parts:

Part	Description
Value (Boolean)	True if the Rotator is currently moving to a new position. False if the Rotator is stationary.

Remarks

Rotator.IsMoving is True whenever Rotator.TargetPosition <> Rotator.Position. Should throw an exception if unable to handle property.

Rotator.Connected Property

Rotator.Connected (read-write, Boolean)

State of the connection to the Rotator.

Syntax

Rotator.Connected [= Boolean]

The property syntax has these parts:

Part	Description
Value (Boolean)	State of the connection to the Rotator.

Remarks

Set True to start the Connected to the Rotator; set False to terminate the Connected. The current Connected status can also be read back as this property. An exception will be raised if the Connected fails to change state for any reason.

Rotator.Position Property

Rotator.Position (read-only, Float)

Current instantaneous Rotator position, in degrees.

Syntax

Rotator.Position

The property syntax has these parts:

Part	Description
Value (Float)	Current Rotator position, in degrees.

Remarks

The meaning of the Rotator.Position property is dependent on the Home state and/or the Synch status. When a rotator is initially powered up the Position value may be persisted from its last known position, it may seek Home and reflect a relative mechanical position, or it may be in an un-initialized state and have no relivance to either the mechanical or equatorial coordinates. To set the position value relative to a repeatable mechanical reference, issue the Rotator.Home method. To synchronize the position value to a know equatorial position, issue the Rotator.Synch method. Should throw an exception if unable to report instantaneous position.

Also see: Rotator.TargetPosition

Rotator.TargetPosition Property

Rotator.TargetPosition (read-only, Float)

Current Rotator target position, in degrees.

Syntax

Rotator.TargetPosition

The property syntax has these parts:

Part	Description
Value (Float)	Current Rotator target position, in degrees.

Remarks

The meaning of the Rotator.TargetPosition property is dependent on the Home state and/or the Synch status. When a rotator is initially powered up the Position value may be persisted from its last known position, it may seek Home and reflect a relative mechanical position, or it may be in an un-initialized state and have no relivance to either the mechanical or equatorial coordinates. To set the position value relative to a repeatable mechanical reference, issue the Rotator.Home method. To synchronize the position value to a know equatorial position, issue the Rotator.Synch method. Should throw an exception if unable to report TargetPosition.

Also see: Rotator.Position

Rotator.StepSize Property

Rotator.StepSize (read-only, Float)

The minimum StepSize, in degrees.

Syntax

Rotator.StepSize

The property syntax has these parts:

Part	Description
Value (Float)	The minimum StepSize, in degrees.

Remarks

Raises an exception if the rotator does not intrinsically know what the step size is.

Rotator.Reverse Property

Rotator.Reverse (read-write, Boolean)

Sets or Returns the rotator’s Reverse state.

Syntax

Rotator.Reverese [= Boolean]

The property syntax has these parts:

Part	Description
Value (Boolean)	Sets or Returns the rotator’s Reverse state

Remarks

The value of Rotator.Reverse should be set to cause positive Rotator.Move() in a CCW direction at the image plane. The Reverse value should be persisted by the Rotator firmware and/or driver, and should be accessible through the Setup Dialog and/or driver application. An exception should be thrown if Reverse property is not supported.

Rotator.CanReverse Property

Rotator.CanReverse (read-only, Boolean)

Returns True if the Rotator supports the Rotator.Reverse() method.

Syntax

Rotator.CanReverse

The property syntax has these parts:

Part	Description
Value (Boolean)	Returns True if the Rotator supports the Rotator.Reverse() method.

Remarks

Rotator.Halt() Method

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

Syntax

Rotator.Halt()

The method syntax has these parts:

Part	Description
Return (Nothing)	Does not return a value.

Remarks

Some Rotators may not support this function, in which case an exception will 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() Method

Syntax

Rotator.Move(Position)

Causes the rotator to move Position degrees relative to the current Position value.

The method syntax has these parts:

Part	Description
Position (Float)	Relative position to move in degrees from current Position.
Return (Nothing)	Does not return a value.

Remarks

Issuing a Rotator.Move(value) method will cause the Rotator.TargetPosition value to change to Rotator.Position plus {Value}, not the Rotator.TargetPosition plus {Value} (i.e. will cause a move relative to its current position, not relative to its last targeted position, if different). The mechanical direction of rotation is determined by the Rotator.Reverse property. By convention, position direction is defined as CCW equatorial at the image plane. If a Move would cause rotation outside a software or mechanical limt, the firmware and/or driver should reverse direction through 360 degrees to minimize cable wrap. Should throw an exception if can not perform Move for any reason.

Rotator.MoveAbsolute() Method

Syntax

Rotator.MoveAbsolute(Position)

Causes the rotator to move the absolute position of Position degrees.

The method syntax has these parts:

Part	Description
Position (Float)	Causes the rotator to move the absolute position of Position degrees.
Return (Nothing)	Does not return a value.

Remarks

Issuing a Rotator.MoveAbsolute(value) method will cause the Rotator.TargetPosition to equal {value}. The mechanical direction of rotation should be determined by the Rotator firmware and/or driver to minimize cable wrap. Should through an exception if unable to perform MoveAbsolute.

Rotator.SetupDialog() Method

Display a dialog box for the user to enter in custom setup parameters, such as a COM port selection.

Syntax

Rotator.SetupDialog()

The method syntax has these parts:

Part	Description
Return (Nothing)	Does not return a value.

Remarks

If no dialog is required or supported, the method shall display a “No setup required.” message..

Rotator Interface Standard 1.0 Programmer's Reference

Introduction

Implementation and Conventions

Usage

For best results

Rotator.IsMoving Property

Syntax

Remarks

Rotator.IsMoving is True whenever Rotator.TargetPosition <> Rotator.Position. Should throw an exception if unable to handle property.

Rotator.Connected Property

Syntax

Remarks

Rotator.Position Property

Syntax

Remarks

Rotator.TargetPosition Property

Syntax

Remarks

Rotator.StepSize Property

Syntax

Remarks

Rotator.Reverse Property

Syntax

Remarks

Rotator.CanReverse Property

Syntax

Remarks

Rotator.Halt() Method

Syntax

Remarks

Rotator.Move() Method

Syntax

Remarks

Rotator.MoveAbsolute() Method

Syntax

Remarks

Rotator.SetupDialog() Method

Syntax

Remarks

Rotator Interface Standard 1.0
Programmer's Reference