org.minetti.astrodevice.common.orb
Interface DeviceOrbProcess

All Known Subinterfaces:

CameraOrbProcess, DomeOrbProcess, FilterWheelOrbProcess, FocuserOrbProcess, RotatorOrbProcess, SafetyMonitorOrbProcess, TelescopeOrbProcess

public interface DeviceOrbProcess

Abstract ORB process on:

• telescopes,
• cameras,
• filter wheels,
• focusers,
• rotators,
• domes,
• safety monitors.

Author:

Jean-Philippe MINETTI

Method Summary

String	action(long telescopeId, String name, String parameters) Invokes the specified device-specific action.
void	commandBlind(long telescopeId, String command, boolean raw) Transmits an arbitrary string to the device and does not wait for a response.
boolean	commandBoolean(long telescopeId, String command, boolean raw) Transmits an arbitrary string to the device and waits for a boolean response.
String	commandString(long telescopeId, String command, boolean raw) Transmits an arbitrary string to the device and waits for a string response.
String	getDescription(long telescopeId) Returns a description of the driver, such as manufacturer and model number.
List<Entity>	getDeviceList() Returns connected devices as entity list.
String	getDeviceName(Locale locale, long deviceId) Returns the name given to device.
String	getDriverInfo() Returns a descriptive and version information about AstroDevice Server.
String	getDriverVersion() Returns a string containing only the major and minor version of the AstroDevice Server.
short	getInterfaceVersion() Returns the AstroDevice protocol version number that this device supports.
String	getPluginName(Locale locale, long deviceId) Returns the name given to astroDeviceServer plug-in responsible for managing the device.
List<String>	getSupportedActions(long telescopeId) Returns the list of action names supported by this driver.
boolean	isConnected(long telescopeId) Checks whether the device is connected.
void	setConnected(long telescopeId, boolean connected) Sets TRUE to connect to the device.
void	showSetupDialog(long telescopeId) Launches a configuration dialog box for the driver.

Method Detail

getPluginName

String getPluginName(Locale locale,
                     long deviceId)
                     throws RemoteException

Returns the name given to astroDeviceServer plug-in responsible for managing the device.

Parameters:

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

deviceId - Device identifier.

Returns:

Name given to astroDeviceServer plug-in.

Throws:

RemoteException - Exception if an error occurred.

getDeviceName

String getDeviceName(Locale locale,
                     long deviceId)
                     throws RemoteException

Returns the name given to device.

Parameters:

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

deviceId - Device identifier.

Returns:

Name given to device.

Throws:

RemoteException - Exception if an error occurred.

getDriverInfo

String getDriverInfo()
                     throws RemoteException

Returns a descriptive and version information about AstroDevice Server.

This string may contain line endings and may be hundreds to thousands of characters long. It is intended to display detailed information on the AstroDevice Server, including version and copyright data. See the getDescription(long) method for information on the telescope itself. To get the driver version in a parseable string, use the getDriverVersion() method.

Returns:

Descriptive and version information about AstroDevice Server.

Throws:

RemoteException - Exception if an error occurred.

getDriverVersion

String getDriverVersion()
                        throws RemoteException

Returns a string containing only the major and minor version of the AstroDevice Server.

This must be in the form "n.n". It should not to be confused with the getInterfaceVersion() method, which is the version of this specification supported by the server.

Returns:

String containing only the major and minor version of the AstroDevice Server.

Throws:

RemoteException - Exception if an error occurred.

getInterfaceVersion

short getInterfaceVersion()
                          throws RemoteException

Returns the AstroDevice protocol version number that this device supports.

Clients can detect legacy V1 drivers by trying to call this method. If the driver raises an error, it is a V1 driver. V1 did not specify this return value. A driver may also return a value of 1. In other words, a raised error or a return value of 1 indicates that the driver is a V1 driver.

Returns:

AstroDevice protocol version number.

Throws:

RemoteException - Exception if an error occurred.

getDeviceList

List<Entity> getDeviceList()
                           throws RemoteException

Returns connected devices as entity list.

Returns:

Connected devices as entity list.

Throws:

RemoteException - Exception if an error occurred.

getDescription

String getDescription(long telescopeId)
                      throws RemoteException

Returns a description of the driver, such as manufacturer and model number. Any ASCII characters may be used.

Parameters:

telescopeId - Telescope identifier.

Returns:

Description of the driver.

Throws:

RemoteException - Exception if an error occurred.

DriverException - Must throw an exception if description unavailable.

showSetupDialog

void showSetupDialog(long telescopeId)
                     throws RemoteException

Launches a configuration dialog box for the driver. The call will not return until the user clicks OK or cancel manually.

Parameters:

telescopeId - Telescope identifier.

Throws:

RemoteException - Exception if an error occurred.

MethodNotImplementedException - Must throw an exception if setup dialog is unavailable.

