org.minetti.astrodevice.common.orb
Interface TelescopeOrbProcess

All Superinterfaces:

DeviceOrbProcess, Remote

public interface TelescopeOrbProcess
extends DeviceOrbProcess, Remote

ORB process on telescopes.

Author:

Jean-Philippe MINETTI

Method Summary

void	abortSlew(long telescopeId) Stops a slew in progress.
TelescopePierSide	destinationSideOfPier(long telescopeId, double rightAscension, double declination) Predicts side of pier for German equatorial mounts.
void	findHome(long telescopeId) Locates the telescope's "home" position (synchronous).
double	getAltitude(long telescopeId) Returns the altitude above the local horizon of the telescope's current position (degrees, positive up).
List<TelescopeAxisRate>	getAxisRateList(long telescopeId, TelescopeAxis axis) Determine the rates at which the telescope may be moved about the specified axis by the moveAxis(long, TelescopeAxis, double) method.
double	getAzimuth(long telescopeId) Returns the azimuth at the local horizon of the telescope's current position (degrees, North-referenced, positive East/clockwise).
TelescopeCapabilities	getCapabilities(Locale locale, long telescopeId) Returns all capabilities of a telescope.
double	getDeclination(long telescopeId) Returns the declination (degrees) of the telescope's current equatorial coordinates, in the coordinate system given by the getCharacteristics(long).getEquatorialSystem() method.
double	getDeclinationRate(long telescopeId) Returns the declination tracking rate (default = 0.0).
TelescopeFeatures	getFeatures(Locale locale, long telescopeId) Returns all features of a telescope.
double	getGuideRateDeclination(long telescopeId) Returns the current declination movement rate offset for telescope guiding.
double	getGuideRateRightAscension(long telescopeId) Returns the current Right Ascension movement rate offset for telescope guiding.
TelescopeOpticalFeatures	getOpticalFeatures(Locale locale, long telescopeId) Returns the optical features of a telescope.
double	getRightAscension(long telescopeId) Returns the right ascension (hours) of the telescope's current equatorial coordinates, in the coordinate system given by the getCharacteristics(long).getEquatorialSystem() method.
double	getRightAscensionRate(long telescopeId) Returns the right ascension tracking rate offset from sidereal (default = 0.0).
TelescopePierSide	getSideOfPier(long telescopeId) Returns the pointing state of the mount.
TimeSynchronization	getSiderealTime(long telescopeId, long clientTransmitTime) Returns the synchronization of local apparent sidereal time from the telescope's internal clock (nanoseconds, sidereal).
double	getSiteElevation(long telescopeId) Returns the elevation above mean sea level of the site at which the telescope is located.
double	getSiteLatitude(long telescopeId) Returns the geodetic(map) latitude of the site at which the telescope is located.
double	getSiteLongitude(long telescopeId) Returns the longitude of the site at which the telescope is located.
short	getSlewSettleTime(long telescopeId) Returns the post-slew settling time.
double	getTargetDeclination(long telescopeId) Returns the declination for the target of an equatorial slew or sync operation.
double	getTargetRightAscension(long telescopeId) Returns the right ascension for the target of an equatorial slew or sync operation.
TelescopeDriveRate	getTrackingRate(long telescopeId) Returns the current tracking rate of the telescope's sidereal drive.
List<TelescopeDriveRate>	getTrackingRates(long telescopeId) Returns a list of supported TelescopeDriveRate values that describe the permissible values of the getTrackingRate(long)/ setTrackingRate(long, TelescopeDriveRate) methods for this telescope type.
TimeSynchronization	getUtcDate(long telescopeId, long clientTransmitTime) Returns the synchronization of UTC date/time of the telescope's internal clock.
boolean	isAtHome(long telescopeId) Returns TRUE if the telescope is stopped in the home position.
boolean	isDoesRefraction(long telescopeId) Returns TRUE if the telescope or driver applies atmospheric refraction to coordinates.
boolean	isParked(long telescopeId) Returns TRUE if the telescope has been put into the parked state by the park(long) method.
boolean	isPulseGuiding(long telescopeId) Returns TRUE if a pulseGuide(long, TelescopeGuideDirection, int) command is in progress, FALSE otherwise.
boolean	isSlewing(long telescopeId) Returns TRUE if telescope is currently moving in response to one of the Slew methods or the moveAxis(long, TelescopeAxis, double) method, FALSE at all other times.
boolean	isTracking(long telescopeId) Returns the state of the telescope's sidereal tracking drive.
void	moveAxis(long telescopeId, TelescopeAxis axis, double rate) Moves the telescope in one axis at the given rate.
void	park(long telescopeId) Moves the telescope to its park position, stop all motion (or restrict to a small safe range), and set isParked(long) to TRUE.
void	pulseGuide(long telescopeId, TelescopeGuideDirection direction, int duration) Moves the scope in the given direction for the given interval or time at the rate given by the corresponding getGuideRateRightAscension(long) and getGuideRateDeclination(long) methods.
void	setDeclinationRate(long telescopeId, double declinationRate) Sets the declination tracking rate.
void	setDoesRefraction(long telescopeId, boolean doesRefraction) Sets TRUE if the telescope or driver applies atmospheric refraction to coordinates.
void	setGuideRateDeclination(long telescopeId, double guideRateDeclination) Sets the current declination movement rate offset for telescope guiding.
void	setGuideRateRightAscension(long telescopeId, double guideRateRightAscension) Sets the current Right Ascension movement rate offset for telescope guiding.
void	setOpticalCharacteristics(Locale locale, long telescopeId, TelescopeOpticalFeatures opticalCharacteristics) Sets the optical features for a telescope.
void	setPark(long telescopeId) Sets the telescope's park position to be its current position.
void	setRightAscensionRate(long telescopeId, double rightAscensionRate) Sets the right ascension tracking rate offset from sidereal.
void	setSideOfPier(long telescopeId, TelescopePierSide sideOfPier) Sets the pointing state of the mount.
void	setSiteElevation(long telescopeId, double elevation) Sets the elevation above mean sea level of the site at which the telescope is located.
void	setSiteLatitude(long telescopeId, double latitude) Sets the geodetic(map) latitude of the site at which the telescope is located.
void	setSiteLongitude(long telescopeId, double longitude) Sets the longitude of the site at which the telescope is located.
void	setSlewSettleTime(long telescopeId, short slewSettleTime) Sets the post-slew settling time.
void	setTargetDeclination(long telescopeId, double targetDeclination) Sets the declination for the target of an equatorial slew or sync operation.
void	setTargetRightAscension(long telescopeId, double targetRightAscension) Sets the right ascension for the target of an equatorial slew or sync operation.
void	setTracking(long telescopeId, boolean tracking) Sets the state of the telescope's sidereal tracking drive.
void	setTrackingRate(long telescopeId, TelescopeDriveRate trackingRate) Sets a new tracking rate of the telescope's sidereal drive.
void	setUtcDate(long telescopeId, long timeOffset) Changes the UTC date/time of the telescope's internal clock.
void	slewToAltAz(long telescopeId, double azimuth, double altitude) Moves the telescope to the given local horizontal coordinates, return when slew is complete.
void	slewToAltAzAsync(long telescopeId, double azimuth, double altitude) This method must be implemented if getCapabilities(long).canSlewAltAzAsync() returns TRUE.
void	slewToCoordinates(long telescopeId, double rightAscension, double declination) Moves the telescope to the given equatorial coordinates, return when slew is complete.
void	slewToCoordinatesAsync(long telescopeId, double rightAscension, double declination) Moves the telescope to the given equatorial coordinates, return immediately after starting the slew.
void	slewToTarget(long telescopeId) Moves the telescope to the getTargetRightAscension(long) and getTargetDeclination(long) coordinates, return when slew complete.
void	slewToTargetAsync(long telescopeId) Moves the telescope to the getTargetRightAscension(long) and getTargetDeclination(long) coordinates, returns immediately after starting the slew.
void	syncToAltAz(long telescopeId, double azimuth, double altitude) Matches the scope's local horizontal coordinates to the given local horizontal coordinates.
void	syncToCoordinates(long telescopeId, double rightAscension, double declination) Matches the scope's equatorial coordinates to the given equatorial coordinates.
void	syncToTarget(long telescopeId) Matches the scope's equatorial coordinates to the given equatorial coordinates.
void	unpark(long telescopeId) Takes telescope out of the parked state.

