Improve GenTL trigger routing safety and tests

Make GenTLCameraBackend trigger configuration more robust and adjust tests.

- Use the waits_for_hardware_trigger property when converting GenTL timeouts to user-facing errors instead of inferring from the role string.
- Read and record the configured trigger role early in _configure_trigger_input.
- Check results when setting TriggerSelector, TriggerSource and TriggerActivation (selector_ok, source_ok, activation_ok). If selector/source routing fails in non-strict mode, disable the trigger, reset internal trigger state and log a warning to avoid arming the camera on a previous/default input line. If activation fails, warn and continue using the camera default.
- If enabling TriggerMode=On fails, disable the trigger and reset internal state instead of only warning.
- Validate LineMode and LineSource when configuring master output and log if configuration is incomplete.

Tests updated to reflect safety changes:
- Expect waits_for_hardware_trigger to be set for external input configuration.
- Rename and change a non-strict invalid-source test to assert the trigger is disabled, waits_for_hardware_trigger is False, and trigger_actual is persisted as off.
- Add a new test ensuring an invalid selector in non-strict mode disables the trigger and persists the off state.

These changes prevent the camera from being left armed on an unintended/default input if routing nodes could not be applied, improving safety and predictability.

Author: C-Achard

dlclivegui/cameras/backends/gentl_backend.py

@@ -498,8 +498,7 @@ def read(self) -> tuple[np.ndarray, float]:
                 except ValueError:
                     frame = array.copy()
         except HarvesterTimeoutError as exc:
-            role = str(self._trigger_attr(getattr(self, "_trigger", None), "role", "off") or "off").lower()
-            if role in {"external", "follower"}:
+            if self.waits_for_hardware_trigger:
                 raise TimeoutError(str(exc) + " (GenTL timeout; waiting for hardware trigger?)") from exc
             raise TimeoutError(str(exc) + " (GenTL timeout)") from exc
 
@@ -1123,24 +1122,59 @@ def _configure_trigger_off(self, node_map, *, strict: bool = False) -> None:
         self._set_enum_node(node_map, "TriggerMode", "Off", strict=strict)
 
     def _configure_trigger_input(self, node_map, cfg, *, strict: bool = False) -> None:
+        role = str(self._trigger_attr(cfg, "role", "external") or "external").strip().lower()
         selector = str(self._trigger_attr(cfg, "selector", "FrameStart") or "FrameStart")
         source = str(self._trigger_attr(cfg, "source", "Line0") or "Line0")
         activation = str(self._trigger_attr(cfg, "activation", "RisingEdge") or "RisingEdge")
 
         # Disable trigger while changing trigger-related nodes.
         self._set_enum_node(node_map, "TriggerMode", "Off", strict=False)
 
-        self._set_enum_node(node_map, "TriggerSelector", selector, strict=strict)
-        self._set_enum_node(node_map, "TriggerSource", source, strict=strict)
-        self._set_enum_node(node_map, "TriggerActivation", activation, strict=strict)
+        selector_ok = self._set_enum_node(node_map, "TriggerSelector", selector, strict=strict)
+        source_ok = self._set_enum_node(node_map, "TriggerSource", source, strict=strict)
+        activation_ok = self._set_enum_node(node_map, "TriggerActivation", activation, strict=strict)
+
+        # TriggerSelector and TriggerSource are required routing nodes.
+        # If either failed in non-strict mode, do not arm TriggerMode=On.
+        # Otherwise the camera may wait on a previous/default input line.
+        if not (selector_ok and source_ok):
+            LOG.warning(
+                "Could not apply GenTL trigger input routing "
+                "(selector_ok=%s, source_ok=%s); disabling trigger. "
+                "requested role=%s selector=%s source=%s activation=%s",
+                selector_ok,
+                source_ok,
+                role,
+                selector,
+                source,
+                activation,
+            )
+            self._configure_trigger_off(node_map, strict=False)
+            self._trigger = CameraTriggerSettings()
+            return
+
+        if not activation_ok:
+            LOG.warning(
+                "Could not apply GenTL TriggerActivation=%s; using camera default/current activation.",
+                activation,
+            )
 
         self._set_enum_node(node_map, "AcquisitionMode", "Continuous", strict=False)
 
         if not self._set_enum_node(node_map, "TriggerMode", "On", strict=strict):
