Command oplet instruction

The list of commands or "oplets" that Dexter knows are defined by the HashInputCMD function in the DexRun.c Firmware and are described by Dexter.instruction_type_to_function_name_map in DDE.

This wiki page attempts to expand on that document to further explain the instructions. In addition to this list, the 'w' Write FPGA, and 'S' SetParameter oplets also have lists of addresses and sub-commands.

To send oplet to Dexter: Oplets are sent to Dexter via a raw socket connection on port 50000 in a format fully documented in DexRun-DDE-communications.

Always wait for return status after sending an oplet, before sending the next oplet.

Non-movement instructions may hold for a move instruction to be sent. This helps to coordinate movement with things like end effector actuation. However, it can be confusing if you just want to e.g. turn a laser end effector on and off and nothing happens. Just send a movement command with the current positions to enable your prior command.

Certain instructions are queued in the FPGA in an internal movement FIFO and executed sequentially but will instantly return a status when recieved even though the movement is not complete. These are marked as "queued" in the list below. Other instructions are executed as soon as they are recieved. When the queue is full, that last movement command submitted will not return a status, and DexRun will not respond to any commands until a movement is complete, opening a space on the queue.

To wait for a movement to completed, use the 'F' oplet, as it will not return a status until the queue is empty.

Note that the commanded position via 'a' or 'M' is added to by the PID position of 'P' or 'C'; PID positions are an offset to commanded positions.

See DDE documentation for the use of the DDE version of each command. E.g. for move_to use Dexter.move_to (...)

Command Format

A job number, instruction number, start POSIX time, end time (unknown) and the oplet and it's parameters are sent followed by a ';' to close the line. e.g. for the 'g' (get_robot_status) oplet you might send 1 2 1528438131 undefined g ; where this is the first job, the 2nd instruction in that job, it was sent at 06/08/2018 @ 6:08am (UTC), the end time is not known (it will be set by Dexter in the returned status). Note: All these values must be present, but are not checked. e.g. 1 1 1 1 g ; works just fine and any set of numbers could be sent; the return status will simply return the same values, updating only the end time. However, that won't tell you what instruction # it's for, or when the command was sent. The purpose of the job and instruction numbers is to coordinate the return status with the command.

	DDE name	DexRun	Description