Methods inherited from interface org.minetti.astrodevice.common.orb.DeviceOrbProcess

action, commandBlind, commandBoolean, commandString, getDescription, getDeviceList, getDeviceName, getDriverInfo, getDriverVersion, getInterfaceVersion, getPluginName, getSupportedActions, isConnected, setConnected, showSetupDialog

Method Detail

getFeatures

TelescopeFeatures getFeatures(Locale locale,
                              long telescopeId)
                              throws RemoteException

Returns all features of a telescope.

Parameters:

locale - Locale for select messages in the language of user.

telescopeId - Telescope identifier.

Returns:

Object representing all features of telescope.

Throws:

RemoteException - Exception if an error occurred.

getCapabilities

TelescopeCapabilities getCapabilities(Locale locale,
                                      long telescopeId)
                                      throws RemoteException

Returns all capabilities of a telescope.

Parameters:

locale - Locale for select messages in the language of user.

telescopeId - Telescope identifier.

Returns:

Object representing all capabilities of telescope.

Throws:

RemoteException - Exception if an error occurred.

getOpticalFeatures

TelescopeOpticalFeatures getOpticalFeatures(Locale locale,
                                            long telescopeId)
                                            throws RemoteException

Returns the optical features of a telescope.

Parameters:

locale - Locale for select messages in the language of user.

telescopeId - Telescope identifier.

Returns:

Object representing the optical features of telescope.

Throws:

RemoteException - Exception if an error occurred.

setOpticalCharacteristics

void setOpticalCharacteristics(Locale locale,
                               long telescopeId,
                               TelescopeOpticalFeatures opticalCharacteristics)
                               throws RemoteException

Sets the optical features for a telescope.

Parameters:

locale - Locale for select messages in the language of user.

telescopeId - Telescope identifier.

opticalCharacteristics - Object representing the optical features of telescope.

Throws:

RemoteException - Exception if an error occurred.

park

void park(long telescopeId)
          throws RemoteException

Moves the telescope to its park position, stop all motion (or restrict to a small safe range), and set isParked(long) to TRUE.

Raises an error if there is a problem communicating with the telescope or if parking fails. Parking should put the telescope into a state where its pointing accuracy will not be lost if it is power-cycled (without moving it). Some telescopes must be power-cycled before unparking. Others may be unparked by simply calling the unpark(long) method. Calling this with isParked(long) = TRUE does nothing (harmless).

Parameters:

telescopeId - Telescope identifier.

Throws:

RemoteException - Exception if an error occurred.

unpark

void unpark(long telescopeId)
            throws RemoteException

Takes telescope out of the parked state.

The state of isTracking(long) after unparking is undetermined. Valid only after park(long). Applications must check and change isTracking(long) as needed after unparking. Raises an error if unparking fails. Calling this with isParked(long) = FALSE does nothing (harmless).

Parameters:

telescopeId - Telescope identifier.

Throws:

RemoteException - Exception if an error occurred.

isParked

boolean isParked(long telescopeId)
                 throws RemoteException

Returns TRUE if the telescope has been put into the parked state by the park(long) method. Set FALSE by calling the unpark(long) method.

isParked(long) is TRUE when the telescope is in the parked state. This is achieved by calling the park(long) method. When isParked(long) is TRUE, the telescope movement is stopped (or restricted to a small safe range of movement) and all calls that would cause telescope movement (e.g. slewing, changing Tracking state) must not do so, and must raise an error.

The telescope is taken out of parked state by calling the unpark(long) method. If the telescope cannot be parked, then isParked(long) must always return FALSE.

Parameters:

telescopeId - Telescope identifier.

Returns:

TRUE if the telescope has been put into the parked state.

Throws:

RemoteException - Exception if an error occurred.

setPark

void setPark(long telescopeId)
             throws RemoteException

Sets the telescope's park position to be its current position.

Parameters:

telescopeId - Telescope identifier.

Throws:

RemoteException - Exception if an error occurred.

findHome

void findHome(long telescopeId)
              throws RemoteException

Locates the telescope's "home" position (synchronous).

Returns only after the home position has been found. At this point the isAtHome(long) method will return TRUE. Raises an error if there is a problem. Raises an error if isParked(long) is TRUE.

Parameters:

telescopeId - Telescope identifier.

Throws:

RemoteException - Exception if an error occurred.

isAtHome

boolean isAtHome(long telescopeId)
                 throws RemoteException

Returns TRUE if the telescope is stopped in the home position. Set only following a findHome(long) operation, and reset with any slew operation. This method must return FALSE if the telescope does not support homing.

Parameters:

telescopeId - Telescope identifier.

Returns:

TRUE if the telescope is stopped in the home position.

Throws:

RemoteException - Exception if an error occurred.

isTracking

boolean isTracking(long telescopeId)
                   throws RemoteException

Returns the state of the telescope's sidereal tracking drive.

Parameters:

telescopeId - Telescope identifier.

Returns:

TRUE if the sidereal drive was turned on.

Throws:

RemoteException - Exception if an error occurred.

setTracking

void setTracking(long telescopeId,
                 boolean tracking)
                 throws RemoteException

Sets the state of the telescope's sidereal tracking drive.

