commands.h File Reference

Client application command tree header file. More...

Go to the source code of this file.

Data Structures
struct	Commands
	Client command action function data structure. More...
Defines
#define	CMD_OK   0
	Command executed OK, return completion status.
#define	CMD_ERR   -1
	Command execution resulted in an error.
#define	CMD_NOOP   1
	Command execution requires no further action (no-op).
Functions
int	cmd_quit (char *, MsgType, char *)
	QUIT command - terminate the client session.
int	cmd_ping (char *, MsgType, char *)
	PING command - communication handshaking request.
int	cmd_pong (char *, MsgType, char *)
	PONG command - communication handshaking acknowledgment.
int	cmd_info (char *, MsgType, char *)
	INFO command - report client application runtime information.
int	cmd_version (char *, MsgType, char *)
	VERSION command - report application version and compilation info.
int	cmd_verbose (char *, MsgType, char *)
	VERBOSE command - toggle verbose console output on/off.
int	cmd_debug (char *, MsgType, char *)
	DEBUG command - toggle debugging (super-verbose) console output on/off.
int	cmd_help (char *, MsgType, char *)
	HELP command - print a list of commands on the client console.
int	cmd_history (char *, MsgType, char *)
	HISTORY command - show the application's interactive command history.
int	cmd_ports (char *, MsgType, char *)
	PORTS command - report info about open mechanism comm comm ports.
int	cmd_rdpos (char *, MsgType, char *)
	RDPOS command - read filter wheel position encoders.
int	cmd_setcur (char *, MsgType, char *)
	CURRENT command - set/query drive current in Amps.
int	cmd_setsp (char *, MsgType, char *)
	SPEED command - set/query drive speed in rev/sec.
int	cmd_setacc (char *, MsgType, char *)
	ACCEL command - set/query move acceleration in rev/sec/sec.
int	cmd_setdec (char *, MsgType, char *)
	DECEL command - set/query move deceleration in rev/sec/sec.
int	cmd_setstep (char *, MsgType, char *)
	STEPS command - set/query the steps/position in steps.
int	cmd_setto (char *, MsgType, char *)
	TIMEOUT command - set/query the communication timeout interval in seconds.
int	cmd_mstatus (char *, MsgType, char *)
	MSTATUS command - report detailed microstep drive status.
int	cmd_idle (char *, MsgType, char *)
	IDLE command - enable/disable the microstep drive idle current.
int	cmd_send (char *, MsgType, char *)
	SEND command - send a raw command to microstep drive.
int	cmd_query (char *, MsgType, char *)
	QUERY command - send a raw device query to the microstep drive.
int	cmd_reset (char *, MsgType, char *)
	RESET command - reload the runtime config paramters and re-initialize the microstep drive.
int	cmd_init (char *, MsgType, char *)
	INIT command - (re)initialize the microstep drive.
int	cmd_abort (char *, MsgType, char *)
	ABORT command - abort a move in progress.
int	cmd_fpars (char *, MsgType, char *)
	FPARS command - report detailed filter wheel parameters.
int	cmd_status (char *, MsgType, char *)
	STATUS command - report client status.
int	cmd_filter (char *, MsgType, char *)
	FILTER command - move filter n into the beam.
int	cmd_load (char *, MsgType, char *)
	LOAD command - move filter n into the filter wheel's load port.
int	cmd_findpos (char *, MsgType, char *)
	FINDPOS command - seek the nearest valid filter position.
Variables
Commands	cmdtab []
	Client command action function data structure.
int	NumCommands = sizeof(cmdtab)/sizeof(struct Commands)
	number of commands defined

---

Detailed Description

Client application command tree header file.

To add a command, you need to

1. Add a command action function prototype to the code below
2. Add the command verb and its function call to the cmdtab struct

See commands.c for the full implementation details.

---

Define Documentation

#define CMD_OK   0

Command executed OK, return completion status.

#define CMD_ERR   -1

Command execution resulted in an error.

#define CMD_NOOP   1

Command execution requires no further action (no-op).

---

Function Documentation

int cmd_quit (  char *  args, MsgType  msgtype, char *  reply )

QUIT command - terminate the client session. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK if command executed without errors, CMD_ERR if an error occurred. On errors reply contains the error message. Executes the application QUIT command. Only works if msgtype=EXEC, indicating that it is an IMPv2 executive command. This prevents remote applications from prematurely terminating this application by sending a QUIT command unqualified by the EXEC: directive.

int cmd_ping (  char *  args, MsgType  msgtype, char *  reply )

