M2FS (BeagleBoard) Commands

2020-01-27: added the MODE command
2019-06-18: removed the AUTOFOCUS commands
2017-11-07: updated the return values for the "FILTER ?" and "FLSIM ?" requests
2017-10-11: added FILTER_MOVE, updated FILTER
2017-09-05: added the MCLED command
2015-04-20: removed STOWEDSHUTDOWN
2014-12-17: added AUTOFOCUS, AUTOFOCUSPARAMS
2014-01-22: minor changes
2013-12-09: minor changes
2013-08-28: minor changes
2013-02-22: v1

Protocol

All communications are initiated by the M2FS-GUI.
Commands are terminated by a 'LF' (0x0a) character.
Responses are terminated by a 'LF' (0x0a) character.: Multi-line responses shall be separated by (0x0d) characters.
All commands will be "immediately" answered by the Beagle board (small delays upto 2 seconds are acceptable).
The Galil motor controllers have a concurrency limit of four axis.: If the M2FS-GUI attempts to start more than four motions simultaneously the BeagleBoard software will respond with an "ERROR".
Response strings to motion commands:: "OK"; "!ERROR some explanation" (syntax error); "ERROR some explanation" (eg. hardware malfunction or the command cannot be executed at this time)
Response strings to status requests:: "#" (where '#' may be a space separated list of values); "MOVING"; "INTERMEDIATE"; "UNCALIBRATED"; "UNKNOWN"; "!ERROR some explanation" (syntax error); "ERROR some explanation" (eg. hardware malfunction)

Commands

Parameter types:

{a,b,c}: a list of possible values

{a-b}: a range of values

# a single value

# # #: a list of values (space separated)

Shack-Hartman and Guider

Plug Plates

FLS Mirror

Other

Disperser Slide

