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

Compare commits

base: joris:0a857f4c23294a09628cafefdc994b058bfd51e3
Branches Tags
joris:master
joris:v1.0
...
compare: joris:4d32b1bd93c8847f004deddacec08a4d62fd6d51
Branches Tags
joris:master
joris:v1.0

2 Commits
0a857f4c23 ... 4d32b1bd93

Author SHA1 Message Date
Joris van Rantwijk 4d32b1bd93 Add development manual 2024-10-26 00:39:10 +02:00
Joris van Rantwijk 4706302dd5 Document GPIO 3 2024-10-19 20:31:34 +02:00
8 changed files with 1002 additions and 505 deletions
Show Stats Expand all files Collapse all files

2
README.md
View File

@ -28,7 +28,7 @@ PuzzleFW has the following features:
Further details about the firmware are in these documents:
- [User manual](doc/user_manual.md)
- Developer manual, including the build procedure, to be written
- [Developer manual](doc/devel_manual.md), including build procedure
- [FPGA firmware description](doc/fpga_firmware.md)
## Supported boards

479
doc/devel_manual.md Normal file
View File

@ -0,0 +1,479 @@
---
gitea: none
include_toc: true
---
# Development manual
This document gives an overview of the internal structure of the PuzzleFW firmware package.
It also describes the process to build the FPGA firmware and the embedded software.
## FPGA design overview
The FPGA captures ADC samples and digital input signals.
ADC samples go into the analog acquisition chain.
The acquisition chain handles triggering and optional downsampling.
A configurable number of samples are collected following each trigger event.
Trigger events and collected samples are transferred to a buffer in DDR memory via the AXI slave interface of the Zynq processing system.
Digital signals go into a timetagger subsystem.
The timetagger detects edges on selected signals and assigns timestamps to such events.
Timestamped events are transferred to a buffer in DDR memory via the AXI slave interface.
All synchronous elements are clocked at 125 MHz, derived from the ADC sample clock.
![FPGA design schematic](fpga_design_schematic.png)
### Block design
A Vivado block design contains the Zynq processing system (ARM), AXI interconnect, and AXI-to-APB bridge.
This block design is instantiated in the top-level VHDL file.
![Block design](fpga_block_design.png)
### PS-to-PL interfaces
The following interfaces are used between the PS (ARM) and PL (FPGA):
- M\_AXI\_GP0 <br>
Used by embedded software to read and write registers in the FPGA via AXI and APB bus.
This interface is mapped to addresses 0x43000000 to 0x431fffff in the PS address map.
- S\_AXI\_HP0 <br>
Used by FPGA firmware to read and write DDR memory.
- GPIO <br>
The PS controls a few specific digital signals in the FPGA via GPIO lines.
One of these lines is a global reset signal for the FPGA firmware.
- SPI0 <br>
Routed via EMIO through the FPGA to the SPI bus of the ADCs (only on 4-input boards).
- IRQ\_F2P <br>
Used by FPGA firmware to trigger interrupts in the PS.
- FCLK\_CLK0 <br>
Fixed 200 MHz clock generated by the PS.
On 4-input boards, the FPGA uses this clock as reference for IODELAY primitives.
On 2-input boards, this clock is not used.
### ADC input timing
The ADC transfers samples via a parallel source-synchronous interface.
The interface is synchronous to a 125 MHz clock output signal from the ADC.
This is also the main clock source of the FPGA design.
On 2-input Red Pitaya boards, the ADC is hardwired to operate in _full rate CMOS mode_.
Each analog channel has 14 parallel data signals from ADC to FPGA.
These data signals transition on the falling clock edge and are captured by the FPGA on the rising clock edge.
Data signals are captured in the FPGA in IOB flip-flops.
These flip-flops are clocked on a 125 MHz clock, derived by a PLL from the ADC output clock.
It turns out that a phase shift of 90 degrees in the PLL provides near-optimal timing for capturing the data signals.
This follows from synthesizer timing reports and has been confirmed experimentally by testing different PLL phase shift settings.
On 4-input Red Pitaya boards, only 7 parallel data signals per analog channel are connected from the ADCs to the FPGA.
The ADCs must be programmed (via SPI) to operate in _double data rate CMOS mode_.
In this mode, the data lines transition on both edges of the 125 MHz clock.
The data signals are routed through IDELAY components in the FPGA before being captured in IDDR registers.
The IDDR are clocked on the 125 MHz clock from the ADC that produces the samples (without PLL).
The IDELAY components use a fixed delay, tuned to 2.34 ns to optimize data capture timing.
Timing reports indicate that this provides sufficient margin.
This has been confirmed experimentally by testing different phase-shift settings of the ADC output clock.
The main FPGA design runs on a 125 MHz clock, derived by a PLL from the ADC that samples channels 1 and 2.
Transferring samples from channels 3 and 4 to the main clock is slightly tricky because the two ADC clocks may be skewed with respect to each other.
A few mysterious timing constraints were added to deal with this.
## Embedded software overview
The purpose of the embedded software is to make the system remotely accessible via the network.
The software collects data from the FPGA and transmits it via TCP.
Similarly, the software accepts remote control commands via TCP and executes these by accessing registers in the FPGA.
### Operating system
The embedded software runs within an embedded Linux system on the Red Pitaya.
The core operating system is based on [Buildroot](https://buildroot.org/), a framework that builds an embedded Linux system from scratch.
Buildroot automatically downloads and builds many additional open source packages that are needed to construct the embedded system.
Among these packages is a cross-compilation toolchain.
The kernel for the embedded system is built from the [Xilinx distribution of the Linux kernel](https://github.com/Xilinx/linux-xlnx).
It is necessary to use the Xilinx variant of Linux.
The vanilla Linux kernel can run on the Red Pitaya, but the Xilinx kernel provides important features that are missing from the vanilla kernel, such as programming the FPGA.
The shell and system utilities of the embedded system are based on Busybox.
Dropbear is installed as SSH server, but disabled by default.
The set of packages to be installed in the embedded system, along with their compile-time settings, are specified in the Buildroot configuration.
Further tweaking of the embedded system is done via a _filesystem overlay_: a set of files that are injected into the embedded root filesystem as a final step.
The overlay mechanism is used to install boot scripts and configuration files.
It is also used to install custom user space software.
### Boot flow
[U-Boot](https://source.denx.de/u-boot/u-boot) is used as boot loader and as _secondary program loader_ (SPL).
Building U-Boot requires a proper device tree for the board.
Building the U-Boot SPL image also requires the file `ps7_init_gpl.c`.
The contents of this file depend on the configuration of the Zynq programming system which is specified in the Vivado block design.
To generate this file, the FPGA design must be _exported_ from Vivado in the form of an XSA file.
The XSA file is actually a ZIP archive which contains `ps7_init_gpl.c` and the corresponding header file.
The U-Boot build script (`12_build_uboot.sh`) copies these files to the correct location in the U-Boot source tree.
The boot process of the Red Pitaya is as follows:
- The Zynq PS boots from ROM.
The ROM program reads `boot.bin` from the SD card and runs it.
- `boot.bin` is the U-Boot SPL image.
It initializes many subsystems in the Zynq PS, including the DDR memory controller.
It then reads `u-boot.img` from the SD card and runs it.
Note that we don't use a Xilinx FSBL at all.
Many Zynq tutorials explain how to build `boot.bin` using Xilinx tools.
That requires a non-free FSBL image which must be built in a Vitis project.
The PuzzleFW package avoids that whole mess by using U-Boot SPL instead.
- `u-boot.img` is the main U-Boot program image.
It reads and executes `boot.scr`, a script which describes the Linux boot process.
The script instructs U-Boot to read the Linux kernel `uImage`,
the device tree `devicetree.dtb` and the root filesystem image `rootfs.cpio.uboot`
from the SD card.
It then runs the Linux kernel.
- `uImage` is the Linux kernel image.
The kernel initializes drivers and subsystems.
The root filesystem is unpacked and mounted as a RAM filesystem.
The filesystem is writeable, but any changes remain in RAM and will be forgotten on the next reboot.
- A set of boot scripts are invoked to initialize the embedded system and start services.
Most of these scripts are prepared by Buildroot, but some scripts have been tweaked or specially created for PuzzleFW.
These scripts take care of the following:
- Read the MAC address from the EEPROM on the Red Pitaya board, and assign it to the Ethernet interface.
- Set a unique hostname `rp-XXXXXX` based on the MAC address.
- Obtain an IPv4 address via DHCP or a preconfigured static address.
This is controlled by a file in the configuration partition of the SD card.
- Start an SSH server, if enabled. By default, this is disabled.
- Read a BIT file from the SD card and program the FPGA.
Information in the EEPROM is used to determine which FPGA image must be used.
- Configure ADCs on the Red Pitaya board via SPI or GPIO.
- Load the Linux kernel driver to access the FPGA firmware.
- Run a user space program that accepts remote control commands via TCP.
### Linux kernel driver
A custom Linux kernel module is used to access the FPGA firmware.
This module is called `puzzlefw.ko`.
The driver is based on the Linux UIO framework.
The kernel module itself has minimal functionality.
Its only functions are:
- mapping the register address range of the FPGA to user space via mmap
- mapping the DMA buffer to user space via mmap
- handling FPGA interrupts and notifying user space via UIO
All non-trivial interactions with the FPGA are done in user space.
This includes managing the DMA data flow.
### User space software
The FPGA firmware is controlled by a user space program.
This program accepts remote control commands via TCP.
Commands are handled by reading and writing registers in the FPGA.
The program also collects data from the FPGA via DMA, and transmits these data through the network via TCP.
The program is written in C++.
It uses Boost Asio, an asynchronous I/O framework.
### Configuration partition
While the embedded software runs, the root filesystem is located in RAM.
The filesystem is writable, but any changes will be lost on the next boot.
In order to store persistent settings, the SD card has a separate configuration partition.
This is `/dev/mmcblk0p2`, formatted as Ext4.
The following files are stored there:
- `network.conf`: IP address configuraton (DHCP or static IP address)
- `calibration.conf`: analog calibration coefficients
- `start_ssh.conf`: enables or disables starting the SSH server
- SSH host key
The configuration partition is temporarily mounted read-only during boot, to read the configuration files.
Otherwise, the partition is only accessed when the configuration is modified.
In such cases, the partition is temporarily mounted to write the updated files, then unmounted again.
As a result, writes to the SD card occur only when the user changes the persistent configuration of the system.
This avoids unnecessary wear of the SD card.
## Build procedure
A Linux PC (x86-64) is required to build the system.
Development was done with Debian 12 (bookworm).
Other Linux distributions will probably also work.
The build process consists of two main steps.
These steps must be done in the following order:
1. Build the FPGA firmware for the Zynq PL.
2. Build the embedded software for the Zynq PS.
## Building FPGA firmware
Building the FPGA firmware requires Vivado release 2020.2.
Later releases will probably work, but may require adjustments.
There are two ways to build the firmware: as a Vivado project, or in Vivado non-project mode.
In most cases, non-project mode will be easier.
### Preparing the build environment
**Install Vivado** <br>
Download and install Vivado 2020.2.
The build scripts assume that Vivado is installed in `/opt/Xilinx/Vivado/2020.2`.
If a different location is used, it must be configured in the script environment file.
**Configure paths** <br>
If necessary, edit the file `redpitaya-puzzlefw/fpga/script_env` and make sure that `VIVADO_DIR` points to the directory where Vivado is installed.
**Install board files** <br>
When running Vivado in project mode, it requires board definition files
for the Red Pitaya.
These files are available from the original Red Pitaya FPGA repository.
Use the following steps to download and install these files.
- Go to directory `redpitaya-puzzlefw/fpga`
- Run `./01_get_redpitaya.sh`
- Copy the complete folder `redpitaya-puzzlefw/fpga/RedPitaya-FPGA/brd/redpitaya`
to `/opt/Xilinx/Vivado/2020.2/data/boards/board_files`
### Building FPGA firmware in non-project mode
There are two top-level designs, each targeting a specific Red Pitaya board type.
These designs are built in separate design runs:
- `puzzlefw_top` for the normal (2-input) Red Pitaya
- `puzzlefw_top_4ch` for the 4-input Red Pitaya
The following steps invoke Vivado in non-project mode to handle synthesis, implementation and bitfile generation of each top-level design.
- Go to directory `redpitaya-puzzlefw/fpga`
- Run `./11_build_bitfile.sh`
- Run `./12_build_bitfile_4ch.sh`
It is normal for the build process to display a large number of messages and warnings.
The build process produces the following output files:
- `puzzlefw_top.bit.bin` <br>
This file is required to program the FPGA.
- `redpitaya_puzzlefw.xsa` <br>
This file contains a description of the system configuration.
It is necessary to build U-boot.
- Similar files for the 4-input design.
The build process also creates various logs and report files in directory `vivado/output` (or `output_4ch`).
It is recommended to review the contents of `vivado/output/post_route_timing.rpt` to make sure that it does not report any timing violations and contains the line `All user specified timing constraints are met`.
### Building FPGA firmware in project mode
The repository contains a Vivado project file to build the design for the normal (2-input) Red Pitaya.
There is currently no project file for the 4-input board.
The following steps may be used to build the design in Vivado in project mode:
- Start Vivado, typically by running something like <br>
`source /opt/Xilinx/Vivado/2020.1/settings64.sh ; vivado`
- Open the project file `redpitaya-puzzlefw/fpga/vivado/redpitaya_puzzlefw.xpr`.
- In the *Flow Navigator* panel on the left, click on "Run Synthesis", then click "Ok".
It may appear that very little is happening, but synthesis should be running in the background.
The status is displayed in the *Design Runs* panel at the bottom of the screen.
- When synthesis completes successfully, choose "Run Implementation" and click "Ok".
- When implementation completes successfully, choose "Generate Bitstream" and click "Ok".
- When bitstream generation completes successfully, choose "View Reports".
- In the *Project Summary* panel, check that timing is ok (Number of Falling Endpoints should be 0).
- In the main menu bar, click *File*, *Export*, *Export Hardware*.
Select "Pre-synthesis".
Change XSA file name and export folder to write the XSA file to
`redpitaya-puzzlefw/fpga/redpitaya_puzzlefw.xsa`.
Then click "Finish".
The build process produces a BIT file `puzzlefw_top.bit` containing the FPGA design.
The Zynq software needs this file in a different format (`.bit.bin`) which can not be created by the Vivado IDE.
Use the following steps to convert the BIT file:
- Go to directory `redpitaya-puzzlefw/fpga`
- Run `./make_binfile.sh vivado/redpitaya_puzzlefw.runs/impl_1/puzzlefw_top.bit`
### Editing the block design
Most source files for the FPGA firmware can be edited with any text editor.
The VHDL source files are in directory `redpitaya-puzzlefw/fpga/rtl`.
Constraint files are in `redpitaya-puzzlefw/fpga/constraints`.
The only exception is the block design that links the Zynq processing system to the FPGA logic.
The block design is stored as `redpitaya-puzzlefw/fpga/vivado/redpitaya_puzzlefw.srcs/sources_1/bd/puzzlefw/puzzlefw.bd`.
This file can only be edited through Vivado, as follows:
- Start Vivado as described above.
- Open the project file `redpitaya-puzzlefw/fpga/vivado/redpitaya_puzzlefw.xpr`.
- In the *Flow Navigator* panel on the left, click on "Open Block Design".
- Make changes as needed.
- In the main menu bar, click *File*, *Save Block Design*.
Both top-level designs (2-input and 4-input boards) use the same block design file.
This is a tricky situation because the block design file targets a specific FPGA part (e.g. `xc7z010clg400-1`), but the two boards have different FPGA parts.
When using the non-project build flow, we find that this just seems to work without issues.
During the build flow, Vivado quietly modifies the block design file to match the target part of the design run.
### Adding VHDL files to the project
When VHDL files are added to the project, both the Vivado project and the non-project build script must be updated.
To update the Vivado project:
- Open the project file `redpitaya-puzzlefw/fpga/vivado/redpitaya_puzzlefw.xpr`.
- In the *Flow Navigator* panel on the left, click "Add Sources".
- Add VHDL files directly from the directory `redpitaya-puzzlefw/fpga/rtl`.
Do not select "Copy sources into project".
- Vivado may get a confused because, by default, it does not support VHDL-2008.
To fix this, in the *Sources* panel, click "Libraries" below the hierachy tree.
Right-click each new VHDL file, choose "Set File Type" and change the file type to "VHDL 2008".
Vivado stores all project settings in the XPR file.
Changes to that file must be tracked in the Git repository.
To update the non-project build script:
- Open `redpitaya-puzzlefw/fpga/vivado/nonproject.tcl` in a text editor.
- Add `read_vhdl` statements to load the new VHDL files.
## Building embedded software
### Preparing the build environment
Install the following Debian packages (or equivalent packages on other Linux distributions):
<br>
`build-essential`,
`bc`,
`bzip2`,
`cpio`,
`dosfstools`,
`file`,
`git`,
`libncurses-dev`,
`mtools`,
`patch`,
`perl`,
`rsync`,
`unzip`,
`wget`.
### Downloading software
Use the following steps to download required software packages:
- Go to directory `redpitaya-puzzlefw/sw`
- Run `./01_get_buildroot.sh` to download [Buildroot](https://buildroot.org).
- Run `./02_get_uboot.sh` to download [U-Boot](https://source.denx.de/u-boot/u-boot).
- Run `./03_get_kernel.sh` to download the [Xilinx distribution of the Linux kernel](https://github.com/Xilinx/linux-xlnx).
### Building embedded software
Use the following steps to build the embedded software:
- Go to directory `redpitaya-puzzlefw/sw`
- Run `./11_build_buildroot.sh` to configure and build Buildroot.
<br>
One of the outcomes of this step is a cross-compilation toolchain for the ARM architecture.
Other build steps need this toolchain, therefore this must be the first step of the build flow.
- Run `./12_build_uboot.sh` to configure and build U-Boot.
<br>
This step requires the file `redpitaya-puzzlefw/fpga/redpitaya_puzzlefw.xsa` from the FPGA build flow.
- Run `./13_build_kernel.sh` to configure and build the Linux kernel.
- Run `./14_build_devicetree.sh` to build the device tree.
- Run `./15_build_driver.sh` to build the Linux kernel module that provides access to the FPGA firmware.
- Run `./16_build_userspace.sh` to build user space applications that will run on the Red Pitaya.
- Run `./21_rebuild_rootfs.sh` to re-build the embedded root filesystem, including the kernel driver and user space tools that were built during previous steps.
- Run `./22_prepare_sdcard.sh` to collect the files that must be installed on the SD card for the Red Pitaya.
- Run `./23_sdcard_image.sh` to build an image file which can be written to the SD card.
### Changing the Buildroot configuration
The Buildroot configuration for this project is stored in the folder `config`.
To change the configuration, start by applying the existing settings, then run the Buildroot configuration tool, then copy the new settings to the `config` folder.
Use the following steps:
- Copy `sw/config/buildroot_puzzlefw_defconfig` to `sw/buildroot-2023.02.08/.config`
- Go to `sw/buildroot-2023.02.8`
- Run `make olddefconfig`
- Run `make nconfig`
- Use the menu to change the configuration as needed.
- Run `make savedefconfig`
- Copy `sw/buildroot-2023.02.08/defconfig` to `sw/config/buildroot_puzzlefw_defconfig`
After changing the Buildroot configuration, rerun step `11_build_buildroot.sh`.
### Changing the U-Boot configuration
The U-Boot configuration for this project is stored in the folder `config`.
To change the configuration, start by applying the existing settings, then run the U-boot configuration tool, then copy the new settings to the `config` folder.
Use the following steps:
- Copy `sw/config/uboot_redpitaya_puzzlefw_defconfig` to `sw/u-boot/configs/redpitaya_puzzlefw_defconfig`
- Go to `sw/u-boot`
- Run `make redpitaya_puzzlefw_defconfig`
- Run `make nconfig`
- Use the menu to change the configuration as needed.
- Run `make savedefconfig`
- Copy `sw/u-boot/defconfig` to `sw/config/uboot_redpitaya_puzzlefw_defconfig`
After changing the Buildroot configuration, rerun step `12_build_uboot.sh`.
### Changing the Linux kernel configuration
The Linux kernel configuration for this project is stored in the folder `config`.
To change the configuration, start by applying the existing settings, then run the kernel configuration tool, then copy the new settings to the `config` folder.
Use the following steps:
- Copy `sw/config/linux_redpitaya_puzzlefw_defconfig` to `sw/linux-xlnx/.config`
- Go to `sw/linux-xlnx`
- Run `make ARCH=arm olddefconfig`
- Run `make ARCH=arm nconfig`
- Use the menu to change the configuration as needed.
- Run `make ARCH=arm savedefconfig`
- Copy `sw/linux-xlnx/defconfig` to `sw/config/linux_redpitaya_puzzlefw_defconfig`
After changing the Buildroot configuration, rerun step `13_build_kernel.sh`.
### Preparing the SD card
This section explains how to set up the SD card manually.
It is not normally necessary to do this.
An easier way to set up the SD card is by building an image file and writing it to the card.
The SD card contains two partitions:
- `/dev/mmcblk0p1` is a 256 MB partition with FAT filesystem
- `/dev/mmcblk0p2` is a 256 MB partition with an Ext4 filesystem
The FAT partition contains the following files:
| File | Description |
|----------------------------|-------------|
| `boot.bin` | first stage boot loader for the Zynq (built by U-Boot) |
| `u-boot.img` | main boot loader program (U-Boot) |
| `boot.scr` | boot script for U-Boot |
| `devicetree.dtb` | device tree for the Linux kernel |
| `uImage` | Linux kernel image |
| `rootfs.cpio.uboot` | root filesystem image |
| `puzzlefw_top.bit.bin` | FPGA firmware image for 2-input board |
| `puzzlefw_top_4ch.bit.bin` | FPGA firmware image for 4-input board |
The Ext4 partition can be left empty initially.
Configuration files will be written to this partition by the embedded system.
The following commands may be used to format the two partitions:
mkdosfs -F 16 /dev/mmcblk0p1
mke2fs -t ext4 -b 4096 /dev/mmcblk0p2

BIN
doc/fpga_block_design.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 166 KiB

BIN
doc/fpga_design_schematic.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

506
doc/fpga_design_schematic.svg Normal file
View File

@ -0,0 +1,506 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
width="297mm"
height="210mm"
viewBox="0 0 297 210"
version="1.1"
id="svg5"
inkscape:version="1.2.2 (b0a8486541, 2022-12-01)"
sodipodi:docname="fpga_design_overview.svg"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns="http://www.w3.org/2000/svg"
xmlns:svg="http://www.w3.org/2000/svg">
<sodipodi:namedview
id="namedview7"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:showpageshadow="2"
inkscape:pageopacity="0.0"
inkscape:pagecheckerboard="0"
inkscape:deskcolor="#d1d1d1"
inkscape:document-units="mm"
showgrid="true"
inkscape:zoom="1.2938725"
inkscape:cx="71.490816"
inkscape:cy="177.37451"
inkscape:window-width="1514"
inkscape:window-height="1247"
inkscape:window-x="576"
inkscape:window-y="53"
inkscape:window-maximized="0"
inkscape:current-layer="layer1"
inkscape:lockguides="false">
<inkscape:grid
type="xygrid"
id="grid29"
originx="0"
originy="0" />
</sodipodi:namedview>
<defs
id="defs2">
<marker
style="overflow:visible"
id="marker29490"
refX="0"
refY="0"
orient="auto"
inkscape:stockid="Dot"
markerWidth="4"
markerHeight="4"
viewBox="0 0 5.4 5.4"
inkscape:isstock="true"
inkscape:collect="always"
preserveAspectRatio="xMidYMid">
<path
transform="scale(0.45)"
style="fill:context-fill;fill-rule:evenodd;stroke:context-stroke;stroke-width:2"
d="M 5,0 C 5,2.76 2.76,5 0,5 -2.76,5 -5,2.76 -5,0 c 0,-2.76 2.3,-5 5,-5 2.76,0 5,2.24 5,5 z"
id="path29488"
sodipodi:nodetypes="sssss" />
</marker>
<marker
style="overflow:visible"
id="marker29344"
refX="0"
refY="0"
orient="auto"
inkscape:stockid="Dot"
markerWidth="4"
markerHeight="4"
viewBox="0 0 5.4 5.4"
inkscape:isstock="true"
inkscape:collect="always"
preserveAspectRatio="xMidYMid">
<path
transform="scale(0.45)"
style="fill:context-fill;fill-rule:evenodd;stroke:context-stroke;stroke-width:2"
d="M 5,0 C 5,2.76 2.76,5 0,5 -2.76,5 -5,2.76 -5,0 c 0,-2.76 2.3,-5 5,-5 2.76,0 5,2.24 5,5 z"
id="path29342"
sodipodi:nodetypes="sssss" />
</marker>
<marker
style="overflow:visible"
id="marker29218"
refX="0"
refY="0"
orient="auto"
inkscape:stockid="Dot"
markerWidth="4"
markerHeight="4"
viewBox="0 0 5.4 5.4"
inkscape:isstock="true"
inkscape:collect="always"
preserveAspectRatio="xMidYMid">
<path
transform="scale(0.45)"
style="fill:context-fill;fill-rule:evenodd;stroke:context-stroke;stroke-width:2"
d="M 5,0 C 5,2.76 2.76,5 0,5 -2.76,5 -5,2.76 -5,0 c 0,-2.76 2.3,-5 5,-5 2.76,0 5,2.24 5,5 z"
id="path29216"
sodipodi:nodetypes="sssss" />
</marker>
<marker
style="overflow:visible"
id="marker9466"
refX="0"
refY="0"
orient="auto"
inkscape:stockid="Dot"
markerWidth="4"
markerHeight="4"
viewBox="0 0 5.4 5.4"
inkscape:isstock="true"
inkscape:collect="always"
preserveAspectRatio="xMidYMid">
<path
transform="scale(0.45)"
style="fill:context-fill;fill-rule:evenodd;stroke:context-stroke;stroke-width:2"
d="M 5,0 C 5,2.76 2.76,5 0,5 -2.76,5 -5,2.76 -5,0 c 0,-2.76 2.3,-5 5,-5 2.76,0 5,2.24 5,5 z"
id="path9464"
sodipodi:nodetypes="sssss" />
</marker>
<marker
style="overflow:visible"
id="TriangleStart"
refX="0"
refY="0"
orient="auto-start-reverse"
inkscape:stockid="TriangleStart"
markerWidth="4.3239999"
markerHeight="4.9988437"
viewBox="0 0 5.3244081 6.1553851"
inkscape:isstock="true"
inkscape:collect="always"
preserveAspectRatio="xMidYMid">
<path
transform="scale(0.5)"
style="fill:context-stroke;fill-rule:evenodd;stroke:context-stroke;stroke-width:1pt"
d="M 5.77,0 -2.88,5 V -5 Z"
id="path135" />
</marker>
<rect
x="50"
y="160"
width="110"
height="50"
id="rect8262" />
<rect
x="50"
y="160"
width="110"
height="50"
id="rect9048" />
<rect
x="50"
y="160"
width="110"
height="50"
id="rect10560" />
<rect
x="50"
y="160"
width="110"
height="50"
id="rect10566" />
<rect
x="50"
y="160"
width="105.41406"
height="67.484375"
id="rect10624" />
<rect
x="50"
y="160"
width="150.125"
height="27.484377"
id="rect12086" />
<rect
x="50"
y="160"
width="150.125"
height="27.484377"
id="rect12123" />
<rect
x="50"
y="160"
width="150.125"
height="27.484377"
id="rect12855" />
<rect
x="50"
y="160"
width="150.125"
height="27.484377"
id="rect14313" />
<rect
x="50"
y="160"
width="150.125"
height="27.484377"
id="rect14321" />
<rect
x="50"
y="160"
width="150.125"
height="27.484377"
id="rect16505" />
<rect
x="50"
y="160"
width="150.125"
height="27.484377"
id="rect17237" />
<rect
x="50"
y="160"
width="150.125"
height="27.484377"
id="rect20229" />
<rect
x="50"
y="160"
width="105.41406"
height="67.484375"
id="rect29672" />
<rect
x="50"
y="160"
width="80.114585"
height="23.184275"
id="rect29708" />
</defs>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1">
<rect
style="fill:none;stroke:#000000;stroke-width:0.3;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
id="rect133"
width="190.6516"
height="84.732727"
x="26.458334"
y="7.9375" />
<rect
style="fill:#fff799;fill-opacity:1;stroke:#000000;stroke-width:0.5;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1"
id="rect2424"
width="31.750004"
height="52.916664"
x="179.91667"
y="13.229167" />
<rect
style="fill:#b2ffb2;fill-opacity:1;stroke:#000000;stroke-width:0.5;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1"
id="rect6690"
width="31.75"
height="10.583332"
x="31.75"
y="13.229167" />
<rect
style="fill:#ccdfff;fill-opacity:1;stroke:#000000;stroke-width:0.5;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
id="rect6694"
width="42.068748"
height="15.874999"
x="74.270424"
y="13.594255" />
<rect
style="fill:#ffcdb2;fill-opacity:1;stroke:#000000;stroke-width:0.5;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1"
id="rect6698"
width="42.333328"
height="10.583332"
x="127"
y="13.229167" />
<rect
style="fill:#cbdcff;fill-opacity:1;stroke:#000000;stroke-width:0.5;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1"
id="rect9828"
width="42.068752"
height="15.875004"
x="74.083336"
y="50.270832" />
<text
xml:space="preserve"
transform="matrix(0.26458333,0,0,0.26458333,169.33334,-27.245888)"
id="text10622"
style="font-size:14.6667px;line-height:125%;font-family:'DejaVu Sans';-inkscape-font-specification:'DejaVu Sans';letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect10624);display:inline;fill:none;fill-opacity:0.75;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"><tspan
x="50"
y="172.97659"
id="tspan32207"><tspan
style="fill:#000000;fill-opacity:1;stroke:none"
id="tspan32205">block design
</tspan></tspan><tspan
x="50"
y="191.30997"
id="tspan32211"><tspan
style="fill:#000000;fill-opacity:1;stroke:none"
id="tspan32209">(PS)</tspan></tspan></text>
<rect
style="fill:#ffcdb2;fill-opacity:1;stroke:#000000;stroke-width:0.5;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1"
id="rect11354"
width="42.068748"
height="10.318751"
x="127"
y="34.395832" />
<text
xml:space="preserve"
transform="matrix(0.26458333,0,0,0.26458333,116.20478,-26.880356)"
id="text12084"
style="font-size:13.3333px;line-height:125%;font-family:'DejaVu Sans';-inkscape-font-specification:'DejaVu Sans';letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect12086);display:inline;fill:none;fill-opacity:0.75;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"><tspan
x="50"
y="171.79685"
id="tspan32215"><tspan
style="font-family:'DejaVu Sans Mono';-inkscape-font-specification:'DejaVu Sans Mono';fill:#000000;fill-opacity:1;stroke:none"
id="tspan32213">dma_write_channel</tspan></tspan></text>
<rect
style="fill:#ffcdb2;fill-opacity:1;stroke:#000000;stroke-width:0.5;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1"
id="rect12117"
width="42.333328"
height="10.583332"
x="127"
y="55.5625" />
<text
xml:space="preserve"
transform="matrix(0.26458333,0,0,0.26458333,116.20478,15.452982)"
id="text12121"
style="font-size:13.3333px;line-height:125%;font-family:'DejaVu Sans';-inkscape-font-specification:'DejaVu Sans';letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect12123);display:inline;fill:none;fill-opacity:0.75;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"><tspan
x="50"
y="171.79685"
id="tspan32219"><tspan
style="font-family:'DejaVu Sans Mono';-inkscape-font-specification:'DejaVu Sans Mono';fill:#000000;fill-opacity:1;stroke:none"
id="tspan32217">dma_write_channel</tspan></tspan></text>
<text
xml:space="preserve"
transform="matrix(0.26458333,0,0,0.26458333,116.20479,-5.732634)"
id="text12853"
style="font-size:13.3333px;line-height:125%;font-family:'DejaVu Sans';-inkscape-font-specification:'DejaVu Sans';letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect12855);display:inline;fill:none;fill-opacity:0.75;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"><tspan
x="50"
y="171.79685"
id="tspan32223"><tspan
style="font-family:'DejaVu Sans Mono';-inkscape-font-specification:'DejaVu Sans Mono';fill:#000000;fill-opacity:1;stroke:none"
id="tspan32221">dma_axi_master</tspan></tspan></text>
<text
xml:space="preserve"
transform="matrix(0.26458333,0,0,0.26458333,21.166668,-26.933748)"
id="text14311"
style="font-size:13.3333px;line-height:125%;font-family:'DejaVu Sans';-inkscape-font-specification:'DejaVu Sans';letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect14313);display:inline;fill:none;fill-opacity:0.75;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"><tspan
x="50"
y="171.79685"
id="tspan32227"><tspan
style="font-family:'DejaVu Sans Mono';-inkscape-font-specification:'DejaVu Sans Mono';fill:#000000;fill-opacity:1;stroke:none"
id="tspan32225">adc_capture</tspan></tspan></text>
<rect
style="fill:#b2ffb2;fill-opacity:1;stroke:#000000;stroke-width:0.5;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1"
id="rect14315"
width="31.75"
height="10.583332"
x="31.75"
y="50.270832" />
<text
xml:space="preserve"
transform="matrix(0.26458333,0,0,0.26458333,21.166666,10.10792)"
id="text14319"
style="font-size:13.3333px;line-height:125%;font-family:'DejaVu Sans';-inkscape-font-specification:'DejaVu Sans';letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect14321);display:inline;fill:none;fill-opacity:0.75;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"><tspan
x="50"
y="171.79685"
id="tspan32231"><tspan
style="font-family:'DejaVu Sans Mono';-inkscape-font-specification:'DejaVu Sans Mono';fill:#000000;fill-opacity:1;stroke:none"
id="tspan32229">deglitch</tspan></tspan></text>
<text
xml:space="preserve"
transform="matrix(0.26458333,0,0,0.26458333,63.499996,10.107924)"
id="text16503"
style="font-size:13.3333px;line-height:125%;font-family:'DejaVu Sans';-inkscape-font-specification:'DejaVu Sans';letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect16505);display:inline;fill:none;fill-opacity:0.75;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"><tspan
x="50"
y="171.79685"
id="tspan32235"><tspan
style="font-family:'DejaVu Sans Mono';-inkscape-font-specification:'DejaVu Sans Mono';fill:#000000;fill-opacity:1;stroke:none"
id="tspan32233">timetagger</tspan></tspan></text>
<text
xml:space="preserve"
transform="matrix(0.26458333,0,0,0.26458333,63.687086,-26.568659)"
id="text17235"
style="font-size:13.3333px;line-height:125%;font-family:'DejaVu Sans';-inkscape-font-specification:'DejaVu Sans';letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect17237);display:inline;fill:none;fill-opacity:0.75;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"><tspan
x="50"
y="171.79685"
id="tspan32239"><tspan
style="font-family:'DejaVu Sans Mono';-inkscape-font-specification:'DejaVu Sans Mono';fill:#000000;fill-opacity:1;stroke:none"
id="tspan32237">acquisition_chain</tspan></tspan></text>
<rect
style="fill:#ccffff;fill-opacity:1;stroke:#000000;stroke-width:0.5;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1"
id="rect20223"
width="31.74999"
height="10.583332"
x="179.91667"
y="76.729164" />
<text
xml:space="preserve"
transform="matrix(0.26458333,0,0,0.26458333,168.70976,36.600693)"
id="text20227"
style="font-size:13.3333px;line-height:125%;font-family:'DejaVu Sans';-inkscape-font-specification:'DejaVu Sans';letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect20229);display:inline;fill:none;fill-opacity:0.75;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"><tspan
x="50"
y="171.79685"
id="tspan32243"><tspan
style="font-family:'DejaVu Sans Mono';-inkscape-font-specification:'DejaVu Sans Mono';fill:#000000;fill-opacity:1;stroke:none"
id="tspan32241">registers</tspan></tspan></text>
<path
style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:0.75;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#TriangleStart)"
d="m 63.5,18.520833 7.9375,0"
id="path21149"
sodipodi:nodetypes="cc" />
<path
style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:0.75;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#TriangleStart)"
d="m 63.5,55.5625 7.937501,0"
id="path22406"
sodipodi:nodetypes="cc" />
<path
style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:0.75;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#TriangleStart)"
d="m 116.41667,18.520833 h 7.9375"
id="path22424"
sodipodi:nodetypes="cc" />
<path
style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:0.75;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#TriangleStart)"
d="m 116.41667,60.854167 h 7.9375"
id="path22430"
sodipodi:nodetypes="cc" />
<path
style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:0.75;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#TriangleStart)"
d="m 169.33333,39.6875 h 7.9375"
id="path22436"
sodipodi:nodetypes="cc" />
<path
style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:0.75;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#TriangleStart)"
d="M 140.22917,55.5625 V 47.625"
id="path22442"
sodipodi:nodetypes="cc" />
<path
style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:0.75;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#TriangleStart)"
d="M 140.22917,23.8125 V 31.75"
id="path22448"
sodipodi:nodetypes="cc" />
<path
style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#TriangleStart)"
d="M 58.208333,50.270833 V 39.6875 H 79.375 l 0,-7.9375"
id="path22557"
sodipodi:nodetypes="cccc" />
<path
style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:0.75;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-start:url(#TriangleStart);marker-end:url(#TriangleStart)"
d="m 190.5,74.083333 0,-5.291666"
id="path24899"
sodipodi:nodetypes="cc" />
<path
style="fill:#ffffff;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#marker29218);stroke-dasharray:none"
d="M 31.75,52.916666 H 21.166666"
id="path25030" />
<path
style="fill:#ffffff;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker9466)"
d="M 31.75,54.239583 H 21.166666"
id="path26680" />
<path
style="fill:#ffffff;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker29344)"
d="M 31.750001,55.5625 H 21.166667"
id="path26650" />
<path
style="fill:#ffffff;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker29490)"
d="M 31.75,56.885417 H 21.166666"
id="path26658" />
<path
style="fill:#eabfff;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-dasharray:none"
d="M 13.229167,18.520833 15.875,15.875 h 5.291666 v 5.291666 H 15.875 Z"
id="path27546" />
<path
style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-dasharray:none"
d="M 21.166666,17.197916 H 31.75"
id="path28300" />
<path
style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:0.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-dasharray:none"
d="M 21.166666,19.84375 H 31.75"
id="path28302" />
<text
xml:space="preserve"
transform="matrix(0.26458333,0,0,0.26458333,-0.20448484,-32.592506)"
id="text29670"
style="font-size:14.6667px;line-height:125%;font-family:'DejaVu Sans';-inkscape-font-specification:'DejaVu Sans';letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect29672);display:inline;fill:none;fill-opacity:0.75;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"><tspan
x="50"
y="172.97659"
id="tspan32247"><tspan
style="fill:#000000;fill-opacity:1;stroke:none"
id="tspan32245">ADC</tspan></tspan></text>
<text
xml:space="preserve"
transform="matrix(0.26458333,0,0,0.26458333,-7.9374998,4.5041105)"
id="text29706"
style="font-size:14.6667px;line-height:125%;font-family:'DejaVu Sans';-inkscape-font-specification:'DejaVu Sans';letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect29708);display:inline;fill:none;fill-opacity:0.75;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"><tspan
x="50"
y="172.97659"
id="tspan32251"><tspan
style="fill:#000000;fill-opacity:1;stroke:none"
id="tspan32249">digital I/O</tspan></tspan></text>
<rect
style="fill:none;fill-opacity:1;stroke:none;stroke-width:0.499999;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1"
id="rect32120"
width="216.95833"
height="89.958336"
x="2.6458333"
y="5.2916665" />
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

14
doc/fpga_firmware.md
View File

@ -40,6 +40,7 @@ By manipulating these GPIO signals, the Linux system can reset the FPGA firmware
| 0 | 54 | out (to FPGA) | Global firmware reset |
| 1 | 55 | in (from FPGA) | Reset status report |
| 2 | 56 | out (to FPGA) | ADC clock duty cycle stabilizer |
| 3 | 57 | out (to FPGA) | ADC sample derandomization |
### GPIO 0: Global firmware reset
@ -82,6 +83,19 @@ This GPIO signal is asynchronously routed through the FPGA to the ADC.
Changing the state of this signal may shift the phase of the ADC data clock.
It must therefore only be changed while the FPGA firmware is in reset.
### GPIO 3: ADC sample derandomization
GPIO 3 controls a sample derandomization function in the FPGA.
- GPIO 3 is an output from the PS to the FPGA.
- Driving this signal as `0` disables sample derandomization.
- Driving this signal as `1` enables sample derandomization.
This signal is only supported on Red Pitaya boards with 4 input channels.
On these boards, the ADC can optionally be configured to randomize its output
by XOR-ing the least significant bit into all other bits.
The derandomization function in the FPGA recovers the original sample values.
# SPI signals

502
doc/remote_control.md
View File

@ -1,502 +0,0 @@
# Remote access
Remote access to the acquisition system is supported via TCP connections.
Three TCP server ports are used:
- port 5001 is used to transfer analog sample data;
- port 5002 is used to transfer timetagger data;
- port 5025 is used for commands.
## Analog sample data stream
A client may connect to TCP port 5001 to receive analog sample data.
At most one client can be connected to this port at any time.
If a new client connects while another connection is still active,
the server closes the old connection and uses the new connection instead.
Data flows through the TCP connection in one direction: from the server
to the client.
The client must not send anything back to the server.
Analog sample data are transferred as a sequence of 64-bit binary messages.
Each message is sent as a group of 8 bytes with the least significant byte first.
The message stream corresponds to the output data format of the
analog acquisition chain as described in the FPGA firmware documentation.
## Timetagger event stream
A client may connect to TCP port 5002 to receive timetagger data.
At most one client can be connected to this port at any time.
If a new client connects while another connection is still active,
the server closes the old connection and uses the new connection instead.
Data flows through the TCP connection in one direction: from the server
to the client.
The client must not send anything back to the server.
Timetagger data are transferred as a sequence of 64-bit binary messages.
Each message is sent as a group of 8 bytes with the least significant byte first.
The message stream corresponds to the output data format of the timetagger
as described in the FPGA firmware documentation.
## Command protocol
A client may connect to TCP port 5025 to send commands.
Multiple clients may be simultaneously connected to this port.
In that case, it is the responsibility of the clients to make sure
that they do not interfere with eachother.
The remote control protocol is based on ASCII strings.
The protocol is vaguely similar to SCPI, but it is not compatible with SCPI.
Every interaction is initiated by the client sending a command,
and completed by the server sending a response.
Each command and each response consists of an ASCII string terminated by linefeed (ASCII 10).
Commands are case-insensitive.
The server ignores empty lines and lines that contain only white space characters.
In all other cases, the server sends one response for every command received, even if the command is not recognized or not supported.
The server only sends data in response to a command; it never sends data spontaneously.
A _query_ is a command that ends with a `?` character.
The server responds to a query either by sending the requested data,
or by sending an error message.
An error message starts with the string `ERROR`, followed by
a space character, followed by a short description of the error.
The server responds to a non-query command either by sending the string `OK`
to indicate that the command was completed successfully,
or by sending an error message.
Some commands require one or more _parameters_.
In the command string, the command and parameters are separated from eachother by space characters.
The response to some queries may consist of multiple data elements.
In the response string, such data elements are separated by space characters.
### Example
| Client | Server |
|--------------------------|---------------|
| `AIN:SRATE?` | |
| | `1000000.000` |
| `AIN:SRATE:DIVISOR 1000` | |
| | `OK` |
| `AIN:SRATE?` | |
| | `125000.000` |
| `AIN:NSAMPLES 0` | |
| | `ERROR Invalid argument` |
| `Hello` | |
| | `ERROR Unknown command` |
### List of commands and queries
| Command | Description |
|---------------------------|-------------|
| `*IDN?` | Instrument identification. |
| `RESET` | Restore default settings. |
| `TIMESTAMP?` | Timestamp counter. |
| `AIN:CHANNELS:COUNT?` | Number of input channels. |
| `AIN:CHANNELS:ACTIVE` | Number of active input channels. |
| `AIN:CHn:RANGE` | Analog input range. |
| `AIN:CHn:OFFSET` | 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?` <br>
Response: string with 4 comma-separated fields.
This query returns the instrument identification string.
The response consists of 4 comma-separated fields:
`manufacturer,model,serialnr,version`.
### `RESET`
Command: `RESET`
This command restores most non-persistent settings to power-on defaults.
It resets all settings, except for the following:
- saved calibration;
- active network configuration;
- saved network configuration.
The active calibration is restored to match the saved calibration.
Other settings are restored to fixed power-on defaults.
Any ongoing analog acquisition is stopped.
### `TIMESTAMP?`
Query: `TIMESTAMP?` <br>
Response: decimal integer, representing the current timestamp in units of 8 ns.
### `AIN:CHANNELS:COUNT?`
Query: `AIN:CHANNELS:COUNT?` <br>
Response: number of supported analog input channels.
The response is `2` for a standard Red Pitaya, or `4` for a 4-input Red Pitaya.
### `AIN:CHANNELS:ACTIVE`
Command: `AIN:CHANNELS:ACTIVE n` <br>
Parameter _n_: number of active channels, either `2` or `4`.
This command is only supported on a 4-input Red Pitaya.
When 2 channels are active, only analog input channels 1 and 2 are included in analog acquisition data.
Query: `AIN:CHANNELS:ACTIVE?` <br>
Response: number of active channels, either `2` or `4`.
### `AIN:CHn:RANGE`
Command: `AIN:CHn:RANGE range` <br>
Field _n_: channel number, in range 1 to 4. <br>
Parameter _range_: input range, either `LO` or `HI`.
This command specifies which set of calibration coefficients should be used to interpret ADC samples.
Note that this command does not change the actual input range of the Red Pitaya.
The input range can only be changed by manually placing a jumper on the board.
Query: `AIN:CHn:RANGE?` <br>
Response: currently configured input range, either `LO` or `HI`.
### `AIN:CHn:OFFSET[:LO|HI]`
Command: `AIN:CHn:OFFSET offs` <br>
Field _n_: channel number, in range 1 to 4. <br>
Parameter _offs_: floating point number specifying the offset calibration.
The offset calibration specifies the raw ADC code corresponding to analog input level 0 Volt.
The expected value is in the middle of the ADC code range, i.e. approximately 8192.
The plain variant of the command configures the offset calibration for the active input range of the channel.
Command: `AIN:CHn:OFFSET:LO offs` <br>
Command: `AIN:CHn:OFFSET:HI offs` <br>
These variants of the command configure the offset calibration for a specific input range.
Query: `AIN:CHn:OFFSET?` <br>
Query: `AIN:CHn:OFFSET:LO?` <br>
Query: `AIN:CHn:OFFSET:HI?` <br>
Response: floating point number indicating the offset calibration for the active input range or the specified input range.
### `AIN:CHn:GAIN[:LO|HI]`
Command: `AIN:CHn:GAIN gain` <br>
Field _n_: channel number, in range 1 to 4. <br>
Parameter _gain_: floating point number specifying the gain calibration.
The gain calibration specifies the difference in raw ADC code corresponding to a 1 Volt difference in analog input level.
The expected value is negative, because the Red Pitaya uses an inverting input amplifier.
The plain variant of the command configures the gain calibration for the active input range of the channel.
Command: `AIN:CHn:GAIN:LO offs` <br>
Command: `AIN:CHn:GAIN:HI offs` <br>
These variants of the command configure the gain calibration for a specific input range.
Query: `AIN:CHn:GAIN?` <br>
Query: `AIN:CHn:GAIN:LO?` <br>
Query: `AIN:CHn:GAIN:HI?` <br>
Response: floating point number indicating the gain calibration for the active input range or the specified input range.
### `AIN:CAL:SAVE`
Command: `AIN:CAL:SAVE`
This command saves the active calibration settings to the SD card, to be used as power-on defaults.
The following settings are saved: for each analog input channel, its input range, offset calibration for low and high range, and gain calibration for low and high range.
### `AIN:CHn:SAMPLE[:RAW]?`
Query: `AIN:CHn:SAMPLE?` <br>
Field _n_: channel number, in range 1 to 4. <br>
Response: floating point number representing the most recent ADC sample for the specified input channel in Volt.
Query: `AIN:CHn:SAMPLE:RAW?` <br>
Response: decimal integer representing the raw ADC code of the most recent sample for the specified input channel.
Sample rate settings are not applicable to this command.
The ADC always samples at 125 MSa/s.
This command returns the most recent single sample, without downsampling or averaging.
### `AIN:CHn:MINMAX[:RAW]?`
Query: `AIN:CHn:MINMAX?` <br>
Field _n_: channel number, in range 1 to 4. <br>
Response: two floating point numbers separated by a space character, representing the minimum and maximum input level in Volt.
Query: `AIN:CHn:MINMAX:RAW?` <br>
Response: two decimal integers separated by a space character, representing the minimum and maximum raw ADC code.
The returned values are the minimum and maximum sample values that occurred since the last reset of the range monitor.
### `AIN:MINMAX:CLEAR`
Command: `AIN:MINMAX:CLEAR`
This command resets the input range monitors of all analog input channels.
### `AIN:SRATE`
Command: `AIN:SRATE rate` <br>
Parameter _rate_: floating point number specifying the sample rate in samples per second.
This command configures the effective sample rate of the acquisition chain.
Valid sample rates are in range 500 to 125e6 samples per second.
The specified sample rate will be rounded to the nearest supported rate.
Query: `AIN:SRATE?` <br>
Response: floating point number representing the sample rate in samples per second.
### `AIN:SRATE:DIVISOR`
Command: `AIN:SRATE:DIVISOR divisor` <br>
Parameter _divisor_: decimal integer specifying the downsample factor.
This command configures the downsample factor of the acquisition chain.
Valid downsample factors are in range 1 to 250000.
Query: `AIN:SRATE:DIVISOR?` <br>
Response: decimal integer representing the downsample factor.
**Note:** Commands `AIN:SRATE` and `AIN:SRATE:DIVISOR` are different methods to control the same internal setting.
**Note:** When auto-trigger mode is selected, the downsample factor must be at least 2.
When 4 channels are active, the downsample factor must be at least 2, or 4 if auto-trigger mode is selected.
### `AIN:SRATE:MODE`
Command: `AIN:SRATE:MODE mode` <br>
Parameter _mode_: downsample mode, either `DECIMATE` or `AVERAGE`.
This command selects downsampling by means of decimation or averaging.
Downsampling works by collecting groups of consecutive raw ADC samples and translating each group into a single downsampled value.
The number of raw samples per group is determined by the downsample factor (see `AIN:SRATE:DIVISOR`).
In mode `DECIMATE`, the first sample of a group is used as downsampled value; the other samples in the group are discarded.
In mode `AVERAGE`, the sum of all samples in a group is used as downsampled value.
Query: `AIN:SRATE:MODE?` <br>
Response: either `DECIMATE` or `AVERAGE`.
### `AIN:SRATE:GAIN?`
Query: `AIN:SRATE:GAIN?` <br>
Response: floating point number representing the effective gain factor due to downsampling.
The value returned by this query depends on the downsample factor and the downsample mode.
In downsample mode `DECIMATE`, this query always returns 1.0.
In downsample mode `AVERAGE`, this query returns a number between 1 and 1024.
### `AIN:NSAMPLES`
Command: `AIN:NSAMPLES n` <br>
Parameter _n_: decimal integer specifying the number of samples per channel per trigger.
This command configures the number of (downsampled) samples to collect for each trigger.
Valid values are from 1 to 65536.
Query: `AIN:NSAMPLES?` <br>
Response: decimal integer representing the number of samples per trigger.
### `AIN:TRIGGER`
Command: `AIN:TRIGGER`
This command forces a trigger to occur, regardless of the configured trigger mode.
Note that even a forced trigger may be ignored if the acquisition chain is still processing a previous trigger.
### `AIN:TRIGGER:MODE`
Command: `AIN:TRIGGER:MODE mode` <br>
Parameter _mode_: trigger mode, either `NONE` or `AUTO` or `EXTERNAL` or `EXTERNAL_ONCE`.
**Note:** When trigger mode `EXTERNAL_ONCE` is selected, the trigger mode automatically changes to `NONE` as soon as a trigger occurs.
Query: `AIN:TRIGGER:MODE?` <br>
Response: active trigger mode.
### `AIN:TRIGGER:DELAY`
Command: `AIN:TRIGGER:DELAY n` <br>
Parameter _n_: decimal integer specifying trigger delay as a number of 8 ns cycles.
This configures a delay between trigger detection and the start of sample collection.
Valid values are from 0 to 65535.
Query: `AIN:TRIGGER:DELAY?` <br>
Response: decimal integer representing the trigger delay as a number of 8 ns cycles.
### `AIN:TRIGGER:STATUS?`
Query: `AIN:TRIGGER:STATUS?` <br>
Response: trigger status, either `BUSY` or `WAITING`.
This query returns `BUSY` when the acquisition chain is processing a trigger, or `WAITING` if the acquisition chain is waiting for a trigger.
### `AIN:TRIGGER:EXT:CHANNEL`
Command: `AIN:TRIGGER:EXT:CHANNEL n` <br>
Parameter _n_: decimal integer specifying a digital input channel, in range 0 to 3.
This command selects the digital input channel to use as external trigger.
Query: `AIN:TRIGGER:EXT:CHANNEL?` <br>
Response: decimal integer specifying the selected digital input channel.
### `AIN:TRIGGER:EXT:EDGE`
Command: `AIN:TRIGGER:EXT:EDGE edge` <br>
Parameter _edge_: trigger edge, either `RISING` or `FALLING`.
This command selects rising or falling edges in the external trigger signal.
Query: `AIN:TRIGGER:EXT:EDGE?` <br>
Response: either `RISING` or `FALLING`.
### `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.
### `IPCFG[:SAVED]`
Command: `IPCFG DHCP` <br>
Command: `IPCFG STATIC ipaddr netmask gateway` <br>
Parameter _ipaddr_: IPv4 address in dotted-quad notation. <br>
Parameter _netmask_: netmask in dotted-quad notation. <br>
Parameter _gateway_: optional gateway address in dotted-quad notation.
This command configures the IP address of the system.
It expects between 1 and 4 parameters, depending on the specific address configuration.
If address mode `DHCP` is selected, the command expects no further parameters.
In this mode, the system attempts to get an IPv4 address from a DHCP server on the local network.
If address mode `STATIC` is selected, the command expects 2 or 3 additional parameters to specify the address, netmask and optional gateway.
IP addresses are specified in _dotted-quad_ notation: 4 decimal integers separated by period characters.
The parameter _gateway_ may be omitted or specified as `0.0.0.0` to indicate that no gateway should be used.
The command `IPCFG` takes effect immediately.
This command does not send an `OK` response.
Instead, all TCP connections are closed while the system prepares to change its IP address.
Changing the IP address typically takes a few seconds.
When the new address is active, the client may re-connect to the new IP address.
**Note:** Configuring an invalid IP address may make the system unreachable.
In that case, the saved IP address configuration can be restored by power-cycling the system.
Command: `IPCFG:SAVED DHCP` <br>
Command: `IPCFG:SAVED STATIC ipaddr netmask gateway`
This variant of the command configures the saved IP address configuration.
It uses the same set of parameters as `IPCFG`.
This command has no effect on the active IP address.
When the command completes, it sends an `OK` response and the system continues to function normally.
The saved address configuration takes effect on the next reboot of the system.
Query: `IPCFG?` <br>
Query: `IPCFG:SAVED?` <br>
Response: active or saved IP address configuration.
### `HALT`
Command: `HALT`
This command iniates a shutdown of the system.
It does not send an `OK` response.
Instead, all TCP connections are closed while the system initiates shutdown.
The halt command causes the system to become unresponsive to further commands.
To recover from the halt state, the system must be power-cycled.
### `REBOOT`
Command: `REBOOT`
This command initiates a system reboot.
It does not send an `OK` response.
Instead, all TCP connections are closed while the system initiates shutdown.
A reboot involves a complete reset of the FPGA and the embedded ARM processor.
The system then proceeds as if just powered on.