Xyd and Xxy
Prev		Next

Programming - Controlling the Daemon with User Software

Examples

Ask the person who installed xyd where the software has been installed (normally /usr/local or ~yamada).

It should be possible to learn to do simple control functions just by using the examples.

The source code for the examples can also be found in the examples directory, though an appropriate system-specific Makefile cannot be provided here.

Common Features

All functions described here will return a status code (which will be negative if there is an error). If the command completed correctly, the status code will be a zero.

If there is an error, then the global character array xy_cmd_err_msg will contain an error message (a zero-terminated character array).

Positive status codes indicate that the command requires special processing. The only positive status code that normal code is likely to recieve is XYERR_PENDING. Only commands that require you to pass in an id (a pointer to an integer variable) will return XYERR_PENDING. If the status code is XYERR_PENDING, then the application code should use the returned id and call xy_cmd_wait(). This will allow the command to complete and return a status code to indicate proper completion.

Unless otherwise stated, all of these functions treat a 0 value as "TRUE" or "set" and a non-0 values as "FALSE" or "unset".

Special Functions

The functions in this section are all rather special, and do not follow the rules that the other functions do.

int xy_cmd_connect(const char host[], int port);

This function is used to connect to the xy daemon. It accepts the name of the host that is running the daemon and the port that the daemon is listening on. If the host is NULL, then a default host that was compiled at the time that the library was built will be used. If the port is 0, then a default port that was compiled at the time that the library was built will be used.

This function returns a file descriptor which all of the other functions require for connecting to the daemon. If there is a problem, then a negative value will be returned.

int xy_cmd_disconnect(int fd);

This function is used to disconnect from the xy daemon. It requires a file descriptor (obtained from xy_cmd_connect()).

int xy_cmd_wait(int fd, int id);

This function waits for an operation to complete. It expects a file descriptor, obtained from xy_cmd_connect. It also expects an id, which is obtained from every command that takes time to complete. It returns an error code which describes the status of specified operation.

If an asynchronous message arrives while xy_cmd_wait() is waiting for a result, it will call the appropriate handler.

int xy_cmd_check_async(int fd);

This function checks if an asynchronous message has arrived. If an asynchronous message has arrived, it calls the appropriate handler.

General-Purpose Functions

The functions in this section all behave similarly. They expect a file descriptor (obtained from xy_cmd_connect()) as their first argument. Following that are a mixture of integers, doubles, and zero-terminated character arrays (strings). These are parameters that will be passed to the daemon. Following those parameters are a mixture of pointers to integers, pointers to doubles, and strings, which receive data from the daemon. The character arrays consist of a character array (pointer to character) followed by an integer. The integer must contain the size of the character array.

All of these functions return an integer status code. A negative value indicates an error. A 0 value indicates success. A value of 1 indicates that the operation was successfully started, but will not be completed until later. (Completion can be checked using the cmd_wait() function.) More details about the return codes can be found in src/xyerr.h.

int xy_cmd_do_auth(int fd);

The user-authentication system is currently not enabled. There is no need to use this function.

int xy_cmd_do_cancel(int fd);

This command cancels a xy_cmd_do_movexy() , xy_cmd_do_moverelxy() , xy_cmd_do_moverd() , xy_cmd_do_moverelrd() , xy_cmd_do_reset() , or xy_cmd_do_monitorreset() command.

Warning

This command cannot actually stop the hardware from rebooting. It only stops the daemon from constantly monitoring the reboot.

int xy_cmd_do_die(int fd);

This commands shuts down the daemon immediately. This command brings down the daemon, regardless of the current state of the daemon. If it is necessary, to shut down the daemon, it is normally better to use shutdown instead. This command is only for use when shutdown fails (e.g., if the daemon is busy, and cannot be interrupted).

Warning

Normal users should never need to shut down the daemon.

int xy_cmd_do_download(int fd);

Download a new boot program to the Galil hardware.

Warning

Only the system maintainer should download a boot program.

int xy_cmd_do_endtrack(int fd);

Stops tracking (non-sidereal guiding).

int xy_cmd_do_fail(int fd, int *id);

This command for debugging purposes only. It always fails and generates an error.

int xy_cmd_do_focus(int fd, double duration, int *id);

Adjusts the focus by a relative amount. duration is the amount of time that the motors should be enabled. Negative values of duration move the focus in the reverse direction.

The focus is not encoded, so positioning is only approximate. The end of travel is not detected.

