dbay-client/README.md

DBay Client (Unified Dual-Mode)

DBay provides a unified Python client (DBayClient) for interacting with DBay hardware in two distinct ways:

1. GUI (stateful) mode – Talks to the DBay GUI backend over lab-link WebSocket sync, pulling the authoritative system state and sending backend commands.
2. Direct (stateless) mode – Sends low-level ASCII commands directly to the mainframe over UDP or Serial without maintaining any shadow state.

Both modes share the same object model and method names where feasible. You choose the mode once at construction via a simple string: mode="gui" or mode="direct".

Installation

Requires Python 3.11 or newer.

Install from PyPI (package name placeholder shown below; adjust if different):

pip install dbay

Or install from source (editable):

git clone <repository-url>
cd dbay/device-bay-client
pip install -e .

Quick Start

GUI Mode (Stateful)

from dbay import DBayClient

client = DBayClient(mode="gui", server_address="192.168.0.50", port=8345)
client.list_modules()

dac16 = client.module(1, expected="dac16D")
dac16.set_voltage(0, 1.2, activated=True)
dac16.set_voltage_shared(0.5)  # sets all channels to 0.5 V

Direct Mode (UDP)

from dbay import DBayClient, dac4D, dac16D

client = DBayClient(mode="direct", direct_host="192.168.0.108", direct_port=8880)

# Direct mode requires explicit attachment (no discovery)
dac4 = client.attach_module(0, dac4D)
dac4.set_voltage(0, 5.0)
dac4.set_voltage_diff(1, -2.0)

dac16 = client.attach_module(1, dac16D)
dac16.set_voltage(10, -1.25)
dac16.set_bias(3.0)
print("Raw read: ", dac16.read())

Direct Mode (Serial)

from dbay import DBayClient, HIC4, ADC4D

client = DBayClient(
	mode="direct",
	direct_transport="serial",
	serial_port="/dev/ttyUSB0",
	baudrate=115200,
	timeout=1.0,
)
h = client.attach_module(2, HIC4)
h.set_voltage(0, 0.75)

Raw Command (Direct Only)

client.direct_send("DAC16D VS 1 5 2.5")

Reacting to State Changes (GUI Only)

The GUI backend broadcasts every state change to all connected clients. Rather than polling snapshot(), subscribe:

from dbay import DBayClient

client = DBayClient(mode="gui", server_address="192.168.0.50")

def on_change(event):
    # The snapshot is already up to date — the client applied the patch before
    # calling back, so you never apply patch operations yourself.
    if event.origin_client_id == client_id_of_mine:
        return                      # ignore echoes of our own commands
    print("version", event.version, client.snapshot()["data"][0])

unsubscribe = client.on_patch(on_change)
client.on_snapshot(lambda e: print("resync at version", e.version))
...
unsubscribe()

client.state_version is bumped on every applied patch, so a consumer holding a derived view (e.g. a typed model validated from the snapshot) can cache it and recompute only when the version changes:

class MirroredState:
    def __init__(self, model_cls, client):
        self._model_cls, self._client = model_cls, client
        self._cached, self._version = None, -1

    def current(self):
        if self._client.state_version != self._version:
            self._cached = self._model_cls.model_validate(self._client.snapshot())
            self._version = self._client.state_version
        return self._cached

Both subscription methods connect the sync transport on demand, so they work on a client built with load_state=False. Callbacks run on the lab-link client's own thread — guard any state they touch accordingly.

State Schema

dbay.state is the single definition of what a rack's state looks like. The GUI backend binds it to lab-link and mutates it; clients validate the snapshot they receive against it. Both sides import the same classes.

from dbay import DBayClient
from dbay.state import SystemState, Dac4DState

client = DBayClient(mode="gui", server_address="192.168.0.50")
state = SystemState.model_validate(client.snapshot())

module = state.data[1]
if isinstance(module, Dac4DState):
    print(module.vsource.channels[0].bias_voltage)

A module type this build doesn't recognize validates into UnknownModuleState rather than failing the whole snapshot — core stays typed and unrecognized fields are preserved, so a consumer older than the rack still reads the slots it understands. A malformed module still raises.

A backend registering custom modules extends the union:

from dbay.state import build_system_state_model
SystemState = build_system_state_model(MyModuleState)   # module_type must be a Literal

Module Methods (Summary)

GUI “pending” indicates the sync command and data models are not yet implemented; calls will raise NotImplementedError.

Migration from Legacy DBay

Old (HTTP-only):

from dbay.client import DBay
client = DBay("192.168.0.50")
client.modules[0].voltage_set(0, 1.0)

New unified API:

from dbay import DBayClient
client = DBayClient(mode="gui", server_address="192.168.0.50")
mod = client.module(0, expected="dac4D")
mod.set_voltage(0, 1.0)

Key changes:

• Class name changed to DBayClient.
• Methods standardized to set_voltage (legacy voltage_set still available as alias).
• Access modules via client.module(slot) instead of client.modules[index].
• Direct mode now uses class-based attach_module(slot, ModuleClass) for better type checking.

Design Notes

• GUI mode uses lab-link WebSocket sync and Pydantic models. By default module changes are retained (retain_changes=True). Opt out with retain_changes=False if you want automatic revert for supported modules.
• Direct mode is intentionally stateless: it sends commands and returns raw responses (no caching). Activation flags are ignored in direct mode.
• Some sense and supply-voltage features may be absent in GUI until sync commands are added.
• Class-based attachment uses each module's CORE_TYPE attribute to set hardware identity.
• New modules (FAFD, HIC4, ADC4D, DAC4ETH) raise NotImplementedError for GUI operations for now.
• Direct connection layer can be injected: pass an existing DeviceConnection (or subclass) via connection= at construction to integrate with higher-level proxy frameworks (e.g., Pyro5 remote transport).

Injecting a Custom Direct Connection

Direct mode can accept an existing DeviceConnection (or subclass) via the connection= parameter instead of constructing one from host/port or serial arguments. If connection is provided it takes precedence; otherwise you must supply either (direct_host + direct_port) for UDP or serial_port for serial.

State Retention & Optional Reversion (retain_changes)

Default behavior now: hardware settings you apply in GUI mode remain in effect after your script ends. This matches the intuitive expectation that "what I last set is what the GUI (and hardware) keeps". The flag retain_changes therefore defaults to True.

If you prefer a session-style workflow where temporary changes are rolled back automatically for supported modules (currently the DAC family), start the client with retain_changes=False:

from dbay import DBayClient

client = DBayClient(
    mode="gui",
    server_address="192.168.0.50",
    retain_changes=False,   # auto-revert DAC channels on cleanup
)

Behavior matrix:

Details & caveats:

• Reversion relies on destructor timing; abrupt termination (e.g. kill -9) skips cleanup.
• Only modules that captured an initial state support revert (DAC family). Others have nothing to restore.
• A future enhancement may add an explicit revert_all() to avoid relying on GC.

Recommendation: leave the default (True) for user-facing or interactive tooling; use False in automated measurement scripts that must leave hardware in a known pre-run state.

Limitations / Not Implemented Yet

• dac16D.read() in GUI mode.
• Batch / shared voltage command optimization in direct mode (currently sequential sends).
• Websocket streaming for sense channels (explicitly out of scope for now).

Contributing

Contributions are welcome! Feel free to open issues or PRs for:

• Adding GUI endpoints/models for the new modules.
• Extending test coverage for direct command generation.
• Documentation improvements.

License

MIT License. See LICENSE.