Skip to content
Jakub Skowronski

Software

WebDAQ

Browser-based data acquisition, developed for LUNA

WebDAQ is the browser-based data acquisition developed for LUNA. It configures the CAEN digitizers, tunes them against a live spectrum, takes the runs, watches the rates and the beam, and keeps with every run a record meant to outlive the shift. It runs the measurements of 12C + 12C, of SHADES (22Ne(α,n)25Mg), of EASY (22Ne(α,γ)26Mg), of 19F + p, of 10B + α (the NUCLEAR project led by Marialuisa Aliotta) and of 24Mg + p.

Try the demoRead the documentation

The demo runs in your browser with simulated detectors: nothing in it is real hardware or real data.

The WebDAQ dashboard, split diagonally between the light and the dark theme: cards for run status, beam current, accumulated charge and data bandwidth, counters for three regions of interest, the Start and Stop buttons and the table of acquisition parameters.
The dashboard, in the light and the dark theme. Image from the WebDAQ repository (MIT licence); the interface has moved on a little since.

Why from a browser

LUNA measures nuclear reactions under about 1.4 km of rock at the Gran Sasso laboratory, where access to the underground halls is regulated. Being next to the digitizers cannot be a condition for running the experiment. With WebDAQ the acquisition is driven from any computer that can reach the DAQ machine, so shifts can be taken remotely.

The design follows from that. The acquisition runs inside the DAQ server, not in the page: closing the browser, reloading it or losing the network leaves a run untouched. A board that stops answering raises an alert, and with auto-restart the run is stopped, flagged and started again, so a night shift loses one run rather than the rest of the night.

How it is put together

Two processes on the DAQ machine, a web interface and a Python server, and no network hop in the data path: the boards are read, decoded and written to disk by a C++ library inside the server itself.

Diagram of WebDAQ. The browser talks to the WebDAQ server over HTTP. Inside the same server process, CaenDAQ reads the CAEN digitizers and writes the run files to data/run<N>/, which RUReader converts to ROOT. CaenDAQ also publishes the rates to Graphite, shown by Grafana. The server reads the picoammeter, posts to the ELOG logbook and sends alerts to Telegram or Zulip.ELOG9Picoammeter8TelegramZulip10Browserany PC on the network1WebDAQ serverPython · Flask2CaenDAQC++ · same process3CAENdigitizers4data/run<N>/5GraphiteGrafana7RUReader6HTTPrates

data pathcontrol and monitoringone process

  1. The browser: the interface, a React application. It asks the server for everything over HTTP, with a login token, and keeps nothing that a run needs.
  2. The WebDAQ server (Python, Flask): run control, the run database, the metadata of each run, and the histograms handed to the browser.
  3. CaenDAQ, a C++ library bound into the same process: it opens the boards, reads and decodes their data, writes the .caendat files and fills the live spectra as it goes.
  4. The CAEN digitizers, over USB, optical link or VME: DPP-PHA firmware for germanium detectors, DPP-PSD for scintillators.
  5. The run directory, data/run<N>/: the data, the board configuration, the beam current, the monitored values, the regions of interest and metadata.json.
  6. RUReader, the offline converter from .caendat to ROOT. It reads only the file header, which is why one converter reads the runs of every WebDAQ version.
  7. Graphite and Grafana: CaenDAQ publishes the rates, Grafana draws them and holds the alert rules that WebDAQ switches on at Start and off at Stop.
  8. The picoammeter (TetrAMM, RBD 9103, or a value the accelerator already publishes): beam current and accumulated charge.
  9. The collaboration's PSI ELOG: read, written and drafted from run control.
  10. Alerts to Telegram or Zulip: a board failure, a board that stops sending data, the beam current, or any monitored value.

Schematic. The numbers refer to the list below.

What it does

  • Boards

    Scan the links for connected digitizers (USB, optical, A4818, VME), add them, and keep each board's full register configuration in one file. From then on that file is the board's configuration, and every run carries a copy.

  • Acquisition

    One .caendat file per run for all the boards together, with the boards started in step by their own synchronized start.

  • Online tuning

    Change thresholds, gates and the trapezoid filter while the run is going, and see the trace and the spectrum change: a live fit of the spectrum taken since the last change gives the resolution of each setting. Only what is safe to move during a run is sent to the board, and during a production run only once you confirm; the rest waits for the next run.

  • Monitoring

    Spectra, waveforms and pulse-shape plots for every channel; event, pile-up, lost and saturated rates per channel; beam current and accumulated charge.

  • Spectra and regions of interest

    Named regions of interest with live counts, defined once on the server: the same dashboard on every screen, restored after a restart, and written into each run as roi.json.

  • Slow control

    Beam current from a TetrAMM, an RBD 9103 or a value the accelerator already publishes, and any other monitored value, recorded into each run's stats.csv with its name and unit.

  • Bookkeeping

    Run metadata written beside the data, a logbook of every run with search, flags and notes, the collaboration's ELOG, and Grafana alert rules tied to the run.

  • Watching

    Readout counters for each board, alerts to Telegram or Zulip, and a history of what happened with the recovery offered next to it.

A shift, in six steps

