ST5000 Commands

Change Log
Version Date Comments
1.0 11-Jun-2003 Initial Release
1.1 04-Aug-2003 Add more cmds
1.2 06-Jun-2005 Update for MkIID
1.3 09-May-2006 Add cmds for TLM control & tracker ID
1.4 ? Add tracker head & base cmds
1.5 04-Sep-2007 Add Trimming & Learn Mode
1.6 27-Feb-2008 Change shim cmds for NSROC
1.7 22-Nov-2010 Add blobmode
1.8 19-Feb-2011 Ensure agreement with st5k.y
1.9 27-Jul-2011 Add filename wrapping & mirror mode
2.0 02-Aug-2012 Add Graphics RAM (GRAM) commands

Introduction

The ST5000 has a Tcl command interpreter reading commands from the serial line. This page describes the command set of the ST5000. You can use ST5000 commands in Tcl command scripts.

The commands are grouped according to their basic functionality. Many are engineering-level commands that the typical user would not use. The typical user can find a quick-start guide here.

A note on notation: the ST5000 command monitor uses a powerful lexical analyzer to scan for commands and command arguments. This allows a rich and flexible command language. It can be difficult to describe, though, unless we use some shorthand notation. In the following command tables, words in plain text are exact, to be typed as written. Words in italics represent abstractions. For example, the abstraction boolean means you can type ON, OFF, ENABLE, or DISABLE. ON and ENABLE have the same effect. Here are the abstractions you will see in the tables below.

When you see this You can type this Comments
boolean on, off, enable, disable
adc adc1, adc2
dac dac1, dac2, dac3, dac4
axis yaw, pitch, roll
modify set, adjust use "set" to assign a value, use "adjust" to apply a delta to a value. Examples below.
angle many things... You can specify angles in any consistent way. Examples:
3h 31m 24s (angle expressed as time)
3h 31m (can omit seconds)
3h 24s (can omit minutes)
31m 24s (can omit hours)
3h (just hours)
31m (just minutes)
24s (just seconds)

You can also use degrees:
3d 31' 24" (with all the variations above)

voltage a number followed by "V" Examples:
6V
2.3V
-5.5V
uint unsigned integer -
sint signed integer Examples: 3, -4
float any numerical value Examples: 1, 3.1, -4, 1e5, -2.2e-4

The command groups are

ACS Commands

These commands affect the ACS hardware interface that interacts with the MarkIID ST5000.

flight boolean

Controls the flight/test bit. It is currently used by the Celestial ACS as an aliveness check when the tracker is idle.

test boolean

Controls the flight/test bit. It is currently used by the Celestial ACS as an aliveness check when the tracker is idle.

pit boolean

If this is asserted, then the ST5000 will run its Progressive Image Transmission task after each acquisition.

lis boolean

If this is asserted, then the ST5000 will run its Lost-In-Space attitude determination task after each acquisition.

acquire boolean

Acquires stars, then tracks.

listest boolean

If this is asserted, then the ST5000 will report a success on subsequent LIS attempts.

acs boolean

Enables special 48-byte CACS packets on the ACS I/O serial line.

hrtb boolean

Puts High-Rate-Track-Boxes onto the ACS Echo line. The high rate track boxes show the track boxes for the 8 brightest targets, at the same rate as normal telemetry.

axis modify angle

Changes the analog voltage on the DAC outputs. Mostly used for testing.
Examples:
yaw set 3d (apply a 3-degree error voltage in yaw)
pitch adjust 3' (add 3 arcminutes' of voltage to the current pitch error)

magnitude modify float

Changes the analog star magnitude voltage in the DAC output.
Examples:
magnitude set 3 (chooses a magnitude 3 star)
mag adjust 0.5 (makes the magnitude fainter by 0.5)

dac modify sint

Changes the raw counts being imposed on the given DAC. This is a lower-level command than the axis modify commands above. Those work in angles; these work in counts.
Examples:
dac1 set 0
dac3 set -4096
dac2 adjust -10

dac modify voltage

Changes the voltage being being asserted by the given DAC. This is a lower-level command than the axis modify commands above. Those work in angles; these work in voltage.
Examples:
dac1 set 0v
dac3 set -6v
dac2 adjust -2v

