Plesty KST201 Device

PLESTY device module for a three-axis XYZ stage built from three Thorlabs KST201 K-Cube stepper motor controllers, each driving a ZST225 25 mm linear actuator, spoken to over the APT serial protocol. One server drives the whole stage: there is one device, one TCP port, and the axes are told apart by name (x, y, z). All positions are in millimetres.

Supported hardware

On macOS nothing claims the Thorlabs FTDI product id, so the controller cannot be reached there. The start-up preflight refuses non-Windows hosts with that explanation. --mock is exempt.

Installation

git clone https://gitlab.com/plesty/hub/devices/thorlab/plesty-kst201.git
cd plesty-kst201
uv sync

Quick start

# Real stage (Windows): server on TCP port 5555
DEVICE_SERIAL_X=... DEVICE_SERIAL_Y=... DEVICE_SERIAL_Z=... \
  uv run python -m plesty.kst201 --tcp-port 5555

# No hardware: serve three in-memory APT motor simulators
uv run python -m plesty.kst201 --tcp-port 5555 --mock

Picking the controllers

Each axis is its own controller, chosen by its serial number. Per axis, the first of these that is set wins:

1. --serial-x / --serial-y / --serial-z
2. DEVICE_SERIAL_X / DEVICE_SERIAL_Y / DEVICE_SERIAL_Z
3. running.axes.<axis>.serial in the packaged config.yaml (empty; never commit a real serial, this repository is public)

All three axes are required. The preflight refuses to start the server, naming the axis that has no serial, shares one with another axis, or is not found, and lists every serial it saw over COM ports and over D2XX so you can pick the right one. A controller is opened through the COM port that carries its serial; if none does, through the FTDI D2XX device with that serial.

Copy .env.example to .env for the same settings in a file.

Schema reference

Parameters (groups x, y, z)

Every axis has the same five parameters, keyed <axis>.<name>, e.g. x.MaxVelocity.

Functions

axis is "x", "y" or "z". A move touches only the axis it names. A target outside the 0 to 25 mm travel raises ValueError before any traffic is sent.

The generated reference pages in docs/ list the full schema.

Communication

APT binary protocol over USB (FTDI 0403:FAF0), connect timeout 5 s, move timeout 60 s (config.yaml).

On Windows with Thorlabs Kinesis installed the controller is bound to FTDI's D2XX driver and has no COM port. The module then opens it through D2XX (the ftd2xx package, installed with the module on Windows): no "Load VCP" setting is needed. Close Kinesis first, since it holds the controller while it runs. A controller that does have a COM port is still reached through it.

Status and open points

• Count scaling comes from pylablib's encoding of the Thorlabs table, not from the primary APT protocol PDF; confirm against the PDF.
• Homing, limit-switch and button parameters stored on the controller are not read or written; the controller keeps its own Kinesis settings.
• Velocity and acceleration limits are conservative, below the actuator's rating.