Command Interface

The default server port for the command interface is port 8888. All commands and responses are in ASCII with lines separated with newline characters (ASCII character 0x0A).

All commands can be grouped into three forms (query, assignment, table assignment) and two targets (system and fields). There exactly four possible response formats (ok, ok with value, error, multiple value). This section describes this command interface.

The three basic command forms are:

Name	Format	Description
Query	target?	Interrogates target for current value, can return error, single value or a list of multiple values.
Assignment	target=value	Updates target with given value, can return error or success.
Table	target<format	Command may be followed by lines of text, must be terminated by blank line.

The four basic command responses are:

Name	Format	Description
Success	OK	Returned assignment and table commands to report successful update.
Value	OK =value	Successful return of single value from query command.
Error	ERR error	Error string returned on any command failure
Multi value	! value .	Any number of values can be returned, each preceded by !, and finally . by itself indicates end of input.

Command forms and their possible responses:

Form	Responses
Query	Error, Value, Multi value
Assignment	Error, Success
Table	Error, Success

Each individual query target will either return a single value or multi-value, as documented below.

Finally, there are two basic types of target: configuration commands and system commands.

Configuration Commands

The entire hardware interface to PandA is structured into “blocks” and “fields”, and each field may have a number of “attributes” depending on the field type. This structure is reflected in the form of configuration commands which are tabulated below:

Command Syntax	Description
block[number].field?	Return current value of field.
block[number].field=value	Assign value to field.
block[number].field<[<][B]	Write table data to field.
block[number].field.attr?	Return current value of field attribute.
block[number].field.attr=value	Assign value to field attribute.
block[number].*?	Returns list of fields.
block[number].field.*?	Returns list of field attributes.

In all of these commands the number after the block is optional if there is only one instance of that block, and is ignored for the two .*? commands. See the description of the .TABLE fields for an explanation of the optional format characters in the table write command.

System Commands

All system commands are prefixed with a leading * character. The simplest command is *IDN? which returns a system identification string:

< *IDN?
> OK =PandA SW: 330bd94-dirty FPGA: 0.1.9 d1275f61 00000000

The available system commands are tabulated here and listed in more detail below:

Command	Description
*IDN?	Device identification.
*ECHO string?	Echo.
*WHO?	List connected clients.
*BLOCKS?	List device blocks.
*DESC. block.field[.attr]? *DESC. block.field[].subfield?	Show description for field, attribute, or table subfield.
*ENUMS. block.field[.attr]? *ENUMS. block.field[].subfield?	List enumerations for field, attribute, or table subfield.
*CHANGES[.group]?	Report changes to values. group can be any of CONFIG, BITS, POSN, READ, ATTR, or TABLE.
*CHANGES[.group]=[E| S]	Reset reported changes, group as above.
*CAPTURE?	Report fields configured for capture.
*CAPTURE.*?	List all fields that can be captured.
*CAPTURE.name?	Interrogate capture options, name can be OPTIONS or ENUMS.
*CAPTURE=	Reset data capture.
*POSITIONS?	Enumerate possible capture positions.
*BITS?	Enumerate possible bit bus positions.
*VERBOSE=value	Control command logging.
*PCAP.field?	Special position capture status fields. field can be any of STATUS, CAPTURED, or COMPLETION.
*PCAP.field=	Position capture actions. field can be either ARM, or DISARM.
*SAVESTATE=	Triggers immediate save to file of the persistence file state.
*CLOCK_FREQ?	Returns currently configured system clock frequency

*IDN?

Returns system identification string, for example the following:

OK =PandA SW: 1.1 FPGA: 0.1.9 d1275f61 00000000 rootfs: PandA 1.1

The first field after “PandA” is the software version, the second field is the FPGA version, the third the firmware build number, and the fourth field identifies the supporting firmware. The final fields (prefixed rootfs:) identify the underlying system on which the server is running.

Note that the rootfs: identification is new to version 1.1 of PandA.

*ECHO string?

Returns string back to caller. Not terribly useful. Note that the echoed string cannot contain any of ?, = or < characters, as this would cause the command to be mistaken for another command format! Example usage:

< *ECHO This is a test?
> OK =This is a test

*WHO?

Returns list of client connections, for example:

< *WHO?
> !2015-12-04T14:30:40.403Z config 127.0.0.1:34185
> .

The first field is the time the connection was made, the second field is either config or data depending on whether the configuration or data port is connected, and the third field is the remote IP address and socket.

*BLOCKS?

Returns a list of all the top level blocks in the system. The order in which the blocks is returned is somewhat arbitrary. For example (here the list has been shortened in the middle):

< *BLOCKS?
> !TTLIN 6
> !OUTENC 4
...
> !CLOCKS 1
> !BITS 1
> !QDEC 4
> .

Block and field commands can be used to interrogate each block. The number after each block records the number of instances of each block.

*DESC.block?

*DESC.block.field?

*DESC.block.field.attr?

*DESC.block.field[].subfield?

Returns description string for specified block, field, attribute, or table subfield eg:

< *DESC.TTLIN?
> OK =TTL input
< *DESC.TTLIN.TERM?
> OK =Select TTL input termination
< *DESC.TTLIN.TERM.INFO?
> OK =Class information for field

