STARBackend: 96-head Y/Z drive speed & acceleration set/request, scoped to each move

[BioCam]

Adds set/request for the 96-head Y and Z drive speed and acceleration (H0 AA / H0 RA), and uses them so a move's speed and acceleration are scoped to that single call. Builds on #1086 (the Z move primitives) and #1087 (the per-drive defaults).

A ZA / YA move writes its speed and acceleration into the drive's volatile register and leaves them there, so a later move - or a C0-level command (aspirate96 / dispense96) that sends none of its own - silently inherits the previous move's values. Confirmed on hardware: a speed=20 Z move reads zv back as 20.

• head96_set_y_speed / head96_set_y_acceleration / head96_set_z_speed / head96_set_z_acceleration (H0 AA): save a persistent drive parameter standalone, no move - the same mechanism slow_iswap uses on the iSWAP via R0 AA.
• head96_request_y_speed / head96_request_y_acceleration / head96_request_z_speed / head96_request_z_acceleration (H0 RA): the read counterparts.
• head96_move_stop_disk_z and head96_move_y reset the drive speed/acceleration to the head's default after the move, skipping the reset when the caller left a parameter at its default (so a plain move adds no register writes); reset_z_parameters / reset_y_parameters opt out.
• head96_move_stop_disk_z retracts to Z-safety on any firmware error (e.g. the head crashing into something) before re-raising - at a quarter of the max Z speed, since the head may be submerged in liquid - via retract_on_crash; head96_move_to_z_safety passes it False so the retract cannot recurse.
• Head96Information gains z_speed_range and z_acceleration_range (constant fields, verified unchanged across the 2008/2013/2025 firmware command sets). head96_move_stop_disk_z, head96_set_z_speed, and head96_set_z_acceleration now validate against the record instead of hardcoded literals, mirroring how head96_move_y already uses y_speed_range. The crash retract speed is derived from z_speed_range[1] rather than a magic number.

Behaviour change to note for review: head96_move_y's speed / acceleration now default to None (resolving to the firmware default, e.g. 390.62 mm/s) instead of a hardcoded 300, matching head96_move_stop_disk_z.

Validated on hardware: RA reads match the firmware-resolved defaults in Head96Information, and an AA set followed by RA round-trips exactly.

---

Update 2026-06-15 (revised during review)

Following review, the public surface moved from standalone set/request methods to client-tracked, runtime-settable defaults. The original description above still explains the underlying register behaviour; this section records what changed on top of it.

• The 96-head Y/Z drive speed and acceleration defaults are now exposed as range-checked properties (head96_y_drive_speed_default, head96_y_drive_acceleration_default, head96_z_drive_speed_default, head96_z_drive_acceleration_default), seeded from Head96Information at setup. A move resolves its None default and restores the register through these, so a user can set their own default at runtime, have it drive plain moves, and have it survive the post-move restore. Head96Information stays frozen as the factory reference; the live values live on the backend.
• The standalone AA register writes are now private (_head96_set_*); the public knob is the property. The RA reads stay public as diagnostics for troubleshooting or specialized use. This addresses the review point that the set methods should not be public.
• Head96Information gains y_acceleration_range, resolved per firmware (max 500.0 on 2008, 781.25 on 2013+) like y_speed_range rather than a constant - the 2008/2013/2025 command sets show the max changed at the 2013 firmware. head96_move_y and the Y-acceleration setter now validate against it; the previous hardcoded 78.125..781.25 literal over-permitted 2008-era heads.
• The head96_move_y default-to-None note above still holds, but None now resolves to the overridable property rather than the raw Head96Information value.
• The 96-head section is regrouped so it opens with the conversion helpers, then the overridable-default properties, the request reads, the private setters, then the movement commands.

[rickwierenga]

what does the range depend on? it says or

[BioCam]

See resolve commands: it depends on the firmware/variant

[rickwierenga]

Dug into this — the or was masking that the range is firmware-version-dependent, and (the part that bit us) that the speed and acceleration cutoffs land on different firmware years:

• Speed max: 390.625 mm/s pre-2021 → 625.0 on 2021+ — _head96_resolve_y_speed_range (year <= 2021)
• Acceleration max: 500.0 mm/s² pre-2010 → 781.25 on 2013+ — _head96_resolve_y_acceleration_range (year >= 2010)

So the single Note that only documented the 2021 speed cutoff was actually wrong for acceleration.

What we did in head96_move_y:

• dropped the or from the Args and spelled out both ranges explicitly, each pointing at the Head96Information field that resolves it (y_speed_range / y_acceleration_range)
• rewrote the Note to document both cutoffs (speed @ 2021, acceleration @ 2010) instead of only speed

