Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,6 @@ backend/configs/*.bak

# Local hardware settings and generated browser-test reports
backend/configs/*.local.json
backend/configs/*.persistent.yaml
backend/configs/**/*.persistent.yaml
frontend/playwright-report/
frontend/test-results/
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ to the image in a debug window; no camera hardware and no frontend are needed.

1. `backend/base_config.yaml` is read. `camera_debug_window: true` asks for a window per camera,
and `camera_recording_dir` sets where recordings go.
2. `NEWSWITCH_CONFIG=configs/camTest.json` overrides two settings:
2. `NEWSWITCH_MODE=hardware NEWSWITCH_CONFIG=configs/camTest_config.yaml` overrides two settings:
`use_virtual_microscope: false` (cameras are only used on real hardware) and the device file
`configs/camTest_config.yaml`.
3. `config_io` validates that file, and `adapters.cameras()` finds the camera: a detector
Expand Down Expand Up @@ -150,7 +150,7 @@ to the image in a debug window; no camera hardware and no frontend are needed.
3. Start the backend with the camera configuration, from the repository root:

```bash
NEWSWITCH_CONFIG=configs/camTest.json just dev-backend
NEWSWITCH_MODE=hardware NEWSWITCH_CONFIG=configs/camTest_config.yaml just dev-backend
```

4. A window **"uc2_cam_py debug - Simulated UC2-SIM SN SIM-0001"** opens. It shows a bright
Expand Down Expand Up @@ -184,7 +184,7 @@ rate, binning, ROI). It calls only the registered actions, as the frontend does:

```bash
cd backend
NEWSWITCH_CONFIG=configs/camTest.json BACKEND_PORT=8069 uv run -q python backend_cli.py
NEWSWITCH_MODE=hardware NEWSWITCH_CONFIG=configs/camTest_config.yaml BACKEND_PORT=8069 uv run -q python backend_cli.py
```

