new ui hardware cal

Author: CamDavidsonPilon

AGENTS.md

@@ -12,26 +12,21 @@
   - `static/vid/` houses mp4/gif assets that can be linked directly from documentation.
   - Files placed under `static/` are copied verbatim to the built site, so maintain clean filenames and avoid private data.
 - **Automation and build scripts** rely on the standard Docusaurus npm scripts defined in `package.json` (e.g., `npm run start`, `npm run build`).
+- For user-guide docs, images live under `static/img/user-guide/<section>/<page>/`.
+- `<section>` is the slugified first folder under `user-guide/`, and `<page>` is the slugified markdown filename.
+- Example: for `user-guide/03-Extending your Pioreactor/02-Calibrations/08-hardware-calibrations.md`, the standard image directory is:
+    - `static/img/user-guide/03-extending-your-pioreactor/08-hardware-calibrations/`
+    - A referenced image would be: `/img/user-guide/03-extending-your-pioreactor/08-hardware-calibrations/<image>.png`
 
-## Screenshot guidelines
-- Screenshots are committed as PNGs and grouped in sub-folders under `static/img/` (for example `static/img/user-guide/`).
-- Existing screenshots are usually high-resolution captures taken from the Pioreactor UI; the common sizes range from ~1400×750 up to ~3200×1650 to keep interface text legible on Retina displays.
-- When adding new screenshots:
-  - Capture the full relevant UI panel without cropping away context, and prefer light-theme UI unless the article explicitly targets dark-theme behavior.
-  - Export as PNG to preserve crisp text and UI accents. JPEGs are discouraged unless file size becomes an issue for photos.
-  - Resize or compress only if the asset exceeds several megabytes; `pngquant` works well and keeps transparency intact.
-  - Place the file in the matching doc-area subfolder and reference it with a relative path such as `/img/user-guide/<filename>.png`.
-  - Large assets should be reviewed to ensure no dimensions explode to placeholder values (for example, some legacy `custom_*` assets show `167772160×671088640` metadata and should be replaced if touched).
 
 ## Tech stack
-- The documentation site is built with **Docusaurus 3** on top of **React 18** and MDX content. Styling extends the classic Docusaurus theme via custom CSS in `src/css/`.
+- The documentation site is built with **Docusaurus 3.x** on top of **React 18** and MDX content. Styling extends the classic Docusaurus theme via custom CSS in `src/css/`.
 - JavaScript tooling is managed with **Node.js** and npm. Install dependencies with `npm install` (Node 18+ recommended) and run the local preview with `npm run start`.
 - Search is powered by the `@easyops-cn/docusaurus-search-local` plugin; diagrams and math rendering use `remark-math`/`rehype-katex`.
 
 ## Other helpful notes
 - Follow Docusaurus front-matter conventions (`id`, `title`, `sidebar_label`, `description`) so pages appear in the correct sidebar.
 - Use MDX for interactive examples—React components live in `src/components/` and can be imported into docs when needed.
 - When reusing or adding React components from `src/components/`, prefer existing shared widgets (callouts, tabs, step-by-step helpers) before creating new ones, keep props well-documented in the component file, and ensure styles stay co-located in `src/css/custom.css` or the component's module CSS.
-- For contributor workflow: create descriptive branch names, run `npm run build` locally if you modify configuration or dependencies, and ensure linting/formatting stays consistent with Prettier defaults.
 - Deployment is handled by GitHub Actions, but manual deploys use `USE_SSH=true GIT_USER=<github-username> npm run deploy` as documented in `README.md`.
 - When embedding videos, copy them to `static/vid/` and reference them via HTML `<video>` tags in MDX rather than external hosts (keeps docs offline-friendly).

developer-guide/20-User interface/05-api-reference.md

@@ -14,6 +14,19 @@ sidebar_class_name: sidebar-item--updated
 - File download endpoints return binary bodies; use the response content-type to handle them.
 - Path parameters are shown inline in the endpoint URL.
 - Request/response examples are the canonical shapes; omit optional fields you do not need.
+- Errors have the following schema:
+
+```
+  {
+    "error": "Human-readable error message",
+    "error_info": {
+      "cause": "Human-readable cause (defaults to error if not set)",
+      "remediation": "Suggested fix or next step",
+      "status": integer,
+    }
+  }
+
+```
 
 
 Use `/api/workers/...` for worker-only targets (experiment-scoped jobs/logs) and `/api/units/...` when the leader is also a valid target; both accept `$broadcast` where supported.

developer-guide/20-User interface/06-unit-api-reference.md

@@ -12,6 +12,19 @@ sidebar_class_name: sidebar-item--updated
 - Poll `GET /unit_api/task_results/{task_id}` until `status` is `complete` or `failed`.
 - `$broadcast` may be used in path parameters where documented to target all units/workers.
 - File download endpoints return binary bodies; use the response content-type to handle them.
