Main Page | Data Structures | File List | Data Fields | Globals | Related Pages

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_status (char *, MsgType, char *)
 STATUS command - report microstep drive motion status.

int cmd_mstatus (char *, MsgType, char *)
 MSTATUS command - report detailed microstep drive status.

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_seticur (char *, MsgType, char *)
 IDLECUR command - set/query idle 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_setdist (char *, MsgType, char *)
 DIST command - set/query the motion profile move distance in steps.

int cmd_setto (char *, MsgType, char *)
 TIMEOUT command - set/query the communication timeout interval in seconds.

int cmd_setpt (char *, MsgType, char *)
 POLLTIME command - set/query the microstep drive polling interval in msec.

int cmd_settopo (char *, MsgType, char *)
 TOPOLOGY command - set/query the mechanism topology.

int cmd_idle (char *, MsgType, char *)
 IDLE command - enable/disable the microstep drive idle current.

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_sclcmds (char *, MsgType, char *)
 CMDS command - print a list of SCL microstep drive commands.

int cmd_ismask (char *, MsgType, char *)
 ISMASK command - set/query the input status bitmask.

int cmd_ndata (char *, MsgType, char *)
 NDATA command - set/query the number of encoder data bits.

int cmd_inpos (char *, MsgType, char *)
 INPOS command - set/query the address of the in-position sensor input.

int cmd_homeaddr (char *, MsgType, char *)
 HOMEADDR command - set/query the address of the home sensor input.

int cmd_limits (char *, MsgType, char *)
 LIMITS command - set/query the limit switch settings.

int cmd_moveit (char *, MsgType, char *)
 MOVE command - execute a generic move with verbose feedback.

int cmd_moveabs (char *, MsgType, char *)
 MOVEABS command - move mechanism to an absolute step-count position.

int cmd_moverel (char *, MsgType, char *)
 MOVEREL command - move mechanism relative to the current position.

int cmd_moveto (char *, MsgType, char *)
 MOVETO command - move to indexed position N.

int cmd_findpos (char *, MsgType, char *)
 FINDPOS command - seek the nearest valid indexed 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.
Usage:
quit
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.
Usage:
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.

Example Output: 

