Table of Contents

Previous Chapter

10.0 UNIX Manual Pages

10.1 ACISshell

NAME

ACISshell - run a shell from which the CTUE can get ACIS commands

SYNOPSIS

ACISshell

DESCRIPTION

ACISshell creates a TCP/IP socket at the port that the CTUE will connect to when accepting commands from the ACIS EGSE. Once the connection is established, the program executes a standard Bourne shell, which it indicates by displaying the ACISshell% command prompt.

This shell and all of the programs that it launches inherit the open socket descriptor that connects to the CTUE. (This socket descriptor is available in environment variable CTUE_CMD_SD.) To send commands to the CTUE use:

ACISshell% buildCmds < ACIS command script file | sendCmds | writeCCB

or:

ACISshell% cat < CTUE command block file > &$CTUE_CMD_SD

ACISshell tries to open port 541 for CTUE commands. This port number is in the range that only root can open. If ACISshell is not running with root priviledges, it will try to open port 7541 for CTUE commands. The appropriate port number must be entered in the CTUE's c:\windows\thernet.cfg file. The IP address of the host where ACISshell will run must also be entered in this file. The CTUE will connect only to the IP address and port indicated.

To connect to the CTUE, the user should first execute ACISshell and then use the CTUE's GUI to select ACIS commands from the Ethernet control section. ACISshell, like the CTUE, handles only a single connection. When that connection terminates, so does the program and so does the connection to the CTUE. However, commands can be sent repeatedly while the ACISshell% prompt is displayed.

AUTHOR

Demitrios Athens, MIT CSR

Ann M. Davis, MIT CSR for the network code.

SEE ALSO

writeCCB(1)

CTUE User's Manual

10.2 acisBepUnix

NAME

acisBepUnix - Simulate the ACIS Back End Processor

SYNOPSIS

acisBepUnix

DESCRIPTION

This program simulates the Back End Processor software on an Ultrix workstation. The program launches a command server program, cserver, to acquire command packets, and writes its binary telemetry to stdout. The cserver program is launched to establish a command socket on the local host machine. The used socket number is 7000. Command packets may be built and sent to the running simulation using buildCmds and cclient. Telemetry can be examined using psci or ltlm. (Note: Typically, a telemetry server, such as filterServer is setup to read stdout of the program and then distribute the telemetry to one or more clients. The clients then decode the received telemetry packets).

FEP hardware and software can be simulated using acisFepUnix. Each instance of a simulated FEP is a distinct invocation of acisFepUnix. The BEP simulator communicates with the simulated FEPs through shared memory segments.

OPTIONS

None

RESTRICTIONS

cserver must be in the user's search path.

This program is currently only supported for the DECstations running Ultrix.

FILES

None

SEE ALSO

cserver(1), cclient(1), acisFepUnix(1), buildCmds(1), psci(1), ipcs(1), ipcrm(1)

DIAGNOSTICS

Fatal Messages:

None

Warning Messages:

None

Informatory Messages:

Discrete Software Telemetry codes (LED codes) appear on stderr as they are written to the "hardware" by the flight software.

The message "WarmFuzzy" is written to stderr once about every 5 seconds.

Commands to the DEA are decoded and written to stderr.

10.3 acisFepUnix

NAME

acisFepUnix - Simulate the ACIS Front End Processor

SYNOPSIS

acisFepUnix fepId

DESCRIPTION

This program simulates a single Front End Processor software on an Ultrix workstation. The FEP is indicated by fepId. The FEP simulation program communicates with the BEP simulation program, acisBepUnix, using shared memory segments and signals. Images are loaded into the FEP simulation using fepImage2, which also uses shared memory and signals to communicate with the FEP process. The BEP program simulates a reset to the FEP simulation using the SIGUSR2 (31) signal. The FEP image loader program simulates FEP interrupts using the SIGUSR1 (30) signal.

OPTIONS

None

RESTRICTIONS

Only one acisFepUnix program with a given fepId may be active on a single machine at a time.

This program is currently only supported for the DECstations running Ultrix.

FILES

None

SEE ALSO

acisBepUnix(1), fepImage2(1), ipcs(1), ipcrm(1)

DIAGNOSTICS

Fatal Messages:

If the program fails to obtain shared memory segments, it will issue an error message to stderr and exit with a -1.

Warning Messages:

None

Informatory Messages:

During initialization, the program prints information about its shared memory segments to stderr.

When the FEP program is "reset" it prints a "Calling fepCtl()" message to stdout.

10.4 acispkts

NAME

acispkts - extract ACIS packets and pseudopackets from LRCTU output

SYNOPSIS

acispkts [-ep] [-np] [-nt]

DESCRIPTION

acispkts reads the stdout stream from the LRCTU handler, rctu2b, identifies individual ACIS telemetry packets, and writes them to the standard output stream, stdout.

Unless the -np option is specified, acispkts will generate one science frame pseudopacket and one engineering pseudopacket for every simulated LRCTU science pulse, at 2.05 second intervals. The science frame pseudopacket will contain the 32-bit BEP science pulse timestamp and a time-of-day clock value in IRIG-B format derived from the gettimeofday() system call. The origin of the IRIG day number is 0h, January 0 of the current year. CCSD major and minor frame counts start at zero. Engineering pseudopackets contain the 8 LED hardware status bits, recorded in two 16-bit data fields, one bit per nibble, e.g. status bits of `00110110' will be reported as 0x0011, followed by 0x0110.

OPTIONS

-ep

generate a user pseudoppacket (a formatId of TTAG_USER) whenever LRCTU or ACIS packet synchronization is lost. If this option is omitted, the information will be written to stderr, (see Diagnostics, below).

-np

suppress the writing of Science Header and Engineering pseudo-packets to stdout. The default behavior is to generate one of each for every equivalent science frame simulated by the LRCTU.

-nt

suppresses the printing of ACIS timestamp and LED information to stderr.

AUTHOR

Ann Davis <amd@space.mit.edu> and Peter Ford, <pgf@space.mit.edu>, MIT CSR

SEE ALSO

rctu2b(1), filterServer(1)

DIAGNOSTICS

* Acis Time: xxxxxxxx Bilevels: bbbbbbbb

this message is generated at 2.05 second intervals unless the -nt option is specified. xxxxxxxx is the BEP timestamp at the most recent science pulse time, and bbbbbbbb are the current LED values.

* Fill error: got 'string'

the character received from the LRCTU doesn't match the ACIS synchronization string, "fAos". If the -ep option is selected, this message will be written to stdout in a user pseudopacket (TTAG_USER). Otherwise, it will be written to stderr.

* Invalid ACIS packet length

the length of the current packet is less than 2 32-bit words or greater than 1024. If the -ep option is selected, this message will be written to stdout in a user pseudopacket (TTAG_USER). Otherwise, it will be written to stderr.

* Lost LRCTU frame synch, n bytes to recover

the expected LRCTU synch code (0x55aa) was not received. n bytes were skipped until the next synch was found. If the -ep option is selected, this message will be written to stdout in a user pseudopacket (TTAG_USER). Otherwise, it will be written to stderr.

* Questionable frame length n

the LRCTU frame length is neither 768 nor 744. If the -ep option is selected, this message will be written to stdout in a user pseudopacket (TTAG_USER). Otherwise, it will be written to stderr.

10.5 bcmd

NAME

bcmd - translate ACIS command script to binary

SYNOPSIS

bcmd [-V] [-r] [file]

DESCRIPTION

This Perl script reads a script of ACIS commands, checks syntax and field values, and writes the binary output to stdout, prefixing each command with a 4-byte header specifying the command type and RCTU channel code.

OPTIONS

-V

(show Version) write to stderr the RCS revision number of this command and of the IP&CL used to generate it.

-r

(raw mode) omit the 4-byte prefix to each command, which are all assumed to be software serial command. The presence of any hardware serial or pulse command will be considered illegal and bcmd will terminate abnormally.

SYNOPSIS

The bcmd command scripts obey the following rules: a "#" sign begins a comment and causes the remainder of the line to be ignored. Blank lines will also be ignored. Each command must appear on a single line, unless it ends with a "{" sign, in which case it continues on as many lines as necessary to define the block, each containing a single "keyword = value" statement, and terminating with a line containing a single "}". The keyword names are identical to those in the IP&CL structures tables.

In the following command lists, the construction "< x | y >" means "necessarily, either x or y\c ".

Software Serial Commands

add n cc badcolumn <{|file>
add n te badcolumn <{|file>
add n badpixel <{|file>
add n patch d d <{|file>
change n systemconfig <{|file>
continue n uplink <{|file>
dump n badpixel
dump n cc
dump n cc badcolumn
dump n dea
dump n huffman
dump n patchlist
dump n systemconfig
dump n te
dump n te badcolumn
dump n window1d
dump n window2d
exec n n
exec n d <{|file>
exec n fep d n
exec n fep d d <{|file>
load n cc d <{|file>
load n dea d <{|file>
load n te d <{|file>
load n window1d d <{|file>
load n window2d d <{|file>
read n d n
read n fep d d n
read n pram d d n
read n sram d d n
remove n patch <{|file>
reset n badpixel
reset n cc badcolumn
reset n te badcolumn
start n cc n
start n cc bias n
start n dea n
start n te n
start n te bias n
start n uplink d d d <{|file>
stop n dea
stop n science
wait n
write n d <{|file>
write n fep d d <{|file>
write n pram d d <{|file>
write n sram d d <{|file>

Hardware Serial Commands

halt bep program eeprom n n run bep select bep <a|b> select eeprom <programming|telemetry> set <warmboot|bootmodifier> <off|on> set radiationmonitor <high|low> verify eeprom n

Hardware Pulse Commands

<open|close> <door|vent|relief> <a|b> <openabort|closeabort> <door|vent> <a|b> <enable|disable> <dabake|daheater|dea|door|dpa|pressure|relief|vent> <a|b> <poweron|poweroff> <dabake|daheater|dea|dpa> <a|b>

Italicized arguments represent user-supplied values; those in normal type must appear unaltered, except that upper and lower case letters may be freely interchanged, except in file names. All numeric arguments may be entered as signed decimal integers or, if preceded by "0x", as unsigned hexadecimal integers. If preceded by "0" alone, they will be interpreted as unsigned octal integers.

Within parameter blocks, i.e. between the "{" and "}" characters, the following fields are determined from the command line and from other keywords, so they do not need to be specified:

ccBlockSlotIndex
checksum
commandLength
commandIdentifier
commandOpcode
deaBlockSlotIndex
teBlockSlotIndex
windowSlotIndex (in window1d and window2d blocks, only)

When a block contains fixed-length arrays, e.g. fepCcdSelect in teBlock, the values, 6 in this case, must appear on the same line, i.e.

fepCcdSelect = 0 1 2 3 10 10

When a block contains varying-length arrays of structures, e.g. windows in window2d, the structures must be defined in the following manner:

load 2 window2d 1 {
  windowBlockId	= 0x00000abc
  windows = {
    ccdId	= 0
    ccdRow	= 50
    ccdColumn	= 150
    width	= 99
    height	= 99
    sampleCycle	= 1
    lowerEventAmplitude	= 0
    eventAmplitudeRange	= 65535
  }
  windows = {
    ccdId	= 0
    ccdRow	= 250
    ccdColumn	= 350
    width	= 99
    height	= 99
    sampleCycle	= 1
    lowerEventAmplitude	= 0
    eventAmplitudeRange	= 65535
  }
}

AUTHOR

Peter G. Ford, MIT CSR

SEE ALSO

buildCmds(1), lcmd(1)

DIAGNOSTICS

* command: bad wait time

the waiting time (in seconds) must be a positive integer.

* command: command not implemented

some hardware serial commands, e.g. "set EEPROM", are unimplemented in this version of bcmd.

* command: command packet too long: n bytes

no commands can contain more than 256 words (512 bytes). Longer packets, e.g. large patches, bad pixel or column table loads, must be split up into smaller data sets and resubmitted.

* command: illegal in raw mode

hardware serial and pulse commands are illegal when the -r flag is used.

* command: unknown command

bcmd does not recognize the command, either because of its leading command word or because it is followed by incorrect keywords.

* command: unrecognized keyword: word

the named word is not legal for this particular command.

* name: bad field offset: bits

the starting offset of a table or data array must be an exact multiple of 16 bits. This error should not occur in a fully debugged version of bcmd.

* name: field missing from block definition

the input script contained no value for the name field.

* name: illegal field value: n

the value n supplied for field name was outside the limits defined for this field in the IP&CL structures table.

* name: missing data array

no array or data file was specified for a command that expects one.

* name: wrong number of field values: n, not m

the number of fields supplied for name did not match that in the IP&CL structures table.

10.6 buildCmds

NAME

buildCmds - generate an ACIS binary command stream

SYNOPSIS

buildCmds [-a] [-i] [-l item] [-m] [-p] [-?]

DESCRIPTION

buildCmds creates a binary ACIS command stream from a script read from stdin.

OPTIONS

-a

output command packets in hexadecimal to stdout. default: output binary to stdout.

-i

print the release number of the IP&CL used to generate commands.

-l item

if item is "blockList", print a list of valid parameter block keywords. otherwise, print a list of valid parameter keywords used to define the parameter block named item.

-m

format a single parameter block. Default: buildCmds accepts a series of commands, some of which may contain parameter blocks

-p

omit the 4-byte command type and channel headers. Default: prefix each command block with type and channel identifiers.

-?

print a description of buildCmds options.

COMMAND SCRIPTS

The input script consists of one or more lines of ASCII text. Blank lines, and all text following the first instance of a `#' character within a line, will be treated as comments and ignored. All other lines must contain one or more tokens, separated by whitespace (blanks or tabs). The first token must be a recognized command as listed below. The second token must be a numeric cmdId. All tokens are case insensitive, file names must be strings in small letters. The underlined tokens indicate values introduced by user, the not underline tokens are keywords.