int xy_cmd_do_galilconnect(int fd, int *id);

Force the daemon to connect to the hardware.

Warning

The daemon normally connects automatically. The only time that it will not connect automatically, is if the terminal server is rebooted or if the user explicitly uses xy_cmd_do_galildisconnect() .

int xy_cmd_do_galildisconnect(int fd, int *id);

Force the daemon to disconnect from the hardware.

Warning

The only time that the daemon should be disconnected is for system maintenance.

int xy_cmd_do_getasync(int fd, int *async);

Get the current state of the asynchronous mode flag.

int xy_cmd_do_getbusy(int fd, int *id);

Get the state of the busy flag. The busy flag is set whenever the daemon is performing an operation that does not complete immediately.

int xy_cmd_do_getinit0(int fd, const char init0[], int init0_size);

Get the state of the init0 flag. The init0 flag indicates the state of the Galil hardware. If it is DONE then all initialization completed successfully. If it is FAIL then initialization failed. If it is anything else, then initialization is still in progress.

Note that this command only returns the last known value of the init0 flag. Use xy_cmd_do_monitorreset() or xy_cmd_do_readinit0() to force the system to read the flag (normally not necessary unless the hardware has been rebooted). The xy_cmd_do_reset() command always monitors the reboot.

int xy_cmd_do_getaction(int fd, const char action[], int action_size);

This command returns a string that is set whenever the daemon is performing an operation that takes a long time to complete (such as moving or focusing). The string provides a brief description of the operation.

int xy_cmd_do_getnaxes(int fd, int *naxes);

This command returns the number of axes that is supported by the controller.

int xy_cmd_do_getrd(int fd, double *ra, double *dec);

This command returns the current position of the xy stage, in the current relative R.A. and Dec coordinates.

It is generally wise to call xy_cmd_do_readrotang() before invoking this function.

int xy_cmd_do_getrotang(int fd, double *rotang);

Get the daemon's current value of the rotator angle.

int xy_cmd_do_getscale(int fd, int *scaleid, double *scalefactor, const char scaledescr[], int scaledescr_size);

Get the current scale factor that is used to convert from R.A. and Dec offsets to encoder units.

scaleid is the index which identifies the currently active scale factor (0-9).

scalefactor is the numeric value of the scale factor.

scaledescr is a text description of the scale factor.

int xy_cmd_do_getscaleinfo(int fd, int ind, int *scaleid, double *scalefactor, const char scaledescr[], int scaledescr_size);

Get the information for the specified scale factor.

ind is the index of the desired scale factor.

scaleid is the index which identifies the currently active scale factor (0-9). (This should be identical to ind. It is provided as a convenience, so that xy_cmd_do_getscale() and xy_cmd_do_getscaleinfo() provide identical data.)

scalefactor is the numeric value of the scale factor.

scaledescr is a text description of the scale factor.

int xy_cmd_do_getswitches(int fd, int *swx, int *swy, const char swxstr[], int swxstr_size, const char swystr[], int swystr_size);

Get the current value of the Galil hardware switches.

swx and swy return the numeric values of the switches.

swxstr and swystr return a text equivalent of the switches that is intended to be slightly more readable for humans.

int xy_cmd_do_gettracking(int fd, int *tracking);

Get the current state of the tracking flag.

The tracking flag is set whenever the system is tracking (non-sidereal guiding).

int xy_cmd_do_gettrackrate(int fd, double *rarate, double *decrate);

Get the current value of the rate variables for tracking (non-sidereal guiding).

int xy_cmd_do_getversion(int fd, const char version[], int version_size);

Get the current version of the Galil hardware.

int xy_cmd_do_getxy(int fd, int *x, int *y);

Gets the position of the xy stage in encoder units.

int xy_cmd_do_gread(int fd, const char parm[], int *id);

Updates the current value of a Galil hardware parameter.

The following parameters are supported: speed, accel (acceleration/deceleration), errlim (error limit), integ (integration servo parameters), gain (servo gain).

Note that this command only modifies the internal state of the daemon, and does not return the current value.

int xy_cmd_do_gget(int fd, const char parm[], int *xval, int *yval);

Gets the current value of a Galil hardware parameter.

The parameters are the same as are listed for gread.

int xy_cmd_do_gset(int fd, const char parm[], int xval, int yval, int *id);

Sets the current value of a Galil hardware parameter.