-            if strict:
-                raise RuntimeError("Could not enable GenTL TriggerMode=On")
-            else:
-                LOG.warning("Could not enable GenTL TriggerMode=On; trigger mode may not be correctly configured.")
+            LOG.warning("Could not enable GenTL TriggerMode=On; disabling trigger.")
+            self._configure_trigger_off(node_map, strict=False)
+            self._trigger = CameraTriggerSettings()
+            return
+
+        LOG.info(
+            "GenTL trigger input configured: role=%s selector=%s source=%s activation=%s activation_ok=%s",
+            role,
+            selector,
+            source,
+            activation,
+            activation_ok,
+        )
 
         LOG.info(
             "GenTL trigger input configured: role=%s selector=%s source=%s activation=%s",
@@ -1174,8 +1208,16 @@ def _configure_trigger_master(self, node_map, cfg, *, strict: bool = False) -> N
             )
             return
 
-        self._set_enum_node(node_map, "LineMode", "Output", strict=strict)
-        self._set_enum_node(node_map, "LineSource", output_source, strict=strict)
+        mode_ok = self._set_enum_node(node_map, "LineMode", "Output", strict=strict)
+        source_ok = self._set_enum_node(node_map, "LineSource", output_source, strict=strict)
+
+        if not (mode_ok and source_ok):
+            LOG.warning(
+                "GenTL trigger master output configuration incomplete (LineMode ok=%s, LineSource ok=%s).",
+                mode_ok,
+                source_ok,
+            )
+            return
 
         LOG.info(
             "GenTL trigger master configured: output_line=%s output_source=%s",

tests/cameras/backends/test_gentl_trigger.py

@@ -75,6 +75,7 @@ def test_trigger_external_configures_input_line_and_timeout(patch_gentl_sdk, gen
     assert nm.TriggerSource.value == "Line0"
     assert nm.TriggerActivation.value == "RisingEdge"
     assert nm.TriggerMode.value == "On"
+    assert be.waits_for_hardware_trigger is True
     assert be._timeout == pytest.approx(10.0)
 
     ns = settings.properties["gentl"]
@@ -140,7 +141,7 @@ def test_trigger_master_configures_output_line_and_keeps_trigger_off(patch_gentl
     be.close()
 
 
-def test_trigger_invalid_source_non_strict_does_not_crash(patch_gentl_sdk, gentl_settings_factory):
+def test_trigger_invalid_source_non_strict_disables_trigger(patch_gentl_sdk, gentl_settings_factory):
     gb = patch_gentl_sdk
 
     settings = _gentl_trigger_settings(
@@ -158,9 +159,17 @@ def test_trigger_invalid_source_non_strict_does_not_crash(patch_gentl_sdk, gentl
 
     # Source was unsupported, so the fake node should retain its default.
     assert nm.TriggerSource.value == "Line0"
-    # Non-strict mode should still allow opening; TriggerMode may be enabled
-    # because TriggerSource failure is best-effort in this mode.
-    assert be._acquirer is not None
+
+    # Safety behavior: do not arm TriggerMode on the previous/default source.
+    assert nm.TriggerMode.value == "Off"
+
+    # Controller should not treat timeouts as expected trigger waits.
+    assert be.waits_for_hardware_trigger is False
+
+    # trigger_actual is persisted after _configure_trigger(); since we reset
+    # self._trigger to off, the effective trigger state is off.
+    actual = settings.properties["gentl"]["trigger_actual"]
+    assert actual["role"] == "off"
 
     be.close()
 
@@ -331,3 +340,35 @@ def test_trigger_actual_is_persisted_for_debugging(patch_gentl_sdk, gentl_settin
     assert actual["timeout"] == pytest.approx(9.0)
 
     be.close()
+
+
+def test_trigger_invalid_selector_non_strict_disables_trigger(patch_gentl_sdk, gentl_settings_factory):
+    gb = patch_gentl_sdk
+
+    settings = _gentl_trigger_settings(
+        gentl_settings_factory,
+        {
+            "role": "external",
+            "selector": "NotARealSelector",
+            "source": "Line1",
+            "strict": False,
+        },
+    )
+    be = gb.GenTLCameraBackend(settings)
+
+    be.open()
+    nm = be._acquirer.remote_device.node_map
+
+    # Selector was unsupported, so the fake node should retain its default.
+    assert nm.TriggerSelector.value == "FrameStart"
+
+    # Source may have been applied, but trigger must not be armed because
+    # the required selector routing failed.
+    assert nm.TriggerSource.value == "Line1"
+    assert nm.TriggerMode.value == "Off"
+    assert be.waits_for_hardware_trigger is False
+
+    actual = settings.properties["gentl"]["trigger_actual"]
+    assert actual["role"] == "off"
+
+    be.close()