Condensed from the "complete session" chapter of the WebDAQ documentation. The demo's guided tour walks through the same steps.

  1. 1. Open the experiment.

    Start WebDAQ and choose the working directory of the campaign. The server starts there and creates what it needs: configuration, calibrations, data and the run database. The directory is the experiment.

  2. 2. Check the hardware.

    The boards are listed with model, firmware and link, green when the server has them open. The picoammeter reads near zero with the beam off, and the monitored values (terminal voltage, rates) are chosen, each with a name and a unit.

  3. 3. Tune a channel.

    In the tuner, with data saving off, set the threshold, then the trapezoid (or, for a scintillator, the charge gates) while watching the pulse and the spectrum.

  4. 4. Take the run.

    Fill in target, terminal and probe voltage and run type, and press Start. WebDAQ copies each board's configuration into the run, starts the boards together, the current recording and the statistics, and switches the run's alert rules on.

  5. 5. Watch it.

    Spectra, rates, beam current and charge, and the boards' own counters, from wherever the shift is. If a board fails, the alert arrives on the phone and the Troubleshoot page offers the fix.

  6. 6. Stop and write it down.

    Stop writes the charge, the region-of-interest counts and the run's metadata. The logbook entry is drafted from the run's own record; the shift adds the reasons.

FAIR in practice

FAIR data are findable, accessible, interoperable and reusable. For an experiment that starts at the acquisition: whatever is not written down while the run is taken is hard to recover afterwards. WebDAQ is designed so that every run leaves a FAIR-ready record, centred on its metadata.json. Here is what each letter rests on in the code today, and the next steps.

Findable

What WebDAQ does today (in its code)

  • Every run is a directory, data/run<N>/, with a versioned metadata.json (schema 1): run number, start and stop, duration, target, terminal and probe voltage, run type, accumulated charge, quality flag and notes.
  • The same file lists every file of the run with its role (raw data, board configuration, beam current, statistics, ROOT) and its size.
  • The logbook searches runs by number, target, notes and voltages, filters them by type and flag, and exports the selection as CSV.

Next steps

  • A persistent identifier (DOI or similar) for each run or data set, beyond the run number of the working directory.
  • The run's ELOG entry recorded in its metadata.

Accessible

What WebDAQ does today (in its code)

  • Open, plain formats (JSON, CSV, text) beside the binary data. metadata.json is rewritten atomically after every change, so a reader never sees half a file.
  • The programs that write and read the data are open source under the MIT licence: WebDAQ, CaenDAQ and RUReader.
  • Everything the interface shows comes from the server's HTTP API, with a login, which a script can use as well.

Next steps

  • Deposit of released data sets in a long-term repository, with their access terms.

Interoperable

What WebDAQ does today (in its code)

  • The .caendat files keep one documented header layout across every WebDAQ version, so a single converter, RUReader, reads them all.
  • RUReader writes ROOT files that carry the time-stamp unit, the start time and the list of boards next to the event tree.
  • The register dumps name every register with its address, as in CAEN's manuals; stats.csv gives each column its name, unit and source.

Next steps

  • The run metadata carried into the converted ROOT file as well; today RUReader takes only what the .caendat header holds.
  • A published JSON Schema for metadata.json.

Reusable

What WebDAQ does today (in its code)

  • Provenance captured at Start: for each board model, serial number, firmware, DPP type, ADC bits, sampling and synchronisation role; the versions of WebDAQ, CaenDAQ, Python and the operating system; and whether the data came from real boards or from test mode.
  • The complete register configuration of every board, copied into the run.
  • Beam current and accumulated charge; region-of-interest definitions and counts.
  • A quality flag and notes, including the automatic [AUTO-RESTART] note when a board failure restarts a run.

Next steps

  • A licence field for the data in metadata.json.

Try it: take a run in the demo, open Run files and read its metadata.json. It has the same keys, plus a Demo block that says the run was simulated.

Try the demo
An abridged metadata.json. The keys and their order are WebDAQ's; the values are made up for the example.
{
  "Schema Version": 1,
  "Run Number": 1276,
  "Start Time": "2025-11-14T21:03:12",
  "Stop Time": "2025-11-15T05:47:40",
  "Duration (s)": 31468.0,
  "Terminal Voltage": 380,
  "Run Type": "beam",
  "Target Name": "TiN #4",
  "Accumulated Charge": 2.71,
  "Flag": "good",
  "Acquisition": {
    "Synchronisation": "daisy-chain",
    "Software": { "webdaq": "…", "caendaq": "…", "acquisition_mode": "hardware" },
    "Boards": [ … ]
  },
  "Files": {
    "Data": ["run_1276_0000.caendat"],
    "Board Configuration": ["V1730_0.json"],
    "Current": ["current.txt"],
    "Statistics": ["stats.csv"],
    "Manifest": [ { "Name": "run_1276_0000.caendat", "Role": "raw-data", "Bytes": 1843200000 } ]
  }
}

Try the demo

The real WebDAQ interface, built from its code and connected to a simulated acquisition that runs in your browser. Choose the detectors: germanium (HPGe) for resolution, BGO scintillators for efficiency, or neutron detectors, liquid scintillators like EJ-309 that tell neutrons from γ-rays by the shape of the pulse. Then choose a source, tune a channel while the run goes, mark a peak, and download the files a real run would leave, metadata.json included.

The demo runs in your browser with simulated detectors: nothing in it is real hardware or real data. WebDAQ is made for a desktop screen; on a phone the demo works, but its tables scroll sideways.

Open the demo

Links, licence and citation

Licence

MIT licence. WebDAQ is written by J. Skowronski, A. Compagnucci and R. Gesue; contributions are welcome as issues or pull requests.

How to cite

J. Skowronski, A. Compagnucci, R. Gesue, WebDAQ: data acquisition for the LUNA experiment, https://github.com/skowrons94/WebDAQ

Until there is a citable release with a DOI, cite the repository and the commit you used.

Keeping data alive starts with recording them well. I keep developing WebDAQ with that aim, and the demo is kept in step with WebDAQ by a test that checks every call the interface makes against the simulation. What comes next, on the research page