joris
/
redpitaya-puzzlefw
1
0
Fork 0
Code Issues Pull Requests Releases 1 Activity

fix

This commit is contained in:
Joris van Rantwijk 2024-10-15 22:42:04 +02:00
parent 3e282efeb7
commit 949ceec60a
1 changed files with 44 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

103
doc/user_manual.md
View File

@ -5,19 +5,17 @@ include_toc: true
# PuzzleFW User Manual # 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. 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. 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. 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. 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. 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. 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 ## Analog input operation
@ -27,13 +25,14 @@ Depending on various configuration settings, the ADC samples are processed and u
### Analog input signals ### Analog input signals
A standard Red Pitaya STEMlab 125-14 has 2 analog input channels, A standard Red Pitaya STEMlab 125-14 has 2 analog input channels,
sampled by one 2-input ADC. sampled by one dual-input ADC.
The analog inputs are labeled as channel 1 and channel 2. The analog inputs are labeled as channel 1 and channel 2.
A Red Pitaya STEMlab 125-14 4-input has 4 analog input channels, A Red Pitaya STEMlab 125-14 4-input has 4 analog input channels,
sampled by a pair of 2-input ADCs. sampled by a pair of dual-input ADCs.
The analog inputs are labeled as channel 1 to channel 4. 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. 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. In 2-channel mode, only samples from channel 1 and channel 2 are processed.
### Sampling ### Sampling
@ -44,8 +43,8 @@ sample rate of 125 MSa/s.
Samples are unsigned 14-bit integers. Samples are unsigned 14-bit integers.
An input level of 0 Volt corresponds to the middle of the 14-bit range, An input level of 0 Volt corresponds to the middle of the 14-bit range,
i.e. approximately 8192. i.e. approximately 8192.
The Red Pitaya uses an inverting input circuit. Since the Red Pitaya uses an inverting input circuit.
As a result, positive input voltages correspond to lower ADC codes, positive input voltages correspond to lower ADC codes,
and negative input voltages correspond to higher ADC codes. and negative input voltages correspond to higher ADC codes.
### Downsampling (decimation) ### Downsampling (decimation)
@ -58,7 +57,7 @@ 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 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. 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 The maximum supported sample rate divisor is 2<sup>18</sup>, corresponding to
an effective sample rate of approximately 477 Sa/s. 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. 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. In this case, the requested sample rate is converted to the corresponding sample rate divisor and rounded to the nearest integer.
@ -68,22 +67,22 @@ In decimation mode with sample rate divisor _N_, only the first sample out of ev
Decimation causes high frequency signals (above the Nyquist frequency) to alias into the downsampled data. 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. 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. Averaging mode has the advantage that it suppresses aliasing and noise.
For these reasons, averaging mode is the default setting. For this reason, averaging mode is the default setting.
Averaging mode is implemented by summing sample values. Averaging mode is implemented by summing sample values.
This causes an effective gain factor which depends on the sample rate divisor: 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 if _N_ samples are summed, the result is equal to _N_ times the average
sample value. sample value.
If the sample rate divisor is greater than 1024, the result may not fit If the sample rate divisor is greater than 1024, the result may not fit
in a 24-bit sample word. in a 24-bit word.
To fix this, the summed values are divided by a power of 2. To fix this, the summed values are divided by a suitable power of 2. <br>
If _N_ &le; 1024, the effective downsample gain is equal to _N_. If _N_ &le; 1024, the effective downsample gain is equal to _N_. <br>
If _N_ &gt; 1024, the effective downsample gain is equal to _N_ / 2<sup>_k_</sup>, where _k_ = ceil(log<sub>2</sub>(_N_ / 1024)). If _N_ &gt; 1024, the effective downsample gain is equal to _N_ / 2<sup>_k_</sup>, where _k_ = ceil(log<sub>2</sub>(_N_ / 1024)).
### Triggering ### Triggering
When a trigger occurs, the system collects a _record_ consisting of a When a trigger occurs, the system collects a record consisting of a
configurable number of (downsampled) samples. configurable number of (downsampled) samples.
Samples are collected for all active channels. Samples are collected for all active channels.
The number of samples collected per trigger must be between 1 and 65536. The number of samples collected per trigger must be between 1 and 65536.
@ -93,7 +92,7 @@ There are 3 ways to trigger the system:
- By sending an explicit trigger command. - By sending an explicit trigger command.
- Via an external digital input signal. - Via an external digital input signal.
A record is collected for each active edge of the digital signal. A record is collected for each trigger pulse in the digital signal.
- Continuous triggering in auto-trigger mode. - Continuous triggering in auto-trigger mode.
There are 4 digital input signals that can be used for external triggering. There are 4 digital input signals that can be used for external triggering.
@ -122,7 +121,8 @@ Sample rates are limited in a number of ways:
is limited by internal data paths in the FPGA. is limited by internal data paths in the FPGA.
In this case, the sample rate divisor must be at least 1, In this case, the sample rate divisor must be at least 1,
or at least 2 when operating in 4-channel mode. or at least 2 when operating in 4-channel mode.
- In auto-trigger mode, the sample rate divisor must be at least 2, - 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. or at least 4 when operating in 4-channel mode.
- For longer acquisition runs, the sample rate is limited by the - For longer acquisition runs, the sample rate is limited by the
network transfer rate. network transfer rate.
@ -130,7 +130,7 @@ Sample rates are limited in a number of ways:
or 2.5 MSa/s when operating in 4-channel mode. or 2.5 MSa/s when operating in 4-channel mode.
If the configured sample rate is too high, the system will either 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 refuse the sample rate setting, or sample data will be lost
when internal data buffers fill up. when internal data buffers fill up.
When using external triggering, the maximum trigger rate depends When using external triggering, the maximum trigger rate depends
@ -145,7 +145,7 @@ by the data transfer rate via the network.
The analog inputs of the Red Pitaya support two different input ranges: The analog inputs of the Red Pitaya support two different input ranges:
&plusmn; 1 V and &plusmn; 20 V. &plusmn; 1 V and &plusmn; 20 V.
The range is selected through jumpers on the board. The range is selected through jumpers on the board.
Software command can not change the actual input range. 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 does provide commands to specify which input range is used by each channel.
The firmware also keeps track of calibration coefficients for each channel The firmware also keeps track of calibration coefficients for each channel
@ -165,12 +165,11 @@ the Red Pitaya to be preserved across power cycles.
The timetagger subsystem detects changes on digital input signals The timetagger subsystem detects changes on digital input signals
and assigns timestamps to such events. 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. The timestamp resolution is the same as the ADC sample rate, 125 MHz.
Timestamps are expressed in units of 8 ns cycles. Timestamps are expressed in units of 8 ns cycles.
The stream of timetagged events is transferred via the network.
### Digital input signals ### Digital input signals
The timetagger has 4 digital input channels. The timetagger has 4 digital input channels.
@ -188,7 +187,7 @@ Each event type of each channel can be separately enabled or disabled for timeta
- Find out the device name of the SD card `/dev/sdX` where `X` is replaced by another letter. - 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. Be **very careful** to get the device name right.
Other storage devices in the PC have similar names. Other storage devices in the PC have similar names.
Writing the SD card image will destroy all other data on the target device. 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. 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. - 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> - Run the following command as root: <br>
@ -207,7 +206,7 @@ The USB console port on the Red Pitaya can be used to login on
the Linux system running on the board. the Linux system running on the board.
This is mostly useful for debugging. This is mostly useful for debugging.
To access the console, use a terminal program such as `minicom` or `PuTTY` To access the console, use a terminal program such as `minicom`
to open the USB serial port of the Red Pitaya. to open the USB serial port of the Red Pitaya.
Set the baud rate to 115200 bps, character format to `8N1`. Set the baud rate to 115200 bps, character format to `8N1`.
@ -230,7 +229,7 @@ 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 If the DHCP request fails, the system chooses a link-local address in
the range 169.254.x.x. the range 169.254.x.x.
A static IPv4 address can be configured via remote control commands. 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`, The system has a unique host name `rp-xxxxxx.local`,
where the x characters are replaced by the last 6 digits of where the x characters are replaced by the last 6 digits of
@ -239,7 +238,7 @@ This is the same host name as used by the official Red Pitaya software.
### SSH access ### SSH access
The PuzzleFW system can optionall run an SSH server on the Red Pitaya. It is possible to run an SSH server on the Red Pitaya.
This can be used to remotely log in on the Linux system. This can be used to remotely log in on the Linux system.
To login via SSH, use username `root` with password `root`. To login via SSH, use username `root` with password `root`.
@ -247,50 +246,36 @@ To login via SSH, use username `root` with password `root`.
For security reasons, the SSH server is disabled by default. 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. 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. 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. To enable the SSH server, login on the USB console as described above.
Then run the following command: `puzzle-sshcfg enable` . Then run the following command: `puzzle-sshcfg enable` .
Finally, run `reboot` to reboot the Red Pitaya. Finally, run `reboot` to reboot the Red Pitaya.
From this point onward, the SSH server will be started automatically during boot. From this point onward, the SSH server will be started automatically during boot.
## Analog sample data stream ## Data stream protocol
A client may connect to TCP port 5001 to receive analog sample data. Clients may connect to TCP port 5001 to receive analog sample data,
At most one client can be connected to this port at any time. 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, If a new client connects while another connection is still active,
the server closes the old connection and uses the new connection instead. the server closes the old connection and uses the new connection instead.
Data flows through the TCP connection in one direction: from the server Data flows through these TCP connections in one direction:
to the client. from the server to the client.
The client must not send anything back to the server. The client must not send anything back to the server.
Analog sample data are transferred as a sequence of 64-bit binary messages. 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. Each message is sent as 8 bytes with the least significant byte first.a
The message stream corresponds to the output data format of the The message streams correspond to the output data format of the
analog acquisition chain as described in the [FPGA firmware documentation](fpga_firmware.md#). analog acquisition chain and the timetagger 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 ## Remote control protocol
A client may connect to TCP port 5025 to send commands. Clients may connect to TCP port 5025 to send commands.
Multiple clients may be simultaneously connected to this port. Multiple clients may be simultaneously connected to this port.
In that case, it is the responsibility of the clients to make sure In that case, it is the responsibility of the clients to make sure
that they do not interfere with eachother. that they do not interfere with eachother.
@ -478,7 +463,7 @@ Response: floating point number indicating the gain calibration for the active i
Command: `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. 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. 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]?` ### `AIN:CHn:SAMPLE[:RAW]?`
@ -535,8 +520,8 @@ 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:** 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. **Note:** When auto-trigger mode is selected, the downsample factor must be at least 2, or 4 if 4 channels are active.
When 4 channels are active, the downsample factor must be at least 2, or 4 if auto-trigger mode is selected. In other trigger modes, the downsample factor must be at least 1, or 2 if 4 channels are active.
### `AIN:SRATE:MODE` ### `AIN:SRATE:MODE`