redpitaya-puzzlefw/doc/remote_control.md

Remote access

Remote access to the acquisition system is supported via TCP connections. Three TCP server ports are used:

• port 5001 is used to transfer analog sample data;
• port 5002 is used to transfer timetagger data;
• port 5025 is used for commands.

Analog sample data stream

A client may connect to TCP port 5001 to receive analog sample data. At most one client can be connected to this port at any time. If a new client connects while another connection is still active, the server closes the old connection and uses the new connection instead.

Data flows through the TCP connection in one direction: from the server to the client. The client must not send anything back to the server.

Analog sample data are transferred as a sequence of 64-bit binary messages. Each message is sent as a group of 8 bytes with the least significant byte first. The message stream corresponds to the output data format of the analog acquisition chain as described in the FPGA firmware documentation.

Timetagger event stream

A client may connect to TCP port 5002 to receive timetagger data. At most one client can be connected to this port at any time. If a new client connects while another connection is still active, the server closes the old connection and uses the new connection instead.

Data flows through the TCP connection in one direction: from the server to the client. The client must not send anything back to the server.

Timetagger data are transferred as a sequence of 64-bit binary messages. Each message is sent as a group of 8 bytes with the least significant byte first. The message stream corresponds to the output data format of the timetagger as described in the FPGA firmware documentation.

Command protocol

A client may connect to TCP port 5025 to send commands. Multiple clients may be simultaneously connected to this port. In that case, it is the responsibility of the clients to make sure that they do not interfere with eachother.

The remote control protocol is based on ASCII strings. The protocol is vaguely similar to SCPI, but it is not compatible with SCPI.

Every interaction is initiated by the client sending a command, and completed by the server sending a response. Each command and each response consists of an ASCII string terminated by linefeed (ASCII 10). Commands are case-insensitive.

The server ignores empty lines and lines that contain only white space characters. In all other cases, the server sends one response for every command received, even if the command is not recognized or not supported. The server only sends data in response to a command; it never sends data spontaneously.

A query is a command that ends with a ? character. The server responds to a query either by sending the requested data, or by sending an error message. An error message starts with the string ERROR, followed by a space character, followed by a short description of the error.

The server responds to a non-query command either by sending the string OK to indicate that the command was completed successfully, or by sending an error message.

Some commands require one or more parameters. In the command string, the command and parameters are separated from eachother by space characters.

The response to some queries may consist of multiple data elements. In the response string, such data elements are separated by space characters.

Example

Client	Server
AIN:SRATE?
	1000000.000
AIN:SRATE:DIVISOR 1000
	OK
AIN:SRATE?
	125000.000
AIN:NSAMPLES 0
	ERROR Invalid argument
Hello
	ERROR Unknown command

List of commands and queries

Command	Description
*IDN?	Instrument identification.
RESET	Restore default settings.
TIMESTAMP?	Timestamp counter.
AIN:CHANNELS:COUNT?	Number of input channels.
AIN:CHANNELS:ACTIVE	Number of active input channels.
AIN:CHn:RANGE	Analog input range.
`AIN:CHn:OFFSET[:LO	HI]`
`AIN:CHn:GAIN[:LO	HI]`
AIN:CAL:SAVE	Save calibration.
AIN:CHn:SAMPLE[:RAW]?	Read ADC sample.
AIN:CHn:MINMAX[:RAW]?	Read ADC range monitor.
AIN:MINMAX:CLEAR	Reset ADC range monitor.
AIN:SRATE	Sample rate.
AIN:SRATE:DIVISOR	Downsample factor.
AIN:SRATE:MODE	Downsample mode.
AIN:SRATE:GAIN?	Downsample gain.
AIN:NSAMPLES	Number of samples per trigger.
AIN:TRIGGER	Force a trigger event.
AIN:TRIGGER:MODE	Select trigger mode.
AIN:TRIGGER:DELAY	Trigger delay.
AIN:TRIGGER:STATUS?	Trigger status.
AIN:TRIGGER:EXT:CHANNEL	External trigger channel.
AIN:TRIGGER:EXT:EDGE	External trigger edge.
TT:SAMPLE?	Digital input state.
TT:EVENT:MASK	Timetagger event mask.
TT:MARK	Emit timetagger marker.
TEMP:FPGA?	FPGA temperature.
IPCFG[:SAVED]	IP address configuration.
HALT	Shut down system.
REBOOT	Reboot system.