Calling this method will turn the sidereal drive on and off. However, some telescopes may not support changing the tracking value and thus may not support turning tracking on and off. See the getCapabilities(long).canSetTracking() method.

Parameters:

telescopeId - Telescope identifier.

tracking - TRUE for turn the sidereal drive on.

Throws:

RemoteException - Exception if an error occurred.

getTrackingRate

TelescopeDriveRate getTrackingRate(long telescopeId)
                                   throws RemoteException

Returns the current tracking rate of the telescope's sidereal drive.

If the mount's current tracking rate cannot be determined (for example, it is a write-only rate of the mount's protocol), it is permitted for the driver to force and report a default rate on connect. In this case, the preferred default is Sidereal rate.

Parameters:

telescopeId - Telescope identifier.

Returns:

Current tracking rate of the telescope's sidereal drive.

Throws:

RemoteException - Exception if an error occurred.

setTrackingRate

void setTrackingRate(long telescopeId,
                     TelescopeDriveRate trackingRate)
                     throws RemoteException

Sets a new tracking rate of the telescope's sidereal drive.

Supported rates are contained within a list of TelescopeDriveRate. Values assigned to trackingRate must be one of these supported rates. If an unsupported value is assigned to this field, it will raise an error. The currently selected tracking rate be further adjusted via the setRightAscensionRate(long, double) and setDeclinationRate(long, double) methods. These rate offsets are applied to the currently selected tracking rate. Mounts must start up with a known or default tracking rate, and the getTrackingRate(long) method must return that known/default tracking rate until changed.

Parameters:

telescopeId - Telescope identifier.

trackingRate - New tracking rate of the telescope's sidereal drive.

Throws:

RemoteException - Exception if an error occurred.

getTrackingRates

List<TelescopeDriveRate> getTrackingRates(long telescopeId)
                                          throws RemoteException

Returns a list of supported TelescopeDriveRate values that describe the permissible values of the getTrackingRate(long)/ setTrackingRate(long, TelescopeDriveRate) methods for this telescope type.

At a minimum, this must contain an item for SIDEREAL driveSidereal.

Parameters:

telescopeId - Telescope identifier.

Returns:

List of supported TelescopeDriveRate values.

Throws:

RemoteException - Exception if an error occurred.

getRightAscensionRate

double getRightAscensionRate(long telescopeId)
                             throws RemoteException

Returns the right ascension tracking rate offset from sidereal (default = 0.0).

This return value, together with getDeclinationRate(long), provides support for "offset tracking". Offset tracking is used primarily for tracking objects that move relatively slowly against the equatorial coordinate system. It also may be used by a software guiding system that controls rates instead of using the pulseGuide(long, TelescopeGuideDirection, int) method.

The return value represents an offset from the currently selected getTrackingRate(long):

• If the return value is zero, tracking will be at the selected getTrackingRate(long).
• If getCapabilities(long).canSetRightAscensionRate() return FALSE, this method must always return 0.
• The return value is in seconds of right ascension per sidereal second.
• If this return value is non-zero when an equatorial slew is initiated, the telescope should continue to update the slew destination coordinates at the given offset rate. This will allow precise slews to a fast-moving target with a slow-slewing telescope. When the slew completes, the getTargetRightAscension(long) and getTargetDeclination(long) methods should reflect the final (adjusted) destination.

Parameters:

telescopeId - Telescope identifier.

Returns:

Right ascension tracking rate offset from sidereal in arcseconds per second.

Throws:

RemoteException - Exception if an error occurred.

setRightAscensionRate

void setRightAscensionRate(long telescopeId,
                           double rightAscensionRate)
                           throws RemoteException

Sets the right ascension tracking rate offset from sidereal.

The rightAscensionRate value, together with declinationRate, provides support for "offset tracking". Offset tracking is used primarily for tracking objects that move relatively slowly against the equatorial coordinate system. It also may be used by a software guiding system that controls rates instead of using the pulseGuide(long, TelescopeGuideDirection, int) method.

The rightAscensionRate value represents an offset from the currently selected getTrackingRate(long):

• If this rightAscensionRate is zero, tracking will be at the selected getTrackingRate(long).
• The rightAscensionRate value is in seconds of right ascension per sidereal second.
• 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 rightAscensionRate value. Please note that these units was an unfortunate choice. A simple multiplication is all that's needed, as noted. The supported range of this rate is telescope specific, however, if this feature is supported, it can be expected that the range is sufficient to allow correction of guiding errors caused by moderate misalignment and periodic error.
• Use the setTracking(long, boolean) method to enable and disable sidereal tracking (if supported).

Parameters:

telescopeId - Telescope identifier.

rightAscensionRate - Right ascension tracking rate offset from sidereal in arcseconds per second.

Throws:

RemoteException - Exception if an error occurred.

getDeclinationRate

double getDeclinationRate(long telescopeId)
                          throws RemoteException

Returns the declination tracking rate (default = 0.0).

This method, together with getRightAscensionRate(long), provides support for "offset tracking". Offset tracking is used primarily for tracking objects that move relatively slowly against the equatorial coordinate system. It also may be used by a software guiding system that controls rates instead of using the pulseGuide(long, TelescopeGuideDirection, int) method.

• The returned value represents an offset from zero motion.
• If getCapabilities(long).canSetDeclinationRate() is FALSE, this method will always return 0.
• To discover whether this feature is supported, call the getCapabilities(long).canSetDeclinationRate() method.
• If this returned value is non-zero when an equatorial slew is initiated, the telescope should continue to update the slew destination coordinates at the given offset rate.
• This will allow precise slews to a fast-moving target with a slow-slewing telescope.
• When the slew completes, the getTargetRightAscension(long) and getTargetDeclination(long) methods should reflect the final (adjusted) destination.

Parameters:

telescopeId - Telescope identifier.

Returns:

Declination tracking rate in arcseconds per second.

Throws:

RemoteException - Exception if an error occurred.

setDeclinationRate

void setDeclinationRate(long telescopeId,
                        double declinationRate)
                        throws RemoteException

Sets the declination tracking rate.

This method, together with setRightAscensionRate(long, double), provides support for "offset tracking". Offset tracking is used primarily for tracking objects that move relatively slowly against the equatorial coordinate system. It also may be used by a software guiding system that controls rates instead of using the pulseGuide(long, TelescopeGuideDirection, int) method.

• The declinationRate value represents an offset from zero motion.
• To discover whether this feature is supported, call the getCapabilities(long).canSetDeclinationRate() method.
• The supported range of declinationRate is telescope specific, however, if this feature is supported, it can be expected that the range is sufficient to allow correction of guiding errors caused by moderate misalignment and periodic error.
• This will allow precise slews to a fast-moving target with a slow-slewing telescope.
• When the slew completes, the getTargetRightAscension(long) and getTargetDeclination(long) methods should reflect the final (adjusted) destination.

Parameters:

telescopeId - Telescope identifier.

