User guide

Every page, what it shows and what you can change from it. For the workflow of a single run from start to logbook entry, read A complete session first; this chapter is the reference you come back to.

The navigation is the same on every page: Dashboard, Logbook, Stats, DAQ, Tuner, Troubleshoot, Alerts, Settings. The header carries four things worth knowing about:

the run status — the run badge (see the table in §1.1) with an elapsed clock;
the DAQ Server badge, which starts and stops the server itself and shows its log. While the server is up, starting or stopping it (and its log) needs you to be logged in; while it is down, it can be started from the login page. A server that is up but does not answer is never stopped from here (nothing can check your login then): stop it from the terminal (server/scripts/kill-server.sh);
the bell, which counts alerts nobody has looked at yet and turns amber when something was raised that reached nobody;
Search, a command palette that jumps to any page, any dashboard tab or any settings section.

Logging in is per browser, and the session does not expire on its own. If it is cleared you are told plainly that the run is unaffected: the DAQ server keeps taking data with nobody logged in.

1. Finding your way

Every page is in the sidebar on the left (on a phone, in the menu behind the ☰ button), grouped by what it is for:

Group	Pages
Run	Overview, Data rates, Stats, Board health
Spectra	Histograms, Waveforms, PSD, Coincidences
Setup	Boards, DAQ settings, Tuner
Records	Logbook
System	Alerts, Troubleshoot, Settings

Each page has its own address (the Dashboard views as /dashboard?tab=…), so a bookmark opens it directly. The sidebar folds down to icons with Collapse at its foot, remembered per browser. Histograms, Waveforms and PSD can be switched off in Settings → Appearance, and the sidebar follows. The search box (or Ctrl-K) jumps to any page or setting by name.

2. Dashboard

2.1 Overview — taking the run

System status is the band of cards at the top. Drag the handle beneath it to show one row more or less; the height is remembered per browser.

Card	What it tells you
Run Status	The run number and the run badge (below), how long ago it started (or how long the last one lasted), the file write rate, and a Save switch. While the DAQ is stopped the run number is a button that opens Next run, where you set the number the next run will take.
DAQ Status	Four lines — data saving, waveforms, current, stats — each with a tick or a cross, so you can see at a glance what this run will actually record.
Picoammeter	Only for a real device: connected or not, whether it is sampling, its address and range. A monitored Graphite value has no device card, because it has no device.
Board n	One per board: Ready, Running, Board Failure or Disconnected, the firmware and channel count, and a waveform switch (locked while a run is going).
ROIs and Metrics	The regions of interest you defined, with live integrals, and the Graphite values you selected on the Stats page.

Run Setup & Control is where a run begins. Fill in Run Name, Run Type (long run, scan, background, calibration), TV (kV) and PV (kV) — all four are pre-filled from the last run, and all four are locked while a run is in progress. Then Start run.

The run badge says the same thing in the header, the phone run bar and the Run Status card:

Badge	Colour	Meaning
Running	green	a production run is acquiring
Stopped	grey	no run
Tuning	amber	the Tuner’s own acquisition, with data saving off (“not saved” in its tooltip); the run bar and the card say Tuner session instead of a run number
Board failure	red	running, and a board reported a FAIL flag this run
No answer	amber	the last run-status request got no answer: the state is unknown until it does
Unknown	grey	waiting for the first answer

The green buttons start (Start run, Start); Stop run is red and always asks first.

If the directory for that run number already exists, WebDAQ asks before using it again rather than quietly overwriting. If the run number is not set at all, it refuses and says so.

A run starts even when something next to it fails: if the current module or the statistics cannot be started, the run still starts and the toast names what is missing — “Run 1276 is acquiring, but beam current is not being recorded”. A run without its current log is worth more than no run.

The Maintenance section underneath holds the things you need rarely: connect the current module, refresh the board connections (not while running), and reset the acquisition. Reset total charge clears the lifetime charge counter and is deliberately outside that section, because it is a bookkeeping action rather than a repair.

Acquisition setup shows what this run will do — saving on or off, the file size limit, the auto-restart delay — and Adjust opens the dialog where those are set, including Auto-Restart on Board Failure and its delay.

Beam Control plots the current on target with the charge beside it: This run (with a dot that says whether it is integrating) and Lifetime total. While a run is going the plot covers the run from its start; while stopped you can pick a 30 s to 5 min window. The Position button moves the panel to one of four places on the Overview.

2.2 Board Health — what the boards are actually doing

One card per board with the readout counters CaenDAQ keeps for the run: data blocks read, events decoded, bytes read and bytes sent to file, each with its rate, and then the three numbers that matter when something is wrong:

Counter	Read it as
FAIL blocks	The board could not sustain the readout for that block — a full buffer or a lost link. Data from that point may be incomplete.
Dropped	Blocks the write queue refused because it was full. This is lost data and should always be zero.
Read errors	CAEN read errors on the link.

The badge on each card is the quick answer: Reading, No data for n s, FAIL flag, No answer (the last request to the server failed, so the numbers are the last known ones) or Not reported (this CaenDAQ build does not publish that counter). A dash in a counter means the same thing.