command: GES {R,B} {LORES,HIRES,LRSWAP}: response: {OK,ERROR}; Note: "LRSWAP" will automatically move the LO-Elevation to a special angle suitable for swapping the grating.
command: GES {R,B} ?: response: {LORES # #, HIRES # #, LRSWAP # #, INTERMEDIATE # #, UNCALIBRATED, MOVING}; '# #' are the encoder value and the step position respectively.; Note: "LASTKNOWN" may be appended to the return if the status is read back from a file.
command: GES_CALIBRATE {R,B}: response: {OK,ERROR}; Causes the disperser slide to execute a calibration routine. After the calibration is done the state becomes 'INTERMEDIATE' with a 'step' value of '0'.
command: GES_MOVE #: response: {OK,ERROR}; Note: TBD "nudge" command

LoRes Elevation

command: LREL {R,B} {a-b}: response: {OK,ERROR}; range: TBD
command: LREL {R,B} ?: response: {#,MOVING,UNCALIBRATED}; Note: "LASTKNOWN" may be appended to the return if the status is read back from a file
command: LREL_CALIBRATE {R,B}: response: {OK,ERROR}; Causes the LoRes Elevation to execute a calibration routine. During the motion a 'LREL ?' returns 'MOVING', afterwards '0'.

HiRes Azimuth

command: HRAZ {R,B} {a-b}: response: {OK,ERROR}; range: TBD
command: HRAZ {R,B} ?: response: {#,MOVING,UNCALIBRATED}; Note: "LASTKNOWN" may be appended to the return if the status is read back from a file
command: HRAZ_CALIBRATE {R,B}: response: {OK,ERROR}; Causes the HiRes Azimuth to execute a calibration routine. During the motion a 'HRAZ ?' returns 'MOVING', afterwards '0'.

HiRes Elevation

command: HREL {R,B} {a-b}: response: {OK,ERROR}; range: TBD
command: HREL {R,B} ?: response: {#,MOVING,UNCALIBRATED}; Note: "LASTKNOWN" may be appended to the return if the status is read back from a file
command: HREL_CALIBRATE {R,B}: response: {OK,ERROR}; Causes the HiRes Elevation to execute a calibration routine. During the motion a 'HREL ?' returns 'MOVING', afterwards '0'.

Focus

command: FOCUS {R,B} {a-b}: response: {OK,ERROR}; range: TBD
command: FOCUS {R,B} ?: response: {#,MOVING #}; While the focus is moving the current encoder reading is appended to the 'MOVING' string.

Filter

command: FILTER {R,B} {1-18}: response: {OK,ERROR}; 9: CHANGE 10: NONE; 11-18: move to positions 1-8 but do not insert the filter.
command: FILTER {R,B} ?: response: {#,MOVING,INTERMEDIATE,UNKNOWN} # # #
Engineering commands:
command: FILTER_MOVE {R,B} #: response: { OK,ERROR }; This commands the filter inserter to move by a step amount ('#') if the elevator is in a safe position.

Slits

Note: The 'R/B' parameter refers to the cradle (not shoe).

command: SLITS {R,B} {1-7} {1-7} {1-7} {1-7} {1-7} {1-7} {1-7} {1-7}: response: {OK,ERROR}
command: SLITS {R,B} ?: response: "a b c d e f g h" where 'x' is from {#,MOVING,UNCALIBRATED}; Note: all slits of a shoe are commanded at the same time.
command: SLITS_CLOSEDLOOP {ON,OFF,?}: response: {OK,ERROR,ON,OFF}; uses the FLS projector to maximize throughput; Note: not implemented (FLS does not exist)
command: SLITS_SLITPOS {R,B} {1-8} {1-7} {#,?}: response: {OK,#}; Sets/gets the nominal slit postition
command: SLITS_CURRENTPOS {R,B} {1-8} {?}: response: {#,MOVING,UNCALIBRATED}; Returns the current motor position in steps
command: SLITS_ACTIVEHOLD {ON,OFF,?}: response: {OK,ERROR,ON,OFF}; The motors remain (not) energized while not moving; Note: not implemented at the M2FS-GUI
command: SLITS_MOVESTEPS {R,B} {1,8} #: response: {OK,ERROR}; Move motor by # steps.; Note: Use 'SLITS_CURRENTPOS' to determine the end of the motion.
command: SLITS_HARDSTOP {R,B} {1-8}: resonse: {OK,ERROR}; Tells a tetris to drive to the hardstop and zero the position.; Note: Use 'SLITS_CURRENTPOS' to determine the end of the motion.

Shack-Hartman and Guider

command: SHLENS {IN,OUT}: response: {OK,ERROR}
command: SHLENS ?: response: {IN,OUT,MOVING}
command: SHLED {0-255}: response: {OK,ERROR}; set LED brightness
command: SHLED ?: response: #; get LED brightness
command: GFOCUS {+,-,#}: response: {OK,ERROR}; range: {0..90}
command: GFOCUS ?: response: {#,MOVING,ERROR}
command: GFILTER {1-6}: response: {OK,ERROR}
command: GFILTER ?: response: {#,MOVING,ERROR}

Plug Plates

command: PLUGMODE {ON,OFF,?}: response: {OK,ON,OFF,MOVING}
command: PLATELIST: response: {name1 name2 name3 ... }; Returns the list of plates available (no spaces in 'names')
command: PLATE name: response: {'Setup 1' 'Setup 2' ...}; Selects plate 'name'. The return string contains the named setups in single quotes (').
command: PLATE ?: response: {name,ERROR}; Returns the currenly selected plate
command: PLATESETUP {#,?}: response: {OK,ERROR}; Sets/gets the setup number '#' on the current plate
command: PLUGPOS {R,B}: response: string1 string2 string3 ... string128; Each 'stringN' has the following structure: Tetris:Groove:PlateHoleID:FiberID with; Tetris = {1.8}; Groove = {1..16}; PlateHoleID = string of characters (no ' ',':'); Note: PlateHoleID may be 'unplugged' or 'unknown' if the cradle does not contain a shoe.; FiberID = string of characters (no ' ',':')

FLS Mirror

command: FLSIM {R,B} {IN,OUT,#}: response: {OK,ERROR}
command: FLSIM {R,B} ?: response: {IN,OUT,MOVING,UNKNOWN} #
Engineering commands:
command: FLSIM_MOVE {R,B} #: response: {OK,ERROR}; Moves the mirror by '#' steps.
command: FLSIM_INSERT {R,B}: response: {OK,ERROR}; Insert the mirror.
command: FLSIM_REMOVE {R,B}: response: {OK,ERROR}; Remove the mirror.

Slit Shoe Assignment

command: CRADLESTATE ?: response: CRADLE_R=string CRADLE_B=string; where 'string' is one of {SHOE_R,SHOE_B,NONE}

Instrument Temperatures

command: TEMPS: response: {# # # # # # # # #,ERROR}; An ordered list [ShackHartman, CradleR/B, EchelleR/B, PrismR/B, LoResR/B] of 9 floating point numbers. Any temperature [Celsius] may be replaced by an 'U' (UNKNOWN) if it is currently not available.

LEDs

command: MCLED # # # # # #: response: { OK,ERROR}
command: MCLED ?: response: {# # # # # #,ERROR}; An ordered list of values (0-4096) for UV, Blue, Visible, N-Red, F-Red, IR.

Instrument Status

command: STATUS: response: A list of strings separated by '\r' [CR]. Each string consists of one or more key:value pairs separated by a ' ' [SPACE].

BeagleBoard Software version

command: VERSION: response: string; The version of the director.

GUI connection and Shutdown

command: MODE {M2FS,IFUM}: response: {OK, ERROR}; Informs the BeagleBoard software what instrument mode to use. This may fail if the wrong instrument is connected.
command: GUICLOSING: response: OK; Informs the BeagleBoard software that the M2FS-GUI will close.
command: SHUTDOWN: response: OK; Exit the BeagleBoard software.