declinationRate - Declination tracking rate in arcseconds per second.

Throws:

RemoteException - Exception if an error occurred.

getAxisRateList

List<TelescopeAxisRate> getAxisRateList(long telescopeId,
                                        TelescopeAxis axis)
                                        throws RemoteException

Determine the rates at which the telescope may be moved about the specified axis by the moveAxis(long, TelescopeAxis, double) method.

See the description of moveAxis(long, TelescopeAxis, double) for more information. This method must return an empty collection if moveAxis(long, TelescopeAxis, double) is not supported.

Please note that the TelescopeAxisRate objects must contain absolute non-negative values only. Applications determine the direction by applying a positive or negative sign to the rates provided. This obviates the need for the driver to to present a duplicate set of negative rates as well as the positive rates.

Parameters:

telescopeId - Telescope identifier.

axis - Axis about which rate information is desired.

Returns:

List of rates at which the telescope may be moved.

Throws:

RemoteException - Exception if an error occurred.

moveAxis

void moveAxis(long telescopeId,
              TelescopeAxis axis,
              double rate)
              throws RemoteException

Moves the telescope in one axis at the given rate.

This method supports control of the mount about its mechanical axes. The telescope will start moving at the specified rate about the specified axis and continue indefinitely. This method can be called for each axis separately, and have them all operate concurrently at separate rates of motion. Set the rate for an axis to zero to stop the motion about that axis. Tracking motion (if enabled, see note below) is suspended during this mode of operation.

Raises an error if isParked(long) is TRUE. This must be implemented for the if the getCapabilities(long).canMoveAxis(TelescopeAxis) method returns TRUE for the given axis.

• The movement rate must be within the value(s) obtained from a TelescopeAxisRate object in the getAxisRateList(long, TelescopeAxis) list. This is a signed value with negative rates moving in the opposite direction to positive rates.
• The values specified in getAxisRateList(long, TelescopeAxis) are absolute, unsigned values and apply to both directions, determined by the sign used in this command.
• The value of isSlewing(long) must be TRUE if the telescope is moving about any of its axes as a result of this method being called. This can be used to simulate a handbox by initiating motion with the MouseDown event and stopping the motion with the MouseUp event.
• It may be possible to implement satellite tracking by using the moveAxis(long, TelescopeAxis, double) method to move the scope in the required manner to track a satellite.

Parameters:

telescopeId - Telescope identifier.

axis - Physical axis about which movement is desired.

rate - Rate of motion (°/s) about the specified axis.

Throws:

RemoteException - Exception if an error occurred.

getAzimuth

double getAzimuth(long telescopeId)
                  throws RemoteException

Returns the azimuth at the local horizon of the telescope's current position (degrees, North-referenced, positive East/clockwise).

Parameters:

telescopeId - Telescope identifier.

Returns:

Azimuth at the local horizon of the telescope's current position.

Throws:

RemoteException - Exception if an error occurred.

getAltitude

double getAltitude(long telescopeId)
                   throws RemoteException

Returns the altitude above the local horizon of the telescope's current position (degrees, positive up).

Parameters:

telescopeId - Telescope identifier.

Returns:

Altitude above the local horizon of the telescope's current position.

Throws:

RemoteException - Exception if an error occurred.

getRightAscension

double getRightAscension(long telescopeId)
                         throws RemoteException

Returns the right ascension (hours) of the telescope's current equatorial coordinates, in the coordinate system given by the getCharacteristics(long).getEquatorialSystem() method.

Calling this method will raise an error if the value is unavailable.

Parameters:

telescopeId - Telescope identifier.

Returns:

Right ascension (hours) of the telescope's current equatorial coordinates.

Throws:

RemoteException - Exception if an error occurred.

getDeclination

double getDeclination(long telescopeId)
                      throws RemoteException

Returns the declination (degrees) of the telescope's current equatorial coordinates, in the coordinate system given by the getCharacteristics(long).getEquatorialSystem() method.

Calling this method will raise an error if the value is unavailable.

Parameters:

telescopeId - Telescope identifier.

Returns:

Declination (degrees) of the telescope's current equatorial coordinates.

Throws:

RemoteException - Exception if an error occurred.

getTargetRightAscension

double getTargetRightAscension(long telescopeId)
                               throws RemoteException

Returns the right ascension for the target of an equatorial slew or sync operation.

Calling the method will raise an error if the value has never been set or is otherwise unavailable.

Parameters:

telescopeId - Telescope identifier.

Returns:

Right ascension for the target of an equatorial slew or sync operation (hours).

Throws:

RemoteException - Exception if an error occurred.

setTargetRightAscension

void setTargetRightAscension(long telescopeId,
                             double targetRightAscension)
                             throws RemoteException

Sets the right ascension for the target of an equatorial slew or sync operation.

Calling this method will raise an error if the given value is outside the range 0 to 24 hours.

Parameters:

telescopeId - Telescope identifier.

targetRightAscension - Right ascension for the target of an equatorial slew or sync operation (hours).

Throws:

RemoteException - Exception if an error occurred.

getTargetDeclination

double getTargetDeclination(long telescopeId)
                            throws RemoteException

Returns the declination for the target of an equatorial slew or sync operation.

Calling this method will raise an error if the value has never been set or is otherwise unavailable.

Parameters:

telescopeId - Telescope identifier.

Returns:

Declination for the target of an equatorial slew or sync operation (degrees, positive North).

Throws:

RemoteException - Exception if an error occurred.

setTargetDeclination

void setTargetDeclination(long telescopeId,
                          double targetDeclination)
                          throws RemoteException

Sets the declination for the target of an equatorial slew or sync operation.

Calling this method will raise an error if the given value is outside the range -90 to +90 degrees.

Parameters:

telescopeId - Telescope identifier.

targetDeclination - Declination for the target of an equatorial slew or sync operation (degrees, positive North).

Throws:

RemoteException - Exception if an error occurred.

isSlewing

boolean isSlewing(long telescopeId)
                  throws RemoteException

Returns TRUE if telescope is currently moving in response to one of the Slew methods or the moveAxis(long, TelescopeAxis, double) method, FALSE at all other times.

Call this method will raise an error if the value is unavailable. If the telescope is not capable of asynchronous slewing, the return value will always be FALSE. The definition of "slewing" excludes motion caused by sidereal tracking, pulseGuide(long, TelescopeGuideDirection, int), setRightAscensionRate(long, double), and setDeclinationRate(long, double). It reflects only motion caused by one of the Slew commands, flipping caused by call the setSideOfPier(long, TelescopePierSide) method, or moveAxis(long, TelescopeAxis, double).

Parameters:

telescopeId - Telescope identifier.

Returns:

TRUE if telescope is currently moving in response to one of the Slew methods or the moveAxis(long, TelescopeAxis, double) method, FALSE at all other times.

Throws:

