19 KiB
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 |
Offset calibration. |
AIN:CHn:GAIN |
Gain calibration. |
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. |
AIN:ACQUIRE:ENABLE |
Enable analog acquisition. |
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.
AIN:ACQUIRE:ENABLE
Command: AIN:ACQUIRE:ENABLE en
Parameter en: either 0 or 1.
This command enables or disables analog acquisition. When enabled, analog samples are acquired according to the configured trigger mode. When disabled, all triggers are ignored and any ongoing analog acquisition stops immediately.
Query: AIN:ACQUIRE:ENABLE?
Response: either 0 or 1.
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.