Docs-only; the validation already reads from the resolved range fields, so behaviour is unchanged.

[rickwierenga]

this should always be true and the parameter should not even exist. it is generally good practice for functions to either do something or update state, very rarely both. this prevents bugs and makes it easier to use. (if we want to set the default, the user can do that on the client side imo, by updating 96head info, and we would still send AA twice just to keep the machine state untouched. we do not want state in two places if we can avoid it, and we easily can)

[rickwierenga]

in other words the code should be as self-contained/"atomic" as possible

[BioCam]

updating 96head info

is not possible, for safety reasons Information is frozen

regarding the reason where this has become really important is described in the comment below about the same topic

[rickwierenga]

Done in 78ea87f — removed reset_y_parameters / reset_z_parameters entirely. head96_move_y and head96_move_stop_disk_z no longer take a flag that makes them also mutate persistent state: the move now always cleans up after itself, so there's no "do a thing and leave state changed" mode to opt out of.

[rickwierenga]

it should always restore to the value that was there before the change, not to the PLR default. Users might've edited it using AA themselves. this wouldn't be consequential to us, since we ALWAYS get values from PLR, but they might have hackery or other software that depends on this in a strange way (it's not transparent, which makes it more dangerous)

[BioCam]

I am not sure I understand:

We always expect the default speed/acceleration to be set if none has been explicitly declared.

(we might want to make the default speeds/accelerations to be made class property variables rather than part of the Head96Information, that way they are easy to modify for all commands by end-users who need more power? - but making that change is a separate PR from this set recovery PR)

But I the restore_speed: bool actually exists for a different purpose: to enable building more complex commands while avoiding roundtrip churn: e.g. if you build a complex command with multiple z positions, changing speed across each, not all commands should re-set in between commands because the next command will instantly overwrite the memory state anyway, i.e. this flag avoids unnecessary command roundtrips.

[rickwierenga]

Done in 78ea87f. The move now snapshots whatever speed/acceleration are on the robot before it runs (read via RA), then restores those exact values afterwards — so an external AA edit a user made is preserved, and the command leaves the persistent register exactly as it found it. No longer restores to the PLR default. The restore AA is skipped when the move's value already matched what was there (compared in increments, the unit actually stored).

Tradeoff: this adds 2 RA reads per move — intrinsic to restoring the actual prior value rather than a tracked default (you can't restore what you didn't read).

[rickwierenga]

since Head96Information is frozen, it is not a good place for storing user configurable values like _head96_y_drive_speed_default. we should either

1. unfreeze it
2. store the defaults somewhere else, whether on the backend or another data class
   my preference would be 2 with backend for now, and then make it attributes of the capability backend in v1

[BioCam]

since Head96Information is frozen, it is not a good place for storing user configurable values like _head96_y_drive_speed_default. we should either

1. unfreeze it
2. store the defaults somewhere else, whether on the backend or another data class
   my preference would be 2 with backend for now, and then make it attributes of the capability backend in v1

There are 2 different "default":

1. the manufacturer defaults -> these are the ones which are stored and resolved in the Head96Information, they don't change ever after setup and that's why I placed them there
2. the PLR programmer's defaults -> these are configurable and during (re-)assignment have to be checked whether the assigned value is valid against the allowed range; that is what I built into this PR as the getter setter class attributes

having both means it is always possible by a PLR programmer to set back to default (because the information is always retrievable from the frozen dataclass)

[rickwierenga]

why do we care about manufacturer defaults? why not just have the PLR default for everything since that's the value that's actually configurable and used? if we want to use the device defaults, we can load those values into the plr default attribute. saving it for people seems like a crutch and it makes everything more chaotic

[BioCam]

One reason is that PLR does then not choose the starting default but instead we use the starting default that the device has been designed for:
When you restart the STAR it only has the device defaults set into it.
When you run a PLR script and overwrite it then the PLR default will take its place on volatile device memory ... until a power cycle comes along again.

And this manufacturer default changes based on firmware/variant.
To keep a clear overview of what is happening we would need a firmware/variant-adaptive record of what is this specific device meant to run on. Then we can make an explicit decision to change it from that reference and always be able to quickly compare from what OEM value it was changed to what PLR value.

We could just always set a PLR default without keeping an explicit record of what the manufacturer intended?

Are you suggesting that initial PLR default is computed during setup based on firmware/variant and then set in PLR, i.e. exactly the same as now but just no record being made of it in Head96Information?

[BioCam]

Thank you @rickwierenga for the thorough review process 😊