CERTUS FLEX protocol and verification#
The driver provides direct Ethernet and INCO server connections, motion, pressure control, timed or calibrated dispensing, and valve maintenance. The Python API uses PLR’s default units: millimetres, seconds, microlitres, and bar for pressure.
Verification scope#
Hardware evidence uses dispenser C196069, firmware 1.0.7.378-trunk, with an angled FLEX8 head. The fixtures retain controller replies for regression testing.
Operation |
Verification |
|---|---|
Direct UDP |
Identity, status, head, signed position/pressure reads; reconnect and sequence rollover |
Motion |
A1–A3 dry traversal at park height; B2/C3 positioning at 35.4 mm Z; return to park |
Pressure |
Regulation to 0.2 bar and discharge to approximately zero |
Timed valves |
Water flow through channels 2/3; visible water in B2/C3 after 1 ms pulses |
INCO server TCP |
Native request fixtures and simulated responses; no hardware verification |
Prime, purge, clean cycle |
One water cycle on channels 2/3 at 0.2 bar: 20 ms cumulative purge in 1 ms pulses, 250 ms pause, 100 ms prime per channel; observed flow into waste, park, and zero pressure after explicit discharge |
Volume-to-time conversion |
Vendor-source reference cases cover interpolation, volume correction, units, and the valve command; physical volume accuracy depends on the supplied calibration |
Registered plate plan |
Live Corning 96-well geometry and channel offsets; four 1 ms water commands to B2/C2/B3/C3 in two compatible channel groups; raised pause after two confirmed doses, then resume |
Run controls |
Paused-plan abort prevented every dose; stop/close accepted on all eight outputs; no pending faults before or after the integration protocol |
Extended maintenance |
50 ms bounded flush per channel and one 2 ms cumulative idle purge in 1 ms pulses on channels 2/3; park and zero pressure after discharge |
Configuration reuse |
Device/head identity round trip on the connected controller; populated vendor calibration and configuration validation use offline fixtures, because measured curves for the installed valves were not supplied |
Reference-axis motion, the full travel envelope, other head types, and cleaning effectiveness remain unverified. Instrument calibration and cleaning effectiveness are separate from driver command verification and depend on the installed valves and fluid.
Capability coverage#
The registry’s Mostly level means routine plate and maintenance workflows are available, with the exclusions below. Hardware verification is scoped to the specific head, controller, and operations in the table above.
User workflow |
API |
|---|---|
Connect and prepare |
Direct UDP or INCO server, identity, installed-head validation, initialization, park, pressure, and detailed faults |
Target a plate well |
PLR plate registration, channel offsets, height/clearance, travel bounds, and well capacity checks |
Fill a plate or region |
Prevalidated plans, CSV volume maps, gradients, row/column/snake orders, repeats, and progress |
Use multiple channels |
Compatible channel groups queued before a shared completion barrier |
Reuse calibration |
Vendor XML import and metadata-preserving re-export, PLR JSON curves, per-channel correction, and device-bound configurations |
Prepare and clean lines |
Timed and calibrated prime/purge, clean cycles, bounded continuous flush, and finite idle-purge schedules |
Control a run |
Boundary pause/resume, abort, close-all, confirmed dose counts, and uncertain-group reporting |
The manufacturer describes independent channel calibration, parallel dispensing, and multiple plate formats in its technical specifications. The user manual documents regions, variable-volume patterns, maintenance, and interval purging. Thermo Fisher’s Certus automation interface also exposes plate access, dispense tables, and head configuration.
Vendor protocol-file execution, evaporation-curtain support, standby, device-network configuration, and a balance-assisted calibration acquisition workflow are outside this API. A numeric speed interface still requires protocol evidence; firmware profile names remain explicit. Supply measured curves for volume delivery; command verification does not establish the physical volume delivered by an uncalibrated valve.
Connection#
With target omitted, the Python client connects directly to the controller
through pylabrobot.io.UDP, normally on UDP port 1964. Put the computer’s wired
interface on the controller’s subnet; source_ip can select the local interface
when necessary. The tested controller was at 192.168.1.3, with the computer at
192.168.1.2/24; these are observed addresses, not assumed factory defaults.
from pylabrobot.gyger import CertusFlex
certus = CertusFlex("192.168.1.3", head="flex8_angled")
With target set, the client uses pylabrobot.io.Socket to reach the INCO server
on the control PC, normally on TCP port 7979. target is the local target
name configured in that server. It is separate from host, the server PC’s
address. The server must have incoming TCP access enabled and be able to reach
the controller. Neither transport loads a Windows DLL or requires SiLA.
Remote target chains, INCO discovery, fragmented transfers, asynchronous procedure tickets, and protocol-file upload are outside this implementation. Only the synchronous get/put/procedure operations used below are implemented. Unsupported replies cause an error rather than an automatic retry.
Evidence#
The device paths, commands, state transitions, and channel mappings were recovered
from CERTUS CONTROL 2.1.17.2517. Transport framing was recovered from
inco_32.dll and its matching PDB in IndelToolsSetup-tools_19.2.0.exe, distributed
inside the manufacturer’s
matching installer.
The supplied User Manual CERTUS FLEX EN gives the 0.051–1.0 bar dispensing
pressure range; the machine’s valve and fluid requirements still apply.
Reference file |
SHA-256 |
|---|---|
|
|
|
|
|
|
|
|
pylabrobot/gyger/certus_flex/fixtures/native_requests.json contains eight complete
requests produced by offline x86 emulation of that DLL. They cover numeric and
string reads, a numeric write, positive and negative motion coordinates, fractional
values, string and empty-string arguments, a timed pulse, and a zero-argument
completion barrier. The fixtures are not produced by the Python encoder.
The hardware_udp_*.json fixtures in that directory contain real controller
exchanges for reads, start/park procedures, numeric plate moves, pressure writes,
timed valve commands, prime limits, native purge/prime, waste positioning,
completion barriers, and discharge. Timeouts, cancellation,
malformed packets, and lost replies use a simulated transport; UDP datagram
handling is tested on loopback sockets.
The native call sequence is CMcINCOFrameWithBuffer construction, address
generation with sender . and server insertion, frame number 1, operation
generation, then AdjustToNextTarget as performed by TransmitINCOFrame.
Useful virtual addresses in this specific x86 binary are:
Native function |
Address |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Direct UDP wire format#
The tested controller uses classic INCO framing, not the extended TCP frame below.
Each request is one datagram: DLE SOH, an eight-byte header (sequence, operation,
subtype, destination count 1, destination FF, source count 1, source 00, checksum),
payload, DLE ETX, and a data checksum. Literal DLE bytes are doubled. The header
sum, including SOH and its checksum, is FF modulo 256. The payload sum, including
ETX and its checksum, is also FF modulo 256; escape bytes are excluded.
An ACK begins DLE ACK, then sequence, a two-byte error, destination count 1,
destination 00, and header checksum. Its payload and trailer use the same
escaping and checksum rule. A nonzero error is exposed as 0x50000 + error.
The source stays 00. Sequence numbers run from 1 to 255; the client reopens its
socket before reusing a sequence. Valid replies with a different sequence are
ignored under the original request deadline. Requests are never retransmitted.
Numeric and string reads are 2/1 and 2/5, with a NUL-terminated path and no
padding. Strings return NUL-terminated Latin-1 bytes. Numeric responses use
legacy 32.32 fixed point, optionally followed by type 0D, or an eight-byte
double followed by type 09. The low fraction bit is a legacy sign flag and is
removed from the numeric value. Short procedure results may use 16.16 fixed point.
Numeric put (2/0) contains an eight-byte signed 32.32 value, the terminated path,
and type 0D. A zero-argument procedure (4/0) contains a four-byte zero count
and a path padded to four bytes. Procedures with arguments (4/1) contain a
four-byte count, four-byte type bitmap, padded path, then arguments. Numeric
arguments set bitmap bits i and 16+i and contain signed 32.32 values; string
arguments set bit 16+i and contain terminated strings padded to four bytes.
At most 16 arguments and 494 payload bytes are supported.
This format was recovered by static inspection of ConvertVariableToClassicFrame
(0x1001d460), ConvertCallProcedureToClassicFrame (0x1001cbe0),
ConvertFromClasicFrame (0x1001d070), and the classic frame generator/parser
(0x100280d0 / 0x100283f0) in the referenced binary. Numeric writes and numeric
procedure arguments also have hardware-capture coverage for the operations in
the verification table.
INCO server TCP wire format#
Each TCP message consists of a 52-byte header, an optional extended header, an address block, and data. TCP may split any of these across reads. There is no additional TCP length prefix. Multi-byte header fields follow the endianness bit at byte 32; requests use big endian.
Offset |
Size |
Meaning |
|---|---|---|
0 |
13 |
Compatibility bytes |
13 |
2 |
Content interface/feature versions: 2, 3 |
15 |
2 |
Receiver interface/feature versions |
17 |
1 |
Transaction: request 1, reply 6 |
18 |
2 |
Operation type and subtype |
20 |
4 |
Frame number |
24 |
4 |
Fragment count and fragment index, two 16-bit values |
28 |
4 |
Unsigned INCO error code |
32 |
4 |
Flags; bit 0 of byte 32 selects big endian |
36 |
4 |
Spare |
40 |
4 |
Target startup timestamp |
44 |
2 |
INCO path offset |
46 |
6 |
Extended-header, address, and data lengths, three 16-bit values |
The outgoing address block begins 01 20 03 01 00 00 00 00, followed by three
32-byte, NUL-padded slots: ., ..., and the target name. These are direction,
slot width, slot count, current index, reserved bytes, and the route respectively.
Numeric get is type/subtype 2/1; string get is 2/5. Both contain four zero
bytes followed by a NUL-terminated path, padded to a four-byte boundary. Numeric
put is 2/0, containing a typed number followed by the NUL-terminated path.
Procedure call is 4/1: one argument-count byte, three zero bytes, padded path,
then typed arguments. Numeric arguments contain type 0x010f, two padding bytes,
an IEEE double and a signed 32.32 fallback. String arguments contain type
0x0200, two padding bytes, and a padded NUL-terminated string.
Numeric responses contain type 0x0109 (double) or 0x010d (fixed point), two
padding bytes, and eight value bytes. Fixed-point words are integer then fraction,
even in little endian replies. String responses use type 0x0202, two padding
bytes, a length split into low and high 16-bit words, and the terminated string.
The INCO error is checked before decoding a value and exposed as IncoError.code.
Device operations#
The root is Machine.Entity.Dispenser. Module paths begin
Machine.Entity.Dispenser.Module.Entity.. .Prop.State values are startup=0,
off=1, wait=2, on=3, ready=4, busy=5, error=6. The coordinator state is
Machine.Entity.Dispenser.Coord.Prop.State.
Operation |
Controller path or command |
|---|---|
Serial number |
|
Firmware |
|
Start |
|
Reference axes |
|
Position |
|
Move |
|
Park |
|
Prime/purge position |
Park Z, |
Pressure |
|
Pressurize/discharge |
|
Pulse |
|
Prime |
|
Purge |
|
Close valve |
|
Await pulses |
Set |
The first head channel is valves[0]. FLEX5 maps to outputs 1–5; FLEX8 to 0–7;
angled FLEX4 to 0–3; angled FLEX8 to 0–7. The installed head is an explicit
constructor argument; the driver does not infer it from a serial number.
Motion waits follow the vendor’s five-second acceptance observation: wait to see Ready depart, then wait for Ready to return. A sufficiently short move can finish between reads, so Ready after the observation period is also accepted. The timeout must allow that grace period. Fault states raise immediately. Pressure completion also requires a charged/idle charge state and actual pressure within 0.01 bar of the requested value.
Speed names select firmware profiles, such as "slow" mapping to "Slow".
A numeric mm/s command interface has not been verified.
Durations use seconds at the Python API and microseconds on the controller. The
protocol validator’s minimum is 50 µs; individual valves may require longer.
Volume dispensing requires a measured per-valve/per-fluid ValveCalibration in
µL and seconds. Setpoint and actual pressure must match that calibration.
dispense(volume, correction_factor=1.0) follows CERTUS CONTROL’s volume-to-time
calculation: multiply the requested volume by the channel’s correction factor,
then linearly interpolate between the surrounding calibration points. The factor
range is 0.5–1.5. The factor applies to volume, not opening duration. PLR converts
the resulting seconds to microseconds for the same native ValveN.Cmd.Dispens
command used by CERTUS CONTROL. It does not read a control PC’s calibration files
or correction factors automatically.
Reference tests cover both interpolation segments, exact endpoints, factor limits,
and the resulting microsecond command. Their synthetic data checks the calculations;
it is not calibration data for an installed valve. For example, points of 0.5 µL
at 500 µs and 1.5 µL at 1250 µs map a 1 µL request with factor 1.25 to 1062.5 µs.
The reference methods are DispenseCalibration.CalculateValveOpenTime and
CalibrationUtils.InterpolateValveOpenTime in CERTUS CONTROL 2.1.17.2517.
Unlike the vendor’s extrapolation, PLR rejects corrected volumes outside the
measured range. This verifies the command calculation, not the actual dispensed
mass or volume; those require measurements for the installed fluid and valve.
Motion and valve operations share a lock. The calibration pressure check is held
under that same lock. This does not prevent another application from controlling
the machine; use one controlling application at a time. A transport timeout,
cancellation during an exchange, or malformed reply closes the socket and requires
explicit reconnection. None of those outcomes proves that a physical operation
stopped. A failed dose must be investigated before another dispense is requested.
stop() disconnects only; use set_pressure(0) explicitly to discharge.
Valve maintenance#
valves[i].prime(duration) opens continuously at the current position.
valves[i].purge(duration, pulse_duration=..., interval=...) requests a pulse
train timed by the controller. All times are in seconds. Purge duration is
cumulative valve-open time; it excludes gaps between pulses. Omit interval to
use the firmware’s timing. Explicit intervals need the three-argument command;
unsupported requests raise without retrying another command form.
clean_cycle() moves to the configured purge position and repeats purge, a
250 ms pause, and prime. It processes selected channels sequentially, waits for
each operation, and parks on success. channels uses zero-based valve indexes.
Pressure is controlled separately and remains unchanged by cleaning:
await certus.initialize()
await certus.set_pressure(0.2)
try:
await certus.clean_cycle(
channels=[1, 2],
prime_duration=0.1,
purge_duration=0.02,
purge_pulse_duration=0.001,
cycles=1,
)
finally:
await certus.set_pressure(0)
The default cycle count is five. These durations are a functional-test example, not a validated cleaning recipe. Use fluid-compatible cleaning conditions and waste collection. Calibrated volumes require measured valve/fluid calibration. On failure or cancellation, cleaning attempts to stop the selected valves and raises the original error without repeating doses or making a recovery move.
Continuing hardware verification#
Use the hello-world notebook one cell at a time. Confirm the controller address (or server/target) and installed head, capture identity and status reads, and compare positions and pressure with CERTUS CONTROL. After those match, verify reference and park motions with a clear workspace, then a short water pulse into waste. Measure delivered volume separately before supplying a calibration. Preserve the PLR capture and record firmware, head, valve, pressure, pulse duration, and observations. Use registered PLR wells for plate protocols and explicit controller coordinates for commissioning.
PLR plate and well operations#
read_plate_registration(plate, bounds=...) reads the controller’s active plate
origin, grid, height, park clearance, and per-channel offsets. It rejects a grid
or installed head that disagrees with the selected resources. Supply a verified
MotionBounds envelope: software-limit paths have not been established, so the
API does not invent them. For a different plate definition, PlateRegistration
also accepts explicitly measured geometry.
move_to_well(registration, well, channel=...) raises vertically to clearance,
traverses XY, lowers, and checks the reported position within 0.05 mm.
dispense_to_well(registration, well, volume, channel=...) additionally checks
calibration, pressure, and well capacity before moving. Positions use PLR well
centers and controller valve offsets. A lid, rotation, changed plate geometry,
foreign well, or target outside the supplied bounds is rejected. Keep the volume
tracker’s initial contents accurate; physical contents are not sensed, and these
operations do not update the tracker automatically.
Plate dispense plans#
Create DispenseStep(well, channel, volume=...) requests in µL, then call
plan_dispense(registration, steps, repeats=1, order="given", parallel=True).
Planning is offline and checks the entire recipe, calibration range, target bounds,
common pressure, and cumulative capacity before movement. Zero-volume wells are
skipped. DispenseStep.gradient produces a linear gradient; from_csv accepts
well,channel,volume columns and an optional correction_factor. Channels are
zero-based. Orders are given, row, column, snake_row, and snake_column.
execute_plan(plan) revalidates geometry, calibration, capacity, head, and pressure.
Consecutive requests with distinct channels at a common stage position are queued
before a shared valve barrier. This permits controller concurrency without
promising simultaneous pulse edges. Other requests retain their specified order.
On success the head is raised at the final XY position. Park and pressure discharge
are explicit. A failed group is stopped best-effort and never automatically repeated.
For commissioning, steps may specify duration instead of volume; these timed
plans cannot check physical filled volume. Do not supply both quantities. Rebuild
plans after changing calibration or plate geometry.
Calibration and configuration files#
ValveCalibration.from_vendor_xml(text, calibration_id=...) imports one CERTUS
CONTROL calibration map. It converts explicit units to µL, seconds, and bar,
excludes disabled points, and preserves the source metadata and disabled points
for to_vendor_xml(). Stored volume is already per shot; shot count must not
divide it again. Ambiguous maps, missing units, and nonmonotonic curves are rejected.
save(path) and load(path) provide versioned PLR JSON for measured curves.
from pathlib import Path
from pylabrobot.gyger import ValveCalibration
calibration = ValveCalibration.from_vendor_xml(Path("water-calibration.xml").read_text())
await certus.configure_channel(
1, calibration=calibration, fluid="Water", valve_serial="INSTALLED-VALVE-SERIAL",
correction_factor=1.0,
)
certus.save_configuration("certus-water.json")
# In another session, after setup():
await certus.load_configuration("certus-water.json")
Configuration files bind to the controller serial and installed head. Every channel entry is validated before any is applied. Fluid and valve serial are operator declarations: the controller does not identify the liquid or the individual valve. Volume operations inherit the configured correction factor unless explicitly overridden, and check actual pressure and setpoint against the calibration. Imported curves establish the command calculation; measured accuracy still depends on the installed valve, liquid, pressure, and the quality of those measurements.
Run control and faults#
Pass a single-use RunControl to execute_plan(plan, control=control). Its immutable
progress snapshot reports state, total/completed groups, confirmed doses, and an
uncertain_group when submitted liquid commands lack confirmed completion.
control.pause() requests a pause after the current group completes and Z raises;
await control.wait_paused() observes that boundary. control.resume() continues
with the next group. Run the executor in an asyncio task to operate these controls.
await certus.abort() prevents further submissions, wakes a paused run, and stops
and closes every selected-head valve. The executor raises RunAborted; a failed
or aborted run cannot resume. An in-flight stage move may finish. Closure failures
raise and do not prove that a valve stopped. No recovery movement, discharge, or
retry is implicit. close_all() waits for the current operation before closing
valves. Neither is a substitute for the physical emergency stop.
await certus.get_faults() returns controller issue IDs, codes, tasks, descriptive
text, flags, and native timestamps without acknowledging them. Resolve the cause
before explicitly starting another operation; the driver never clears faults to
force a run through.
Bounded flush and volume-based maintenance#
await certus.flush([1, 2], duration=0.05) moves to prime waste, queues a continuous
opening on each selected valve, waits, and parks. duration is in seconds and must
fit each valve’s native prime timeout. It uses firmware-timed Prime rather than an
indefinite OpenValve; connection loss cannot extend the requested opening. For an
early stop, run it in a task and call await certus.abort(). A RunControl reports
completion and uncertainty. Neither flush nor idle purge changes the pressure setpoint.
With measured calibration assigned, valves[i].prime_volume(volume) opens once
for the interpolated duration. valves[i].purge_volume(volume, pulse_volume=...)
converts each pulse separately, including any remainder. All pulse volumes must
fit the measured range; the whole request is validated before the first opening.
These per-valve methods operate at the current position, which must be over waste.
idle_purge(channels, interval=..., cycles=..., duration=..., pulse_duration=...)
waits the specified seconds before each cycle, acquires the operation lock, moves
to purge waste, purges the selected channels, and parks. The cycle count is required
and finite. It waits for active or paused plate plans and releases the lock between
cycles. Run it as an asyncio task for background maintenance; abort or cancel and
await that task before disconnecting. No persistent firmware timer is installed.
For maintenance, progress counts completed valve operations rather than individual
pulses. Cleaning effectiveness depends on the fluid, contamination, and chosen recipe.