dt5215 1.0.1__tar.gz

dt5215-1.0.1/.gitignore

@@ -0,0 +1,51 @@
+# build outputs
+output/
+site/
+build/
+dist/
+.ci-build/
+*.egg-info/
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+venv/
+
+# C / C++
+sdk/c/build/
+sdk/cpp/build/
+*.o
+*.a
+*.so
+*.so.*
+*.dll
+*.lib
+*.exe
+
+# Go
+sdk/go/build/
+
+# .NET
+sdk/dotnet/**/bin/
+sdk/dotnet/**/obj/
+
+# Node
+node_modules/
+sdk/node/dist/
+
+# Java
+sdk/java/target/
+.m2/
+
+# conformance
+ci-test/report/
+
+# editors
+.vscode/
+.idea/
+*.swp
+
+# generated by the build and packaging scripts
+tars/
+packaging/windows/staging/
+staging/

dt5215-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nuclear Instruments SRL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dt5215-1.0.1/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.5
+Name: dt5215
+Version: 1.0.1
+Summary: Control SDK of the Nuclear Instruments / CAEN DT5215 FERS concentrator: HTTP/JSON over Ethernet
+Project-URL: Homepage, https://www.nuclearinstruments.eu
+Project-URL: Documentation, https://downloads.nuclearinstruments.eu/package/dt5215-control-sdk
+Project-URL: Source, https://gitlab.nuclearinstruments.eu/public-repo/fers/dt5215-control-sdk
+Author: Nuclear Instruments
+License-Expression: MIT
+License-File: LICENSE
+Keywords: caen,concentrator,daq,dt5215,fers,nuclear instruments,scintillator,sipm,tdlink
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.8
+Provides-Extra: test
+Requires-Dist: dt5215-emulator; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# DT5215 Control SDK — Python
+
+The control and monitoring API of the **DT5215** FERS concentrator, in Python, with no
+dependencies: the standard library is enough.
+
+```bash
+pip install dt5215
+```
+
+```python
+import dt5215
+
+with dt5215.connect("192.168.0.10", username="user", password="user") as dev:
+    info = dev.info()
+    print(info.hostname, info.info.sw_release)
+
+    for chain in dev.chains.status().enabled:
+        print("chain", chain.chain, chain.board_count, "boards",
+              "%.1f Mbps" % chain.mbps)
+
+    for board in dev.chains.links().boards:
+        print(board.id, board.name, board.tempBoard, "C", board.hv_Vmon, "V")
+```
+
+Python 3.8 and later, on Linux, Windows and macOS.
+
+## What is in it
+
+Everything the instrument's web interface can do, grouped the way the API is grouped:
+
+| | |
+|---|---|
+| `dev.info()` `dev.alive()` `dev.error_flags()` `dev.leds()` `dev.reboot()` | identity, health, front panel, life cycle |
+| `dev.chains` | the 8 TDlink chains: status, enumeration, the boards on them, heatmaps |
+| `dev.boards` | the FERS boards: registers, HV, firmware upgrade over TDlink |
+| `dev.io` | the front panel: LEMO direction and function, sync matrix, test pulse |
+| `dev.clock` | the master PLL, the DDMTD phase detectors, the link phase |
+| `dev.network` | the LAN, 10 GbE and USB interfaces, and their traffic |
+| `dev.time` | the GPS receiver, the system clock, systemd-timesyncd |
+| `dev.system` | the log, the debug counters, the configuration file |
+| `dev.raw` | any endpoint, including one a newer firmware adds before this SDK names it |
+
+Event data is **not** here: it leaves the instrument over the binary streaming sockets that
+Janus and FERSlib speak. This SDK is the control plane.
+
+## Three things worth knowing
+
+**The firmware answers HTTP 200 with `result: false`.** A client that only reads the status
+code believes every refusal succeeded. This SDK checks the body and raises `DeviceError`
+with the instrument's own message — including the configuration validator's list of
+complaints, which is otherwise hidden behind "configuration validation failed".
+
+**Tokens expire** (7 days), and restarting the bridge application throws them all away. Pass
+`username`/`password` and the SDK logs in when it needs to, notices a 401, logs in again and
+retries the request once. `dev.alive()` is the one operation that answers without a token:
+call it to tell "the instrument is down" from "my token is stale".
+
+**Some operations take minutes.** `chains.rescan()` runs the whole enumeration and blocks
+until it is over. To follow it instead:
+
+```python
+dev.chains.rescan_async()
+status = dev.chains.wait_enumeration(on_progress=lambda s: print(s.progress, "%"))
+print(dev.chains.enumeration_log())
+```
+
+The same shape works for the board firmware upgrade:
+
+```python
+info = dev.boards.fw_upload("firmware.ffu")      # what the file holds, and for which models
+dev.boards.fw_start(dev.chains.links().boards)   # Board, BoardRef, (chain, node) or "0:1"
+status = dev.boards.wait_fw_upgrade(on_progress=lambda s: print(s.overall, "%"))
+```
+
+## Errors
+
+Six kinds, all deriving from `dt5215.Dt5215Error`:
+
+| | |
+|---|---|
+| `ConnectionError` | the instrument cannot be reached |
+| `Timeout` | the request went out and no reply came in time |
+| `DeviceError` | the instrument refused: `result: false`, or a 4xx/5xx |
+| `AuthError` | 401: no token, wrong credentials, expired token |
+| `NotSupported` | this firmware does not have the endpoint |
+| `InvalidArgument` | a parameter is wrong — **nothing was sent** |
+
+```python
+try:
+    dev.boards.write_register(0, 1, 0x1000, 0x42)
+except dt5215.InvalidArgument as e:
+    print("my mistake, in parameter", e.name)
+except dt5215.DeviceError as e:
+    print("the instrument said no:", e.reason)
+```
+
+## Typed results, and the fields the SDK does not know yet
+
+Every result is a dataclass, so the editor can complete it and `mypy` can check it. Every
+result also keeps the dictionary it came from:
+
+```python
+info = dev.info()
+info.network.ten_giga.mtu          # typed
+info.raw["info"]["sysversion"]     # anything, including a field added by a newer firmware
+```
+
+## HTTPS
+
+The instrument serves plain HTTP today; HTTPS is coming and the SDK side is ready:
+
+```python
+dev = dt5215.connect("https://dt5215.lan", username="user", password="user",
+                     tls=dt5215.Tls(ca_file="/etc/ssl/ni-ca.pem"))
+```
+
+`Tls` carries the CA bundle, a client certificate for mutual TLS, and `insecure=True` for a
+self-signed certificate on a closed network. The default port follows the scheme and
+verification is **on** by default. No operation knows which scheme it is on, so nothing else
+changes the day the firmware serves TLS.
+
+## From the shell
+
+The package installs a `dt5215` command:
+
+```bash
+dt5215 --host 192.168.0.10 info
+dt5215 chains
+dt5215 boards
+dt5215 health
+dt5215 rescan --log
+dt5215 watch --interval 2
+dt5215 get /get_pll
+dt5215 post /set_board_sync '{"master_slave": 0, "clk_source": 1}'
+```
+
+`DT5215_HOST`, `DT5215_USER`, `DT5215_PASSWORD` and `DT5215_TOKEN` fill in what you leave out.
+
+## Without an instrument
+
+```bash
+pip install dt5215-emulator
+dt5215-emulator --port 8080
+DT5215_HOST=127.0.0.1:8080 dt5215 info
+```
+
+The emulator answers the whole API, statefully, and reproduces the firmware's quirks on
+purpose. It is what this SDK's own tests run against.
+
+## Examples
+
+`examples/` has twelve, numbered in the order they are worth reading, from
+`01_connect_and_info.py` to `12_raw_endpoint.py`. They all take `DT5215_HOST`,
+`DT5215_USER` and `DT5215_PASSWORD` from the environment, and they are part of the test
+suite — an example that does not run is documentation that lies.
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+They run against the emulator, so no instrument is needed.

