add kx2 backend

docs/api/pylabrobot.paa.rst

@@ -0,0 +1,19 @@
+.. currentmodule:: pylabrobot.paa
+
+pylabrobot.paa package
+======================
+
+KX2
+---
+
+.. currentmodule:: pylabrobot.paa.kx2
+
+.. autosummary::
+  :toctree: _autosummary
+  :nosignatures:
+  :recursive:
+
+    KX2
+    KX2BarcodeReader
+    KX2Config
+    Axis

docs/api/pylabrobot.rst

@@ -43,6 +43,7 @@ Manufacturers
     pylabrobot.mettler_toledo
     pylabrobot.molecular_devices
     pylabrobot.opentrons
+    pylabrobot.paa
     pylabrobot.qinstruments
     pylabrobot.tecan
     pylabrobot.thermo_fisher

docs/user_guide/index.md

@@ -41,6 +41,7 @@ liconic/index
 mettler_toledo/index
 molecular_devices/index
 opentrons/index
+paa/index
 qinstruments/index
 thermo_fisher/index
 ufactory/index

docs/user_guide/paa/index.md

@@ -0,0 +1,11 @@
+# PAA
+
+```{toctree}
+:maxdepth: 1
+
+kx2/installation
+kx2/hello-world
+kx2/continuous-motion
+kx2/proximity-sensor
+kx2/barcode-reader
+```

docs/user_guide/paa/kx2/barcode-reader.ipynb