*IDN?

Query: *IDN?
Response: string with 4 comma-separated fields.

This query returns the instrument identification string. The response consists of 4 comma-separated fields: manufacturer,model,serialnr,version.

RESET

Command: RESET

This command restores most non-persistent settings to power-on defaults. It resets all settings, except for the following:

• saved calibration;
• active network configuration;
• saved network configuration.

The active calibration is restored to match the saved calibration. Other settings are restored to fixed power-on defaults.

Any ongoing analog acquisition is stopped.

TIMESTAMP?

Query: TIMESTAMP?
Response: decimal integer, representing the current timestamp in units of 8 ns.

AIN:CHANNELS:COUNT?

Query: AIN:CHANNELS:COUNT?
Response: number of supported analog input channels.

The response is 2 for a standard Red Pitaya, or 4 for a 4-input Red Pitaya.

AIN:CHANNELS:ACTIVE

Command: AIN:CHANNELS:ACTIVE n
Parameter n: number of active channels, either 2 or 4.

This command is only supported on a 4-input Red Pitaya. When 2 channels are active, only analog input channels 1 and 2 are included in analog acquisition data.

Query: AIN:CHANNELS:ACTIVE?
Response: number of active channels, either 2 or 4.

AIN:CHn:RANGE

Command: AIN:CHn:RANGE range
Field n: channel number, in range 1 to 4.
Parameter range: input range, either LO or HI.

This command specifies which set of calibration coefficients should be used to interpret ADC samples. Note that this command does not change the actual input range of the Red Pitaya. The input range can only be changed by manually placing a jumper on the board.

Query: AIN:CHn:RANGE?
Response: currently configured input range, either LO or HI.

AIN:CHn:OFFSET[:LO|HI]

Command: AIN:CHn:OFFSET offs
Field n: channel number, in range 1 to 4.
Parameter offs: floating point number specifying the offset calibration.

The offset calibration specifies the raw ADC code corresponding to analog input level 0 Volt. The expected value is in the middle of the ADC code range, i.e. approximately 8192. The plain variant of the command configures the offset calibration for the active input range of the channel.

Command: AIN:CHn:OFFSET:LO offs
Command: AIN:CHn:OFFSET:HI offs
These variants of the command configure the offset calibration for a specific input range.

Query: AIN:CHn:OFFSET?
Query: AIN:CHn:OFFSET:LO?
Query: AIN:CHn:OFFSET:HI?
Response: floating point number indicating the offset calibration for the active input range or the specified input range.

AIN:CHn:GAIN[:LO|HI]

Command: AIN:CHn:GAIN gain
Field n: channel number, in range 1 to 4.
Parameter gain: floating point number specifying the gain calibration.

The gain calibration specifies the difference in raw ADC code corresponding to a 1 Volt difference in analog input level. The expected value is negative, because the Red Pitaya uses an inverting input amplifier. The plain variant of the command configures the gain calibration for the active input range of the channel.

Command: AIN:CHn:GAIN:LO offs
Command: AIN:CHn:GAIN:HI offs
These variants of the command configure the gain calibration for a specific input range.

Query: AIN:CHn:GAIN?
Query: AIN:CHn:GAIN:LO?
Query: AIN:CHn:GAIN:HI?
Response: floating point number indicating the gain calibration for the active input range or the specified input range.

AIN:CAL:SAVE

Command: AIN:CAL:SAVE

This command saves the active calibration settings to the SD card, to be used as power-on defaults. The following settings are saved: for each analog input channel, its input range, offset calibration for low and high range, and gain calibration for low and high range.

AIN:CHn:SAMPLE[:RAW]?

Query: AIN:CHn:SAMPLE?
Field n: channel number, in range 1 to 4.
Response: floating point number representing the most recent ADC sample for the specified input channel in Volt.

Query: AIN:CHn:SAMPLE:RAW?
Response: decimal integer representing the raw ADC code of the most recent sample for the specified input channel.