RemoteException - Exception if an error occurred.

getSlewSettleTime

short getSlewSettleTime(long telescopeId)
                        throws RemoteException

Returns the post-slew settling time.

Parameters:

telescopeId - Telescope identifier.

Returns:

Post-slew settling time in seconds (s).

Throws:

RemoteException - Exception if an error occurred.

setSlewSettleTime

void setSlewSettleTime(long telescopeId,
                       short slewSettleTime)
                       throws RemoteException

Sets the post-slew settling time.

Adds additional time to slew operations. Slewing methods will not return, and the isSlewing(long) method will not become FALSE, until the slew completes and the slewSettleTime has elapsed.

This feature (if supported) may be used with mounts that require extra settling time after a slew.

Parameters:

telescopeId - Telescope identifier.

slewSettleTime - Post-slew settling time in seconds (s).

Throws:

RemoteException - Exception if an error occurred.

slewToAltAz

void slewToAltAz(long telescopeId,
                 double azimuth,
                 double altitude)
                 throws RemoteException

Moves the telescope to the given local horizontal coordinates, return when slew is complete.

This Method must be implemented if getCapabilities(long).canSlewAltAz() returns TRUE. Raises an error if the slew fails. The slew may fail if the target coordinates are beyond limits imposed within the driver component. Such limits include mechanical constraints imposed by the mount or attached instruments, building or dome enclosure restrictions, etc.

The return value by getTargetRightAscension(long) and getTargetDeclination(long) methods are not changed by this method. Raises an error if isParked(long) is TRUE, or if isTracking(long) is TRUE.

Parameters:

telescopeId - Telescope identifier.

azimuth - Target azimuth (degrees, North-referenced, positive East/clockwise).

altitude - Target altitude (degrees, positive up)

Throws:

RemoteException - Exception if an error occurred.

slewToAltAzAsync

void slewToAltAzAsync(long telescopeId,
                      double azimuth,
                      double altitude)
                      throws RemoteException

This method must be implemented if getCapabilities(long).canSlewAltAzAsync() returns TRUE.

This method should only be implemented if the methods getAltitude(long), getAzimuth(long), getRightAscension(long), getDeclination(long) and isSlewing(long) can be read while the scope is slewing. Raises an error if starting the slew fails. Returns immediately after starting the slew. The client may monitor the progress of the slew by reading the getAzimuth(long), getAltitude(long) , and isSlewing(long) methods during the slew. When the slew completes, isSlewing(long) becomes False. The slew may fail if the target coordinates are beyond limits imposed within the driver component. Such limits include mechanical constraints imposed by the mount or attached instruments, building or dome enclosure restrictions, etc. The getTargetRightAscension(long) and getTargetDeclination(long) methods are not changed by this method.

Raises an error if isParked(long) is TRUE, or if isTracking(long) is TRUE.

Parameters:

telescopeId - Telescope identifier.

azimuth - Azimuth to which to move.

altitude - Altitude to which to move to.

Throws:

RemoteException - Exception if an error occurred.

slewToCoordinates

void slewToCoordinates(long telescopeId,
                       double rightAscension,
                       double declination)
                       throws RemoteException

Moves the telescope to the given equatorial coordinates, return when slew is complete.

This Method must be implemented if getCapabilities(long).canSlew() returns TRUE. Raises an error if the slew fails. The slew may fail if the target coordinates are beyond limits imposed within the driver component. Such limits include mechanical constraints imposed by the mount or attached instruments, building or dome enclosure restrictions, etc. The target coordinates are copied to getTargetRightAscension(long) and getTargetDeclination(long) whether or not the slew succeeds.

Raises an error if isParked(long) is TRUE, or if isTracking(long) is FALSE.

Parameters:

telescopeId - Telescope identifier.

rightAscension - Destination right ascension (hours). Copied to getTargetRightAscension(long).

declination - Destination declination (degrees, positive North). Copied to getTargetDeclination(long).

Throws:

RemoteException - Exception if an error occurred.

slewToCoordinatesAsync

void slewToCoordinatesAsync(long telescopeId,
                            double rightAscension,
                            double declination)
                            throws RemoteException

Moves the telescope to the given equatorial coordinates, return immediately after starting the slew.

This method must be implemented if getCapabilities(long).canSlewAsync() returns TRUE. Raises an error if starting the slew failed. Returns immediately after starting the slew. The client may monitor the progress of the slew by reading the getRightAscension(long), getDeclination(long), and isSlewing(long) methods during the slew. When the slew completes, isSlewing(long) becomes FALSE. The slew may fail to start if the target coordinates are beyond limits imposed within the driver component. Such limits include mechanical constraints imposed by the mount or attached instruments, building or dome enclosure restrictions, etc.

The target coordinates are copied to getTargetRightAscension(long) and getTargetDeclination(long) whether or not the slew succeeds. Raises an error if isParked(long) is TRUE, or if isTracking(long) is FALSE.

Parameters:

telescopeId - Telescope identifier.

rightAscension - Destination right ascension (hours). Copied to getTargetRightAscension(long).

declination - Destination declination (degrees, positive North). Copied to getTargetDeclination(long).

Throws:

RemoteException - Exception if an error occurred.

slewToTarget

void slewToTarget(long telescopeId)
                  throws RemoteException

Moves the telescope to the getTargetRightAscension(long) and getTargetDeclination(long) coordinates, return when slew complete.

This Method must be implemented if getCapabilities(long).canSlew() returns TRUE. Raises an error if the slew fails. The slew may fail if the target coordinates are beyond limits imposed within the driver component. Such limits include mechanical constraints imposed by the mount or attached instruments, building or dome enclosure restrictions, etc. Raises an error if isParked(long) is TRUE, or if isTracking(long) is FALSE.

Parameters:

telescopeId - Telescope identifier.

Throws:

RemoteException - Exception if an error occurred.

slewToTargetAsync

void slewToTargetAsync(long telescopeId)
                       throws RemoteException

Moves the telescope to the getTargetRightAscension(long) and getTargetDeclination(long) coordinates, returns immediately after starting the slew.

This Method must be implemented if getCapabilities(long).canSlewAsync() returns TRUE. Raises an error if starting the slew failed. Returns immediately after starting the slew. The client may monitor the progress of the slew by reading the getRightAscension(long), getDeclination(long), and isSlewing(long) methods during the slew. When the slew completes, isSlewing(long) becomes FALSE. The slew may fail to start if the target coordinates are beyond limits imposed within the driver component. Such limits include mechanical constraints imposed by the mount or attached instruments, building or dome enclosure restrictions, etc. Raises an error if isParked(long) is TRUE, or if isTracking(long) is FALSE.

Parameters:

telescopeId - Telescope identifier.

Throws:

RemoteException - Exception if an error occurred.

abortSlew

void abortSlew(long telescopeId)
               throws RemoteException