@@ -0,0 +1,181 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "kx2-bcr-intro",
+   "metadata": {},
+   "source": [
+    "# KX2 Barcode Reader\n",
+    "\n",
+    "The KX2's onboard barcode reader is a serial 1D laser scanner wired to the controller PC. It's fully independent of the CAN motor stack, so it works even with the arm e-stopped — exposed as its own {class}`~pylabrobot.paa.kx2.KX2BarcodeReader` `Device`.\n",
+    "\n",
+    "The model that ships with KX2 systems we've inspected is a **Denso MDI-4050** (firmware reports as `BD01J09`). Factory defaults: **9600 8N1**, no flow control. Find your port with `python -m serial.tools.list_ports -v`.\n",
+    "\n",
+    "### macOS: USB-to-serial driver\n",
+    "\n",
+    "The reader cable is typically a Prolific PL2303. macOS bundles a driver for older variants but not the newer GC/HXN chip (USB ID `067b:23a3`). If the device doesn't show up at `/dev/tty.PL2303G-USBtoUART<n>` after plugging it in:\n",
+    "\n",
+    "```bash\n",
+    "brew install --cask prolific-pl2303\n",
+    "open -a PL2303Serial      # registers the system extension\n",
+    "```\n",
+    "\n",
+    "Then **System Settings → Privacy & Security → Allow** on the \"System software from PL2303Serial was blocked\" prompt, restart if asked, and replug the cable. Verify with `systemextensionsctl list`: `com.prolific.cdc.PLCdcFSDriver` should show `[activated enabled]`.\n",
+    "\n",
+    "### Symbologies\n",
+    "\n",
+    "The MDI-4050 is a 1D laser, so **PDF417 / DataMatrix / QR Code aren't supported** — you'd need the 2D imager variants (e.g. MDI-4150) for those.\n",
+    "\n",
+    "Typical out-of-the-box 1D enables: UPC-A, UPC-E, EAN-13, EAN-8, Code 39, Tri-Optic, Codabar, Industrial 2/5, Interleaved 2/5, IATA, Code 128, Code 93, GS1 DataBar, GS1 DataBar Limited. Add-on (supplemental) codes, postal codes, MSI/Plessey, Telepen, UK/Plessey, and Code 11 are off by default.\n",
+    "\n",
+    "You can read your unit's full configuration over the wire — model, firmware, every per-symbology enable flag, prefixes/suffixes, and length limits — via `dump_config()` (which sends `Z4`):\n",
+    "\n",
+    "```python\n",
+    "text = await bcr.driver.dump_config()\n",
+    "print(text[:200])  # header has MODEL / ROM Ver. / I/F\n",
+    "```\n",
+    "\n",
+    "To **change** which symbologies are enabled, three options in order of practicality:\n",
+    "\n",
+    "1. **Denso's MDI Setup utility** (free Windows download from Denso ADC) — checkbox UI, talks to the reader over the same serial port, writes to NVRAM.\n",
+    "2. **Configuration barcodes** printed in the MDI-4050 setting manual — scan a Start → toggle → End sequence; no host required.\n",
+    "3. Direct register writes via the ESC protocol — possible but the per-symbology byte layout is documented only in Denso's protocol manual.\n",
+    "\n",
+    "{class}`~pylabrobot.resources.barcode.Barcode` returned from `scan()` has `symbology=\"ANY 1D\"` by default — the reader doesn't emit a symbology ID unless prefix/suffix bytes are configured to include one."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e7a9907a",
+   "source": "## Integrated with the arm\n\nWhen you construct the arm with a `barcode_port`, the `KX2` owns the reader and manages its lifecycle: `kx2.setup()` opens the port and runs the handshake, `kx2.scan_barcode(read_time=8)` returns a {class}`~pylabrobot.resources.barcode.Barcode` (or `None` on a no-read), and `kx2.stop()` tears it down.\n\n```python\nfrom pylabrobot.paa.kx2 import KX2\n\nkx2 = KX2(barcode_port=\"/dev/tty.PL2303G-USBtoUART11240\")\nawait kx2.setup()\nbarcode = await kx2.scan_barcode(read_time=8)\nawait kx2.stop()\n```\n\nThe standalone {class}`~pylabrobot.paa.kx2.KX2BarcodeReader` below drives the reader on its own — useful when the arm is e-stopped, or when there's no arm at all.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "markdown",
+   "id": "kx2-bcr-setup-header",
+   "metadata": {},
+   "source": [
+    "## Setup\n",
+    "\n",
+    "Pass the serial port path. `setup()` opens the port, does the `Z1` software-version handshake, and puts the reader into single-trigger mode."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "kx2-bcr-setup-code",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pylabrobot.paa.kx2 import KX2BarcodeReader\n",
+    "\n",
+    "bcr = KX2BarcodeReader(port=\"/dev/tty.PL2303G-USBtoUART11240\")\n",
+    "await bcr.setup()\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "kx2-bcr-scan-md",
+   "metadata": {},
+   "source": [
+    "`scan(read_time=...)` fires the trigger and waits up to `read_time + 1s` for the reader to decode something. Omit `read_time` to use whatever read window is currently programmed on the reader. Returns a {class}`~pylabrobot.resources.barcode.Barcode`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "kx2-bcr-scan-code",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "barcode = await bcr.barcode_scanning.scan(read_time=8)\n",
+    "print(barcode.data)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "kx2-bcr-config-md",
+   "metadata": {},
+   "source": [
+    "Change the trigger mode at runtime:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "kx2-bcr-config-code",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# \"single\" (default), \"multiple\" (two reads per trigger), or \"continuous\".\n",
+    "# await bcr.set_read_mode(\"continuous\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "kx2-bcr-driver-md",
+   "metadata": {},
+   "source": [
+    "For raw vendor commands or the auto-trigger mode (reader fires on its own), go through `bcr.driver`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "kx2-bcr-driver-code",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(await bcr.driver.get_software_version())\n",
+    "\n",
+    "# Full NVRAM dump — model, firmware, all symbology enables, prefixes/suffixes, length limits.\n",
+    "config = await bcr.driver.dump_config()\n",
+    "print(config[:200])\n",
+    "\n",
+    "# await bcr.driver.set_auto_trigger(True)   # reader scans on its own\n",
+    "# await bcr.driver.set_auto_trigger(False)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "kx2-bcr-teardown-header",
+   "metadata": {},
+   "source": [
+    "## Teardown\n",
+    "\n",
+    "`stop()` sends `Y` (trigger off) and `Y2` (reset to a 2s read window), then closes the serial port — leaving the reader in a known state for the next session."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "kx2-bcr-teardown-code",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "await bcr.stop()\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "env",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.15"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}