Command List for the Detector Head Electronics (DHE)
The following list describes the command and parameters available for
the detector controller electronics.
All the listed commands MUST begin with the prefix DHE. The system
is case INSENSITIVE.
The meaning of the simbology is:
< > : holds a parameter which is necesarry (mandatory)
[ ] : holds a parameter which is optional
| : separates possible values for an enumerated type.
Command prefix: DHE
1.- Observer Commands
This is the list of commands that will be normally used during an observation.
This are useful commands for the normal user.
1.1- Initialization
INIT <dhe_confpath>
description
Initializes the controller. After the completion
of this command, the system will be ready for taking images. The initialization
will perform basically the following steps:
opens the PCI driver,
resets the DHE,
loads the DSP working files (here are included the waveforms
for handling the detector),
sets the geometry of the system,
sets the working temperature,
executes any custom command(s) specified (can include
any command described on this document),
returns the status.
parameters
<dhe_confpath>: path to the configuration
file. The configuration file describes how the array and electronics should
be initialized. A detailed description on the configuration file can be
found on the Configuration File section.
1.2.- Exposure Setup
SET <param1>[=] <value1>
[, <param2>[=] <value2>, ... <paramN>[=]<valueN>]
description
Sets the parameter to the specified value.
parameters
The sintax can be "param=value" (with or without blanks) or just
"param val" (blank-separated). If there are multiples pairs, then they must
be separated by comma (,)
exposuretime <value> ['[s | ms]']
: sets the exposure time value for the next exposure. This
value will be held untill a new <exposuretime> command is issued.
If no time
unit is specified, it will assume milliseconds.
write_to_disk <yes | no>
: write the generated
image to disk or not
fowler <nsamples>
: sets the amount of fowler samples to perform (IR only)
coadd <ncoadds>
: sets the amount of coadds to perform
multipleextensions <yes | no>
: says if the format of the output images should be multiple
extension images or plain (single) fits images
displayimage <yes
| no> : says if
you want to automatically display the image (after read or RTD)
imagetitle <title>
: sets the title for the image
imagecomment <comment>
: sets a comment to appear on the headers
imagenumber <number>
: sets the starting
number for the sequence of images (see examples below)
imagestoread <number>
: sets the amount of images to be read
in the sequence
rootname <path+basename>
: sets the "rootname" for the image. This names INCLUDES the
path (see the examples below)
examples
DHE SET displayimage yes
DHE
SET exposuretime = 3.2[s]
/*would be equivalent to "3200 [ms]",
or just "3200" */
DHE
SET exposuretime = 3200, write_to_disk yes, imagetitle = this is a test
image, displayimage =no
DHE
SET rootname /home/wirc/images/dark, imagenumber 5, imagestoread 3
/*this says: read 3 images, which will be located
at
/home/wirc/images, and that will be
named
dark0005.fits -->
dark0008.fits
return value
DONE on success,
ERROR: <error message> [error code] on failure
IMPARAMS <rootname> <imagenumber> <exposuretime>
<imagestoread>
description
sets basic parameters for the image. This command is equivalent to
"DHE SET rootname = <rootname>, imagenumber = <number>, exposuretime
= <exptime>, imagestoread = <number2>" (see the SET command)
parameters
rootname
: the base name for the images. This name includes the Path
for the images, like /home/wirc/images/obj
imagenumber : initial image
number
exposuretime : exposure
time for images
imagestoread : number
of images to take
example
DHE SET imparams /home/wirc/images/obj 1 3.5 5
This command is saying: take 5 images, with numbers 1 to 5, with 3.5 seconds
of exposure time each, and writes those images on /home/wirc/images, with
names obj0001.fits -> obj0005.fits
return value
DONE on success,
ERROR: <error message> [error code] on failure
1.3.- Observation Commands
EXPOSE
description
Starts an exposition with the previously set parameters. An "exposition"
may consists on N images, each of which will have the same exposure time.
For the Infrared case, each image may have M coadds with K fowler samples
each.
return value
DONE on success,
ERROR: <error message> [error code] on failure
ABORT
description
Aborts all the ongoing activity, as well as all the remainig activity on
the same exposure, returning the system to an "idle" state. This means that
if it is in the middle of an exposure, it will abort the exposure, the following
image read, and will skip all the remaining images if it was in a sequence.
After the abort, the system will be idle.
return value
DONE on success
ERR: <error message> [error code] on failure
STOP
desciription
Stops the current sequence, but waits untill the current image (the one
in progress) finishes normally. This means that if it is exposing, it will
wait untill the current exposure finishes, then it will read out and
write that image, and then will skip the rest of the images if it was in a
sequence. After the stop, the system will be idle
return value
DONE on success,
ERR: <error message> [error code] on failure
DISCARD
description
Discards current image, but continues with the next one. Thsi command will
abort only the current image, and will continue with the next ones.
return value
DONE on success,
ERR: <error message> [error code] on failure
PAUSE
description
Pauses the current exposure, by closing the shutter.
return value
DONE on success,
ERR: <error message> [error code] on failure (if not exposing it
will return an error)
RESUME
description
Resumes a paused exposure, opening the shutter
return value
DONE on sucees
ERR: <error message> [error code] on failure (if
not paused it will return an error)
RESET <controller | pci>
description
Resets the specified device
parameters
controller : restes the hardware controller. After this,
a new "INIT" command should be sent
astropci
: resets the PCI card on the computer.
1.4.- Status Commands
GET <param>
description
It wil return the current value of the specified parameter
parameters
All the parameters described under "SET" apply here. This means that
any parameter that it is possble to set, it is possible to get. Beside the
already described parameters, we have:
progress
: It will return a multiline string with status information about the exposure
progress. The sintax of the returned string is:
read = <value>\n
/* percentage of readout*/
write = <value> \n
/* percentage of writting */
exposure = <value>\n
/* amount of elapsed exposure time, in miliseconds */
image = <imname> \n
/* current image
*/
state = <reading | reseting | exposing
| idle>\n /* status
of the system*/
return value
The value of the specified parameter, on success
ERR: <error message> [error code] on failure
examples
DHE GET exposuretime [s]
/*if no unit specified, it will return [ms]
>> 32.20 [s]
DHE GET displayimage
>> yes
DHE GET progress
>> read = 0
/* no read has been perfromed
yet */
write = 0
exposure = 7100
/* msecs of elapsed exposure time */
image = /home/wirc/images/obj0120
state = exposing
2.- Engineering and Setup commands
This is a set of engineering commands, used for testing the system and configuring
it. This commands are normally not requiered to be changed byt the observer
(and not recommended to)
2.1.- Utility Commands
<DO | PERFORM> [command] <action>
<value>
description
Performs actions that must be done inmediatelly, rather than seting for posterior
using.
parameters
[command] : this optional parameter can contain any command header described
on this document, like SET, or MEMORY.
<action> : if the alternate command is there, this value
can be anyone that is valid for that command (see the examples below).
If the command option is not, then this parameters can have the followig
values:
power <on | off>
: brings the power to the detector (biases, clocks, etc)
shutter <open | close>
: opens or closes the shutter
tdl <board> <value to write>
: "test data link". This command places a value on the specified board, and
then reads it back to see if the target is alive and responding or not. <board>
is the target board name. For example, under an SDSU DHE system, it can be
: timing, utility, or pci. The value can be any number (less than 24 bits)
examples
DHE DO power on
/* brings the power to the detector */
DHE DO tdl timing
144
/*sends the value 144 to the timing board*/
DHE DO SET exposuretime=3.2
/* same that DHE SET exposuretime 3.2 */
return value
if [command] is specified, it will rspond according to the specification
of that command
tdl will return the value sent on succes, and a diferent value, or ERR <error
message> on failure
power and shutter will return DONE on success, and ERR: <error message>
[error code] on failure
2.2.- Memory Commands
MEMORY <action> <parameter1> [... <parameterN>
]
description
This set of commands will perform the specified actions over the DHE memories.
This commands does not perform any kind of verification about the security
of the command being issued, so it must be used carefully or yoy can run
the risk of overriding some vital part of the memory.
parameters
<action>: actions are the actual
operation to apply. The parameters will change according to it. The possible
values are:
write <board> <memtype> <address> <value>
:
<board> is the name
of the target board (in SDSU: <timing | utility | pci>)
<memtype> is the
memory type (in SDSU: <X | Y | P | D>)
<address>
: the memory address to write
<value>
: the value to write on the specified place
read <board> <memtype> <address>:
<board>
is the name of the target board
<memtype>
is the memory type
<address>
: the memory address to read
load <board> <type> <location>:
<board> is the name of
the target board
<type>
: the type of loading you want to perform (in SDSU: <file | app>
)
<location>
: where to find the source for the loading (in SDSU: If <file>
whas specified, then it is the file path. If <app> was specified,
then it is the application number)
manualcommand <board> <arg1> <arg2> <arg3>
<arg4> <arg5> <command>:
specifies
a low level command to be sent to the controller. In an SDSU system, this
command is used for sending values to the DACs, adjusting the type of gain,
switching the multiplexors, etc. (see the examples below). The arguments
depends on the <command> field, and the <command> field depends
on the specific commands than the DHE supports, and on the program it is
running (examples for SDSU are: 'SBN' (sets bias number), 'SMX' (set multiplexer),
etc)
examples
DHE MEMORY write
timing X 0 132 : wites the value 132
(decimal) to the location 0 of memory X, on timing board
DHE MEMORY write
utility Y 0xA 0x132: writes the value 0x132 (hexa) to the location 10 of
memory Y, on utility board
DHE MEMORY load
timing file /home/ArcVIEW/Modules/SDSU/config/DSPfiles/HAWAII-II/tim.lod
DHE MEMORY load
timing app 1
/*loads the timing board with the applicatio
program located on EPROM number 1 */
return values
manualcommand will return a value according to the command specified.
write and load will return DONE on success, and ERR: <error message>
[error code] on failure
read will return the memory value on success, and ERR: <error message>
[error code] on failure
2.3 Setup Commands
SET <param1>[=] <value1>
[, <param2>[=] <value2>, ... <paramN>[=] <valueN>]
description
Sets the parameter to the specified value.
parameters
temperature <value> [K | C]
: sets the
setpoint temperature of the array. If no unit is specified, it will assume
Kelvin dregrees (K) if it is positive, and Celcious (C) if it is negative
size <xvalue> <yvalue>
: sets the dimensions of the array. This value includes the total size of
the array (including overscan, etc)
geometry <trim> <datacols>
<datarows> <ignoredbias> <bias> : sets
the geometry of the array
gainspeed <gain> <speed>
: specifies the gain and speed
of the video chain
binning <xbining> <ybinning>
: specified the binning in horizontal
and vertical directions
idlemode <on | off>
: sets the array to idle or non-idle
mode
writeframes <framelist>
: This is valid only for IR system. The frame list says which frames the
user can write when performing a CDS. The valid names are: reset, exposed,
and substracted. For example, writeframes reset exposed, will write both
the reset and exposed frames for each CDS
artifdata <yes | no>
: sets the artificial or normal
data mode.
autoshutter <yes | no>
: sets the shutter mode of operation. If set, it will open automatically
when the exposure starts. If not, it will wait for an specific "open shutter"
command for opening.
3.- Configuration file
The DHE configuration file tells the system the basic information for
starting the specific controller/detector. This file is normally built and
tested for the engineers, and it is not normally changed by the observer.
The format of the file is:
[SECTION1]
key1 = val1
...
keyN = valN
[SECTION2]
...
The sections are:
[Lod]
Utility = <utility .lod file path>
Timing = <timing board .lod file path>
[Geometry]
DataColumns = <data size in x>
DataRows = <data size in y>
Trim = <trim value, in pixels>
Bias = <overscan value, in pixels>
IgnoredBias = <bias to ingonere in headers at the beginning of overscan,
in pixels>
[Binning]
x = <xbinning>
y = <ybinning>
[Readout]
PixelTime = <pixel time, in usecs]
SkipPixel = <time to skip a pixel, in usecs>
ShiftRow = <time to shift a row, in usecs>
SkipRow = <time to skip a row, in msecs>
[Misc]
ReadoutMode = <readout type, like quad amplifiers, or lower left, etc>
Temperature = <temperature setpoint>
Commands = <list of commands to execute after all the initialization has
been done. Commands are sepatared by comma>
Example: hawaii2.conf
[Lod]
Utility = /home/ArcVIEW/Modules/SDSU/config/DSPfiles/Hawaii-II/util.lod
Timing = /home/ArcVIEW/Modules/SDSU/config/DSPfiles/Hawaii-II/util.lod
[Geometry]
DataColumns = 2048
DataRows = 2048
Trim = 0
Bias = 0
IgnoredBias = 0
[Binning]
x = 1
y = 1
[Readout]
PixelTime = 3
SkipPixel = 0.1
ShiftRow = 9
SkipRow = 2.9
[Misc]
ReadoutMode = Hawaii_2
Temperature = 77
Commands = "power on, SET write_to_disk yes, SET multipleextensions no,
SET outputtype 32_bits_long, SET writeframes substracted"