a	"move_all_joints"	MOVEALL_CMD	Queued. Arguments: 5 to 7 goal joint angles in arcseconds, space separated. E.g. a 0 0 0 0 0 is home. The goal can not be changed during the move. Trapezoidal speed ramping is used with coordination so the first 5 joints arrive at their goals at the same time. Acceleration, MaxSpeed, and StartSpeed can be set via the "S" SetParameter oplet. Does not require calibration, works even in Open Loop mode (w/ lower accuracy). Since 2018.11.07 accepts joint 6 and 7 positions.
b	"move_to"	n/a	Queued. Use "Dexter.move_to" in DDE which calculates joint angles and sends an 'a' oplet. In DexRun, this oplet is superseded by 'M'. See: Kinematics
B	"set_boundries"	SET_ALL_BOUNDRY	10 args in arcseconds: j1BoundryHigh, j1Boundrylow, j2BoundryHigh, j2Boundrylow, j3BoundryHigh, j3Boundrylow, j4BoundryHigh, j4Boundrylow, j5BoundryHigh, j5Boundrylow. Set individually with "S" oplet subcommands
c	"capture_ad"	CAPTURE_AD_CMD
C	n/a	PID_MOVE_TO	Since 2019.10.10 Onboard kinematics move to XYZ (integer microns), with end effector in XYZ direction (unit vector), using configuration (booleans). Like 'M' but uses PID moves like 'P' instead of joint moves like 'a'. See also S PID_P and w MAX_ERROR to limit drive strength.
d	"dma_read"	DMAREAD_CMD	Writes the FPGA DMA data into the specified file. 3 args: Address, Length, Filename.
e	"cause_dexter_error"	n/a	Used only in DDE
E	"empty_instruction_ queue_immediately" Since 2016.09.01	n/a	Apparently never implemented in firmware?
F	"empty_instruction_ queue"	HEART_BEAT Since 2016.09.01	Queued. Does wait_fifo_flush() first. Was SET_FORCE_MOVE_POINT. This instruction will not return a status until it actually executes. Instructions before this one will be executed first. Very useful to synchronize robot motion with control software. E.g. to wait until the arm has moved to a new position before closing the gripper.
f	"find_home"	FIND_HOME_CMD	Depreciated Use job engine.
G	"get_robot_status_ immediately"	Since 2016.09.01 HEART_BEAT	(Same as 'g'?)
g	"get_robot_status"	SEND_HEARTBEAT	Returns the current status of the robot.//fry
h	"get_robot_status_ heartbeat"	HEART_BEAT	obsolete //fry
i	"capture_points"	CAPTURE_POINTS_CMD	Enters a sub mode where points are captured to a file on Dexter. 1 arg: Filename. Expects an input stream of commands from stdin via getchar(). No timeout.
l	"load_tables"	LOAD_TABLES	Writes encoder CalTables from FPGA to /srv/samba/share/HiMem.dta
M	n/a1	MOVETO_CMD Since 2018.10.9	Queued Onboard kinematics move to XYZ (integer microns), with end effector in XYZ direction (unit vector), using configuration (booleans). For example to move to [0,0.5,1.0] (in meters) with the end effector pointed straight down and right_arm, elbow_up, and wrist_out:1 1 1 1 M 0 500000 100000 0 0 -1 1 1 1. See T and S MaxSpeed
m	"record_movement"	RECORD_MOVEMENT
n	"find_index"	FIND_INDEX_CMD	Unused
o	"replay_movement"	REPLAY_MOVEMENT
P	"pid_move_all_joints"	PID_FINEMOVE	Chases a goal offset on each joint using the PID control system which must be enabled. Requires calibration. The goal can change in the middle of the move. Movement is not coordinated so each joint may arrive at the goal at a different time. The standard trapezoidal speed ramping is not used. Adds to "a" position. Modified 201909 to optionally accept joint 6/7 angles. See kinematics for its comparison to move_all_joints. See also S PID_P and w MAX_ERROR to limit drive strength.
p	"find_home_rep"	FIND_HOME_REP_CMD	Depreciated Use job engine.
R	"move_all_joints_ relative"	MOVEALL_RELATIVE	Queued. Like 'a' but the joint is moved relative to it's prior position. E.g. R 0 0 -36000 0 0; will move joint 3 ccw 10 degrees.
r	"read_from_robot" Since v2.3.16	READ_CMD Since 2018.07.26	Reads files or string data from the robot. Also reads and prints locally values from the memory mapped FPGA interface.
s	"slow_move"	SLOWMOVE_CMD Since 2018.10.9
S	"set_parameter"	SET_PARAM	Sets many different values
T	"move_to_straight"1	MOVETOSTRAIGHT_CMD	Use "Dexter.move_to_straight" in DDE which calculates a sequence of joint angles and sends a bunch of 'a' oplets with speed settings. 'T' does onboard kinematics move in a straight line from prior 'M' oplet position to new XYZ position, direction, and configuration. See S CartesianSpeed
t	"dma_write"	DMAWRITE_CMD
w	"write"	WRITE_CMD	Writes to the FPGA / Gateware. Does wait_fifo_flush() first.
W	"write_to_robot" Since v2.3.15-16	WRITE_TO_ROBOT Since 20180418	Send files to the Dexter file system.
x	"exit"	EXIT_CMD
z	"sleep"	SLEEP_CMD	Queued. Pause the robot for the specified uSeconds (1 second = 1000000 uSeconds)

1. The 'M' and 'T' oplets are not used in DDE because DDE does its own kinematics.