Stops a slew in progress. Effective only after a call to:

• slewToTargetAsync(long),
• slewToCoordinatesAsync(long, double, double),
• slewToAltAzAsync(long, double, double),
• or moveAxis(long, TelescopeAxis, double).

Does nothing if no slew/motion is in progress. Tracking is returned to its pre-slew state. Raises an error if isParked(long) is TRUE.

Parameters:

telescopeId - Telescope identifier.

Throws:

RemoteException - Exception if an error occurred.

syncToAltAz

void syncToAltAz(long telescopeId,
                 double azimuth,
                 double altitude)
                 throws RemoteException

Matches the scope's local horizontal coordinates to the given local horizontal coordinates.

This must be implemented if the getCapabilities(long).canSyncAltAz() method is TRUE. Raises an error if matching fails.

Raises an error if isParked is TRUE, or if isTracking(long) is TRUE.

Parameters:

telescopeId - Telescope identifier.

azimuth - Target azimuth (degrees, North-referenced, positive East/clockwise).

altitude - Target altitude (degrees, positive up).

Throws:

RemoteException - Exception if an error occurred.

syncToCoordinates

void syncToCoordinates(long telescopeId,
                       double rightAscension,
                       double declination)
                       throws RemoteException

Matches the scope's equatorial coordinates to the given equatorial coordinates.

Parameters:

telescopeId - Telescope identifier.

rightAscension - Corrected right ascension (hours). Copied to the getTargetRightAscension(long) method.

declination - Corrected declination (degrees, positive North). Copied to the getTargetDeclination(long) method.

Throws:

RemoteException - Exception if an error occurred.

syncToTarget

void syncToTarget(long telescopeId)
                  throws RemoteException

Matches the scope's equatorial coordinates to the given equatorial coordinates.

This must be implemented if the getCapabilities(long).canSync() method is TRUE. Raises an error if matching fails. Raises an error if isParked(long) is TRUE, or if isTracking(long) is FALSE.

Parameters:

telescopeId - Telescope identifier.

Throws:

RemoteException - Exception if an error occurred.

destinationSideOfPier

TelescopePierSide destinationSideOfPier(long telescopeId,
                                        double rightAscension,
                                        double declination)
                                        throws RemoteException

Predicts side of pier for German equatorial mounts.

Parameters:

telescopeId - Telescope identifier.

rightAscension - Destination right ascension (hours).

declination - Destination declination (degrees, positive north).

Returns:

Side of the pier on which the telescope would be on if a slew to the given equatorial coordinates is performed at the current instant of time. Can be NULL if the pointing state is unknown.

Throws:

RemoteException - Exception if an error occurred.

getSideOfPier

TelescopePierSide getSideOfPier(long telescopeId)
                                throws RemoteException

Returns the pointing state of the mount.

For historical reasons, this method's name does not reflect its true meaning. The name will not be changed (so as to preserve compatibility), but the meaning has since become clear. All conventional mounts have two pointing states for a given equatorial (sky) position. Mechanical limitations often make it impossible for the mount to position the optics at given HA/Dec in one of the two pointing states, but there are places where the same point can be reached sensibly in both pointing states (e.g. near the pole and close to the meridian). In order to understand these pointing states, consider the following (thanks to Patrick Wallace for this info):

All conventional telescope mounts have two axes nominally at right angles. For an equatorial, the longitude axis is mechanical hour angle and the latitude axis is mechanical declination. Sky coordinates and mechanical coordinates are two completely separate arenas. This becomes rather more obvious if your mount is an altaz, but it's still true for an equatorial. Both mount axes can in principle move over a range of 360 deg. This is distinct from sky HA/Dec, where Dec is limited to a 180 deg range (+90 to -90). Apart from practical limitations, any point in the sky can be seen in two mechanical orientations. To get from one to the other the HA axis is moved 180 deg and the Dec axis is moved through the pole a distance twice the sky codeclination (90 - sky declination).

Mechanical zero HA/Dec will be one of the two ways of pointing at the intersection of the celestial equator and the local meridian. Choose one, and move your scope there. Once you're there, consider the two mechanical encoders zeroed. The two pointing states are, then:

Normal	Where the mechanical Dec is in the range -90 deg to +90 deg
Beyond the pole	Where the mechanical Dec is in the range -180 deg to -90 deg or +90 deg to +180 deg.

"Side of pier" is a "consequence" of the former definition, not something fundamental. Apart from mechanical interference, the telescope can move from one side of the pier to the other without the mechanical Dec having changed: you could track Polaris forever with the telescope moving from west of pier to east of pier or vice versa every 12h. Thus, "side of pier" is, in general, not a useful term (except perhaps in a loose, descriptive, explanatory sense). All this applies to a fork mount just as much as to a GEM, and it would be wrong to make the "beyond pole" state illegal for the former. Your mount may not be able to get there if your camera hits the fork, but it's possible on some mounts. Whether this is useful depends on whether you're in Hawaii or Finland.

To first order, the relationship between sky and mechanical HA/Dec is as follows:

Normal state:

• HA_sky = HA_mech
• Dec_sky = Dec_mech

Beyond the pole:

• HA_sky = HA_mech + 12h, expressed in range ± 12h
• Dec_sky = 180d - Dec_mech, expressed in range ± 90d

Astronomy software often needs to know which which pointing state the mount is in. Examples include setting guiding polarities and calculating dome opening azimuth/altitude. The meaning of the getSideOfPier/setSideOfPier methods, then is:

EAST	Normal pointing state
WEST	Beyond the pole pointing state

If the mount hardware reports neither the true pointing state (or equivalent) nor the mechanical declination axis position (which varies from -180 to +180), a driver cannot calculate the pointing state, and *must not* implement SideOfPier. If the mount hardware reports only the mechanical declination axis position (-180 to +180) then a driver can calculate SideOfPier as follows:

• EAST = abs(mechanical dec) <= 90 deg
• WEST = abs(mechanical Dec) > 90 deg

It is allowed (though not required) that this method may be written to force the mount to flip. Doing so, however, may change the right ascension of the telescope. During flipping, isSlewing(long) must return TRUE.

Parameters:

telescopeId - Telescope identifier.

Returns:

Pointing state of the mount.

Throws:

RemoteException - Exception if an error occurred.

setSideOfPier

void setSideOfPier(long telescopeId,
                   TelescopePierSide sideOfPier)
                   throws RemoteException

Sets the pointing state of the mount.

For historical reasons, this method's name does not reflect its true meaning. The name will not be changed (so as to preserve compatibility), but the meaning has since become clear. All conventional mounts have two pointing states for a given equatorial (sky) position. Mechanical limitations often make it impossible for the mount to position the optics at given HA/Dec in one of the two pointing states, but there are places where the same point can be reached sensibly in both pointing states (e.g. near the pole and close to the meridian). In order to understand these pointing states, consider the following (thanks to Patrick Wallace for this info):

