joris
/
redpitaya-puzzlefw
1
0
Fork 0
Code Issues Pull Requests Releases Activity
redpitaya-puzzlefw/doc/user_manual.md

29 KiB
Raw Blame History

Table of Contents

PuzzleFW User Manual

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 218, 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.
If N ≤ 1024, the effective downsample gain is equal to N.
If N > 1024, the effective downsample gain is equal to N / 2k, 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 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:
    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 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.

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 that they do not interfere with each other.

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 each other 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, 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
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.