`BACKEND_PORT=8069` lets `just dev-frontend` connect at the same time (without it: 8099, as for
Expand Down
10 changes: 9 additions & 1 deletion backend/configs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ virtual microscope keeps its simulated detector.
showing its newest image, and keeps the cameras acquiring from startup (without writing
to disk; `stop_live_view` ends the writing even though the camera keeps acquiring).
- `camTest_config.yaml` is a simulated camera (`manufacturer: Simulated`) for trying it
out without hardware: `NEWSWITCH_CONFIG=configs/camTest.json uvicorn main:app`. Walkthrough:
out without hardware: `NEWSWITCH_MODE=hardware NEWSWITCH_CONFIG=configs/camTest_config.yaml uvicorn main:app`. Walkthrough:
"End-to-end test for camera" in the root `README.md`.

## Stages, axes and wheels
Expand Down Expand Up @@ -217,3 +217,11 @@ flow style and further keys stay; the previous file is kept as `*.bak` (git-igno
- A physical value written as scalar or `null` becomes a mapping.

The app's shutdown hook writes exposure, gain, wheel positions and stage position back.

## Hardware integration demos

Two [reduced test configurations](demos/README.md) isolate Serial and direct CAN
from the main example. Mixed connections and axes on different controllers are
already demonstrated in `newswitch-config.yaml`. The main example additionally
contains a CAN LED-matrix mapping. The demo README documents the supported runtime
contract, startup commands and unsupported bridge/camera/wheel cases.
2 changes: 1 addition & 1 deletion backend/configs/camTest_config.yaml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Test configuration: one simulated camera through uc2_cam_py (no hardware needed).
#
# The camera manager is only used on real hardware, so start the backend with
# NEWSWITCH_CONFIG=configs/camTest.json
# NEWSWITCH_MODE=hardware NEWSWITCH_CONFIG=configs/camTest_config.yaml
# (needs the extra "camera": uv sync --extra camera). Stage and illumination then look for
# a UC2 board and keep retrying without one; the camera works regardless.
#
Expand Down
111 changes: 111 additions & 0 deletions backend/configs/demos/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
# UC2 hardware from controller mappings

These two files are reduced from `../newswitch-config.yaml`. They use Christian's
standalone axes, stage references and controller mappings. The runtime adapter in
`newswitch/managers/uc2/yaml_runtime.py` consumes their addresses and parameters.

| File | Motion | Illumination |
| --- | --- | --- |
| `uc2-serial.yaml` | X/Z through one Serial master | Laser, LED and RGB matrix on the same master |
| `uc2-canopen.yaml` | X/Z on direct CAN, nodes 11/22 | Laser/LED on node 21 and matrix on node 20 |

All addresses/calibration values are illustrative. Replace them for the actual
machine before connecting hardware. Automated tests use fake clients, not motors.

## Start

From `backend`:

```bash
uv sync --extra uc2
uv run python -m newswitch.config_io configs/demos/uc2-serial.yaml
NEWSWITCH_MODE=hardware NEWSWITCH_CONFIG=configs/demos/uc2-serial.yaml uv run uvicorn main:app --port 8099
# Or select configs/demos/uc2-canopen.yaml for direct CAN.
```

`NEWSWITCH_CONFIG` selects a device YAML, not a legacy JSON settings file. Relative
paths resolve against `backend`. The input is never overwritten; positions are
written to a separate `<name>.persistent.yaml` next to it. Base settings still work
without environment overrides; `base_config.yaml` selects the default mode and
device file (currently hardware mode with the simulated-camera profile). A custom
`config_file` passed to ImswitchConfig is honored by startup and shutdown too.

The old `uc2_*` hardware overrides are rejected in real mode if set to nondefault
values. Hardware addresses and mechanics must have one authority: the device YAML.
The old flat JSON files and import-script output are not supported startup files.

## Supported mapping contract

| Connection / mapping type | Address |
| --- | --- |
| `uc2-rest` + `serial-motor` | `id`: master stepper ID 0=A, 1=X, 2=Y, 3=Z; `subid` must be 0 |
| `uc2-rest` + `serial-laser` | `id`: master light/PWM channel 0..3; `subid` must be 0 |
| `uc2-rest` + `serial-led-matrix` | One matrix; required placeholder `id: 0`; `subid: 0` |
| `canopen` + `canopen-motor` | `id`: CAN node 1..127; `subid`: zero-based motor index 0..3 |
| `canopen` + `canopen-laser` | `id`: CAN node 1..127; `subid`: zero-based PWM channel |
| `canopen` + `canopen-led-matrix` | `id`: matrix CAN node; default `subid: 0` is unused |

`serial-motor` explicitly selects the known `/motor_act` master-ID interface. It
is a backend addressing contract, not a claim about wiring behind the master.
The old illustrative `canopen-motor {id: 0, subid: ...}` on a Serial controller is
ambiguous and rejected. We do not guess how to translate it. Explicit SDO routes
through a Serial bridge (`/can_act`) need a confirmed firmware contract first.
The runtime names can be adapted once the team agrees on a different schema/domain
vocabulary; no downstream addresses are inferred from device names.

The logical stage direction does not have to match the master's physical axis:
X may refer to a motor with master ID 2, and feedback is translated back to X.
A logical linear axis can use master ID 0, with linear scaling supplied by its own
AxisConfig. Logical X/Y/Z/A use linear units (um) in this YAML adapter;
angular motion/units on A/rx/ry/rz are not supported yet.

A PWM-driven LED uses the same `serial-laser` / `canopen-laser` API as a laser.
`pwm_max` supplies the raw range for each PWM output; it is not guessed or read
from hardware. Application intensity is 0..100 percent. `channels` on a source
means color/spectral count (1 for a PWM output, 3 for an RGB matrix), not an address.
Matrix fill uses 0..255 per RGB channel, and its illumination slider fills gray.
The current matrix convenience API supports exactly one matrix per microscope.

Motor and laser IDs form separate namespaces on Serial: both can use ID 1 on the
same master. Duplicate outputs across logical controllers sharing a physical link
are rejected. One pooled client owns each used physical connection; controllers
sharing it must agree on protocol and transport settings.

## Motion, connection and startup behavior

- Calibration (`steps_per_um`), inversion, travel limits, velocity and acceleration
are taken from each axis. Values in compatible units are converted by config_io.
jerk and axes with no step calibration are rejected by this UC2 runtime.
- Optional `move_timeout_s` (default 120), `homing_speed_steps`,
`homing_direction` and `homing_timeout_ms` are typed axis fields. Homing speed is
already in hardware steps/s; ordinary velocity/acceleration are in physical units.
- `homing_required` blocks movement until a successful home. Homing is explicitly
requested, never automatic. An explicit `homing_order` runs sequentially;
`null` uses parallel homing as specified by the model.
- Commands on one axis are serialized; axes on different controllers can move
together. Cancellation/error cancels sibling moves and attempts to stop motors.
Completion means reported controller completion, not independent encoder proof.
- Outputs are switched off before a connection becomes available and again on
reconnection. Previous brightness is not automatically restored. Reconnect and
motion errors invalidate reference status.
- Serial selectors must match exactly one port (explicit ports can reconnect if
temporarily absent). Unsupported transport/request settings fail explicitly.
Direct CAN currently supports SocketCAN and Waveshare USB-CAN-A.
- Camera mappings are passed independently to Christian's `build_detector_manager`
and `UC2DetectorManager` (`uv sync --extra camera` on supported Linux/Python 3.12
systems). Its warning-and-virtual-fallback behavior when the library is absent is
retained. With no cameras configured the hardware path exposes no fake camera.
Actuated wheels and undefined Serial bridge mappings remain unsupported; the
broad main example still contains these and is not a ready-made startup file.

## Mixed devices and split stages

No third demo is needed: to combine these files, keep one StageConfig and its axis
entries, then place each axis/light mapping in the controller that serves it.
The adapter resolves controller_of(axis_key) independently for every axis. Thus
X can be on Serial while Z and all illumination share CAN. Integration tests cover
this split-stage case, pooling, feedback remapping, failures and startup.

```bash
uv run pytest tests/test_yaml_hardware.py -q
```
89 changes: 89 additions & 0 deletions backend/configs/demos/uc2-canopen.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
# Reduced hardware configuration using controller mappings.
# Replace illustrative ports, addresses and calibration before physical use.
newswitch_version: v1.0.2
devices:
my-hat-board-via-can:
type: controller
name: CAN_HAT
manufacturer: someDude
connection:
protocol: canopen
transport:
type: can
interface: socketcan
channel: can0
bitrate: 500000
mapping:
my-first-axis:
type: canopen-motor
id: 11
subid: 0
my-second-axis:
type: canopen-motor
id: 22
subid: 0

my-laser-serial:
type: canopen-laser
id: 21
subid: 1
pwm_max: 1023
top-illumination-LED:
type: canopen-laser
id: 21
subid: 0
pwm_max: 1023
led-matrix:
type: canopen-led-matrix
id: 20
just-some-boring-stage:
type: stage
name: xyz-linear-100
manufacturer: openUC2
homing_order: [z, x]
axes:
x: my-first-axis
z: my-second-axis

my-first-axis:
type: axis
steps_per_um: 8.0
homing_required: true
pos: {min: 0.0, max: 100000.0, unit: um}
vel: {value: 5000.0, unit: um/s}
optikit_dsn_variable: sample-x

my-second-axis:
type: axis
name: scanning-axis
manufacturer: openUC2
steps_per_um: 8.0
pos: {min: 0.0, max: 100000.0, unit: um}
vel: {value: 5000.0, unit: um/s}
optikit_dsn_variable: sample-z

my-laser-serial:
type: lightsource
name: boison-488
manufacturer: Boison
wavelength: 488
bandwidth: 2.0
spec_shape: gauss
coherence: coherent

top-illumination-LED:
type: lightsource
name: cool-led
manufacturer: TheLEDCompany
wavelength: 193
bandwidth: 200
spec_shape: gauss

# RGB matrix, routed through its controller mapping.
led-matrix:
type: lightsource
name: RGB LED matrix
channels: 3
coherence: incoherent

# --- STAGES, AXES AND WHEELS ---
84 changes: 84 additions & 0 deletions backend/configs/demos/uc2-serial.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
# Reduced hardware configuration using controller mappings.
# Replace illustrative ports, addresses and calibration before physical use.
newswitch_version: v1.0.2
devices:
my-standalone-board:
type: controller
name: UC2-Mainboard-v4
manufacturer: openUC2
connection:
protocol: uc2-rest
transport:
type: serial
baudrate: 921600
port: /dev/ttyUSB0
firmware:
name: esp32-uc2-standalone-4
version: v2026.0.0-beta.3
mapping:
my-first-axis:
type: serial-motor
id: 1
my-second-axis:
type: serial-motor
id: 3
my-laser-serial:
type: serial-laser
id: 2
pwm_max: 1023
top-illumination-LED:
type: serial-laser
id: 3
pwm_max: 1023
led-matrix:
type: serial-led-matrix
id: 0
just-some-boring-stage:
type: stage
name: xyz-linear-100
manufacturer: openUC2
homing_order: [z, x]
axes:
x: my-first-axis
z: my-second-axis

my-first-axis:
type: axis
steps_per_um: 8.0
homing_required: true
pos: {min: 0.0, max: 100000.0, unit: um}
vel: {value: 5000.0, unit: um/s}
optikit_dsn_variable: sample-x

my-second-axis:
type: axis
name: scanning-axis
manufacturer: openUC2
steps_per_um: 8.0
pos: {min: 0.0, max: 100000.0, unit: um}
vel: {value: 5000.0, unit: um/s}
optikit_dsn_variable: sample-z

my-laser-serial:
type: lightsource
name: boison-488
manufacturer: Boison
wavelength: 488
bandwidth: 2.0
spec_shape: gauss
coherence: coherent

top-illumination-LED:
type: lightsource
name: cool-led
manufacturer: TheLEDCompany
wavelength: 193
bandwidth: 200
spec_shape: gauss

# RGB matrix, routed through its controller mapping.
led-matrix:
type: lightsource
name: RGB LED matrix
channels: 3
coherence: incoherent
Loading
Loading