All conventional telescope mounts have two axes nominally at right angles. For an equatorial, the longitude axis is mechanical hour angle and the latitude axis is mechanical declination. Sky coordinates and mechanical coordinates are two completely separate arenas. This becomes rather more obvious if your mount is an altaz, but it's still true for an equatorial. Both mount axes can in principle move over a range of 360 deg. This is distinct from sky HA/Dec, where Dec is limited to a 180 deg range (+90 to -90). Apart from practical limitations, any point in the sky can be seen in two mechanical orientations. To get from one to the other the HA axis is moved 180 deg and the Dec axis is moved through the pole a distance twice the sky codeclination (90 - sky declination).

Mechanical zero HA/Dec will be one of the two ways of pointing at the intersection of the celestial equator and the local meridian. Choose one, and move your scope there. Once you're there, consider the two mechanical encoders zeroed. The two pointing states are, then:

Normal	Where the mechanical Dec is in the range -90 deg to +90 deg
Beyond the pole	Where the mechanical Dec is in the range -180 deg to -90 deg or +90 deg to +180 deg.

"Side of pier" is a "consequence" of the former definition, not something fundamental. Apart from mechanical interference, the telescope can move from one side of the pier to the other without the mechanical Dec having changed: you could track Polaris forever with the telescope moving from west of pier to east of pier or vice versa every 12h. Thus, "side of pier" is, in general, not a useful term (except perhaps in a loose, descriptive, explanatory sense). All this applies to a fork mount just as much as to a GEM, and it would be wrong to make the "beyond pole" state illegal for the former. Your mount may not be able to get there if your camera hits the fork, but it's possible on some mounts. Whether this is useful depends on whether you're in Hawaii or Finland.

To first order, the relationship between sky and mechanical HA/Dec is as follows:

Normal state:

• HA_sky = HA_mech
• Dec_sky = Dec_mech

Beyond the pole:

• HA_sky = HA_mech + 12h, expressed in range ± 12h
• Dec_sky = 180d - Dec_mech, expressed in range ± 90d

Astronomy software often needs to know which which pointing state the mount is in. Examples include setting guiding polarities and calculating dome opening azimuth/altitude. The meaning of the getSideOfPier/setSideOfPier methods, then is:

EAST	Normal pointing state
WEST	Beyond the pole pointing state

If the mount hardware reports neither the true pointing state (or equivalent) nor the mechanical declination axis position (which varies from -180 to +180), a driver cannot calculate the pointing state, and *must not* implement SideOfPier. If the mount hardware reports only the mechanical declination axis position (-180 to +180) then a driver can calculate SideOfPier as follows:

• EAST = abs(mechanical dec) <= 90 deg
• WEST = abs(mechanical Dec) > 90 deg

It is allowed (though not required) that this method may be written to force the mount to flip. Doing so, however, may change the right ascension of the telescope. During flipping, isSlewing(long) must return TRUE.

Parameters:

telescopeId - Telescope identifier.

sideOfPier - Pointing state of the mount.

Throws:

RemoteException - Exception if an error occurred.

getGuideRateRightAscension

double getGuideRateRightAscension(long telescopeId)
                                  throws RemoteException

Returns the current Right Ascension movement rate offset for telescope guiding.

This is the rate for both hardware/relay guiding and the pulseGuide(long, TelescopeGuideDirection, int) method.

• To discover whether this feature is supported, call the getCapabilities(long).canSetGuideRates() method.
• Mounts must start up with a known or default right ascension guide rate, and this value must return that known/default guide rate until changed.

Parameters:

telescopeId - Telescope identifier.

Returns:

Current Right Ascension movement rate offset in degrees/second (°/s).

Throws:

RemoteException - Exception if an error occurred.

setGuideRateRightAscension

void setGuideRateRightAscension(long telescopeId,
                                double guideRateRightAscension)
                                throws RemoteException

Sets the current Right Ascension movement rate offset for telescope guiding.

This is the rate for both hardware/relay guiding and the pulseGuide(long, TelescopeGuideDirection, int) method.

• To discover whether this feature is supported, call the getCapabilities(long).canSetGuideRates() method.
• The supported range of guideRateDeclination value is telescope specific, however, if this feature is supported, it can be expected that the range is sufficient to allow correction of guiding errors caused by moderate misalignment and periodic error.
• If a telescope does not support separate guiding rates in Right Ascension and Declination, then it is permissible for guideRateRightAscension and guideRateDeclination to be tied together. In this case, changing one of the two properties will cause a change in the other.

Parameters:

telescopeId - Telescope identifier.

guideRateRightAscension - New Right Ascension movement rate offset in degrees/second (°/s).

Throws:

RemoteException - Exception if an error occurred.

getGuideRateDeclination

double getGuideRateDeclination(long telescopeId)
                               throws RemoteException

Returns the current declination movement rate offset for telescope guiding.

This is the rate for both hardware/relay guiding and the pulseGuide(long, TelescopeGuideDirection, int) method.

• To discover whether this feature is supported, call the getCapabilities(long).canSetGuideRates() method.
• Mounts must start up with a known or default declination guide rate, and this value must return that known/default guide rate until changed.

Parameters:

telescopeId - Telescope identifier.

Returns:

Current declination movement rate offset in degrees/second (°/s).

Throws:

RemoteException - Exception if an error occurred.

setGuideRateDeclination

void setGuideRateDeclination(long telescopeId,
                             double guideRateDeclination)
                             throws RemoteException

Sets the current declination movement rate offset for telescope guiding.

This is the rate for both hardware/relay guiding and the pulseGuide(long, TelescopeGuideDirection, int) method.

• To discover whether this feature is supported, call the getCapabilities(long).canSetGuideRates() method.
• The supported range of guideRateDeclination value is telescope specific, however, if this feature is supported, it can be expected that the range is sufficient to allow correction of guiding errors caused by moderate misalignment and periodic error.
• If a telescope does not support separate guiding rates in Right Ascension and Declination, then it is permissible for guideRateRightAscension and guideRateDeclination to be tied together. In this case, changing one of the two properties will cause a change in the other.

Parameters:

telescopeId - Telescope identifier.

guideRateDeclination - New declination movement rate offset in degrees/second (°/s).

Throws:

RemoteException - Exception if an error occurred.

isPulseGuiding

boolean isPulseGuiding(long telescopeId)
                       throws RemoteException

Returns TRUE if a pulseGuide(long, TelescopeGuideDirection, int) command is in progress, FALSE otherwise.

Raises an error if the value of the getCapabilities(long).canPulseGuide() method return FALSE (the driver does not support the pulseGuide(long, TelescopeGuideDirection, int) method).

Parameters:

telescopeId - Telescope identifier.

Returns:

TRUE if a pulseGuide(long, TelescopeGuideDirection, int) command is in progress, FALSE otherwise.