PING command - communication handshaking request. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK if command executed without errors, CMD_ERR if an error occurred. On errors reply contains the error message. This function is invoked when the client application receives a PING from a remote host requesting a communications handshaking reply. PINGs are actually handled separately in the SocketCommand() handler (nothing is done by the KeyboardCommand() handler) because the PONG sent back acknowledging the comm handshaking request is, in effect, a pseudo-command (implicit REQ:), not a "DONE:" response to a command request. This exception to the general messaging syntax has to be handled carefully to prevent problems, especially to ensure backwards compatibility with older IMPv applications. See also: cmd_pong

int cmd_pong (  char *  args, MsgType  msgtype, char *  reply )

PONG command - communication handshaking acknowledgment. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_NOOP since PONG is a no-op pseudo command. For historical reasons, a "PONG" sent in acknowledgment of a software handshaking "PING" looks like an implicit REQ:, and hence like a "command request" sent to the recipient, even though it isn't. It is, however, an exception to the strict messaging protocol, which is why it needs a separate handler. cmd_pong doesn't do anything except return a CMD_NOOP (since this "command" must NOT result in a reply back to the sender). In more sophisticated apps, we might actually use receipt of a pong to do something useful (e.g., help build up a node table), so at the very least this module works as a placeholder for future expansion. See also: cmd_ping

int cmd_info (  char *  args, MsgType  msgtype, char *  reply )

INFO command - report client application runtime information. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on successful creation of the info report, CMD_ERR if errors encountered. cmd_info creates a summary report of the current client application's runtime configuration as an IMPv2-compliant message string in which the runtime parameters are reported as keyword=value pairs. The format of cmd_info should be tailored specifically for the particular client application. If a client controls specific instrument or interface functions, the state of those functions should be reported in the info string, making it an omnibus "what is your status" command.

int cmd_version (  char *  args, MsgType  msgtype, char *  reply )

VERSION command - report application version and compilation info. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK Loads an IMPv2 message into the reply string with the version number and any relevant compilation information (e.g., date and time of compilation). VERSION allows a way for users or remote apps to verify the runtime version of the current application.

int cmd_verbose (  char *  args, MsgType  msgtype, char *  reply )

VERBOSE command - toggle verbose console output on/off. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK Sets the client isVerbose flag to 1 (enabled) if currently 0 (disabled) and vis-versa. Verbose output mode is used for basic client debugging information by printing extra information on the application console screen. Disabling throttles verbose console output. VERBOSE mode is normally disabled during normal operations. In general "Verbose" output refers only to client application level output (i.e., echoing socket message traffic, printing status update info, etc.). An more chatty DEBUG mode is provided that prints more engineering-level info for detailed low-level system debugging. See also: cmd_debug

int cmd_debug (  char *  args, MsgType  msgtype, char *  reply )

DEBUG command - toggle debugging (super-verbose) console output on/off. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK Sets the client Debug flag to 1 (enabled) if currently 0 (disabled) and vis-versa. May also set mechanism-level debug flags as well. DEBUG mode is a super-verbose mode that spews lots of I/O chatter onto the application console, useful during client debugging or for troubleshooting. For example, in client applications that control stepper motors, the full motor control chatter is echoed to the console during DEBUG mode to enable the user to follow the steps the system is (or is not) taking, watch encoder and limit switches assert (or not), etc. DEBUG is normally disabled during normal user operations. See also: cmd_verbose

int cmd_help (  char *  args, MsgType  msgtype, char *  reply )

HELP command - print a list of commands on the client console. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_NOOP on success, CMD_ERR if help executed as a non-EXEC: command cmd_help is usually invoked by the HELP or ? commands. It prints a list of all interactive commands on the client application's console screen. It is only meant to be executed as an EXEC: message type. If the command is not qualifed as EXEC:, it returns an error.

int cmd_history (  char *  args, MsgType  msgtype, char *  reply )

HISTORY command - show the application's interactive command history. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_NOOP on success, CMD_ERR if history executed as a non-EXEC: command Report the application's interactive command history on the console. The KeyboardCommand() function uses the GNU readline and history system to record all commands entered. This prints a list of the most recent commands. See also: KeyboardCommand()

int cmd_ports (  char *  args, MsgType  msgtype, char *  reply )

PORTS command - report info about open mechanism comm comm ports. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Report information about all mechanism comm ports connected to the client in IMPv2-compliant format. Shows their status as follows: FWPort=/dev/ttyS0 PortStatus=Open