dt5215-1.0.1/README.md

@@ -0,0 +1,164 @@
+# DT5215 Control SDK — Python
+
+The control and monitoring API of the **DT5215** FERS concentrator, in Python, with no
+dependencies: the standard library is enough.
+
+```bash
+pip install dt5215
+```
+
+```python
+import dt5215
+
+with dt5215.connect("192.168.0.10", username="user", password="user") as dev:
+    info = dev.info()
+    print(info.hostname, info.info.sw_release)
+
+    for chain in dev.chains.status().enabled:
+        print("chain", chain.chain, chain.board_count, "boards",
+              "%.1f Mbps" % chain.mbps)
+
+    for board in dev.chains.links().boards:
+        print(board.id, board.name, board.tempBoard, "C", board.hv_Vmon, "V")
+```
+
+Python 3.8 and later, on Linux, Windows and macOS.
+
+## What is in it
+
+Everything the instrument's web interface can do, grouped the way the API is grouped:
+
+| | |
+|---|---|
+| `dev.info()` `dev.alive()` `dev.error_flags()` `dev.leds()` `dev.reboot()` | identity, health, front panel, life cycle |
+| `dev.chains` | the 8 TDlink chains: status, enumeration, the boards on them, heatmaps |
+| `dev.boards` | the FERS boards: registers, HV, firmware upgrade over TDlink |
+| `dev.io` | the front panel: LEMO direction and function, sync matrix, test pulse |
+| `dev.clock` | the master PLL, the DDMTD phase detectors, the link phase |
+| `dev.network` | the LAN, 10 GbE and USB interfaces, and their traffic |
+| `dev.time` | the GPS receiver, the system clock, systemd-timesyncd |
+| `dev.system` | the log, the debug counters, the configuration file |
+| `dev.raw` | any endpoint, including one a newer firmware adds before this SDK names it |
+
+Event data is **not** here: it leaves the instrument over the binary streaming sockets that
+Janus and FERSlib speak. This SDK is the control plane.
+
+## Three things worth knowing
+
+**The firmware answers HTTP 200 with `result: false`.** A client that only reads the status
+code believes every refusal succeeded. This SDK checks the body and raises `DeviceError`
+with the instrument's own message — including the configuration validator's list of
+complaints, which is otherwise hidden behind "configuration validation failed".
+
+**Tokens expire** (7 days), and restarting the bridge application throws them all away. Pass
+`username`/`password` and the SDK logs in when it needs to, notices a 401, logs in again and
+retries the request once. `dev.alive()` is the one operation that answers without a token:
+call it to tell "the instrument is down" from "my token is stale".
+
+**Some operations take minutes.** `chains.rescan()` runs the whole enumeration and blocks
+until it is over. To follow it instead:
+
+```python
+dev.chains.rescan_async()
+status = dev.chains.wait_enumeration(on_progress=lambda s: print(s.progress, "%"))
+print(dev.chains.enumeration_log())
+```
+
+The same shape works for the board firmware upgrade:
+
+```python
+info = dev.boards.fw_upload("firmware.ffu")      # what the file holds, and for which models
+dev.boards.fw_start(dev.chains.links().boards)   # Board, BoardRef, (chain, node) or "0:1"
+status = dev.boards.wait_fw_upgrade(on_progress=lambda s: print(s.overall, "%"))
+```
+
+## Errors
+
+Six kinds, all deriving from `dt5215.Dt5215Error`:
+
+| | |
+|---|---|
+| `ConnectionError` | the instrument cannot be reached |
+| `Timeout` | the request went out and no reply came in time |
+| `DeviceError` | the instrument refused: `result: false`, or a 4xx/5xx |
+| `AuthError` | 401: no token, wrong credentials, expired token |
+| `NotSupported` | this firmware does not have the endpoint |
+| `InvalidArgument` | a parameter is wrong — **nothing was sent** |
+
+```python
+try:
+    dev.boards.write_register(0, 1, 0x1000, 0x42)
+except dt5215.InvalidArgument as e:
+    print("my mistake, in parameter", e.name)
+except dt5215.DeviceError as e:
+    print("the instrument said no:", e.reason)
+```
+
+## Typed results, and the fields the SDK does not know yet
+
+Every result is a dataclass, so the editor can complete it and `mypy` can check it. Every
+result also keeps the dictionary it came from:
+
+```python
+info = dev.info()
+info.network.ten_giga.mtu          # typed
+info.raw["info"]["sysversion"]     # anything, including a field added by a newer firmware
+```
+
+## HTTPS
+
+The instrument serves plain HTTP today; HTTPS is coming and the SDK side is ready:
+
+```python
+dev = dt5215.connect("https://dt5215.lan", username="user", password="user",
+                     tls=dt5215.Tls(ca_file="/etc/ssl/ni-ca.pem"))
+```
+
+`Tls` carries the CA bundle, a client certificate for mutual TLS, and `insecure=True` for a
+self-signed certificate on a closed network. The default port follows the scheme and
+verification is **on** by default. No operation knows which scheme it is on, so nothing else
+changes the day the firmware serves TLS.
+
+## From the shell
+
+The package installs a `dt5215` command:
+
+```bash
+dt5215 --host 192.168.0.10 info
+dt5215 chains
+dt5215 boards
+dt5215 health
+dt5215 rescan --log
+dt5215 watch --interval 2
+dt5215 get /get_pll
+dt5215 post /set_board_sync '{"master_slave": 0, "clk_source": 1}'
+```
+
+`DT5215_HOST`, `DT5215_USER`, `DT5215_PASSWORD` and `DT5215_TOKEN` fill in what you leave out.
+
+## Without an instrument
+
+```bash
+pip install dt5215-emulator
+dt5215-emulator --port 8080
+DT5215_HOST=127.0.0.1:8080 dt5215 info
+```
+
+The emulator answers the whole API, statefully, and reproduces the firmware's quirks on
+purpose. It is what this SDK's own tests run against.
+
+## Examples
+
+`examples/` has twelve, numbered in the order they are worth reading, from
+`01_connect_and_info.py` to `12_raw_endpoint.py`. They all take `DT5215_HOST`,
+`DT5215_USER` and `DT5215_PASSWORD` from the environment, and they are part of the test
+suite — an example that does not run is documentation that lies.
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+They run against the emulator, so no instrument is needed.

