PuzzleFW is an alternative, unofficial firmware package for the Red Pitaya.
It consists of FPGA firmware and embedded software.
The embedded software runs under Linux on the ARM processor in the Zynq.
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.
## 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 dual-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 dual-input ADCs.
The analog inputs are labeled as channel 1 to channel 4.
On a 4-input system, the firmware can operate either in 2-channel mode or
in 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.
Since the Red Pitaya uses an inverting input circuit.
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 2<sup>18</sup>, corresponding to
an effective sample rate of approximately 477 samples/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 and noise.
For this reason, averaging mode is the default setting.
Averaging mode is implemented by summing sample values.
This causes an effective gain factor that 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 word.
To fix this, the summed values are divided by a suitable power of 2. <br>
If _N_≤ 1024, the effective downsample gain is equal to _N_. <br>
If _N_> 1024, the effective downsample gain is equal to _N_ / 2<sup>_k_</sup>, where _k_ = ceil(log<sub>2</sub>(_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 trigger pulse in 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.
- However, in auto-trigger mode, even for short acquisition runs,
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 sample data will be lost
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 commands 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 stream of timetagged events is transferred via the network.
The timestamp resolution is the same as the ADC sample rate, 125 MHz.
Timestamps are expressed in units of 8 ns cycles.
### 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 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: <br>
`dd if=puzzlefw_sdcard.img of=/dev/sdX bs=1M`
<br>
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`
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.
As an alternative to DHCP, 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
It is possible to 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.
If you want to use the SSH server, you have to enable it explicitly.
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.
## Data stream protocol
Clients may connect to TCP port 5001 to receive analog sample data,
and to TCP port 5002 to receive timetagger data.
At most one client can be connected to each of these ports 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 these TCP connections in one direction:
from the server to the client.
The client must not send anything back to the server.
Data are transferred as a sequence of 64-bit binary messages.
Each message is sent as 8 bytes with the least significant byte first.a
The message streams correspond to the output data format of the
analog acquisition chain and the timetagger as described in the
[FPGA firmware documentation](fpga_firmware.md#).
## Remote control protocol
Clients 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
| `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?`<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, or 4 if 4 channels are active.
In other trigger modes, the downsample factor must be at least 1, or 2 if 4 channels are active.
### `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`.
### `AIN:ACQUIRE:ENABLE`
Command: `AIN:ACQUIRE:ENABLE en`<br>
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?`<br>
Response: either `0` or `1`.
### `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.