The full syntax is as follows:

command cmdId [ arg_1 ... arg_n ]

command

the action to be executed by the ACIS instrument or by its EGSE.

cmdId

a decimal integer in the range 0-65535, identifying the specific command. It is used to identify the command reply in the telemetry packets.

The remaining arguments arg_1 ... arg_n depend on the particular command. They are of the following types:

address

a decimal or hexadecimal (`0x' prefix) number identifying a memory location.

length

a decimal or hexadecimal (`0x' prefix) number specifying the length of a memory segment.

memory

a mnemonic identifying the memory segment to which the action is applied, e.g: bep, fep, pram, or sram.

memoryId

a mnemonic identifying a subsection of memory by name, e.g: slotid.

param_block

the contents of an ACIS parameter block. Parameter blocks are represented by brace-enclosed command line lists of the form

{
  parameterBlockName = nameId
  keyword1 = value 1
  keyword2 = value 2
  .
  keywordN = value N
}

The value of the parameterBlockName keyword identifies the type of parameter block. Valid values are:

* arguments
* badcolumn
* badpixel
* ccblock
* configsetting
* deablock
* patches
* teblock
* window1d
* window2d

The parameterBlockName keyword is required, and must be the first keyword in the block definition. Keyword values are expressed as decimal or hexadecimal (`0x' prefix) integers. Any number of newlines may appear within the enclosing braces. Some parameter blocks, namely window1D, window2D, and, deaBlock, contain keywords followed by arrays of structures, each containing several keywords. In these cases, the special keyword arrayDim must be added immediately before the array to indicate its dimension.

Within the parameter block, and within each enclosed sub-structure, the order of keywords must follow the order in the IP&CL tables, i.e. ascending bit offset from the start of the block. Omitted keywords will be assigned default values-their most recently specified value, or zero if they have not yet been used in the block.

Each ACIS command must therefore appear on a separate input line. The only exception is that in-line param_blocks may contain newline characters within the enclosing braces.

---

SERIAL SOFTWARE COMMANDS

The following commands will be prefixed by a 4-byte header that sends them to the software serial command port of the DPA.

---

ADD

This command reads data to add in BEP memory and outputs a binary stream to the standard output, stdout, which contains the commands in the format requested by the ACIS software.

add cmdId badPixel paramBlock

add set of pixels to Timed Exposure Bad Pixel Map

add cmdId cc badColumn paramBlock

add set of columns to Continuous Clocking Bad Column Pixel Map.

add cmdId patch patchId address file

add a patch to the specified address corresponding to patchId slot.

add cmdId te badColumn paramBlock

add set of columns to Timed Exposure Bad Column Pixel Map.

When the entire block cannot be stick in one command, the buildCmds subdivides the parameter block into sections and outputs several commands.

A list of the parameter keywords contained in the parameter block is given in the example section.

Examples:

add 12 cc badColumn {
  paramBlockName = badColumn
  ccdId = 2
  ccdColumn = 34
}

add 23 te badColumn {
  paramBlockName = badColumn
  ccdId = 2
  ccdColumn = 34
  ccdId = 4
  ccdColumn = 5
}

add 15 badPixel {
  paramBlockName = badPixel
  ccdId = 2
  ccdRow = 4
  ccdColumn = 50
  ccdId = 5
  ccdRow = 4
  ccdColumn = 60
}

The two sets: ccdId, ccdColumn, and ccdId, ccdRow, ccdColumn, can be repeated until a maximum of TBD times. Note that the order of the keywords is significant-ccdId must precede ccdRow, which must precede the ccdColumn to which it refers.

A list of the parameter keywords contained in the parameter block is given in the example section.

Example:

change 22 systemConfig {
  paramBlockName = configSetting
  itemId = 2
  itemValue = 8
}

The set, itemId and itemValue, can be repeated until a maximum of TBD times.

file is the name of a binary file containing the data to uplink.

Example:

continue 35 uplink file

Example:

dump 35 badPixel
dump 36 cc badColumn
dump 37 te

fepId specifies the FEP memory where the function is located. The value is a decimal integer in the range 0-5. If the fep and fepId keywords are missing, the default memory is BEP.

argumentBlock contains the list of arguments used by the function.

Example:

exec 2 0x1111111

execute the function located in the BEP at address 0x11111111

exec 56 fep 5 0x12345678

execute the function located in the FEP 5 at address 0x12345678

exec 44 0x22222222 {

  paramBlockName = arguments
  functionArguments = 1111
  functionArguments = 3
}

execute the function located in the BEP at the address 0x22222222 with two arguments, 1111 and 3.

exec 24 fep 3 0x1234 {

  paramBlockName = arguments
  functionArguments = 2222
  functionArguments = 5
}

execute the function located in the FEP 3 at the address 0x1234 with two arguments, 2222 and 5.

cc, te, dea, window1D, and window2D are keywords identifying the parameter block to which the action is applied. In particular, cc specifies the Continuous Clocking parameter block, te the Timed Exposure parameter block, dea the DEA housekeeping parameter block, window1D and window2D respectively the Window 1-D and Window 2-D parameter block.

The parameterBlocks "window1D" and "window2D" contain an additional parameter name "arrayDim" which indicate the number of windows contained in the paramBlock. A list of the parameter keywords contained in the parameter block is given in the example section. As explained above, keyword order is significant.

Examples:

load 2 cc 3 {
  paramBlockName	= ccBlock
  parameterBlockId	= 2030
  fepCcdSelect	= 0 1 2 3 4 5
  fepMode	= 1
  bepPackingMode	= 2
  ignoreBadColumnMap	= 1
  recomputeBias	= 1
  trickleBias	= 0
  rowSum	= 8
  columnSum	= 6
  overclockPairsPerNode	= 8
  outputRegisterMode	= 2
  ccdVideoResponse	= 1 1 0 1 1 0
  fep0EventThreshold	= 100 100 100 100
  fep1EventThreshold	= 100 100 100 100
  fep2EventThreshold	= 100 100 100 100
  fep3EventThreshold	= 100 100 100 100
  fep4EventThreshold	= 100 100 100 100
  fep5EventThreshold	= 100 100 100 100
  fep0SplitThreshold	= 0   0   0   0
  fep1SplitThreshold	= 0   0   0   0
  fep2SplitThreshold	= 0   0   0   0
  fep3SplitThreshold	= 0   0   0   0
  fep4SplitThreshold	= 0   0   0   0
  fep5SplitThreshold	= 0   0   0   0
  lowerEventAmplitude	= 0
  eventAmplitudeRange	= 40
  gradeSelections	= 0
  windowSlotIndex	= 1
  rawCompressionSlotIndex	= 255
  ignoreInitialFrames	= 2
  biasAlgorithmId	= 2 2 2 2 2 2
  biasRejection	= 1 2 4 6 5 6
  fep0VideoOffset	= 1000 1000 1000 1000
  fep1VideoOffset	= 1000 1000 1000 1000
  fep2VideoOffset	= 1000 1000 1000 1000
  fep3VideoOffset	= 1000 1000 1000 1000
  fep4VideoOffset	= 1000 1000 1000 1000
  fep5VideoOffset	= 1000 1000 1000 1000
  deaLoadOverride	= 0
  fepLoadOverride	= 0
}

load 3 te 2 {
  parameterBlockName	= teBlock
  parameterBlockId	= 0x2345
  fepCcdSelect	= 0 1 2 3 4 5
  fepMode	= 2
  bepPackingMode	= 1
  onChip2x2Summing	= 0
  ignoreBadPixelMap	= 0
  ignoreBadColumnMap	= 0
  recomputeBias	= 1
  trickleBias	= 1
  subarrayStartRow	= 0
  subarrayRowCount	= 1023
  overclockPairsPerNode	= 16
  outputRegisterMode	= 0
  ccdVideoResponse	= 0 0 0 0 0 0
  primaryExposure	= 1
  secondaryExposure	= 10
  dutyCycle	= 0
  fep0EventThreshold	= 100 100 100 100
  fep1EventThreshold	= 100 100 100 100
  fep2EventThreshold	= 100 100 100 100
  fep3EventThreshold	= 100 100 100 100
  fep4EventThreshold	= 100 100 100 100
  fep5EventThreshold	= 100 100 100 100
  fep0SplitThreshold	= 0   0   0   0
  fep1SplitThreshold	= 0   0   0   0
  fep2SplitThreshold	= 0   0   0   0
  fep3SplitThreshold	= 0   0   0   0
  fep4SplitThreshold	= 0   0   0   0
  fep5SplitThreshold	= 0   0   0   0
  lowerEventAmplitude	= 0
  eventAmplitudeRange	= 65535
  gradeSelections	= 0
  windowSlotIndex	= 0
  histogramCount	= 0
  biasCompressionSlotIndex	= 255 255 255 255 255 255
  rawCompressionSlotIndex	= 0
  ignoreInitialFrames	= 2
  biasAlgorithmId	= 2  2  2  2  2  2
  biasArg0	= 10 10 10 10 10 10
  biasArg1	= 0  0  0  0  0  0
  biasArg2	= 1  1  1  1  1  1
  biasArg3	= 0  0  0  0  0  0
  biasArg4	= 0  0  0  0  0  0
  fep0VideoOffset	= 1000 1000 1000 1000
  fep1VideoOffset	= 1000 1000 1000 1000
  fep2VideoOffset	= 1000 1000 1000 1000
  fep3VideoOffset	= 1000 1000 1000 1000
  fep4VideoOffset	= 1000 1000 1000 1000
  fep5VideoOffset	= 1000 1000 1000 1000
  deaLoadOverride	= 0
  fepLoadOverride	= 0
}

load 4 dea 4 {
  paramBlockName	= deaBlock
  deaBlockId	= 123456
  sampleRate	= 4
  arrayDim	= 2
  ccdId	= 5
  queryId	= 2
  ccdId	= 5
  queryId	= 2
}

load 4 window1D 4 {
  parameterBlockName	= window1D
  windowBlockId	= 45
  arrayDim	= 3

  ccdId	= 1
  ccdColumn	= 2
  width	= 4
  sampleCycle	= 6
  lowerEventAmplitude	= 7
  eventAmplitudeRange	= 8

  ccdId	= 1
  ccdColumn	= 2
  width	= 4
  sampleCycle	= 6
  lowerEventAmplitude	= 7
  eventAmplitudeRange	= 8

  ccdId	= 1
  ccdColumn	= 2
  width	= 4
  sampleCycle	= 6
  lowerEventAmplitude	= 7
  eventAmplitudeRange	= 8
}

load 2 window2D 3 {
  paramBlockName	= window2D
  windowBlockId	= 50
  arrayDim	= 3

  ccdId	= 0
  ccdRow	= 490
  ccdColumn	= 490
  width	= 20
  height	= 20
  sampleCycle	= 0
  lowerEventAmplitude	= 0
  eventAmplitudeRange	= 64535

  ccdId	= 0
  ccdRow	= 500
  ccdColumn	= 500
  width	= 100
  height	= 100
  sampleCycle	= 1
  lowerEventAmplitude	= 0
  eventAmplitudeRange	= 64535

  ccdId	= 0
  ccdRow	= 0
  ccdColumn	= 0
  width	= 1023
  height	= 1023
  sampleCycle	= 0
  lowerEventAmplitude	= 0
  eventAmplitudeRange	= 0
}

The memory bank is identified by the keywords: fep fepId, sram ccdId, and pram ccdId. A missing memory indicates the bep memory.

address is an hexadecimal or decimal integer indicating the memory address where to start the reading. This value is in the range 0-0xffffffff for fep and bep memory reading, and in the range 0-0xffff for sram and pram reading.

length is an hexadecimal or decimal integer indicating the number of words to read. This value is in the range 0-0xffffffff for fep and bep memory reading, in the range 0-0xffff for pram and sram reading.

Example:

read 4 0x103d87a0 40

request to read 40 32-bit words in the bep starting from address 0x103d87a0

read 1 fep 2 0x10003400 2

request to read 2 32-bit words in the fep 2 starting from address 0x10003400

read 2 pram 2 0x2340 5

request to read 5 16-bit words in the pram 2 starting from address 0x2340

read 2 sram 4 0x1fff 5

request to read 5 16-bit words in the sram 4 starting from address 0x1fff

Example

remove 1 patch {
  paramName = patches
  patchId = 1
  patchId = 2
  patchId = 8
}

remove three patches: 1,2,and 8 from the patch list

cc, te, badPixel, and badColumn are keywords identifying the memory to reset. In particular, cc badColumn specifies the Continuous Clocking badColumn map, te badColumn the Timed Exposure parameter badColumn map.

Examples:

reset 4 badPixel

reset the badPixel Map

reset 6 te badColumn

reset the Timed Exposure badColumn map

reset 10 cc badColumn

reset the Continous Clocking badColumn map

cc, te, dea, and bias are keywords identifying the parameter block to which the action is applied. In particular, cc specifies the Continuous Clocking parameter block, te the Timed Exposure parameter block, dea the DEA housekeeping parameter block.

uplink is a keyword identifying the boot mode.

Examples:

start 22 te 4

start Timed Exposure science run with the parameters stored in slotId 4

start 33 cc 3

start Continous Clocking science run with the parameters stored in slotId 3

start 44 cc bias 0

start Timed Exposure bias calculation with the parameters stored in slotId 0

start 55 te bias 1

start Continous Clocking bias calculation with the parameters stored in slotId 1

start 66 dea 2

start Dea Housekeeping monitor with the parameters stored in slotId 2

start 77 uplink fileName

start the uplink boot with the data contained in the fle fileName

science, and dea are keywords identifying the task to stop.

Examples:

stop 22 science
stop 33 dea

The memory bank to write is identified by the keywords fep fepId, pram ccdId, and sram ccdId. A missing memory indicates the bep memory.

address is an hexadecimal or decimal integer indicating the memory address where to start the reading. This value is in the range 0-0xffffffff for fep and bep memory reading, and in the range 0-0xffff for sram and pram reading.

file is the name of the file containing the data to write in memory. The file size is limited by the memory bank where the data should be stored. If the data contained in the file cannot be loaded in one command, their content will be divided into sections and loaded by multiple commands.

Examples:

write 4 0x00002345 asm

write the content of the "asm" file in the bep at the address 0x00002345

write 5 fep 4 0x00000056 bsm

write the content of the "bsm" file in the fep 4 at the address 0x00000056

write 6 pram 4 0x0024 csm

write the content of the "csm" file in the pram 4 at the address 0x0024

write 7 sram 5 0x0034 dsm

write the content of the "dsm" file in the sram 5 at the address 0x0034

10.7 cclient

NAME

cclient - send commands to a command server process on a remote host

SYNOPSIS

cclient hostname socket_number

DESCRIPTION

cclient sends commands to a command server process, typically cserver, on a remote host.

EXAMPLES

The following UNIX pipe uses cclient as part of commanding ACIS:

ash% buildCmds < myCmdScript | sendCmds | writeCCB | cclient poplar 8000

AUTHOR

Ann M. Davis, MIT CSR

STATUS

The current version is working according to specification.

10.8 cserver

NAME

cserver - Read data from socket and write it to stdout

SYNOPSIS

cserver socketNumber

DESCRIPTION

This program waits for a connection to its socket, socketNumber, reads data from the connection and writes the read data to stdout. It continues to read and write data until the connection is broken by the client, and then waits for a new connect.

OPTIONS

None

RESTRICTIONS

This program can handle only one connection at a time.

FILES

None

SEE ALSO

cclient(1), socket(2), accept(2)

DIAGNOSTICS

Fatal Messages:

Various socket and connection error messages to stderr.

Warning Messages:

None

Informatory Messages:

When waiting for a connection, the program writes "Waiting for Connection" to stderr. Once a connection is attempted, the program writes a message indicating from which machine the attempt is being made, to stderr.

10.9 diff6

NAME

diff6 - compare multiple ACIS binary event files against each other

SYNOPSIS

diff6 [-v] file1 file2 [file3...file6]

DESCRIPTION

This program reads the binary ERV event files generated by psci, and compares them record-by-record. If it finds a mis-match, it attempts to re-synchronize.

OPTIONS

-v

run diff6 in verbose mode, writing informatory messages to stderr. If omitted, only one single error message will be written at the conclusion of the program.

EXAMPLE

The following pipe uses filterClient to read ACIS telemetry packets from emily, runs them through psci to decommutate them, generating both data files (the -l flag) and monitor records (the -m flag). The latter are passed through sciglue to scramble them, and on into monitorScience to display (hopefully) useful statistics on an X-window display.

filterClient -h emily | psci -v -l run123 -m | sciglue | monitorScience

While monitorScience is displaying fancy stuff on the screen, psci is doing the hard work of unpacking the bias maps and event files. The latter will be written to a series of disk files with names "run123.nrun.nfep.\fRerv.dat\fP", where run123 is a prefix inherited from the -l option of psci, nrun is a "science run index" that is incremented at the start of each science run, and nfep is the index of the particular FEP that generated the events. After psci has generated an end-of-run message, e.g.

stdin: scienceReport[54321,0] run 1 irig 12345:678 exp 2 fep ok ccd ok dea 0 bep 1

indicating that the event files have been written successfully, they may be compared by

diff6 -v run123.1.*.erv.dat

AUTHOR

Peter G. Ford, MIT CSR

SEE ALSO

psci(1)

DIAGNOSTICS

* count mis-matches reported

diff6 has found this number of mis-matches during the comparison.

* count records processed from each of count files. No problemo!

The message we hope for, but don't always get.

* file[rec,exp,row,col] != file[rec,exp,row,col]

a mis-match has occurred: the message includes the file names, the record numbers (starting at 0), and the exposure number, row, and column recorded in each.

* file: no data

the input file was empty.

* file: premature EOF

One (or more) of the input files ended before at least one of the others.

* too many input files

6 is the limit.

10.10 dumpring

NAME

dumpring - translate ACIS FEP ring buffer records to ASCII

SYNOPSIS

dumpring [file]

DESCRIPTION

This Perl script reads a FEP ring buffer file and lists its contents in ASCII on the standard output stream, stdout. If file is omitted, the input is taken from the standard input stream, stdin. Records are indexed by their exposure number and by the count of records of the same type generated by that exposure. All indices, including exposure numbers, start at 1. The record and field names are taken from fepBep.h.

AUTHOR

Peter G. Ford, MIT CSR

SEE ALSO

fepBep.h

DIAGNOSTICS

unknown code id for record nexp,nrec

the type code in record nrec of exposure number nexp is invalid.

BUGS

*

the contents of raw image rows and histograms are not reported.

10.11 fepCtlTest

NAME

fepCtlTest - simulate ACIS front end processor

SYNOPSIS

fepCtlTest [file]

DESCRIPTION

This command subjects the high-level ACIS front end processor software to a series of tests, directed by a script read from file, or, if omitted, from the standard input stream , stdin. All input lines are echoed to stderr, with the following additional output, detailing the interaction between the FEP and the (simulated) BEP:

BEP COMMAND name [ parm ... ]

a command has been received from the simulated BEP mailbox

FEP REPLY TYPE=type CODE=retc

the FEP is replying to a BEP type command with a return code retc.

FEP REPLY TYPE=type MODE=mode BIAS=flag PARITY=addr OCLK=(n,n,n,n)

the FEP is replying to a BEP_FEP_CMD_STATUS command.

file: usec user ssec sys

an image frame has been processed, using usec seconds of user CPU time and ssec seconds of system CPU time.

file: bias0 = { n, n, n, n }

A bias map has been calculated. The initial overclock averages are shown.

EOF on stdin

The input script has been processed.

COMMAND LANGUAGE

dumpbias file

write a bias map to file in FITS format.

exec cmd

execute a BEP command. The names are as defined in the IP&CL nodes, e.g. BEP_FEP_CMD_STATUS, BEP_FEP_CMD_PARAM, etc.

fidpix = row col ...

define one or more fiducial pixels.

fidpix = bad

issue a null-length fiducial-pixel command.

param name = val

set an internal parameter field. name is a member of the FEPparmBlock structure as defined in fepBep.h, i.e. type, nrows, etc.

reset ctr

reset an internal counter. Currently, only wakeup is implemented.

set buf[row,col] = val

set the row and col element of buf (either "bias" or "biasparity") to val.

set input = file

read data from the FITS image. file should contain "%d" to be replaced with the exposure number.

set maxfile = n

set limit to input files

set output = file

write ring buffer to file

set overclocks = p1,p2, ...

specify ranges of overclock pixels

set pixels = p1,p2, ...

specify ranges of data pixels

set rows = r1,r2

specify range of input rows

stuff param name = val

set FEP parameter field

xor buf[row,col] = val

XOR value into a buffer Notes: The "param" command sets fields within the parameter block that will be sent to the FEP by "exec BEP_FEP_CMD_PARAM", whereas the "stuff" command updates the field directly in the FEP's FEPparmBlock parameter block, which tests the ability of the software to detect damaged parameters after they have been loaded.

The only "ctr" is "wakeup" which causes FIOgetNextCmd() to simulate BEP commands arriving while a FEP mode is running.

AUTHOR

Peter G. Ford, MIT CSR

SEE ALSO

dumpring(1), tlmsim(1)

DIAGNOSTICS

Bad xor command: text

the command must specify a legitimate row and column address

Unknown call: name

the entry point name is unrecognized

Unknown command: text

the command is unrecognized

file: bad bias checksum: n

the bias map checksum is invalid

file: bad rows value: n < n-1

the row count requested is incompatible with the FITS image size

file: file count exceeded

no more image files will be read in the current science run

file: too few rows: n < n

the row count requested is incompatible with the FITS image size

10.12 fepImage2

NAME

fepImage2 - Load an image into a Unix FEP Simulation

SYNOPSIS

fepImage2 fepId sequencer

DESCRIPTION

This program reads a DEA to FEP pixel stream from stdin and feeds the image to a running Unix FEP simulation process, which is simulating the FEP indicated by fepId. A Unix FEP simulation process (see acisFepUnix(1) ) must be running with the same fepId prior to using this program. The input for this program can be produced using several programs, including genObjectImage and loadFitsImage.

OPTIONS

None

RESTRICTIONS

This program is currently only supported for the DECstations running Ultrix.

FILES

None

SEE ALSO

acisFepUnix(1), genObjectImage(1), loadFitsImage(1), ipcs(1), ipcrm(1)

DIAGNOSTICS

Fatal Messages:

If the system attempts to write a pixel beyond the end the image memory (due to some internal error, or to a badly formed input image), the program write print the contents of some key FEP register values (from shared memory) to stderr and exit with a -1 exit code.

Warning Messages:

None

Informatory Messages:

If the program would be blocked by the FEP when trying to write an image, rather than discard the image, the program prints a "Dummy Image VSYNC - Sleep 3" message to stderr and then sleeps for 3 seconds. It will then re-attempt to load the image. This will continue indefinitely until either the FEP accepts the image, or until the program is aborted (usually via a Ctrl-C).

As the program loads the image into the FEP, it prints the current image start row, CCD start row and Row Count values used for the load to stdout.

10.13 filterClient

NAME

filterClient - receive ACIS telemetry from filterServer socket

SYNOPSIS

filterClient [-D] [-h host] [-m mode] [-p port]

DESCRIPTION

This Perl script makes a TCP connection to the specified filterServer port, and copies packets of type mode to the standard output stream, stdout.

OPTIONS

-D

run filterClient in debug mode.

-h host

specifies the name of the host running filterServer. If omitted, this is assumed to be the local machine

-m mode

selects the type of telemetry packets to be extracted from filterServer. mode is a string of between one and four letters, as follows:

s  science telemetry
e  engineering pseudo-packets
p  science frame pseudo-packets
h  DEA housekeeping packets

If omitted, the default is seph, i.e. extract all types of packet.

-p port

specifies the port number on the filterServer host. If omitted, the default is 7002.

AUTHOR

Peter G. Ford, MIT CSR

SEE ALSO

processScience(1)

10.14 filterServer

NAME

filterServer - Distribute ACIS telemetry to TCP clients

SYNOPSIS

filterServer [-D] [-S] [-b size] [-l file] [-n num] [-p port] [-v]

DESCRIPTION

This Perl script reads ACIS telemetry from its standard input and accepts connections from filterClient processes. It writes the buffered telemetry to each connected client, until that client disconnects. If an end-of-file occurs on its standard input, it disconnects all clients immediately.

OPTIONS

-D

run filterServer in debug mode, writing all I/O activity to the log file (if -l was specified), or to stderr if it wasn't. -D implies -v.

-S

sleep for 0.1 second after reading each input packet. This is intended to aid in debugging the filterClient process.

-b size

specifies the maximum size of each client's telemetry buffer. If a client's buffer grows larger than this amount, the socket to the client will be broken. The default is 1 MByte.

-l file

write a list of socket activity (opens and closes) to the log file (if -l was specified), or to stderr if it wasn't. -l implies -v.

-n num

specify the maximum number of concurrent connections. The default is 8.

-p port

specify the number of the TCP port on which filterServer listens for connections. The default is 7002.

-v

write a list of socket activity (opens and closes) to stderr.

AUTHOR

Peter G. Ford, MIT CSR

SEE ALSO

filterClient(1)

10.15 genObjectImage

NAME

genObjectImage - generate an ACIS pixel image from an ASCII script

SYNOPSIS

genObjectImage [-D] [-c cols] [-e] [-m mode] [-n count] [-o oclks] [-r rows] [-s iseed] [-u] [-v] [infile [outfile]]

DESCRIPTION

genObjectImage reads commands from infile (or, if omitted, from stdin), and generates a stream of pixels to outfile (or, if omitted, to stdout), in a format suitable for passing to the ACIS Image Loader.

OPTIONS

-D

for debugging purposes, writes the output in the form of a FITS image file, in the native byte ordering of the CPU, with the rows running top to bottom and the nodes, columns and overclocks from left to right, beginning with the columns and ending with the overclocks. For example, for 4 nodes (mode = ABCD), the four columns will be followed by the 4 sets of overclocks. Each set will be separated by a null pixel; two rows of null pixels will separate the columns from the overclocks. Pixel ordering within each column follows the CCD mapping order, i.e. nodes B and D are not reversed. Pixel OP codes (bits 0-3) are set to zero and VSYNC, HSYNC, and NOOP pixels are suppressed.

-c cols

specifies the number of columns per output node, overriding any "columns =" statement in the input script. If omitted entirely, the number depends on the "mode", 256 for ABCD, 512 otherwise.

-e

instructs genObjectImage to write a Last Pixel Flag (LPF) code at the end of the output stream, telling the frame buffer to start loading its data into the instrument. This flag must always be specified on the last, or only invocation of genObjectImage to load the frame buffer.

-m mode

selects the CCD quadrant readout mode that is to be simulated, overriding any "mode =" statement in the input script. mode must be either "ABCD", "AC", or "BD" (or their lower case equivalents). If omitted entirely, the default is "ABCD".

-n count

commands the frame buffer to write the following data to the instrument a total of count times. If omitted, the frame buffer loops continuously until reset. This option can only be specified on the first of a series of invocations of genObjectImage when loading the frame buffer.

-o noclks

specifies the number of overclocks to be used per quadrant, overriding any "overclocks =" statement in the input script. If omitted entirely, the default is 4.

-r rows

specifies the number of rows in the output image, overriding any "rows =" statement in the input script. If omitted entirely, the default is 1024.

-s seed

specifies a seed integer to be used to start the random number generator, overriding any "seed =" statement in the input script. If omitted entirely, the default is the value returned by a call to the time() function.

-u

omits the special image-loader codes. No compression is possible; stdout contains only valid FEP pixel codes.

-v

runs genObjectImage in verbose mode, writing a description of each node and display object to stderr, and summarizing the number of pixels in the output image.

INPUT SCRIPTS

A script consists of a series of ASCII statements of the form

keyword = value . . .

followed by zero or more object "call-outs" of the form

object row column

which will be described below. The script statements are case-insensitive\(emupper and lower case characters may be freely mixed. Each statement must appear on a separate line, but may be surrounded by any number of blanks and tabs. Any number of spaces or tabs may separate statement arguments.

Null lines, lines containing only whitespace, and lines whose first non-whitespace character is '#', are interpreted as comments, and ignored.

The statements are grouped logically into five classes:

* Global Parameter Assignments

These statements affect the entire output image. All except wedge and noop may be overridden by options on the genObjectImage command line, as described above.

columns = ival

The number of pixels to write for each output node. This may be overridden by the -c option. The default value is determined by the mode: 256 if ABCD, otherwise 512.

mode = string

The CCD output shift register mode to be simulated. Possible string values are ABCD, AC, and BD. This may be overridden by the -m option. The default value is ABCD.

noop = ival where what

The number of NOOP pixels to write between various parts of the output pixel stream. where may be either before or after. what may be either vsync, hsync, or oclks. That number of NOOPs will be written (for each of the 4 output nodes) before or after VSYNC or HSYNC OP codes, or before or after writing each row's overclock section.

overclocks = ival

The number of overclock pixels to write for each output node. This may be overridden by the -o option. The default value is 4.

rows = ival

The number of rows of pixels to write. This may be overridden by the -r option. The default value is 1024.

seed = ival

An integer to initialize the random number generator used when dbias or doverclock is non-zero.

wedge = drow dcol drowcol

Adjust all pixels in this image by adding

drow * irow + dcol *  icol + drowcol * irow *  icol

where the row index, irow, varies from 0 for the first row to rows-1 for the last, and the column index, icol, varies from 0 for the first pixel of node A to (nodes * columns - 1) for the first pixel of node D. This statement allows genObjectImage output to mimic various CCD behaviors, e.g., light leaks.

* Node Blocks

A node block, a group of statements delimited by "begin node" and "end node" statements, should be specified for each CCD output node that is to be simulated. It is good practice to define all 4, A, B, C, and D, even when the mode is AC or BD, since you may want to override it on the command line. The contents of the node block generates the background pixel and overclock values, on which the other display object are superimposed.

begin node = char

bias = ival

Initialize all data pixels (but not overclocks) in this node to the integer value, ival. This serves as a base on which to apply various adjustments.

dbias = fval

Adjust all pixels in this node by adding a zero-mean Gaussian random variable of variance fval. This mimics the real variability of CCD pixel values.

overclock = ival

Initialize all overclocks in this node to the integer value, ival. This serves as a base on which to apply various adjustments.

doverclock = fval

Adjust all overclocks in this node by adding a zero-mean Gaussian random variable of variance fval.

end node = char

* Event Blocks

Each event block, a group of statements delimited by "begin event" and "end event" statements, defines an array of integers to be added to the CCD pixel array. Each block is named, and these names are used later in the script (see "Object Call-outs", below) to perform this task, perhaps many times at different image locations.

begin event = name

columns = ival

The width of the values array.

rows = ival

The height of the values array.

values = ival ival . . . ival

A series of columns\(murows integer values to be added to the CCD pixel image. The values are supplied in row-major order, i.e. the first row values are followed by the second row, and so on. Within a row, the values are in ascending column order.

end event = name

* Blob Blocks

A blob block, a group of statements delimited by "begin blob" and "end blob" statements, specifies an elliptical artifact to add to the CCD image. It is defined by its width, height, orientation angle, and maximum (additional) pixel value. The blob is modeled as a double Gaussian in width and height. Each block is named, and these names are used later in the script (see "Object Call-outs", below) to perform this task, perhaps many times at different image locations.

begin blob = name

angle = fval

The rotation angle of the blob, in degrees counter-clockwise.

height = fval

The Gaussian width of the blob in the column direction, before rotating through angle.

value = fval

The additional pixel value of the center of the blob.

width = fval

The Gaussian width of the blob in the row direction, before rotating through angle.

end blob = name

* Object Call-outs

Zero or more statements of the form

name row column

where name represents a previously defined object (event or blob) which is to be added to the CCD image, centered at row and column. These call-outs are necessary for adding events and blobs\(emmerely defining them in "begin" blocks won't affect the image because their centers are undefined.

10.16 genPixelImages

NAME

genPixelImages - generate an ACIS image from a command script

SYNOPSIS

genPixelImages [-n] [-?]

DESCRIPTION

genPixelImages reads input commands from stdin and writes images to stdout in a format suitable for transferring to an "Image Loader". This format consists of 16 bit-words containing frame-buffer directives, FEP synchronization codes, and pixel and overclock values. Each image begins with four VSYNC codes and may contain from 1 to 1024 "rows", each beginning with four HSYNC codes. Each row may contain between 4 and 1024 "columns", divided into "nodes" (four in "ABCD" mode, two in either "AC" or "BD" mode), and followed by 0 to 15 pairs of overclocks per node. Note that the fourth, diagnostic, clocking mode generates no pixel values. It is therefore simulated by "ABCD" mode and no separate genPixelImages option is required.

Before generating any output, genPixelImages verifies (1) that the dimension of the images (number of rows, columns, and overclocks) are within ACIS constraints; (2) that the number and position of pixels and overclocks correspond to the image requested, i.e. each row contains the required number of pixels, followed by the required number of overclocks; (3) that each repeatRowBlock command operates on one or more whole rows.

OPTIONS

-n

do not reorder the image bytes.

-?

print option list

COMMAND SCRIPTS

The stdin commands consist of lines of ASCII text obeying a formal grammar. Each output image is described by a statement of the form

row n col m overclock o mode pixelDefinition

where n, m, and o are integers (m and o must be even) and mode specifies the CCD readout node configuration-ABCD, AC, or BD. These are followed on the same line by pixelDefinition- a series of commands that define the pixels and overclocks that will comprise the image.

The basic commands are

p v

which defines a single pixel with value v (an integer between 0 and 4095), and

c v

which defines a single overclock with value v (also an integer between 0 and 4095). A pixel or overclock value may be repeated by preceding the p or c command by r, e.g.

r n p v

generates a sequence of n pixels, each of value v. r, p, and c commands may be grouped by enclosing them in parentheses and repeated by prefixing the group with a repeatSec command, e.g.

repeatSec i ( r n p v r m c v )

repeats the commands within the parentheses a total of i times. This process continues until one or more full rows have been defined. A group of rows may be repeated with the repeatRowBlock command, e.g.

repeatRowBlock n [
  repeatSec n ( r n p v r n p v )
  repeatSec n ( r n p v r n c v )
]

Note that the repeatSec commands are grouped by enclosing them in square brackets. Similarly, repeatRowBlock commands may be grouped by enclosing them within braces, e.g.

row 200 col 1024 overclock 4 ac {
  repeatRowBlock 50 [
    repeatSec 2 (
      r 100 p 1 r 100 p 2 r 100 p 3 r 100 p 4 r 100 p 5
      r 100 p 6 r 100 p 7 r 100 p 8 r 100 p 9 r 100 p 10
      r 24 p 11 c 30 c 31 c 32 c 33
    )
  ]
  repeatRowBlock 50 [
    repeatSec 2 ( r 100 p 20 r 100 p 30 r 824 p 40 r 4 c 34 )
  ]
}

The last image must be followed by an end command. Blank lines, and all text between a "#" character and the end of that line, will be treated as comments and ignored.

genPixelImages locates each pixel in the 2-dimensional coordinate system of n rows and m columns defined by the physical CCD image store. Since the pixels are simultaneously sampled by 2 or 4 output nodes, genPixelImages must rearrange the pixel order according to the output node configuration. It also outputs VSYNC codes before each image, HSYNC codes before each row, and, only in AC or BD readout mode, a "null" pixel between each data pixel. It can also be instructed to add "null" pixels before or after synchronization codes, e.g.

row 8 col 8 overclock 4 delay vsync before 3 abcd [
  repeatSec 2 ( r 8 p 1 r 4 c 10 )
  repeatSec 3 ( r 4 p 2 r 4 p 8 r 4 c 30 )
  repeatSec 3 ( r 8 p 3 r 4 c 20 )
]

If genPixelImages is invoked with the single command go, it instructs the Frame Buffer to keep sending to the FEPs the image or images currently stored in its buffer, until commanded to halt. Alternatively, the image definitions may be prefixed with repeatFile n to repeat the images exactly n times. If this is omitted, the images will be repeated until the Frame Buffer is commanded to halt,

( genPixelImages <<EOF
repeatFile 1 row 8 col 8 ac {
  repeatRowBlock 8 [
    repeatSec 1 ( p 1 p 2 p 3 p 4 p 5 p 6 p 7 p 8 )
  ]
}
end
EOF
) | putImages

DETAILED EXAMPLES

The reported examples show the correspondence between input commands and pixel image represented by them, and illustrate the available command to control the transfer of the image to the "Frame Buffer".

Pixel Pattern

This example shows the use of pixel and overclock patterns with and without repetitions to define pixel image.

row 3 col 4 overclock 4 abcd (
  p 100 p 200 p 250 p 200      r 4 c 120
  r 4 p 240                    r 4 c 130
  r 4 p 150                    c 100 c 110 c 120 c 130
)

Image size: 3x4 + 4 overclocks. Image values row by row:

100  200  250  200    120 120 120 120
240  240  240  240    130 130 130 130
150  150  150  150    100 110 120 130

repeatSec

This example shows the use of repeatSec to define rows.

row 9 col 8 overclock 4 abcd [
  repeatSec 3 (r 8 p 40 r 4 c 15)
  repeatSec 2 (r 1 p 100 r 1 p 150 r 1 p 100 r 1 p 10)
  repeatSec 1 (r 4 c 8)
  repeatSec 2 (r 1 p 120 r 1 p 250 r 1 p 120 r 1 p 10)
  repeatSec 1 (r 4 c 8)
  repeatSec 2 (r 1 p 120 r 1 p 250 r 1 p 120 r 1 p 10)
  repeatSec 1 (r 4 c 8)
  repeatSec 3 (r 8 p 40 r 4 c 6)]
end

Image size: 9x8 + 4 overclocks per row.
Image values row by row:

  40  40  40  40  40  40  40  40   6  6  6  6
  40  40  40  40  40  40  40  40   6  6  6  6
  40  40  40  40  40  40  40  40   6  6  6  6
 100 150 100  10 100 150 100  10   8  8  8  8
 120 250 120  10 120 250 120  10   8  8  8  8
 100 150 100  10 100 150 100  10   8  8  8  8
  40  40  40  40  40  40  40  40   6  6  6  6
  40  40  40  40  40  40  40  40   6  6  6  6
  40  40  40  40  40  40  40  40   6  6  6  6

repeatRowBlock

This example shows the use of repeatRowBlock to generate images containing multiple equal blocks of rows

row 14 col 8 overclock 2 ac {
repeatRowBlock 2 [
  repeatSec 2 (r 8 p 10 r 2 c 8)
  repeatSec 2 (r 1 p 100 r 1 p 150 r 1 p 100 r 1 p 10)
  repeatSec 1 (r 2 c 10)
  repeatSec 2 (r 1 p 120 r 1 p 200 r 1 p 120 r 1 p 10)
  repeatSec 1 (r 2 c 12)
  repeatSec 2 (r 1 p 100 r 1 p 150 r 1 p 100 r 1 p 10)
  repeatSec 1 (r 2 c 10)
  repeatSec 2 (r 8 p 10 r 2 c 8) ]
repeatRowBlock 2 [
  repeatSec 1 (r 8 p 10 r 2 c 8)
  repeatSec 2 (r 1 p 100 r 1 p 150 r 1 p 100 r 1 p 10)
  repeatSec 1 (r 2 c 10)
  repeatSec 2 (r 1 p 120 r 1 p 200 r 1 p 120 r 1 p 10)
  repeatSec 1 (r 2 c 10)
  repeatSec 2 (r 1 p 100 r 1 p 150 r 1 p 100 r 1 p 10)
  repeatSec 1 (r 2 c 10)
  repeatSec 2 (r 8 p 10 r 2 c 8) ]
}
end

The image size: 10x8 + 2 overclocks
The image values row by row:

  8   8   8   8   8   8   8   8    8  8
  8   8   8   8   8   8   8   8    8  8
100 150 100  10 100 150 100  10   10 10
120 200 120  10 120 200 120  10   10 12
100 150 100  10 100 150 100  10   12 10
  8   8   8   8   8   8   8   8    8  8
  8   8   8   8   8   8   8   8    8  8
  8   8   8   8   8   8   8   8    8  8
  8   8   8   8   8   8   8   8    8  8
100 150 100  10 100 150 100  10   10 10
120 200 120  10 120 200 120  10   10 12
100 150 100  10 100 150 100  10   12 10
  8   8   8   8   8   8   8   8    8  8
  8   8   8   8   8   8   8   8    8  8

Delay

This example show the use of delay to introduce time delays before beginning to image transfer.

row 8 col 8 overclock 4 delay vsync before 3 after 2 abcd [
  repeatSec 2 (r 8 p 100           r 4 c 10)
  repeatSec 3 (r 4 p 200 r 4 p 100 r 4 c 15)
  repeatSec 3 (r 8 p 150           r 4 c 120) ]
end

The image loading is delayed by the insertion of three NULL pixels before and two after the VSYNC code. No delay is introduced between rows.

repeatFile

This example shows the use of repeatFile to send the same file multiple times to the "Frame Buffer".

repeatFile 2 row 22 col 8 overclock 4 abcd {
repeatRowBlock 2 [
  repeatSec 2 (r 8 p 1 r 4 c 10)
  repeatSec 3 (r 4 p 2 r 4 p 3 r 4 c 30)
  repeatSec 3 (r 8 p 4 r 4 c 20) ]
repeatRowBlock 3 [
  repeatSec 2 (r 8 p 5 r 4 c 33)]
}
end

The output image is preceded by a keyword requesting the "Frame Buffer" to repeat the loading of the same image twice.

AUTHOR

Rita Somigliana, MIT CSR <rita@space.mit.edu>

SEE ALSO

genObjectImage(1), loadFitsImage(1), putImages(1)

10.17 getPackets

NAME

getPackets - read AXAF-I telemetry frames and extract ACIS-related information

SYNOPSIS

getPackets

DESCRIPTION

getPackets reads a stream of AXAF-I telemetry frames from its standard input and writes a stream of ACIS telemetry packets and pseudo-packets to its standard output.

getPackets typically receives AXAF-I telemetry frames from SHIM. It extracts ACIS-related information and passes it to its client, which is typically filterServer. getPackets processes only AXAF-I telemetry formats 1 and 2. It accepts but ignores all other formats. It must first identify the current telemetry format -- either 1 or 2. In the former, ACIS science data is being generated at 512 bits/sec; in the latter at 24 Kbits/sec. In both cases, getPackets assembles the serial telemetry from ACIS, locates the individual packets by their synch words and lengths, and writes them to filterServer as a stream of separate logical records.

getPackets also sends filterServer two types of "pseudo-packet", i.e. records whose format mimics genuine ACIS telemetry packets but whose Format Tag codes are distinguished from those used by the instrument itself.

One type, the Science Frame Pseudo-Packet, contains telemetry-generated and ACIS-generated timestamps.

The other, the Engineering Pseudo-Packet, contains ACIS and other AXAF-I engineering data that resides in the non-science areas of the telemetry frames. getPackets determines the content of the engineering pseudo-packet by reading a file at run time. This file specifies the locations in the AXAF-I telemetry frames of the telemetry mnemonics that getPackets will extract and write as engineering pseudo-packets. The FILES section below explains how to specify which file getPackets will use.

The interface between getPackets and its various clients (via the filterServer/filterClient combination) may be described as a single stream of binary bytes, with no timing constraints.

getPackets writes a stream of telemetry packets and pseudo-packets to standard output. These are passed through filterServer to each filterClient, which writes a user-selected sub-set to its standard output. The four packet types that getPackets writes are: "ACIS Science Packets", "ACIS Analog Housekeeping Packets", "Science-Frame Pseudo-Packets", and "Engineering Pseudo-Packets". Each packet consists of a telemetry header followed by application data, as defined in the IP&CL. The header formats and contents are defined in Table 1.

TABLE 1. Header Format and Content

Packet Header Fields	Field Length (bits)	Science or Housekeeping Packet	Science Frame Pseudo-Packet	Engineering Pseudo-Packet
Synch	32	0x736f4166	0x736f4166	0x736f4166
Length	10	Varying1	7	Varying1
Format Tag	6	Varying	62	61
Sequence Number	16	incremented by 1 for each packet in the telemetry stream	02	02

¹ The packet length (number of 32 bit words) varies with the contents.
² The sequence number of a pseudo-packet is always zero.

The packet length (number of 32-bit words) varies with the contents.
The sequence number of a pseudo-packet is always zero.

All fields are written in "little-endian" format, e.g. the packet synch word, 0x736f4166, is written as 4 bytes, 0x66, 0x41, 0x6f, and finally 0x73. The contents of all packets originating within ACIS are defined in the IP&CL. The data portion of the Science Frame pseudo-packet is described in Table 2 and that of the Engineering pseudo-packet in Table 3.

TABLE 2. Science Frame Pseudo-Packet Format and Content

Field Name	Source			filterClient Output Format	Description
	Location	Start	Length
format	Virtual Channel ID	bit 10	3 bits	unsigned int	Frame format identifier, either 1 (signifying 512 bps) or 2 (24 kbps), i.e. the AXAF tlm code + 1.
majorFrameId	CCSDS Header	bit 16	17 bits	unsigned int	Virtual Channel Data Unit Major Frame Counter (0 to 131071)
minorFrameId	CCSDS Header	bit 33	7 bits	unsigned short	Virtual Channel Data Unit Minor Frame Counter (0 to 127)
irigb	Science Header	byte 32	6 bytes	unsigned short [3]	Time (msec) from the IRIG-B interface
bepSciTime	Science Data	byte 56	4 bytes	unsigned int	Latched version of the BEP science pulse 1 MHz timestamp
	Next-in-line Data	TBD

TABLE 3. Engineering Pseudo-Packet Format and Content

Field Name	Source			filterClient Output Format	Description
	Location	Start	Length
format	Virtual Channel ID	bit 10	3 bits	unsigned int	Frame format identifier, either 1 (signifying 512 bps) or 2 (24 kbps), i.e. the AXAF tlm code + 1.
majorFrameId	CCSDS Header	bit 16	17 bits	unsigned int	Major frame counter (0 to 131071)
followed by an array of one or more elements, each consisting of the following fields
data	variable location within major frame	var	8 bits	unsigned char	Engineering data
minorFrameId	CCSDS Header	bit 33	7 bits	unsigned char	Virtual Channel Data Uint Minor frame counter (0 to 127)
minorFrameByte				unsigned short	Byte number in the minor frame (0 to 1024)

The 6-byte IRIG-B timestamp in the AXAF-I minor frame is the result of packing 4 separate bit fields into a 48-bit string. However, getPackets treats the 6 bytes of the IRIG-B timestamp as 3 unsigned 16-bit integers. It copies them into the Engineering Pseudo-Packet and converts them to little-endian format, which is the ACIS standard. Table 4 describes how to decipher the Engineering Pseudo-Packet's irigb field.

TABLE 4. IRIG-B Field Format and Contents

Field Name	Bit Length	Byte	Word
Julian Day	11	0,1	0
Seconds	17	1,2,3	0,1
Milliseconds	10	3,4	1,2
Microseconds (always zero)	10	4,5	2

Each packet will be written to the getPackets standard output stream as soon as the last data byte that contributes to it is read from SHIM. A Science Frame Pseudo-Packet will be written after the last byte of each complete minor frame that contains a science data area header has been read. An Engineering Pseudo-Packet will be written after the last byte of each complete major frame is read.

EXAMPLES

The following UNIX pipe uses getPackets as part of commanding the ACIS instrument:

... | buildCmds | sendCmds | shim lrctu | getPackets | filterServer ...

FILES

$ACISTOOLSDIR

The path name of the ACIS Test Tools directory. If this variable does not exist in the user's environment, getPackets will exit.

$ACISTTMFILE

The name of the file that specifies the locations in the AXAF-I telemetry frames of the telemetry mnemonics that getPackets will extract and write as engineering pseudo-packets. If this variable exists in the user's environment, getPackets will attempt to open $ACISTOOLSDIR/lib/$ACISTTMFILE. If it doesn't, getPackets will attempt to open $ACISTOOLSDIR/lib/acisEng.ttm instead.

AUTHOR

Demitrios Athens, MIT CSR

STATUS

The current version should work with either the CTUE or the LRCTU (if its telemetry output is passed through ltp2mnf).

The current version is only capable of processing Format 2 telemetry. Its behavior if fed any other format is unknown but is liable to be objectionable.

The current version is implemented by having getPackets fork into 2 processes. One process, the original one as it turns out, reads AXAF-I telemetry and produces pseudo-packets. It also pipes the ACIS telemetry packet stream to the other process, which assembles and writes the ACIS packets. Both processes change their argv[0] environment value to either "axafFrames" or "acisPackets" as appropriate. This fools ps(1) into reporting the new name of each process. However, top(1) reports both as "getPackets."

10.18 lcmd

NAME

lcmd - list contents of ACIS command stream

SYNOPSIS

lcmd [-Bindent] [-V] [-lc] [-lh] [-lp] [-r] [-v] [-w cols] [file [file ...]]

DESCRIPTION

This Perl script reads one or more ACIS command files and writes a formatted listing to the standard output stream, stdout. If no input file is specified, lcmd reads the standard input stream, stdin.

The output consists of a series of "keyword = value" lines, in which the keywords are derived from the IP&CL field names, translating to uppercase all characters that immediately follow an embedded blank, and then removing the blank, e.g. "command length" is written as "commandLength". The "value" fields are rendered in decimal, with the following exceptions * 32-bit addresses and block IDs are in hexadecimal, prefixed with "0x"; * command tags are displayed as enumerated names, e.g. "CMDOP_LOAD_1D", followed by their decimal value in parentheses; * the timed-exposure "gradeSelection" value is written as a series of 8-character hexadecimal fields.

Each command begins with a header line of the form "name[n] = {", and ends with a matching right brace. Command blocks are separately numbered, starting at zero.

OPTIONS

-B n

inserts n blank characters at the start of each output line\(emused by ltlm when invoking lcmd internally. The default is to insert no blanks.

-V

write two lines to stderr reporting the RCS update level of this command and of the IP&CL structure description to which it refers.

-lc

does no processing; merely lists the names of ACIS software serial command blocks, their "commandIdentifier" codes, and decimal equivalents.

-lh

does no processing; merely lists the names of ACIS hardware serial commands, their IP&CL mnemonics, and hexadecimal equivalents.

-lp

does no processing; merely lists the names of ACIS high-level pulse commands, their IP&CL mnemonics, and their decimal and hexadecimal RCTU channel values.

-r

raw mode\(emthe commands are not assumed to be prefixed by 4-byte headers, two 16-bit binary integers containing the command type and channel number, respectively.

-v

becomes very verbose, listing the values of all large arrays. Otherwise lcmd will only list the number of elements in each array.

-w cols

sets the column width\(emarray values that exceed this width will be continued on the next output line. The default value is 73.

AUTHOR

Peter G. Ford, MIT CSR

SEE ALSO

The Web page "http://acisweb.mit.edu/ipcl", which tabulates ACIS command and telemetry packet formats.

DIAGNOSTICS

bad commandOpcode: code in packet n

the "commandOpcode" in command n is illegal. lcmd lists only the command header.

10.19 lerv

NAME

lerv - display contents of binary ERV event data files

SYNOPSIS

lerv [-N] [-V] [file]

DESCRIPTION

This Perl script reads an ERV event file, e.g. one generated by psci, and writes the contents of each record in ASCII to stdout. The ERV record data fields are as follows:

typedef struct {
	unsigned short	expnum;	/* exposure number [5] */
	unsigned short	exposure;	/* exposure time (msec) [5] */
	unsigned long	irigtime;	/* IRIG timestamp [8] */
	unsigned short	nodenum;	/* output node index [1] */
	unsigned short	col;	/* column index [4] */
	unsigned short	row;	/* row index [4] */
	unsigned short	data[9];	/* event data values [4] */
	short	doclk;	/* delta overclock [2] */
} RvRec;

They are written out as decimal numbers, right-justified with blank fill and separated by single blanks. The numbers in square brackets in the above definitions represent the minimum field widths. If the ASCII value of a particular field exceeds this, the remaining fields will be shifted right in the output line to accommodate it. Thus, although most output lines will contain 80 characters followed by a newline, some could be longer.

OPTIONS

-N

interpret the input field as big-endian (MSB first) integers. Use this flag to read a MSB event file, e.g. one created on a Sun, on a LSB machine, e.g. a DecStation.

-V

interpret the input field as little-endian (LSB first) integers. Use this flag to read a LSB event file, e.g. one created on a DecStation, on a MSB machine, e.g. a Sun.

AUTHOR

Peter G. Ford, MIT CSR

SEE ALSO

psci(1)

10.20 lhuff

NAME

lhuff - display contents of binary Huffman table block

SYNOPSIS

lhuff [-N] [-V] [file]

DESCRIPTION

This Perl script reads a binary Huffman table block, e.g. as created by psci, and writes the contents in ASCII to stdout.

OPTIONS

-N

interpret the input field as big-endian (MSB first) integers. Use this flag to read a MSB Huffman file, e.g. one created on a Sun, on a LSB machine, e.g. a DecStation.

-V

interpret the input field as little-endian (LSB first) integers. Use this flag to read a LSB Huffman file, e.g. one created on a DecStation, on a MSB machine, e.g. a Sun.

AUTHOR

Peter G. Ford, MIT CSR

SEE ALSO

psci(1)

DIAGNOSTICS

* file: bad table header

one of the 4-byte offsets at the beginning of file points beyond the end of the file.

* file: bad table length: n

the length of a single table exceeds that of the remainder of the file.

10.21 loadFitsImage

NAME

loadFitsImage - convert FITS file to FEP image load format

SYNOPSIS

loadFitsImage [-a] [-m mode] [-n noclks] [-o col1,...,col8] [-p col1,...,col8] [-r nrows] [-s row1] [-v] [file [file ...]]

DESCRIPTION

This command loads one or more FITS images and reformats them for an ACIS Image Loader, rearranging the pixels and overclocks according to the simulated CCD readout mode specified by the -m option. If the list of files is omitted, a single FITS image will be read from the standard input stream, stdin.

OPTIONS

-a

determine the image dimensions and the location of the valid pixels and overclocks from the FITS header keywords alone. When the -v flag is specified, the values of the -n, -o, -p, -r, and -s options are copied to stderr.

-m mode

selects the CCD quardant readout mode that is to be simulated. mode must be either abcd, or ac, or bd.

-n noclks

specifies the number of overclocks to be used per quadrant. At least this number must be available in each of the input FITS files.

-o col1,col2,col3,col4,col5,col6,col7,col8

selects the column limits of overclocked pixels in the 4 quadrants of the input FITS files. The pixels from quadrant A are located in columns col1 through col2 of each line, those of quadrant B in columns col3 through col4, etc. It is assumed that the input pixel order is as in the ACIS Memo cited below.

-p col1,col2,col3,col4,col5,col6,col7,col8

selects the column limits of good pixels in the 4 quadrants of the input FITS files. The first column is indexed 0. The pixels from quadrant A are located in columns col1 through col2 of each line, those of quadrant B in columns col3 through col4, etc. It is assumed that the input pixel order is as in the ACIS Memo cited below.

-r nrows

specifies the number of output rows to write, each of which will be followed by a HSYNC code.

-s row1

specifies the index of the first row in the input image (counting from 0) to write to the output.

-v

puts loadFitsImage into verbose mode, writing statistics to stderr, detailing the number of rows and columns of each output image.

AUTHOR

Peter G. Ford, MIT CSR

SEE ALSO

The Coordinate System of ACIS FITS Files, ACIS Memo, J. W. Woo and S. E. Kissel, December 7, 1994.

DIAGNOSTICS

EOF while reading FITS header

the input probably isn't in FITS format.

IcMAXCOL: header keyword missing

the -a option has been specified, but the FITS header doesn't contain sufficient information to specify the pixel locations.

IcMINCOL: header keyword missing

the -a option has been specified, but the FITS header doesn't contain sufficient information to specify the pixel locations.

bad pixel range in quadrant val

the number of pixels in each quadrant is not the same.

bad BITPIX value: val

the value of the FITS header keyword BITPIX must be 16.

bad NAXIS1 value: val

the value of the FITS header keyword NAXIS1 must be not less than 1024+4\(munoclks, where noclks is as specified in the -n option.

bad NAXIS2 value: val

the value of the FITS header keyword NAXIS2 must be not less than nrows+row1, where nrows is as specified by the -r option, and row1 by the -s option.

bad overclock offsets: list

the overclock column list must contain exactly 8 unsigned integers, separated by commas, without any other whitespace or punctuation.

bad pixel offsets: list

the pixel column list must contain exactly 8 unsigned integers, separated by commas, without any other whitespace or punctuation.

unable to allocate input buffer

the value of the FITS header keyword NAXIS1 is too large and loadFitsImage is unable to allocate a buffer to hold the input record.

unexpected EOF in record val

an end-of-file was encountered while reading record val of the input file, indicating that the file is truncated, or that one or more FITS header keywords are incorrect.

name: n lines, each n pixels + n oclks

generated by the -v verbose flag, this indicates that the FITS file name generated a number of output lines, each containing the specified number of pixels and overclocks.

BUGS

On-chip summation is not currently implemented. It is assumed that all output nodes generate either 256 pixels (ABCD mode) or 512 pixels (AC or BD mode).

10.22 logGet

NAME

logGet - get CTUE command abort log messages

SYNOPSIS

logGet

DESCRIPTION

logGet listens on the TCP/IP port number that the CTUE will try to connect to for sending command abort log messages. It prints any messages it receives on its standard output.

If logGet is run with root priviledges, it will listen on port 542 for a connection from the CTUE. If it is run with regular user priviledges, logGet will listen on port 7542. The appropriate port number must be entered in the CTUE's c:\windows\ethernet.cfg file.

logGet adds its own time stamp to each message.

EXAMPLES

The following UNIX command uses logGet as part of commanding ACIS:

acisEgseHost% logGet

AUTHOR

Ann M. Davis, MIT CSR

Demitrios Athens, MIT CSR

STATUS

The current version is working according to specification.

10.23 ltlm

NAME

ltlm - list contents of ACIS telemetry stream

SYNOPSIS

ltlm [-E] [-V] [-e type] [-f from] [-lc] [-lt] [-p type] [-s] [-t to] [-v] [-w cols] [file [file ...]]

DESCRIPTION

This Perl script reads one or more ACIS telemetry files and writes a formatted listing to the standard output stream, stdout. If no input file is specified, ltlm reads the standard input stream, stdin.

The output consists of a series of "keyword = value" lines, in which the keywords are derived from the IP&CL field names, translating to uppercase all characters that immediately follow an embedded blank, and then removing the blank, e.g. "command length" is written as "commandLength". The "value" fields are rendered in decimal, with the following exceptions * synch codes, 32-bit addresses, timestamps and block IDs are in hexadecimal, prefixed with "0x"; * command and packet tags are displayed as enumerated names, e.g. "TTAG_CMD_ECHO", followed by their decimal value in parentheses; * the timed-exposure "gradeSelection" value is written as a series of 8-character hexadecimal fields.

Each telemetry packet and embedded command block begins with a header line of the form "name[n] = {", and ends with a matching right brace. Each type of command block and telemetry packet is separately numbered, starting at zero. Embedded arrays of data structures are also numbered from zero, but the index is reset at the start of each array instance.

OPTIONS

-E

write two lines to perform extended error checking on ACIS packets. Currently, the only test is to verify that the packet sequence numbers are in ascending order. Missing or out-of-sequence packets are noted by messages to stderr.

-V

write two lines to stderr reporting the RCS update level of this command and of the IP&CL structure description to which it refers.

-e type

excludes output of those packets whose decimal "formatTag" value is type. Allowed values are tabulated by invoking ltlm with the -lt flag. Multiple -e options may be specified to exclude more than one type of packet.

-f from

don't list packets with "sequenceNumber" values less than from.

-lc

does no processing; merely list the names of ACIS command blocks, their "commandIdentifier" codes, and decimal equivalents.

-lt

does no processing; merely list the names of ACIS telemetry packets, their "formatTag" codes, and decimal equivalents.

-p type

restricts output to those packets whose decimal "formatTag" value is type. Allowed values are tabulated by invoking ltlm with the -lt flag. Multiple -p options may be specified to list more than one type of packet.

-s

print only a tally of packet statistics: the number of packets, the packet type, and its TTAG format code.

-t to

don't list packets with "sequenceNumber" values greater than to.

-v

becomes very verbose, listing the values of all large arrays within the telemetry packets. Otherwise ltlm will only list the number of elements in each array.

-w cols

sets the column width\(emarray values that exceed this width will be continued on the next output line. The default value is 73.

AUTHOR

Peter G. Ford, MIT CSR

SEE ALSO

The Web page "http://acisweb.mit.edu/ipcl", which tabulates ACIS command and telemetry packet formats.

DIAGNOSTICS

bad commandOpcode: code in packet n

the "commandOpcode" in packet n is illegal. ltlm lists only the command header.

bad formatTag: tag in packet n

the format tag in the header of packet n is illegal. ltlm ignores this packet and reads the next.

decompression unimplemented in packet n

this version of ltlm cannot list the values of compressed pixels in "dataCcRaw", "dataTeBiasMap", or "dataTeRaw" packets.

10.24 monitorScience

NAME

monitorScience - display ACIS run-time information on an X11 server

SYNOPSIS

monitorScience

DESCRIPTION

monitorScience creates a multi-window display, reads the stdout stream from processScience, and writes it into one of the windows.

monitorScience uses colors to signal various conditions: fatal anomalies are shown in red, warnings in blue. The initiation and termination of science or monitor requests are displayed in green. Colors are also used to distinguish decimal numbers (black) from hexadecimal numbers (brown).

Black and brown colors are also used to facilitate the reading of parameter names. In science data windows, they distinguish telemetry packet names (black) from parameter names (brown). In the Dea Housekeeping window, packet header fields are colored brown, and data fields black (see below). In Sw Housekeeping, packet header fields are brown, data fields are black, red, or blue, depending on the type of information displayed.

Normally, window backgrounds are colored "linen", but background of the most recently updated window is colored "white".

WINDOW LIST

Echo Command Packets

This window displays the command name, arrival time, execution time, and command ID of all commands echoed from the ACIS instrument. The list shows what commands were sent to the BEP, and the order in which they were executed.

Science General Parameters

This window displays information about any BepStartupMessage","Dump Parameter", and "Science Report" telemetry packets. It identifies the most recent science parameter block, and the result of the most recent science run.

Science Data

This window displays information about the most recent science and bias telemetry packets received from ACIS. The window is divided vertically into three regions -- two for science data and one for bias data -- and horizontally into six columns, one for each FEP. The first science data packet is displayed in the top window, the next in the middle window, the third in the top window again, and so on.

Fatal Messages

This window displays the time at which a fatal error was detected by the BEP and the corresponding error code and value.

Read and Write

This window displays information about the execution of write-to-memory commands, i.e. "Read Bad Columns" (TE and CC), "Read Bad Pixels", "Read System Configuration", "Read Patches", "Read Huffman Tables", and "Read Parameter Slots" (TE, CC, 2D window, 1D window, and DEA).

Sw Housekeeping

This window displays information about "Software Housekeeping" telemetry packets in the form of a table containing rows of two types. One contains the start and end times of the housekeeping collection period, the other contains the name, repetition times, and value of each monitored parameter.

Dea Housekeeping

This window displays information about "Dea Housekeeping" telemetry packets in the form of a table containing rows of two types. One contains the "Dea Block id" and "Command Id" of the most recent "Start Dea Housekeeping" command and the BEP time corresponding to the most recent housekeeping packet. The other contains monitor information:; the "Board Id", "Query Id" name and value.

ENVIRONMENT VARIABLES

ACISTOOLSDIR

must point to the top-level test directory within which the monitorScience modules are located, e.g. "~acis/toolstest".

TCL_LIBRARY

must point to the TCL run-time library, e.g. "$ACISTOOLSDIR/src/Other/tcl7.4/lib/tcl7.4".

TK_LIBRARY

must point to the TK run-time library, e.g. "$ACISTOOLSDIR/src/Other/tk4.0/lib/tk4.0".

AUTHOR

Rita Somigliana, MIT CSR <rita@space.mit.edu>

10.25 processDEAhkp

NAME

processDEAhkp - extract DEA query response data from a DEA housekeeping ACIS telemetry packet

SYNOPSIS

processDEAhkp -f outFileName [ filename... ]

DESCRIPTION

processDEAhkp reads DEA housekeeping ACIS telemetry packets either from the standard input or from one or more files specified as command line arguments. It rewrites the outFileName whenever it reads a DEA housekeeping ACIS telemetry packet from its input.

For each query response that the DEA housekeeping packet contains, processDEAhkp writes to the outFileName the ccdId, queryId, and value. The output is in ASCII and is the decimal value of the item in the packet. A blank delimits the end of each of the first two items and a newline delimits the end of the last item.

processDEAhkp expects its input to consist of DEA housekeeping ACIS telemetry packets. It silently ignores any other packets in its input. It also silently ignores the other elements of the DEA housekeeping ACIS telemetry packet: deaBlockId, commandId, and bepTickCounter.

processDEAhkp always removes any existing contents of outFileName when starting.

EXAMPLES

The following UNIX pipe uses processDEAhkp as part of monitoring DEA housekeeping information:

filterClient -h | processDEAhkp -f DEAhkp | monitorDEAhkp -f DEAhkp ...

AUTHOR

Demitrios Athens, MIT CSR <da@space.mit.edu>

STATUS

The current version has been been tested but not used extensively.

The current version does not ensure that its first argument is "-f" but simply assumes that its second argument, if present, is the outFileName. If the "-f" option is missing and processDEAhkp is to read its input from a file, then the contents of the first input file will be lost.

10.26 psci

NAME

psci - parse an ACIS serial telemetry stream

SYNOPSIS

psci [-DVacmpqsuv] [-h file] [-l prefix] [file]

DESCRIPTION

This program reads a stream of ACIS packets, verifies their format and internal consistency, and optionally, sorts, reformats, and writes them to a series of data streams and disk files. Packets are read from the input file, or, if omitted, from the standard input stream, stdin. They are subjected to a variety of tests. If the -l option is specified, their headers are translated into ASCII and written to log files. If -m is specified, a one-line description is written to stdout, suitable for display by monitorScience(1). Most packets are then discarded, and psci goes on to read the next one, but some are retained, as follows:

*

the most recent exposure header packet from each FEP,

*

all event data packets, until a corresponding exposure header packet is encountered,

*

multi-packet memory read-out packets originating from a single BEP command,

*

the most recent dumped*Block and dumpedHuffman packets.

psci has been compiled with tables derived directly from the IP&CL Structures database. Packets with unrecognized TTAG codes (as defined in the "acis_h/interface.h" file) cause warning messages to be written to stderr, and are ignored. All fields in recognized packets and pseudopackets are then checked against their IP&CL limits\(embit fields are expanded to "unsigned long int" values unless their minimum permissible values (column 15 in the IP&CL structure tables) are negative, in which case, psci treats them as twos-complement signed integers and expands them to "long int". If a field is discovered to be out of range, psci writes a message to stderr:

file: packet[ntotal,ncount].field[index] above maximum (val > maxval)
file: packet[ntotal,ncount].field[index] below minimum (val < maxval)

All stderr messages begin with a "file:" argument; for errors and warnings, this is the name of the input file (or stdin); for informatory messages, it is usually the name of an output file. Packets are designated by their IP&CL names, e.g., exposureTeRaw, followed by ntotal, the sequence number of the packet within the input stream, and ncount, its sequence number among packets of its particular type. Both counts start at zero, so the first packet is [0,0]. Multi-dimensional fields within packets are followed by an array index, which also starts at [0]. The value of the field is displayed as a decimal integer. Since out-of-limits field-values are not considered to be sufficient reason for halting the program, psci writes these messages and continues processing. The messages themselves can be suppressed by invoking psci with the -q option.

When the -l option is used, psci writes packet-header information to log files. The format of these files is derived from that of data structures in the C language. Fields whose values are enumerated in "acis_h/interface.h" will be followed by "#" and the enumeration. Unsigned values larger than 32767 are shown in hexadecimal base, preceded by "0x". The values of arrays of fields with dimension > 9 are not shown\(emmerely their dimension. When a packet contains one or more command blocks, e.g. dumpedTeBlock, which contains a science parameter block (either loadTeBlock or loadCcBlock) and an optional window block (either load1dBlock or load2dBlock), the individual fields are also logged, shifted to the right by 2 columns.

When a dumpedCcBlock or dumpedTeBlock packet is received, a comment is written into all open log files, and the science run number is incremented. Any opened science and bias data files are automatically closed, and a warning message is written to stderr since they should have been closed: science files by the receipt of a previous scienceReport packet, and bias files when complete.

When psci is invoked with the -m flag, monitor records are written to stdout.

Warning Messages:

These are written to stderr unless the -q flag appears on the psci command line.

* packet[ntot,npkt] `file' partially filled

* last data packet was packet[ntot,npkt]

a science run was terminated while incomplete raw-mode data files were being written.

* packet[ntot,npkt] `file' partially filled

* packet[ntot,npkt].ccdRow=n in last bias packet

a science run was terminated while incomplete bias files were being written.

* packet[ntot,npkt] missing parameter block

A science packet cannot be processed because no science-mode parameter block has been received.

* packet[ntot,npkt] no Huffman table specified

An initial table can be pre-allocated by using the -h option.

* packet[ntot,npkt] no histogram data packets received

An exposureTeHistogram packet was received with no preceding dataTeHist packets.

* packet[ntot,npkt] no parameter block was found

A scienceReport packet was received without any prior dumpedCcBlock or dumpedTeBlock packets.

* packet[ntot,npkt].readAddress != packet[ntot,npkt.requestedAddress + 4*n

The readAddress is inconsistent with the position of this packet within a group of memory-readout packets.

* packet[ntot,npkt].readIndex != packet[ntot,npkt].requestedIndex + 2*n

The readIndex is inconsistent with the position of this packet within a group of DEA memory-readout packets.

* packet[ntot,npkt] unpacking failure in=m/n out=p/p

This packet has failed Huffman decompression. n 32-bit words (out of m) remain to be unpacked; p 12-bit values (out of an anticipated q) have resulted.

* packet[ntot,npkt] unpacking length inconsistency

The unpacked length of this packet does not conform to that expected from its header fields.

* packet[ntot,npkt] warning: no data packets

A raw-mode exposure packet was not preceded by any raw-mode data packets.

* packet[ntot,npkt].startExposureNumber=n <= packet[ntot,npkt].endExposureNumber=n

The startExposureNumber of this histogram exposure packet is not greater than the endExposureNumber of the previous exposure packet.

* packet[ntot,npkt].ccdRow=n > packet[ntot,npkt].(subarrayStartRow+subarrayRowCount)=n

The ccdRow field of the current packet is inconsistent with the subarrayStartRow and subarrayRowCount fields in the science-mode parameter block.

* packet[ntot,npkt].field[n] above maximum (val > maxval)

The named field is larger than the limit defined in the IP&CL Structures table.

* packet[ntot,npkt].field[n] below minimum (val < minval)

The named field is smaller than the limit defined in the IP&CL Structures table.

* packet[ntot,npkt].(ccdRow-ccdRowCount)=n < packet[ntot,npkt].subarrayStartRow=n

The ccdRow and ccdRowCount fields of this packet are inconsistent with the subarrayStartRow field in the science-mode parameter block.

* packet[ntot,npkt].sequenceNumber=n != n

The packet sequence number is not one larger than that of the preceding (non-pseudo-) packet.

* packet n ignored: unknown type n

The packet's formatTag is not defined in the IP&CL Structures table.

* unrecognized commandOpcode n in packet[ntot,npkt]

The commandOpcode is not defined in the IP&CL Structures table.

* warning: non-zero dutyCycle, ERV timetags may be inaccurate

psci does not attempt to generate "reasonable" acistime fields for timed-exposure mode with non-zero dutyCycle.

Informatory Messages:

These are only written to stderr if the -v flag appears on the psci command line.

* written n bytes to log file `file'

a log file has been successfully closed.

* packet[ntot,npkt] written to `file'

a memory-read packet, or groups of packets, has been written to a disk file.

*\fP packet[ntot,npkt] run n irig n:n exp n fep n ccd n dea n bep n

A science run has terminated with the specified number of exposures and FEP, DEA, and BEP completion codes.

* Executing packet[ntot,npkt] run n

A science run has begun.

* written n bytes to bias file `file'

A bias file has been successfully closed.

* start packet run n fepmode bepmode bep timestamp irig days:secs exptime secs

A science run has started and psci has figured out the approximate IRIG start time and inter-exposure interval.

* written n exposures n events to `file'

An event file has been successfully closed.

* written histogram to `file'

A histogram file has been successfully closed.

* written n bytes to raw image file `file'

A raw-mode FITS file has been successfully closed.

10.27 runacis

NAME

runacis - Execute ACIS FEP and BEP software simulators

SYNOPSIS

runacis [-B file] [-D dir] [-F file] [-b file] [-c] [-h host] [-nc ccd] [-nf fep] [-x file]

DESCRIPTION

runacis starts a simulated ACIS back-end processor (BEP) on a remote DecStation host and copies its telemetry stream to the standard output stream, stdout. It reads its standard input stream, stdin, copying the contents to the software serial port of the simulated BEP. This input stream may be constructed from the standard output of buildCmds, invoked with the -p flag to suppress channel code prefixes.

The -b and -x options are used to specify programs that will supply CCD pixel values to a simulated ACIS front-end processor (FEP) that will be started on the same remote host as was the BEP simulator. The -b file is intended for bias pixels, and -x for subsequent science-mode pixels. If both -b and -x are omitted, no FEP simulator will be started.

All error messages from the simulator(s) will be written to files named host.type.log in the current directory, where host is the name of the remote DecStation that is running the simulator(s), and type is bep for output from acisBepUnix, fep for output from acisFepUnix, img for output from the fepImage2 loader, cmd for output from the cclient command sender, and tlm for output from filterClient, the telemetry receiver. The standard error stream, stderr, from runacis itself will only contain short informatory messages, e.g. "acisBepUnix: starting", etc., along with the stderr of commands specified in the -b and -x options.

OPTIONS

-B file

specifies the name of the BEP software simulator. The default is acisBepUnix.

-D dir

specifies the name of the directory tree within which the various executables ( acisBepUnix, acisFepUnix, fepImage2, etc. ) are to be found. If dir is a relative pathname, it is assumed to be located within ~acis.

-F file

specifies the name of the FEP software simulator. The default is acisFepUnix. It will only be started if the -x option is used.

-b file

starts the executable file, passing its standard output to a copy of fepImage2 running on the remote host. This standard output should therefore consist of a stream of DEA pixel values with legal control codes. For instance, rows should be ended with HSYNC codes and frames with VSYNC codes. Unless either this option or -x (q.v.) is specified, no FEP simulator will be started on the remote host.

-c

clean up the software simulator processes running on the remote host and release any shared memory that remains allocated.

-h host

the name of the remote DecStation host that is to run the simulators.

-nc ccd

the number of the CCD/DEA to simulate. The default is CCD 0. runacis will only start a single simulated CCD, and then only if the -x option is used.

-nf fep

the number of the FEP to simulate. The default is FEP 0. runacis will only start a single simulated FEP, and then only if the -x option is used.

-x file

waits until acisBepUnix writes the string ":invokeDataProcess" to its stderr stream, and then starts the executable file, passing its standard output to a copy of fepImage2 running on the remote host. The contents are as described for the -b option described above.

EXAMPLE

In the following, only the first telemetry packet, a cmdEcho, and a scienceReport packet, are shown.

$ buildCmds -p < te.1 | runacis -h quasar -b genbias -x genfep | ltlm -v -e11


acisBepUnix: starting
acisFepUnix: starting
filterClient: starting
quasar: configuring

commandEcho[0] = {
  synch	= 0x736f4166
  telemetryLength	= 8
  formatTag	= 7 (TTAG_CMD_ECHO)
  sequenceNumber	= 1
  arrival	= 0x00000097
  result	= 1 (CMDRESULT_OK)
  changeConfigSetting[1] = {
    commandLength	= 7
    commandIdentifier	= 0
    commandOpcode	= 32 (CMDOP_CHANGE_SYS_ENTRY)
    entries[0] = {
      itemId	= 0 (SETTING_DEA_POWER)
      itemValue	= 1
    }
    entries[1] = {
      itemId	= 1 (SETTING_FEP_POWER)
      itemValue	= 1
    }
  }
}

cclient: starting
fepImage2: starting FEP 0 sequencer for bias
genbias: bias 1 written
genbias: bias 2 written
genbias: bias 3 written
fepImage2: starting FEP 0 sequencer for science run
genfep: image 1 written
genfep: image 2 written
genfep: image 3 written

scienceReport[0] = {
  synch	= 0x736f4166
  telemetryLength	= 12
  formatTag	= 15 (TTAG_SCI_REPORT)
  sequenceNumber	= 13
  runStartTime	= 0x09af8da0
  parameterBlockId	= 0x12345678
  windowBlockId	= 0xffffffff
  biasStartTime	= 0x04460e20
  biasParameterId	= 0x12345678
  exposuresProduced	= 2
  exposuresSent	= 2
  biasErrorCount	= 0
  fepErrorCodes	= 0 0 0 0 0 0
  ccdErrorFlags	= 0 1 1 1 1 1
  deaInterfaceErrorFlag	= 0
  terminationCode	= 1 (SMTERM_STOPCMD)
}

acisBepUnix: stopping science run

The user must now type CTRL-C to stop the run. runacis will respond "Cleaning up", and will continue to run until the processes are killed on the remote host and the shared memory released.

FILES

host.bep.log

stderr from acisBepUnix running on host.

host.cmd.log

stderr from cclient sending commands to host.

host.fep.log

stderr from acisFepUnix running on host.

host.img.log

stderr from fepImage2 running on host.

host.tlm.log

stderr from filterClient receiving telemetry from host.

AUTHOR

Peter G. Ford, MIT CSR

SEE ALSO

acisBepUnix(1), acisFepUnix(1), buildCmds(1), cclient(1), fepImage2(1), filterClient(1), filterServer(1), ltlm(1), processScience(1)

DIAGNOSTICS

Bad -nc value

the CCD value must lie in the range 0 through 9.

Bad -nf value

the FEP value must lie in the range 0 through 5.

BUGS

runacis makes various assumptions about the time required for the various processes to start up. If the network connection to the remote host is particularly slow, it will fail.

If acisFepUnix isn't correctly cleaned up on the remote host, a subsequent runacis job may fail because the shared memory segments are still in use. The remedy is to invoke runacis with the -c flag to repeat the clean-up and then run it a second time in its usual manner.

10.28 sciglue

NAME

sciglue - convert psci monitor output for monitorScience

SYNOPSIS

sciglue [file]

DESCRIPTION

This Perl script reads the standard output of psci, invoked with the -m flag, and converts it into a format suitable for input to monitorScience.

AUTHOR

Peter G. Ford, MIT CSR

SEE ALSO

monitorScience(1), psci(1)

10.29 sendCmds

NAME

sendCmds - send the output of buildCmds to shim

SYNOPSIS

sendCmds

DESCRIPTION

sendCmds receives a binary command stream from buildCmds, containing command type, command channel, command data triplets. It constructs 23-bit, formatted command strings, packages them into 24-bit strings to simplify the output interface, and sends them to stdout, which is assumed to be piped to SHIM.

sendCmds expects its standard input to consist of pairs of 16-bit words (command type and command channel) followed by zero or more 16-bit words comprising the command data, as described below. All 16-bit words are assumed to start with their least significant bytes, i.e. little-endian order. The format and content of commands are contained in the AXAF IP&CL documents.

Command Type		Command Channel		Description
Name	Value	Name	Value
Serial Digital	2	Software	2	Command used to control the ACIS software
Serial Digital	2	Hardware	3	Command used to control the ACIS hardware
High Level Pulse	0	Pulse Cmd Channel Number	0-98	PS and MC commands, whose action is determined by the Command Channel value
No-Op	3	TBD	TBD	Potential RCTU/CTUE operation commands

High Level Pulse commands are completely specified by the Command Type and Command Channel pair. Therefore, no command data will follow.

Serial Digital Hardware commands will consist of a single 16-bit word that will immediately follow the Command Type and Command Channel pair.

Serial Digital Software commands will consist of from 3 to 256 16-bit words contained in an ACIS software command packet that will immediately follow the Command Type and Command Channel pair. All software command packets contain length fields which are extracted by sendCmds to determine how to read the remainder of the command packet.

The output, which is produced in 3-byte groups, looks like this:

Serial Digital Commands		High Level Pulse Commands
Bit*	Contents	Bit*	Contents
0	Unspecified	0	Unspecified
1-2	Command Type	1-2	Command Type
3-18	Command Data	3-14	Unspecified
19-23	Command Channel	15-23	Command Channel

* bit 0 is the most significant bit and is transmitted/received first

When sendCmds reads an illegal command type or command channel from stdin, it writes an error message to stderr and terminates processing. When sendCmds reads an illegal software command packet from stdin, it writes an error message to stderr, but it processes the command anyway. No warning is given if an unknown opcode is encountered. These shortcomings will be fixed in a later version.

EXAMPLES

The following UNIX pipe uses sendCmds as part of commanding the ACIS instrument to start executing stored timed exposure parameter block 1:

echo `start 22 te 1' | buildCmds | sendCmds | shim ...

AUTHOR

Demitrios Athens, MIT CSR

STATUS

The current version does not check for and remove critical commands.

The current version has been used with the LRCTU and the CTUE.

The current version produces its output in the bit order shown above, which is as defined in the CTUE and the Command and Data Management equipment specifications. However, to make the software work successfully with the LRCTU, the current version REVERSES THE BYTE ORDER OF ALL SERIAL DIGITAL COMMAND DATA that it receives. This seems to work when talking to the CTUE.

The current version has successfully handled both software and hardware Serial Digital commands and High Level Pulse commands.

The values currently used for software and hardware command channels are updated to the current IP&CL values as expressed in the beta version of the "interface.h" file.

The curent version will may be modified to emit No-Op commands that will be used to convey a command count for use in assembling CTUE command blocks.

Software commands with unrecognized opcodes are passed through. This responds to a request from the flight software folks to provide flexibility during testing.

Hardware command data is not checked for validity.

10.30 shim

NAME

shim - common interface for both CTUE and LRCTU

SYNOPSIS

shim \ ctue | lrctu

DESCRIPTION

shim provides a consistent interface between ACIS and all user applications that either generate ACIS commands or receive ACIS telemetry. It can communicate with ACIS using either the CTUE/RCTU combination or the Jim Littlefield RCTU emulator, the LRCTU. It always expects its command input to be in the 24-bit sendCmds format. It always produces its telemetry output in the AXAF-I minor frame format.

OPTIONS

ctue

communicate with ACIS using the CTUE/RCTU combination.

shim extracts the 23-bit input command words from the 24-bit sendCmds format and packs them into 48-bit Ground Command format strings. It then assembles these strings into command blocks, which it sends to the CTUE/RCTU via a TCP/IP interface.

shim receives telemetry via the same interface and passes it to its client, which is typically getPackets, without modification.

lrctu

communicate with ACIS using the Jim Littlefield RCTU emulator, the LRCTU

When sending commands to an LRCTU, shim reads the 24-bit output of sendCmds and passes it to the LRCTU via a serial interface. Note that High Level Pulse commands will not be executed because the LRCTU does not support them.

When receiving telemetry from an LRCTU via the same serial interface, shim reformats the LRCTU telemetry packets into AXAF-I, Format 2, telemetry minor frames, adding frame synchs and CCSDS headers as appropriate.

shim always resets the LRCTU hardware (by sending an ASCII character with many zero bits to the LRCTU's reset port) and then copies the LRCTU's operating code to the device's memory.

EXAMPLE

... buildCmds | sendCmds | shim lrctu | getPackets ...

ENVIRONMENT

ACISTOOLSDIR

The name of the top-level ACIS Test Tools directory. shim will use this directory as its starting point when looking for executables. See the FILES section immediately below.

FILES

${ACISTOOLSDIR}/bin/sun4/lrctu.unix

Jim Littlefield's code that runs on UNIX and communicates with the LRCTU through the fast tty device.

${ACISTOOLSDIR}/bin/mips/lrctu.mongoose.srec

Jim Littlefield's code that runs on the Mongoose processor on the LRCTU and communicates with UNIX through the fast tty device.

/dev/ttyC?0

LRCTU command and telemetry fast tty device (? is typically 4)

/dev/ttyC?1

LRCTU hardware reset fast tty device (? is typically 4)

/dev/ct.o

fast tty device driver

/etc/rc/sts

fast tty device system boot file

/etc/sts/bin/cdmknods

fast tty device system boot file

AUTHOR

Demitrios Athens, MIT CSR

STATUS

The current version only works with the Jim Littlefield RCTU Emulator.

The current version creates AXAF-I telemetry major frames from LRCTU telemetry by piping LRCTU telemetry to ltp2mnf.

The current version does not put bilevels (LED's) reported in the LRCTU telemetry packets into the AXAF-I minor frames. Expect this to change soon.

The current version of the LRCTU does not produce real-time or even near-real-time timestamps when it issues science header pulses to the BEP. It merely copies the BEP timestamp, which is the latched value of a free running counter, and uses this information in its telemetry packet headers. The ability to obtain near-real-time timestamp information from the LRCTU has been proposed but has neither been made a requirement nor been implemented.

ltp2mnf creates pseudo IRIG-B timestamps and puts them into the AXAF-I format minor frames that it creates. Times come from the host system clock, not from an actual IRIG-B interface, and are not adjusted to account for processing or transmission delays.

The ability to command BEP and FEP hardware resets through the LRCTU has been proposed but has neither been made a requirement nor been implemented.

10.31 tlmsim

NAME

tlmsim - simulate ACIS telemetry packet stream

SYNOPSIS

tlmsim [-c file] [-f] [-p] [-t] [-w file] ringfile biasfile

DESCRIPTION

This command generates a stream of ACIS telemetry packets from a timed-exposure ring-buffer file (ringfile) and a bias map in FITS format (biasfile). These files are generated by the output and dumpbias directives in fepCtlTest scripts.

OPTIONS

-c file

Load a timed-exposure parameter block from file, which must contain a series of "keyword = value" lines, as exemplified in the following section. If this option is omitted, tlmsim will use a default block.

-f

Simulate Format 1 output, i.e. with ACIS out of the focal plane and restricted to 512 baud downlink. This will affect the ratio of telemetry packets to science-frame pseudo-packets.

-p

Generate science-frame pseudo-packets in the format described in the ACIS Test Tools document. If this option is used in conjunction with the -f flag, a huge number of pseudo-packets will be generated.

-t

Use the current UNIX system clock as a basis for BEP timestamps. If omitted, these fields will be zeroed out, making it easier to compare tlmsim output files.

-w file

Load a 2-dimensional window block from file, which must contain a series of "keyword = value" lines, as exemplified in the following section. If this option is omitted, tlmsim uses no windows.

PARAMETER BLOCK EXAMPLE

Keywords may be expressed in upper, lower, or mixed case characters. In this example, a simple 3x3 faint-with-bias science run is defined, using CCD number 6 and FEP number 2, as specified by the fep*CcdSelect keywords. All keyword values are unsigned integers, or arrays of unsigned integers, with the following exceptions: * parameterBlockId, deaLoadOverride, and fepLoadOverride are hexadecimal integers with "0x" prefixes; * gradeSelection is an array of 8 hexadecimal integers, without any "0x" prefix. With these exceptions, tlmsim does not check the values in any way. Blank lines, and all characters between "#" and newline, are ignored.

teBlockSlotIndex	= 1
parameterBlockId	= 0x00000fab
fepCcdSelect	= 10 10 6 10 10 10
fepMode	= 2
bepPackingMode	= 1
onChip2x2Summing	= 0
ignoreBadPixelMap	= 0
ignoreBadColumnMap	= 0
recomputeBias	= 1
trickleBias	= 1
subarrayStartRow	= 0
subarrayRowCount	= 0
overclockPairsPerNode	= 15
outputRegisterMode	= 0
ccdVideoResponse	= 0 0 0 0 0 0
primaryExposure	= 28
secondaryExposure	= 0
dutyCycle	= 0
fep0EventThreshold	=    0    0    0    0 
fep1EventThreshold	=    0    0    0    0 
fep2EventThreshold	=  100  100  100  100 
fep3EventThreshold	=    0    0    0    0 
fep4EventThreshold	=    0    0    0    0 
fep5EventThreshold	=    0    0    0    0 
fep0SplitThreshold	=    0    0    0    0 
fep1SplitThreshold	=    0    0    0    0 
fep2SplitThreshold	=    0    0    0    0 
fep3SplitThreshold	=    0    0    0    0 
fep4SplitThreshold	=    0    0    0    0 
fep5SplitThreshold	=    0    0    0    0 
lowerEventAmplitude	= 0
eventAmplitudeRange	= 65535
gradeSelection	= ffff0000 0 0 0 0 0 0 0 
windowSlotIndex	= 65535
histogramCount	= 0
biasCompressionSlotIndex	=  255  255  255  255  255  255 
rawCompressionSlotIndex	= 255
ignoreInitialFrames	= 20
biasAlgorithmId	=    0    0    1    0    0    0 
biasArg0	=    0    0    0    0    0    0 
biasArg1	=    0    0   10    0    0    0 
biasArg2	=    0    0    0    0    0    0 
biasArg3	=    0    0  100    0    0    0 
biasArg4	=    0    0   70    0    0    0 
fep0VideoOffset	=    0    0    0    0
fep1VideoOffset	=    0    0    0    0
fep2VideoOffset	=  127  128  129  130
fep3VideoOffset	=    0    0    0    0
fep4VideoOffset	=    0    0    0    0
fep5VideoOffset	=    0    0    0    0
deaLoadOverride	= 0x00000000
fepLoadOverride	= 0x00000000

WINDOW BLOCK EXAMPLE

Keywords may be expressed in upper, lower, or mixed case characters. In this example, two windows are defined, one for CCD 5 and the other for CCD 6. All keyword values are unsigned integers, except for windowBlockId, which must be a hexadecimal integer with leading "0x". Otherwise, tlmsim does not check the values in any way. Blank lines, and all characters between "#" and newline, are ignored.

windowSlotIndex	= 1
windowBlockId	= 0x00000baf

ccdId	= 5
ccdRow	= 1
ccdColumn	= 1
width	= 1022
height	= 1022
sampleCycle	= 0
lowerEventAmplitude	= 0
eventAmplitudeRange	= 65535

ccdId	= 6
ccdRow	= 1
ccdColumn	= 1
width	= 1022
height	= 1022
sampleCycle	= 0
lowerEventAmplitude	= 0
eventAmplitudeRange	= 65535

AUTHOR

Peter G. Ford, MIT CSR

SEE ALSO

dumpring(1), fepCtlTest(1), ltlm(1)

ACIS Test Tools, ACIS Document, Version 1.0, July, 1996

ACIS IP&CL Structures, Version 1.17, July, 1996

DIAGNOSTICS

bad argument: arg(s)

tlmsim too many arguments have been specified on the command line.

does not scan: line

the statement in a parameter or window block is invalid, either because the keyword is unrecognized, or the value(s) is(are) illegal, or because there is no equals sign between them.

missing file name(s)

takes exactly two non-optional command line arguments, the name of the ring-buffer file, followed by the name of the FITS bias file.

multiple CCDs selected

the parameter block can contain only one fep*ccdSelect field whose value is less than 10, i.e. tlmsim can only simulate a single CCD at a time.

no CCD selected

the parameter block must contain at least one fep*ccdSelect whose value differs from 10.

no window specified

the window block contains no window-specific keywords.

out of order: line

one or more header keywords comes after the first window-specific keyword in a window block.

unknown flag: flag

the flag is unrecognized. There must be whitespace between the flag and the file name in the -c and -w options.

unsupported biasCompressionSelect[n] value: val

this version of tlmsim requires that all biasCompressionSelect fields have the value 255, i.e. no compression at all.

unsupported rawCompressionSelect value: val

this version of tlmsim requires that the rawCompressionSelect field has the value 255, i.e. no compression at all.

10.32 writeCCB

NAME

writeCCB - package the output of sendCmds into CTUE command blocks

SYNOPSIS

writeCCB [actu | bctu] [abus | bbus]

DESCRIPTION

writeCCB receives a series of 24-bit command strings from sendCmds that contain command type, command data, and command channel triplets. It constructs CTUE command blocks that contain the commands and sends them either to stdout, or, over a TCP/IP connection, to the CTUE's command port.

writeCCB expects its standard input to consist of 3-byte groups as produced by sendCmds. writeCCB places each 24-bit command into a 48-bit CTUE format command that looks like this:

CTUE Command

Bit*	Contents
0-6	Spacecraft address
7	CTU A/B select
8	Fixed bit `1'
9-11	Command routing
12-16	RCTU address
17-39	sendCmds output
40	Fixed bit `1'
41-47	Polynomial check code

* bit 0 is the most significant bit and is transmitted/received first

writeCCB places each 48-bit CTUE format command into a command block that looks like this:

CTUE command block

Byte*	Contents
0	Command count
1-6	CTUE Command
7-8	Checksum

* byte 0 is the most significant byte and is transmitted/received first

writeCCB automatically checks the environment when starting. If it discovers a CTUE_CMD_SD variable, it writes the output CTUE command blocks to the socket descriptor that the variable indicates. ( ACISshell will set this variable when the CTUE connects to accept ACIS commands.) Output goes to stdout otherwise.

OPTIONS

actu | bctu

selects either the A or B side of the spacecraft's CTU. If the user does not specify a side, writeCCB defaults to using the A side.

abus | bbus

selects either Bus A or Bus B command routing from either the CTUE or the spacecraft CTU to the RCTU. If the user does not specify a bus, writeCCB defaults to using the A bus.

EXAMPLES

The following UNIX pipe uses writeCCB as part of commanding the ACIS instrument to start executing stored timed exposure parameter block 1. The command prompt indicates that ACISshell has been executed and that the CTUE has established a connection.

ACISshell% echo `start 22 te 1' | buildCmds | sendCmds | writeCCB

AUTHOR

Demitrios Athens, MIT CSR

SEE ALSO

sendCmds(1) ACISshell(1)

STATUS

The current version has been used with the CTUE only.

The actu | bctu option is probably meaningless and best left alone when using a CTUE, which has only an A side. (The B side was so good that it's being saved for the album.)

The interaction of the abus | bbus option and the CTUE's own GUI, which allows the operator to select a command bus, is a complete mystery. It's probably best not to specify the option unless you're looking for adventure.

Table of Contents

Next Chapter