ADC Commands

These commands control the Analog-to-Digital converters that monitor the ST5000 hardware.

adc calibrate internal

Invokes the ADC calibration (see the ADC data sheet).

adc calibrate system

Invokes the ADC calibration (see the ADC data sheet).

adc read uint

Reads an ADC channel (0-7), prints out the value.

adc status

Reads and prints out the ADC status (see the ADC data sheet).

adc read uint

Reads the given ADC channel (0-15). With this command, you don't differentiate between the two ADCs. The channels are numbered 0-15, the first 8 referring to ADC1, the next 8 referring to ADC2.

adc read all

Reads all 16 channels on both ADCs and prints out the values.

Alignment Commands

These commands affect various alignment settings in the ST5000.

focal length modify float (mm)

Not implemented.

align e313 z1|x|z2 modify angle

Sets the mechanical alignment of the ST5000 with respect to the attitude control system. The ACS has its own reference frame. The ST5000 maps its tracking errors from its own internal reference frame into the frame of the ACS using these alignment angles.
The alignment matrix is computed using a 3-1-3 Euler angle sequence. The angles are used in the order z1, then x, then z2.

shim axis modify angle

Sets the shim angles for the ST5000. Shim angles indicate the amount by which the ST5000 is misaligned with respect to some fiducial, like an instrument optical axis or the ACS null. Instead of shimming the ST5000 with metal spacers, you can shim it electronically with these commands.
Example: take out 30" of alignment error in the ST5000 yaw axis
shim yaw set 30"
Getting the sign right: the ST5000 removes the shim error; therefore, if the ST5000 is reporting an unwanted error of 30", then you'd assign a positive value to the shim angle, which will then be removed by the ST5000.
The shim matrix is computed as a 1-2-3 Euler sequence.

shim take

Sets the shim angles for the ST5000 using the current tracking error.

shim reset

Resets the shim values to zero.

axis window modify angle

The ST5000 provides its 3-axis tracking errors in telemetry and at the outputs of three digital-to-analog converters. Each axis has a mapping between angle and voltage. The voltage range is fixed; the ST5000 can provide error voltages between -6 and +6 volts. As a function of angle, each axis has a negative saturation, then a linear region, then a positive saturation. These commands set the angular size of the linear region.
NOTE: the window is expressed by its half-width, not its full width. The default values are 20 arcminutes for yaw and pitch, and 200 arcminutes for roll.
The calculation is:
volts = (angle/window) * 6V
The voltage is further limited to the range (-6V, +6V).
Examples:
yaw window set 10' (sets the full linear range to be +/- 10 arcminutes)
pitch window set 10'

magnitude window modify float
magnitude m0 modify float

The ST5000 provides a measure of the brightness of the brightest trackable star. The V magnitude of the star is provided in telemetry, and a voltage proportional to the V magnitude is provided at the output of a digital-to-analog converter. The scaling from magnitude to voltage is programmable.
We map the magnitude onto a DAC value as follows: We map a certain range in magnitudes (the magnitude window) onto a certain range of voltages. In addition to the size of the magnitude window, we anchor its bright end at magnitude m0. We choose voltage v1 to be the voltage at the bright end (m0) and v2 to be the voltage at the faint end (m0 + window). Solving the equations
v1 = s * m0 + b
v2 = s * (m0 + window) + b
for the slope s and the y-intercept b, we get
s = (v2 - v1) / window (units are volts per magnitude)
and
v = s * (mag - m0) + v1.
Note: we now choose, as a default, v1 = 5V and v2 = 0V; a case where brighter stars cause higher voltages. This causes a negative value of s, showing that voltage decreases for numerically increasing (fainter) magnitudes.
Example: suppose you wanted the magnitude voltage to be +5V for 2nd magnitude stars, and 0V for 6th magnitude stars:
magnitude m0 set 2
magnitude window set 4

CSR Commands

CSR commands deal with the two ST5000 control/status registers csr1, csr2, and csr3. (CSR3 is the Graphics RAM CSR.)

csr1 read
csr2 read
csr3 read

