Fix Firmware Flashing for merged binaries via USB (#246)

This pull request introduces significant enhancements to the autofocus
functionality in the frontend, adding support for a new hill-climbing
autofocus method, expanding live focus monitoring capabilities, and
improving the user interface for configuring autofocus parameters. It
also includes small updates to documentation and backend API utilities.

**Autofocus Method Enhancements:**

* Added support for hill-climbing autofocus, including UI for selecting
the method, configuring its parameters (initial step, min step,
reduction factor, max iterations), and backend API integration
(`frontend/src/components/AutofocusController.js`,
`frontend/src/axon/experiment-designer/ZFocusDimension.js`,
`frontend/src/backendapi/apiAutofocusControllerHillClimbing.js`).
[[1]](diffhunk://#diff-c3de947737de070529a7c4962892c79fe159cfc6329c99af1f87600bf0398199L163-R188)
[[2]](diffhunk://#diff-c3de947737de070529a7c4962892c79fe159cfc6329c99af1f87600bf0398199R55-R59)
[[3]](diffhunk://#diff-45e9e9a07fe68dc37fa41fbbc4fae253b9599cd23bdee02c65292d4d81cfe513L358-R388)
[[4]](diffhunk://#diff-45e9e9a07fe68dc37fa41fbbc4fae253b9599cd23bdee02c65292d4d81cfe513R532-R552)
[[5]](diffhunk://#diff-45e9e9a07fe68dc37fa41fbbc4fae253b9599cd23bdee02c65292d4d81cfe513R565-R607)
[[6]](diffhunk://#diff-5fe7141615a2256c23b61476b37cbc704ba4ede629a4fabdf4b0a4bd80aa8a2dR1-R43)

* The autofocus parameter UI now conditionally displays controls for
either Z-sweep or hill-climbing, and provides tooltips and explanations
for each method
(`frontend/src/axon/experiment-designer/ZFocusDimension.js`).
[[1]](diffhunk://#diff-45e9e9a07fe68dc37fa41fbbc4fae253b9599cd23bdee02c65292d4d81cfe513L358-R388)
[[2]](diffhunk://#diff-45e9e9a07fe68dc37fa41fbbc4fae253b9599cd23bdee02c65292d4d81cfe513R491)
[[3]](diffhunk://#diff-45e9e9a07fe68dc37fa41fbbc4fae253b9599cd23bdee02c65292d4d81cfe513L475-L492)
[[4]](diffhunk://#diff-45e9e9a07fe68dc37fa41fbbc4fae253b9599cd23bdee02c65292d4d81cfe513R532-R552)
[[5]](diffhunk://#diff-45e9e9a07fe68dc37fa41fbbc4fae253b9599cd23bdee02c65292d4d81cfe513R565-R607)

**Live Focus Monitoring Improvements:**

* Introduced a live focus monitoring section with configurable update
period, focus method, and crop size, as well as a rolling plot of the
last 20 focus values for real-time feedback
(`frontend/src/components/AutofocusController.js`).
[[1]](diffhunk://#diff-c3de947737de070529a7c4962892c79fe159cfc6329c99af1f87600bf0398199R38-R39)
[[2]](diffhunk://#diff-c3de947737de070529a7c4962892c79fe159cfc6329c99af1f87600bf0398199R157-R166)
[[3]](diffhunk://#diff-c3de947737de070529a7c4962892c79fe159cfc6329c99af1f87600bf0398199L263-R419)

**Point List Editor Usability:**

* Added a "Set Z" button in the Point List Editor to quickly set a
point's Z coordinate to the current stage position, improving workflow
efficiency (`frontend/src/axon/PointListEditorComponent.js`).
[[1]](diffhunk://#diff-ee91e602319fa9e01c59ef542d6ebeea361bc859b06e8c47ec7a6440e5068c14R10)
[[2]](diffhunk://#diff-ee91e602319fa9e01c59ef542d6ebeea361bc859b06e8c47ec7a6440e5068c14R44)
[[3]](diffhunk://#diff-ee91e602319fa9e01c59ef542d6ebeea361bc859b06e8c47ec7a6440e5068c14R85-R90)
[[4]](diffhunk://#diff-ee91e602319fa9e01c59ef542d6ebeea361bc859b06e8c47ec7a6440e5068c14L447-R465)

**API Utilities:**

* Added a new backend API utility for probing device state, useful for
verifying firmware after flashing
(`frontend/src/backendapi/apiUC2ConfigControllerProbeDeviceState.js`).

**Documentation:**

* Updated installation instructions in `README.md` to clarify the use of
`uv sync` and provide a recommended workflow.

---------

Co-authored-by: Florian Paproth <florian@paproth.biz>

Author: beniroquai

README.md

@@ -26,6 +26,15 @@ cd ImSwitch
 
 # Create a virtual environment and install ImSwitch with UV
 uv venv
+uv sync
+
+# then start it in headless mode with the API server:
+uv run python main.py --headless --http-port 8001
+```
+
+# Alternative installation with uv pip (not recommended, may cause dependency issues):
+
+```bash
 source .venv/bin/activate
 # Yes, we need to start using `uv sync` instead for reproducible installs with our lockfile...but we're still ignoring the lockfile right now:
 uv pip install -e .[dev]
@@ -130,12 +139,15 @@ uv venv --python /usr/local/bin/python3.11 .venv_x86_311
 
 # Verify architecture
 arch -x86_64 .venv_x86_311/bin/python3.11 -c "import platform; print(platform.machine())"
+uv run main.py --venv .venv_x86_311 --headless --http-port 8001
+```
 # → x86_64
 
 source .venv_x86_311/bin/activate
 uv pip install -e .
 
 # Always launch under x86_64 so Rosetta uses the x86_64 dylibs
+source .venv_x86_311/bin/activate
 arch -x86_64 python main.py --headless --http-port 8001
 ```
 

frontend/src/axon/PointListEditorComponent.js

@@ -7,6 +7,7 @@ import GenericTabBar from "./GenericTabBar";
 //import { FixedSizeList as List } from "react-window";
 
 import * as experimentSlice from "../state/slices/ExperimentSlice";
+import * as positionSlice from "../state/slices/PositionSlice.js";
 
 import apiPositionerControllerMovePositioner from "../backendapi/apiPositionerControllerMovePositioner.js";
 
@@ -40,6 +41,7 @@ const PointListEditorComponent = () => {
 
   // Access global Redux state
   const experimentState = useSelector(experimentSlice.getExperimentState);
+  const positionState = useSelector(positionSlice.getPositionState);
   //console.log("PointListEditorComponent", experimentState);
   //console.log("PointListEditorComponent", experimentState.pointList);
 
@@ -80,6 +82,12 @@ const PointListEditorComponent = () => {
     dispatch(experimentSlice.createPoint(newPoint));
   };
 
+  //##################################################################################
+  const handleSetCurrentZ = (index) => {
+    // Override the point's Z with the current stage Z position from Redux
+    handlePointChanged(index, "z", positionState.z);
+  };
+
   //##################################################################################
   const handleDeleteAll = () => {
     // Update Redux state
@@ -444,7 +452,17 @@ const PointListEditorComponent = () => {
                 </>
               )}
 
-              {/* dummy button*/}
+              {/* Set current Z position */}
+              {viewMode == ViewMode.POSITION && (
+                <Button
+                  sx={{ padding: "0px" }}
+                  onClick={() => handleSetCurrentZ(index)}
+                  title="Set Z to current stage position"
+                >
+                  Set Z
+                </Button>
+              )}
+              {/* Goto button */}
               {viewMode != ViewMode.READONLY && (
                 <Button
                   sx={{ padding: "0px" }}

frontend/src/axon/experiment-designer/ZFocusDimension.js

@@ -355,12 +355,37 @@ const ZFocusDimension = () => {
                 value={parameterValue.autoFocusMode || "software"}
                 onChange={(e) => dispatch(experimentSlice.setAutoFocusMode(e.target.value))}
               >
-                <MenuItem value="software">Software (Z-Sweep)</MenuItem>
+                <MenuItem value="software">Software</MenuItem>
                 <MenuItem value="hardware">Hardware (FocusLock One-Shot)</MenuItem>
               </Select>
             </FormControl>
           </Box>
 
+          {/* Software autofocus method selector */}
+          {parameterValue.autoFocusMode !== "hardware" && (
+            <Box sx={{ mb: 2 }}>
+              <Box sx={{ display: "flex", alignItems: "center", gap: 1, mb: 1 }}>
+                <Typography variant="caption" sx={{ fontWeight: 500 }}>
+                  Software Method
+                </Typography>
+                <Tooltip title="Z-Sweep: scans through a range of Z positions and fits a Gaussian. Hill Climbing: iteratively searches for peak contrast by gradient ascent (faster, fewer images).">
+                  <IconButton size="small">
+                    <InfoIcon fontSize="small" />
+                  </IconButton>
+                </Tooltip>
+              </Box>
+              <FormControl size="small" fullWidth>
+                <Select
+                  value={parameterValue.autoFocusSoftwareMethod || "scan"}
+                  onChange={(e) => dispatch(experimentSlice.setAutoFocusSoftwareMethod(e.target.value))}
+                >
+                  <MenuItem value="scan">Z-Sweep (Scan)</MenuItem>
+                  <MenuItem value="hillClimbing">Hill Climbing</MenuItem>
+                </Select>
+              </FormControl>
+            </Box>
+          )}
+
           {/* Hardware autofocus specific parameters */}
           {parameterValue.autoFocusMode === "hardware" && (
             <>
@@ -463,6 +488,7 @@ const ZFocusDimension = () => {
             {/* Software autofocus parameters */}
             {parameterValue.autoFocusMode !== "hardware" && (
               <>
+                {/* Common parameters (shared by scan and hill climbing) */}
                 <TextField
                   label="Settle Time (s)"
                   type="number"
@@ -472,24 +498,6 @@ const ZFocusDimension = () => {
                   inputProps={{ step: 0.01, min: 0, max: 10 }}
                 />
 
-                <TextField
-                  label="Range (±μm)"
-                  type="number"
-                  size="small"
-                  value={parameterValue.autoFocusRange || 100}
-                  onChange={(e) => dispatch(experimentSlice.setAutoFocusRange(Number(e.target.value)))}
-                  inputProps={{ step: 1, min: 1 }}
-                />
-
-                <TextField
-                  label="Resolution (μm)"
-                  type="number"
-                  size="small"
-                  value={parameterValue.autoFocusResolution || 10}
-                  onChange={(e) => dispatch(experimentSlice.setAutoFocusResolution(Number(e.target.value)))}
-                  inputProps={{ step: 0.1, min: 0.1 }}
-                />
-
                 <TextField
                   label="Crop Size (px)"
                   type="number"
@@ -521,16 +529,80 @@ const ZFocusDimension = () => {
                   inputProps={{ step: 0.1, min: -100, max: 100 }}
                 />
 
-                <FormControlLabel
-                  control={
-                    <Switch
+                {/* Scan-specific parameters */}
+                {(parameterValue.autoFocusSoftwareMethod || "scan") === "scan" && (
+                  <>
+                    <TextField
+                      label="Range (±μm)"
+                      type="number"
                       size="small"
-                      checked={parameterValue.autoFocusTwoStage || false}
-                      onChange={(e) => dispatch(experimentSlice.setAutoFocusTwoStage(e.target.checked))}
+                      value={parameterValue.autoFocusRange || 100}
+                      onChange={(e) => dispatch(experimentSlice.setAutoFocusRange(Number(e.target.value)))}
+                      inputProps={{ step: 1, min: 1 }}
                     />
-                  }
-                  label={<Typography variant="caption">Two-Stage Focus</Typography>}
-                />
+
+                    <TextField
+                      label="Resolution (μm)"
+                      type="number"
+                      size="small"
+                      value={parameterValue.autoFocusResolution || 10}
+                      onChange={(e) => dispatch(experimentSlice.setAutoFocusResolution(Number(e.target.value)))}
+                      inputProps={{ step: 0.1, min: 0.1 }}
+                    />
+
+                    <FormControlLabel
+                      control={
+                        <Switch
+                          size="small"
+                          checked={parameterValue.autoFocusTwoStage || false}
+                          onChange={(e) => dispatch(experimentSlice.setAutoFocusTwoStage(e.target.checked))}
+                        />
+                      }
+                      label={<Typography variant="caption">Two-Stage Focus</Typography>}
+                    />
+                  </>
+                )}
+
+                {/* Hill Climbing-specific parameters */}
+                {(parameterValue.autoFocusSoftwareMethod) === "hillClimbing" && (
+                  <>
+                    <TextField
+                      label="Initial Step (μm)"
+                      type="number"
+                      size="small"
+                      value={parameterValue.autoFocusHillClimbingInitialStep ?? 20}
+                      onChange={(e) => dispatch(experimentSlice.setAutoFocusHillClimbingInitialStep(Number(e.target.value)))}
+                      inputProps={{ step: 1, min: 1, max: 200 }}
+                    />
+
+                    <TextField
+                      label="Min Step (μm)"
+                      type="number"
+                      size="small"
+                      value={parameterValue.autoFocusHillClimbingMinStep ?? 1}
+                      onChange={(e) => dispatch(experimentSlice.setAutoFocusHillClimbingMinStep(Number(e.target.value)))}
+                      inputProps={{ step: 0.1, min: 0.1, max: 50 }}
+                    />
+
+                    <TextField
+                      label="Step Reduction Factor"
+                      type="number"
+                      size="small"
+                      value={parameterValue.autoFocusHillClimbingStepReduction ?? 0.5}
+                      onChange={(e) => dispatch(experimentSlice.setAutoFocusHillClimbingStepReduction(Number(e.target.value)))}
+                      inputProps={{ step: 0.05, min: 0.1, max: 0.9 }}
+                    />
+
+                    <TextField
+                      label="Max Iterations"
+                      type="number"
+                      size="small"
+                      value={parameterValue.autoFocusHillClimbingMaxIterations ?? 50}
+                      onChange={(e) => dispatch(experimentSlice.setAutoFocusHillClimbingMaxIterations(Number(e.target.value)))}
+                      inputProps={{ step: 1, min: 5, max: 200 }}
+                    />
+                  </>
+                )}
               </>
             )}
           </Box>

frontend/src/backendapi/apiAutofocusControllerHillClimbing.js

@@ -0,0 +1,43 @@
+// src/backendapi/apiAutofocusControllerHillClimbing.js
+import createAxiosInstance from "./createAxiosInstance";
+
+/**
+ * Run hill-climbing autofocus via AutofocusController.autoFocusHillClimbing.
+ * Iteratively searches for peak contrast by moving in the gradient direction,
+ * reversing and halving the step on decline, until convergence.
+ *
+ * @param {Object} params - Hill-climbing autofocus parameters
+ * @param {number} [params.initial_step=20] - Starting step size (µm)
+ * @param {number} [params.min_step=1] - Min step size / convergence criterion (µm)
+ * @param {number} [params.step_reduction=0.5] - Factor to reduce step on reversal
+ * @param {number} [params.max_iterations=50] - Max iterations safety limit
+ * @param {number} [params.tSettle=0.1] - Settle time after each Z step (s)
+ * @param {number} [params.nCropsize=2048] - Crop size for focus algorithm
+ * @param {string} [params.focusAlgorithm="LAPE"] - Focus quality algorithm
+ * @param {number} [params.nGauss=0] - Gaussian blur sigma
+ * @param {number} [params.static_offset=0] - Static Z offset after focusing
+ * @returns {Promise<Object>} { status: "started", centerZ, method } or error
+ */
+const apiAutofocusControllerHillClimbing = async (params = {}) => {
+  const axiosInstance = createAxiosInstance();
+
+  const response = await axiosInstance.get(
+    "/AutofocusController/autoFocusHillClimbing",
+    {
+      params: {
+        initial_step: params.initial_step ?? 20,
+        min_step: params.min_step ?? 1,
+        step_reduction: params.step_reduction ?? 0.5,
+        max_iterations: params.max_iterations ?? 50,
+        tSettle: params.tSettle ?? 0.1,
+        nCropsize: params.nCropsize ?? 2048,
+        focusAlgorithm: params.focusAlgorithm ?? "LAPE",
+        nGauss: params.nGauss ?? 0,
+        static_offset: params.static_offset ?? 0,
+      },
+    }
+  );
+  return response.data;
+};
+
+export default apiAutofocusControllerHillClimbing;

frontend/src/backendapi/apiUC2ConfigControllerProbeDeviceState.js

@@ -0,0 +1,31 @@
+import createAxiosInstance from "./createAxiosInstance";
+
+/**
+ * Send {"task":"/state_get"} to a device and return the raw response.
+ * Use this to verify that firmware is running correctly after flashing.
+ * @param {string} port - Serial port device path (e.g. "/dev/ttyACM0")
+ * @param {number} baud - Serial baudrate (115200 or 921600)
+ * @param {number} timeout - Serial read timeout in seconds (default 2.0)
+ * @returns {Promise<Object>} Result with status, state_response, and firmware_ok
+ */
+const apiUC2ConfigControllerProbeDeviceState = async (
+  port,
+  baud = 115200,
+  timeout = 2.0
+) => {
+  const axiosInstance = createAxiosInstance();
+  const response = await axiosInstance.get(
+    "/UC2ConfigController/probeDeviceState",
+    {
+      params: {
+        port: port,
+        baud: baud,
+        timeout: timeout,
+      },
+      timeout: 15000, // 15 seconds
+    }
+  );
+  return response.data;
+};
+
+export default apiUC2ConfigControllerProbeDeviceState;