pycontrol-core 3.0.0b1__tar.gz → 3.0.0b2__tar.gz

{pycontrol_core-3.0.0b1 → pycontrol_core-3.0.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pycontrol-core
-Version: 3.0.0b1
+Version: 3.0.0b2
 Summary: Sans-IO host library for the pyControl behavioural-experiment framework.
 Project-URL: Homepage, https://github.com/pyControl/core
 Author: pyControl contributors

{pycontrol_core-3.0.0b1 → pycontrol_core-3.0.0b2}/docs/changelog.md

@@ -17,6 +17,19 @@
   names, then sync the pyControl framework to the board. The old names are no
   longer exported. Pin mappings are unchanged.
 
+### I2C connectors
+
+- New `pycontrol.hardware.I2CConnector` for 4-pin JST-SH I2C connectors
+  (SparkFun Qwiic / Adafruit STEMMA QT). The six-port H7 breakouts expose one
+  as `board.qwiic`, on the same I2C-1 bus as `port_4`.
+- `VL53L4CD` is now only the sensor: `VL53L4CD(i2c, name, sampling_rate,
+  address=0x29, enable_pin=None, trigger=None)`. It no longer takes a `port` or
+  creates `LED`/`motor` outputs; build those in a nosepoke device instead.
+  `i2c_setup(new_address)` and `begin()` are replaced by the `address` argument
+  and an automatic bring-up at the first run start (or `setup()`), so several
+  sensors on one bus can be constructed independently. Sensors sharing a bus
+  need distinct addresses and enable pins; clashes raise `ValueError`.
+
 ### Add-on naming
 
 - Workspace add-ons live in `addons/task_handlers/`,

{pycontrol_core-3.0.0b1 → pycontrol_core-3.0.0b2}/docs/hardware-definitions.md

@@ -126,6 +126,39 @@ counter.
 Timer and pin ownership lasts for the hardware object's lifetime. Switching a
 port between UART and encoder mode while a task is running is not supported.
 
+## I2C Connectors
+
+Some breakouts have a 4-pin JST-SH I2C connector (SparkFun Qwiic / Adafruit
+STEMMA QT). It is an `I2CConnector` with `SCL`, `SDA` and `I2C` (the bus
+number). The six-port H7 breakouts expose it as `board.qwiic`, wired to
+`port_4`'s DIO_A/DIO_B, so both connectors are the same I2C-1 bus:
+
+```python
+from machine import I2C
+from devices.VL53L4 import VL53L4CD
+
+i2c = I2C(board.qwiic.I2C, freq=400_000)
+tof = VL53L4CD(i2c, "tof", sampling_rate=40)
+```
+
+Create one `I2C` object per bus and pass it to every device on that bus: a
+second `I2C(1, freq=...)` re-clocks the bus for all of them.
+
+## I2C Time-of-Flight Sensors
+
+`VL53L4CD(i2c, name, sampling_rate, address=0x29, enable_pin=None, trigger=None)`
+streams `entrance - distance` (mm) as the analog input `name`. `enable_pin`
+drives the chip's XSHUT pin. The chip is brought up when the first run starts,
+once the task file has constructed every device; call `setup()` at import to
+bring a sensor that is alone on its bus up earlier and report wiring problems
+at upload.
+
+Sensors that share a bus all start at address 0x29, so each needs an
+`enable_pin` and its own `address`. Each constructor holds its chip in reset;
+at run start each chip boots at 0x29 in turn and moves to its own address
+before the next is released. A clashing address, or a sensor without an
+`enable_pin` on a shared bus, raises `ValueError` at construction.
+
 ## Analog sources and DAC buffering
 
 `AnalogInput` records the ADC's raw codes. A plausible trace does not establish

{pycontrol_core-3.0.0b1 → pycontrol_core-3.0.0b2}/src/pycontrol/__init__.py

@@ -1,5 +1,5 @@
 """pycontrol host library: sans-IO core + addon points."""
 
-__version__ = "3.0.0b1"
+__version__ = "3.0.0b2"
 
 __all__ = ["__version__"]

{pycontrol_core-3.0.0b1 → pycontrol_core-3.0.0b2}/src/pycontrol/firmware/devices/VL53L4.py

@@ -48,24 +48,40 @@ _BOOT_S = 0.002  # Datasheet tBOOT: the chip answers on I2C 1.2 ms after XSHUT r
 _BOOT_POLL_ATTEMPTS = 100  # x 1 ms between polls of the firmware status register.
 
 
+# Sensors constructed on each I2C object, so address clashes fail at import.
+_buses = {}
+
+
 class VL53L4CD(AnalogInput):
-    def __init__(self, port, i2c_instance, sampling_rate, nose_event, trigger=None):
-        super().__init__(None, nose_event, int(sampling_rate), data_type="h", triggers=[trigger] if trigger else None)
+    """VL53L4CD time-of-flight sensor, streamed as the analog input `name`.
+
+    Samples are entrance - distance (mm), so they rise as a target approaches.
+    enable_pin drives the chip's XSHUT; while it is low the chip is in reset.
+
+    The chip is brought up when the first run starts, after every device in the
+    task file has been constructed (call setup() to do it earlier). Sensors
+    sharing an I2C bus each need an enable_pin and their own address: every
+    constructor holds its chip in reset, then each chip boots at the default
+    address in turn and is moved to its own before the next is released.
+    """
+
+    def __init__(self, i2c, name, sampling_rate, address=_DEFAULT_I2C_ADDRESS, enable_pin=None, trigger=None):
+        super().__init__(None, name, int(sampling_rate), data_type="h", triggers=[trigger] if trigger else None)
         self.trigger = trigger
         if self.trigger:
-            self.trigger.attached_to = nose_event
-        self.i2c = i2c_instance
+            self.trigger.attached_to = name
+        sharing = _buses.setdefault(id(i2c), [])
+        for other in sharing:
+            if other._target_address == address:
+                raise ValueError("VL53L4CD '{}' and '{}' share address 0x{:02X}.".format(other.name, name, address))
+            if other.enable is None or enable_pin is None:
+                raise ValueError("VL53L4CDs sharing an I2C bus each need an enable_pin.")
+        sharing.append(self)
+        self.i2c = i2c
         self._address = _DEFAULT_I2C_ADDRESS
-        self._target_address = _DEFAULT_I2C_ADDRESS
+        self._target_address = address
         self._powered = False
-
-        self.LED = DigitalOutput(port.POW_A)
-        self.LED.off()
-        self.motor = DigitalOutput(port.POW_B)
-        self.motor.off()
-        assert port.DIO_C is not None, "! VL53L4CD needs a port with DIO_C."
-        self.tof_enable = DigitalOutput(port.DIO_C)
-        self.tof_enable.off()
+        self.enable = DigitalOutput(enable_pin) if enable_pin is not None else None  # Starts off: chip in reset.
 
         self.buffer = bytearray(2)
         self.get_range_packet = struct.pack(">H", 0x0096)
@@ -75,15 +91,12 @@ class VL53L4CD(AnalogInput):
         self._ranging = False
         self.connection_error = False
 
-    def i2c_setup(self, new_address=None):
-        """Reset the chip through XSHUT, initialise it and move it to new_address.
-
-        Every sensor sharing the bus must be held in reset (tof_enable off,
-        which the constructor does) until its own i2c_setup() runs: a reset
-        chip answers at the default address, so two live chips would collide.
-        """
-        self._target_address = new_address or _DEFAULT_I2C_ADDRESS
-        self._power_up()
+    def setup(self):
+        """Reset the chip, initialise it, move it to its address and start ranging."""
+        try:
+            self._power_up()
+        except Exception as exc:
+            raise RuntimeError("Trouble connecting to VL53L4CD '{}': {!r}".format(self.name, exc))
 
     def _power_up(self):
         # XSHUT low is a full hardware reset: it discards the remapped address
@@ -91,23 +104,25 @@ class VL53L4CD(AnalogInput):
         # chip was mid-transaction. The pyboard soft-reset between uploads
         # leaves GPIO state alone, so the chips are otherwise still live at
         # their old addresses when the next task file imports.
-        self.tof_enable.off()
-        time.sleep(_XSHUT_LOW_S)
-        self.tof_enable.on()
-        time.sleep(_BOOT_S)
+        if self.enable:
+            self.enable.off()
+            time.sleep(_XSHUT_LOW_S)
+            self.enable.on()
+            time.sleep(_BOOT_S)
         self._address = _DEFAULT_I2C_ADDRESS
         try:
             self._wait_for_boot()
         except OSError:
             if self._target_address == _DEFAULT_I2C_ADDRESS:
                 raise
-            # Nothing at the default address: XSHUT did not reset the chip, so
-            # it is still running at the address the previous run gave it.
+            # Nothing at the default address: the chip was not reset, so it is
+            # still running at the address the previous run gave it.
             self._address = self._target_address
             self._wait_for_boot()
         self._sensor_init()
         if self._address != self._target_address:
             self.set_address(self._target_address)
+        self.begin()
         self._powered = True
 
     def set_address(self, new_address):
@@ -119,10 +134,15 @@ class VL53L4CD(AnalogInput):
         self.timing_budget = 20
         self.start_ranging()
 
+    def _initialise(self):
+        # Runs once, before the first run's clock starts, after the task file
+        # has constructed every sensor and so put every chip in reset.
+        if not self._powered:
+            self.setup()
+
     def _run_start(self):
-        if not self._powered:  # Re-run without a fresh task import.
-            self._power_up()
-            self.begin()
+        if not self._powered:  # Re-run: _run_stop powered the chip down.
+            self.setup()
         super()._run_start()
 
     def _run_stop(self):
@@ -131,7 +151,8 @@ class VL53L4CD(AnalogInput):
             self.stop_ranging()
         except OSError:
             pass
-        self.tof_enable.off()
+        if self.enable:
+            self.enable.off()
         self._powered = False
 
     def read_sample(self):

pycontrol_core-3.0.0b1/src/pycontrol/firmware/devices/breakout_10port_r0_6_h7.py → pycontrol_core-3.0.0b2/src/pycontrol/firmware/devices/breakout_10port_r0_4_h7.py

@@ -1,12 +1,12 @@
-from pycontrol.hardware import Port, DigitalInput, DigitalOutput
+from pycontrol.hardware import Port, DigitalOutput
 
 # MCU family this breakout's pin geometry is wired for. The host reads it
 # statically (pycontrol.workspace.hwdef_inspect) to pre-flight setups.
 MCU = "stm32h743"
 
 
-class Breakout10PortR0_6H7:
-    """Pin geometry for the ten-port H7 breakout, PCB revision 0.6."""
+class Breakout10PortR0_4H7:
+    """Pin geometry for the ten-port H7 breakout, PCB revision 0.4-0.7"""
 
     def __init__(self):
         self.port_1 = Port(DIO_A="B10", DIO_B="B11", DIO_C="A4", POW_A="C2", POW_B="C3", UART=3, I2C=2, DAC=1)

{pycontrol_core-3.0.0b1 → pycontrol_core-3.0.0b2}/src/pycontrol/firmware/devices/breakout_10port_r0_8_h7.py

@@ -1,4 +1,4 @@
-from pycontrol.hardware import Port, DigitalInput, DigitalOutput
+from pycontrol.hardware import Port, DigitalOutput
 
 # MCU family this breakout's pin geometry is wired for. The host reads it
 # statically (pycontrol.workspace.hwdef_inspect) to pre-flight setups.

pycontrol_core-3.0.0b2/src/pycontrol/firmware/devices/breakout_6port_r0_1_h7.py

@@ -0,0 +1,33 @@
+from pycontrol.hardware import Port, I2CConnector, DigitalOutput
+
+# MCU family this breakout's pin geometry is wired for. The host reads it
+# statically (pycontrol.workspace.hwdef_inspect) to pre-flight setups.
+MCU = "stm32h743"
+
+
+class Breakout6PortR0_1H7:
+    """Pin geometry for the six-port H7 breakout, PCB revision 0.1."""
+
+    def __init__(self):
+        self.port_1 = Port(DIO_A="B13", DIO_B="B12", POW_A="E1", POW_B="E4", POW_C="B0", UART=5)
+        self.port_2 = Port(DIO_A="A0", DIO_B="A1", POW_A="E5", POW_B="E6", POW_C="D3", UART=4)
+        self.port_3 = Port(DIO_A="B10", DIO_B="B11", DIO_C="A4", POW_A="C1", POW_B="C3", UART=3, I2C=2, DAC=1)
+        self.port_4 = Port(DIO_A="B8", DIO_B="B9", DIO_C="A5", POW_A="D6", POW_B="D7", I2C=1, DAC=2)
+        self.port_5 = Port(DIO_A="A2", DIO_B="A3", DIO_C="D1", POW_A="E10", POW_B="E15", UART=2)
+        self.port_6 = Port(DIO_A="C6", DIO_B="C7", DIO_C="B14", POW_A="C0", POW_B="E0", UART=6)
+        self.qwiic = I2CConnector(SCL="B8", SDA="B9", I2C=1)  # Shares the I2C-1 bus with port_4.
+
+
+        self.led_red = DigitalOutput("D5")
+        self.led_yellow = DigitalOutput("D1")
+        self.led_green = DigitalOutput("D4")
+        self.led_blue = DigitalOutput("E3", inverted=True)
+
+        self.BUTTON_A = self.BUTTON = "C13"
+        self.BUTTON_B = "C12"
+        self.BUTTON_C = "D4"
+        self.BUTTON_D = "A15"
+
+        self.BNC_2 = "C7"
+        self.BNC_3 = self.DAC_1 = "A4"
+        self.BNC_4 = self.DAC_2 = "A5"

pycontrol_core-3.0.0b2/src/pycontrol/firmware/devices/breakout_6port_r0_2_h7.py

@@ -0,0 +1,34 @@
+from pycontrol.hardware import Port, I2CConnector, DigitalOutput
+
+# MCU family this breakout's pin geometry is wired for. The host reads it
+# statically (pycontrol.workspace.hwdef_inspect) to pre-flight setups.
+MCU = "stm32h743"
+
+
+class Breakout6PortR0_2H7:
+    """Pin geometry for the six-port H7 breakout, PCB revision 0.1."""
+
+    def __init__(self):
+        self.port_1 = Port(DIO_A="B13", DIO_B="B12", POW_A="E1", POW_B="E4", POW_C="B0", UART=5)
+        self.port_2 = Port(DIO_A="A0", DIO_B="A1", POW_A="E5", POW_B="E6", POW_C="D3", UART=4)
+        self.port_3 = Port(DIO_A="B10", DIO_B="B11", DIO_C="A4", POW_A="C2", POW_B="C3", UART=3, I2C=2, DAC=1)
+        self.port_4 = Port(DIO_A="B8", DIO_B="B9", DIO_C="A5", POW_A="D6", POW_B="D7", I2C=1, DAC=2)
+        self.port_5 = Port(DIO_A="A2", DIO_B="A3", DIO_C="D1", POW_A="E10", POW_B="E15", UART=2)
+        self.port_6 = Port(DIO_A="C6", DIO_B="C7", DIO_C="B3", POW_A="C0", POW_B="E0", UART=6)
+        self.qwiic = I2CConnector(SCL="B8", SDA="B9", I2C=1)  # Shares the I2C-1 bus with port_4.
+
+
+        self.led_red = DigitalOutput("D5", inverted=True)
+        self.led_yellow = DigitalOutput("D0", inverted=True)
+        self.led_green = DigitalOutput("D4", inverted=True)
+        self.led_blue = DigitalOutput("E3", inverted=True)
+
+        self.BUTTON_A = self.BUTTON = "C13"
+        self.BUTTON_B = "C12"
+        self.BUTTON_C = "D4"
+        self.BUTTON_D = "A15"
+
+        self.BNC_1 = "D4"
+        self.BNC_2 = "D5"
+        self.BNC_3 = self.DAC_1 = "A4"
+        self.BNC_4 = self.DAC_2 = "A5"

{pycontrol_core-3.0.0b1 → pycontrol_core-3.0.0b2}/src/pycontrol/firmware/pycontrol/framework.py

@@ -6,7 +6,7 @@ from . import state_machine as sm
 from . import hardware as hw
 from . import utility as ut
 
-VERSION = "3.0.0b1"
+VERSION = "3.0.0b2"
 
 
 class FrameworkError(BaseException):  # Exception for pycontrol framework errors.

{pycontrol_core-3.0.0b1 → pycontrol_core-3.0.0b2}/src/pycontrol/firmware/pycontrol/hardware.py

@@ -597,6 +597,16 @@ class Port:
         return self.UART
 
 
+class I2CConnector:
+    # 4-pin JST-SH I2C connector (SparkFun Qwiic / Adafruit STEMMA QT). Exposes
+    # the same I2C attribute as Port, so drivers that only need the bus accept
+    # either. It may share its bus with a Port; share one I2C object between them.
+    def __init__(self, SCL, SDA, I2C):
+        self.SCL = SCL
+        self.SDA = SDA
+        self.I2C = I2C
+
+
 # IOExpanderPin -------------------------------------------------------------
 
 

{pycontrol_core-3.0.0b1 → pycontrol_core-3.0.0b2}/src/pycontrol/firmware/pycontrol/state_machine.py

@@ -83,8 +83,25 @@ def stop():
         event_dispatch_dict["run_end"]()
 
 
+def _match_tuples(value, current):
+    # Values from the host may have been through JSON (persistent, setup and CLI
+    # variables), which turns tuples into lists. Restore the tuples the task declared.
+    if isinstance(value, (list, tuple)) and isinstance(current, (list, tuple)):
+        if len(value) == len(current):
+            items = [_match_tuples(x, c) for x, c in zip(value, current)]
+        elif current:
+            items = [_match_tuples(x, current[0]) for x in value]
+        else:
+            items = list(value)
+        return tuple(items) if isinstance(current, tuple) or isinstance(value, tuple) else items
+    if isinstance(value, dict) and isinstance(current, dict):
+        return {k: _match_tuples(x, current[k]) if k in current else x for k, x in value.items()}
+    return value
+
+
 def set_variable(v_name, v_value):
     try:
+        v_value = _match_tuples(v_value, getattr(variables, v_name, None))
         setattr(variables, v_name, v_value)
         return True
     except Exception:

pycontrol_core-3.0.0b2/tests/unit/firmware/test_breakout_qwiic.py

@@ -0,0 +1,21 @@
+"""The six-port H7 breakouts' Qwiic connector is the I2C-1 bus on port_4's DIO pins."""
+
+from __future__ import annotations
+
+import importlib
+
+import pytest
+
+
+@pytest.mark.parametrize(
+    ("module", "cls"),
+    [("breakout_6port_r0_1_h7", "Breakout6PortR0_1H7"), ("breakout_6port_r0_2_h7", "Breakout6PortR0_2H7")],
+)
+def test_qwiic_shares_port_4_i2c_bus(module: str, cls: str) -> None:
+    from pycontrol.hardware import I2CConnector
+
+    board = getattr(importlib.import_module(f"devices.{module}"), cls)()
+
+    assert isinstance(board.qwiic, I2CConnector)
+    assert (board.qwiic.SCL, board.qwiic.SDA) == (board.port_4.DIO_A, board.port_4.DIO_B) == ("B8", "B9")
+    assert board.qwiic.I2C == board.port_4.I2C == 1

pycontrol_core-3.0.0b2/tests/unit/firmware/test_state_machine_variables.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+
+def _variables(**defaults):
+    from pycontrol import state_machine as sm
+    from pycontrol import utility as ut
+
+    for name, value in defaults.items():
+        setattr(ut.v, name, value)
+    sm.variables = ut.v
+    return sm, ut.v
+
+
+def test_json_lists_are_restored_to_declared_tuples() -> None:
+    sm, v = _variables(thresholds=[(-10, 0), (-10, 0), (-10, 0)], lengths=(300, 10))
+
+    assert sm.set_variable("thresholds", [[-5, 0], [-6, 1], [-7, 2]]) is True
+    assert sm.set_variable("lengths", [200, 20]) is True
+
+    assert v.thresholds == [(-5, 0), (-6, 1), (-7, 2)]
+    assert type(v.thresholds) is list
+    assert v.lengths == (200, 20)
+
+
+def test_resized_sequence_uses_first_declared_item_as_template() -> None:
+    sm, v = _variables(thresholds=[(-10, 0), (-10, 0)])
+
+    assert sm.set_variable("thresholds", [[1, 2], [3, 4], [5, 6]]) is True
+
+    assert v.thresholds == [(1, 2), (3, 4), (5, 6)]
+
+
+def test_dict_values_are_matched_by_key() -> None:
+    sm, v = _variables(windows={"left": (0, 1), "count": 3})
+
+    assert sm.set_variable("windows", {"left": [2, 3], "right": [4, 5], "count": 4}) is True
+
+    assert v.windows == {"left": (2, 3), "right": [4, 5], "count": 4}
+
+
+def test_values_without_declared_tuples_are_unchanged() -> None:
+    sm, v = _variables(items=[1, 2], name="x", pair=(1, 2))
+
+    assert sm.set_variable("items", [3, 4, 5]) is True
+    assert sm.set_variable("name", [1, 2]) is True
+    assert sm.set_variable("pair", 7) is True
+
+    assert v.items == [3, 4, 5]
+    assert v.name == [1, 2]
+    assert v.pair == 7

{pycontrol_core-3.0.0b1 → pycontrol_core-3.0.0b2}/tests/unit/firmware/test_vl53l4.py

@@ -8,8 +8,6 @@ the chip's firmware boot.
 
 from __future__ import annotations
 
-from types import SimpleNamespace
-
 import pytest
 
 DEFAULT = 0x29
@@ -38,15 +36,12 @@ class FakeI2C:
         buf[0] = 0x03  # Firmware booted.
 
 
-def _port() -> SimpleNamespace:
-    return SimpleNamespace(POW_A="X1", POW_B="X2", DIO_C="X3", DIO_A="B8", DIO_B="B9", I2C=1)
-
-
-def _sensor(i2c, name="l_nose"):
+def _sensor(i2c, name="l_nose", address=DEFAULT, enable_pin="X3"):
     from devices.VL53L4 import VL53L4CD
 
-    sensor = VL53L4CD(port=_port(), i2c_instance=i2c, sampling_rate=40, nose_event=name)
+    sensor = VL53L4CD(i2c, name, 40, address=address, enable_pin=enable_pin)
     sensor._sensor_init = lambda: None  # type: ignore[method-assign]  # Register dump irrelevant here.
+    sensor.begin = lambda: None  # type: ignore[method-assign]  # Ranging configuration irrelevant here.
     return sensor
 
 
@@ -60,17 +55,17 @@ def _fast_sleep(monkeypatch: pytest.MonkeyPatch) -> None:
 def test_constructor_holds_chip_in_reset() -> None:
     sensor = _sensor(FakeI2C(present=[DEFAULT]))
 
-    assert sensor.tof_enable.state is False
+    assert sensor.enable.state is False
 
 
-def test_i2c_setup_resets_then_readdresses_chip_found_at_default() -> None:
+def test_setup_resets_then_readdresses_chip_found_at_default() -> None:
     i2c = FakeI2C(present=[DEFAULT])
-    sensor = _sensor(i2c)
+    sensor = _sensor(i2c, address=0x20)
     xshut: list[bool] = []
-    sensor.tof_enable.on = lambda: xshut.append(True)  # type: ignore[method-assign]
-    sensor.tof_enable.off = lambda: xshut.append(False)  # type: ignore[method-assign]
+    sensor.enable.on = lambda: xshut.append(True)  # type: ignore[method-assign]
+    sensor.enable.off = lambda: xshut.append(False)  # type: ignore[method-assign]
 
-    sensor.i2c_setup(0x20)
+    sensor.setup()
 
     assert xshut == [False, True]
     assert i2c.writes[0] == (DEFAULT, STATUS_REG), "first transfer must be the boot poll at the default address"
@@ -79,22 +74,78 @@ def test_i2c_setup_resets_then_readdresses_chip_found_at_default() -> None:
     assert i2c.present == {0x20}
 
 
-def test_i2c_setup_falls_back_to_previous_address_if_xshut_did_not_reset() -> None:
+def test_setup_falls_back_to_previous_address_if_xshut_did_not_reset() -> None:
     i2c = FakeI2C(present=[0x20])
-    sensor = _sensor(i2c)
+    sensor = _sensor(i2c, address=0x20)
 
-    sensor.i2c_setup(0x20)
+    sensor.setup()
 
     assert sensor._address == 0x20
     assert all(addr == 0x20 for addr, _ in i2c.writes)
     assert not any(buf.startswith(ADDRESS_REG) for _, buf in i2c.writes), "no remap needed"
 
 
-def test_i2c_setup_raises_underlying_oserror_when_chip_missing() -> None:
-    sensor = _sensor(FakeI2C(present=[]))
+def test_setup_names_the_sensor_when_chip_missing() -> None:
+    sensor = _sensor(FakeI2C(present=[]), name="c_nose", address=0x40)
 
-    with pytest.raises(OSError):
-        sensor.i2c_setup(0x40)
+    with pytest.raises(RuntimeError, match=r"'c_nose'.*OSError"):
+        sensor.setup()
+
+
+def test_sensors_sharing_a_bus_need_distinct_addresses_and_enable_pins() -> None:
+    i2c = FakeI2C()
+    _sensor(i2c, name="l_nose", address=0x20, enable_pin="X1")
+
+    with pytest.raises(ValueError, match="share address 0x20"):
+        _sensor(i2c, name="c_nose", address=0x20, enable_pin="X2")
+    with pytest.raises(ValueError, match="enable_pin"):
+        _sensor(i2c, name="r_nose", address=0x40, enable_pin=None)
+    _sensor(FakeI2C(), name="other_bus", address=0x20, enable_pin=None)  # Separate buses do not interact.
+
+
+def test_initialise_brings_shared_bus_sensors_up_one_at_a_time() -> None:
+    class SharedBus:
+        """Each chip answers only while enabled; two chips at one address NACK, as a collision would."""
+
+        def __init__(self) -> None:
+            self.chips: list[list] = []  # [sensor, address]
+
+        def _chip(self, addr):
+            live = [chip for chip in self.chips if chip[0].enable.state and chip[1] == addr]
+            if len(live) != 1:
+                raise OSError(19)
+            return live[0]
+
+        def writeto(self, addr, buf):
+            chip = self._chip(addr)
+            if bytes(buf[:2]) == ADDRESS_REG and len(buf) == 3:
+                chip[1] = buf[2]
+
+        def readfrom_into(self, addr, buf):
+            self._chip(addr)
+            buf[0] = 0x03
+
+    bus = SharedBus()
+    sensors = [
+        _sensor(bus, name=n, address=a, enable_pin=p)
+        for n, a, p in (("l", 0x20, "X1"), ("c", 0x30, "X2"), ("r", 0x40, "X3"))
+    ]
+    for sensor in sensors:
+        chip = [sensor, DEFAULT]
+        bus.chips.append(chip)
+        enable_off = sensor.enable.off
+
+        def reset_on_off(enable_off=enable_off, chip=chip):
+            enable_off()
+            chip[1] = DEFAULT  # XSHUT low discards the remapped address.
+
+        sensor.enable.off = reset_on_off  # type: ignore[method-assign]
+
+    for sensor in sensors:
+        sensor._initialise()
+
+    assert [chip[1] for chip in bus.chips] == [0x20, 0x30, 0x40]
+    assert all(sensor._powered for sensor in sensors)
 
 
 def test_wait_for_boot_tolerates_nacks_while_firmware_boots() -> None:
@@ -152,15 +203,30 @@ def test_ranging_timeouts_use_supported_exception(monkeypatch: pytest.MonkeyPatc
         getattr(sensor, method)()
 
 
+def test_sensor_without_enable_pin_sets_up_without_reset() -> None:
+    i2c = FakeI2C(present=[DEFAULT])
+    sensor = _sensor(i2c, enable_pin=None)
+
+    assert sensor.enable is None
+    sensor.setup()
+    assert sensor._address == DEFAULT
+    assert i2c.writes[0] == (DEFAULT, STATUS_REG)
+
+    sensor._ranging = True
+    sensor._run_stop()
+    assert sensor._ranging is False
+    assert sensor._powered is False
+
+
 def test_run_stop_stops_ranging_and_powers_chip_down() -> None:
     i2c = FakeI2C(present=[DEFAULT])
-    sensor = _sensor(i2c)
-    sensor.i2c_setup(0x20)
+    sensor = _sensor(i2c, address=0x20)
+    sensor.setup()
     sensor._ranging = True
 
     sensor._run_stop()
 
-    assert sensor.tof_enable.state is False
+    assert sensor.enable.state is False
     assert (0x20, b"\x00\x87\x00") in i2c.writes  # SYSTEM_START = stop
     assert sensor._ranging is False
     assert any(call[0] == "deinit" for call in sensor.timer.calls)
@@ -168,8 +234,8 @@ def test_run_stop_stops_ranging_and_powers_chip_down() -> None:
 
 def test_run_start_after_run_stop_powers_chip_back_up() -> None:
     i2c = FakeI2C(present=[DEFAULT])
-    sensor = _sensor(i2c)
-    sensor.i2c_setup(0x20)
+    sensor = _sensor(i2c, address=0x20)
+    sensor.setup()
     sensor._run_stop()
     i2c.present = {DEFAULT}  # Powered-down chip comes back at the default address.
     i2c.writes.clear()
@@ -179,7 +245,7 @@ def test_run_start_after_run_stop_powers_chip_back_up() -> None:
 
     sensor._run_start()
 
-    assert sensor.tof_enable.state is True
+    assert sensor.enable.state is True
     assert (DEFAULT, ADDRESS_REG + b"\x20") in i2c.writes
     assert began == [True]
     assert any(call[0] == "init" for call in sensor.timer.calls)
@@ -187,8 +253,8 @@ def test_run_start_after_run_stop_powers_chip_back_up() -> None:
 
 def test_run_start_without_run_stop_does_not_reinitialise() -> None:
     i2c = FakeI2C(present=[DEFAULT])
-    sensor = _sensor(i2c)
-    sensor.i2c_setup(0x20)
+    sensor = _sensor(i2c, address=0x20)
+    sensor.setup()
     i2c.writes.clear()
     sensor.read_sample = lambda: None  # type: ignore[method-assign]