int cmd_rdpos (  char *  args, MsgType  msgtype, char *  reply )

RDPOS command - read filter wheel position encoders. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Queries the microstep controller and reads the filter wheel position encoders (8 input bits), returning the raw bit pattern as 1s and 0s.

int cmd_setcur (  char *  args, MsgType  msgtype, char *  reply )

CURRENT command - set/query drive current in Amps. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Sends a CC command with appropriate syntax to the microstep drive. If the calling command was given without arguments, it instead queries the controller for the value of the drive current and sets the appropriate internal variables. NOTE: the maximum current is not specified a priori, so we need to find some way to set this in the header. At present, until we work this out, this could allow dangerously high currents to be set.

int cmd_setsp (  char *  args, MsgType  msgtype, char *  reply )

SPEED command - set/query drive speed in rev/sec. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Sends the microstep drive a VE command with appropriate syntax. If the calling command was given without arguments, it instead queries the controller for the current speed setting and sets the appropriate internal variables. Speeds must be in the range #SI_MINVEL to #SI_MAXVEL (defined in siutils.h)

int cmd_setacc (  char *  args, MsgType  msgtype, char *  reply )

ACCEL command - set/query move acceleration in rev/sec/sec. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Sends a AC command with appropriate syntax to the microstep drive. If the calling command was given without arguments, it instead queries the controller for the value of the current acceleration and sets the appropriate internal variables. Accelerations are in integer steps from #SI_MINVDOT to #SI_MAXVDOT (defined in siutils.h).

int cmd_setdec (  char *  args, MsgType  msgtype, char *  reply )

DECEL command - set/query move deceleration in rev/sec/sec. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Sends a DE command with appropriate syntax to the microstep drive. If the calling command was given without arguments, it instead queries the controller for the value of the current deceleration and sets the appropriate internal variables. Decelerations are in integer steps from #SI_MINVDOT to #SI_MAXVDOT (defined in siutils.h), in units of rev/s/s.

int cmd_setstep (  char *  args, MsgType  msgtype, char *  reply )

STEPS command - set/query the steps/position in steps. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Sets the number of steps/move when the microstep drive is instructed to move. It sends a DI (move "distance") command with the appropriate syntax to the microstep drive. If the calling command passed no arguments, it instead queries the controller for the current DI value sets the appropriate internal variables. Move distances are in integer units of steps, + or -, with value in the range #SI_MAXMOVE (see scutils.h)

int cmd_setto (  char *  args, MsgType  msgtype, char *  reply )

TIMEOUT command - set/query the communication timeout interval in seconds. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Sets the communications timeout in seconds used for all comm with the microstep controller. If TIMEOUT was given without arguments, it returns the current timeout interval, otherwise it sets the timeout to the interval specified by the first command-line argument. This is an internal variable, no microstep controller setting is required.

int cmd_mstatus (  char *  args, MsgType  msgtype, char *  reply )

MSTATUS command - report detailed microstep drive status. Queries the stepper motor controller and reports the current microstep drive paramters. The report is formatted as IMPv2-compliant message with the parameters given as keyword=value pairs. The keywords correspond to the names of the parameters in the SCL command set. This is low-level stuff, meaningful only to people who know the SCL command set, or have the manual at hand. If you have to look at mstatus, you have to be ready to get down to the nitty-gritty. It takes approximately 1 second to execute a complete controller status query, depending on the local communications details. For brief filter status, use the STATUS command (cmd_status()). For detailed filter wheel parameters, use the FPARS command (cmd_fpars()). See also: cmd_info(), cmd_status(), cmd_fpars()

int cmd_idle (  char *  args, MsgType  msgtype, char *  reply )

IDLE command - enable/disable the microstep drive idle current. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Allows the user to set whether the drive idles after moves. The default drive idle current is 50% of the normal set current (see cmd_setcur()). Sets the fw.Idle flag (1=enabled, 0=disabled), and uploads either the "MD" ("Motor Disable") or "ME" ("Motor Enable") commands to the Si controller. Note that a move can in fact be launched even if the drive is "disabled", as all that is disabled is the idle current (i.e., ME sets the idle current to 50% of the drive current and turns the drive on, while MD sets the idle current to 0 and turns the drive off. The next FL or other "move" command will start the drive at full current). If IDLE is given with no arguments, it reports the current idle setting (as it is known)

int cmd_send (  char *  args, MsgType  msgtype, char *  reply )