Reads the given control/status register and print the value in hex on the command line.

csr1 set uint
csr2 set uint
csr3 set uint

Writes a value into the given control/status register. The whole byte is written, changing all 8 bits. To control individual bits, use the following commands.

csr1 uint boolean
csr2 uint boolean
csr3 uint boolean

Changes a bit in the control/status register. "csr1 0 on" would set bit 0 of csr1.

rama boolean
ramb boolean

Enables or disables the RAM A or B buffers. During frame grabbing, the CCD frame will be grabbed into an enabled buffer. If a buffer is disabled, its contents won't be disturbed by a frame grab.

sysaux1 boolean
sysaux2 boolean

Controls the SYSAUX bits. These bits are brought out as LEDs on the front panel, and are used by the ST5000 to indicate its activity during normal operations.

vdac boolean

Controls the video digital-to-analog converter.

camera boolean
cohu boolean

Controls the camera power.

shutter3 boolean
shutter2 boolean
shutter1 boolean

The electronic shuttering provided by the Cohu-1100 CCD electronics is controlled with a 3-bit value. These commands provide bit-level control over the shuttering. For higher-level control see the tracker commands.

gain high
gain low

The CCD amplifier gain is controlled by a digital potentiometer. This low-level command generates the step function.
Example:
gain up (sets the direction)
gain hign
gain low (one step is completed)
gain high
gain low (a second step is completed)

gain up
gain down

Sets the direction of the gain steps. See the description of the digital potentiometer.

gain step

Combines a "gain high" and "gain low" command to do a full step of the digital potentiometer.

gain sleep uint uint

Determines the width of the on and off pulses when changing the digital potentiometer.

camaux1 boolean
camaux2 boolean

The camaux bits are delivered to the sensor head, and could be used, for example, to control a shutter or a star simulator. They are currently unused.

graphics boolean

Enables or disables the display of Graphics RAM.

video boolean

Enables or disables the display of star video.

grama|gramb

Enables Graphics RAM A or B for combining with the video output. The GRAM that isn't enabled is available for writing by the CPU. You can't write the GRAM while it is selected for display.

Graphics Commands

gram bpr set 0x00-0xff

Enables Graphics RAM bitplanes. Any bit set in the mask will enable the corresponding graphics bit plane.

gram gir set 0-255

Sets the Graphics Intensity Register (GIR). Controls the brightness of the graphics overlay.

gram gpr set 0x00-0x1f

Sets the Graphics Page Register (GPR). Page numbers are 0-31.

grama/b tag x y z string

Writes the string to graphics ram at coordinates (x, y). z (0x00-0xff) specifies the bitplanes to write.

RAM Commands

These commands perform operations on the ST5000's frame buffers. The ST5000 has two frame buffers, each capable of holding a grabbed video frame, and two Graphics RAM buffers The ST5000 can grab into both frame buffers simultaneously. One frame buffer is typically used for tracking, the other for Progressive Image Transmission.

"rama/b" means you can type "rama" or "ramb". They select the frame buffers. "grama/b" directs the operation to the Graphics RAM.

rama/b copy
grama/b copy

Copies the video frame from the given frame buffer into the ST5000's main memory. The frame buffer should be disabled to prevent the frame grabber from updating it during the copy. The grabbing normally occurs each 100 ms; a copy into main memory takes about 400 ms. If the frame buffer is not taken "off line" using the "rama/b disable" command, then the grabber will be grabbing into it during the copy, corrupting the image.

rama/b line uint
grama/b line uint

Displays the given image line (in text form) from the given frame buffer.

rama/b load
grama/b load

Loads a previously saved on-sky image into the given frame buffer. After this, you can do a one-shot acquire command to locate the stars in the image, then a one-shot lis command to determine the attitude. The file loaded is /home/st5k/lis.field. The image must be in "field" format.

rama/b load filename
grama/b load filename

Loads a previously saved on-sky image of your choice into the given RAM. After this, you can do a one-shot acquire command to locate the stars in the image, then a one-shot lis command to determine the attitude. The image must be in "field" format.

rama/b save
grama/b save