*ENUMS.block.field?

*ENUMS.block.field.attr?

*ENUMS.block.field[].subfield?

Returns list of enumerations for given field, attribute, or table subfield, if appropriate.

*CHANGES?

*CHANGES.CONFIG?

*CHANGES.BITS?

*CHANGES.POSN?

*CHANGES.READ?

*CHANGES.ATTR?

*CHANGES.TABLE?

Reports changes to the appropriate group of values. Changes are reported since the last request on the connection, and on the first request the current value for every field will be reported. The *CHANGES? command reports changes for all groups, otherwise one of the following groups can be selected:

CONFIG	Configuration settings
BITS	Bits on the system bus
POSN	Positions
READ	Polled read values
ATTR	Attributes (included capture enable flags)
TABLE	Table changes

For example:

< *CHANGES.CONFIG?
> !TTLIN1.TERM=High-Z
> !TTLIN2.TERM=50-Ohm
> !TTLIN3.TERM=High-Z
...
> !QDEC2.B=TTLIN1.VAL
> !QDEC3.B=TTLIN1.VAL
> !QDEC4.B=TTLIN1.VAL
> .

Here 804 (at the time of writing) lines have been deleted from the transcript! Now if we repeat the call we see that no further changes have happened until something is actually changed:

< *CHANGES.CONFIG?
> .
< TTLOUT4.VAL=TTLIN3.VAL
> OK
< *CHANGES.CONFIG?
> !TTLOUT4.VAL=TTLIN3.VAL
> .

Note that for tables only the fact that the table has changed is shown, no attempt is made to show the current table value:

< *CHANGES.TABLE?
> !PCOMP1.TABLE<
> !PCOMP2.TABLE<
> !PCOMP3.TABLE<
> !PCOMP4.TABLE<
> !PGEN1.TABLE<
> !PGEN2.TABLE<
> !SEQ1.TABLE<
> !SEQ2.TABLE<
> !SEQ3.TABLE<
> !SEQ4.TABLE<
> .

*CHANGES=[E| S]

*CHANGES.CONFIG=[E| S]

*CHANGES.BITS=[E| S]

*CHANGES.POSN=[E| S]

*CHANGES.READ=[E| S]

*CHANGES.ATTR=[E| S]

*CHANGES.TABLE=[E| S]

These commands reset the change information for the corresponding group of information so that only changes occuring after the reset are reported, or so that all changes are reported. If = or =E (for End) is specified then only new changes are reported, if =S (for Start) then change reporting is reset to the start as for a new connection. For example:

< TTLIN1.TERM=50-Ohm
> OK
< *CHANGES=
> OK
< *CHANGES.CONFIG?
> .

*CAPTURE?

This returns a list of all positions and bit masks that will be written to the data capture port. This list is controlled by setting the .CAPTURE attribute on the corresponding position fields.

*CAPTURE.*?

This returns a list of all fields that can be configured for capture. This includes all pos_out and ext_out fields.

*CAPTURE.OPTIONS?

Lists the available capture options for pos_out fields. The available options are “Value”, “Diff”, “Sum”, “Mean, “Min”, “Max”, “StdDev”. Availability of the last option “StdDev” depends on the FPGA configuration.

*CAPTURE.ENUMS?

Generates a curated list of capture option selections. This is designed to be used for presenting lists of available capture options as an enumeration. Returns the same as calling *ENUMS.name.field.CAPTURE? on any pos_out field.

*CAPTURE=

This resets all .CAPTURE flags to zero so that no data will be captured.

*POSITIONS?

This command lists all available position capture fields in order.

*BITS?

This command lists all available bit bus positions, but not including the special values ZERO and ONE.

*VERBOSE=value

If *VERBOSE=1 is set then every command will be echoed to the server’s log. Set *VERBOSE=0 to restore normal quiet behaviour.

*PCAP.STATUS?

*PCAP.CAPTURED?

*PCAP.COMPLETION?

Interrogates status of position capture:

STATUS	Returns string with three fields: “Busy” or “Idle”, followed by the number of connected readers, and the number taking data.
CAPTURED	Returns number of samples captured in the current or most recent data capture.
COMPLETION	Returns completion status from most recent data capture, as listed in the table below.

The completion codes have the following meaning:

Busy	Capture in progress.
Ok	Capture completed without error or intervention.
Disarmed	Capture was manually disarmed by *PCAP.DISARM= command.
Framing error	Data capture framing error, probably due to incorrectly configured capture.
DMA data error	Internal data error, should not occur.
Driver data overrun	Data capture too fast, internal buffers overrun. Can also occur if PandA processor overloaded.

*PCAP.ARM=

*PCAP.DISARM=

Top level capture control:

ARM	Initiates data capture. Will fail if capture already in progress, or no fields configured for capture.
DISARM	Halts ongoing data capture.

*SAVESTATE=

Updates the persistence state file (as configured on the command line when launched) with the current state. Returns after a file system sync call, so it is safe to power-off the system after this command has completed.

*CLOCK_FREQ?

Returns currently configured FPGA clock frequency as used to convert between times in natural units and times in clock ticks.