SEND command - send a raw command to microstep drive. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Sends a raw command to the microstep drive. Raw commands generate no reply unless there is an error (they'll return ! or ?), so sends the command typed as-is (no validation) to the controller and then returns to the command prompt without waiting for a reply. To send a command that produces a reply from the controller, you need to send a "query" command (cmd_query()). The Si motor controllers require commands in all uppercase. As a precaution we force the arguments of this command to uppercase. See also: cmd_query()

int cmd_query (  char *  args, MsgType  msgtype, char *  reply )

QUERY command - send a raw device query to the microstep drive. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Raw commands that are a query (e.g., "VE" to query speed instead of "VE2" which sets the speed to 2 rev/sec) generate a reply that needs to be passed back to the caller. This routine sends a raw query and waits for a reply or timeout (e.g., if controller not present or not powered on). The timeout is set by the fw.Timeout datum. To send a command that produces no reply from the controller, use the "send" command, cmd_send(). See also: cmd_send()

int cmd_reset (  char *  args, MsgType  msgtype, char *  reply )

RESET command - reload the runtime config paramters and re-initialize the microstep drive. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Calls loadconfig() to re-read the runtime config file, restoring all initial client parameters, then re-opens the serial port (if any - better be), and uploads the microstep drive parameters to the controller. This provides the client application with a warm restart facility.

int cmd_init (  char *  args, MsgType  msgtype, char *  reply )

INIT command - (re)initialize the microstep drive. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Uploads the microstep drive parameters to the controller by calling MechSetProfile().

int cmd_abort (  char *  args, MsgType  msgtype, char *  reply )

ABORT command - abort a move in progress. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Sends an SK command (Stop/Kill) to the microstep drive. This will stop any move in progress, and erase any pending commands from its command buffer, finally putting the controller in an idle state ready for subsequent commands. Sets the fw.Abort flag to report to upstream processes that an abort has been sent and services. It then queries the drive status after sending the abort to try to determine the drive status.

int cmd_fpars (  char *  args, MsgType  msgtype, char *  reply )

FPARS command - report detailed filter wheel parameters. Prints a detailed listing of all of the filter wheel control parameters. The defaults are defined in the runtime configuration file (see loadconfig()), and may be overridden by various low-level motor control commands (e.g., SPEED, ACCEL, etc.). This reptors the current state of this parameter set. The report is formatted as IMPv2-compliant message with the parameters given as keyword=value pairs. For brief filter status, use the STATUS command (cmd_status()). For the current microstep drive internal parameters, use the MSTATUS command (cmd_mstatus()). See also: cmd_info(), cmd_status(), cmd_mstatus()

int cmd_status (  char *  args, MsgType  msgtype, char *  reply )

STATUS command - report client status. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. On success it contains a status message. Queries the filter-wheel mechanism and reports the current filter wheel position and drive state in the form of an IMPv2-conformal status message in the reply. For example: FWState=Ready Filter=2 Load=5 If the filter is out of position when queried, it will read something like FWState=Ready Filter=UNKNOWN Load=UNKNOWN

int cmd_filter (  char *  args, MsgType  msgtype, char *  reply )

FILTER command - move filter n into the beam. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Move the named filter into the beam, or query for the filter currently in the beam if FILTER is given without command arguments. If a move is requested, the filter is moved through N steps, where N is the least path to the target filter position.' See cmd_load() for the equivalent LOAD command to put a specific filter into the loading position

int cmd_load (  char *  args, MsgType  msgtype, char *  reply )

LOAD command - move filter n into the filter wheel's load port. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Move the named filter into the filter wheel's load port, or query for the filter currently in the load port if LOAD is given without command arguments. If a move is requested, the filter is moved through N steps, where N is the least path to the target filter position. See cmd_filter() for the equivalent FILTER command to put a specific filter into the instrument beam.

int cmd_findpos (  char *  args, MsgType  msgtype, char *  reply )

FINDPOS command - seek the nearest valid filter position. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. FINDPOS instructs the filter wheel controller to seek the nearest valid filter wheel position. If the filter is already in a valid position (in-position bit = HIGH), it reports that position. If it is instead out of position (in-position bit = LOW), it does a slow seek forward to find a valid position. This is the software equivalent of a person physically moving an inactive filter wheel until in a valid position (held in place by the spring detent). This command provides the user a way to remotely reset the filter wheel after badness (e.g., a power interruption that left the mechanism in an unindexed in-between position).

---

Variable Documentation

struct Commands cmdtab[]

Client command action function data structure.

int NumCommands = sizeof(cmdtab)/sizeof(struct Commands)

number of commands defined

---