diff --git a/README.md b/README.md index 6964f91..b64ff70 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ PuzzleFW has the following features: Further details about the firmware are in these documents: -- User manual, to be written +- [User manual](doc/user_manual.md) - Developer manual, including the build procedure, to be written - [FPGA firmware description](doc/fpga_firmware.md) diff --git a/doc/user_manual.md b/doc/user_manual.md new file mode 100644 index 0000000..5ee2185 --- /dev/null +++ b/doc/user_manual.md @@ -0,0 +1,748 @@ +--- +gitea: none +include_toc: true +--- + +# PuzzleFW User Manual + +This document describes the functionality and usage of the PuzzleFW firmware. +PuzzleFW is an alternative, unofficial firmware package for the Red Pitaya. + +The PuzzleFW firmware does not provide a built-in user interface. +It does not have a web interface, nor any other kind of graphical interface. + +The only way to control the system is via the network, using a remote command protocol. +In typical cases, you would design custom PC software that connects to the Red Pitaya via the network to send commands and receive data. +Such software can then present the measured data on the PC in any way it wants, possibly via a custom graphical user interface. + +PuzzleFW consists of FPGA firmware and embedded software. +The embedded software runs under Linux on the ARM processor in the Zynq. + + +## Analog input operation + +The analog input subsystem captures ADC samples. +Depending on various configuration settings, the ADC samples are processed and ultimately transferred via the network. + +### Analog input signals + +A standard Red Pitaya STEMlab 125-14 has 2 analog input channels, +sampled by one 2-input ADC. +The analog inputs are labeled as channel 1 and channel 2. + +A Red Pitaya STEMlab 125-14 4-input has 4 analog input channels, +sampled by a pair of 2-input ADCs. +The analog inputs are labeled as channel 1 to channel 4. +A 4-input system can operate in 2-channel mode or 4-channel mode. +In 2-channel mode, only samples from channel 1 and channel 2 are processed. + +### Sampling + +All analog input channels are simultaneously sampled at a fixed +sample rate of 125 MSa/s. + +Samples are unsigned 14-bit integers. +An input level of 0 Volt corresponds to the middle of the 14-bit range, +i.e. approximately 8192. +The Red Pitaya uses an inverting input circuit. +As a result, positive input voltages correspond to lower ADC codes, +and negative input voltages correspond to higher ADC codes. + +### Downsampling (decimation) + +The ADCs operate at a fixed sample rate of 125 MSa/s. +While the sample rate of the ADC can not be changed, the effective sample rate can be reduced by digital processing in the FPGA. + +The effective sample rate after digital processing is equal to the ADC sample rate divided by the _sample rate divisor_ (also called _downsample factor_ or _decimation factor_). +The sample rate divisor is always an integer. +Setting the sample rate divisor to 1 results in an effective sample rate equal to the ADC sample rate, i.e. 125 MSa/s. +Setting a higher sample rate divisor reduces the effective sample rate to `125000000 / divisor` samples per second. +The maximum supported sample rate divisor is 218, corresponding to +an effective sample rate of approximately 477 Sa/s. + +Rather than configuring the sample rate divisor, the system also supports configuring an effective sample rate in samples per second. +In this case, the requested sample rate is converted to the corresponding sample rate divisor and rounded to the nearest integer. + +The system supports two modes of sample rate reduction: decimation and averaging. +In decimation mode with sample rate divisor _N_, only the first sample out of every group of _N_ samples is processed, and the remaining _N_ - 1 samples are discarded. +Decimation causes high frequency signals (above the Nyquist frequency) to alias into the downsampled data. + +In averaging mode, the system calculates the sum of each group of _N_ samples. +Averaging mode has the advantage that it suppresses aliasing while also reducing the impact of quantization noise from the ADC. +For these reasons, averaging mode is the default setting. + +Averaging mode is implemented by summing sample values. +This causes an effective gain factor which depends on the sample rate divisor: +if _N_ samples are summed, the result is equal to _N_ times the average +sample value. +If the sample rate divisor is greater than 1024, the result may not fit +in a 24-bit sample word. +To fix this, the summed values are divided by a power of 2. +If _N_ ≤ 1024, the effective downsample gain is equal to _N_. +If _N_ > 1024, the effective downsample gain is equal to _N_ / 2_k_, where _k_ = ceil(log2(_N_ / 1024)). + +### Triggering + +When a trigger occurs, the system collects a _record_ consisting of a +configurable number of (downsampled) samples. +Samples are collected for all active channels. +The number of samples collected per trigger must be between 1 and 65536. +Collected samples are transferred via the network. + +There are 3 ways to trigger the system: + +- By sending an explicit trigger command. +- Via an external digital input signal. + A record is collected for each active edge of the digital signal. +- Continuous triggering in auto-trigger mode. + +There are 4 digital input signals that can be used for external triggering. +These signals are connected via pins `DIO0_P` to `DIO3_P` on the Red Pitaya. +Settings are available to select one of these signals, and +to trigger on either rising or falling edges of the selected signal. + +An optional trigger delay can be specified. +The delay specifies the number of 8 ns cycles to wait after detecting +the trigger event and before recording the first ADC sample. +The external trigger event is subject to a jitter of 1 sample (8 ns). + +New trigger events are ignored while the system is still processing a previous trigger. + +When auto-trigger mode is active, the system triggers continuously. +A new trigger occurs as soon as acquisition for the previous trigger has ended, after a dead time controlled by the trigger delay setting. +In this mode, the sample rate divisor must be at least 2 (or at least 4 in 4-channel mode). +If the trigger delay is zero, sampling continues accross triggers at a fixed pace controlled by the sample rate divisor. +This makes it possible to set up continuous streaming sampling. + +### Performance limits + +Sample rates are limited in a number of ways: + +- For acquisition runs up to about 16000 samples, the sample rate + is limited by internal data paths in the FPGA. + In this case, the sample rate divisor must be at least 1, + or at least 2 when operating in 4-channel mode. +- In auto-trigger mode, the sample rate divisor must be at least 2, + or at least 4 when operating in 4-channel mode. +- For longer acquisition runs, the sample rate is limited by the + network transfer rate. + In this case, the maximum sample rate is approximately 5 MSa/s, + or 2.5 MSa/s when operating in 4-channel mode. + +If the configured sample rate is too high, the system will either +refuse the sample rate setting, or part of the sample data will be discarded +when internal data buffers fill up. + +When using external triggering, the maximum trigger rate depends +on the time it takes to complete data collection for a trigger. +The system is ready to accept a new trigger as soon as data collection +for the previous trigger ends. +At high sample rates, the maximum trigger rate is eventually also limited +by the data transfer rate via the network. + +### Calibration + +The analog inputs of the Red Pitaya support two different input ranges: +± 1 V and ± 20 V. +The range is selected through jumpers on the board. +Software command can not change the actual input range. + +The firmware does provide commands to specify which input range is used by each channel. +The firmware also keeps track of calibration coefficients for each channel +and input range. + +Two calibration coefficients, _offset_ and _gain_, establish a linear relation +between ADC codes and input voltage. +The conversion formula is as follows: + + adc_code = offset + gain * input_voltage + +Input ranges and calibration coefficients can be saved to the SD card of +the Red Pitaya to be preserved across power cycles. + + +## Timetagger operation + +The timetagger subsystem detects changes on digital input signals +and assigns timestamps to such events. + +The timestamp resolution is the same as the ADC sample rate, 125 MHz. +Timestamps are expressed in units of 8 ns cycles. + +The stream of timetagged events is transferred via the network. + +### Digital input signals + +The timetagger has 4 digital input channels. +These signals are connected via pins `DIO0_P` to `DIO3_P` on the Red Pitaya. + +Each input channel produces two types of events: rising edge events and falling edge events. +Each event type of each channel can be separately enabled or disabled for timetagging. + + +## Firmware installation + +- Use a micro SD card, at least 1 GB. +- Get the PuzzleFW firmware image `puzzlefw_sdcard.img` +- Put the SD card in a Linux PC. +- Find out the device name of the SD card `/dev/sdX` where `X` is replaced by another letter. + Be **very careful** to get the device name right. + Other storage devices in the PC have similar names. + Writing the SD card image will destroy all other data on the target device. + If you accidentally write the image to the main drive of your PC, you will have a very bad day. +- Make sure that the SD card is not mounted by some automatic device management subsystem in your PC. +- Run the following command as root:
+ `dd if=puzzlefw_sdcard.img of=/dev/sdX bs=1M` +
+ This command may take a few minutes to complete. +- Run `sync` and `eject /dev/sdX` before removing the SD card from the PC. + +The SD card image can also be written on a PC with a different operating system than Linux. +The steps to do this are described in the official Red Pitaya documentation. + + +## Console access + +The USB console port on the Red Pitaya can be used to login on +the Linux system running on the board. +This is mostly useful for debugging. + +To access the console, use a terminal program such as `minicom` or `PuTTY` +to open the USB serial port of the Red Pitaya. +Set the baud rate to 115200 bps, character format to `8N1`. + +Press Enter to get a login prompt on the console. +Use login `root` with password `root`. + + +## Network 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. + +### Default IP address settings + +By default, the system attempts to obtain an IPv4 address via DHCP. +If the DHCP request fails, the system chooses a link-local address in +the range 169.254.x.x. + +A static IPv4 address can be configured via remote control commands. + +The system has a unique host name `rp-xxxxxx.local`, +where the x characters are replaced by the last 6 digits of +the MAC address. +This is the same host name as used by the official Red Pitaya software. + +### SSH access + +The PuzzleFW system can optionall run an SSH server on the Red Pitaya. +This can be used to remotely log in on the Linux system. + +To login via SSH, use username `root` with password `root`. + +For security reasons, the SSH server is disabled by default. +An SSH server with an easy-to-guess password should never be connected to an untrusted network. + +The SSH server can be enabled by the user. +To enable the SSH server, login on the USB console as described above. +Then run the following command: `puzzle-sshcfg enable` . +Finally, run `reboot` to reboot the Red Pitaya. +From this point onward, the SSH server will be started automatically during boot. + + +## 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](fpga_firmware.md#). + + +## Timetagger data 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](fpga_firmware.md). + + +## Remote control 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. +