Real time provider TCLab

Real-time provider: TCLab

This page documents TCLab usage through the serial provider.

Current status:

• Driver is implemented in code.
• Not yet hardware-validated in this repo.

Implementation module: src/bdsim/blocks/io_tclab.py.

Provider and driver selection

Use serial provider with a TCLab device entry in bdsim.toml.

from bdsim.realtime import BDRealTime

rt = BDRealTime(
    io_provider="serial",
    io_provider_kwargs={"config_path": "bdsim.toml"},
)

TCLab protocol summary

• Commands: VER, T1, T2, Q1 <pct>, Q2 <pct> (space-separated, \n-terminated — not comma-separated)
• Inputs: T1, T2
• Outputs: Q1, Q2 in percent
• Typical baud: 115200

The driver sets safe state on startup/shutdown (heaters to zero).

Example bdsim.toml

[io]
config_version = 1
default_provider = "serial"

[providers.serial]
type = "serial"
shutdown_on_signal = true
safe_shutdown_timeout_s = 0.5

[devices.tclab0]
provider = "serial"
driver = "tclab"
port = "/dev/ttyACM0"
baud = 115200
startup_probe = true
startup_timeout_s = 2.0

[devices.tclab0.channels.t1]
direction = "in"
kind = "analog"
address = "T1"
eng_units = "C"
scale = 1.0
offset = 0.0

[devices.tclab0.channels.t2]
direction = "in"
kind = "analog"
address = "T2"
eng_units = "C"
scale = 1.0
offset = 0.0

[devices.tclab0.channels.q1]
direction = "out"
kind = "analog"
address = "Q1"
eng_units = "%"
eng_min = 0.0
eng_max = 100.0
safe = 0.0

[devices.tclab0.channels.q2]
direction = "out"
kind = "analog"
address = "Q2"
eng_units = "%"
eng_min = 0.0
eng_max = 100.0
safe = 0.0

Diagram binding

clock = bd.clock(0.1, name="main")

t1 = bd.ANALOGIN(clock=clock, device="tclab0", channel="t1", name="T1")
q1 = bd.ANALOGOUT(clock=clock, device="tclab0", channel="q1", name="Q1")

Bring-up checklist

1. Verify serial connectivity first; see Real-time provider: Serial transport setup.
2. Start with a low heater limit and short run.
3. Confirm shutdown drives Q1 and Q2 to zero.
4. Add telemetry while tuning.

Example script

Use:

python examples/eg_tclab_rt.py

Safety notes

• Always include output saturation in the controller path.
• Keep safe = 0.0 for heater channels.
• Use conservative gain values for first run.