Skip to content

Latest commit

 

History

History
843 lines (723 loc) · 90.9 KB

RELEASE.md

File metadata and controls

843 lines (723 loc) · 90.9 KB

ADServal Releases

Unified EPICS areaDetector driver for ASI pixel detectors via Serval (TimePix3, Medipix3; TimePix4 planned). Repository: areaDetector/ADTimePix3 (legacy module name; see Naming below).

The repository was transferred a while back to the areaDetector organization.

Naming. Release notes and new documentation use ADServal for the unified driver. The EPICS support module, $(ADTIMEPIX) install path, C++ symbols (ADTimePix, ADTIMEPIX_*), and this GitHub repository remain ADTimePix3 until a planned rename and compatibility stub. Full naming guide: documentation/NAMING.md. areaDetector/ADTimePix is an unused placeholder (initial commit only); it is not this driver. Earlier TimePix driver efforts predated the current Serval-based implementation here.

Since Serval features differ the driver is specific to Serval version. Different branches of ADTimePix3 support different Serval versions. The master branch supports Serval 4.x.x and 3.x.x. Serval 4.1.5 remains the recommended stable 4.1.x version and includes dual-image and other Serval fixes. R1-7-4 acquisition-lifecycle qualification also passed with Serval 4.1.6-EXPERIMENTAL build 1760 on the TPX3 and MPX3 emulators.

From R1-7-0, one driver module (ADServal; shipped as ADTimePix3) supports both TimePix3 (TPX3) and Medipix3 (MPX3) via Serval: family is detected at runtime (DetectorFamily_RBV, capability PVs) and IOC startup selects the TPX3 or MPX3 profile.

Driver depends on Serval versions, at this time. Latest release is R1-8-0 (October 6, 2026, driver 1.8.0). Tested with stable Serval 4.1.5, Serval 4.1.6-EXPERIMENTAL build 1760 on the TPX3 and MPX3 emulators, other 4.1.x versions, and 3.0.0-3.3.2.

R1-8-0 (October 6, 2026)

Driver / user-visible version 1.8.0 (see ADTIMEPIX_* in ADTimePix.h).

Qualification and support matrix

R1-8-0 is a software- and emulator-qualified release. It makes no new physical-detector qualification claim, and physical testing is not a release gate. Site-specific physical results remain useful follow-up evidence and will be addressed if they expose behavior not represented by the emulators.

Configuration R1-8-0 support and qualification
TPX3 single chip and 2×2 quad Established support retained, including existing rotation and mirror mappings.
TPX3 two-quad 4×2 Emulator-qualified at 1024×512. Coordinate-dependent mask/BPC comparison, PixelConfig-difference, and masked-pixel export support UP only and require two distinct 41... quad-board IDs. This restriction does not imply that established one-chip or quad acquisition orientations are absent.
TPX3 single-board SpidrTurbo 4×2 Not supported. Its distinct 84... mapping is not inferred from the two-quad layout and fails closed.
MPX3 Existing software/emulator support retained; no new physical post-equalization qualification is claimed.
Generic geometry and Timepix4 Deferred. Geometry generalization must first represent independent ASIC width and height, including the 448×512-pixel Timepix4 matrix.

Interactive per-pixel editing and any expansion of per-pixel observability are deferred to a future release. Existing BPC upload, PixelConfig refresh, comparison, and diagnostic paths remain in scope.

Release scope and traceability

The feature-content range R1-7-4..7c0fbd8 contains 29 commits delivered by 14 consecutively merged pull requests. The release-preparation pull request adds version, release-status, and final-assurance updates to this baseline.

PR Scope
#51 Bounded rolling accumulation
#52 Preview-rate semantics
#53 Accumulator numeric-range contract
#54 Calibration-path containment
#55 Removal of stray BOB text
#56 Release-assurance CI
#57 Image-accumulation screen stability
#58 AddressSanitizer and UndefinedBehaviorSanitizer CI
#59 Dependency/version evidence
#60 Size-aware mask and histogram displays
#61 Eight-chip profile and waveform capacity
#62 Phoebus screen refresh
#63 Phoebus prefix-macro synchronization
#64 TPX3 two-quad 4×2 mask and calibration support

Phoebus screen refresh

  • Synchronize the detector-owned R3-14 screens with tested SNS BOB commit 73f4d0c.
  • Add native BOB detector information, detector configuration, detector layout, measurement dashboard, measurement information, TPX3 API/alarm, and MPX3 alarm panels while retaining the legacy OPI files for compatibility.
  • Update TPX3 and MPX3 embeds to use the native BOB panels and remove the obsolete TPX3 diagnostics action, whose target display is not shipped.
  • Keep the SNS-wide ADet/R3-14/common display changes in the site BOB repository; they are not copied into this module.
  • The imported detector-owned files are byte-identical to the SNS set runtime qualified with the TPX3 and MPX3 emulators, including image display, profiles, histogram, and interactive ROI selection.

CI and release assurance

  • Add a pinned epics-base/ci-scripts submodule and GitHub Actions workflow that builds a clean EPICS Base 7.0 dependency tree with asyn and ADCore before building ADTimePix3.
  • Run the deterministic C++ suite, coordinate-map validation, Phoebus BOB XML validation, REUSE compliance, and whitespace checks in CI, retaining TAP results as workflow artifacts.
  • Add a repository-owned BOB XML validator so local and CI validation use the same command.
  • Add AddressSanitizer and UndefinedBehaviorSanitizer debug jobs for the deterministic C++ suite.
  • Generate deterministic JSON and Markdown dependency/version evidence for each default CI build. The retained workflow artifact records the exact ADTimePix3, ci-scripts, EPICS Base, asyn, and ADCore commits; component and bundled CPR/json versions; and the ADCore configuration-hook digest without embedding timestamps or local filesystem paths. Generation fails if a declared dependency ref does not match the branch or tag actually checked out for the build.
  • The R1-8-0 hosted CI matrix uses Ubuntu 24.04, GCC, C++17, and EPICS Base 7.0. It runs default, AddressSanitizer, and UndefinedBehaviorSanitizer configurations. The default job prepares asyn and ADCore from their selected master refs; its retained dependency artifact records the exact resolved commits, the pinned ci-scripts commit, bundled CPR 1.14.2 and nlohmann/json 3.12.0, and the ADCore configuration-hook digest.

Image accumulation display stability

  • Replace nine overlapping, geometry-specific Phoebus image widgets with one dynamically sized widget for each accumulated, current-frame, and last-N waveform. The display continues to support 256x256, 512x512, and 1024x512 detector rasters while avoiding repeated array-index update warnings.
  • Preserve the existing waveform and geometry PV names and the accumulation controls introduced for R1-8-0.

Mask and histogram display stability

  • Replace overlapping fixed-size MaskBPC, BPC, and PixelConfig-difference widgets with one dynamically sized widget per image. Rules based on PixCount_RBV retain 256x256, 512x512, and 1024x512 raster support.
  • Restore a direct Verify BPC action on the PixelConfig mask panel while preserving the existing RefreshPixelConfig PV and BPC/DACS navigation.
  • Keep accumulated preview-histogram Y autoscaling enabled as frame updates arrive. No histogram data, axis PV, or acquisition behavior changes.
  • SNS Phoebus qualification passes for 256x256 and 512x512 mask displays and preview-histogram accumulation. The 1024x512 mask display also passes with the two-quad TPX3 emulator. No new physical-detector qualification is claimed for R1-8-0.

Eight-chip IOC waveform capacity

  • Raise the TPX3 NDStats profile capacity to 1024x512 so the horizontal cursor profile is not truncated at 512 pixels for an eight-chip 4x2 mosaic. Smaller detector geometries continue to publish their actual profile lengths.
  • Select MASK_BPC_NELEMENTS=524288 to reserve 1024x512 record capacity for mask/BPC, PixelConfig-difference, and image-accumulation waveforms. This is a capacity prerequisite; it does not provide an eight-chip calibration file.
  • Remove the unused legacy NELMT setting from the TPX3 profile; current waveform capacities are controlled by XSIZE, YSIZE, and MASK_BPC_NELEMENTS.
  • SNS Phoebus qualification passes for the full-width 1024-pixel horizontal profile, 1024x512 image accumulation, and preview-histogram accumulation.
  • Add an opt-in synthetic 4x2 demo calibration pair: a deterministic 524288-byte BPC and a DACS file with unique [Chip0] through [Chip7] sections, both reproducibly composed from the existing quad demo files.
  • Correct the rectangular eight-chip geometry using captured Serval metadata: RowLen=4 chips across, NumberOfRows=512, NumberOfChips=8, and PixCount=524288. The isolated eight-chip path derives a 1024x512 raster, two chip rows, and a 256-pixel chip edge (65536 PixelConfig bytes per chip), while preserving the established one- and four-chip geometry path. Eight-chip mask mapping requires two distinct TPX3 quad board IDs and fails closed for the separate single-board SpidrTurbo layout.
  • Replace stale global PixelConfig errors with a completion message after each refresh; per-chip status fields continue to report matches and failures.
  • Map two adjacent quads as 2,1,4,7 / 3,0,5,6, with the right module rotated 180 degrees, and add compiled full-grid round-trip and portable coordinate tests. The distinct single-board SpidrTurbo mapping remains deferred.
  • Qualify the opt-in 4x2 files and mask workflow with the two-quad TPX3 emulator on 2026-10-04: BPC and DACS uploads returned HTTP 200; all eight 65536-byte PixelConfig responses matched their BPC slices with zero mismatches; and a rectangular mask propagated through the 1024x512 mask preview and masked-pixel JSON export. The 1024x512 image-accumulation and histogram views continued to operate during the same qualification.
  • The checked-in calibration is explicitly synthetic and must not be used as detector equalization or as evidence of hardware qualification. Physical 1024x512 mask testing and detector-specific eight-chip equalization are optional post-release site work, not R1-8-0 release gates.

Bounded rolling accumulation

  • Replace repeated sum-of-N recomputation with an exact rolling update whose per-frame work is O(elements), independent of the requested window length.
  • Bound retained Img and PrvHst rolling-window state by geometry-aware, per-channel budgets (512 MiB default; 1-4096 MiB configurable). The budget is a ceiling, not an up-front allocation.
  • Publish window-capacity, current-fill, and status readbacks so a capped or unavailable request and the number of frames currently contributing are explicit to operators and analysis clients.
  • Release retained window storage on invalid or undersized reconfiguration and preserve the newest history when a valid window is reduced.
  • Add reusable rolling-sum tests for exact sums, eviction, resize, capacity, frame mismatch, failed reconfiguration, recovery, reset, and size overflow.
  • Rename the operator-facing update-interval labels to publication interval: the rolling sums remain exact on every input frame, while waveform and NDArray publication may be decimated to control callback and display load.
  • Add the budget, window capacity, current fill, and status to the Img and PrvHst Phoebus accumulation screens.
  • Preserve the existing preview acquisition-rate PV names while labeling their detector-frame semantics explicitly. Add nominal preview-product rate and histogram-window span readbacks derived from PrvPeriod_RBV, and show them on the PrvImg and PrvHst screens.
  • Refresh the PrvHst memory estimate immediately after a requested-window or retention-budget change; periodic refresh remains active during acquisition.
  • The operator contract and capacity formula are documented in documentation/ACCUMULATION_CAPACITY.md.

