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.
Driver / user-visible version 1.8.0 (see ADTIMEPIX_* in
ADTimePix.h).
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.
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 |
- 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/commondisplay 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.
- Add a pinned
epics-base/ci-scriptssubmodule 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
masterrefs; 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.
- 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.
- Replace overlapping fixed-size MaskBPC, BPC, and PixelConfig-difference
widgets with one dynamically sized widget per image. Rules based on
PixCount_RBVretain 256x256, 512x512, and 1024x512 raster support. - Restore a direct Verify BPC action on the PixelConfig mask panel while
preserving the existing
RefreshPixelConfigPV 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.
- 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=524288to 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
NELMTsetting from the TPX3 profile; current waveform capacities are controlled byXSIZE,YSIZE, andMASK_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=4chips across,NumberOfRows=512,NumberOfChips=8, andPixCount=524288. The isolated eight-chip path derives a 1024x512 raster, two chip rows, and a 256-pixel chip edge (65536PixelConfig 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.
- 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.
- Publish accumulated Img and PrvHst waveforms as
UINT64, current-frame count waveforms asULONG, Sum NDArrays asNDUInt64, and Average NDArrays as checkedNDUInt32; 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 atINT64_MAXinstead of allowing negative or implementation-defined conversion results. - Correct
PrvHstTotalCounts_RBVfromaitoint64in, without renaming it, so values remain integral and exact throughINT64_MAX. - Document that CA exposes unsigned-32 and 64-bit records as
DBF_DOUBLE, while PVA preservesuint[],ulong[], andlong. All supported last-N values remain integer-exact over CA because they are below2^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.
- Canonicalize an immutable startup
ADTIMEPIX_CALIBRATION_ROOTand 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 asPermissive: /; restrictive sites select one narrower subtree in the familyunique.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_ALLOWLISTbefore 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_ASGfields for calibration-path, calibration-load, and mask-upload controls. - Remove the unused legacy
initCamerahelper, 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.
- 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_DOUBLEprotocol view, while PVA reportedulong[]for accumulated waveforms,uint[]for current-frame waveforms, andlongforPrvHstTotalCounts_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 returnedOK. - 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 producedWRITE/INVALIDwith the path-exists readback set toNo; 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 policyPermissive: /, destination allowlistfile:/*,tcp://*,http://*, and destination policyPermissive. - 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.
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.
- Add one coordinator for the legal
Idle,Starting,Running,Stopping, andFaulttransitions and deriveADAcquire,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
Faultand an explicit stop retries reconciliation. - Add 22 deterministic transition, injected partial-start, concurrent
stop/fault, worker-readiness, fault-message, and Serval
Info: nullreconciliation 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.
- 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.
ADTPX3-CAN-011,ADTPX3-CAN-012, andADTPX3-CAN-015remain 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.
Driver / user-visible version 1.7.3 (see ADTIMEPIX_* in ADTimePix.h).
-
Release contents and traceability:
- The exact
R1-7-2..R1-7-3range 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
d081fe3removed TPX3-specific default macros from shared launcher shells; the other direct commits in the range are release-version bookkeeping.
- The exact
-
Serval request, file, and response hardening:
BiasEnabledand 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 (
bitDepthanddataSize, 8-, 16-, or 32-bit) and cross-checked against dimensions and any explicitpixelFormat; 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 callsfileWriter(),initAcquisition(),uploadBPC(), oruploadDACS(); 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, andApplyConfigare 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.Destinationunset and performed no automatic BPC or DACS upload. ExplicitApplyConfigrestored the preview destination, after which 30 frames were processed with zero drops and preview images updated.
- On a disconnected-to-connected transition,
-
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
ADStatusto 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 /
0x1fis 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, andOrientationlayout and fail closed when that layout is missing or unsupported. All eight Serval chip-orientation strings are supported, and a detector-orientation write refreshesLayout.Rotated.Chipsbefore 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
Yorigins are bottom-based while areaDetector image Y is top-based. The shared mapping convertsimage_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.
PixelConfigDiffcompares 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
UPimage assigns chips 2/3 to the top row withLtRTtB(identity) and 1/0 to the bottom row withRtLBtT(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
PixelConfigvalue 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.bpcanddetector-chips.jsonas example/test configuration. They are included undertest/fixtures/mpx3/eq-02/with provenance, integrity hashes, and a fixture-specific redistribution notice.
-
Rectangular mask geometry safety:
MaskReset,MaskRectangle, andMaskCirclenow use one checked row-majory * width + ximplementation 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.
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, wasMediPix3/MediPix3.bob),Mpx3Status.bob,Mpx3*acquire/detector panels.profiles/tpx4/— placeholder README.- Root launchers —
TimePix3.bob,MediPix3.bobembed profile mains with defaultP/Rmacros;MediPix3/MediPix3.bobshim keeps legacy bookmark paths. Emulator/— unchanged (family embed panels).- Layout guide:
tpx3App/op/bob/README.md. Legacyop/opi/(CS-Studio) not moved.
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 driverreadEnum(); removed invalidFTHS/FTVLfromMeasurement.template.- Parse
Measurement.Statusfrom GET/dashboard(flat JSON) and GET/measurement(Info.Status); do not overwrite idle state with Unknown when dashboardMeasurementis null after stop. - Default
PipelineStateto Unknown (-1) at driver init;RefreshConnectionat end of profileinit/detector.cmdscripts.
- Autosave (profile-specific):
- Split
auto_settings.reqinto TPX3 and MPX3 lists so TPX3 startup does not monitor MPX3-only plugin PVs. create_monitor_set: useset_requestfile_path("profiles/<family>")+ basenameauto_settings.reqso.savfiles land in./autosave/<family>/(not nestedprofiles/…paths).
- Split
- IOC boot — profile layout (Option C):
profiles/tpx3/,profiles/mpx3/, sharedcommon/st_core.cmd; thin launchersst.cmd/st_mpx3.cmd.- Legacy
init_detector*.cmdremain as shims; MPX3 plugins inprofiles/mpx3/plugins_mpx3.cmd. - Fix missing quote on
FileHDFImgT1inplugins_mpx3.cmd.
- File-plugin XML templates:
templates/hdf5/(NDFileHDF5hdf5_layout:hdf5_minimal.xml,hdf5_prvhst_histogram.xml) andtemplates/nexus/(NDFileNexusplugin_template.xml).- NDFileNexus templates isolated for possible ADCore deprecation in favour of NeXus-metadata HDF5 layouts.
- Vendor calibration layout:
vendor/tpx3/1x1/(wasoneChip/),vendor/tpx3/2x2/(demotpx3-demo.*),vendor/mpx3/unchanged,vendor/tpx4/placeholder.profiles/tpx3/init/paths.cmdupdated; runtimemask.bpcand*_masked_pels.jsonstill written under activeBPCFilePath.
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 usest.cmd/profiles/tpx3/andTimePix3.bob; MPX3 usesst_mpx3.cmd/profiles/mpx3/andMediPix3.bob(below). Prior TPX3-only releases remain valid for TPX3-only deployments (R1-6-3 and earlier). From R1-7-1, boot paths moved toprofiles/<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
thresholdIDon 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.
- IOC profile:
- TimePix3 (TPX3) — fixes in this release (behaviour unchanged when family is TPX3):
- Make
prvHstWorkerjoinable soacquireStopdoes not hang after Preview histogram streaming. - Enable NDStats row/column profile axes for PVA preview plots (
stats_profiles.cmd, Stats1 init, mosaicXSIZE/YSIZE).
- Make
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/cprrelease 1.14.2 intotpx3Support/cpr(headers undercpr/, implementation.cppfiles in parent directory). - Updated
tpx3Support/Makefileheader/source lists to the 1.14.2 file set (includes new units such asconnection_pool,curlmultiholder,multiperform,sse; removes obsoletebearer.cpp). - Added vendored
tpx3Support/cpr/cpr/cprver.hfor non-CMake EPICS builds (CPR 1.14.2 still includescpr/cprver.hfromcpr.h; upstream typically generates it via CMake).
- Synced vendored CPR sources from upstream
- Compiler baseline change for CPR >= 1.10:
- Switched driver/support builds to C++17 in
tpx3Support/Makefileandtpx3App/src/Makefile(USR_CPPFLAGS += -std=c++17).
- Switched driver/support builds to C++17 in
- Driver HTTP call cleanup after CPR upgrade:
- Shared CPR request helpers in
serval_http.h/ namespaceADTimePix3ServalHttp(serval_http.cpp); high-duplication GET/PUT sites (connection checks, config paths, measurement start/stop inacquire.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, andlogHttpWarningonADTimePix(implemented inserval_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::getAuthOnlysomask_io.cppstays consistent withserval_http.cpp). On HTTP status other than 200, each calllogHttpFailureand returnsasynError(previously these uploads often returnedasynSuccesseven when SERVAL reported an error).HttpCode/WriteFileMessage(or equivalent PVs) still reflect SERVAL response; check them when uploads fail.
- Shared CPR request helpers in
- 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(seedocumentation/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; runreuse lintfrom 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.mdfor contributor expectations on new files.
- Build validation:
- Full repository build (
make -j) completes successfully after upgrade.
- Full repository build (
- BPC naming consistency: Renamed
bcp2ImgIndextobpc2ImgIndex(BPC file index to image index). Masked-pels JSON export usesskipped_unmapped_bpc_index(wasskipped_unmapped_bcp_index). Fixed stray BCP typos in path-check comments. - Serval JSON shape parsing (
getDetector,getServer,fetchDacs):updateDetectorHealthFromJson()inserval_http.cpp: Maps GET/detectorHealthto temperature, humidity, andVDD/AVDDPVs by JSON shape (object for Serval 2/3, array for Serval 4 / multi-board), not byADSDKVersionalone. Multi-board behavior matches R1-6-2 (mergedChipTemperatures, dual-board rail PVs at asynADDR3-5). Logs and skips on unexpectedHealthtypes instead of throwing.fetchDacs(): Per-chipChipNTemperatureuseschipTemperatureFromHealthV4/V3depending on whetherHealthis an array or object.getServer(): Unwraps Serval 4.x{"Destination": {...}}before counting Raw / Image / Preview channels; missing or non-array keys count as zero (nojson::exceptionon partial responses).getDetector(): Guards optionalLayout/Original/Chips;try/catcharound JSON parse/update so malformed detector JSON logsgetDetector JSON errorand returnsasynErrorinstead of aborting the IOC (extends R1-6-2 HTTP/JSON robustness to the full detector refresh path).
- Connection status UX:
updateStatusFromConnection()setsDetectorState_RBV(ADStatus) to Disconnected when SERVAL or the detector is unreachable, with specificStatusMessage_RBVtext; restores Idle / Acquire when linked. Phoebus:ConnectionStatus.bob(SERVAL/detector LEDs, status line, Refresh);Acquire/ADCollect.bobshows enum labels (Idle, Disconnected, Error, ...) not raw integers (replaces unusedbob/Acquire/ADCollect.opi;TimePix3.bobembeds the.bob).ADSetup.bob(local fork): Ready / Not ready followDetConnected_RBV(notAsynIO.CNCT); Connect/Disconnect buttons still control the asyn port only (Asyn port label).ADSetup.bobandAcquire/ADCollect.bobuse 11 pt Sans and tighter widget spacing (rescaled from ADCore autoconvert 16 pt Liberation Sans) so they align with native TimePix3 OPI panels;TimePix3.bobembed heights and layout were adjusted accordingly. - IOC boot raw channel defaults (
init_detector_paths.cmd):RawFilePathdefault istcp://listen@localhost:8085(TCP stream);Raw1FilePathdefault isfile:/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 setRawFilePathexplicitly. - 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: updatesSDKVersion_RBV/ FW timestamp from/dashboard(updateServalVersionFromDashboardincheckConnection,getDashboard, and startup),getDetector(),getMeasurementConfig(), channel config (fileWriter/initAcquisition/getServer), and BPC/DACS upload when file names are configured.updateTdcRatesFromMeasurementInfo()inacquire.cppreadsTdc1EventRate/Tdc2EventRate/ legacyTdcEventRatefrom measurement JSON by field presence, not staleSDKVersion_RBV(fixesTdc1EvtRate_RBVstuck at zero and log spam when version wasunknownat IOC start).
-
IOC boot -- deployment-independent calibration paths:
profiles/tpx3/init/paths.cmdsetsBPCFilePathandDACSFilePathusing$(ADTIMEPIX)/vendor/tpx3/2x2/(withtpx3-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::parseon that body in several paths (writeDac,getHealth,initialServerCheckConnectiondashboard handling,timePixCallback/measurementpolling). That could throw an uncaughtjson::parse_errorand 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/FLOWhelpers use a singleADTPX3_FUNCmacro: 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 intpx3App/src/Makefile). Variadic*_ARGSmacros use##__VA_ARGS__so format-only calls (no extra printf args) compile. By defaultWARN/WARN_ARGSuseASYN_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_ERRORsoWARN*is emitted atASYN_TRACE_ERROR(see commented line intpx3App/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_RBVOPI: Implemented as a CHAR waveform (octet readback). Intpx3App/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)usingk = pelIndex(i,j)(same mapping as mask write /maskCircle), notbpc2ImgIndex--those two were not equivalent for all quad orientations (e.g. LEFT), which broke alignment at chip boundaries. SameNELEMENTSasBPC/MaskBPCinMaskBPC.template. Phoebus:Mask/Mask.bobembedsPixelConfigMaskPanel.bob(refresh, table, 512x512 / 256x256 |Delta| heatmaps). MaskBPCread from.bpc: Loading the mask image from disk usespelIndex(i,j)andj*COLS+i(clearsvalue[]first), matching mask write andPixelConfigDiff;bpc2ImgIndexis no longer used on that path.- EPICS / asyn fixes (R1-6-2):
TPX3_PIXEL_CONFIG_DIFFregistered asasynParamInt32Array;doCallbacksInt32Arraypushes the full diff buffer (notPixCount).RefreshPixelConfigFLNK ->PixelConfigDiff.PROCso the waveform VAL updates on process (same idea as readingBPC/MaskBPC). Compared length usesmin(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:
bpc2ImgIndexquad-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. NowbpcIndex / chipPelCount(for remainingbpc2ImgIndexcallers).
- Trigger:
-
Eight-chip / dual SPIDR (IOC, DB, driver, mask indexing):
- IOC:
iocs/tpx3IOC/iocBoot/iocTimePix/load_chips.cmdloadsChips.templateforCHIP0...CHIP7(asynADDR0-7);st_base.cmdsources it.OperatingVoltage.templateextended withPwr3...Pwr5atADDR3-5 for the second board's threeVDD/AVDDrails (see driver). MASK_BPC_NELEMENTS:MaskBPC.templaterequires macroMASK_BPC_NELEMENTS(must be >= PixCount). It is set inunique.cmdwith documented choices 65536 (1 chip), 262144 (4 chip), 524288 (8 chip). If undefined, iocsh failsdbLoadRecordsforMaskBPC.templateand mask PVs stay disconnected.envPathsonly notes thatunique.cmdmust define it.- Driver (
getDetector, Serval 4): Merges allHealth[].ChipTemperaturesinto one flat JSON array forChipTemps_RBV; with twoHealthblocks,VDD_RBV/AVDD_RBVstrings become a JSON array of per-board rail arrays; fillsTPX3_CHIP_VDD/TPX3_CHIP_AVDDatADDR3-5 fromHealth[1](zeros when single board).Info.Boards[1]->TPX3_BOARDS2_ID,TPX3_BOARDS2_IP,TPX3_BOARDS_CH5...CH8(second SPIDR chip JSON). Safer parsing whenBoardsorChipsarrays are short. - Database:
ADTimePix3.template--BChBoard2Id_RBV,IpAddr2_RBV,Chip5_RBV...Chip8_RBV. New asyn parameter names inADTimePix.h/createParam. - Mask / BPC (
mask_io.cpp): FornumChips == 8and DetectorOrientation UP (0) only,pelIndexandbpc2ImgIndexuse a rectangular mosaic withchip = Y_CHIP * xChips + X_CHIPfromrowsCols(); intra-chip order matches single-chip UP. Other orientations for eight tiles remain TODO (verify on hardware vs ServalLayout). - Documentation:
documentation/8chip-migration.md; README anddocumentation/MIGRATION_SUPPORT2.mdupdated (MASK_BPC_NELEMENTSchecklist, links). - Phoebus / OPI (8-chip UX):
TimePix3Detector.bobembedsCHIP0...CHIP7(operator-adjustable layout);Acquire/DetectorConfig.bobadds Vth panels forCHIP4...CHIP7;Acquire/ImgAccumulation.bob,Mask/PixelConfigMaskPanel.bob, andMask/Mask.bobadd 1024x512 image variants whenPixCount_RBVmatches the 8-chip mosaic (524288);Detector/TimePixDetectorVoltages.bob(Display Builder,op/bob/Detector) orTimePixDetectorVoltages.opi(legacy BOY,op/opi/Detector) lists second-board railsPwr3...Pwr5;Detector/TimePixDetectorHealth.bobprovides summary health with cross-links to voltages. - IOC hardware init (calibration push):
iocs/tpx3IOC/iocBoot/iocTimePix/init_detector_hw.cmdnow documents thatWriteBPCFile=1andWriteDACSFile=1trigger driveruploadBPC()/uploadDACS()calls to SERVAL/config/load(using paths frominit_detector_paths.cmd), with troubleshooting notes forHttpCode,WriteFileMessage, and detector/SERVAL readiness.
- IOC:
-
Phoebus histogram InfoDisplay layout tweak: Manually adjusted the layout in
tpx3App/op/bob/Acquire/PrvHstHistogram.bobso InfoDisplay text fits properly (increased container/text height). -
Masked pels JSON export (
RefreshPixelConfig): When a BPC file is read successfully duringRefreshPixelConfig, the driver writes<BPCFilePath><stem>_masked_pels.json(stem =BPCFileNamewith a trailing.bpcremoved, case-insensitive) containingformat_version,source, optionaldetector/acquisition,masked_pels(BPC index, chip,lx/ly, imagei/jviabpc2ImgIndex), andBad pixels(median 1x1) for NDPluginBadPixel. Readbacks:TPX3_MASKED_PELS_JSON_RBV,TPX3_MASKED_PELS_COUNT_RBV,TPX3_MASKED_PELS_EXPORT_STATUS_RBV(File.templateasMaskedPelsJson_RBV, etc.). Phoebus:op/bob/Mask/PixelConfigMaskPanel.bobshows count / status / path;Mask.bobembedded panel height updated to 920 px. Seedocumentation/MASKED_PIXELS_JSON_AND_STREAMING.md.
- 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
ImgImageDataandImgImageSumNFramescan 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=2or3receive 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 fromimgRunningSum_and the sum-of-N buffer, optionally converts to average (divide byimgAccumulatedFrameCount_or by N for sum-of-N), and callsdoCallbacksGenericPointer(..., 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. NewimgAccumulatedFrameCount_tracks frames in the running sum for the average calculation. - Database: New records in
Server.templateforWriteProcessedImgandProcessedImgOutputType(DESC fields kept <=40 characters). - Phoebus:
ImgAccumulation.bob- added "Push to file (addr 2,3)" button and "Output type" combo (Sum / Average). Usescombowidget 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 fromprocessImgFramewhen Img accumulation is enabled;WriteProcessedImgis an additional on-demand push with Sum/Average typing. Documented thatImgImageFramehas no NDArray address (use address 1 for single-frame file saving), optional HDF5dbLoadRecordsone-line iocsh note, and a short verification tip (mean ratio addr 3 vs 1 ~ N). - Validation procedure/results: Added a reproducible single-plugin runtime
NDArrayAddressverification section (HDF5 and TIFF) indocumentation/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(NDFileHDF5hdf5_layout) andiocs/tpx3IOC/iocBoot/iocTimePix/templates/nexus/plugin_template.xml(NDFileNexusNXroottemplate, validated with ADCoreXML_schema/template.sch). README documents that HDF5 and Nexus plugins use different XML dialects, template PVs, andTemplateFilePathconcatenation rules. - Readout stack diagram:
documentation/TimePix3_pipeline_48_64_96_caption.png(PNG) anddocumentation/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,
processPrvHstFramepushes 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 toPrvHstHistogramTimeMs). Arrays on 4 and 5 add NDAttributesPrvHstTimeBin0Ms,PrvHstTimeBinStepMs,PrvHstNumBins(uniform axis metadata).WriteProcessedHst/ProcessedHstOutputTypemirror processed Img: one-shot push with Sum (NDInt64) vs Average (NDInt32, divide by frame count or sum-of-N buffer length).pushProcessedHstToPlugins()inADTimePix.cpp;ADDriver(..., maxAddr=8, ...)so lists 0-7 exist. Records inServer.template. Seedocumentation/PROCESSED_IMAGE_FILE_SAVING.mdand README Histogram sections.
- 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
- 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 writepath indocumentation/PROCESSED_IMAGE_FILE_SAVING.md. Clarifies thatNDWriteFilerequires at least one latched NDArray on the selected plugin address, and adds a minimal check sequence forArrayCallbacks,HDF1:NDArrayAddress, andWriteProcessedHst. - PV naming clarification for callbacks: Updated docs to distinguish EPICS PV
$(P)$(R)ArrayCallbacks/_RBVfrom internal driver/asyn parameterNDArrayCallbacks, avoiding "channel not found" confusion when testing from CA clients. - Phoebus histogram plot artifact fix: Updated
tpx3App/op/bob/Acquire/PrvHstHistogram.bobXY traces to points-only rendering (no line interpolation) to avoid line-to-origin artifacts when waveformNELMexceeds validNORD.
- 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
ADTimePixDetConnectedlogic ininitialServerCheckConnection(): 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/dashboardas the single source of truth and updates onlyServalConnected_RBV,DetConnected_RBV,ADStatusMessage, and (when connected)DetType/ADModel. ServalConnected is 1 when GET/dashboardreturns 200 (SERVAL reachable even when the root URL returns 404/302). DetConnected is 1 only when the dashboard JSON hasDetectornon-null. It does not callgetServer()or fullgetDashboard(). - Consistent connection status in getDashboard():
getDashboard()(Health PV path) now setsServalConnected_RBVandDetConnected_RBVthe same way ascheckConnection(): ServalConnected=1 when GET/dashboardreturns 200; DetConnected=1 only when the dashboard JSON hasDetectornon-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 runscheckConnection()and updates connection status. Record inDashboard.template. - Periodic connection poll: A low-priority thread runs every 5 seconds (default), calls
checkConnection(), and on transition from disconnected to connected optionally callsgetServer()once to refresh channel config. NoacquireStop()orinitCamera()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
ADStatusMessageis set to "SERVAL or detector disconnected". - Behavior on reconnect: Status PVs are set to connected,
ADStatusMessageis cleared to "OK", and channel config is re-applied by callingfileWriter()(push current PV config to SERVAL) thengetServer()(refresh PVs from SERVAL). Detector initialization (BPC/DACS load,initCamera()) is not run on reconnect.
- Bug fix - DetConnected inversion: Corrected
- 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 byWriteData=1orApplyConfig).- init_detector.cmd: The detector init block (formerly inline in
st_base.cmd) is now iniocs/tpx3IOC/iocBoot/iocTimePix/init_detector.cmd.st_base.cmdsources it afteriocInit(). 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 runsfileWriter()+getServer()(same effect asWriteData=1), so operators can re-apply current PV config to SERVAL without toggling WriteData or re-running a script. Record inDashboard.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), thengetServer()(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.cmdorst_base.cmd); the driver applies those PVs to SERVAL whenWriteData=1or whenApplyConfigis triggered.
- init_detector.cmd: The detector init block (formerly inline in
- Code Organization - BPC/mask logic in mask_io.cpp: Moved
checkBPCPath()anduploadBPC()fromADTimePix.cpptomask_io.cppto shorten the main driver file and keep all BPC/mask path and upload logic in one place.mask_io.cppalready containedreadBPCfile(),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.
- Stem (4D-STEM):
- 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.templatefor all eight parameters (setpoint + _RBV readback where applicable). - Phoebus screen: New
Measurement/MeasurementConfig.bobscreen (4D-STEM and ToF sections) with spinners/text entries and readbacks. Embedded inTimePix3Detector.bobbelow 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.
- New:
- Bug fix - Memory leaks:
- BPC buffer (
mask_io.cpp):readBPCfile()allocates a buffer withmalloc()and passes it to the caller. The buffer was never freed inreadInt32Array(), leaking memory on every mask/BPC read or write. The buffer is now freed beforereadInt32Array()returns (andbufBPCis initialized toNULL). - Histogram NDArray (
histogram_io.cpp): WhenpNDArrayPool->alloc()returned a non-null array with nullpData, the array was not released, leaking a pool reference. The failure path now callspHistArray->release()whenpHistArrayis non-null.
- BPC buffer (
- Database:
Measurement.template-TofTdcReferencestringout record uses device supportasynOctetWrite(notasynOctet) sodbLoadRecordsdoes 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 lowercasedbfolder, so save_restore finds the.reqfiles (e.g.sseq_settings.req,sseqRecord_settings.req).
-
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-previewbranch 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
PrvHstAccumulationEnablecontrol (similar toImgAccumulationEnable) 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 dataPrvHstHistogramSumNFrames(INT64): Sum of last N framesPrvHstHistogramTimeMs(DOUBLE): Time-of-Flight axis in milliseconds (bin centers)
-
Phoebus Screen for Histogram Plotting: Updated
PrvHstHistogram.bobscreen 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.InterruptedExceptionerrors 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
tpx3imageIOC into the ADTimePix3 driver's Img channel. New features include:- Running Sum Accumulation: 64-bit accumulation of pixel values over all frames via
ImgImageDataPV (INT64 waveform array) - Current Frame Display: Individual frame data via
ImgImageFramePV (INT32 waveform array) - Sum of Last N Frames: Configurable sum of last N frames (default: 10) via
ImgImageSumNFramesPV (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
ImgTotalCountsPV (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) andImgSumUpdateInterval(1-10000, default: 1 frame) - Phoebus Screen: Updated
ImgAccumulation.bobscreen (located inAcquire/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
- Running Sum Accumulation: 64-bit accumulation of pixel values over all frames via
-
Bug Fix - Image Accumulation Parameter Update: Fixed critical bug in
writeInt32()handler where condition for bias/trigger parameters (line 2795) was missingfunction ==comparisons for subsequent terms, causing all writeInt32 calls to be intercepted and preventingImgFramesToSumparameter updates from being processed. The buffer size now correctly updates whenImgFramesToSumPV 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
NDDataTypetoNDInt64(value 8), but theDataType_RBVdatabase record enum only supports values 0-5, causing "Illegal Value" status. The driver now preserves the previousNDDataTypevalue and does not set it for histogram data. The NDArray itself still correctly usesNDInt64data 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_RBVwas 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 sharedNDArrayCounter, causing double counting. The driver now only incrementsNDArrayCounterin the Img channel (main acquisition), not in PrvImg channel (preview).ArrayRate_RBVnow correctly reflects the main Img channel rate. Preview channel rate is available viaPrvImgAcqRate_RBVPV. 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, usingtcp://listen@localhost:8089andhttp://localhost), not in the actual image channel (TPX3-TEST:cam1:ImgFilePath). The histogram channel was callingcallParamCallbacks()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. Seedocumentation/PVA_FLICKERING_DIAGNOSIS.mdfor detailed analysis and diagnostic steps. -
Optimization - Histogram Processing When Accumulation Disabled: Optimized histogram data processing to skip all processing (including rate calculation) when
PrvHstAccumulationEnableis 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 fromprocessPrvHstDataLine()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
PrvHstAccumulationEnablewas 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
PrvHstDataResetPV (boolean output) to allow manual reset of accumulated histogram data. This one-shot button resetsPrvHstFrameCount_RBV,PrvHstTotalCounts_RBV, clearsPrvHstHistogramDataandPrvHstHistogramSumNFrameswaveform 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 thePrvHstHistogram.bobscreen 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, andPrvHstTotalTimeMs_RBVthat 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 withCP(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
NumImagesPV showed INVALID status with value 100000000 (100 million) at IOC startup. The ADDriver base class was initializingNumImagesto a very large default value, causing INVALID status. The driver now initializesNumImagesto 0 (unlimited) in the constructor, which is appropriate for continuous mode and prevents the INVALID status. For single mode (ImageMode = 0), the driver automatically setsNumImages = 1when switching to single mode. Bug Fix - NumImages WRITE INVALID in single mode: When the database or a client wrote a value other than 1 toNumImageswhile 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_RBVwas approximately twiceNumImagesCounter_RBVwhen jsonhisto streaming was enabled. The histogram channel (PrvHst, address 5) was callingdoCallbacksGenericPointer(), which automatically increments the sharedNDArrayCounterparameter. Since histogram uses a separate NDArray address (5) and should not affect the image channel counter, the driver now saves and restoresNDArrayCounteraround histogram callbacks to prevent histogram from incrementing it.ArrayCounter_RBVnow correctly reflects only image frame counts, matchingNumImagesCounter_RBVwhen 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 usesmaxAddr=6so 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_bswap32for 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.
- 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
- 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
-
- 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.
- Updated documentaiton
- Attempt at rotating images using DetectorOrientation in Layout
- 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
- Two chips DACs voltages have PVs for setting values, but support for changing any of the 18 voltages can be added with new
- 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.
- Multiple raw streams (Serval 3.3.0 support)
- raw can be .tpx3 file
- raw1 can be a socket
- 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
consttostatic 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
.tpx3events; saving preview images to disk is not required; more consistent default channel settings
- 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.
- 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
- Serval 2.3.6 only.
- prepare for Serval 3.0.0
- Serval 2.3.6 only.
- Removed restApi
- Removed Param
- Removed frozen
- Uses nlohmann json
- Uses cpr (Curl for humans)
- Serval 2.3.6 only.
- frozen sources removed
- Enhancements
- 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