The parameters are the same as are listed for gread.

int xy_cmd_do_monitorreset(int fd, int *id);

If the hardware is currently resetting, continuously check the state of the INIT0 flag.

int xy_cmd_do_moverd(int fd, double ra, double dec, int *id);

Move the xy stage, using R.A. and Dec offsets relative to the origin of the xy stage.

It is generally a good idea to use xy_cmd_do_readrotang() before calling xy_cmd_do_moverd() .

int xy_cmd_do_moverelrd(int fd, double ra, double dec, int *id);

Move the xy stage, using R.A. and Dec offsets, relative to the current position.

It is generally a good idea to use xy_cmd_do_readrotang() before calling xy_cmd_do_moverelrd() .

int xy_cmd_do_moverelxy(int fd, int x, int y, int *id);

Move the xy stage, using encoder units, relative to the current position.

int xy_cmd_do_movexy(int fd, int x, int y, int *id);

Not written.

int xy_cmd_do_readback(int fd, int *id);

Read back the current Galil start up code.

This is primarily used to verify that download worked correctly. It should not necessary to use it for any other purpose.

int xy_cmd_do_readinit0(int fd, int *id);

Updates the current value of the init0 flag.

This command does not return a value to the user. It only updates the internal state of the daemon. Use xy_cmd_do_getinit0() to get the value of the init0 flag.

int xy_cmd_do_readrd(int fd, int *id);

This is identical to the xy_cmd_do_readxy() command, and is provided only for completeness.

int xy_cmd_do_readrotang(int fd, int *id);

Read the current rotator angle from the TCS controller.

int xy_cmd_do_readswitches(int fd, int *id);

Read the current values of the Galil hardware switches.

int xy_cmd_do_readxy(int fd, int *id);

Force the daemon to re-read the position of the x and y axes from the hardware. Note that under normal circumstances, this is not necessary, because the daemon keeps track of when the x and y axes are changed. This command only updates the internal state of the daemon, and does not return the value to the user. To get the current value, use getxy.

int xy_cmd_do_reset(int fd, int *id);

Force a Galil hardware reset and monitor the init0 variable until the reset completes.

int xy_cmd_do_setasync(int fd, int async);

Sets the value of the asynchronous mode flag.

int xy_cmd_do_setrotang(int fd, double rotang);

Manually set the value of the rotator angle.

int xy_cmd_do_setscale(int fd, int scaleid);

Select one of the scale factors (0-9). Use xy_cmd_do_getscaleinfo() to get a description of the available scale factors.

int xy_cmd_do_settrackrate(int fd, double rarate, double decrate);

Set the R.A. and Dec offset rates (marcsec / s)

int xy_cmd_do_shutdown(int fd);

This commands shuts down the daemon, after verifying that the daemon is in an idle state (i.e., that no mechanisms are moving).

Warning

Normal users should never need to shut down the daemon.

int xy_cmd_do_track(int fd, int *id);

Start tracking (non-sidereal guiding).

It is generally a good idea to use xy_cmd_do_readrotang() before calling xy_cmd_do_track() .

Asynchronous messages

Normally, the daemon does not send an messages back except in response to a user command. The user can request that the messages be sent when an internal variable of the daemon changes or when an operation completes. This is called "asynchronous mode", and is set by the xy_cmd_do_func_setasync() function.

The user may assign values to the following global pointers-to-functions: xy_cmd_done_handler and xy_cmd_update_handler. The user may also assign values to the following global pointers-to-arbitrary-data: xy_cmd_done_arg and xy_cmd_update_arg.

When asynchronous mode is enabled, and a message arrives while or before xy_cmd_wait() is invoked or before xy_cmd_do_get_async() is invoked, then the function (*xy_cmd_done_handler)() or (*xy_cmd_update_handler)() will be called. xy_cmd_done_arg or xy_cmd_update_arg will be passed as the first argument. The remaining arguments are an integer, which contains the number of words in the asynchronous message and an array of pointers-to-characters which contains the words of the message.

For reference purposes, the definitions of the functions are provided here (though for programming, they are better obtained from src/xycmd.h.)

	extern void (*xy_cmd_done_handler)(void *, int, char *[]);
	extern void *xy_cmd_done_arg;
	extern void (*xy_cmd_update_handler)(void *, int, char *[]);
	extern void *xy_cmd_update_arg;

Prev	Home	Next
Tcl Interface		xyd - Network Interface