-
Notifications
You must be signed in to change notification settings - Fork 2
Native Controller Commands
A command cmd preceded by "native", such as native <cmd> [args] will be interpreted as a native detector controller command. A native command is a command which is "native" or inherent to the particular detector controller and is sent directly to the controller using the controller's specific syntax.
This functionality is illustrated by the green box in Figure 1. Although the figure shows a path completely circumventing the detector controller server, they are certainly received by the server; this is meant to illustrate that these commands have no corresponding "handling" function and are passed directly to the controller by the server and any return value comes directly from the controller. Other than proper formatting, the server does not interact with the command nor the return value.
In particular for the AstroCam controller, when the server returns DONE or ERROR that indicates the server's success or failure to send the command and receive a return value only. Therefore it is entirely possible for a native command to return an error and the server still report "DONE " (as opposed to "ERROR"). The client must examine the controller's return value to determine whether the controller returned an error or not.
Since the server does not interact with native commands or their return values, this means that if a native command is sent which changes the image dimensions, for example, then the server would not know about the new dimensions. Therefore, it's possible to produce undesirable behavior and in general, use of native commands is typically limited for use by detector engineers for engineering and testing purposes. However, in some cases (such as the three query-only native Archon commands outlined in §7.1.1, §0, §7.1.3) native commands might be very useful for reading values directly from the controller which might be needed for a FITS header. Stated another way, query-only native commands are safe to use, while native commands that cause a change in the controller should be used with extreme caution.
For the STA/Archon controller (§7.1), the server will add the required preamble and check only whether or not the return value contained an error. For the ARC (Leach) controller (§7.2), the server will enforce only that the maximum number of arguments is not exceeded, and that the command has exactly 3 letters.
This section is not meant to be an exhaustive list of Archon commands but only an example, and will list the three native query-only commands that might be of value for most users. Please see the Communications section of the Archon manual for additional details.
Commands to the Archon controller are of the form:
>xxCOMMAND
Commands begin with a greater-than symbol, followed by a two hexadecimal digit reference number, followed by the command itself, and terminated with a newline character ("\n" or ASCII 10, 0x0A). The detector controller server creates all of this preamble (in blue) for the user; the user need only to send COMMAND to the server.
Archon's response to this command will be tagged with the supplied hexadecimal reference number xx. The server will verify that a response with the corresponding reference was received and will return that response to the user. Lengthy responses will be sent to the async message port only, in a format suitable for parsing by client applications.
The example commands described here are FRAME,STATUS,SYSTEM.
The output from the native FRAME command is written to the async message port in the following format, minus the comments in grey:
FRAME:BEGIN
FRAME:TIMER=x ; Current hexadecimal 64-bit internal timer
FRAME:RBUF=d ; Current buffer number locked for reading
FRAME:WBUF=d ; Current buffer number locked for writing
FRAME:BUF_n_SAMPLE=d ; Buffer n sample mode, 0: 16 bit, 1: 32 bit
FRAME:BUF_n_COMPLETE=d ; Buffer n complete, 1: buffer ready to read
FRAME:BUF_n_MODE=d ; Buffer n mode, 0: top, 1: bottom, 2: split
FRAME:BUF_n_BASE=d ; Buffer n base address for fetching
FRAME:BUF_n_FRAME=d ; Buffer n frame number
FRAME:BUF_n_WIDTH=d ; Buffer n width
FRAME:BUF_n_HEIGHT=d ; Buffer n height
FRAME:BUF_n_PIXELS=d ; Buffer n pixel progress
FRAME:BUF_n_LINES=d ; Buffer n line progress
FRAME:BUF_n_RAWBLOCKS=d ; Buffer n raw blocks per line
FRAME:BUF_n_RAWLINES=d ; Buffer n raw lines
FRAME:BUF_n_RAWOFFSET=d ; Buffer n raw offset
FRAME:BUF_n_TIMESTAMP=x ; Buffer n hexadecimal 64-bit time stamp
FRAME:BUF_n_RETIMESTAMP=x ; Buffer n trigger rising edge time stamp
FRAME:BUF_n_FETIMESTAMP=x ; Buffer n trigger falling edge time stamp
FRAME:BUF_n_REATIMESTAMP=x ; Buffer n trigger A rising edge time stamp
FRAME:BUF_n_FEATIMESTAMP=x ; Buffer n trigger A falling edge time stamp
FRAME:BUF_n_REBTIMESTAMP=x ; Buffer n trigger B rising edge time stamp
FRAME:BUF_n_FEBTIMESTAMP=x ; Buffer n trigger B falling edge time stamp
FRAME:END
The output from the native STATUS command is written to the async message port in the following format, minus the comments in grey:
STATUS:BEGIN
STATUS:VALID=n ; n = 1 if remaining status fields are valid
STATUS:COUNT=n ; Number of times system status has been updated
STATUS:LOG=n ; Number of log entries available
STATUS:POWER=n ; Power status. Possible values:
; 0: Unknown – _usually an internal error
; 1: Not Configured – _no configuration applied
; 2: Off – _power to the CCD is off
; 3: Intermediate – _some modules have enabled
; power to the CCD, some have not
; 4: On – _Power to the CCD is on
; 5: Standby – _System is in standby
STATUS:POWERGOOD=n ; n = 1 when system power supply is good
STATUS:OVERHEAT=n ; n = 1 when system is overheating
STATUS:BACKPLANE_TEMP=f ; Floating point backplane temperature in C
STATUS:P2V5_V=f ; +2.5V system supply voltage in V
STATUS:P2V5_I=f ; +2.5V system supply current in A
STATUS:P5V_V=f ; +5V system supply voltage in V
STATUS:P5V_I=f ; +5V system supply current in A
STATUS:P6V_V=f ; +6V system supply voltage in V
STATUS:P6V_I=f ; +6V system supply current in A
STATUS:N6V_V=f ; -6V system supply voltage in V
STATUS:N6V_I=f ; -6V system supply current in A
STATUS:P17V_V=f ; +17V system supply voltage in V
STATUS:P17V_I=f ; +17V system supply current in A
STATUS:N17V_V=f ; -17V system supply voltage in V
STATUS:N17V_I=f ; -17V system supply current in A
STATUS:P35V_V=f ; +35V system supply voltage in V
STATUS:P35V_I=f ; +35V system supply current in A
STATUS:N35V_V=f ; -35V system supply voltage in V
STATUS:N35V_I=f ; -35V system supply current in A
STATUS:P100V_V=f ; +100V system supply voltage in V
STATUS:P100V_I=f ; +100V system supply current in A
STATUS:N100V_V=f ; -100V system supply voltage in V
STATUS:N100V_I=f ; -100V system supply current in A
STATUS:USER_V=f ; User system supply voltage in V
STATUS:USER_I=f ; User system supply current in A
STATUS:HEATER_V=f ; Heater system supply voltage in V
STATUS:HEATER_I=f ; Heater system supply current in A
STATUS:FANTACH=n ; Fan speed in RPM (Rev F only)
STATUS:MOD_m_/TEMP=f ; Floating point module m temperature in C
STATUS:MOD_m_/LVLC_V_n_=f ; LV(X)Bias only: Floating point module m low
; voltage low current n voltage reading in V
; n = 1 to 24 maps to LV1 to LV24
STATUS:MOD_m_/LVLC_I_n_=f ; LV(X)Bias only: Floating point module m low
; voltage low current n current reading in mA
; n = 1 to 24 maps to LV1 to LV24
STATUS:MOD_m_/LVHC_V_n_=f ; LV(X)Bias only: Floating point module m low
; voltage high current n voltage reading in V
; n = 1 to 6 maps to LV25 to LV30
STATUS:MOD_m_/LVHC_I_n_=f ; LV(X)Bias only: Floating point module m low
; voltage high current n current reading in mA
; n = 1 to 6 maps to LV25 to LV30
STATUS:MOD_m_/HVLC_V_n_=f ; HV(X)Bias only: Floating point module m high
; voltage low current n voltage reading in V
; n = 1 to 24 maps to HV1 to HV24
STATUS:MOD_m_/HVLC_I_n_=f ; HV(X)Bias only: Floating point module m high
; voltage low current n current reading in mA
; n = 1 to 24 maps to HV1 to HV24
STATUS:MOD_m_/HVHC_V_n_=f ; HV(X)Bias only: Floating point module m high
; voltage high current n voltage reading in V
; n = 1 to 6 maps to HV25 to HV30
STATUS:MOD_m_/HVHC_I_n_=f ; HV(X)Bias only: Floating point module m high
; voltage high current n current reading in mA
; n = 1 to 6 maps to HV25 to HV30
STATUS:MOD_m_/TEMPA=f ; Heater(X) only: Floating point temperature
; sensor A reading in K
STATUS:MOD_m_/TEMPB=f ; Heater(X) only: Floating point temperature
; sensor B reading in K
STATUS:MOD_m_/TEMPC=f ; HeaterX only: Floating point temperature
; sensor C reading in K
STATUS:MOD_m_/HEATERAOUTPUT=f ; Heater only: Floating point heater A
; output in V
STATUS:MOD_m_/HEATERBOUTPUT=f ; Heater only: Floating point heater B
; output in V
STATUS:MOD_m_/HEATERAP=d ; Heater only: Heater A P term contribution
; to PID loop (signed integer)
STATUS:MOD_m_/HEATERAI=d ; Heater only: Heater A I term contribution
; to PID loop (signed integer)
STATUS:MOD_m_/HEATERAD=d ; Heater only: Heater A D term contribution
; to PID loop (signed integer)
STATUS:MOD_m_/HEATERBP=d ; Heater only: Heater B P term contribution
; to PID loop (signed integer)
STATUS:MOD_m_/HEATERBI=d ; Heater only: Heater B I term contribution
; to PID loop (signed integer)
STATUS:MOD_m_/HEATERBD=d ; Heater only: Heater B D term contribution
; to PID loop (signed integer)
STATUS:MOD_m_/DINPUTS=bbbbbbbb; LV(X)Bias and Heater(X): reports the status
; of DIO1 to DIO8 (each is 0=low or 1=high)
STATUS:MOD_m_/MAG_V_n_=f ; HS only: Floating point module m magnitude n
; voltage reading in V
STATUS:MOD_m_/MAG_I_n_=f ; HS only: Floating point module m magnitude n
; current reading in mA
STATUS:MOD_m_/OFS_V_n_=f ; HS only: Floating point module m offset n
; voltage reading in V
STATUS:MOD_m_/OFS_I_n_=f ; HS only: Floating point module m offset n
; current reading in mA
STATUS:MOD_m_/DINPUTS=bbbb ; HS and LVDS: reports the status of
; DIO1 to DIO4 (each is 0=low or 1=high)
STATUS:MOD_m_/VCPU_OUTREG_n_=d ; Modules with DIO: VCPU output register n
; (unsigned 16-bit integer)
STATUS:END
The output from the native SYSTEM command is written to the async message port in the following format, minus the comments in grey:
SYSTEM:BEGIN
SYSTEM:BACKPLANE_TYPE=n ; n = 1 for an X4 backplane, n = 2 for X12
SYSTEM:BACKPLANE_REV=n ; Backplane PCB revision, 0 = A, 1 = B…
SYSTEM:BACKPLANE_VERSION=n.n.n ; Backplane firmware, major.minor.build
SYSTEM:BACKPLANE_ID=x ; 16 hexadecimal digit backplane unique ID
SYSTEM:MOD_PRESENT=x ; Hexadecimal bit field: a 1 in the LSB
; indicates a module is present in slot 1
SYSTEM:MOD_m__TYPE=n ; Reports module type for slots 1…n.
; 0: None
; 1: Driver
; 2: AD
; 3: LVBias
; 4: HVBias
; 5: Heater
; 7: HS
; 8: HVXBias
; 9: LVXBias
; 10: LVDS
; 11: HeaterX
; 12: XVBias
; 13: ADF
; 14: ADX
; 15: ADLN
; 16+: Unknown
SYSTEM:MOD_m__REV=n ; Module m PCB revision, 0 = A, 1 = B…
SYSTEM:MOD_m__VERSION=n.n.n ; Module m firmware, major.minor.build
SYSTEM:MOD_m__ID=x ; 16 hexadecimal digit module m unique ID
SYSTEM:END
The ARC detector controller firmware utilizes "3-letter" commands that can have up to four 24-bit arguments. The ARC-22 Timing Board will in most cases reply to these commands with an ASCII 'DON' (0x444F4E) on success or an ASCII 'ERR' (0x455454) on error, although some commands can produce other errors or return values. Table 4 shows return values which are mapped to their ASCII string counterparts so that when the camera server encounters one of these return values, the associated string will instead be returned; all other return values are returned by decimal (base 10) value.
Table 4. ASCII string return values for specified ARC return codes.
| ARC return value | string returned |
|---|---|
| 0x00455252 | ERR |
| 0x00444F4E | DON |
| 0x544F5554 | TOUT |
| 0x524F5554 | ROUT |
| 0x48455252 | HERR |
| 0x00535952 | SYR |
| 0x00525354 | RST |
| 0x00434E52 | CNR |
The 3-letter commands that are accepted by the controller are wholly dependent on the firmware that is loaded into the timing board and therefore any combination of 3-letter commands could exist; therefore this section can neither completely nor accurately describe all of the native 3-letter commands for your particular firmware. There are however, some commonly used, almost "standard" commands which are typically flashed into all ARC-22 timing board EEPROMs; these will be described here.
usage: POF
Turn off the biases and clocks.
usage: PON
Turn on the biases and clocks.
usage: RDM <addr> <val>
Read from memory address <addr>. This is flashed into the on-board EEPROM so it is available even without uploading firmware.
usage: SBN <boardid> <dac#> <BOARD> <adu>
Sets the output DAC number <dac#> on board ID <boardid> to the voltage specified by <adu>.
The ID number of the board <boardid> is {0:15}.
<dac#> is the DAC number {0:7}.
<BOARD> is the string name of the board, "CLK" or "VID" and can be substituted with the hex value of those strings, 0x434C4B or 0x564944, respectively.
<adu> represents the voltage in A/D units, {0:4095} scaled to the max output voltage. E.g. for a 3.3V system, <adu> = 4095 x voltage / 3.3.
usage: SMX <boardid> <mux1> <mux2>
The clock driver board has two multiplexed outputs. This specifies the MUX values to be output to the clock driver board. <boardid> is the board ID of the clock driver {0:15} and <mux1> and <mux2> are the clocks outputs {0:23}.
usage: TDL <number>
Test fiber optic data link.
Writes a number to the timing board which returns the same number; used to test the operability of the fiber optic data link between the host and the timing board. This is flashed into the on-board EEPROM so it is available even without uploading firmware.
usage: WRM <addr> <val>
Write <val> to address <addr>. Note that the Y:memory starts at address 0x400000. This is flashed into the on-board EEPROM so it is available even without uploading firmware.