ID=SCL2 Host=darkstar:10702 Mode=STANDALONE SCLPort=172.16.1.56:8002 
Verbose -DEBUG rcfile=port2.ini

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
Usage:
version
Creates an IMPv2 message (in 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.

Example output: 

  Version=v1.0 CompileDate=2004-Jun-11 CompileTime=17:08:15

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
Usage:
verbose
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
Usage:
debug
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
Usage:
help <cmd>
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.

If an argument is given, it tries to find that string in the command list, and if successful, prints a brief description and usage message.

Help is meant to be simple. It can give help on particular commands (really a reminder of the command's function and syntax), or a list of all commands.

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
Usage:
history
List 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_status (  char *  args,
MsgType  msgtype,
char *  reply
) 
 

STATUS command - report microstep drive motion 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.
Usage:
status
Prints a detailed listing of all of the microstep drive 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 example: 


State=Ready NDataBits=1 Inputs=00000000 EncPos=0 CWLimit=0 CCWLimit=0 
Accel=1 Speed=2.00 Dist=1 Decel=1 Current=3.00 Idle=OFF Timeout=10 
PollTime=100 Port=172.16.1.56:8002
For the current microstep drive internal parameters, use the MSTATUS command (cmd_mstatus()).

See also:
cmd_info(), cmd_mstatus()

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

MSTATUS command - report detailed microstep drive 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.
Usage:
mstatus
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.

Use the STATUS command if you only want to view the motion and input parameters. MSTATUS shows everything...

Example: 


RS=Ready RV=215 PM=2 PC=2.50 CC=2.99 CI=1.50 VE=2.00 VC=1.00 
AC=1 DE=1 AM=5 DI=1 DC=20000 ID=0 IP=63737 DL=1 MR=8 IS=1 JS=1.00 
JA=1 BS=128

See also:
cmd_info(), cmd_status

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.
Usage:
ports
Report information about all mechanism comm ports connected to the client in IMPv2-compliant format. Shows their status as follows: 
  FWPort=/dev/ttyS0 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.
Usage:
rdpos
Queries the microstep controller and reads the filter wheel position encoders (8 input bits), returning the raw bit pattern as 1s and 0s. Also queries the immediate drive position, returning the number of step counts from the device "zero" position.

Typical output: 

   RawIn=01111111 Inputs=10000000 ISMask=00000000 IPos=63737
This shows the raw input bits, the masked input bits, the input status mask used (see cmd_ismask()), and the step count position.

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.
Usage:
current <Amps>
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.

The default idle current (CI parameter) is 50% of the drive current. If we are using a non-default idle current, we need to restore that value after setting CC (since CI is recomputed by the CC set command). A default idle current is denoted by scl.IdleCurrent<0.0 amps.

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.

See also:
cmd_seticur()

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

IDLECUR command - set/query idle 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.
Usage:
idlecur <Amps|-1>
Sends a CI 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 idle current and sets the appropriate internal variables.

If the idle current is set to -1, the default idle current, which is 50% of the drive current, is used.

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.

See also:
cmd_setcur()

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.
Usage:
speed <rev/s>
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.
Usage:
accel <rev/s/s>
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.
Usage:
decel <rev/s/s>
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_setdist (  char *  args,
MsgType  msgtype,
char *  reply
) 
 

DIST command - set/query the motion profile move distance 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.
Usage:
distances <steps>
Sets the distance of a move in steps 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.
Usage:
timeout <seconds>
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_setpt (  char *  args,
MsgType  msgtype,
char *  reply
) 
 

POLLTIME command - set/query the microstep drive polling interval in msec.

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.
Usage:
polltime <milliseconds>
Sets the polling time interval to be used when monitoring the status of a move. Polling times are given in millisecons. If POLLTIME was given without arguments, it returns the current polling interval, otherwise it sets the polling interval specified by the first command-line argument. This is an internal variable, no microstep controller setting is done.

In practice, roundtrip communications via 9600 baud serial to this family of microstep drives is around 40-50msec for a typical parameter query or parameter setting operation. The polling time should not be so fast as to harrass the controller, possibly intefering with its ability to execute a move. A typical polling time we use is 100-200msec, providing 5 status messages/second which seems more than sufficient when debugging drive performance.

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

TOPOLOGY command - set/query the mechanism topology.

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.
Usage:
topology <rotary|linear>
Allows the user to set the drive topology as either "rotary" or "linear". If topology is given with no arguments, it reports the current topology.

The drive topology tells the system how to move between fixed ("indexed") positions. In a linear drive, it simply moves directly to the position requested, but in a rotary drive, which can approach a position from clockwise or counter-clockwise around the circle, it selects the shortest path to that position.

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.
Usage:
idle <on|off>
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 scl.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_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.
Usage:
reset
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.
Usage:
init
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.
Usage:
abort
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.

It then queries the drive status after sending the abort to try to determine the drive status.

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

CMDS command - print a list of SCL microstep drive commands.

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
Usage:
cmds
Prints a summary of the SCL microstep drive commands. Not comprehensive, mostly just a reminder. It is only meant to be executed as an EXEC: message type. If the command is not qualifed as EXEC:, it returns an error.

For a list of client commands, see HELP (cmd_help()).

See also:
cmd_help()

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

ISMASK command - set/query the input status bitmask.

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.
Usage:
ismask <8-bit mask>
Sets the input status bitmask, or returns the current mask if ISMASK given without arguments.

The input status mask (ISMask) needs to be set correctly to interpret the input sensors, since in practice inputs may be either normally open or normally closed depending on the application. The input status mask is a string of eight (8) 1s and 0s, defined as follows. For the i-th mask bit, 

   0  means the input is asserted (true) when INi=0 (closed)
   1  means the input is asserted (true) when INi=1 (open)
Beware: the order of bits in ismask is identical to the order of bits in the raw controller IS string (i.e., IN8..IN1).

Input Status Mask Example:
An 8-position filter wheel uses normally-open proximity sensors as position encoders. Each discrete position is encoded by drilling a pattern of holes representing the 3 bits at each valid filter position: open hole=1, closed-hole=0. For each filter, a 4th "in-position" bit is drilled that is always open below the in-position sensor when that filter is centered in a valid position. The 3 position bit sensors are connected to IN1..IN3 (ndata=3), and the in-position sensor is connected to IN4. IN5..IN8 are unused, and since they are unconnected and therefore are always open, they will always appear as 1s in IN5..IN8 in the IS query string. The ismask to use with this device would be:

 
  ismask 00001111;

IN1..IN4 is 1 if there is a hole under the proximity sensor (binary 1 = "asserted"), and 0 if there is metal under the sensor (binary 0 = "deasserted"). We mask IN5..IN8 as 0 so that they always be deasserted 0 since they are unused. The result of using this mask on the above IS string is as follows: 

  raw status = 11111001
      ismask = 00001111
      result = 00001001
The masked status bits make it easy to see that only IN1 (position 1s bit) and IN4 (the in-position bit) are asserted.

See also:
cmd_ndata(), cmd_inpos().

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

NDATA command - set/query the number of encoder data bits.

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.
Usage:
ndata <0..8>
Sets the number of data bits used to encode positions using the microstep drive inputs. Position bits run from IN1..IN<ndata>, with IN1=LSB ... IN<ndata>=MSB.

If NDATA was given without arguments, it returns the current number of data bits.

The command "NDATA 0" disabled sensing position with the inputs.

The input status mask (ISMask) needs to be set correctly to interpret the input sensors. See cmd_ismask() for the gory details.

See also:
cmd_inpos(), cmd_ismask().

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

INPOS command - set/query the address of the in-position sensor input.

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.
Usage:
inpos <0..8>
Sets the address (1..8) of the in-position bit, or disables in-position sensing if set to 0 (zero).

If INPOS was given without arguments, it returns the current address of the in-position bit.

The input status mask (ISMask) needs to be set correctly to interpret the input sensors. See cmd_ismask() for the gory details.

See also:
cmd_ndata(), cmd_ismask().

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

HOMEADDR command - set/query the address of the home sensor input.

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.
Usage:
homeaddr <0..8>
Sets the address (1..8) of the home bit, or disables home sensing if set to 0 (zero).

If HOMEADDR was given without arguments, it returns the current address of the home sensor input.

The input status mask (ISMask) needs to be set correctly to interpret the input sensors. See cmd_ismask() for the gory details.

See also:
cmd_ndata(), cmd_ismask().

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

LIMITS command - set/query the limit switch settings.

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.
Usage:
limits <OFF|OPEN|CLOSED>
Sets the limit switches. Arguments are
  • OFF Disable the limit switches (DL3)
  • OPEN Enable limit switches normally-open (DL1)
  • CLOSED Enable limit switches normally-closed (DL2)
If LIMITS was given without arguments, it reports the current limit switch settings and queries the controller for the switch states.

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

MOVE command - execute a generic move with verbose feedback.

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.
Usage:
move <FL|FP|FC|FM#x|FS#x|FY#x|FO#x|FD#x#x>
Executes a move command (FL, FP, FC, etc.) with verbose feedback during the move by polling the controller while the move is in progress and reporting the immediate position, inputs, and move distance.

The argument must be a valid raw move command (FL, FP, etc.) which it is to execute then monitor to completion.

If MOVE is given with no arguments a usage error message is printed.

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

MOVEABS command - move mechanism to an absolute step-count 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.
Usage:
moveabs <step_pos>
Moves the mechanism to an absolute step-count position relative to the mechanism zero (home) position. Launches an FP (Feed to Position), with the position specified on the command line.

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

MOVEREL command - move mechanism relative to the current 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.
Usage:
moverel <dx>
Moves the mechanism by dx steps relative to its current position, where dx is in steps. Launches an FL (Feed to Length) of the distance specified on the command line. +dx moves in positive step counts, -dx in negative step counts.

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

MOVETO command - move to indexed position N.

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.
Usage:
moveto <N>
Move a mechanism to indexed position N. Mechanism must be an indexed mechanism, either linear or rotary (this as indicated by the Topology parameter). It uses the "Offset" data member of the si_mechanism struct as the offset between the encoder and device positions, if set to non-zero.

In a rotary indexed mechanism, it moves to the requested position via the least path clockwise or counterclockwise.

If MOVETO is issued without arguments, it reports the current indexed position.

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

FINDPOS command - seek the nearest valid indexed 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.
Usage:
findpos
FINDPOS instructs the mechanism to seek the nearest valid indexed position.

  • If the mechanism 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 mechanism by hand until in a valid position (held in place by the spring detent).
This command provides the user a way to remotely reset the mechanism after badness (e.g., a move abort or 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

Generated on Thu Jul 22 20:02:06 2004 for SiTool Si Microstepping Motor Controller Agent by doxygen 1.3.7