isConnected

boolean isConnected(long telescopeId)
                    throws RemoteException

Checks whether the device is connected. Set True to connect to the device. Set False to disconnect from the device. You can also call the method to check whether the device is connected.

Parameters:

telescopeId - Telescope identifier.

Returns:

TRUE if the device is connected and FALSE if the device is disconnected.

Throws:

RemoteException - Exception if an error occurred.

DriverException - Must throw exception if unsuccessful.

setConnected

void setConnected(long telescopeId,
                  boolean connected)
                  throws RemoteException

Sets TRUE to connect to the device. Sets FALSE to disconnect from the device.

Parameters:

telescopeId - Telescope identifier.

connected - TRUE if for connect the device and FALSE for disconnect the device.

Throws:

RemoteException - Exception if an error occurred.

DriverException - Must throw exception if unsuccessful.

commandBlind

void commandBlind(long telescopeId,
                  String command,
                  boolean raw)
                  throws RemoteException

Transmits an arbitrary string to the device and does not wait for a response. Optionally, protocol framing characters may be added to the string before transmission.

Parameters:

telescopeId - Telescope identifier.

command - Literal command string to be transmitted.

raw - If set to TRUE the string is transmitted 'as-is'. If set to FALSE then protocol framing characters may be added prior to transmission.

Throws:

RemoteException - Exception if an error occurred.

commandBoolean

boolean commandBoolean(long telescopeId,
                       String command,
                       boolean raw)
                       throws RemoteException

Transmits an arbitrary string to the device and waits for a boolean response. Optionally, protocol framing characters may be added to the string before transmission.

Parameters:

telescopeId - Telescope identifier.

command - Literal command string to be transmitted.

raw - If set to TRUE the string is transmitted 'as-is'. If set to FALSE then protocol framing characters may be added prior to transmission.

Returns:

Boolean response received from the device.

Throws:

RemoteException - Exception if an error occurred.

commandString

String commandString(long telescopeId,
                     String command,
                     boolean raw)
                     throws RemoteException

Transmits an arbitrary string to the device and waits for a string response. Optionally, protocol framing characters may be added to the string before transmission.

Parameters:

telescopeId - Telescope identifier.

command - Literal command string to be transmitted.

raw - If set to TRUE the string is transmitted 'as-is'. If set to FALSE then protocol framing characters may be added prior to transmission.

Returns:

String response received from the device.

Throws:

RemoteException - Exception if an error occurred.

action

String action(long telescopeId,
              String name,
              String parameters)
              throws RemoteException

Invokes the specified device-specific action. The names of all supported actions must be returned in the getSupportedActions method.

This method is intended for use in all current and future device types and to avoid name clashes, management of action names is important from day 1. A two-part naming convention will be adopted - DeviceType:UniqueActionName where:

• deviceType is the same value as would be used by getDeviceType() e.g. Telescope, Camera, Switch etc.
• UniqueActionName is a single word, or multiple words joined by underscore characters, that sensibly describes the action to be performed.

It is recommended that UniqueActionNames should be a maximum of 16 characters for legibility. Should the same function and UniqueActionName be supported by more than one type of device, the reserved DeviceType of “General” will be used. Action names will be case insensitive, so FilterWheel:SelectWheel, filterwheel:selectwheel and FILTERWHEEL:SELECTWHEEL will all refer to the same action.

The names of all supported actions must bre returned in the getSupportedActions(long) method.

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

Parameters:

telescopeId - Telescope identifier.

name - A well known name agreed by interested parties that represents the action to be carried out.

parameters - List of required parameters or NULL value if none are required.

Returns:

Result value (the meaning of result value is set by the driver author).

Throws:

RemoteException - Exception if an error occurred.

MethodNotImplementedException - Throws this exception if no actions are suported.

ActionNotImplementedException - It is intended that the getSupportedActions(long) method will inform clients of driver capabilities, but the driver must still throw an ASCOM.ActionNotImplemented exception if it is asked to perform an action that it does not support.

getSupportedActions

List<String> getSupportedActions(long telescopeId)
                                 throws RemoteException

Returns the list of action names supported by this driver.

This method must return an empty list if no actions are supported. Please do not throw a PropertyNotImplementedException.

This is an aid to client authors and testers who would otherwise have to repeatedly poll the driver to determine its capabilities. Returned action names may be in mixed case to enhance presentation but will be recognised case insensitively in the action(long, String, String) method.

An array list collection has been selected as the vehicle for action names in order to make it easier for clients to determine whether a particular action is supported. Since the collection is also ennumerable it is easy to use constructs such as For Each ... to operate on members without having to be concerned about how many members are in the collection.

Parameters:

telescopeId - Telescope identifier.

Returns:

List of action names supported by this driver.

Throws:

RemoteException - Exception if an error occurred.