Every counter belongs to the run. They start at zero when a run starts and are gone when it ends, which is why the tab says so plainly between runs instead of showing zeros.

2.3 Data Rates — counts per second, per channel

A tile per board with its total event rate, then four tiles for the selected board — Events, Pile-ups, Lost events, Saturations — and the write rate for the board and for all boards together. Pile-up, lost and saturation turn amber when they are not zero.

Each board’s tile also shows its average rate over the run and a trend line of the whole run, so a detector that slowly faded is visible at a glance.

The plot shows one metric for up to six channels of one board, over the whole run: the server keeps the rates from the start (and after the run stops, until the next one starts), so a reload or a late arrival loses nothing. A long run is thinned by averaging neighbouring points, which keeps it light without changing the mean. Three controls sit above it:

Plot — the sampling cadence, from 0.5 s to 60 s. This is not a display setting: one CaenDAQ tick samples the counters, differences them and publishes them, so the same number sets the refresh rate, the averaging window and the resolution of what reaches Graphite.
Show — the whole run, the last 10 minutes or the last minute.
Rate shown — which of the four rates is drawn. All four are recorded, so switching keeps the history you already have.

A badge reads Running, Stopped or No answer. A run that stops leaves its trace on screen; a run that starts begins a new one.

2.4 Histograms, Waveforms and PSD

The histogram dashboard is covered in Spectra and ROIs: which spectra are shown, their ROIs, zoom, rebinning and the per-run roi.json. It belongs to the experiment rather than to your browser — the layout lives on the DAQ server, so every screen in the control room shows the same thing.

Waveforms and PSD are tabs on the same dashboard. Waveforms also carries the board-configuration controls that decide what the board digitises into a trace — dual trace, what trace 1 and trace 2 carry, and the digital probe. Those go to the board immediately, so treat them as a setup activity rather than something to touch mid-measurement.

3. Logbook

Two logbooks live here: the run metadata WebDAQ records itself (Runs) and the collaboration’s ELOG (ELOG).

3.1 Runs

A table of every run, newest first. Search covers run numbers, targets, notes and voltages; the type and flag filters narrow it; Columns chooses what is shown and Export CSV writes out exactly the rows you have filtered to.

Two columns are editable in place: the Flag (good, unknown, bad) and the Notes. Actions → Edit entry… corrects the run name, voltages and type of a run already taken — useful when a shift realises the target was mistyped.

The run number is a link to the run’s own page.

3.2 One run

Six tabs, reading the database and the run directory together:

Overview — the notes, the timeline, the run conditions, the data products with their sizes, and the acquisition provenance (which WebDAQ, which CaenDAQ, which platform, and whether the data came from real boards or from the mock).
Notes — a Markdown editor with a preview. It warns you before leaving with an unsaved draft.
Beam Current — current.txt plotted, with the charge integrated over every sample rather than over the drawn points.
Stats — one plot per monitored metric from stats.csv, each labelled with the name and unit you gave it on the Stats page.
Boards — the register dump each board ran with, copied into the run directory at start. This is what makes the run reproducible.
Convert — RUReader, offering only the options the installed converter advertises. See Run data and conversion.

A run still in progress is marked in progress and its duration reads still in progress; nothing on the page pretends the run is finished.

3.3 ELOG

Read and write the collaboration logbook without leaving run control: the entry list with search, the reading pane with attachments, and a composer whose fields come from the logbook’s own form definition, so required attributes are required here too.

Write up a run fills a new entry from the run’s own record — timing, beam current, ROIs, board configuration — and tells you if some of that was missing. Everything stays editable before you post. See ELOG.

4. Stats

The Graphite values this experiment watches. Each card is one metric, with its latest value, a sparkline, and buttons to rename it, stop reading it or remove it. N/A means no reading came back; the light at the top says whether Graphite is answering at all, so “server down” never looks like “metric with no data”.

Add metric browses the metric tree or searches it by name, which beats typing a path from memory. The name and unit you give a metric are not cosmetic: they become the column heading in every run’s stats.csv.

The Graphite server card holds the host, the port and the metric prefix for this experiment. Give each campaign its own subtree — ancillary.rates.12c12c — and no campaign ever shares a series with another. A live run picks up a change at its next stats interval.

5. DAQ

Three tabs: Configuration, Calibration and Hardware Info.

5.1 Configuration

Board Settings is the whole register set of one board, grouped by function and in the order the signal is processed. Advanced shows every register rather than the tuned ones; Binary shows bit fields. Registers carry their CAEN manual description, and values are shown in the units you think in — per cent for the DC offset, nanoseconds for the time registers.

Writes on this tab go to the board immediately and are not blocked while a run is in progress. That is deliberate — it is the same dashboard used to set a board up — but it means this is not the place to experiment during a measurement. Use the Tuner, which knows which registers are safe to move while the boards are acquiring.

Synchronization is the daisy chain: which board is master, which are slaves, what each board’s TRG-OUT carries, and whether the start pulse can actually walk the cable. Each switch is annotated needed — on, needed — off or not needed here for that board’s position in the chain, and anything that would stop the chain starting is listed with a ⚠ next to the board that causes it. The page also draws the cable order and the start sequence. CAEN digitizers explains the mechanism.