+- Errors have the following schema:
+
+```
+  {
+    "error": "Human-readable error message",
+    "error_info": {
+      "cause": "Human-readable cause (defaults to error if not set)",
+      "remediation": "Suggested fix or next step",
+      "status": integer,
+    }
+  }
+
+```
 
 
 ## Health Check

static/img/user-guide/03-extending-your-pioreactor/08-hardware-calibrations/pump-calibration-protocol.png

@@ -4,13 +4,6 @@ slug: /hardware-calibrations
 hide_table_of_contents: true
 ---
 
-import AssemblyInstructionBlock from '@site/src/components/AssemblyInstructionBlock';
-import Highlight from '@site/src/components/Highlight';
-import Admonition from '@theme/Admonition';
-
-import * as colors from '@site/src/components/constants';
-
-
 Hardware calibrations serve as a method to get accurate performance from your Pioreactor.
 
 
@@ -20,14 +13,21 @@ Hardware calibrations serve as a method to get accurate performance from your Pi
 This is optional, but can really help stirring performance. Creating a stirring calibration is also very easy, so we recommend it.
 :::
 
-1. Start by filling a Pioreactor vial about 3/4th with water, and place the stirbar inside. Close with lid. Place into the Pioreactor.
-1. We'll perform this routine through your computer's command line. Need help [accessing it](/user-guide/accessing-raspberry-pi)?
-2.  Enter **`ssh pioreactor@<insert unit name>.local`**.
-    *   For example, to calibrate on our Pioreactor named _worker3_, we typed **`ssh pioreactor@worker3.local`**.
-    *   The default password is `raspberry`.
-2. After SSHing into your Pioreactor, enter `pio calibrations run --device stirring`.
-4. The Pioreactor will increment the voltage applied to the motor, and record the RPM. After it's done, it will collect this data into a calibration curve, and store it locally.
-4. At the end, you'll be prompted to set this as the "active" calibration. Select "Yes".
+You'll need:
+
+1. A vial
+2. A stir bar
+3. Liquid (water is fine)
+
+![DC-based stirring calibration protocol in the Protocols page.](/img/user-guide/03-extending-your-pioreactor/08-hardware-calibrations/stirring-calibration-protocol.png)
+
+1. In the **Protocols** page, choose your Pioreactor and select the **stirring** device.
+2. Click **Run protocol** for **DC-based stirring calibration**.
+3. Follow the on-screen flow:
+    1. Insert a vial with a stir bar and the liquid volume you plan to use.
+    2. Confirm stirring is off before starting.
+    3. Let the protocol step through duty cycles while it records RPM.
+4. When the protocol finishes, save the calibration as active if prompted. Otherwise, set it active later from the **Calibrations** page.
 
 You're done! Your stirring RPM should be much more responsive now.
 
@@ -43,24 +43,24 @@ There are three pumps on the Pioreactor: media, alt-media, and waste. You don't
 2. An accurate weighing scale, with accuracy of 0.1g or better.
 3. Container of water
 
+![Duration-based pump calibration protocol in the Protocols page.](/img/user-guide/03-extending-your-pioreactor/08-hardware-calibrations/pump-calibration-protocol.png)
+
 
 :::tip
 [Supplying external power](/user-guide/external-power)? Make sure to plug in your external power **before** pump calibration!
 :::
 
 
-<AssemblyInstructionBlock title="Calibrating the pumps" images={["experiments/turbidostat/ssh_into_unit.png","experiments/turbidostat/run_pump_calc.png"]}>
-
-
-1. We'll perform this routine through your computer's command line. Need help [accessing it](/user-guide/accessing-raspberry-pi)?
-2.  Enter **`ssh pioreactor@<insert unit name>.local`**.
-    *   For example, to calibrate on our Pioreactor named _worker3_, we typed **`ssh pioreactor@worker3.local`**.
-    *   The default password is `raspberry`.
-3. To calibrate the `media_pump`, enter `pio calibrations run --device media_pump`. Likewise for `waste_pump` and `alt_media_pump.`
-4. Follow the prompts to calibrate your pump.
-4. At the end, you'll be prompted to set this as the "active" calibration. Select "Yes".
-
-</AssemblyInstructionBlock>
+1. In the **Protocols** page, choose your Pioreactor and select the pump device you want to calibrate (for example `media_pump`, `waste_pump`, or `alt_media_pump`).
+2. Click **Run protocol** for **Duration-based pump calibration**.
+3. Follow the on-screen flow:
+    1. Review the safety steps for keeping liquids away from the Pioreactor hardware.
+    2. Name the calibration.
+    3. Enter the target volumes to calibrate around (comma-separated values, in mL).
+    4. Optionally adjust PWM settings.
+    5. Place both tubing ends in the water container and prime the pump until the tubing is fully filled.
+    6. For each dispense step, hold the outflow tube above your vial or graduated cylinder, run the pump for the prompted duration, and record the measured volume. Repeat until the protocol completes.
+4. When the protocol finishes, save the calibration as active if prompted. Otherwise, set it active later from the **Calibrations** page.
 
 ## Managing calibrations