dt5215-1.0.1/examples/01_connect_and_info.py

@@ -0,0 +1,40 @@
+"""Connect, and print what the instrument is.
+
+The first thing to run against a new unit: it proves the address, the credentials and the
+firmware all line up.
+"""
+
+from _common import open_device
+
+
+def main():
+    with open_device() as dev:
+        alive = dev.alive()
+        print("instrument up for {} s (application instance {})".format(
+            alive.uptime_seconds, alive.instance_id))
+
+        info = dev.info()
+        print("hostname   {}".format(info.hostname))
+        print("PID        {} (PCB rev {})".format(info.pid, info.pcb_revision))
+        print("software   {}".format(info.info.sw_release))
+        print("FPGA       {}".format(info.info.fw_fpga_release))
+        print("logged in as {}".format(info.user))
+
+        print("\nnetwork")
+        print("  LAN     {} (configured {}, dhcp {})".format(
+            info.network.lan.current_ip, info.network.lan.ip, info.network.lan.dhcp))
+        print("  10 GbE  {} (enabled {}, mtu {})".format(
+            info.network.ten_giga.current_ip, info.network.ten_giga.enable,
+            info.network.ten_giga.mtu))
+
+        print("\nsensors")
+        for sensor in info.temperatures:
+            print("  {:<12} {:>8.2f} {}".format(sensor.text or sensor.name,
+                                                sensor.value, sensor.unit))
+
+        flags = dev.error_flags()
+        print("\nhealth: {}".format("ok" if flags.ok else "FAULT"))
+
+
+if __name__ == "__main__":
+    main()

