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]`  | Offset calibration. |
| `AIN:CHn:GAIN[:LO|HI]`    | 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. |
| `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?` <br>
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?` <br>
Response: decimal integer, representing the current timestamp in units of 8 ns.

### `AIN:CHANNELS:COUNT?`

Query: `AIN:CHANNELS:COUNT?` <br>
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` <br>
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?` <br>
Response: number of active channels, either `2` or `4`.

### `AIN:CHn:RANGE`

Command: `AIN:CHn:RANGE range` <br>
Field _n_: channel number, in range 1 to 4. <br>
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?` <br>
Response: currently configured input range, either `LO` or `HI`.

### `AIN:CHn:OFFSET[:LO|HI]`

Command: `AIN:CHn:OFFSET offs` <br>
Field _n_: channel number, in range 1 to 4. <br>
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` <br>
Command: `AIN:CHn:OFFSET:HI offs` <br>
These variants of the command configure the offset calibration for a specific input range.

Query: `AIN:CHn:OFFSET?` <br>
Query: `AIN:CHn:OFFSET:LO?` <br>
Query: `AIN:CHn:OFFSET:HI?` <br>
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` <br>
Field _n_: channel number, in range 1 to 4. <br>
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` <br>
Command: `AIN:CHn:GAIN:HI offs` <br>
These variants of the command configure the gain calibration for a specific input range.

Query: `AIN:CHn:GAIN?` <br>
Query: `AIN:CHn:GAIN:LO?` <br>
Query: `AIN:CHn:GAIN:HI?` <br>
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?` <br>
Field _n_: channel number, in range 1 to 4. <br>
Response: floating point number representing the most recent ADC sample for the specified input channel in Volt.

Query: `AIN:CHn:SAMPLE:RAW?` <br>
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?` <br>
Field _n_: channel number, in range 1 to 4. <br>
Response: two floating point numbers separated by a space character, representing the minimum and maximum input level in Volt.

Query: `AIN:CHn:MINMAX:RAW?` <br>
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` <br>
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?` <br>
Response: floating point number representing the sample rate in samples per second.

### `AIN:SRATE:DIVISOR`

Command: `AIN:SRATE:DIVISOR divisor` <br>
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?` <br>
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` <br>
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?` <br>
Response: either `DECIMATE` or `AVERAGE`.

### `AIN:SRATE:GAIN?`

Query: `AIN:SRATE:GAIN?` <br>
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` <br>
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?` <br>
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` <br>
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?` <br>
Response: active trigger mode.

### `AIN:TRIGGER:DELAY`

Command: `AIN:TRIGGER:DELAY n` <br>
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?` <br>
Response: decimal integer representing the trigger delay as a number of 8 ns cycles.

### `AIN:TRIGGER:STATUS?`

Query: `AIN:TRIGGER:STATUS?` <br>
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` <br>
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?` <br>
Response: decimal integer specifying the selected digital input channel.

### `AIN:TRIGGER:EXT:EDGE`

Command: `AIN:TRIGGER:EXT:EDGE edge` <br>
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?` <br>
Response: either `RISING` or `FALLING`.

### `TT:SAMPLE?`

Query: `TT:SAMPLE?` <br>
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` <br>
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?` <br>
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?` <br>
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` <br>
Command: `IPCFG STATIC ipaddr netmask gateway` <br>
Parameter _ipaddr_: IPv4 address in dotted-quad notation. <br>
Parameter _netmask_: netmask in dotted-quad notation. <br>
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` <br>
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?` <br>
Query: `IPCFG:SAVED?` <br>
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.