Energy calibration is no longer here: it is made where the spectrum is, from each histogram card (the ruler button, see Spectra, ROIs and the histogram dashboard).

5.2 Hardware Info

What the boards report about themselves — model, serial number, firmware, DPP licence, connection, and the acquisition registers as actually programmed — plus the software versions recorded with every run. The CAEN API only answers while the digitizers are open, so this page is populated during a run and says so when there is none.

6. Tuner

The place to change thresholds and shaping with beam on target. The page starts acquisition with data saving switched off, so nothing you do here lands in a run directory; the amber Tuning badge (and Tuner session in the run bar) says that the Tuner is holding the run. The Tuner has no automatic scans: you change a setting, save it, and judge it on the trace, the rates and the fitted peak; the Tune this channel checklist gives the order.

The Online switch decides where a change goes:

Online	While a run is going	Effect
on	yes	Registers that are safe to move are written to the board as you save them. Each field is marked live or next run, so you know before you touch it.
on	no	Written to the board anyway — the next run applies the whole configuration regardless.
off	either	Saved to the board’s configuration only, and applied at the next run.

During a production run (started from the Dashboard), Online is never carried over: it comes back off, and switching it on asks first (Online for this run), because saved changes then reach the data of the run being taken at once, while the run’s stored register file does not show them.

The allowlist of live-writable registers comes from the server per firmware and channel, and a write the board refuses is reported as saved, not sent to the board with the reason. The configuration and the hardware therefore cannot drift apart: the save always happens, and you are told whether the board took it.

Beneath the controls are a waveform panel (with the trace and digital-probe selectors) and the energy spectrum of the channel you are tuning.

7. Troubleshoot

The page to open when something looks wrong, and the one to read the morning after. It has two halves: Recovery at the top and History below. Troubleshooting is the chapter that goes with it.

Recovery lists five actions, each with its current state — whether that part of the system answers right now — and a button that says what it does (for example Restart the server, Reset acquisition). Nothing here runs by itself. An action that would cost data while a run is in progress is refused before you press it, with the reason on the page.

History is every alert and recovery, newest first, kept on the server across restarts. Filter it by Everything, Problems, Recoveries or Actions. Each row carries the board or value it was about, the run it belonged to, and which destinations received it — including the badge reached nobody, which is the one you want to notice. Mark all read clears the bell.

8. Alerts

The Grafana alert rules, managed from here so you do not have to open Grafana during a shift: pause or activate a rule, edit its threshold, and mark rules as auto-managed with the ⚡ button.

An auto-managed rule is activated when a run starts and silenced when it stops, which is the answer to a “beam current too low” rule that is right during a run and pure noise while you are setting up. The marks are stored per browser, so set them on the control-room screen.

This page talks to Grafana through the DAQ server; the address and token are in Settings → Monitoring.

9. Settings

Grouped by what each section is about; every entry says in one line what it is for. Everything except Appearance is stored on the DAQ server and is therefore the same for everyone. The boards are set up under Setup → Boards (scan, add, live status) and DAQ settings (their registers).

Group	Section	What it holds
Hardware	Current module	Which source the beam current comes from — TetrAMM, RBD 9103 or a monitored Graphite value — and its settings. The measured current is pushed to the Graphite server of Monitoring.
Services	Monitoring (Graphite, Grafana)	The Graphite server — host, web port (where the Stats page reads metrics), Carbon port (where the DAQ rates and the beam current are written) and the metric prefix of the experiment — and the Grafana address with a service-account token. Detect finds both on this PC and lunaserver. The DAQ server makes the requests, so the addresses have to be reachable from the server machine.
Services	Logbook (ELOG)	The logbook URL, the shared account, default attributes, and whether WebDAQ may post at all.
Alerts	Notifications	Telegram and Zulip credentials, and the alert rules. See Monitoring and alerts.
Interface	Appearance	Theme, which dashboard views and cards are shown, and whether current acquisition is enabled at all. Browser-local.

Note

conf/telegram_settings.json, conf/zulip_settings.json, conf/elog_settings.json and conf/grafana_settings.json hold credentials in plain text on the DAQ machine. The interface never shows them again once saved — it masks them — but the files themselves are readable by anyone with an account on that machine, so do not copy a working directory between sites without emptying them.

10. What is refused, and when

A short list of the places WebDAQ says no, so the refusal is not a surprise:

Action	Refused when
Start a run	No run number set; a run is already going; no boards configured.
Overwrite a run directory	Always asked first.
Change the run number, saving, the size limit, the run name, type or voltages	While a run is in progress.
Refresh the board connections	While a run is in progress.
Reopen the boards, reset the acquisition	While a run is in progress (from Troubleshoot).
Scan for boards	While a run is in progress.
Switch the current module	While the current module is acquiring.
Restart the statistics	With no run active, or when the run saves no data, or when the existing `stats.csv` cannot be moved aside.
Write a register to a live board	When it is not on the firmware’s safe list — it is saved to the configuration and applied at the next run instead.