Throws:

RemoteException - Exception if an error occurred.

pulseGuide

void pulseGuide(long telescopeId,
                TelescopeGuideDirection direction,
                int duration)
                throws RemoteException

Moves the scope in the given direction for the given interval or time at the rate given by the corresponding getGuideRateRightAscension(long) and getGuideRateDeclination(long) methods.

This method returns immediately if the hardware is capable of back-to-back moves, i.e. dual-axis moves. For hardware not having the dual-axis capability, the method returns only after the move has completed.

• Raises an error if isParked(long) is TRUE.
• The isPulseGuiding(long) method must be be TRUE during pulse-guiding.
• The rate of motion for movements about the right ascension axis is specified by the getGuideRateRightAscension(long) method. The rate of motion for movements about the declination axis is specified by the getGuideRateDeclination(long) method. These two rates may be tied together into a single rate, depending on the driver's implementation and the capabilities of the telescope.

Parameters:

telescopeId - Telescope identifier.

direction - Direction in which the guide-rate motion is to be made.

duration - Duration of the guide-rate motion (milliseconds).

Throws:

RemoteException - Exception if an error occurred.

isDoesRefraction

boolean isDoesRefraction(long telescopeId)
                         throws RemoteException

Returns TRUE if the telescope or driver applies atmospheric refraction to coordinates.

If this returned value is TRUE, the coordinates sent to, and retrieved from, the telescope are unrefracted.

• If the driver does not know whether the attached telescope does its own refraction, and if the driver does not itself calculate refraction, this method (if implemented) must raise an error when call.

Parameters:

telescopeId - Telescope identifier.

Returns:

TRUE if the telescope or driver applies atmospheric refraction to coordinates.

Throws:

RemoteException - Exception if an error occurred.

setDoesRefraction

void setDoesRefraction(long telescopeId,
                       boolean doesRefraction)
                       throws RemoteException

Sets TRUE if the telescope or driver applies atmospheric refraction to coordinates.

If this doesRefraction value is TRUE, the coordinates sent to, and retrieved from, the telescope are unrefracted.

• Using to this method is optional. Often, a telescope (or its driver) calculates refraction using standard atmospheric parameters.
• If the client wishes to calculate a more accurate refraction, then this method could be set to FALSE and these client-refracted coordinates used.
• If disabling the telescope or driver's refraction is not supported, the driver must raise an error when an attempt to call this method with a doesRefraction = FALSE.
• Setting doesRefraction to TRUE for a telescope or driver that does refraction, or to FALSE for a telescope or driver that does not do refraction, shall not raise an error. It shall have no effect.

Parameters:

telescopeId - Telescope identifier.

doesRefraction - TRUE if the telescope or driver applies atmospheric refraction to coordinates.

Throws:

RemoteException - Exception if an error occurred.

getSiteElevation

double getSiteElevation(long telescopeId)
                        throws RemoteException

Returns the elevation above mean sea level of the site at which the telescope is located.

Parameters:

telescopeId - Telescope identifier.

Returns:

Elevation above mean sea level in meters (m).

Throws:

RemoteException

setSiteElevation

void setSiteElevation(long telescopeId,
                      double elevation)
                      throws RemoteException

Sets the elevation above mean sea level of the site at which the telescope is located.

Call this method will raise an error if the given value is outside the range -300 through +10000 meters.

Parameters:

telescopeId - Telescope identifier.

elevation - Elevation above mean sea level in meters (m).

Throws:

RemoteException

getSiteLatitude

double getSiteLatitude(long telescopeId)
                       throws RemoteException

Returns the geodetic(map) latitude of the site at which the telescope is located.

Parameters:

telescopeId - Telescope identifier.

Returns:

Geodetic(map) latitude of the observing site (degrees, positive North, WGS84).

Throws:

RemoteException

setSiteLatitude

void setSiteLatitude(long telescopeId,
                     double latitude)
                     throws RemoteException

Sets the geodetic(map) latitude of the site at which the telescope is located.

Call this method will raise an error if the given value is outside the range -90 to +90 degrees.

Parameters:

telescopeId - Telescope identifier.

latitude - Geodetic(map) latitude of the observing site (degrees, positive North, WGS84).

Throws:

RemoteException

getSiteLongitude

double getSiteLongitude(long telescopeId)
                        throws RemoteException

Returns the longitude of the site at which the telescope is located.

Note that West is negative.

Parameters:

telescopeId - Telescope identifier.

Returns:

Longitude of the observing site (degrees, positive East, WGS84).

Throws:

RemoteException

setSiteLongitude

void setSiteLongitude(long telescopeId,
                      double longitude)
                      throws RemoteException

Sets the longitude of the site at which the telescope is located.

Call this method will raise an error if the given value is outside the range -180 to +180 degrees.

Note that West is negative.

Parameters:

telescopeId - Telescope identifier.

longitude - Longitude of the observing site (degrees, positive East, WGS84).

Throws:

RemoteException

getUtcDate

TimeSynchronization getUtcDate(long telescopeId,
                               long clientTransmitTime)
                               throws RemoteException

Returns the synchronization of UTC date/time of the telescope's internal clock.

The driver must calculate this from the system clock if the telescope has no accessible source of UTC time.

Calling this method will raise an error if the value has never been set or is otherwise unavailable.

Parameters:

telescopeId - Telescope identifier.

clientTransmitTime - Transmission UTC date/time of the request by the client.

Returns:

Object containing all informations used for UTC date/time synchronization.

Throws:

RemoteException - Exception if an error occurred.

setUtcDate

void setUtcDate(long telescopeId,
                long timeOffset)
                throws RemoteException

Changes the UTC date/time of the telescope's internal clock.

This method will raise an error if the telescope has no accessible source of UTC time.

However, it is permitted to change the telescope's internal UTC clock if it is being used. This allows clients to adjust the telescope's UTC clock as needed for accuracy.

Parameters:

telescopeId - Telescope identifier.

timeOffset - UTC date/time offset between the client and the server.

Throws:

RemoteException - Exception if an error occurred.

getSiderealTime

TimeSynchronization getSiderealTime(long telescopeId,
                                    long clientTransmitTime)
                                    throws RemoteException

Returns the synchronization of local apparent sidereal time from the telescope's internal clock (nanoseconds, sidereal).

It is required for a driver to calculate this from the system clock if the telescope has no accessible source of sidereal time. Local Apparent Sidereal Time is the sidereal time used for pointing telescopes, and thus must be calculated from the Greenwich Mean Sidereal time, longitude, nutation in longitude and true ecliptic obliquity.

Parameters:

telescopeId - Telescope identifier.

clientTransmitTime - Transmission sidereal time of the request by the client.

Returns:

Object containing all informations used for sidereal time synchronization.

Throws:

RemoteException - Exception if an error occurred.