Saves the given frame buffer to the ST5000's internal disk. The image is saved to a file with a time-tagged file name of the form st5k.yyyymmdd.hhmmss.rama.grab. The image is in "grab" format.

rama/b send
grama/b send

Sends the given RAM buffer down the serial line in the form of xmsg-encoded lines. The mighty ST5000 Graphical User Interface saves the image to the local (PC) disk.

rama/b set uint
grama/b set uint

For debugging. Sets all of the given frame buffer's bytes to the given value.

rama/b show
grama/b show

Prints out the given frame buffer's contents. We used this a lot during the frame grabber testing. Use "p" and "q" to move around in the frame buffer.

rama/b stats
grama/b stats

Performs a statistical analysis of the image in the given frame bufffer. You get a histogram of pixel intensities, and the mode, mean, and standard deviation of pixel values.

rama/b take

Captures an image into the given frame buffer. This command manages the ram enable/disable bits. The frame buffer is enabled before the grab, and disabled after the grab.

rama/b test
grama/b test

Tests the frame buffers by writing a value into each location, then reading it back out and checking for correctness.

System Commands

status

Shows general system status. Hard to read. Cryptic.

status procs

Shows the status of processes (worker IDs, interrupt counts, etc).

status acquire

Shows the status of the most recent target acquisition.

block

Blocks the command monitor until the next image stored interrupt happens. That is, the command monitor won't return with a new command prompt, and will not process an commands, until the next image is stored.

packets boolean

The ST5000 tasks occasionally write strings by using print statements in the code. The ST5000 can optionally wrap these strings into the xmsg protocol used for telemetry frames. This allows them to interleaved nicely in the presence of telemetry frames. This is enabled by default.

trace boolean

Turns on specially compiled debug statements. Leave this alone. This is used like this:
#ifdef DEBUG
if (trace) {
(void)fprintf(stderr, "debug message goes here\n");
}
#endif
I make sure I "#undef DEBUG" in released flight code to render the trace command inoperative.