Sample rate settings are not applicable to this command. The ADC always samples at 125 MSa/s. This command returns the most recent single sample, without downsampling or averaging.

AIN:CHn:MINMAX[:RAW]?

Query: AIN:CHn:MINMAX?
Field n: channel number, in range 1 to 4.
Response: two floating point numbers separated by a space character, representing the minimum and maximum input level in Volt.

Query: AIN:CHn:MINMAX:RAW?
Response: two decimal integers separated by a space character, representing the minimum and maximum raw ADC code.

The returned values are the minimum and maximum sample values that occurred since the last reset of the range monitor.

AIN:MINMAX:CLEAR

Command: AIN:MINMAX:CLEAR

This command resets the input range monitors of all analog input channels.

AIN:SRATE

Command: AIN:SRATE rate
Parameter rate: floating point number specifying the sample rate in samples per second.

This command configures the effective sample rate of the acquisition chain. Valid sample rates are in range 500 to 125e6 samples per second. The specified sample rate will be rounded to the nearest supported rate.

Query: AIN:SRATE?
Response: floating point number representing the sample rate in samples per second.

AIN:SRATE:DIVISOR

Command: AIN:SRATE:DIVISOR divisor
Parameter divisor: decimal integer specifying the downsample factor.

This command configures the downsample factor of the acquisition chain. Valid downsample factors are in range 1 to 250000.

Query: AIN:SRATE:DIVISOR?
Response: decimal integer representing the downsample factor.

Note: Commands AIN:SRATE and AIN:SRATE:DIVISOR are different methods to control the same internal setting.

Note: When auto-trigger mode is selected, the downsample factor must be at least 2. When 4 channels are active, the downsample factor must be at least 2, or 4 if auto-trigger mode is selected.

AIN:SRATE:MODE

Command: AIN:SRATE:MODE mode
Parameter mode: downsample mode, either DECIMATE or AVERAGE.

This command selects downsampling by means of decimation or averaging. Downsampling works by collecting groups of consecutive raw ADC samples and translating each group into a single downsampled value. The number of raw samples per group is determined by the downsample factor (see AIN:SRATE:DIVISOR). In mode DECIMATE, the first sample of a group is used as downsampled value; the other samples in the group are discarded. In mode AVERAGE, the sum of all samples in a group is used as downsampled value.

Query: AIN:SRATE:MODE?
Response: either DECIMATE or AVERAGE.

AIN:SRATE:GAIN?

Query: AIN:SRATE:GAIN?
Response: floating point number representing the effective gain factor due to downsampling.

The value returned by this query depends on the downsample factor and the downsample mode.

In downsample mode DECIMATE, this query always returns 1.0. In downsample mode AVERAGE, this query returns a number between 1 and 1024.

AIN:NSAMPLES

Command: AIN:NSAMPLES n
Parameter n: decimal integer specifying the number of samples per channel per trigger.

This command configures the number of (downsampled) samples to collect for each trigger. Valid values are from 1 to 65536.

Query: AIN:NSAMPLES?
Response: decimal integer representing the number of samples per trigger.

AIN:TRIGGER

Command: AIN:TRIGGER

This command forces a trigger to occur, regardless of the configured trigger mode.

Note that even a forced trigger may be ignored if the acquisition chain is still processing a previous trigger.

AIN:TRIGGER:MODE

Command: AIN:TRIGGER:MODE mode
Parameter mode: trigger mode, either NONE or AUTO or EXTERNAL or EXTERNAL_ONCE.

Note: When trigger mode EXTERNAL_ONCE is selected, the trigger mode automatically changes to NONE as soon as a trigger occurs.

Query: AIN:TRIGGER:MODE?
Response: active trigger mode.

AIN:TRIGGER:DELAY

Command: AIN:TRIGGER:DELAY n
Parameter n: decimal integer specifying trigger delay as a number of 8 ns cycles.

This configures a delay between trigger detection and the start of sample collection. Valid values are from 0 to 65535.

Query: AIN:TRIGGER:DELAY?
Response: decimal integer representing the trigger delay as a number of 8 ns cycles.

AIN:TRIGGER:STATUS?

Query: AIN:TRIGGER:STATUS?
Response: trigger status, either BUSY or WAITING.