dt5215-1.0.1/examples/02_chains_and_boards.py

@@ -0,0 +1,42 @@
+"""What is connected: the eight TDlink chains and the boards on them."""
+
+from _common import open_device
+from dt5215 import ChainStatus
+
+
+def main():
+    with open_device() as dev:
+        status = dev.chains.status()
+        print("chain  state      boards      Mbps      ev/s   SFP")
+        for chain in status.chains:
+            state = getattr(ChainStatus.of(chain.chain_status), "name", "?").lower()
+            print("  {}    {:<9} {:>6} {:>9.2f} {:>9.0f}   {}".format(
+                chain.chain, state, chain.board_count, chain.mbps, chain.evps,
+                chain.sfp.vendor_pn or ("present" if chain.sfp.present else "-")))
+            if chain.los or chain.fault:
+                print("       loss of signal: {}, transmitter fault: {}".format(
+                    chain.los, chain.fault))
+
+        print("\ntotal {:.2f} Mbps, event builder buffer {}%".format(
+            status.total_mbps, status.event_builder.get("output_buffer_status", "?")))
+
+        links = dev.chains.links()
+        print("\n{} board(s)".format(len(links.boards)))
+        for board in links.boards:
+            faults = ", ".join(board.status.faults) or "-"
+            print("  {:<6} {:<6} PID {:<7} fw {:<6} {:>5.1f} C  HV {:>5.1f} V  {}".format(
+                board.id, board.name, board.pid, board.fwVersion, board.tempBoard,
+                board.hv_Vmon, faults))
+
+        # the per-channel count map of the first board, as an 8-wide grid
+        if links.boards:
+            first = links.boards[0]
+            heatmap = dev.chains.heatmap(first.chain, first.node)
+            print("\nheatmap of {} ({} x {}):".format(heatmap.board, heatmap.rows,
+                                                      heatmap.columns))
+            for row in heatmap.grid():
+                print("  " + " ".join("{:>6.0f}".format(v) for v in row))
+
+
+if __name__ == "__main__":
+    main()

