Usage

The server software has two modes:

  • server mode (default) - the server listens for incoming connections and processes them as they come in.

  • local mode - the software is set up using command line arguments and processes a single request.

There are command line arguments that can be used in general for both modes:

  • --help - display the help message and exit.

  • --version - display the version of the software and exit.

Server mode

The server mode is the default mode. It starts to listen for incoming connections on the specified port and processes them as they come in. Multiple connections can be processed at the same time but only one measurement can be processed at a time.

To start the server in server mode, simply run the server software without any arguments. The server will listen for incoming connections on the default port (33333) and process them as they come in.

./akr2daq3

There is on command line argument to set the port number for the server:

  • p, --port - set the port number for the server to listen on (default 33333).

Message format

All messages have the following format:

  • 1 byte - unsigned byte - the message type.

  • 4 bytes - unsigned integer - the message length.

  • n bytes - the message data.

Image representation of the previously described message format.

With the exception of the DMA messages, all message data is JSON. DMA messages carry binary sample data (for example 16-bit ADC samples in arbitrary units).

Message types

The JSON contract for each message type — including which bodies have no fields, which require version, and which accept optional client-config / measurement-config — is documented on the MessageType enumeration. That is the full API.

See nexmess::components::network::MessageType for the field inventory, send/receive examples, and error strings.

Local mode

The local mode is used to process a single request. The request is specified using command line arguments. The server software will process the request and print the result to the standard output while optionally saving the measurement data to a files.

To start the server in local mode, use the -l or --local command line argument. The request is specified using the following command line arguments. --help lists channel bitmasks, boolean lists, and per-channel examples for the board this binary was built for (ZC706: 2 channels, ZCU102: 4).

Comma-separated numeric lists (--offsets, --trigger-values, --long-gates, --mpk-thresholds, --pre-gates, and the other per-channel numeric flags) take one value per ADC channel, channel 1 first. A single value is copied to every channel. A shorter list repeats the last value for the remaining channels. ZC706 has two channels; ZCU102 has four, so 10,-19,5,8 is valid.

Channel-enable CLI flags (--channels, --invert, --fir, and the other enable flags) accept a bitmask (decimal, 0x, or 0b; bit 0 is channel 1) or a comma-separated true/false or 1/0 list. A shorter boolean list leaves remaining channels off. Too many boolean entries is an error.

The START/SETTINGS JSON protocol does not accept bitmasks. Channel enables are boolean arrays (index 0 is channel 1). Per-channel numeric settings are arrays too. Responses always include every ADC channel, so the array length is the channel count. Local mode writes all GPIO cores directly from the CLI list. coincidence in JSON is a boolean array (all false = none), the same encoding as moving-average.

  • -r, --raw-data - Store raw data

  • -c, --count-data - Store count data

  • --storage-location - The location where the measurement data is stored. The location must be a directory and the file name is generated by the server based on the current time, date and selected channels (default: None).

  • --channels - ADC channels to acquire. Bitmask (1 = ch1, 2 = ch2, …) or boolean list (e.g. true,false). At least one channel must be enabled. Default: 1 (channel 1 only).

  • --invert - Channels to invert, same encoding as --channels (0 / all false = none). Default: 0.

  • --fir - Channels to filter with FIR, same encoding (0 / all false = none). Default: 0.

  • --offsets - Per-channel offsets in ADC units (e.g. 10,-19 or 10,-19,5,8). Default: 0.

  • --measurement-time - The Measurement time in milliseconds (default 10).

  • --trigger-values - Per-channel trigger values in ADC units (e.g. 100,200). Default: 100.

  • --long-gates - Per-channel long gate times in samples. The long gate is the amount of samples which are output for each triggered event (e.g. 100,200). Default: 100.

  • --mpk-thresholds - Threshold for rejecting pulse windows that contain a second pulse within the long gate. If a second pulse above this threshold occurs inside the window, the whole pulse is considered invalid and filtered out in hardware. A value of 0 disables the filter for that channel (e.g. 50,60). Default: 0.

  • --pre-gates - Per-channel pre gate times in samples. The pre gate is the amount of samples which are output before the trigger event (e.g. 10,20). Default: 10.

  • --coincidence - Coincidence filtering as a bitmask or boolean list of channels that participate (0 / all false = none; e.g. 3 or true,true = both on ZC706). A participating channel is delayed by --coincidence-window and kept only when at least two participating pulses overlap; other channels pass through at the same delay. Default: 0.

  • --coincidence-window - Shared coincidence window in samples (default 5000).

  • --version - Shows the version of the software and exit.

ZCU102 (FMC-ADC500-CD)

The following applies only to the ZCU102 with the FMC-ADC500-CD mezzanine. It does not apply to the ZC706.

ADS54J60 interleaving-core offsets

DC coupling at the ADC pins needs a stored interleaving-core offset profile. Capture it at least once with idle, AC-coupled analog inputs (disconnect the source or keep it AC-coupled):

./akr2daq3 --calibrate-offset
./akr2daq3 --calibrate-offset --channels 1
./akr2daq3 --calibrate-offset --channels 2
./akr2daq3 --calibrate-offset --channels false,true

--channels is a bitmask or boolean list (ZCU102 also accepts 4, 8, 15, or 0b1111). If omitted with --calibrate-offset, channels 1 and 2 are captured. Unselected channels keep their previous values in the file.

This writes /var/lib/adc500cd/offset-corr (the same file adc500cd uses). Until that file exists, akr2daq3 uses zeros and prints a warning.

--no-store keeps the captured values in RAM only (this process).

The analog bring-up CLI can capture the same profile:

adc500cd offset-corr generate

In server mode the file is loaded at start. While idle, send nexmess::components::network::MessageType::kOffsetCorr to capture a new profile. JSON field store (default false) writes the file; false keeps the values in RAM until the next capture or restart. JSON field channels is a boolean array that enables at least one ADC channel (omitted default is channels 1 and 2).

AC/DC coupling

Idle hardware is AC. DC is applied only for a measurement and restored to AC afterwards. Each channel has its own ENDCC switch (coupling in the measurement config: 0 = AC, 1 = DC per channel). Analog input DC mode on the ADS54J60 is chip-wide and is enabled when any channel requests DC.

Local-mode argument (ZCU102 only):

  • --coupling - AC/DC per channel (for example ac or ac,dc). Default ac.

Trapezoid pulse-height filter

On ZCU102 and ZC706 the HPD maximum path can run a Jordanov–Knoll trapezoid per channel instead of the original sliding-window peak. trapez-k is the pole-zero coefficient K (0 bypasses PZ). trapez-rise / trapez-flat are N and G in samples. N is sample-accurate (32..1024). G must be a multiple of 4 (32..256, G <= N) because the second boxcar tap is beat-granular. N/4 + G/4 must be less than 256 (s1 delay ring). Height is written to the existing max DMA stream. Defaults: original peak (trapez-mode false), K=47, N=72, G=32. Only enabled channels are validated, so the disabled defaults never block a measurement; software rejects illegal N/G once a channel enables the filter, and a window shorter than 2N+G+8 may drop height events from DMA.

Local-mode arguments:

  • --trapez-mode - true (trapezoid) or false (original peak) per channel. Default false.

  • --trapez-k - PZ coefficient K per channel.

  • --trapez-rise - rise length N in samples per channel.

  • --trapez-flat - flat-top G in samples per channel.