Upgrade Agilent VSpin and Access2 protocol drivers

[rickwierenga]

Summary

This PR substantially upgrades PyLabRobot's Agilent VSpin centrifuge and Access2 loader support
using complete protocol and sequencing knowledge from the vspin-cockpit project.

The existing PLR APIs and FTDI transports are retained, while opaque wire captures are replaced
with named protocol operations, typed status decoding, explicit trajectory calculations, bounded
polling, and safer state-confirmed workflows.

Thanks

Special thanks to Reed Kelso for generously sharing his work on the Agilent VSpin and Access2 in the
vspin-cockpit repository and allowing us to adapt the
relevant logic for PyLabRobot.

The reference implementation was pinned during development to
2e6ff6b9327cb66f7889d76cdefefc2a5b5652b2.

A durable acknowledgement is also included in the package-local VSpin README.

VSpin changes

• Added structured NMC command construction and typed response decoding.
• Replaced delimiter-based reads with fixed-length reads derived from each module's active status
  mask.
• Added checksum validation and command/response context to protocol errors.
• Ported baud probing, network reset, sequential address assignment, module identification,
  topology validation, and final 57,600-baud setup.
• Added bounded, status-driven homing and retained the resulting home position.
• Added shortest-path bucket positioning with:
  • motion-complete confirmation;
  • encoder-position tolerance;
  • servo fault detection;
  • motor-off failure handling;
  • one-revolution alignment recovery.
• Reworked spin calculations around explicit RCF/RPM, velocity, acceleration, ramp-time, and
  encoder-distance conversions.
• Preserved independent acceleration and deceleration fractions.
• Confirmed deceleration using both MOVE_DONE and zero measured velocity.
• Removed the unexplained post-spin reset/re-home loop.
• Added an explicit safe spin-abort operation.
• Rejects signed 32-bit position overflow before sending servo motion.
• Teardown now closes FTDI without resetting the NMC network.

Access2 changes

• Added a typed, transport-independent Access2 command/status codec.
• Uses PLR's binary Reader and Writer helpers throughout.
• Preserves the existing FTDI constructor and transport behavior.
• Added strict FTDI framing, CRC validation, response-ID matching, bounded frame sizes, and
  partial-read handling.
• Added firmware and hardware version queries.
• Added short and full status decoding, including:
  • initialized and homed state;
  • emergency-stop state;
  • motor-power faults;
  • optical sensor state;
  • per-axis status and positions.
• Distinguishes absolute single-axis moves from controller-stored teachpoint moves.
• Added bounded, status-confirmed homing and motion polling.
• Added readable load and unload sequences with physical VSpin interlocks.
• PLR resource state changes only after the corresponding physical operation succeeds.
• Added idempotent absolute gripper open/close operations while retaining private relative grip
  adjustments.

TCP Access2 support is intentionally deferred. A future implementation can use
pylabrobot.io.Socket without changing the existing FTDI path.

Compatibility

The principal PLR interfaces remain intact:

• VSpin.spin(g, duration, acceleration, deceleration)
• go_to_bucket1() and go_to_bucket2()
• VSpin door, bucket-lock, status, and calibration operations
• Access2.load() and Access2.unload()
• Existing FTDI-based construction

Internal helpers and protocol names were refactored repository-wide without deprecation aliases.

[TheBirdAttack]

What would speak against making a Windows-specific exception for VSpin and allowing it to
use the existing COM port/VCP path?

On Windows, the VSpin can appear as a normal virtual COM port. If PyLabRobot could use that directly, users would not have to replace the FTDI driver with libusbK via Zadig. That would also make it much easier to switch back to the original Agilent software, since the manufacturer tools should still be able to find the device through the standard driver path.

I know, this is mainly an operational concern, still we Windows users already suffer enough through Microslop, why make us perform driver archaeology before spinning a plate? ;)

This would also align well with PyLabRobot’s existing IO model, since pylabrobot.io.Serial already supports explicit COM ports and could be used as an optional transport without changing the current FTDI backend.

Something like:

VSpin(name="vspin", device_id="FTDI_SERIAL")  # unchanged default FTDI path
VSpin(name="vspin", serial_port="COM7")       # optional VCP path