This query returns BUSY when the acquisition chain is processing a trigger, or WAITING if the acquisition chain is waiting for a trigger.

AIN:TRIGGER:EXT:CHANNEL

Command: AIN:TRIGGER:EXT:CHANNEL n
Parameter n: decimal integer specifying a digital input channel, in range 0 to 3.

This command selects the digital input channel to use as external trigger.

Query: AIN:TRIGGER:EXT:CHANNEL?
Response: decimal integer specifying the selected digital input channel.

AIN:TRIGGER:EXT:EDGE

Command: AIN:TRIGGER:EXT:EDGE edge
Parameter edge: trigger edge, either RISING or FALLING.

This command selects rising or falling edges in the external trigger signal.

Query: AIN:TRIGGER:EXT:EDGE?
Response: either RISING or FALLING.

TT:SAMPLE?

Query: TT:SAMPLE?
Response: array of 4 digits 0 or 1, separated by space characters.

This query returns the input state of all digital input channels.

TT:EVENT:MASK

Command: TT:EVENT:MASK mask
Parameter mask: decimal integer specifying a bit mask of enabled events.

This command configures the set of enabled timetagger events. The integer value of mask represents an 8-bit mask. Each bit position denotes an event type, as follows:

Bit index	Value	Description
0	1	Rising edge on digital input 0.
1	2	Falling edge on digital input 0.
2	4	Rising edge on digital input 1.
3	8	Falling edge on digital input 1.
4	16	Rising edge on digital input 2.
5	32	Falling edge on digital input 2.
6	64	Rising edge on digital input 3.
7	128	Falling edge on digital input 3.

Query: TT:EVENT:MASK?
Response: decimal integer representing the event mask.

TT:MARK

Command: TT:MARK

This command emits a marker record in the timetagger event stream.

TEMP:FPGA?

Query: TEMP:FPGA?
Response: floating point number representing the temperature in Celsius.

The temperature is measured by the internal temperature sensor of the Zynq FPGA.

IPCFG[:SAVED]

Command: IPCFG DHCP
Command: IPCFG STATIC ipaddr netmask gateway
Parameter ipaddr: IPv4 address in dotted-quad notation.
Parameter netmask: netmask in dotted-quad notation.
Parameter gateway: optional gateway address in dotted-quad notation.

This command configures the IP address of the system. It expects between 1 and 4 parameters, depending on the specific address configuration.

If address mode DHCP is selected, the command expects no further parameters. In this mode, the system attempts to get an IPv4 address from a DHCP server on the local network.

If address mode STATIC is selected, the command expects 2 or 3 additional parameters to specify the address, netmask and optional gateway. IP addresses are specified in dotted-quad notation: 4 decimal integers separated by period characters. The parameter gateway may be omitted or specified as 0.0.0.0 to indicate that no gateway should be used.

The command IPCFG takes effect immediately. This command does not send an OK response. Instead, all TCP connections are closed while the system prepares to change its IP address. Changing the IP address typically takes a few seconds. When the new address is active, the client may re-connect to the new IP address.

Note: Configuring an invalid IP address may make the system unreachable. In that case, the saved IP address configuration can be restored by power-cycling the system.

Command: IPCFG:SAVED DHCP
Command: IPCFG:SAVED STATIC ipaddr netmask gateway

This variant of the command configures the saved IP address configuration. It uses the same set of parameters as IPCFG. This command has no effect on the active IP address. When the command completes, it sends an OK response and the system continues to function normally. The saved address configuration takes effect on the next reboot of the system.

Query: IPCFG?
Query: IPCFG:SAVED?
Response: active or saved IP address configuration.

HALT

Command: HALT

This command iniates a shutdown of the system. It does not send an OK response. Instead, all TCP connections are closed while the system initiates shutdown.

The halt command causes the system to become unresponsive to further commands. To recover from the halt state, the system must be power-cycled.

REBOOT

Command: REBOOT

This command initiates a system reboot. It does not send an OK response. Instead, all TCP connections are closed while the system initiates shutdown.

A reboot involves a complete reset of the FPGA and the embedded ARM processor. The system then proceeds as if just powered on.