Numeric range contract

  • Publish accumulated Img and PrvHst waveforms as UINT64, current-frame count waveforms as ULONG, Sum NDArrays as NDUInt64, and Average NDArrays as checked NDUInt32; existing PV names and NDArray addresses are preserved.
  • Saturate running-sum and total-count accumulation at UINT64_MAX; reject a rolling-window update that cannot remain exact. Preserve legacy signed scalar total-count PVs by clamping at INT64_MAX instead of allowing negative or implementation-defined conversion results.
  • Correct PrvHstTotalCounts_RBV from ai to int64in, without renaming it, so values remain integral and exact through INT64_MAX.
  • Document that CA exposes unsigned-32 and 64-bit records as DBF_DOUBLE, while PVA preserves uint[], ulong[], and long. All supported last-N values remain integer-exact over CA because they are below 2^53.
  • Add per-channel latched range-alarm and detail readbacks, reset with the corresponding accumulation reset, and expose them on both Phoebus screens.
  • Add numeric range, count-unit, and saturation attributes to count NDArrays. Document the public types and client migration in documentation/NUMERIC_RANGE_CONTRACT.md.

Security and deployment containment

  • Canonicalize an immutable startup ADTIMEPIX_CALIBRATION_ROOT and reject BPC/DACS paths, mask filenames, traversal, absolute filenames, and symlink targets that escape it. An unset root defaults to /; an explicitly invalid root fails closed.
  • Keep the shipped TPX3 and MPX3 profiles portable by defaulting the root to /, reported as Permissive: /; restrictive sites select one narrower subtree in the family unique.cmd. Basename, regular-file, and atomic-write protections remain active in permissive mode.
  • Stage BPC and masked-pixel JSON output beside the target, synchronize the complete content, and atomically rename it; local failure never initiates a BPC upload and does not expose a partial replacement.
  • Check every enabled Raw, Image, Preview Image, and Preview Histogram base against the immutable startup ADTIMEPIX_DESTINATION_ALLOWLIST before any destination update is sent to Serval. The shipped portable default, file:/*,tcp://*,http://*, permits arbitrary supported ports and TCP roles; restrictive sites replace it with exact endpoints and directory prefixes.
  • Remove compiled placeholder Basic credentials. Optional Serval credentials come from the protected startup environment and are never exposed as PVs.
  • Add readbacks for both active policies and configurable CALIBRATION_ASG fields for calibration-path, calibration-load, and mask-upload controls.
  • Remove the unused legacy initCamera helper, which contained hard-coded calibration paths and a fixed bias write.
  • Document the ACF/ASG, least-privilege service-account, filesystem, credential, destination, and protected-network/TLS deployment contract in documentation/SECURE_DEPLOYMENT.md.

Validation

  • Full IOC build passed.
  • 358/358 deterministic protocol, lifecycle, rolling-window, numeric-range, path-containment, atomic-write, and destination-policy checks passed.
  • Coordinate-map validation passed for 13 implemented cases; five planned physical SpIDR 4x2 cases remain deferred.
  • All Phoebus BOB files passed XML validation.
  • REUSE validation passed for 396/396 files with REUSE 3.0.
  • TPX3 emulator runtime qualification passed at 10 Hz for Img and PrvHst windows of 10 and 100 frames: requested capacity equaled current fill, memory plateaued at the expected bounded values, per-frame publication operated, and status text remained complete within the EPICS string limit.
  • TPX3 emulator capped-window qualification passed: a 64 MiB image budget capped a requested 100-frame 512 x 512 window at 62 frames, and a 1 MiB histogram budget capped a requested 100-frame, 16000-bin window at 14 frames. Increasing each budget restored 100-frame capacity and fill without a reset.
  • Runtime transport qualification passed: CA reported the expected DBF_DOUBLE protocol view, while PVA reported ulong[] for accumulated waveforms, uint[] for current-frame waveforms, and long for PrvHstTotalCounts_RBV. Constraining PVA discovery to the configured CA path selected the intended server interface.
  • Runtime reset qualification passed: Img and PrvHst range alarms returned zero / OK, and both detail readbacks returned OK.
  • TPX3 emulator deployment-containment qualification passed with the restrictive module-vendor root: startup policy readbacks reported Enforced; an approved destination Apply succeeded without configured credentials; an out-of-root calibration directory produced WRITE/INVALID with the path-exists readback set to No; a traversal filename was rejected before any BPC request; and an unapproved histogram endpoint was rejected before Serval configuration. Restoring the approved values returned both calibration records and destination Apply to normal.
  • Portable-default restart qualification passed: the IOC environment and driver readbacks agreed on calibration root /, calibration policy Permissive: /, destination allowlist file:/*,tcp://*,http://*, and destination policy Permissive.
  • The established TPX3 2×2 quad path passed regression checks for BPC and DACS uploads, four 65536-byte PixelConfig matches, asymmetric mask placement, mask reset, whole-detector counts, and image accumulation.
  • Final release-candidate smoke testing confirmed that a cleanly rebuilt single-chip TPX3 emulator IOC reported driver version 1.8.0 and completed a short acquisition with image accumulation and histogram display operating. TPX3 and MPX3 quad emulator acquisitions also completed successfully in the immediately preceding qualification run.
  • No new physical-hardware qualification is claimed or required for R1-8-0.

R1-7-4 (September 27, 2026)

Driver / user-visible version 1.7.4 (see ADTIMEPIX_* in ADTimePix.h).

The functional change since R1-7-3 is the transactional acquisition-lifecycle work merged as PR #49.

Acquisition lifecycle

  • Add one coordinator for the legal Idle, Starting, Running, Stopping, and Fault transitions and derive ADAcquire, ADStatus, and status messages from that state.
  • Commit acquisition startup only after Serval, the measurement monitor, and every enabled TCP receiver are ready within bounded deadlines.
  • Route partial-start, monitor, stop, and shutdown failures through one idempotent cleanup owner. Unconfirmed remote stop state remains Fault and an explicit stop retries reconciliation.
  • Add 22 deterministic transition, injected partial-start, concurrent stop/fault, worker-readiness, fault-message, and Serval Info: null reconciliation checks; the full fixture suite passes 294/294.
  • Emulator qualification:
    • MPX3 completed eight normal start/stop acquisitions (98 frames total, zero dropped) with preview, integrated-preview, and full-image streams.
    • TPX3 survived a forced Serval stop/restart during acquisition: explicit Stop reconciled the retained fault, explicit Apply restored the destination, and the recovered Image, Preview, and histogram acquisition processed 403 frames with zero dropped.
    • MPX3 likewise survived a forced Serval stop/restart during acquisition: explicit Stop reconciled the retained fault, explicit Apply restored the full-image and dual-preview destinations, and the recovered acquisition processed 81 frames with zero dropped.

Documentation consistency

  • Correct the current bundled nlohmann/json version, 14-address NDArray map, and GraphicsMagick status; document the surrounding EPICS release files as the source of external module versions.
  • Align the support2 migration note with read-only reconnect behavior and require source/exit-test verification of the ADCore shutdown fix instead of inferring it from an ADCore version number.

Deferred assessment scope

  • ADTPX3-CAN-011, ADTPX3-CAN-012, and ADTPX3-CAN-015 remain open for the post-release R11 numeric, accumulation, and retained-capacity contract. Large retained workloads require site validation and resource monitoring meanwhile.
  • Calibration-path/deployment containment (CAN-014), incremental component extraction (CAN-017), and broader CI, sanitizer, generated-dependency, and evidence gates remain separate post-release workstreams.
  • Physical-hardware qualification remains pending under the controlled R19 acceptance matrix.

R1-7-3 (September 26, 2026)

Driver / user-visible version 1.7.3 (see ADTIMEPIX_* in ADTimePix.h).

  • Release contents and traceability:

    • The exact R1-7-2..R1-7-3 range contains 32 merged pull requests (#16 through #47), 67 commits, and 87 changed files. The grouped ledger below accounts for every merged PR; later sections provide the operator-visible detail.
    • #16 established the deterministic C++ test product and bounded fake Serval HTTP/TCP peers.
    • #17-#22 hardened request booleans, stream dimensions, BPC file bounds, momentary upload actions, HTTP deadlines, and stream shutdown ordering.
    • #23-#37 added typed/atomic validation and failure propagation for measurement, detector configuration, TPX3 clock/enum/TDC state, DAC writes, destination, dashboard, status, health, measurement configuration, and PixelConfig responses.
    • #38-#42 completed family-safe mask semantics, MPX3 packed PixelConfig mapping, bit preservation, documentation, and rectangular mask geometry.
    • #43 documented the fork/branch/pull-request workflow; #44-#46 completed consume-once framing, read-only reconnect, and synchronized worker lifecycle; #47 prepared and validated the release.
    • Direct commit d081fe3 removed TPX3-specific default macros from shared launcher shells; the other direct commits in the range are release-version bookkeeping.
  • Serval request, file, and response hardening:

    • BiasEnabled and TPX3 clock flags are serialized as native JSON booleans; TPX3 enum inputs are range-checked before use. TDC readbacks are decoded by field presence and malformed values fail without overwriting prior state.
    • Image dimensions and byte counts use checked products and detector-derived limits. BPC reads/writes require exact family/geometry sizes, retain bounded storage, and stop before upload on local failure. Calibration upload actions reset reliably after processing.
    • Shared Serval HTTP calls have finite deadlines. Measurement, detector, destination, dashboard, health, DAC, configuration, and PixelConfig paths validate status and complete JSON shape before changing driver state; failed PUT/GET operations propagate errors instead of publishing partial success.
  • Consume-once Serval TCP stream framing:

    • Preview-image, full-image, and preview-histogram workers use one bounded framing component that owns all unconsumed receive bytes.
    • Each frame consumes exactly one newline-terminated JSON header, its declared binary payload, and Serval's trailing payload newline. Payload newline, brace, NUL, and high-bit bytes are never interpreted as delimiters, and coalesced later messages remain buffered for the next decode.
    • Image payload width is derived from Serval metadata (bitDepth and dataSize, 8-, 16-, or 32-bit) and cross-checked against dimensions and any explicit pixelFormat; this includes MPX3 integrated previews serialized as 32-bit rasters.
    • Stream decoders receive only complete frames and no longer read additional payload bytes directly from the socket. Invalid or oversized headers, retained-byte overflow, and truncated EOF fail closed with channel-specific diagnostics.
    • Hardware-free regression tests cover every two-chunk split across adjacent messages, byte-at-a-time delivery, coalescing, binary delimiter bytes, short payloads, clean/truncated EOF, and reconnect-buffer reset.
    • Emulator qualification passed on 2026-09-26 with Serval 4.1.6: TPX3 processed 117 frames with zero drops while image and histogram displays updated; MPX3 processed four frames with zero drops, delivered four arrays on every T0/T1 preview, integrated-preview, threshold-difference, and full-image output, and closed all three TCP image channels normally at measurement end.
  • Read-only Serval reconnect reconciliation:

    • On a disconnected-to-connected transition, refreshOnReconnect() performs read-only GETs of destination, detector, and measurement state. It never calls fileWriter(), initAcquisition(), uploadBPC(), or uploadDACS(); configuration and calibration changes remain explicit operator actions.
    • Partial reconnect readback reports Error and is retried by the periodic connection poll instead of publishing a false OK state. Dashboard version data and measurement TDC rates are refreshed by field presence rather than a stale SDK-version value.
    • RefreshConnection, RefreshPixelConfig, and ApplyConfig are reliable momentary actions. Shared Phoebus controls provide Refresh Status, Apply Destination, Verify BPC, and View Differences without redundant command readbacks.
    • TPX3 Serval-restart qualification left Server.Destination unset and performed no automatic BPC or DACS upload. Explicit ApplyConfig restored the preview destination, after which 30 frames were processed with zero drops and preview images updated.
  • Synchronized Serval TCP worker lifecycle:

    • PrvImg, PrvImg1, Img, and PrvHst use one atomic stopped/running/connected phase protocol instead of unsynchronized Boolean flags. Thread-handle creation and joining are serialized separately from channel data access.
    • Stop first publishes the stopped phase, wakes reconnect waits, and interrupts any blocked socket receive with shutdown(). The driver then joins every worker before releasing its socket; shared socket ownership keeps a receiver valid until it exits.
    • The worker read loops no longer hold a channel mutex across blocking TCP receives, reconnect delays, or invocation of the frame-processing path.
    • Hardware-free tests cover duplicate starts, stop/failure transitions, concurrent stop versus connection publication, 100 repeated start/stop cycles, idempotent socket teardown, and prompt interruption of a silent peer.
    • TPX3 emulator qualification with Serval 4.1.6 completed 17 consecutive IOC acquisition start/stop cycles with preview image, full image, and preview histogram enabled. Every cycle returned ADStatus to Idle after all enabled workers closed; the histogram worker connected and exited on every cycle. The 16 corresponding Serval measurement summaries processed 1,178 frames with zero drops and reported no TCP sender errors.
    • MPX3 emulator qualification with Serval 4.1.6 completed six finite acquisitions with frame preview, integrated preview, and full image enabled. All three TCP streams closed normally after every measurement, every subsequent acquisition began from Idle, and Serval processed 139 frames with zero drops and no TCP sender errors.
  • Release qualification and deferred scope:

    • R1-7-3 is software- and emulator-qualified. Physical post-equalization MPX3 mask/PixelConfig confirmation, broader physical reconnect testing, and 4x2 SpIDR placement/rotation/BPC ordering remain controlled-hardware follow-up work; a Serval PixelConfig match is not proof of detector-register state.
    • Standard acquisition start/stop and reconnect paths are covered, but exhaustive transactional partial-start and injected-fault coordination remain future work.
    • Large retained image/histogram accumulation workloads do not yet have a geometry-aware memory-capacity or unsigned-to-signed overflow contract. Validate site workloads and monitor resource use.
    • File and destination configuration assume a trusted deployment boundary; canonical writable-root confinement, destination allowlists, access control, and credential policy remain deployment-hardening work.
  • Family-safe BPC mask semantics:

    • ASI confirmed that bit 0 is the per-pixel mask for both TPX3 and MPX3: set it to mask and clear it for normal operation. Mask changes preserve every adjustment, test-pulse, reserved, and unknown bit.
    • TPX3 mask readback, counts, writes, and masked-pels JSON now test or update only bit 0. The observed value 31 / 0x1f is a masked pixel whose adjustment bits are also set; it is not a required complete-byte replacement value.
    • MPX3 mask readback, counts, writes, and export operate on one big-endian 16-bit word per pixel. Bit 0 masks both counters; bits 1–5 and 6–10 are the two adjustment fields; bit 11 is test-pulse injection. ASI identifies bits 12–15 as unused and normally zero; the driver still preserves them defensively.
    • TPX3 bits 6–7 are likewise unused and normally zero. All mask changes preserve every non-mask bit rather than normalizing unused fields.
    • MPX3 mask images and JSON use Serval's explicit per-chip Chip, X, Y, and Orientation layout and fail closed when that layout is missing or unsupported. All eight Serval chip-orientation strings are supported, and a detector-orientation write refreshes Layout.Rotated.Chips before later mask operations.
    • An asymmetric live operator-mask test exposed two independent layout conventions: the four non-axis-swapped direction strings must be applied literally, and Serval tile Y origins are bottom-based while areaDetector image Y is top-based. The shared mapping converts image_tile_y = image_height - chip_width - serval_y. After rebuilding, the L-shaped mask aligned with both threshold-counter images in all eight global detector orientations. These live cases exercise all eight Serval chip-orientation strings.
    • Added deterministic family, packed-value, classification, count, bounds, and bit-preservation tests in servalProtocolFixtureTest.
  • MPX3 packed PixelConfig layout:

    • Correct the MPX3 model from two concatenated 64 KiB byte slices to one big-endian 16-bit word per pixel: mask bit 0, threshold-0 adjustment bits 1–5, and threshold-1 adjustment bits 6–10. The per-chip size remains 131072 bytes.
    • PixelConfigDiff compares complete packed words; a bit-0-only change displays as 1. Full-block mismatch PVs continue counting differing byte positions.
    • Place MPX3 diff pixels using Serval's per-chip rotated layout instead of the TPX3 quad map. After converting Serval's bottom-origin tile Y to top-origin image Y, the UP image assigns chips 2/3 to the top row with LtRTtB (identity) and 1/0 to the bottom row with RtLBtT (180°).
    • Emulator validation set only bit 0 in five words per chip. Serval round-trip comparison reported five byte mismatches per chip, and identical acquisitions showed exactly those 20 pixels suppressed in both counters with no other image changes.
    • ASI subsequently confirmed the shared bit-0 set/clear rule, chip-block order 0, 1, 2, 3, and that the remaining TPX3/MPX3 upper bits are unused. ASI indicated that the PixelConfig value reported through Serval is converted from the BPC rather than guaranteed to be read directly from detector registers. During TPX3 emulator qualification, the applied BPC/mask effect persisted across a Serval process restart while the emulator remained running, ruling out the Serval JVM as the sole persistence layer. The comparison therefore validates a Serval-reported configured value against the selected file; it neither proves hardware-register state nor identifies whether persistence is in the emulator, SPIDR/controller, or detector chip.
    • ASI granted redistribution of the supplied eq-02.bpc and detector-chips.json as example/test configuration. They are included under test/fixtures/mpx3/eq-02/ with provenance, integrity hashes, and a fixture-specific redistribution notice.
  • Rectangular mask geometry safety:

    • MaskReset, MaskRectangle, and MaskCircle now use one checked row-major y * width + x implementation for square and rectangular detector images.
    • Rectangle and circle operations clip at image edges, preserve non-mask bits, and fail instead of writing when the EPICS waveform is smaller than the declared detector geometry.
    • Hardware-free regression tests cover rectangular stride, clipping, guard elements, bit preservation, and invalid geometry.

R1-7-2 (August 24, 2026)

Driver / user-visible version 1.7.2 (see ADTIMEPIX_* in ADTimePix.h).

Patch after R1-7-1: Phoebus Display Builder layout only — no Serval API or IOC DB change. Reorganize tpx3App/op/bob/ to mirror IOC boot Option C:

  • common/ — shared panels: ADSetup.bob, ConnectionStatus.bob, Acquire/ADCollect.bob, Detector/, Mask/, Setup/, Measurement/ (macro-driven $(P)$(R)).
  • profiles/tpx3/ — TPX3 main shell (main.bob), TimePix3Detector.bob, TimePix3Status.bob, TPX3-only acquire panels (PrvHstHistogram, PrvImgMonitor, DetectorConfig, stream utilities).
  • profiles/mpx3/ — MPX3 main shell (main.bob, was MediPix3/MediPix3.bob), Mpx3Status.bob, Mpx3* acquire/detector panels.
  • profiles/tpx4/ — placeholder README.
  • Root launchers — TimePix3.bob, MediPix3.bob embed profile mains with default P/R macros; MediPix3/MediPix3.bob shim keeps legacy bookmark paths.
  • Emulator/ — unchanged (family embed panels).
  • Layout guide: tpx3App/op/bob/README.md. Legacy op/opi/ (CS-Studio) not moved.

R1-7-1 (August 21, 2026)

Driver / user-visible version 1.7.1 (see ADTIMEPIX_* in ADTimePix.h).

Patch release after R1-7-0: driver fixes, IOC boot layout, and calibration/template path cleanup. No Serval API change; rebuild driver and update IOC startup paths if you use custom scripts.

  • PipelineState / dashboard sync (TPX3 + MPX3):
    • PipelineState_RBV: enum labels via driver readEnum(); removed invalid FTHS/FTVL from Measurement.template.
    • Parse Measurement.Status from GET /dashboard (flat JSON) and GET /measurement (Info.Status); do not overwrite idle state with Unknown when dashboard Measurement is null after stop.
    • Default PipelineState to Unknown (-1) at driver init; RefreshConnection at end of profile init/detector.cmd scripts.
  • Autosave (profile-specific):
    • Split auto_settings.req into TPX3 and MPX3 lists so TPX3 startup does not monitor MPX3-only plugin PVs.
    • create_monitor_set: use set_requestfile_path("profiles/<family>") + basename auto_settings.req so .sav files land in ./autosave/<family>/ (not nested profiles/… paths).
  • IOC boot — profile layout (Option C):
    • profiles/tpx3/, profiles/mpx3/, shared common/st_core.cmd; thin launchers st.cmd / st_mpx3.cmd.
    • Legacy init_detector*.cmd remain as shims; MPX3 plugins in profiles/mpx3/plugins_mpx3.cmd.
    • Fix missing quote on FileHDFImgT1 in plugins_mpx3.cmd.
  • File-plugin XML templates:
    • templates/hdf5/ (NDFileHDF5 hdf5_layout: hdf5_minimal.xml, hdf5_prvhst_histogram.xml) and templates/nexus/ (NDFileNexus plugin_template.xml).
    • NDFileNexus templates isolated for possible ADCore deprecation in favour of NeXus-metadata HDF5 layouts.
  • Vendor calibration layout:
    • vendor/tpx3/1x1/ (was oneChip/), vendor/tpx3/2x2/ (demo tpx3-demo.*), vendor/mpx3/ unchanged, vendor/tpx4/ placeholder.
    • profiles/tpx3/init/paths.cmd updated; runtime mask.bpc and *_masked_pels.json still written under active BPCFilePath.

R1-7-0 (August 11, 2026)

Driver / user-visible version 1.7.0 (see ADTIMEPIX_* in ADTimePix.h).

  • Unified TimePix3 + Medipix3 driver: One driver binary and shared Serval HTTP/TCP stack for ASI pixel detectors on Serval. Runtime family from Serval metadata (DetectorFamily_RBV, capability PVs). TPX3 sites use st.cmd / profiles/tpx3/ and TimePix3.bob; MPX3 uses st_mpx3.cmd / profiles/mpx3/ and MediPix3.bob (below). Prior TPX3-only releases remain valid for TPX3-only deployments (R1-6-3 and earlier). From R1-7-1, boot paths moved to profiles/<family>/ (see R1-7-1 release notes).
  • Medipix3 (MPX3) — new in this release:
    • IOC profile: st_mpx3.cmd, init_detector_*_mpx3.cmd, vendor/mpx3/ BPC/DACS.
    • Dual-threshold preview: demux by thresholdID on TCP 8088 / 8089; BothCounters; T0−T1 band-pass (Pva5/Pva6).
    • Opt-in full-rate Image[] TCP (8086) with threshold demux (Pva7/Pva8) and HDF soak plugins.
    • Phoebus: MediPix3.bob, detector config, preview writer, image channels.
    • Docs: documentation/medipix3/ (integration, dual-threshold preview, hardware notes). Validated on emulator and first ASI hardware preview (July 2026); equalization / IXS band-pass on hardware still to follow.
  • TimePix3 (TPX3) — fixes in this release (behaviour unchanged when family is TPX3):
    • Make prvHstWorker joinable so acquireStop does not hang after Preview histogram streaming.
    • Enable NDStats row/column profile axes for PVA preview plots (stats_profiles.cmd, Stats1 init, mosaic XSIZE/YSIZE).

R1-6-3 (June 7, 2026)

Driver / user-visible version 1.6.3 (see ADTIMEPIX_* in ADTimePix.h).

  • Embedded libcpr (CPR) upgrade to 1.14.2:
    • Synced vendored CPR sources from upstream libcpr/cpr release 1.14.2 into tpx3Support/cpr (headers under cpr/, implementation .cpp files in parent directory).
    • Updated tpx3Support/Makefile header/source lists to the 1.14.2 file set (includes new units such as connection_pool, curlmultiholder, multiperform, sse; removes obsolete bearer.cpp).
    • Added vendored tpx3Support/cpr/cpr/cprver.h for non-CMake EPICS builds (CPR 1.14.2 still includes cpr/cprver.h from cpr.h; upstream typically generates it via CMake).
  • Compiler baseline change for CPR >= 1.10:
    • Switched driver/support builds to C++17 in tpx3Support/Makefile and tpx3App/src/Makefile (USR_CPPFLAGS += -std=c++17).
  • Driver HTTP call cleanup after CPR upgrade:
    • Shared CPR request helpers in serval_http.h / namespace ADTimePix3ServalHttp (serval_http.cpp); high-duplication GET/PUT sites (connection checks, config paths, measurement start/stop in acquire.cpp) use them to reduce repeated auth/header/timeout boilerplate.
    • Default 5 second timeouts on key status reads (/dashboard, /detector, /detector/health, /measurement/config, PixelConfig GETs, etc.).
    • trimHttpBodyForLog, logHttpFailure, and logHttpWarning on ADTimePix (implemented in serval_http.cpp): HTTP error lines include method, URL, status, and a truncated/sanitized response snippet (avoid giant HTML dumps in the IOC log).
    • BPC / DACS upload alignment (uploadBPC(), uploadDACS(), GET SERVAL /config/load): Use the same auth-only CPR path as the rest of the driver (servalHttpGetAuthOnly -> ADTimePix3ServalHttp::getAuthOnly so mask_io.cpp stays consistent with serval_http.cpp). On HTTP status other than 200, each call logHttpFailure and returns asynError (previously these uploads often returned asynSuccess even when SERVAL reported an error). HttpCode / WriteFileMessage (or equivalent PVs) still reflect SERVAL response; check them when uploads fail.
  • Code organization (driver split, no functional or PV changes):
    • serval_stream.cpp + network_client.cpp - PrvImg / Img TCP jsonimage streaming and image accumulation hooks.
    • serval_http.cpp - Serval REST (dashboard, detector/server config, DACs, fileWriter, initCamera / initAcquisition, PixelConfig refresh, measurement config, connection poll).
    • acquire.cpp - acquireStart, acquireStop, timePixCallback (measurement HTTP + worker-thread orchestration).
    • histogram_io.cpp - PrvHst TCP jsonhisto streaming and histogram accumulation (unchanged responsibility).
    • mask_io.cpp - BPC/mask paths, upload, pelIndex / bpc2ImgIndex (see documentation/COORDINATE_MAP.md).
    • ADTimePix.cpp - core driver shell (~1.8k lines): constructor, path checks, PV I/O (writeInt32 / writeOctet), report, PrvHst NDArray plugin push.
  • Copyright, SPDX, and REUSE (license compliance):
    • LICENSE: Dual copyright (Brookhaven Science Associates / BNL, UT-Battelle / ORNL) with development-history note; MIT terms unchanged.
    • tpx3App/src/*.{cpp,h}: Matching file headers with the SPDX MIT license identifier.
    • .reuse/dep5: Machine-readable copyright/license for Db templates, OPI (op/**), IOCs, documentation, vendored CPR / nlohmann/json, and other paths without per-file headers.
    • LICENSES/MIT.txt: REUSE 3.0 license text; run reuse lint from the repository root before tagging a release (project is compliant when lint reports success).
    • SPDX.spdx: Minimal SBOM listing the driver (MIT), bundled dependencies, EPICS build-time packages, and external Serval (NOASSERTION).
    • See documentation/CONTRIBUTING.md for contributor expectations on new files.
  • Build validation:
    • Full repository build (make -j) completes successfully after upgrade.
  • BPC naming consistency: Renamed bcp2ImgIndex to bpc2ImgIndex (BPC file index to image index). Masked-pels JSON export uses skipped_unmapped_bpc_index (was skipped_unmapped_bcp_index). Fixed stray BCP typos in path-check comments.
  • Serval JSON shape parsing (getDetector, getServer, fetchDacs):
    • updateDetectorHealthFromJson() in serval_http.cpp: Maps GET /detector Health to temperature, humidity, and VDD/AVDD PVs by JSON shape (object for Serval 2/3, array for Serval 4 / multi-board), not by ADSDKVersion alone. Multi-board behavior matches R1-6-2 (merged ChipTemperatures, dual-board rail PVs at asyn ADDR 3-5). Logs and skips on unexpected Health types instead of throwing.
    • fetchDacs(): Per-chip ChipNTemperature uses chipTemperatureFromHealthV4 / V3 depending on whether Health is an array or object.
    • getServer(): Unwraps Serval 4.x {"Destination": {...}} before counting Raw / Image / Preview channels; missing or non-array keys count as zero (no json::exception on partial responses).
    • getDetector(): Guards optional Layout / Original / Chips; try/catch around JSON parse/update so malformed detector JSON logs getDetector JSON error and returns asynError instead of aborting the IOC (extends R1-6-2 HTTP/JSON robustness to the full detector refresh path).
  • Connection status UX: updateStatusFromConnection() sets DetectorState_RBV (ADStatus) to Disconnected when SERVAL or the detector is unreachable, with specific StatusMessage_RBV text; restores Idle / Acquire when linked. Phoebus: ConnectionStatus.bob (SERVAL/detector LEDs, status line, Refresh); Acquire/ADCollect.bob shows enum labels (Idle, Disconnected, Error, ...) not raw integers (replaces unused bob/Acquire/ADCollect.opi; TimePix3.bob embeds the .bob). ADSetup.bob (local fork): Ready / Not ready follow DetConnected_RBV (not AsynIO.CNCT); Connect/Disconnect buttons still control the asyn port only (Asyn port label). ADSetup.bob and Acquire/ADCollect.bob use 11 pt Sans and tighter widget spacing (rescaled from ADCore autoconvert 16 pt Liberation Sans) so they align with native TimePix3 OPI panels; TimePix3.bob embed heights and layout were adjusted accordingly.
  • IOC boot raw channel defaults (init_detector_paths.cmd): RawFilePath default is tcp://listen@localhost:8085 (TCP stream); Raw1FilePath default is file:/media/nvme/raw1 (disk). The previous example IOC boot had these reversed (primary Raw to disk, Raw1 to TCP). Sites that write raw events to disk should set RawFilePath explicitly.
  • Late SERVAL/detector connect (issue #14): When the IOC starts before SERVAL or the detector is available, connection poll refreshOnReconnect() now runs on disconnect-to-connect transition: updates SDKVersion_RBV / FW timestamp from /dashboard (updateServalVersionFromDashboard in checkConnection, getDashboard, and startup), getDetector(), getMeasurementConfig(), channel config (fileWriter / initAcquisition / getServer), and BPC/DACS upload when file names are configured. updateTdcRatesFromMeasurementInfo() in acquire.cpp reads Tdc1EventRate / Tdc2EventRate / legacy TdcEventRate from measurement JSON by field presence, not stale SDKVersion_RBV (fixes Tdc1EvtRate_RBV stuck at zero and log spam when version was unknown at IOC start).

R1-6-2 (April 29, 2026)

  • IOC boot -- deployment-independent calibration paths: profiles/tpx3/init/paths.cmd sets BPCFilePath and DACSFilePath using $(ADTIMEPIX)/vendor/tpx3/2x2/ (with tpx3-demo.bpc / tpx3-demo.dacs) instead of hard-coded site paths, so the same script works when the module is installed under different trees.

  • Robustness -- HTTP error bodies vs JSON: When SERVAL returns a non-success HTTP status (e.g. 409 Conflict) or a body that is not JSON (plain text/HTML), the driver previously called nlohmann::json::parse on that body in several paths (writeDac, getHealth, initialServerCheckConnection dashboard handling, timePixCallback /measurement polling). That could throw an uncaught json::parse_error and abort the IOC (SIGABRT). The driver now checks HTTP status where appropriate, parses JSON only for successful responses, and catches parse exceptions so the IOC logs an error and continues. Operators should still fix SERVAL/detector connectivity; behavior is unchanged when responses are valid JSON.

  • Driver logging (asyn): Internal ERR / WARN / LOG / FLOW helpers use a single ADTPX3_FUNC macro: on GCC/Clang it defaults to __PRETTY_FUNCTION__ (richer context); other compilers use __func__. For shorter log lines, build with -DADTPX3_LOG_SHORT (see commented line in tpx3App/src/Makefile). Variadic *_ARGS macros use ##__VA_ARGS__ so format-only calls (no extra printf args) compile. By default WARN / WARN_ARGS use ASYN_TRACE_WARNING; the port trace mask must include the warning bit to see them. Sites that only enable ERROR-level trace and need legacy visibility for warnings can build with -DADTPX3_WARN_AS_ERROR so WARN* is emitted at ASYN_TRACE_ERROR (see commented line in tpx3App/src/Makefile).

  • PixelConfig vs on-disk BPC (on-demand compare): Documents the per-chip configuration held and returned by SERVAL (GET /detector/chips/<i>/PixelConfig) versus the binary file the IOC points at (BPCFilePath + BPCFileName). ASI indicates this value is converted from the BPC rather than read directly from detector registers, so a match does not independently prove hardware register state. Full operator-oriented explanation: documentation/PIXELCONFIG_BPC_DIFF.md.

    • Trigger: RefreshPixelConfig (Dashboard.template). Not merged into DAC refresh; not polled at 1 Hz.
    • Per chip: Base64 JSON string decoded to 65536 bytes per chip; compared to the BPC file slice at byte offset chip x 65536 (quad = 262144-byte file). Readbacks: PixelConfigLen_RBV, PixelConfigMatchBPC_RBV (-1 error, 0 !=, 1 =, 2 no file, 3 size), PixelConfigMismatchBytes_RBV, PixelConfigStatus_RBV (Chips.template).
    • PixelConfigStatus_RBV OPI: Implemented as a CHAR waveform (octet readback). In tpx3App/op/bob/Mask/PixelConfigMaskPanel.bob, each chip status Text Update uses Format = String (file value <format>6</format>) so Phoebus shows the message as text instead of a sequence of ASCII codes.
    • Waveform PixelConfigDiff: After each refresh, holds |SERVAL byte - BPC byte| at each TPX3 image pixel (i,j) using k = pelIndex(i,j) (same mapping as mask write / maskCircle), not bpc2ImgIndex--those two were not equivalent for all quad orientations (e.g. LEFT), which broke alignment at chip boundaries. Same NELEMENTS as BPC / MaskBPC in MaskBPC.template. Phoebus: Mask/Mask.bob embeds PixelConfigMaskPanel.bob (refresh, table, 512x512 / 256x256 |Delta| heatmaps).
    • MaskBPC read from .bpc: Loading the mask image from disk uses pelIndex(i,j) and j*COLS+i (clears value[] first), matching mask write and PixelConfigDiff; bpc2ImgIndex is no longer used on that path.
    • EPICS / asyn fixes (R1-6-2): TPX3_PIXEL_CONFIG_DIFF registered as asynParamInt32Array; doCallbacksInt32Array pushes the full diff buffer (not PixCount). RefreshPixelConfig FLNK -> PixelConfigDiff.PROC so the waveform VAL updates on process (same idea as reading BPC / MaskBPC). Compared length uses min(65536, bytes remaining in file) per chip so a 4x64 KiB file does not look like a single oversized "chip 0" slice.
    • Mask mapping bug fix: bpc2ImgIndex quad-chip index used (bpcIndex+1)/chipPelCount, which misclassified the last pel of each 64 KiB block and the final file byte (chip == 4), producing bogus "detector larger than 2x2" console messages and wrong boundary mapping. Now bpcIndex / chipPelCount (for remaining bpc2ImgIndex callers).
  • Eight-chip / dual SPIDR (IOC, DB, driver, mask indexing):

    • IOC: iocs/tpx3IOC/iocBoot/iocTimePix/load_chips.cmd loads Chips.template for CHIP0...CHIP7 (asyn ADDR 0-7); st_base.cmd sources it. OperatingVoltage.template extended with Pwr3...Pwr5 at ADDR 3-5 for the second board's three VDD/AVDD rails (see driver).
    • MASK_BPC_NELEMENTS: MaskBPC.template requires macro MASK_BPC_NELEMENTS (must be >= PixCount). It is set in unique.cmd with documented choices 65536 (1 chip), 262144 (4 chip), 524288 (8 chip). If undefined, iocsh fails dbLoadRecords for MaskBPC.template and mask PVs stay disconnected. envPaths only notes that unique.cmd must define it.
    • Driver (getDetector, Serval 4): Merges all Health[].ChipTemperatures into one flat JSON array for ChipTemps_RBV; with two Health blocks, VDD_RBV/AVDD_RBV strings become a JSON array of per-board rail arrays; fills TPX3_CHIP_VDD/TPX3_CHIP_AVDD at ADDR 3-5 from Health[1] (zeros when single board). Info.Boards[1] -> TPX3_BOARDS2_ID, TPX3_BOARDS2_IP, TPX3_BOARDS_CH5...CH8 (second SPIDR chip JSON). Safer parsing when Boards or Chips arrays are short.
    • Database: ADTimePix3.template -- BChBoard2Id_RBV, IpAddr2_RBV, Chip5_RBV...Chip8_RBV. New asyn parameter names in ADTimePix.h / createParam.
    • Mask / BPC (mask_io.cpp): For numChips == 8 and DetectorOrientation UP (0) only, pelIndex and bpc2ImgIndex use a rectangular mosaic with chip = Y_CHIP * xChips + X_CHIP from rowsCols(); intra-chip order matches single-chip UP. Other orientations for eight tiles remain TODO (verify on hardware vs Serval Layout).
    • Documentation: documentation/8chip-migration.md; README and documentation/MIGRATION_SUPPORT2.md updated (MASK_BPC_NELEMENTS checklist, links).
    • Phoebus / OPI (8-chip UX): TimePix3Detector.bob embeds CHIP0...CHIP7 (operator-adjustable layout); Acquire/DetectorConfig.bob adds Vth panels for CHIP4...CHIP7; Acquire/ImgAccumulation.bob, Mask/PixelConfigMaskPanel.bob, and Mask/Mask.bob add 1024x512 image variants when PixCount_RBV matches the 8-chip mosaic (524288); Detector/TimePixDetectorVoltages.bob (Display Builder, op/bob/Detector) or TimePixDetectorVoltages.opi (legacy BOY, op/opi/Detector) lists second-board rails Pwr3...Pwr5; Detector/TimePixDetectorHealth.bob provides summary health with cross-links to voltages.
    • IOC hardware init (calibration push): iocs/tpx3IOC/iocBoot/iocTimePix/init_detector_hw.cmd now documents that WriteBPCFile=1 and WriteDACSFile=1 trigger driver uploadBPC() / uploadDACS() calls to SERVAL /config/load (using paths from init_detector_paths.cmd), with troubleshooting notes for HttpCode, WriteFileMessage, and detector/SERVAL readiness.
  • Phoebus histogram InfoDisplay layout tweak: Manually adjusted the layout in tpx3App/op/bob/Acquire/PrvHstHistogram.bob so InfoDisplay text fits properly (increased container/text height).

  • Masked pels JSON export (RefreshPixelConfig): When a BPC file is read successfully during RefreshPixelConfig, the driver writes <BPCFilePath><stem>_masked_pels.json (stem = BPCFileName with a trailing .bpc removed, case-insensitive) containing format_version, source, optional detector/acquisition, masked_pels (BPC index, chip, lx/ly, image i/j via bpc2ImgIndex), and Bad pixels (median 1x1) for NDPluginBadPixel. Readbacks: TPX3_MASKED_PELS_JSON_RBV, TPX3_MASKED_PELS_COUNT_RBV, TPX3_MASKED_PELS_EXPORT_STATUS_RBV (File.template as MaskedPelsJson_RBV, etc.). Phoebus: op/bob/Mask/PixelConfigMaskPanel.bob shows count / status / path; Mask.bob embedded panel height updated to 920 px. See documentation/MASKED_PIXELS_JSON_AND_STREAMING.md.

R1-6-1 (March 31, 2026)

  • Processed Img file saving (Option A): The driver can push the current image accumulation (running sum and sum-of-N) as NDArrays to file plugins so that ImgImageData and ImgImageSumNFrames can be saved as TIFF or HDF5.
    • WriteProcessedImg (boolean PV): Writing 1 pushes the current running sum to NDArray address 2 and the current sum-of-N (if available) to address 3. File plugins (NDFileTIFF, NDFileHDF5) with NDArrayAddress=2 or 3 receive and can save them. One-shot; driver resets the PV to 0 after the push.
    • ProcessedImgOutputType (mbbo): 0 = Sum (NDInt64, for HDF5); 1 = Average (NDInt32, sum divided by number of frames, for NDFileTIFF). Enables TIFF writing without overflow by storing average counts per frame.
    • Driver: New pushProcessedImgToPlugins() builds NDArrays from imgRunningSum_ and the sum-of-N buffer, optionally converts to average (divide by imgAccumulatedFrameCount_ or by N for sum-of-N), and calls doCallbacksGenericPointer(..., 2) and (..., 3). Shared params (ADSizeX/Y, etc.) are saved/restored so image channels are unchanged; NDArrayCounter is restored so the main counter is not affected. New imgAccumulatedFrameCount_ tracks frames in the running sum for the average calculation.
    • Database: New records in Server.template for WriteProcessedImg and ProcessedImgOutputType (DESC fields kept <=40 characters).
    • Phoebus: ImgAccumulation.bob - added "Push to file (addr 2,3)" button and "Output type" combo (Sum / Average). Uses combo widget type for compatibility.
    • Documentation: documentation/PROCESSED_IMAGE_FILE_SAVING.md - Status section added; README "File Saving" under Img accumulation updated with WriteProcessedImg and NDArrayAddress 2/3 usage. Clarified (doc fix): addresses 2 and 3 also receive per-frame NDArrays from processImgFrame when Img accumulation is enabled; WriteProcessedImg is an additional on-demand push with Sum/Average typing. Documented that ImgImageFrame has no NDArray address (use address 1 for single-frame file saving), optional HDF5 dbLoadRecords one-line iocsh note, and a short verification tip (mean ratio addr 3 vs 1 ~ N).
    • Validation procedure/results: Added a reproducible single-plugin runtime NDArrayAddress verification section (HDF5 and TIFF) in documentation/PROCESSED_IMAGE_FILE_SAVING.md, including numeric results and viewer-compatibility notes for 64-bit TIFF.
    • NeXus-style file output: IOC boot examples iocs/tpx3IOC/iocBoot/iocTimePix/templates/hdf5/hdf5_minimal.xml (NDFileHDF5 hdf5_layout) and iocs/tpx3IOC/iocBoot/iocTimePix/templates/nexus/plugin_template.xml (NDFileNexus NXroot template, validated with ADCore XML_schema/template.sch). README documents that HDF5 and Nexus plugins use different XML dialects, template PVs, and TemplateFilePath concatenation rules.
    • Readout stack diagram: documentation/TimePix3_pipeline_48_64_96_caption.png (PNG) and documentation/TimePix3_pipeline_48_64_96.svg (editable source). Shows chip -> readout -> SERVAL and the ADTimePix3 / EPICS path vs optional LUNA (96-bit) path not used by the driver; README links to both files under Additional information.
    • PrvHst NDArray file streams (addresses 4-7): With PrvHst accumulation enabled, processPrvHstFrame pushes 1D NDArrays each frame: 4 = sum of last N (NDInt64, when the sum-of-N buffer updates), 5 = running sum (NDInt64), 6 = current frame (NDInt32), 7 = ToF bin centers in ms (NDFloat64, parallel to PrvHstHistogramTimeMs). Arrays on 4 and 5 add NDAttributes PrvHstTimeBin0Ms, PrvHstTimeBinStepMs, PrvHstNumBins (uniform axis metadata). WriteProcessedHst / ProcessedHstOutputType mirror processed Img: one-shot push with Sum (NDInt64) vs Average (NDInt32, divide by frame count or sum-of-N buffer length). pushProcessedHstToPlugins() in ADTimePix.cpp; ADDriver(..., maxAddr=8, ...) so lists 0-7 exist. Records in Server.template. See documentation/PROCESSED_IMAGE_FILE_SAVING.md and README Histogram sections.
  • PrvHst NeXus/HDF5 1D ToF example layout: Added iocs/tpx3IOC/iocBoot/iocTimePix/templates/hdf5/hdf5_prvhst_histogram.xml (hdf5_layout) for NDFileHDF5. The main detector dataset stores counts (address 5 by default), with uniform ToF axis metadata from NDAttributes (PrvHstTimeBin0Ms, PrvHstTimeBinStepMs, PrvHstNumBins) so clients can reconstruct bin centers without requiring a second full axis dataset.
  • HDF5 write troubleshooting (PrvHst): Documented and validated the NDPluginFile::writeInt32: ERROR, no valid array to write path in documentation/PROCESSED_IMAGE_FILE_SAVING.md. Clarifies that NDWriteFile requires at least one latched NDArray on the selected plugin address, and adds a minimal check sequence for ArrayCallbacks, HDF1:NDArrayAddress, and WriteProcessedHst.
  • PV naming clarification for callbacks: Updated docs to distinguish EPICS PV $(P)$(R)ArrayCallbacks / _RBV from internal driver/asyn parameter NDArrayCallbacks, avoiding "channel not found" confusion when testing from CA clients.
  • Phoebus histogram plot artifact fix: Updated tpx3App/op/bob/Acquire/PrvHstHistogram.bob XY traces to points-only rendering (no line interpolation) to avoid line-to-origin artifacts when waveform NELM exceeds valid NORD.

R1-6 (March 4, 2026)

  • CONNECT/DISCONNECT (graceful reconnection without IOC restart): The driver now supports connection status monitoring and optional config refresh when SERVAL or the detector reconnects, so the IOC does not need to be restarted when the detector/emulator or SERVAL restarts.
    • Bug fix - DetConnected inversion: Corrected ADTimePixDetConnected logic in initialServerCheckConnection(): detector present is now reported as 1 (connected), detector absent as 0 (disconnected). Previously the values were inverted.
    • Lightweight connection check: New checkConnection() uses GET /dashboard as the single source of truth and updates only ServalConnected_RBV, DetConnected_RBV, ADStatusMessage, and (when connected) DetType/ADModel. ServalConnected is 1 when GET /dashboard returns 200 (SERVAL reachable even when the root URL returns 404/302). DetConnected is 1 only when the dashboard JSON has Detector non-null. It does not call getServer() or full getDashboard().
    • Consistent connection status in getDashboard(): getDashboard() (Health PV path) now sets ServalConnected_RBV and DetConnected_RBV the same way as checkConnection(): ServalConnected=1 when GET /dashboard returns 200; DetConnected=1 only when the dashboard JSON has Detector non-null (and DetType/ADModel set); both 0 on non-200 or parse error. This avoids inconsistent states (e.g. ServalConnected=false, DetConnected=true) when Health is triggered.
    • On-demand refresh: New PV RefreshConnection (boolean output): writing 1 runs checkConnection() and updates connection status. Record in Dashboard.template.
    • Periodic connection poll: A low-priority thread runs every 5 seconds (default), calls checkConnection(), and on transition from disconnected to connected optionally calls getServer() once to refresh channel config. No acquireStop() or initCamera() is invoked from the poll thread. Poll is started in the constructor and stopped in the destructor.
    • Behavior on disconnect: Status PVs are set to disconnected and ADStatusMessage is set to "SERVAL or detector disconnected".
    • Behavior on reconnect: Status PVs are set to connected, ADStatusMessage is cleared to "OK", and channel config is re-applied by calling fileWriter() (push current PV config to SERVAL) then getServer() (refresh PVs from SERVAL). Detector initialization (BPC/DACS load, initCamera()) is not run on reconnect.
  • Detector initialization single source of truth: Detector initialization (channel paths, formats, modes, BPC/DACS paths, WriteData, etc.) uses EPICS PVs as the single source of truth: the init script sets PVs, and the driver applies them to SERVAL via fileWriter() (triggered by WriteData=1 or ApplyConfig).
    • init_detector.cmd: The detector init block (formerly inline in st_base.cmd) is now in iocs/tpx3IOC/iocBoot/iocTimePix/init_detector.cmd. st_base.cmd sources it after iocInit(). The same file can be re-run from iocsh after reconnect (e.g. < init_detector.cmd) to re-apply the same init.
    • ApplyConfig PV: New PV ApplyConfig (boolean output): writing 1 runs fileWriter() + getServer() (same effect as WriteData=1), so operators can re-apply current PV config to SERVAL without toggling WriteData or re-running a script. Record in Dashboard.template.
    • Reconnect: On transition from disconnected to connected, the connection poll now calls fileWriter() (push channel config), initAcquisition() (push detector config: TriggerMode, NumImages, etc., from PVs to SERVAL so they stay CONTINUOUS / desired values after restart), then getServer() (refresh channel state from SERVAL).
    • Documentation: README and this release note state that detector initialization is defined by the PV values set at startup (e.g. from init_detector.cmd or st_base.cmd); the driver applies those PVs to SERVAL when WriteData=1 or when ApplyConfig is triggered.
  • Code Organization - BPC/mask logic in mask_io.cpp: Moved checkBPCPath() and uploadBPC() from ADTimePix.cpp to mask_io.cpp to shorten the main driver file and keep all BPC/mask path and upload logic in one place. mask_io.cpp already contained readBPCfile(), writeBPCfile(), and mask helpers; it now also implements BPC path validation and BPC upload to SERVAL. No functional or PV changes.
  • Measurement.Config PVs (SERVAL 4.1.x - 4D-STEM and Time-of-Flight): Added read/write support for SERVAL Measurement.Config via GET/PUT /measurement/config. Previously the driver used only Measurement.Info (status, rates, frame count); Measurement.Config was not exposed. New asyn parameters and EPICS records:
    • Stem (4D-STEM): StemScanWidth, StemScanHeight, StemDwellTime (Scan); StemRadiusOuter, StemRadiusInner (VirtualDetector). Read/write; values are sent to SERVAL on write and refreshed from SERVAL when "Scan detector/health" (Health PV) is triggered.
    • TimeOfFlight: TofTdcReference (comma-separated string, e.g. PN0123,PN0123), TofMin, TofMax. Same read/write and refresh behavior.
  • Driver: getMeasurementConfig() (GET /measurement/config, parse Stem and TimeOfFlight into PVs), sendMeasurementConfig() (merge PVs into current config, PUT /measurement/config). Called when Health is written (with getDetector) and when any of the new PVs are written. Corrections and Processing branches are preserved on PUT (merge with existing config).
  • Database: New records in Measurement.template for all eight parameters (setpoint + _RBV readback where applicable).
  • Phoebus screen: New Measurement/MeasurementConfig.bob screen (4D-STEM and ToF sections) with spinners/text entries and readbacks. Embedded in TimePix3Detector.bob below Measurement Info so Measurement Config is available from the Detector Status tab. Layout may be adjusted manually for best fit.
  • Screens (new and updated):
    • New: Measurement/MeasurementConfig.bob - Measurement.Config (4D-STEM Stem scan/virtual detector, Time-of-Flight). Opened from Detector Status tab (TimePix3Detector) below Measurement Info.
    • Updated: TimePix3Detector.bob - embeds MeasurementConfig; size/layout may be adjusted manually.
    • Updated: tpx3emulator.bob - title and Replay File label now state replay of previously collected raw .tpx3 data; tooltip added on Replay File. Emulator screen supports replay of raw .tpx3 files (single, repeat N, forever, file list). Opened from Detector Config tab.
  • Bug fix - Memory leaks:
    • BPC buffer (mask_io.cpp): readBPCfile() allocates a buffer with malloc() and passes it to the caller. The buffer was never freed in readInt32Array(), leaking memory on every mask/BPC read or write. The buffer is now freed before readInt32Array() returns (and bufBPC is initialized to NULL).
    • Histogram NDArray (histogram_io.cpp): When pNDArrayPool->alloc() returned a non-null array with null pData, the array was not released, leaking a pool reference. The failure path now calls pHistArray->release() when pHistArray is non-null.
  • Database: Measurement.template - TofTdcReference stringout record uses device support asynOctetWrite (not asynOctet) so dbLoadRecords does not report "no such device support for 'stringout' record type".
  • ADCore iocBoot/commonPlugins.cmd: request file paths for support modules must use each module's Db folder (e.g. $(CALC)/calcApp/Db, $(SSCAN)/sscanApp/Db), not the lowercase db folder, so save_restore finds the .req files (e.g. sseq_settings.req, sseqRecord_settings.req).

R1-5 (January 27, 2026)

  • TCP Streaming for Preview Images: Replaced GraphicsMagick HTTP method with TCP jsonimage streaming for PrvImg channel. Preview images now use configurable TCP streaming (tcp://listen@hostname:port format) for lower latency and better performance. GraphicsMagick implementation preserved in preserve/graphicsmagick-preview branch for backward compatibility.

  • TCP Streaming for Image Channel: Added TCP jsonimage streaming support for Img channel, enabling real-time 2D image streaming similar to PrvImg channel. Both PrvImg and Img channels can now stream concurrently using separate array slots (pArrays[0] for PrvImg, pArrays[1] for Img) to prevent reference count conflicts.

  • TCP Streaming for Histogram Channel: Added TCP jsonhisto streaming support for PrvHst channel, enabling real-time 1D histogram streaming. Histogram data is processed and accumulated (running sum) with support for sum of last N frames. Histogram NDArrays are sent via callbacks with NDArrayAddress=5 for use with areaDetector plugins. PrvHst channel can stream concurrently with PrvImg and Img channels without conflicts.

  • Histogram Accumulation Enable Control: Added PrvHstAccumulationEnable control (similar to ImgAccumulationEnable) to enable/disable histogram accumulation processing. When disabled, the driver does not connect to the TCP port, allowing other clients to process jsonhisto data. When enabled, the driver connects and processes histogram frames for accumulation and display.

  • Histogram Waveform PVs for ToF Plotting: Added waveform PVs for histogram data visualization:

    • PrvHstHistogramData (INT64): Accumulated histogram data (running sum)
    • PrvHstHistogramFrame (INT32): Current frame histogram data
    • PrvHstHistogramSumNFrames (INT64): Sum of last N frames
    • PrvHstHistogramTimeMs (DOUBLE): Time-of-Flight axis in milliseconds (bin centers)
  • Phoebus Screen for Histogram Plotting: Updated PrvHstHistogram.bob screen with three XY plots for Time-of-Flight histogram visualization:

    • Accumulated histogram vs ToF [ms]
    • Current frame histogram vs ToF [ms]
    • Sum of last N frames vs ToF [ms] The screen includes controls for enabling/disabling accumulation and histogram configuration parameters.
  • Concurrent Channel Support: Fixed NDArray reference count conflicts when multiple channels are configured for TCP streaming simultaneously. Each channel now uses its own NDArray address (PrvImg: 0, Img: 1, PrvHst: 5), allowing stable concurrent operation of all three channels.

  • Clean Shutdown for TCP Streaming: Fixed "Broken pipe" errors when stopping acquisition with preview, image, and/or histogram channels enabled. Shutdown sequence now properly stops Serval measurement first, signals all worker threads (PrvImg, Img, PrvHst) to stop concurrently, then waits for all threads to exit before disconnecting. This ensures clean shutdown even with rate mismatches (e.g., 60 Hz frame rate vs 5 Hz preview rate). Worker threads now detect "Connection closed by peer" as expected behavior during shutdown. Connection closure messages are channel-specific ("PrvImg TCP connection closed by peer", "Img TCP connection closed by peer", and "PrvHst TCP connection closed by peer") to distinguish which channel is closing. This unified shutdown sequence prevents java.lang.InterruptedException errors from Serval's TcpSender threads.

  • Optimized TCP Connection Delays: Reduced delay times to minimum safe values for faster acquisition startup/shutdown: port release delay (100ms), port binding delays (200ms for PrvImg and Img channels), and TcpSender stop delay (300ms). These optimized delays reduce total acquisition cycle time by ~900ms while maintaining reliability.

  • Improved Debug Messages: Enhanced acquisition status debug messages to show actual ADStatus values (0 = Idle, 1 = Acquire) instead of asynStatus return codes. Messages now display ADAcquire value, previous state, and ADStatus before and after acquireStart()/acquireStop() operations for better debugging.

  • Phoebus .bob Screen Updates: Updated multiple Phoebus display builder (.bob) screens throughout the user interface to reflect new features and improvements, including TCP streaming support, Img1 channel configuration, PrvImg monitoring, and enhanced metadata display. Screens updated include acquisition controls, detector configuration, file writing, mask management, and status monitoring.

  • Image Accumulation Features for Img Channel: Integrated functionality from the standalone tpx3image IOC into the ADTimePix3 driver's Img channel. New features include:

    • Running Sum Accumulation: 64-bit accumulation of pixel values over all frames via ImgImageData PV (INT64 waveform array)
    • Current Frame Display: Individual frame data via ImgImageFrame PV (INT32 waveform array)
    • Sum of Last N Frames: Configurable sum of last N frames (default: 10) via ImgImageSumNFrames PV (INT64 waveform array), with configurable update interval
    • Performance Monitoring: Processing time (ImgProcessingTime, ms) and memory usage (ImgMemoryUsage, MB) tracking
    • Total Counts: Total counts across all accumulated frames via ImgTotalCounts PV (INT64)
    • Reset Control: ImgImageDataReset (boolean output) - one-shot button to reset accumulated image data, clearing running sum, frame buffer, total counts, and processing time samples
    • Configuration PVs: ImgFramesToSum (1-100000, default: 10) and ImgSumUpdateInterval (1-10000, default: 1 frame)
    • Phoebus Screen: Updated ImgAccumulation.bob screen (located in Acquire/ folder) adapted for ADTimePix3 to visualize accumulated images, sum of N frames, and performance metrics, with controls for enabling/disabling accumulation and resetting accumulation
    • Code Organization: ImageData class and accumulation logic implemented in separate files (img_accumulation.h/.cpp) following existing pattern (mask_io.cpp) for better maintainability
  • Bug Fix - Image Accumulation Parameter Update: Fixed critical bug in writeInt32() handler where condition for bias/trigger parameters (line 2795) was missing function == comparisons for subsequent terms, causing all writeInt32 calls to be intercepted and preventing ImgFramesToSum parameter updates from being processed. The buffer size now correctly updates when ImgFramesToSum PV is changed, and memory usage properly reflects the configured buffer size.

  • Bug Fix - DataType_RBV "Illegal Value" with Histogram Channel: Fixed issue where histogram channel was setting NDDataType to NDInt64 (value 8), but the DataType_RBV database record enum only supports values 0-5, causing "Illegal Value" status. The driver now preserves the previous NDDataType value and does not set it for histogram data. The NDArray itself still correctly uses NDInt64 data type internally.

  • Bug Fix - SizeX_RBV/SizeY_RBV Incorrect Values with Histogram Channel: Fixed issue where histogram channel was overwriting shared size parameters (ADSizeX, NDArraySizeX, ADSizeY, NDArraySizeY) used by image channels, causing histogram bin sizes (e.g., 16000) to overwrite image dimensions (e.g., 512). The driver now preserves these shared parameters and does not set them for histogram data, since histogram uses NDArray address 5 (separate from image addresses) and the NDArray contains size information in its attributes.

  • Bug Fix - ArrayRate_RBV Showing Double Rate: Fixed issue where ArrayRate_RBV was showing double the actual rate (e.g., 10 Hz instead of 5 Hz) when preview image channel (PrvImg) was active. Both PrvImg and Img channels were incrementing the shared NDArrayCounter, causing double counting. The driver now only increments NDArrayCounter in the Img channel (main acquisition), not in PrvImg channel (preview). ArrayRate_RBV now correctly reflects the main Img channel rate. Preview channel rate is available via PrvImgAcqRate_RBV PV. Also fixed NDArray address assignment: PrvImg uses address 0, Img uses address 1 (was incorrectly using 0 for both).

  • Bug Fix - PVA Image Flickering with Histogram Channel: Fixed issue where PVA image display (pva://TPX3-TEST:Pva1:Image) flickered when histogram channel was enabled. The flickering occurs in the Preview image channel (TPX3-TEST:cam1:PrvImgFilePath, using tcp://listen@localhost:8089 and http://localhost), not in the actual image channel (TPX3-TEST:cam1:ImgFilePath). The histogram channel was calling callParamCallbacks() without arguments, which updated all parameters including shared ones (ADSizeX, ADSizeY, etc.) used by PVA plugin, triggering unnecessary redraws. The driver now uses selective parameter callbacks, only updating histogram-specific parameters. This prevents parameter updates from affecting image channel displays. Note: Investigation confirmed there are no duplicate PVs between ADTimePix3 and the standalone histogram IOC that could cause conflicts. The flickering that persists after this fix is likely related to the TimePix3 emulator (tpx3Emulator-4.1.1-rc1.jar) behavior when histogram channel is enabled in Serval configuration, affecting preview image data timing, network bandwidth allocation, and frame synchronization. This may be emulator-specific and might not occur with physical detectors. This is a known emulator limitation, not a driver bug. See documentation/PVA_FLICKERING_DIAGNOSIS.md for detailed analysis and diagnostic steps.

  • Optimization - Histogram Processing When Accumulation Disabled: Optimized histogram data processing to skip all processing (including rate calculation) when PrvHstAccumulationEnable is disabled. Previously, the worker thread would still parse and process histogram data even when accumulation was disabled, only skipping the accumulation step. The driver now returns early from processPrvHstDataLine() when accumulation is disabled, avoiding unnecessary CPU usage and parameter updates.

  • Bug Fix - Histogram Log Message Spam When Accumulation Disabled: Fixed issue where repeated "PrvHst TCP buffer full without finding newline, resetting" messages were filling log files when PrvHstAccumulationEnable was disabled. The worker thread was still reading data from the TCP socket even when accumulation was disabled, causing the buffer to fill without processing. The driver now skips data reading when accumulation is disabled, preventing buffer overflow and suppressing warning messages. The worker thread remains connected (so Serval doesn't see a disconnect) but doesn't consume data, significantly reducing log file spam. These messages are warnings (not errors) indicating buffer overflow, which is expected behavior when accumulation is disabled since data isn't being processed.

  • Feature - Histogram Data Reset Control: Added PrvHstDataReset PV (boolean output) to allow manual reset of accumulated histogram data. This one-shot button resets PrvHstFrameCount_RBV, PrvHstTotalCounts_RBV, clears PrvHstHistogramData and PrvHstHistogramSumNFrames waveform arrays, and resets processing time and memory usage. Histogram counters no longer automatically reset when acquisition stops, allowing users to preserve accumulated data between acquisitions and reset manually when needed. A reset button has been added to the PrvHstHistogram.bob screen in the ConfigurationControl group, matching the arrangement in the image accumulation screen. This provides consistent user experience between image and histogram accumulation features.

  • Feature - Histogram Millisecond PVs for Compatibility: Added calculated PVs PrvHstBinWidthMs_RBV, PrvHstBinOffsetMs_RBV, and PrvHstTotalTimeMs_RBV that provide histogram bin parameters in milliseconds (calculated from frame parameters using TDC clock period constant). These PVs are compatible with the standalone histogram IOC screen format and are automatically updated when frame parameters change. The PVs use calc records with CP (Change Process) flags to update when source parameters change.

  • Feature - StatusMessage_RBV Updates: Added status message updates to ADStatusMessage (standard areaDetector parameter) to provide user feedback during acquisition operations. Status messages include "Starting acquisition...", "Acquisition running", "Acquisition stopped", and error messages for failed start/stop operations. The status message updates automatically as acquisition state changes, providing clear feedback in the user interface.

  • Bug Fix - NumImages INVALID Status: Fixed issue where NumImages PV showed INVALID status with value 100000000 (100 million) at IOC startup. The ADDriver base class was initializing NumImages to a very large default value, causing INVALID status. The driver now initializes NumImages to 0 (unlimited) in the constructor, which is appropriate for continuous mode and prevents the INVALID status. For single mode (ImageMode = 0), the driver automatically sets NumImages = 1 when switching to single mode. Bug Fix - NumImages WRITE INVALID in single mode: When the database or a client wrote a value other than 1 to NumImages while already in single mode, the driver returned an error ("Cannot set numImages in single mode"), causing WRITE INVALID on the record and log spam. The driver now accepts the write and clamps the value to 1 internally, so the record no longer goes WRITE INVALID. No action required - both issues have been resolved in R1-5.

  • Bug Fix - ArrayCounter_RBV Double Count with Histogram Channel: Fixed issue where ArrayCounter_RBV was approximately twice NumImagesCounter_RBV when jsonhisto streaming was enabled. The histogram channel (PrvHst, address 5) was calling doCallbacksGenericPointer(), which automatically increments the shared NDArrayCounter parameter. Since histogram uses a separate NDArray address (5) and should not affect the image channel counter, the driver now saves and restores NDArrayCounter around histogram callbacks to prevent histogram from incrementing it. ArrayCounter_RBV now correctly reflects only image frame counts, matching NumImagesCounter_RBV when histogram is enabled. No action required - this has been resolved in R1-5.

  • Bug Fix - "parameter 51 in list 5, invalid list" asyn Warnings: The driver was created with maxAddr=4 (addresses 0-3 only), but the histogram channel uses NDArray address 5. When asyn or plugins accessed parameter 51 (ARRAY_DATA) at address 5, asyn reported "invalid list" because that address did not exist. The driver now uses maxAddr=6 so that PrvImg=0, Img=1, and PrvHst=5 are all valid. The "parameter 51 in list 5, invalid list" (and similar) messages no longer appear when the histogram channel is enabled. Root cause (from asynReport): "Parameter 51 is undefined, name=ARRAY_DATA" in "list 5" indicated that address (list) 5 was invalid on the TPX3 port, not that parameter 51 was undefined.

  • Known Issue - RESNIC Pattern Distortion in Phoebus: Some images displayed in Phoebus show distorted RESNIC patterns (expected checkerboard pattern appears as a different structure). This is an intermittent issue that affects only some frames, not all. The correct checkerboard pattern is visible in some images, while others show a distorted pattern with vertical stripes or different geometric structures. This may be a SERVAL bug specific to TCP streaming channels when histogram (jsonhisto) is enabled. The byte swapping code in the driver appears correct (using __builtin_bswap16/__builtin_bswap32 for network byte order conversion). The issue may be related to:

    • SERVAL TCP streaming implementation when multiple channels (image + histogram) are active
    • Data corruption or frame synchronization issues in SERVAL's TCP sender threads
    • Network bandwidth allocation or timing issues when histogram channel competes with image channel
    • Emulator-specific behavior (if using TimePix3 emulator)

    Further investigation is needed to determine if this is a SERVAL bug, driver issue, network transfer issue, or display issue. If you encounter this issue, please report it with details about which channel (PrvImg or Img), frame numbers, whether it occurs consistently or intermittently, and whether it only occurs when histogram channel is enabled.

  • Note: GraphicsMagick was only used for preview image reading via HTTP. File saving is handled directly by Serval, which writes files to disk without using GraphicsMagick.

R1-4 (January 8, 2026)

  • For img channel, rename $(P)$(R)ImgStpOnDskLim, $(P)$(R)ImgStpOnDskLim_RBV for consistancy.
  • Refresh the FileWriter Phoebus screens for additional img1 channel.
  • Add additional image (img1) channel, to allow concurrent tcp streming of jsonimag, and TIFF file writing.
  • cpr (1.9.1) and nlohmann/json (3.12.0) sources embeded in this ioc (Jakub Wlodek)
  • documentation folder created

R1-3 (September 7, 2025)

  • Preview readout of tiff (50 fsp) is faster than png (37 fps).
  • Resolved "Warning: timePixCallback thread self-join of unjoinable"
  • The fileWriter() function in the ADTimePix3 driver has been successfully optimized to improve maintainability, performance, and reliability. The original 200+ line monolithic function has been refactored into a modular, well-structured implementation.
  • Serval 4.x.x: Rotations/mirror operation strict checking, and requires 'reset=true', DOWN->half instead of 180.
  • TDC1/TDC2 reporting for serval 4, and Serval 3.
  • The Serval 4.x.y requires {"Content-Type", "application/json"}, instead of "text/plain", as "Content-Type" when using cpr library.
    • Log Level, ChainMode, Polarity, PeriphClk80, ExternalReferenceClock, etc.
  • Serval 4.1.x requires changes to the driver.
    • Server->Detector->Health is an array of kv pairs in Serval 4.1.x, but was kv pairs in Serval v3.3.2.

    • Server->Detector->Health->Pressure

    • Server->Detector->Info->ChipType

R1-2 (June 24, 2025)

  • Alarms added: TDC not present, NO detector counts.
  • ResetHotPixels PV loads negative then positive mask. Neutron detectors radiation issues.
  • Alarms: stream channels, serval/detector connection, hot pixels detection.
  • Read back configured channels from Serval
  • Read VDD and AVDD and set monitor. {Voltage [V], Current [A], Power [W]}
  • Compute masked pixels as areaDetector 1D array index (replaces bpc vector index).
  • Links to manuals from DetectorConfig.opi screen.
  • The ioc starts even without detector or Serval: detector and serval API status PVs are updated.
  • Individual chip temperature, and archiver monitoring
  • Mask generation for one chip, and 2x2 quad chip detectors for all 8 detector orientations.
  • AD mask image placed into BPC calibration mask.bpc file.
  • Masked pixels from BPC read into AD mask image.
  • Masked pels in 2nd octet of BPC waveform PV
  • Connection status PVs
    • Serval connected (URL web interface is up)
    • Detector is connected to Serval
  • Report number of masked pixels in bpc calibration
  • Manipulation of the Binary Pixel Configuration (BPC). Allows creation of positive or negative image mask.
    • Create image rectangular mask
    • Create image circular mask
    • Image mask can be positive or negative
    • Individual image mask is additive
    • Number of image masks is not limited
  • Rotate image into all 8 possible arrangement.
    • Update readback PV to report orientation correctly
  • Data collection control added
    • Raw modes: Queue size
    • Image mode: Integration Size, Queue Size, Stop Measurement on Disk Limit.
    • Preview modes: Integration Size, Queue Size, Stop Measurement on Disk Limit.
  • Serval 3.3.2-SNAPSHOT: ORNL assembled detectors do not have voltage bias sensors in detection layer. Detection layer is build by ORNL, and not provided by ASI. The 3.3.2-SNAPSHOT minimizes spam TimePix3 related to missing bias from log file. The log file size is manageable with this change in Serval.
  • Bug fix: Image Integration mode connected to correct PV.
  • Operational ioc: st.cmd delay before writing the preview images.
  • Updated driver Revision version in file.

R1-1 (August 18, 2024)

  • Updated documentaiton
  • Attempt at rotating images using DetectorOrientation in Layout

R1-0 (August 17, 2024)

  • Chips DACs voltages settings use atomic function. The DACs voltages must be written at the same time (serval constraint).
    • Two chips DACs voltages have PVs for setting values, but support for changing any of the 18 voltages can be added with new writeDac() rewrite.
      • Vthreshold_coarse
      • Vthreshold_fine
  • Another rewrite of the layout image rotation [not working, checking with ASI]
    • There are 8 possible image rotation modes
  • The Phoebus .bob screens are converted/created, but not yet included in the driver.

R0-9 (February 25, 2024)

  • Multiple raw streams (Serval 3.3.0 support)
    • raw can be .tpx3 file
    • raw1 can be a socket

R0-8 (February 25, 2024)

  • count_fb mode support added which was added originally in Serval 3.1
  • Chip loop update starts at chip1, since chip0
  • Initial work on Chip orientation control in FPGA
  • Measurement status values updated for interrupted acquisition
  • Serval 3.3.0 TDC: Before 3.3.0, one JSON record covered both TDC1 and TDC2; from 3.3.0 onward SERVAL exposes two separate JSON entries, and the driver uses separate PVs (and separate rate computations) for each TDC during image readout
  • Updated BPC / DACS to have default shorter path
  • Chip Voltage threshold coarse/fine setting opi and control
    • Douglas Araujo from ESS PR
    • Refactor DACs code to use asyn multidevice mechanism, using different asyn address for the chips
    • Initialize GraphicsMagick on class constructor
    • Fix RawStream PV type
  • Destructor changed from const to static const (code/API change)
  • TDC signals for one-chip TPX3 detector
  • Raw file streaming to tcp://connect@localhost:8085 enabled
  • ADCore commonPlugins.cmd settings
  • Preview image loop speed up
  • Preview[0] optional: The driver no longer crashes when Preview[0] is not enabled. SERVAL does not send preview images in this configuration, so the Phoebus preview display stays empty
  • Driver ensures that for Continuous mode ExposureTime (AcquireTime) propagates to TriggerPeriod (AcquirePeriod), must be equal to each other
  • Default reduce readout of preview images to not more than 1 per second
  • Remove diagnostic messages
  • Dashboard DiskSpace is empty until raw file writing enabled, and acquisition starts
  • Dashboard work updated
  • Startup update documents which channels to configure in the IOC (raw, preview/image, etc.)
  • Allow streaming of raw .tpx3 events; saving preview images to disk is not required; more consistent default channel settings

R0-7 (June 26, 2023)

  • Driver works for Serval 3.2 and Emulator 3.2
    • Separate TDC1 and TDC2 EventRate PVs in Serval 3.2
  • Performance issue resolved for reading preview images. Multiple connections were opening in callback while loop.
    • Used cpr library object called a Session is now used. Session is the only stateful piece of the cpr library.
    • Session object of cpr library is useful to hold on to state while reading preview images.
  • The preview images do not need to be written to disk, and are read from PrvImg Base [0] channel socket channel.
    • The preview is on Preview [1] channel, which does not have to enabled
  • Allow streaming of raw .tpx3 data.
    • Streaming: tcp://localhost:8085
    • Writing to .tpx3 file: file:/media/nvme/raw
  • More consistent settings for file writing and streaming channels in st_base.cmd
  • opi screens for fileWriter streaming enhancement
  • Continuous mode: ExposureTime (AcquireTime) used and propagates to TriggerPeriod (AcquirePeriod)
  • Preview[0] does not need to be enabled. Preview images are then not displayed.

R0-6 (March 30, 2023)

  • Driver works for one chip, in addition to four chips, and any number of chips
    • Status (temperature, ...) PVs exists for up to four chips
    • txp3Cam optical detector (one chip)
  • Changed PVs related to serval 3.0.0
    • Removed Detector chip Network Port, which does not exist in R3.0.0
    • ChipID is not part of the Detector Info Boards in R3.0.0
    • Humidity added
    • Detector orientation is part of Detector Layout
  • Prepopulate BPC and DACS calibration paths
  • Changed default port from 8080 to 8081 due to conflict with thinlinc
  • Tested with Serval 3.1.1

R0-4 (August 10, 2022)

  • Serval 2.3.6 only.
  • prepare for Serval 3.0.0

R0-3 (August 10, 2022)

  • Serval 2.3.6 only.
  • Removed restApi
  • Removed Param
  • Removed frozen
  • Uses nlohmann json
  • Uses cpr (Curl for humans)

R0-2 (August 3, 2022)

  • Serval 2.3.6 only.
  • frozen sources removed
  • Enhancements

R0-1 (July 26, 2022)

  • First release.
  • Serval 2.3.6 only
  • Additional controls in Serval 4.1.x (Stem/Measurement.Config implemented in R1-6)
    • Server->Measurement->Stem (Scan, Virtual Detector) - PVs and MeasurementConfig.bob in R1-6