peek uint (peek port#)

Does a peek (read) instruction on the given I/O port.

poke uint uint (poke port# value)

Does a poke (write) instruction on the given I/O port.

com boolean

Manages the transmitters of the RS422 ports.

noop

Executes a no-op (no operation) instruction. Huh?

quit

Causes all ST5000 tasks to quit. For normal boots, the tasks will automatically restart. For alt-boots (with the escape key held down), a shell prompt will appear.

Target Commands

target ra modify angle

Sets the target's J2000 FK5 Right Ascension.

target dec modify angle

Sets the target's J2000 FK5 Declination

target roll modify angle

Sets the target's J2000 FK5 Roll

catalog trim angle

Trims the triangle catalog to exclude triangles further than angle from the currently programmed target.

catalog learn

Modifies the loaded catalogs to contain the currently acquired list of stars.

catalog save

Saves the current star and t riangle catalogs (trimmed or learned or both) to internal disk. These custom catalogs have special names, user.cat.s.dat and user.cat.t.dat.

catalog custom

Loads the custom catalogs into memory.

catalog normal

Loads the normal (full-sky) catalogs into memory.

Tracker Commands

init

Initializes the ST5000 software values to their defaults.

tracker set uint

Sets the tracker ID. The telemetry packets contain this ID, which can be used to distinguish between multiple trackers or identify particular telemetry log files. The default is 0.

head set uint

Sets the sensor head ID. The telemetry packets contain this ID, which can be used to distinguish between multiple sensor heads or identify particular telemetry log files. The default is 0.

base set uint

Sets the controller box ID. The telemetry packets contain this ID, which can be used to distinguish between multiple controllers or identify particular telemetry log files. The default is 0.

acquire save boolean

Controls whether the acquire image is saved to the solid state disk.

filename wrap boolean

Controls how saved filed are named. With wrapping, you get names like "acq.00.grab", with the embedded number varying from 00 to 15. Newer files clobber older ones of the same name. With wrapping off, you get unique file names based on the current time: "st5k.20110727.165258.grab". Be careful not to fill up the solid state disk.

blobmode boolean

Activates "blob mode", which coarsens the shape/brightness criteria for trackable targets. In blob mode, the ST5000 will acquire and track the blob with the most light. Use this for blobby stars from big fibers, Venus, etc.

blobflux modify uint

Sets the blob flux threshold in counts. Blobs have to be at least this bright.

blobsize modify uint

Sets the blob size in pixels. Use this to frame your blob nicely in track box 0.

mirror mode boolean

Activates "mirror mode", in which the ST5000 is looking at the sky as reflected by a flat mirror.

save

Causes a file called "st5000.tcl" to be written onto the ST5000's internal disk. This file is read at boot-time, so the target, alignment, shim and DAC window settings will be retained between resets and power ups.

reset

Resets the alignment, shim and window settings to their default (factory) values.

reload

Not implemented.

frames set uint
load uint (deprecated)

Sets the integration time (and tracking rate). The time is given in frame counts. The basic frame rate is set by the video output of the CCD: 30 Hz (33.3 ms per frame). A frame count of 3 (default) means that each grabbed frame will be exposed for 100 ms. Tracking is performed at the rate of the frame grabber. A frame count of 15 would produce 500 ms integrations and a 2 Hz track rate.

shutter set uint

The ST5000's CCD supports an electronic shuttering mode that can limit exposures to small fractions of a second. The exposure times are given here. Note that the exposure time and the frame grabbing rate are independent of each other. If you set the frame count to 15 and set the shuttering to 1/1000 s, then you will get frames with 1/1000 s exposure at a rate of 2 Hz.

gain set uint

The ST5000's CCD has a programmable amplifier gain. 0 selects the highest gain, and 255 the lowest. The gain is non-linear; it is flatish between 0 and about 100, then falls down roughly linearly to about 200, then is flattish again to 255. We normally run at the highest gain setting (0).

gml

Runs the General Measurement Loop once. This just reads the ADCs.

gml boolean

Enables or disables the periodic running of the General Measurement Loop. This is enabled by default.

tlm

Runs the telemetry task once. A single telemetry frame is sent.

tlm boolean

Enables or disables the periodic running of the telemetry task. If enabled, a telemetry frame will be sent during each CCD readout. This is enabled by default.

tlm set uint

Sets the vertical sync number for launching the telemetry task. When tracking at 10 Hz, there is a repeating pattern of vertical sync interrupts from the sensor video. We number them as follows:
Sync # Description
0 the start of the readout
1 the end of the readout
2 halfway between the readouts
Sync 0 is traditionally used because the system is pretty idle during the readout, so we might as well send the telemetry packets then. Sync 2 is 33 ms earlier, so when sending the disturbance quaternion to the ACS, you gain some phase margin. Tests at Wallops indicate little difference. The default in version 4.21 is 2; in version 4.22 it is back to 0.

acquire

Runs the acquisition task once.

track

Runs the tracking task once.

lis

Runs the Lost-In-Space task once.

pit

Runs the Progressive Image Transmission task once.

track start modify uint

The ST5000 keeps a brightness-sorted list of trackable stars. The start value is where in the list it starts using stars. This is normally 1.

track count modify uint

The ST5000 will normally try to track all of the stars in its list. If you want to track a certain number of stars, modify the count.

track target uint

Normally the ST5000 will try to maintain the attitude of its acquisition frame. That is, zero error corresponds to the attitude the current track started with. It can be told, however, to boresight one of the stars on its acquisition list. This might be used to boresight the brightest star. If you want to boresight the nth brightest star, use this command. Note: the value of 0 has a special meaning: if the target number is 0, then the ST5000 will not try to boresight any star. The ST5000 will try to maintain the attitude of its acquisition frame. This is the default.

track sky (default, body frame mode)
track ccd (deprecated, tangent plane mode)

When tracking, the ST5000 can use one of two algorithms: tangent plane tracking or body frame tracking. In tangent plane tracking, the tracking image is treated as a 2-D projection, and the errors are derived using a linear least squares fit in X and Y. In body frame tracking, the stars are treated as an ensemble of unit vectors in 3-space, and a more sophisticated 3-dimensional least squares fit is used. The default is body frame tracking (track sky).
"track ccd" is a legacy mode used in early development, and you shouldn't use it.