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.
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,-19or10,-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.3ortrue,true= both on ZC706). A participating channel is delayed by--coincidence-windowand 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 exampleacorac,dc). Defaultac.
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) orfalse(original peak) per channel. Defaultfalse.--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.