LCS Serial Commands V1.
20
This document specifies the available commands to be sent to the OSI: MSG Lens Control System.
The 12S lens group is referred to as the F1 motor, or motor 0.
The 4S-5S lens group is referred to as the F2 motor, or motor 2.
The iris is referred to as the A1 motor, or motor 1.
Changelog:
V1.10
Updated for external release, added more detail for checksum
All commands and responses (except checksum_on and checksum_off) include a 2 character ASCII Hex
encoded checksum <CK> with an offset of 0x55 immediately before the linefeed < of all the characters up
until that point, if validation is enabled an error will be raised if the checksum is invalid. Note that errors
responses may vary based upon command.
Example: the command qf?<CK><LF> maps to the hex bytes, "71 66 3F 36 42 0A", where 0x36 0x42 is ASCII
for "6B" calculated as 0x55 (offset) + 0x71 + 0x66 + 0x3F.
Refer to Data Formats Tab for definitions. Engineering CMDs are for reference only, and may change
without notice and are intended for use by Marcus Engineering.
V1.13
Serial command list updated for test release to AED.
All commands have been tested with sample data loaded.
V1.14
Added cam_on and cam_off commands.
Added max_speed command.
Expanded engineering commands.
V1.15
Updated command definitions to be more clear on their usage.
Consolidated commands into single commands with a motor select parameter.
Moved some commands from the Engineering tab to the Manufacturing tab.
Added the max_speed? command.
Added the motor_enc_coarse? command.
Added the motor_enc_fine? command.
Added the pterm? command.
Added the iterm? command.
Added the dterm? command.
Added calibrate_from_reboot command.
v1.20
Removed error? command
v1.21
Added commands for adjustable calibration movements
LCS Serial Commands V1.20
Format C Format Specifier Description
[int32] %+011d Signed 32 Bit number with leading zeros and explicit sign
<LF> \n Represents a newline 0x0A
[uint32] %010 PRIu32 Unsigned 32 Bit number with leading zeros
s[x] %ns 8-Bit ASCII string of padded to length x
<CK> XX 8-Bit ASCII Hex values capital letters 0-9,A-F
Commands Parameters Units Range
qf? [focus] [aperture] um, % 2000-100000, 0-150
f1_gohome N/A N/A N/A
f2_gohome N/A N/A N/A
a1_gohome N/A N/A N/A
f1_powon N/A N/A N/A
f1_powoff N/A N/A N/A
f2_powon N/A N/A N/A
f2_powoff N/A N/A N/A
a1_powon N/A N/A N/A
a1_powoff N/A N/A N/A
sw_ver? N/A N/A 128 Characters
hw_ver? N/A N/A N/A
serial? [serial_number] N/A 16 Characters
model? [model_number] N/A 16 Characters
focus= [distance] mm 2000-100000
focus? [distance] mm 2000-100000
aperture= [opening] % 0-150
aperture? [opening] % 0-150
LC
Data Formatting Command Class
[int32] [int32] CAMERA
N/A CAMERA
N/A CAMERA
N/A CAMERA
N/A CAMERA
N/A CAMERA
N/A CAMERA
N/A CAMERA
N/A CAMERA
N/A CAMERA
s[128] CAMERA
x.x CAMERA
s[16] CAMERA
s[16] CAMERA
[int32] CAMERA
[int32] CAMERA
[int32] CAMERA
[int32] CAMERA
LCS Serial Commands V1.20
Details
Returns the focus and iris positions, with guaranteed response time of less than 16ms
Move the 12S lens to its home position (Infinity focus)
Move the 4S-5S lens to its home position (Infinity focus)
Move the iris to its home position (F4.5 aperture)
Enables the 12S lens
Disables the 12S lens
Enables the 4S-5S lens
Disables the 4S-5S lens
Enables the iris
Disables the iris
Displays software version string; with hash for development versions
Displays hardware version
Get the device serial number
Get the device model number
Set the lens focus position
Get the current lens focus position
Set the iris position
Get the current iris position
mands V1.20
Example Input
qf?<CK><LF>
f1_gohome<CK><LF>
f2_gohome<CK><LF>
a1_gohome<CK><LF>
f1_powon<CK><LF>
f1_powoff<CK><LF>
f2_powon<CK><LF>
f2_powoff<CK><LF>
a1_powon<CK><LF>
a1_powoff<CK><LF>
sw_ver?<CK><LF>
hw_ver?<CK><LF>
serial?<CK><LF>
model?<CK><LF>
focus=+0000003286<CK><LF>
focus?<CK><LF>
aperture=+0000000050<CK><LF>
aperture?<CK><LF>
Example Output TX Checksum RX Checksum
+0000003286,+0000000050<CK><LF> 0x6B 0xAF
OK<CK><LF> 0xCA 0xEF
OK<CK><LF> 0xCB 0xEF
OK<CK><LF> 0xC5 0xEF
OK<CK><LF> 0x7E 0xEF
OK<CK><LF> 0xDC 0xEF
OK<CK><LF> 0x7F 0xEF
OK<CK><LF> 0xDD 0xEF
OK<CK><LF> 0x79 0xEF
OK<CK><LF> 0xD7 0xEF
GIT HASH<CK><LF> 0x2A Variable
v1.1<CK><LF> 0x1F 0x5B
0000000000000451<CK><LF> 0x14 0x5F
Cyberdyne_mod101<CK><LF> 0xA5 0x2B
OK<CK><LF> 0xD0 0xEF
+0000003286<CK><LF> 0xB4 0x73
OK<CK><LF> 0x0A 0xEF
+0000000050<CK><LF> 0xFC 0x65
Notes
Commands Parameters Units
ATTENTION: These commands may cause the system to operate in a
adjust these settings without consulting Marcus Engineering or Opti
echo_on N/A N/A
echo_off N/A N/A
help N/A N/A
checksum_on N/A N/A
checksum_off N/A N/A
save_settings N/A N/A
cam_on N/A N/A
cam_off N/A N/A
mctask_on
mctask_off
serial= [password] [serial_number] N/A
model= [model_number] N/A
f1_sethome_curr N/A N/A
f1_sethome? [distance] nm
f2_sethome_curr N/A N/A
f2_sethome? [distance] nm
a1_sethome_curr N/A N/A
a1_sethome? [distance] %
f1_setpoint= [distance] mm
f1_setpoint? [distance] mm
f2_setpoint= [distance] mm
f2_setpoint? [distance] mm
a1_setpoint= [opening] %
a1_setpoint? [opening] %
setpoint? [distance][distance][opening] mm, mm, %
f1_cam= [entry #] [focus] [f1 position] N/A
f1_cam? [entry] N/A
f2_cam= [entry #] [focus] [f2 position] N/A
f2_cam? [entry] N/A
a1_cam= [entry #] [focus] [a1 position] N/A
a1_cam? [entry] N/A
motor_mov_ustep= [motor][distance] usteps
motor_mov_um= [motor][distance] N/A
max_speed= [motor][speed] usteps/s
max_speed? [motor] usteps/s
motor_enc_coarse= [motor][encoder value] encoder steps/rev
motor_enc_coarse? [motor] encoder steps/rev
motor_enc_fine= [motor][encoder value] encoder steps/rev
motor_enc_fine? [motor] encoder steps/rev
clear_stop= [motor] N/A
enc_cal= [motor] N/A
enc_n_cal= [motor] N/A
goto_limit= [motor] N/A
gohome_from_n= [motor] N/A
autocalibrate N/A N/A
valid_config= [valid] N/A
lens_pos? [motor] N/A
enc_n_distance= [motor][distance] usteps
enc_n_distance? [motor] N/A
home_distance= [motor][distance] usteps
home_distance? [motor] N/A
Range Data Formatting Command Class
use the system to operate in a manner that does not provide a proper lens
ng Marcus Engineering or Optical Support Inc.
N/A N/A MANF
N/A N/A MANF
N/A N/A MANF
N/A N/A MANF
N/A N/A MANF
N/A N/A MANF
N/A N/A MANF
N/A N/A MANF
ENGR
ENGR
12 Characters, 16 Characters s[12] s[16] MANF
16 Characters s[16] MANF
N/A N/A MANF
-8000000 to +8000000 [int32] MANF
N/A N/A MANF
-8000000 to +8000000 [int32] MANF
N/A N/A MANF
-8000000 to +8000000 [int32] MANF
2000-100000 [int32] MANF
2000-100000 [int32] MANF
2000-100000 [int32] MANF
2000-100000 [int32] MANF
0-150 [int32] MANF
0-150 [int32] MANF
2000-100000, 2000-100000, 0-150 [int32] [int32] [int32] MANF
0-980, 0-100000, -8000000 to +8000000 [int32] [int32] [int32] MANF
0-980, 0-100000, -8000000 to +8000000 [int32] [int32] MANF
0-980, 0-100000, -8000000 to +8000000 [int32] [int32] [int32] MANF
0-980, 0-100000, -8000000 to +8000000 [int32] [int32] MANF
0-100, 0-100, -20000 to +20000 [int32] [int32] [int32] MANF
0-100, 0-100, -20000 to +20000 [int32] [int32] MANF
0-2, -20000-20000 [int32][int32] MANF
0-2, -8000-8000 [int32][int32] MANF
0-2, 0-8000 [int32][int32] MANF
0-2 [int32] MANF
0-2, 1-5000 [int32][int32] MANF
0-2 [int32] MANF
0-2, 1-5000 [int32][int32] MANF
0-2 [int32] MANF
0-2 [int32] MANF
0-2 [int32] MANF
0-2 [int32] MANF
0-2 [int32] MANF
0-2 [int32] MANF
N/A N/A MANF
0-1 [bool] MANF
0-2 [int32] MANF
0-2, -20000 to 20000 [int32][int32] MANF
0-2 [int32] MANF
0-2, -500 to 500 [int32][int32] MANF
0-2 [int32] MANF
LCS Serial Commands V1.20
Details
es not provide a proper lens focus if incorrectly used, it is ill-advised to
Turns on input command echo over serial terminal (default is off, resets at reboot)
Turns off echo to serial terminal (this is the desired mode for automated control via script or camera)
Displays help info
Enables Checksum validation
Disables Checksum validation
Saves current home and cam table data, serial number, and model to flash memory
Enables tandem camming between focus motors
Disables tandem camming between focus motors, allows both to be moved independently
Enables the motor controller task, use this when you need CAM table movement
Disables the motor controller task, use this when you need manual movement, or to calibrate
Set the device serial number
Set the device model number
Set the current position as the 12S lens home position (Infinity focus)
Get the 12S lens home position offset from encoder N
Set the current position as the 4S-5S lens home position (Infinity focus)
Get the 4S-5S lens home position offset from encoder N
Set the current position as the iris home position (F4.5)
Get the iris home position offset from limit switch
Set the 12S lens focus position
Get current 12S lens focus position
Set the 4S-5S lens focus position
Get current 4S-5S lens focus position
Set current iris position
Get current iris position
Get all current motor positions
Writes a data value to the 12S lens CAM table
Reads a data value from the 12S lens CAM table
Writes a data value to the 4S-5S CAM table
Reads a data value from the 4S-5S CAM table
Writes a data value to the iris motor 1 CAM table
Reads a data value from the iris motor 1 CAM table
Moves motor_X by the number of microsteps requested
Moves motor_X by a distance of um
Sets the max speed for motor_X (Non-persistant)
Get the max speed for motor_X
Sets the coarse encoder factor (1um encoder steps per motor revolution) for motor_X
Gets the fine encoder factor (1um encoder steps per motor revolution) for motor_X
Sets the coarse encoder factor (1um encoder steps per motor revolution) for motor_X
Gets the fine encoder factor (1um encoder steps per motor revolution) for motor_X
Clears the motor_X STOP R/L limit switch event (Allows continued motion in that direction)
Calibrates the motor_X encoder for AB and N operation
Moves to the motor_X encoder N position, and sets that as the XACTUAL and ENC_POS 0
Moves to the assigned motor limit switch, and then moves away from it by a set amount.
Goes to the home position from N for motor_X. For the iris motor (1), this will move to home from limit switch
Performs the full calibration procedure for all motors from the currently stored home settings after a reboot
Set this to 1 when the home configuration is valid for auto-calibration routine at system boot
Read the physical lens position in nm
Sets the distance a motor will move to locate the encoder N mark during encoder calibration (Blind movement)
Gets the distance a motor will move to locate the encoder N mark during encoder calibration (Blind movement)
Sets the distance a motor will move off the home limit switch, after homing to the limit switch (Blind movement)
Gets the distance a motor will move off the home limit switch, after homing to the limit switch (Blind movement)
Example Input
echo_on<CK><LF>
echo_off<CR><LF>
help<CK><LF>
checksum_on<LF>
checksum_off<LF>
save_settings<CK><LF>
cam_on<CK><LF>
cam_off<CK><LF>
mctask_on<CR>
mctask_off<CR>
serial=Password123!,0000000000000451<CK><LF>
model=Cyberdyne_mod101<CK><LF>
f1_sethome_curr<CK><LF>
f1_sethome?<CK><LF>
f2_sethome_curr<CK><LF>
f2_sethome?<CK><LF>
a1_sethome_curr<CK><LF>
a1_sethome?<CK><LF>
f1_setpoint=+0000003286<CK><LF>
f1_setpoint?<CK><LF>
f2_setpoint=+0000003286<CK><LF>
f2_setpoint?<CK><LF>
a1_setpoint=+0000000050<CK><LF>
a1_setpoint?<CK><LF>
setpoint?<CK><LF>
f1_cam=0000000001,+0000003286,-0001340000<CK><LF>
f1_cam?0000000001<CK><LF>
f2_cam=0000000002,+0000003286,+0000560000<CK><LF>
f2_cam?0000000002<CK><LF>
a1_cam=0000000008,+0000000008,+0000000150<CK><LF>
a1_cam?0000000008<CK><LF>
motor_mov_ustep=0,100<LF>
motor_mov_um=0,100<LF>
max_speed=0,1600<LF>
max_speed?0<LF>
motor_enc_coarse=0,4951<LF>
motor_enc_coarse?0<LF>
motor_enc_fine=0,4951<LF>
motor_enc_fine?0<LF>
clear_stop=0<LF>
enc_cal=0<LF>
enc_n_cal=0<LF>
goto_limit=0<LF>
gohome_from_n=0<LF>
calibrate_from_reboot<LF>
valid_config=1<LF>
lens_pos?0<LF>
enc_n_distance=0,-1392<LF>
enc_n_distance?<LF>
home_limit_distance=0,-192<LF>
home_limit_distance?<LF>
Example Output TX Checksum RX Checksum
OK<CK><LF> 0x30 0xEF
OK<CK><LF> 0x8E 0xEF
Please refer to…<CK><LF> 0xFE 0xE4
OK<CK><LF> 0x6E 0xEF
OK<CK><LF> 0x66 0xEF
OK<CK><LF> 0xD4 0xEF
OK<CK><LF> 0xC2 0xEF
OK<CK><LF> 0x20 0xEF
OK<CR>
OK<CR>
OK<CK><LF> 0x52 0xEF
OK<CK><LF> 0x79 0xEF
OK<CK><LF> 0x5B 0xEF
-0000877127<CK><LF> 0x7F 0x82
OK<CK><LF> 0x5C 0xEF
-0000877127<CK><LF> 0x80 0x82
OK<CK><LF> 0x56 0xEF
+0000015334<CK><LF> 0x7A 0x70
OK<CK><LF> 0x1C 0xEF
+0000003286<CK><LF> 0x00 0x73
OK<CK><LF> 0x1D 0xEF
+0000003286<CK><LF> 0x01 0x73
OK<CK><LF> 0x09 0xEF
+0000000050<CK><LF> 0xFB 0x65
+0000003286,+0000003286,+0000000050<CK><LF> 0x0A 0xF9
OK<CK><LF> 0x25 0xEF
+0000003286,-0001340000<CK><LF> 0x9C 0xB4
OK<CK><LF> 0x28 0xEF
+0000003286,+0000560000<CK><LF> 0x9E 0xB5
OK<CK><LF> 0x18 0xEF
+0000000008,+0000000150<CK><LF> 0x9E 0xA5
OK<LF>
OK<LF>
OK<LF>
+0000001000<LF>
OK<LF>
+0000002000<LF>
OK<LF>
+0000001983<LF>
OK<LF>
OK<LF>
OK<LF>
OK<LF>
OK<LF>
OK<LF>
OK<LF>
OK<LF>
OK<LF>
OK<LF>
OK<LF>
OK<LF>
Notes
This command never requires a checksum <CK>
This command never requires a checksum <CK>
Requires password to set serial number
CMD only works when CAM is disabled
CMD only works when CAM is disabled
12S, 4S-5S, and Iris setpoint in that order
Commands Parameters Units Range
WARNING: These commands may cause the system to become unst
without consulting Marcus Engineering. If the system does not oper
task N/A N/A N/A
pos_set= [motor][motor ustep position] usteps 0-2, -20000-20000
foc_set= [motor][distance] mm 0-2, 2000-100000
pterm= [motor][pterm] N/A 0-2, 0-16777215
pterm? [motor] N/A 0-2
iterm= [motor][iterm] N/A 0-2, 0-16777215
iterm? [motor] N/A 0-2
dterm= [motor][dterm] N/A 0-2, 0-16777215
dterm? [motor] N/A 0-2
current= [motor][ihold][irun] mA 0-2, 106-2007, 106-2007
enc_n_rst= [motor] N/A 0-2
offset_rst= [motor] N/A 0-2
campos_rst= [motor] N/A 0-2
encoder_pos? [motor] N/A 0-2
xactual? [motor] N/A 0-2
Data Formatting Command Class
ystem to become unstable if configured incorrectly, it is ill-advised to adjus
system does not operate correctly, reboot the system to clear non-persiste
ENGR
[int32][int32] ENGR
[int32][int32] ENGR
[int32][int32] ENGR
[int32] ENGR
[int32][int32] ENGR
[int32] ENGR
[int32][int32] ENGR
[int32] ENGR
[int32][int32][int32] ENGR
[int32] ENGR
[int32] ENGR
[int32] ENGR
[int32] ENGR
[int32] ENGR
LCS Serial Commands V1.20
Details
ble if configured incorrectly, it is ill-advised to adjust these settings
e correctly, reboot the system to clear non-persistent settings.
Displays SCP task parameters
Sets the value for the current position for motor_X (Need to also set focus value!)
Sets the value for the current focus for motor_X (Need to also set position value!)
Sets the P term for the motor_X PID loop (Non-persistant)
Gets the P term for the motor_X PID loop
Sets the I term for the motor_X PID loop (Non-persistant)
Gets the I term for the motor_X PID loop
Sets the D term for the motor_X PID loop (Non-persistant)
Gets the D term for the motor_X PID loop
Sets the hold and run current for motor_X in discrete increments (Rounded to lowest value)
Resets encoder N position for motor_X
Resets home offset for motor_X
Resets cam position for motor_X
Reads the encoder position for motor_X (usteps)
Reads the controller actual position for motor_X (usteps)
nds V1.20
Example Input
task<CR>
pos_set=0,0<LF>
foc_set=0,0<LF>
pterm=0,1000<LF>
pterm?0<LF>
iterm=0,1000<LF>
iterm?0<LF>
dterm=0,1000<LF>
dterm?0<LF>
current=0,423,1056<LF>
enc_n_rst=0<LF>
offset_rst=0<LF>
campos_rst=0<LF>
encoder_pos?0<LF>
xactual?0<LF>
Example Output TX Checksum RX Checksum
Task info…<CR> 0x08 Variable
OK<LF>
OK<LF>
OK<LF>
+0000001000<LF>
OK<LF>
+0000000250<LF>
OK<LF>
+0000000000<LF>
OK<LF>
OK<LF>
OK<LF>
OK<LF>
+0000000000<LF>
+0000000000<LF>
Notes
LCS Serial Comm
Error Message
Failed: No error set.
Failed: Invalid input.
Failed: Invalid command name.
Failed: Incorrect number of parameters.
Failed: One or more parameters are invalid.
Failed: A command is already running.
Failed: The system state is not valid for this command.
Failed: The command encountered an internal error.
Failed: Command output could not be converted.
Failed: This command has not yet been implemented.
Failed: Invalid checksum.
LCS Serial Commands V1.20
RX Checksum Error Importance
0x95 N/A
0xCD N/A
0xA9 Low
0xBD Low
0xCB Low
0x81 Critical
0x24 N/A
0xB4 Critical
0x2B Critical
0x66 N/A
0x5C Low
Error Cause
No error, or an internal error has occurred, but was not properly flagged
Unused error code
Command input does not match any known commands
Number of data parameters is too high, or too low
One or more paramaters are formatted incorrectly
Command is taking too long to execute
Unused error code
Internal error has occurred
Output formatter error, or output data length exceeds the maximum
Unused error code
Checksum value is is incorrect (Or is missing)
scp_command_error_t
SCP_CMDERROR_NONE
SCP_CMDERROR_PACKET_INVALID
SCP_CMDERROR_COMMAND_INVALID
SCP_CMDERROR_PARAM_COUNT
SCP_CMDERROR_PARAM_INVALID
SCP_CMDERROR_COMMAND_RUNNING
SCP_CMDERROR_STATE_INVALID
SCP_CMDERROR_INTERNAL_ERROR
SCP_CMDERROR_OUTPUT_ERROR
SCP_CMDERROR_NOT_IMPLEMENTED
SCP_CMDERROR_BAD_CHECKSUM
LCS Serial Commands V1.20
Critical Error Code Error
0 No Error
1 Controller 0 communication failure
2 Controller 1 communication failure
3 Controller 2 communication failure
4 Controller 0 encoder n calibrate failure
5 Controller 1 encoder n calibrate failure
6 Controller 2 encoder n calibrate failure
7 Controller 0 motor home failure
8 Controller 1 motor home failure
9 Controller 2 motor home failure
10 Controller 0 debug motor move failure
11 Controller 1 debug motor move failure
12 Controller 2 debug motor move failure
13 Driver 0 communication failure
14 Driver 1 communication failure
15 Driver 2 communication failure
LCS Serial Commands V1.20
Error Cause
PCB Damage
Disconnected Data Cable between LCS Master and LCS Slave, LCS slave has no power
Disconnected Data Cable between LCS Master and LCS Slave, LCS slave has no power
Failure to locate encoder N mark, failure to move motor
Failure to locate encoder N mark, failure to move motor
Failure to locate encoder N mark, failure to move motor
Failure to detect limit switch, failure to move motor
Failure to detect limit switch, failure to move motor
Failure to detect limit switch, failure to move motor
Failure to move motor
Failure to move motor
Failure to move motor
PCB Damage
PCB Damage
PCB Damage
Only newest error is displayed (Single error reporting only).
