View source for DCS4

= Hard ware =

This PC is ordered from OriginPC. 

{|class="wikitable"
! Item !! Description
|-
| CPU || AMD Ryzen 9 9950X3D 16-Core Processor (up to 5.7 GHz)
|-
| Motherboard || MSI PRO B850-P WIFI7 (WIFI antanna not installed)
|-
| RAM || 2 x 48 GB DDR5 6000MT/s 
|-
| Cooling || Liquid cool
|-
| GPU || NVIDIA RTX PRO 2000 Blackwell 16 GB
|-
| Disk || 1TB M.2 (OS) + 2x 8TB M.2 (storage)
|- 
| network card || Intel X550-T2 10Gbps (2 ports)
|- 
| Fiber Optics || CAEN A3818 Fiber optics adaptor
|}

= CAEN A3818 PCIe CONET2 Controller — Setup on dcs4 =

Reconstructed from the shell history on <code>dcs4.onenet</code> and verified against the
live system on 2026-09-09. Every command below was actually run on this host.

{| class="wikitable"
! Item !! Value
|-
| Host || <code>dcs4.onenet</code>
|-
| OS || Ubuntu 24.04.4 LTS (noble)
|-
| Running kernel || <code>7.0.0-30-generic</code>
|-
| Card || CAEN A3818 (PCIe, 4× CONET2 optical links)
|-
| PCI address || <code>05:00.0</code>
|-
| PCI ID || <code>10ee:1015</code> (Xilinx vendor, CAEN device); subsystem <code>10ee:0007</code>
|-
| Driver || <code>a3818</code> v1.6.12, installed via DKMS
|-
| DKMS source || <code>/usr/src/a3818-1.6.12</code>
|-
| Driver tarball || <code>~/Desktop/CAEN_Digitizer_Libs/a3818_linux_driver-v1.6.12.tar.gz</code>
|-
| Manuals || <code>~/Desktop/CAEN_Manual/A3818/</code>
|-
| Device nodes || <code>/dev/a3818_<N></code> (see [[#Device node numbering]])
|}

'''Current state:''' the DKMS module is built for kernel <code>7.0.0-31-generic</code>,
but the machine is running <code>7.0.0-30-generic</code>. The module is therefore ''not'' loaded
and <code>/dev/a3818_*</code> does not exist. See [[#Module not loaded after a kernel update]].

== 1. Prerequisites ==

The A3818 driver is an out-of-tree kernel module built by DKMS, so the toolchain and the
headers for the running kernel must be present:

<syntaxhighlight lang="bash">
sudo apt update
sudo apt install dkms build-essential linux-headers-$(uname -r)
</syntaxhighlight>

This was the cause of the first failed install attempt in the history — <code>install.sh</code>
was run before <code>dkms</code> and the kernel headers were present, and the <code>dkms build</code>
step aborted. Install these ''first''.

== 2. Confirm the card is seen by the bus ==

Before touching the driver, check that the PCIe card enumerates. The A3818 presents itself as a
Xilinx memory controller, ''not'' as anything named "CAEN":

<syntaxhighlight lang="bash">
lspci -nn | grep 10ee
</syntaxhighlight>

Expected output on this host:

<pre>
05:00.0 Memory controller [0580]: Xilinx Corporation Device [10ee:1015]
</pre>

If this line is absent, stop — the problem is hardware/seating/BIOS, not software. No amount of
driver work will help.

== 3. Unpack the driver ==

The driver ships inside the CAEN library bundle:

<syntaxhighlight lang="bash">
cd ~/Desktop/CAEN_Digitizer_Libs
tar -xvf a3818_linux_driver-v1.6.12.tar.gz
cd a3818_linux_driver-v1.6.12
</syntaxhighlight>

Contents:

{| class="wikitable"
! File !! Purpose
|-
| <code>src/a3818.c</code>, <code>src/a3818.h</code> || Driver source
|-
| <code>install.sh</code> || DKMS install wrapper (the supported path)
|-
| <code>Makefile</code> || Manual build (<code>make</code> / <code>sudo make install</code>)
|-
| <code>dkms.conf.in</code> || DKMS template; <code>install.sh</code> substitutes the version into <code>dkms.conf</code>
|-
| <code>dkms_post_add.sh</code> || Writes <code>/etc/udev/rules.d/10-CAEN-A3818.rules</code>
|-
| <code>dkms_post_remove.sh</code> || Deletes that udev rule again
|-
| <code>Readme.txt</code>, <code>ReleaseNotes.txt</code> || CAEN docs
|}

If a previously-extracted <code>a3818_linux_driver-v1.6.12/</code> directory is already
present, delete it before extracting (<code>rm -rf a3818_linux_driver-v1.6.12</code>). A stale
tree with a half-written <code>dkms.conf</code> will make <code>install.sh</code> fail in
confusing ways.

== 4. Install the driver ==

<syntaxhighlight lang="bash">
chmod +x install.sh
sudo ./install.sh
</syntaxhighlight>

Must be run as root — the script writes to <code>/usr/src</code> and calls <code>dkms</code>.

What <code>install.sh</code> does, in order:

# Generates <code>dkms.conf</code> from <code>dkms.conf.in</code> with <code>VERSION=1.6.12</code>.
# <code>rmmod a3818</code> (ignored if not loaded).
# <code>dkms uninstall</code> / <code>dkms remove a3818/1.6.12 --all</code> to clear any prior install.
# Copies the tree to <code>/usr/src/a3818-1.6.12</code>.
# <code>dkms add</code> → <code>dkms build</code> → <code>dkms install --force</code>.
# <code>modprobe a3818</code>.

Because <code>dkms.conf.in</code> sets <code>AUTOINSTALL=yes</code>, DKMS will rebuild the module
automatically for each new kernel installed by <code>apt</code> from this point on.

=== Manual (non-DKMS) alternative ===

Only if DKMS is unavailable. Note this build will '''not''' survive a kernel update:

<syntaxhighlight lang="bash">
make
sudo make install
# and to reverse it:
sudo make uninstall
</syntaxhighlight>

== 5. Verify the module loaded ==

<syntaxhighlight lang="bash">
lsmod | grep a3818
dkms status
</syntaxhighlight>

<code>dkms status</code> should report the module as installed for the '''running''' kernel:

<pre>
a3818/1.6.12, 7.0.0-31-generic, x86_64: installed
</pre>

Kernel messages from the probe:

<syntaxhighlight lang="bash">
sudo dmesg | grep -i a3818
# CAEN PCIe: N device(s) found.
</syntaxhighlight>

<code>dkms status</code> prints <code>Deprecated feature: REMAKE_INITRD</code>. This comes
from CAEN's <code>dkms.conf</code> and is harmless — the A3818 module is not needed in the initrd.

The driver also registers a proc entry:

<syntaxhighlight lang="bash">
cat /proc/a3818
</syntaxhighlight>

== 6. udev rule for non-root access ==

By default the character devices are root-owned, so CoMPASS and any user-space program using
CAENComm would need <code>sudo</code>. The driver registers a device '''class''' named
<code>a3818</code> and creates nodes <code>a3818_<N></code> under it, so a udev rule can widen
the permissions.

The rule in use on this host is <code>/etc/udev/rules.d/99-caen-a3818.rules</code>:

<syntaxhighlight lang="bash">
sudo nano /etc/udev/rules.d/99-caen-a3818.rules
</syntaxhighlight>

<pre>
# CAEN A3818 PCIe CONET2 controller - open access to all local users
SUBSYSTEM=="a3818", KERNEL=="a3818_*", MODE="0666"
</pre>

Reload and re-trigger:

<syntaxhighlight lang="bash">
sudo udevadm control --reload-rules
sudo udevadm trigger --subsystem-match=a3818
ls -l /dev/a3818_0
</syntaxhighlight>

=== Relationship to CAEN's own rule ===

<code>dkms_post_add.sh</code> writes its own rule at <code>/etc/udev/rules.d/10-CAEN-A3818.rules</code>:

<pre>
KERNEL=="a3818_[0-9]", MODE="0666"
KERNEL=="a3818_[0-9][0-9]", MODE="0666"
</pre>

and <code>dkms_post_remove.sh</code> deletes it again. Because <code>install.sh</code> runs
<code>dkms remove</code> before <code>dkms add</code>, a re-install cycle can leave this file
missing — and indeed '''it is not present on dcs4 right now'''; only the hand-written
<code>99-</code> rule exists. The <code>99-</code> rule is the more robust of the two (it matches
any index, not just one or two digits), so keeping it is deliberate. If you ever reinstall the
driver and find both files, that is fine — they set the same mode.

<code>MODE="0666"</code> grants read/write on the card to '''every''' local user. That is
acceptable on a dedicated DAQ box like dcs4. On a shared machine, prefer
<code>GROUP="caen", MODE="0660"</code> and add DAQ users to a <code>caen</code> group.

== 7. Device node numbering ==

The driver computes the minor number, and hence the node name, as:

<pre>
index = (CardNumber << 6) + (OpticalLink << 3) + V2718Slave
/dev/a3818_<index>
</pre>

{| class="wikitable"
! Node !! Card !! Link !! Slave
|-
| <code>/dev/a3818_0</code> || 0 || 0 || 0
|-
| <code>/dev/a3818_8</code> || 0 || 1 || 0
|-
| <code>/dev/a3818_16</code> || 0 || 2 || 0
|-
| <code>/dev/a3818_24</code> || 0 || 3 || 0
|-
| <code>/dev/a3818_64</code> || 1 || 0 || 0
|}

So a single A3818 with its four CONET2 links produces nodes at 0, 8, 16 and 24 (plus the daisy-chain
slave offsets in between). When a CAENComm/CAENDigitizer program asks for "link 0", it opens
<code>/dev/a3818_0</code>.

== 8. CAEN user-space libraries ==

The kernel driver alone is not enough — CoMPASS and any DAQ code need the CAEN shared libraries.
These are installed by the bundle's own script:

<syntaxhighlight lang="bash">
cd ~/Desktop/CAEN_Digitizer_Libs
chmod +x Install_libraries.sh
sudo ./Install_libraries.sh
</syntaxhighlight>

It installs build dependencies (<code>build-essential</code>, <code>libusb-1.0-0-dev</code>,
<code>qt6-base-dev</code>, <code>libqt6charts6-dev</code>, <code>libcurl4-openssl-dev</code>,
<code>libboost-all-dev</code>, <code>libgl1-mesa-dev</code>) and then builds, in order:

{| class="wikitable"
! Library !! Version on dcs4 !! Installed to
|-
| CAENVMELib || v4.1.3 || <code>/usr/lib/libCAENVME.so</code>
|-
| CAENComm || v1.8.0 || <code>/usr/lib/libCAENComm.so</code>
|-
| CAENDigitizer || v2.19.0 || <code>/usr/lib/libCAENDigitizer.so</code>
|-
| CAEN FELib || v1.3.2 || <code>/usr/local/lib/libCAEN_FELib.so</code>
|-
| CAEN Dig2 || v1.8.3 || <code>/usr/local/lib/libCAEN_Dig2.so</code>
|-
| CAEN Dig1 (binary) || v1.1.4 || <code>/usr/local/lib/libCAEN_Dig1.so</code>
|}

Verify:

<syntaxhighlight lang="bash">
ldconfig -p | grep -i caen
</syntaxhighlight>

Useful flags at the top of <code>Install_libraries.sh</code>:

* <code>INSTALL_A4818=false</code> — set true only if the USB A4818 bridge is also in use. Not needed for the A3818.
* <code>BOOST_PATH=""</code> — point at a manually-extracted Boost if the system Boost is too new for <code>caen_dig2</code>.
* <code>sudo ./Install_libraries.sh clean</code> — removes the extracted source directories but keeps the tarballs.

The A3818 kernel driver is deliberately '''not''' handled by <code>Install_libraries.sh</code>.
It is installed separately, as in [[#4. Install the driver]].

== 9. Troubleshooting ==

=== Module not loaded after a kernel update ===

'''This is the current state of dcs4.''' Symptoms: <code>lsmod | grep a3818</code> is empty,
<code>modinfo a3818</code> says "Module a3818 not found", <code>/dev/a3818_*</code> does not exist —
yet <code>lspci</code> still shows the card.

Cause: DKMS built the module for the newest ''installed'' kernel, not the ''running'' one:

<syntaxhighlight lang="bash">
dkms status
# a3818/1.6.12, 7.0.0-31-generic, x86_64: installed
uname -r
# 7.0.0-30-generic
</syntaxhighlight>

Two fixes:

<syntaxhighlight lang="bash">
# Preferred: reboot into the kernel the module was built for
sudo reboot

# Or build for the currently running kernel (headers for it are installed)
sudo dkms install a3818/1.6.12 -k $(uname -r) --force
sudo modprobe a3818
</syntaxhighlight>

Confirm afterwards with <code>lsmod | grep a3818</code> and <code>ls -l /dev/a3818_0</code>.

=== "Operation not allowed" when inserting the module ===

Secure Boot is enabled and the kernel is rejecting the unsigned out-of-tree module. Either sign
the module with an enrolled MOK, or disable Secure Boot in the BIOS. See the N.B. in CAEN's
<code>Readme.txt</code>.

=== <code>dkms build</code> fails ===

Almost always missing headers for the running kernel:

<syntaxhighlight lang="bash">
sudo apt install dkms build-essential linux-headers-$(uname -r)
</syntaxhighlight>

Then re-run <code>sudo ./install.sh</code>. The build log is at
<code>/var/lib/dkms/a3818/1.6.12/build/make.log</code>.

=== No <code>/dev/a3818_*</code> even though the module is loaded ===

The driver only registers the char device '''if the PCI hardware is found''' — this is deliberate,
to avoid a kernel crash on <code>cat /proc/devices</code>. Check <code>lspci -nn | grep 10ee</code>
and <code>sudo dmesg | grep -i a3818</code> for the "CAEN PCIe: N device(s) found." line.

=== Permission denied opening the card from a user program ===

The udev rule is missing or was not applied. Re-run:

<syntaxhighlight lang="bash">
sudo udevadm control --reload-rules
sudo udevadm trigger --subsystem-match=a3818
ls -l /dev/a3818_0    # should be crw-rw-rw-
</syntaxhighlight>

== 10. Quick reference ==

<syntaxhighlight lang="bash">
# Is the card on the bus?
lspci -nn | grep 10ee

# Is the driver loaded and built for this kernel?
lsmod | grep a3818
dkms status
uname -r

# Device nodes and permissions
ls -l /dev/a3818_*
cat /proc/a3818

# Reload the module
sudo rmmod a3818 && sudo modprobe a3818

# Reapply udev rules
sudo udevadm control --reload-rules
sudo udevadm trigger --subsystem-match=a3818

# Rebuild for the running kernel
sudo dkms install a3818/1.6.12 -k $(uname -r) --force

# Full reinstall from source
cd ~/Desktop/CAEN_Digitizer_Libs/a3818_linux_driver-v1.6.12 && sudo ./install.sh

# Remove entirely
sudo dkms uninstall a3818/1.6.12
sudo dkms remove a3818/1.6.12 --all

# CAEN user-space libraries
ldconfig -p | grep -i caen
</syntaxhighlight>

== See also ==

* <code>~/Desktop/CAEN_Manual/A3818/</code> — CAEN A3818 hardware manual
* <code>~/Desktop/CAEN_Digitizer_Libs/UM1934_CAENComm_User_Manual_rev.9.pdf</code>
* <code>~/Desktop/CAEN_Digitizer_Libs/UM1935_CAENDigitizer Library_rev.22.pdf</code>
* <code>~/Desktop/CAEN_Digitizer_Libs/UM7715_CAENVMELib_User_Manual_rev.2.pdf</code>

= Software =

Inventory and setup notes for the analysis / DAQ / monitoring software on
<code>dcs4.onenet</code>. Reconstructed from the shell history and verified against the live
system on 2026-09-09.

'''Four of the seven packages below are not yet installed.''' The status column is the
short answer; each section gives the install procedure either way. See
[[#Installation status]].

== Installation status ==

{| class="wikitable"
! Software !! Purpose !! Version
|-
| [[#CERN ROOT|CERN ROOT]] || Analysis framework || 6.36.06
|-
| [[#InfluxDB 3 Core|InfluxDB 3 Core]] || Time-series database || 3.11.2
|-
| [[#Grafana|Grafana]] || Dashboards ||  13.2.1 Enterprise
|-
| [[#CoMPASS|CoMPASS]] || CAEN turnkey DAQ ||  v2.6.4 available
|-
| [[#FSUDAQ|FSUDAQ]] || DAQ for 1st-gen CAEN digitizers || —
|-
| [[#SOLARIS DAQ|SOLARIS DAQ]] || DAQ for 2nd-gen CAEN digitizers ||  —
|-
| [[#ELOG client|ELOG client]] || Electronic logbook || 3.1.5 upstream
|}

The CAEN A3818 driver and user-space libraries that the DAQ programs depend on are documented
separately — see [[CAEN A3818 PCIe CONET2 Controller — Setup on dcs4|the A3818 page]].

== Dependency map ==

<pre>
                      A3818 kernel driver (v1.6.12, DKMS)
                                  |
        +-------------------------+-------------------------+
        |                         |                         |
   CAENVMELib 4.1.3          CAEN FELib 1.3.2          (USB / A4818)
   CAENComm   1.8.0          CAEN Dig2  1.8.3
   CAENDigitizer 2.19.0      CAEN Dig1  1.1.4
        |                         |
     FSUDAQ                  SOLARIS DAQ  ------> ROOT (EventBuilder only)
     CoMPASS  (bundles its own ROOT + Qt + JDK)
        |                         |
        +---------> InfluxDB 3 <--+ ---------> Grafana
        +---------> ELOG <--------+
</pre>

Both FSUDAQ and SOLARIS DAQ can push scaler rates to InfluxDB and post entries to ELOG, which is
why those four pieces belong on one page.

== CERN ROOT ==

{| class="wikitable"
! Item !! Value
|-
| Version || 6.36.06
|-
| Install path || <code>/opt/root_v6.36.06</code>, with <code>/opt/root</code> as a symlink
|-
| Distribution || Official pre-built binary, <code>ubuntu24.04-x86_64-gcc13.3</code>
|-
| Activated by || <code>source /opt/root/bin/thisroot.sh</code> in <code>~/.bashrc</code> (line 159)
|}

=== Build dependencies ===

ROOT is installed from the pre-built binary, so these are not strictly required to ''run'' it —
but they are needed to compile anything against ROOT, and were installed here:

<syntaxhighlight lang="bash">
sudo apt install binutils cmake dpkg-dev g++ gcc libssl-dev git libx11-dev libxext-dev \
  libxft-dev libxpm-dev python3 libtbb-dev libvdt-dev libgif-dev

sudo apt install gfortran libpcre3-dev libglu1-mesa-dev libglew-dev libftgl-dev libfftw3-dev \
  libcfitsio-dev libgraphviz-dev libavahi-compat-libdnssd-dev libldap2-dev python3-dev \
  python3-numpy libxml2-dev libkrb5-dev libgsl-dev qtwebengine5-dev nlohmann-json3-dev \
  libmysqlclient-dev libgl2ps-dev liblzma-dev libxxhash-dev liblz4-dev libzstd-dev \
  libcurl4-openssl-dev
</syntaxhighlight>

=== Install ===

<syntaxhighlight lang="bash">
cd ~/Downloads
tar -xvf root_v6.36.06.Linux-ubuntu24.04-x86_64-gcc13.3.tar.gz
mv root root_v6.36.06
sudo mv root_v6.36.06 /opt/.
cd /opt
sudo ln -s root_v6.36.06 root
</syntaxhighlight>

The versioned directory plus a <code>root</code> symlink is deliberate: upgrading means
unpacking the new version alongside and re-pointing the symlink, with no change to
<code>~/.bashrc</code> and an instant rollback if the new build misbehaves.

=== Environment ===

In <code>~/.bashrc</code>:

<syntaxhighlight lang="bash">
#================================== CERN ROOT
source /opt/root/bin/thisroot.sh
</syntaxhighlight>

This sets <code>ROOTSYS</code>, <code>PATH</code>, <code>LD_LIBRARY_PATH</code> and
<code>PYTHONPATH</code>. Reload with <code>rebash</code> (alias for <code>source ~/.bashrc</code>).

=== Verify ===

<syntaxhighlight lang="bash">
root-config --version      # 6.36.06
root-config --features
root -l -q                 # starts and exits cleanly
</syntaxhighlight>

Features compiled into this build include <code>pyroot</code>, <code>dataframe</code>,
<code>roofit</code>, <code>tmva</code> (with <code>tmva-cpu</code>, <code>tmva-sofie</code>),
<code>fftw3</code>, <code>fitsio</code>, <code>spectrum</code>, <code>unfold</code>,
<code>gdml</code>, <code>opengl</code>, <code>http</code>, <code>sqlite</code>,
<code>fortran</code> and <code>cxx17</code>. Cling and LLVM are the builtin versions.

== ELOG client ==

PSI's Electronic Logbook. Both FSUDAQ and SOLARIS DAQ can post run entries to an ELOG server, using
the <code>elog</code> command-line client. Current upstream version is '''3.1.5'''.

'''Not installed, and not installable via apt on this machine.''' FSUDAQ's README says
<code>sudo apt install elog</code>, which was correct on Ubuntu 22.04. The <code>elog</code>
package '''does not exist in Ubuntu 24.04 (noble)''' — <code>apt-cache policy elog</code> returns
nothing here even though <code>universe</code> is enabled. It must be built from source.

=== Build from source ===

<syntaxhighlight lang="bash">
sudo apt install cmake build-essential git
git clone https://gitea.psi.ch/ELOG/elog --recursive
cd elog
mkdir build && cd build
cmake ..
make
</syntaxhighlight>

This produces two binaries in the build directory:

{| class="wikitable"
! Binary !! Role
|-
| <code>elog</code> || Command-line '''client''' — this is the one FSUDAQ/SOLARIS need
|-
| <code>elogd</code> || The logbook '''server''' daemon
|}

There is no <code>make install</code> target; place the binaries manually:

<syntaxhighlight lang="bash">
sudo cp elog /usr/local/bin/
# only if this host is also to run the logbook server:
sudo cp elogd /usr/local/sbin/
</syntaxhighlight>

Upstream uses no release tags — build from <code>master</code>.

dcs4 only needs the '''client''' if the logbook lives on another machine. Decide that before
setting up <code>elogd</code>, a config file and a systemd unit.

=== Client usage ===

<syntaxhighlight lang="bash">
elog -h <host> -p <port> -l <logbook> -u <user> <password> \
     -a Author="Ryan" -a Type="Run" -a Run=123 \
     "Run 123 started, 4 digitizers armed"
</syntaxhighlight>

The same host/port/logbook/user/password values go into lines 5–8 of FSUDAQ's
<code>programSettings.txt</code>.

Docs: <code>https://elog.psi.ch/elog/</code> · PDF manual:
<code>https://elog.psi.ch/elog/pdf/document.pdf</code>

== InfluxDB 3 Core ==

Time-series database, used as the sink for scaler rates and slow-control data from the DAQ, and as
Grafana's data source.

'''There is already a full operations document for this at <code>~/influx.md</code>''' —
tokens, databases, writing, querying, deletion limitations, troubleshooting. This section is only
the summary. Read that file for anything beyond the basics: <code>mdless ~/influx.md</code>.

{| class="wikitable"
! Item !! Value
|-
| Product || InfluxDB 3 '''Core''' 3.11.2
|-
| Binary || <code>~/.influxdb/influxdb3</code>
|-
| Data dir || <code>~/.influxdb</code> (object store: local file)
|-
| Node ID || <code>dcs4.onenet-node</code>
|-
| HTTP API || <code>http://0.0.0.0:8181</code>
|-
| Service || <code>influxdb.service</code> — enabled, active
|-
| Runs as || <code>adminrt</code>
|-
| Admin token || <code>~/influx.token</code> (mode 600)
|-
| Databases || <code>MUSIC</code>, <code>_internal</code>
|}

=== Install ===

<syntaxhighlight lang="bash">
curl -O https://www.influxdata.com/d/install_influxdb3.sh && sh install_influxdb3.sh
source ~/.bashrc
rm install_influxdb3.sh
influxdb3 create token --admin        # save the output to ~/influx.token
</syntaxhighlight>

=== Environment ===

In <code>~/.bashrc</code>:

<syntaxhighlight lang="bash">
#================================== influxDB 3
export PATH="$PATH:/home/phy/adminrt/.influxdb/"
export INFLUXDB3_AUTH_TOKEN=$(sed -n 's/^Token: //p' ~/influx.token)
</syntaxhighlight>

With <code>INFLUXDB3_AUTH_TOKEN</code> exported, the CLI needs no <code>--token</code> flag.

=== Service ===

<code>/etc/systemd/system/influxdb.service</code>:

<syntaxhighlight lang="ini">
[Unit]
Description=InfluxDB 3 Core Database Server
Documentation=https://docs.influxdata.com/influxdb3/core/
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=adminrt
Group=adminrt
LimitNOFILE=65536
EnvironmentFile=-/etc/default/influxdb3
ExecStart=/home/phy/adminrt/.influxdb/influxdb3 serve \
      --node-id dcs4.onenet-node \
      --object-store file \
      --data-dir /home/phy/adminrt/.influxdb \
      --http-bind 0.0.0.0:8181
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

=== Quick commands ===

<syntaxhighlight lang="bash">
sudo systemctl status influxdb.service
curl -i http://localhost:8181/health          # 401 without a token — that means it IS running
influxdb3 show databases
influxdb3 create database MUSIC
influxdb3 write -d MUSIC "testing value=1"
</syntaxhighlight>

An unauthenticated <code>GET /health</code> returns '''401 Unauthorized''', not 200. That is
the expected healthy response — it proves the server is up and enforcing auth. Pass
<code>-H "Authorization: Bearer $INFLUXDB3_AUTH_TOKEN"</code> for a 200.

This is InfluxDB '''3''', not 1.x or 2.x. The daemon is <code>influxdb3 serve</code>, not
<code>influxd</code>, and 1.x/2.x guides do not apply. This matters for FSUDAQ, which was written
against 1.8 — see the warning in [[#FSUDAQ]].

== Grafana ==

Dashboards over the InfluxDB data.

{| class="wikitable"
! Item !! Value
|-
| Package || <code>grafana-enterprise</code> 13.2.1 (<code>.deb</code>)
|-
| Binary || <code>/usr/sbin/grafana-server</code>
|-
| Config || <code>/etc/grafana/grafana.ini</code>
|-
| Data || <code>/var/lib/grafana</code>
|-
| Share || <code>/usr/share/grafana</code>
|-
| Service || <code>grafana-server.service</code> — enabled, active
|-
| Web UI || <code>http://dcs4.onenet:3000</code>
|}

=== Install ===

<syntaxhighlight lang="bash">
sudo apt-get install -y adduser libfontconfig1 musl
cd ~/Downloads
wget https://dl.grafana.com/grafana-enterprise/release/13.2.1/grafana-enterprise_13.2.1_33191028959_linux_amd64.deb
sudo dpkg -i grafana-enterprise_13.2.1_33191028959_linux_amd64.deb
sudo systemctl daemon-reload
sudo systemctl enable --now grafana-server.service
sudo systemctl status grafana-server.service
</syntaxhighlight>

The <code>grafana-enterprise</code> package is the same binary as OSS Grafana; the
enterprise features simply stay locked without a licence. No licence is installed here, so this is
functionally the free build.

=== Configuration ===

<code>/etc/grafana/grafana.ini</code> is '''entirely at defaults''' — every line is commented out.
That means port 3000, no TLS, and the stock <code>admin</code>/<code>admin</code> credentials with
a change prompt at first login.

Change the admin password at first login. With the config untouched, Grafana is listening
on <code>0.0.0.0:3000</code> with default credentials.

=== Verify ===

<syntaxhighlight lang="bash">
sudo systemctl status grafana-server.service
curl -s http://localhost:3000/api/health
# {"database":"ok","version":"13.2.1", ...}
</syntaxhighlight>

=== Connecting to InfluxDB 3 ===

Not yet provisioned — <code>/etc/grafana/provisioning/datasources/</code> contains only the
stock <code>sample.yaml</code>. To add the data source through the UI:

* '''Type:''' InfluxDB
* '''Query language:''' SQL (InfluxDB 3 native; not InfluxQL or Flux)
* '''URL:''' <code>http://localhost:8181</code>
* '''Database:''' <code>MUSIC</code>
* '''Token:''' Ask Ryan.

No need to use HTTP headers

= CoMPASS =

Source: CAEN SpA. Installed at <code>~/CoMPASS-v2.6.4</code>, extracted from the tarball kept in <code>~/Desktop/CAEN_Digitizer_Libs/</code>.

CAEN's multiparametric acquisition program. It is a sealed appliance: unpack, run, and take data — at the cost of being unable to change anything about how the data is processed.

{| class="wikitable"
! Version !! Bundled JDK !! Plotter !! Install
|-
| v2.6.4, January 2026 || jdk-21.0.2 || Qt 5.15.2 + ROOT 6.28.06 || Extract in place, no compile
|}

== How CoMPASS was installed here ==

Extract and move. Nothing else.

<pre>
cd ~/Desktop/CAEN_Digitizer_Libs
tar -xvf CoMPASS-v2.6.4.tar.gz
mv CoMPASS-v2.6.4 ~/
cd ~/CoMPASS-v2.6.4
./CoMPASS
</pre>

'''<code>install.sh</code> was deliberately not run on this machine.''' It only does two things, both optional:

* symlinks the launcher to <code>/usr/local/bin/CoMPASS</code> so it is on <code>$PATH</code> — we run <code>./CoMPASS</code> from the folder instead;
* copies <code>a4818.rules</code> to <code>/etc/udev/rules.d</code> and reloads udev, so an A4818 optical-USB adaptor is reachable without root — irrelevant while the digitizers are on Ethernet.

Run <code>sudo ./install.sh</code> only if you want one of those. Uninstalling is deleting the folder either way; there is no package manager state to unwind.

The older tarballs (<code>CoMPASS-v2.1.1</code>, <code>v2.2.1</code>) are still in <code>CAEN_Digitizer_Libs/</code>. Versions are fully parallel — extract one elsewhere and run it directly if you need to compare behaviour.

== The g++-11 problem ==

This is the one thing that will stop a fresh CoMPASS on Ubuntu 24.04, and the launcher's own version check does '''not''' catch it.

'''Symptom.''' CoMPASS starts, the main window appears, but the plot window never does. <code>~/Compass/logs/log.0.txt</code> reports <code>Process CoMPASSPlot has been terminated with exit value 139</code> (SIGSEGV) followed by a Java <code>IllegalStateException</code>. The DPP server is fine — <code>CAENDPPServerLog.txt</code> shows it binding its ports and accepting the client, then logging a clean <code>Client disconnection</code> when the plotter takes the app down. <code>CoMPASSPlotLog.txt</code> contains only its logger-init line; the plotter dies before writing anything else.

'''Root cause.''' The ROOT/cling build bundled in <code>plot/linux/</code> was compiled on Ubuntu 22.04 against GCC 11, and it hardcodes the compiler name <code>x86_64-linux-gnu-g++-11</code> to discover the C++ standard-library include paths at runtime:

<pre>
LC_ALL=C x86_64-linux-gnu-g++-11 -xc++ -E -v /dev/null 2>&1 | sed -n ...
</pre>

On Ubuntu 24.04 that binary does not exist — only <code>g++</code> 13.3.0 and <code>/usr/include/c++/13</code>. The pipeline still exits 0, because <code>sed</code> succeeds even though the compiler was not found, so cling never bails out cleanly. It proceeds with an empty include list, builds a VFS overlay entry with <code>'name': ''</code>, and segfaults in <code>llvm::vfs::OverlayFileSystem::pushOverlay()</code>, inside <code>plot/linux/lib/libCling.so</code>.

The stack trace in <code>log.0.txt</code> shows the whole chain:

<pre>
main
 -> RootApplication::RootApplication()
 -> TApplication::TApplication()
 -> TROOT::InitInterpreter()
 -> CreateInterpreter()                              [libCling.so]
 -> cling::Interpreter::Interpreter()
 -> cling::IncrementalParser::IncrementalParser()
 -> cling::CIFactory::createCI()
 -> setupCxxModules(clang::CompilerInstance&)
 -> collectModuleMaps(...)
 -> llvm::vfs::OverlayFileSystem::pushOverlay(...)    <-- SEGFAULT
</pre>

'''Fix.'''

<pre>
sudo apt install g++-11
</pre>

This provides <code>/usr/bin/x86_64-linux-gnu-g++-11</code> and <code>/usr/include/c++/11</code>, exactly what cling probes for. It installs alongside GCC 13 and does '''not''' change the system default compiler.

<div style="border-left:4px solid #b8860b; background:#fdf6e3; padding:0.6em 1em; margin:0.8em 0;">
'''Why the launcher does not catch this.''' The <code>CoMPASS</code> script checks <code>g++ -dumpfullversion</code> against a minimum of 11.4.0. GCC 13.3.0 passes that check comfortably, so the launcher proceeds — while the thing cling actually needs, a binary literally named <code>g++-11</code>, is missing. The version check and the runtime dependency are testing different things.
</div>

=== If g++-11 alone does not fix it ===

<code>ROOTSYS=/opt/root</code> is set in the environment here, and <code>/opt/root/lib</code> gets appended to the <code>LD_LIBRARY_PATH</code> CoMPASS builds for itself. CoMPASS's own <code>plot/linux/lib</code> comes first so it should win, but a separate ROOT install can still feed the wrong <code>etc/</code> modulemaps into <code>collectModuleMaps</code>. Next test:

<pre>
env -u ROOTSYS ./CoMPASS
</pre>

== Launcher preflight checks ==

The <code>CoMPASS</code> script refuses to start rather than failing halfway, and each check prints its own reason. All of these currently pass on this machine.

{| class="wikitable"
! Requirement !! Minimum !! How it is checked
|-
| Architecture || x86-64 || <code>uname -m</code> must contain <code>64</code>
|-
| Java || 21 || Bundled JDK, version parsed from <code>-version</code>
|-
| g++ || 11.4.0 || <code>g++ -dumpfullversion</code>, compared field by field
|-
| glibc || 2.34 || <code>strings</code> on the libc that <code>CAENDPPServer</code> links
|-
| glibcxx || 3.4.30 || <code>strings</code> on the libstdc++ that <code>CoMPASSPlot</code> links
|}

== CoMPASS is three processes, not one ==

What looks like a single application is a Java front end talking over local TCP to a native back end, plus a separate plotting binary. Knowing this is what makes the logs readable — and it is why a plotter crash leaves a perfectly healthy digitizer log.

{| class="wikitable"
! Process !! Role !! Endpoint
|-
| <code>compass-v2.6.4.jar</code> || Java 21 GUI, run configuration, orchestration || —
|-
| <code>CAENDPPServer</code> || Native digitizer control and readout || <code>127.0.0.1:56342</code> control<br><code>127.0.0.1:56343</code> data
|-
| <code>CoMPASSPlot</code> || Qt5 + ROOT histogram and waveform display || —
|}

Those ports are set by the launcher via <code>-Ddpp.server.*</code> flags, and the server is spawned by the JVM (<code>dpp.server.launch=true</code>). If a stale <code>CAENDPPServer</code> is holding 56342, a new CoMPASS will not come up — check <code>~/Compass/logs/CAENDPPServerPID</code> and kill it.

<div style="border-left:4px solid #a3372b; background:#faf0ef; padding:0.6em 1em; margin:0.8em 0;">
'''Library collision.''' <code>server/linux/</code> ships CAEN's whole stack — <code>libCAENDigitizer</code>, <code>libCAEN_Dig2</code>, <code>libCAEN_FELib</code>, <code>libCAENComm</code>, <code>libCAENVME</code> — and prepends that directory to <code>LD_LIBRARY_PATH</code>. It is deliberately insulated from the system CAEN libraries that FSUDAQ and SOLARIS_DAQ link against, so the two can disagree on version without either breaking. It also means a system library upgrade does nothing for CoMPASS.
</div>

== CoMPASS files and logs ==

The working directory is <code>~/Compass/</code>, created on first run, and separate from the install directory.

{| class="wikitable"
! Path !! Contents
|-
| <code>~/Compass/config/</code> || Saved project and board configurations
|-
| <code>~/Compass/data/</code> || Acquired runs
|-
| <code>~/Compass/logs/log.''N''.txt</code> || Java front-end log, rotated; <code>log.0.txt</code> is current — '''start here'''
|-
| <code>~/Compass/logs/CAENDPPServerLog.txt</code> || Native server — board and link errors
|-
| <code>~/Compass/logs/CAENDPPServerPID</code> || PID of the running native server
|-
| <code>~/Compass/logs/CoMPASSPlotLog.txt</code> || Plotter, including ROOT complaints
|}

Documentation ships in the install folder rather than online: <code>UM5960_Compass_UserManual_rev27.pdf</code> is the reference manual and <code>GD6300_Compass_QuickStart_rev27.pdf</code> the getting-started guide. Older revisions (rev19–rev23) sit in <code>~/Desktop/CAEN_Manual/</code>, filed per board. <code>releasenotes.txt</code> carries the full changelog.


= FSUDAQ =

Source: [https://github.com/goluckyryan/FSUDAQ github.com/goluckyryan/FSUDAQ]. Cloned to <code>~/FSUDAQ</code>.

A Qt6 acquisition system for first-generation CAEN digitizers, with a half-second scope, full register control, and an online analysis layer you are expected to write against.

{| class="wikitable"
! Boards !! Firmware !! Binary !! Data format
|-
| x725, x725S, x730, V1740 || PHA, PSD, QDC || <code>FSUDAQ_Qt6</code> || <code>.fsu</code>
|}

Everything on the digitizer is reachable from the settings panel ''except LVDS''. The scope redraws every 500 ms, waveforms can be saved, and each channel carries its own 1D histogram — off by default, switched on in the '''Online Histograms''' panel, with the binning persisted to <code>singleSpectaSetting.txt</code> under the raw data path.

== FSUDAQ dependencies ==

The CAEN libraries must be downloaded and installed by hand; the rest come from apt.

{| class="wikitable"
! Component !! Minimum !! Needed for
|-
| CAENVMELib || 3.3 (4.0+ for A5818) || VME access layer
|-
| CAENComm || 1.5.3 || Link abstraction
|-
| CAENDigitizer || 2.17.1 || Board control
|-
| CAEN A3818 driver || 1.6.8 || PCIe optical card
|-
| CAENUSBdrv || 1.5.5 || V57xx over USB
|-
| Qt6 + Charts || — || GUI and plots
|-
| libcurl || — || InfluxDB writes
|-
| elog || 3.1.3+ || Logbook entries
|}

<pre>
sudo apt install qt6-base-dev libqt6charts6-dev libcurl4-openssl-dev elog
</pre>

QCustomPlot is vendored in the repository, so it is not an external dependency.

=== Building FSUDAQ ===

<pre>
cd ~/FSUDAQ
qmake6 FSUDAQ_Qt6.pro     # regenerates the Makefile
make -j$(nproc)
./FSUDAQ
</pre>

Re-run <code>qmake6</code> whenever the <code>.pro</code> changes — notably after adding an analyzer. For a debug build, uncomment <code>QMAKE_CXXFLAGS += -g</code> and the two <code>-O0</code> lines in the <code>.pro</code>; the program installs an abort handler that writes a core dump, which needs <code>ulimit -c unlimited</code> and a writable <code>core_pattern</code> to land anywhere useful.

=== Optical link handling ===

<div style="border-left:4px solid #7a2e40; background:#faf0f2; padding:0.6em 1em; margin:0.8em 0;">
'''A4818 cabling order.''' Connect the optical fibre ''before'' powering the digitizers on. If a fibre is unplugged and reconnected during a session, the digitizers must be power-cycled — reconnecting alone will not restore the link.
</div>

A Raspberry Pi 5 with 8 GB and an A4818 is a tested configuration; all the CAEN libraries build for ARM. On Pi, substitute <code>qt6-chart-dev</code> for <code>libqt6charts6-dev</code>, and install elog by hand or skip it.

== FSUDAQ settings and data ==

<code>programSettings.txt</code> sits beside the binary and is read line by line — position is the only key, so blank lines are meaningful placeholders and must be kept. The copy in <code>~/FSUDAQ</code> is currently blank throughout, so no data path, InfluxDB or elog is configured.

{| class="wikitable"
! # !! Field !! Effect if empty
|-
| 1 || raw data path || Can still run ACQ, but cannot save a run
|-
| 2 || InfluxDB IP || rowspan="3" | InfluxDB logging disabled
|-
| 3 || database name
|-
| 4 || InfluxDB token (v2.0+)
|-
| 5 || elog IP || rowspan="4" | elog disabled
|-
| 6 || elog logbook
|-
| 7 || elog user
|-
| 8 || elog password
|}

With no settings file at all, FSUDAQ still starts and still discovers every digitizer on the optical link. Degradation is graceful and per-feature.

=== What lands in the data path ===

{| class="wikitable"
! File !! Purpose
|-
| <code>*.fsu</code> || Raw acquired data
|-
| <code>*.bin</code> || Digitizer settings snapshot for the run
|-
| <code>RunTimestamp.dat</code> || Start/stop times and comments for every run
|-
| <code>RunTimestamp.csv</code> || The same, for a spreadsheet
|-
| <code>lastRun.sh</code> || Last-run values exported for shell scripts
|-
| <code>singleSpectaSetting.txt</code> || Per-channel histogram binning
|}

=== Compiled-in limits ===

{| class="wikitable"
! Limit !! Value
|-
| Digitizers || 16 (4 ports × 4 boards)
|-
| Channels || 64
|-
| Record length || 0x3FFF × 8
|-
| Max file size || 2 GB
|-
| Buffer per channel || 10,000 events
|-
| Traces per event || 5
|-
| Scope refresh || 200 ms
|-
| Scaler refresh || 1,000 ms
|}

=== Keyboard control ===

The panels are fully keyboard-drivable, which matters when the DAQ box is on a KVM at the far end of a hall.

{| class="wikitable"
! Key !! Action
|-
| <code>F4</code> || Open the focused drop-down
|-
| <code>Tab</code> / <code>Ctrl+Tab</code> || Next / previous element
|-
| <code>Space</code> || Press the focused button
|-
| <code>&uarr;</code> / <code>&darr;</code> || Increment / decrement a number
|-
| <code>Alt+Tab</code> || Switch between DAQ windows
|}

Field colour is state, not decoration: <span style="color:#2c5f8a;">'''blue'''</span> means the value has been typed but not yet pushed to the board; <span style="color:#a3372b;">'''red'''</span> means the board rejected it.

== FSUDAQ online analyzers ==

<div style="border-left:4px solid #b8860b; background:#fdf6e3; padding:0.6em 1em; margin:0.8em 0;">
'''Read this before debugging empty spectra.''' No events are built when FSUDAQ starts. The <code>MultiBuilder</code> only begins once an online analyzer has been created and opened — and once it has, event building continues even if you close the analyzer window. An empty coincidence spectrum usually means nobody opened an analyzer, not that the physics is wrong.
</div>

<code>MultiBuilder</code> correlates hits across several digitizers. It builds forward in the usual way, and also backward — from the most recent data back through a fixed number of events — which is what lets the online plots stay responsive at high rate instead of lagging behind the front of the buffer.

Above that sit 1D and 2D histograms with graphical cuts that can be drawn, named, and renamed, and whose rates can be pushed to InfluxDB.

=== Analyzers in the repository ===

{| class="wikitable"
! Header !! Purpose
|-
| <code>Analyser.h</code> || Base class — subclass this
|-
| <code>SplitPoleAnalyzer.h</code> || Reference example: a 2D and a 1D histogram, plus cut rates to InfluxDB
|-
| <code>CoincidentAnalyzer.h</code> || Coincidence conditions
|-
| <code>MUSICAnalyzer.h</code> || MUSIC detector
|-
| <code>NeutronGamma.h</code> || n/γ pulse-shape discrimination
|-
| <code>EncoreAnalyzer.h</code> || Encore array
|-
| <code>RAISOR.h</code> || RAISOR separator
|-
| <code>Isotope.h</code>, <code>Cross.h</code> || Mass table (<code>mass20.txt</code>) and kinematics helpers
|}

=== Adding your own analyzer ===

Derive from <code>Analyser.h</code>, then wire it into four places — the analyzer will not appear in the menu until all four are done:

# Add the source file to <code>FSUDAQ_Qt6.pro</code>.
# Include the header at the top of <code>FSUDAQ.cpp</code>.
# Add an entry to the <code>onlineAnalyzerList</code> vector, also at the top of <code>FSUDAQ.cpp</code>.
# Handle it in <code>FSUDAQ::OpenAnalyzer()</code>.

<pre>
qmake6 FSUDAQ_Qt6.pro
make
</pre>

== FSUDAQ known issues ==

These are documented upstream and are worth reading as operating procedure rather than as a bug list.

=== Aggregation settings will hang the board ===

<div style="border-left:4px solid #7a2e40; background:#faf0f2; padding:0.6em 1em; margin:0.8em 0;">
'''Correlated registers.''' '''Aggregate Organization''', '''Events per Aggregate''' and '''Record Length''' constrain one another. Invalid combinations are accepted by the panel and then send the digitizer into an unrecoverable state. When using the scope, '''Agg/Read must stay below 512'''.
</div>

For PHA firmware, Events-per-Aggregate is recomputed through the CAEN API before ACQ starts, but that calculation assumes the current rate — if the trigger rate changes substantially mid-experiment, it needs setting again by hand. Trapezoid scaling and the fine-gain register are likewise computed at ACQ start.

=== Everything else ===

{| class="wikitable"
! Symptom !! Cause / action
|-
| Negative trigger or accept rate || Buffer arriving out of time order. A digitizer settings problem, not a program bug — reprogram the board.
|-
| Pile-up rate looks wrong || Inaccurate above roughly 60 kHz input.
|-
| GUI stalls || Database access is slow. Disable InfluxDB.
|-
| Loaded settings look incomplete || Expected. Loading restores channel settings and some board settings only.
|-
| V1740D QDC: ReadData error, ACQ stops || When the first channel group is enabled, channel 0 must also be enabled.
|-
| V1740 QDC record length behaves oddly || Record length is a board-level setting, but readout is per group.
|-
| <code>EventBuilder</code> crashes offline || Known: very high trigger rates in the data.
|}

= SOLARIS_DAQ =

Source: [https://github.com/goluckyryan/SOLARIS_DAQ github.com/goluckyryan/SOLARIS_DAQ]. Cloned to <code>~/SOLARIS_DAQ</code>.

Built for the SOLARIS solenoidal spectrometer at FRIB and the x2730-series digitizers. Second-generation boards speak Ethernet and a REST-like endpoint model rather than VME registers, and the program is structured around that difference.

{| class="wikitable"
! Boards !! Firmware !! Max digitizers !! Data format
|-
| VX2730, VX2740, VX2745 || DPP-PHA, DPP-PSD || 20 || <code>.sol</code>
|}

The digitizer control classes are deliberately independent of the Qt layer, so the same core can be driven from the auxiliary command-line tools without dragging in a GUI.

=== Core, independent of Qt ===

{| class="wikitable"
! File !! Role
|-
| <code>ClassDigitizer2Gen.h/cpp</code> || Connection, configuration, readout, file I/O
|-
| <code>Hit.h</code> || Decoded event structure
|-
| <code>RawDecoder.h</code> || Unpacks the raw endpoint blob into hits
|-
| <code>DigiParameters.h</code> || Register definitions for both firmwares
|-
| <code>RingBuffer.h</code> || Lock-free circular buffer for per-channel spectra
|}

=== Qt layer ===

{| class="wikitable"
! File !! Role
|-
| <code>mainwindow.h/cpp</code> || Digitizer management, run control, scalers
|-
| <code>digiSettingsPanel.h/cpp</code> || Board and channel register editor
|-
| <code>scope.h/cpp</code> || Waveform display
|-
| <code>SingleSpectra.h/cpp</code> || Per-channel energy spectra
|-
| <code>SOLARISpanel.h/cpp</code> || SOLARIS detector mapping and configuration
|-
| <code>CustomThreads.h</code> || <code>ReadDataThread</code> and <code>TimingThread</code>
|-
| <code>ClassElog.cpp</code>, <code>ClassInfluxDB.cpp</code> || Logbook entries and scaler-rate logging
|}

=== Building SOLARIS_DAQ ===

<pre>
cd ~/SOLARIS_DAQ
qmake6 SOLARIS_DAQ.pro
make -j$(nproc)
./SOLARIS_DAQ
</pre>

<div style="border-left:4px solid #1b5e4a; background:#eff5f3; padding:0.6em 1em; margin:0.8em 0;">
'''Missing header.''' <code>CAENDig2.h</code> is not installed to the system include path by the CAEN Dig2 package. Copy it out of the source tree before the first build:
<pre>
sudo cp caen_dig2-vXXXX/include/CAENDig2.h /usr/local/include/
</pre>
</div>

Tested against V2740 and V2745 DPP-PHA-1G and DPP-PSD-1G, and VX2730 DPP-PSD from firmware 2025052203.

== SOLARIS readout formats ==

Chosen through <code>SetDataFormat()</code>. Each step down the table drops metadata in exchange for bandwidth, and the choice is the single biggest lever on sustainable rate.

{| class="wikitable"
! Format !! ID !! Carries
|-
| <code>ALL</code> || <code>0x00</code> || All metadata, 2 analog probes, 4 digital probes
|-
| <code>OneTrace</code> || <code>0x01</code> || 1 analog probe + energy, timestamp, flags
|-
| <code>NoTrace</code> || <code>0x02</code> || Energy, timestamp, flags — no waveform
|-
| <code>Minimum</code> || <code>0x03</code> || Channel, energy, timestamp
|-
| <code>MiniWithFineTime</code> || <code>0x04</code> || As above plus fine timestamp
|-
| <code>Raw</code> || <code>0x0A</code> || Undecoded blob, unpacked in software
|}

=== What a decoded hit holds ===

{| class="wikitable"
! Field !! Width !! Units
|-
| channel || 6 bit || —
|-
| energy || 16 bit || ADC
|-
| energy_short || 16 bit || ADC — PSD only
|-
| timestamp || 48 bit || ns
|-
| fine_timestamp || 10 bit || ps
|-
| flags, high / low priority || 8 / 12 bit || —
|-
| analog probes ×2 || 18 bit/sample || —
|-
| digital probes ×4 || 1 bit/sample || —
|}

== What SOLARIS_DAQ pushes to InfluxDB ==

Six measurements, in two groups. Points accumulate in one buffer and are flushed as a '''single HTTP POST per tick''', so a 64-channel board sends 128 points every 2 s in one request. No timestamps are sent on any point — the server stamps them at write time.

=== Continuous, one batch every 2 s ===

{| class="wikitable"
! Measurement !! Tags !! Field !! Source
|-
| <code>Rate</code> || <code>Bd=&lt;serial&gt;</code>, <code>Ch=&lt;NN&gt;</code> || <code>value</code> || <code>PHA::CH::SelfTrgRate</code>, read straight off the board
|-
| <code>AccpRate</code> || <code>Bd=&lt;serial&gt;</code>, <code>Ch=&lt;NN&gt;</code> || <code>value</code> || Computed in software — see below
|-
| <code>FileSize</code> || — || <code>value</code> || Sum of <code>GetTotalFilesSize()</code> across all digitizers, in bytes
|}

<code>Ch</code> is zero-padded to two digits (<code>mainwindow.cpp:1372</code>). The 2 s cadence is <code>TimingThread</code>'s default of <code>20 × 100 ms</code> — the <code>SetWaitTimeSec</code> call at <code>mainwindow.cpp:78</code> is commented out, so it is never overridden. <code>FileSize</code> is additionally gated on the '''Save Run''' checkbox (<code>mainwindow.cpp:1380</code>).

=== Event-driven ===

{| class="wikitable"
! Measurement !! Tags !! Fields !! Fires on
|-
| <code>ProgramStart</code> || — || <code>value=1</code> || InfluxDB setup succeeding — doubles as the write test
|-
| <code>ProgramStart</code> || — || <code>value=0</code> || Program exit
|-
| <code>StartStop</code> || — || <code>value=1</code> or <code>0</code> || Run start / stop; also scope open, and the scope's ACQ toggle
|-
| <code>RunID</code> || <code>start=1</code> || <code>value=&lt;runID&gt;</code>, <code>expName</code>, <code>comment</code> || Run start
|-
| <code>RunID</code> || <code>start=0</code> || <code>value=&lt;runID&gt;</code>, <code>expName</code>, <code>comment</code> || Run stop, new experiment, experiment switch
|}

Spaces in comments are replaced with underscores before writing.

=== Two gates that silently stop the rate data ===

<div style="border-left:4px solid #b8860b; background:#fdf6e3; padding:0.6em 1em; margin:0.8em 0;">
'''The Scaler window must be open.''' <code>UpdateScalar()</code> begins with <code>if( scalar->isVisible() == false ) return;</code> (<code>mainwindow.cpp:1318</code>), before any InfluxDB work happens. Close that window and <code>Rate</code>, <code>AccpRate</code> and <code>FileSize</code> stop dead — with no warning, and with <code>RunID</code> and <code>StartStop</code> still flowing normally because they sit on separate code paths. A Grafana panel can therefore go flat while the run looks perfectly healthy.
</div>

The second gate is <code>scalarOutputInflux</code>, set true at run start and false at run stop (<code>mainwindow.cpp:525</code>, <code>589</code>), so the continuous group only flows during a run.

=== How AccpRate differs from Rate ===

<code>Rate</code> is the firmware's self-trigger rate register, and does '''not''' apply the coincidence condition.

<code>AccpRate</code> is derived (<code>mainwindow.cpp:1346-1350</code>):

<pre>
(ChannelSavedCount delta) * 1e9 / (ChannelRealtime delta)
</pre>

but only when the realtime delta exceeds 1e9 ns '''and''' the saved count actually increased. Otherwise it is forced to '''0''' — so expect genuine zeros on the first tick or two after starting, and on any quiet channel, rather than a gap in the series.

A VX2730 quirk sits immediately above it: <code>ChannelRealtime</code> is divided by 4 because the register is not in ns on that model.

=== Setup preconditions ===

<code>SetupInflux()</code> (<code>mainwindow.cpp:2460</code>) refuses to connect unless all of the following hold. If any fails, the <code>influx</code> object is deleted and '''nothing''' is ever pushed:

* Both <code>DatabaseIP</code> and <code>DatabaseName</code> are non-empty.
* <code>TestingConnection()</code> succeeds.
* If the server reports version > 1, a token is set. The configuration here is <code>apiv3_…</code> against <code>localhost:8181</code>, so this branch is live and the token is mandatory.
* '''The database already exists.''' It is matched against the list returned by <code>CheckDatabases()</code>. Despite <code>CreateDatabase()</code> existing in <code>ClassInfluxDB</code>, it is never called — <code>MUSIC</code> has to be there beforehand.

One latent inconsistency, which cannot bite with current hardware: the register-read loop clamps to <code>MaxNumberOfChannel</code> (64), but the InfluxDB loop at <code>mainwindow.cpp:1371</code> iterates <code>GetNChannels()</code> unclamped. Every x2730-series board is 64 channels or fewer, so the two agree today; a wider board would read past the <code>haha[]</code> array.