dt5215-1.0.1/examples/03_enumerate.py

@@ -0,0 +1,42 @@
+"""Enumerate the chains and watch it happen.
+
+``chains.rescan()`` blocks for minutes, so this starts it with ``rescan_async()`` and polls
+the status — which is also how you drive a progress bar in a GUI.
+"""
+
+from _common import open_device
+from dt5215 import EnumPhase
+
+
+def main():
+    with open_device() as dev:
+        # enable the chains that are cabled; a chain left out of the mapping is disabled
+        dev.chains.set_enabled({0: True, 1: True})
+
+        print("starting the enumeration")
+        dev.chains.rescan_async()
+
+        last = ""
+
+        def show(status):
+            nonlocal last
+            phase = getattr(EnumPhase.of(status.phase), "name", "?").lower()
+            line = "  attempt {}  {:<12} {:>3.0f}%  chain {}".format(
+                status.attempt, phase, status.progress,
+                status.current_chain if status.current_chain >= 0 else "-")
+            if line != last:
+                print(line)
+                last = line
+
+        status = dev.chains.wait_enumeration(timeout=300.0, poll=0.5, on_progress=show)
+        print("FAILED" if status.failed else "done")
+
+        print("\n--- enumeration log ---")
+        print(dev.chains.enumeration_log())
+
+        for link in dev.chains.links().links:
+            print("chain {}: {} board(s)".format(link.id, len(link.boards)))
+
+
+if __name__ == "__main__":
+    main()

dt5215-1.0.1/examples/04_registers.py

@@ -0,0 +1,35 @@
+"""Read and write a register of a FERS board over TDlink.
+
+Register addresses are in ``FERS_Registers_520X.h`` of FERSlib; this reads one back after
+writing it, which is the honest way to prove a link works end to end.
+"""
+
+from _common import open_device
+
+
+def main():
+    with open_device() as dev:
+        boards = dev.chains.links().boards
+        if not boards:
+            print("no boards: enumerate first (see 03_enumerate.py)")
+            return
+
+        board = boards[0]
+        print("talking to board {} ({})".format(board.id, board.name))
+
+        # 0x01000000 is a scratch register on the 520X family
+        address = 0x01000000
+        before = dev.boards.read_register(board.chain, board.node, address)
+        print("  read  0x{:08X} -> 0x{:08X}".format(address, before.value))
+
+        dev.boards.write_register(board.chain, board.node, address, 0xDEADBEEF)
+        after = dev.boards.read_register(board.chain, board.node, address)
+        print("  wrote 0xDEADBEEF, read back 0x{:08X}".format(after.value))
+
+        if before.value is not None:
+            dev.boards.write_register(board.chain, board.node, address, before.value)
+            print("  restored 0x{:08X}".format(before.value))
+
+
+if __name__ == "__main__":
+    main()

dt5215-1.0.1/examples/05_hv.py

@@ -0,0 +1,34 @@
+"""Check the HV of every board and switch it off safely.
+
+Switching all the HV off is the one operation worth having in a script you can run in a
+hurry; it reports the boards that refused instead of raising, so you know which one is still
+live.
+"""
+
+from _common import open_device
+
+
+def main():
+    with open_device() as dev:
+        status = dev.boards.hv_status()
+        print("system HV: {}{}{}".format(
+            "on" if status.hv_on else "off",
+            "  OVERVOLTAGE" if status.hv_overvoltage else "",
+            "  OVERCURRENT" if status.hv_overcurrent else ""))
+
+        for board in dev.chains.links().boards:
+            print("  {:<6} {:<6} HV {:<3} {:>6.1f} V {:>6.2f} mA   det {:>5.1f} C".format(
+                board.id, board.name, "on" if board.hv_on else "off",
+                board.hv_Vmon, board.hv_Imon, board.tempDetector))
+
+        if status.hv_on:
+            print("\nswitching every HV off")
+            result = dev.boards.switch_off_all_hv()
+            print("  {} board(s) switched off".format(result.switched_off or 0))
+            for error in result.errors or []:
+                print("  REFUSED: chain {} board {} ({}), status {}".format(
+                    error.chain, error.board, error.model, error.status))
+
+
+if __name__ == "__main__":
+    main()