feat(big_bear): add BigBear orbital shaker driver

docs/api/pylabrobot.big_bear.rst

@@ -0,0 +1,14 @@
+.. currentmodule:: pylabrobot.big_bear
+
+pylabrobot.big_bear package
+===========================
+
+.. currentmodule:: pylabrobot.big_bear.orbital_shaker
+
+.. autosummary::
+  :toctree: _autosummary
+  :nosignatures:
+  :recursive:
+
+    BigBearOrbitalShaker
+    BigBearError

docs/api/pylabrobot.rst

@@ -34,6 +34,7 @@ Manufacturers
 
     pylabrobot.agilent
     pylabrobot.azenta
+    pylabrobot.big_bear
     pylabrobot.bmg_labtech
     pylabrobot.brooks
     pylabrobot.byonoy

docs/user_guide/big_bear/index.md

@@ -0,0 +1,7 @@
+# BigBear
+
+```{toctree}
+:maxdepth: 1
+
+orbital-shaker/hello-world
+```

docs/user_guide/big_bear/orbital-shaker/hello-world.ipynb

@@ -0,0 +1,133 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "bigbear-intro",
+   "source": "# BigBear Orbital Shaker\n\nThe BigBear orbital shaker is a plate shaker with a serial (RS-232 / ASCII) interface. A single serial line can drive up to 16 shaker positions -- called **nests** -- wired together in a *daisy chain*, each addressed independently.\n\n| Property | Value |\n|---|---|\n| Communication | Serial, ASCII line protocol |\n| Serial settings | 9600 baud, 8 data bits, no parity, 1 stop bit, no handshake |\n| Line terminator | carriage return (`\\r`) |\n| Speed range | 60--3570 rpm |\n| Acceleration | 1--10 (device scale) |\n| Nests per chain | 1--16 |\n\n```{warning}\nThis driver has NOT been tested against hardware in PyLabRobot. The protocol,\nline terminator, and reply formats are reconstructed from the vendor software.\nIf you verify it on a shaker, please open a PR to remove the not-tested warning.\n```",
+   "metadata": {}
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bigbear-daisy-md",
+   "source": "## Daisy chaining\n\nMultiple shaker units share one serial connection: the host talks to the first unit, which is wired to the second, and so on down the chain. Each unit is a **nest** with a 1-based address.\n\nEvery command is addressed with an `@<id>` prefix, where `<id>` is the nest number written in **hexadecimal** -- so nest 10 is `@A` and nest 16 is `@10`. A command reaches only the nest it names; the others ignore it. This lets one port run up to 16 shakers with independent speed, direction, and start/stop.\n\nAt `setup()` the driver:\n\n1. sends `U` to put the chain into daisy-chain (addressing) mode,\n2. sends `~` to ask how many units are present, and\n3. checks that the reported count matches the `num_shakers` you passed.\n\nIf the counts disagree (a unit is off, unplugged, or `num_shakers` is wrong) setup raises a `BigBearError`. Set `num_shakers` to the number of physical units on the chain.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bigbear-setup-md",
+   "source": "## Physical setup\n\nConnect the shaker's serial port to your computer, typically through a USB-to-serial adapter. Chain any additional units in series and give the whole chain a single port.\n\nMake sure the shaker's serial parameters match the driver defaults (9600 baud, 8 data bits, no parity, 1 stop bit, no handshake).",
+   "metadata": {}
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bigbear-connect-md",
+   "source": "## Connect\n\n`setup()` opens the serial port, enters daisy-chain mode, and verifies the shaker count. It also logs the not-tested warning. Pass `num_shakers` to match your chain.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "bigbear-connect-code",
+   "source": "from pylabrobot.big_bear import BigBearOrbitalShaker\n\nshaker = BigBearOrbitalShaker(port=\"/dev/ttyUSB0\", num_shakers=1)  # replace with your port\nawait shaker.setup()",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bigbear-shake-md",
+   "source": "## Start shaking\n\n`start_shaking()` sets the acceleration, speed, and direction for a nest and starts it. Shaking continues until you stop it. `device_id` selects which nest (default 1).",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "bigbear-shake-code",
+   "source": "await shaker.start_shaking(\n    rpm=750,\n    acceleration=3,\n    sequence=\"CW\",\n    device_id=1,\n)",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bigbear-stop-md",
+   "source": "## Stop shaking\n\nStop a single nest with `stop_shaking()`, or every nest on the chain with `stop_all()`.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "bigbear-stop-code",
+   "source": "await shaker.stop_shaking(device_id=1)\n# or, for the whole chain:\n# await shaker.stop_all()",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bigbear-multi-md",
+   "source": "## Driving multiple nests\n\nWith a multi-unit chain, address each nest by its `device_id`. Each runs independently.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "bigbear-multi-code",
+   "source": "# Example for a 3-nest chain (create with num_shakers=3)\n# await shaker.start_shaking(rpm=500, device_id=1)\n# await shaker.start_shaking(rpm=900, sequence=\"CCW\", device_id=2)\n# await shaker.start_shaking(rpm=1200, device_id=3)",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bigbear-home-md",
+   "source": "## Homing\n\nHome a single nest with `find_home()`, or every nest with `home_all()`.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "bigbear-home-code",
+   "source": "await shaker.find_home(device_id=1)\n# or, for the whole chain:\n# await shaker.home_all()",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bigbear-info-md",
+   "source": "## Device info\n\nRead a nest's serial-number fields (`Y`, `X`, `Z`). The reply format is device-defined; the raw fields are returned joined.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "bigbear-info-code",
+   "source": "print(\"Serial number:\", await shaker.get_serial_number(device_id=1))",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bigbear-teardown-md",
+   "source": "## Teardown\n\n`stop()` stops every nest and closes the serial connection.",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "bigbear-teardown-code",
+   "source": "await shaker.stop()",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/user_guide/index.md

@@ -32,6 +32,7 @@ definitions
 
 agilent/index
 azenta/index
+big_bear/index
 bmg_labtech/index
 brooks/index
 byonoy/index

pylabrobot/big_bear/__init__.py

@@ -0,0 +1 @@
+from .orbital_shaker import BigBearError, BigBearOrbitalShaker