Source code for QC.SCAN

"""I2C multiplexer scanner for detecting sensors across all MUX channels.

Iterates through all four I2C MUX channels, runs ``i2cdetect`` on each,
and cross-references discovered addresses against a known sensor map
(:obj:`sensorList`) to produce a summary table showing sensor names,
expected vs. actual channels, and detection status. This is primarily a
factory-floor diagnostic helper used to confirm that every I2C peripheral
on an Oizom mainboard is responding on the correct MUX leg.

Example:
    Run directly from the project root to perform a full bus sweep::

        $ python -m QC.SCAN  # doctest: +SKIP

Note:
    Requires the ``i2cdetect`` utility (``i2c-tools``) and read access
    to ``/dev/i2c-*``. Switching MUX channels uses
    :meth:`drivers.gpio.gpio.select_I2C`, which drives MUX-select GPIOs
    on the host Raspberry Pi.
"""

import subprocess

from drivers.gpio import gpio

sensorList = {
    "0x29_1": "0x29 - Light Sensor(TSL2591)",
    "0x31_0": "0x31 - Co2(ELT)",
    "0x36_3": "0x36 - Battery",
    "0x41_2": "0x41 - ATHP SELECTOR",
    "0x44_2": "0x44 - ATH/ATHP/SHT",
    "0x53_1": "0x53 - UV Sensor(LTR390)",
    "0x60_1": "0x60 - OLD UV(SI1147)",
    "0x60_2": "0x60 - ATHP Pressure",
    "0x61_0": "0x61 - 4-20mA Current",
    "0x62_0": "0x62 - CO2(Sensirion)",
    "0x76_0": "0x76 - Box Temp(BME280)",
    "0x77_0": "0x77 - Box Temp(BME280)",
}




def detect_i2c_addresses(bus_number: int = 0) -> list[int]:
    """Detect all responding I2C addresses on the specified bus.

    Shells out to ``i2cdetect -y <bus_number>`` and parses the resulting
    grid into a list of integers. Cells marked ``--`` are skipped, and
    only acknowledged addresses are returned.

    Args:
        bus_number: I2C bus number passed to ``i2cdetect -y``. Defaults
            to ``0`` which corresponds to ``/dev/i2c-0`` on the Pi.

    Returns:
        List of integer I2C addresses (7-bit) that acknowledged during
        the scan. Returns an empty list if ``i2cdetect`` fails.

    Raises:
        subprocess.CalledProcessError: Caught internally and logged; the
            function returns ``[]`` in that case rather than re-raising.

    Example:
        Sweep bus 0 and print the discovered addresses in hex::

            >>> for addr in detect_i2c_addresses(0):  # doctest: +SKIP
            ...     print(hex(addr))

    Note:
        Requires ``i2c-tools`` to be installed on the host. The current
        process must also have permission to read ``/dev/i2c-<bus>``,
        which usually means membership in the ``i2c`` group or running
        as root.
    """
    try:
        output = subprocess.check_output(["i2cdetect", "-y", str(bus_number)], universal_newlines=True)
        addresses = []
        lines = output.split("\n")[1:]  # Skip the header row
        for line in lines:
            parts = line.split()
            if parts:
                for part in parts[1:]:  # Skip the first column which is the row header
                    if part != "--":
                        addresses.append(int(part, 16))
        return addresses
    except subprocess.CalledProcessError as e:
        print(f"An error occurred while detecting I2C addresses: {e}")
        return []





def scan_i2c_mux() -> None:
    """Scan all four I2C MUX channels and print a sensor detection report.

    For each of the four MUX channels (0-3) this routine switches the
    multiplexer via :meth:`drivers.gpio.gpio.select_I2C`, calls
    :func:`detect_i2c_addresses` to enumerate live peripherals, and
    finally compares the results against :obj:`sensorList`. A formatted
    plain-text table is printed to stdout summarising channel, address,
    sensor name, and a ``Status`` column that flags expected hits,
    relocations, and unknown devices.

    Returns:
        None. Output is rendered to stdout for human inspection.

    Raises:
        OSError: If switching MUX channels via GPIO fails (propagated
            from :class:`drivers.gpio.gpio`).

    Example:
        Run a full scan from a Python REPL on the device::

            >>> scan_i2c_mux()  # doctest: +SKIP

    Note:
        This function is hardware-only and will not produce meaningful
        output when executed on a development workstation. Must be run
        with sufficient privileges to manipulate GPIO and the I2C bus.
    """
    # Create a mapping from address to expected channel and sensor name
    address_to_info = {}
    for key, value in sensorList.items():
        addr, ch = key.split("_")
        address_to_info[addr] = {"channel": int(ch), "name": value}

    all_addresses = {}
    for channel in range(4):
        gpio.select_I2C(channel)
        addresses = detect_i2c_addresses()
        all_addresses[channel] = addresses

    # Collect data for table
    table_data = []
    for channel in range(4):
        addresses = all_addresses[channel]
        for num in addresses:
            addr_hex = hex(num)
            key = f"{addr_hex}_{channel}"
            if key in sensorList:
                status = "OK"
                name = sensorList[key].split(" - ", 1)[1] if " - " in sensorList[key] else sensorList[key]
            elif addr_hex in address_to_info:
                expected_ch = address_to_info[addr_hex]["channel"]
                name = (
                    address_to_info[addr_hex]["name"].split(" - ", 1)[1]
                    if " - " in address_to_info[addr_hex]["name"]
                    else address_to_info[addr_hex]["name"]
                )
                status = f"Position changed from {expected_ch} to {channel}"
            else:
                name = f"Unknown sensor at {addr_hex}"
                status = "Unknown"
            table_data.append([channel, addr_hex, name, status])

    # Print table header
    print("\nI2C Mux Scan Results")
    print("=" * 80)
    print(f"{'Channel':<8} | {'Address':<8} | {'Sensor':<30} | {'Status'}")
    print("-" * 80)

    # Print table rows
    current_channel = 0
    for row in table_data:
        channel, addr, sensor, status = row
        if current_channel != channel:
            print("-" * 80)
            current_channel = channel
        print(f"{channel:<8} | {addr:<8} | {sensor:<30} | {status}")

    print("=" * 80)
    print("Scan complete.\n")



if __name__ == "__main__":
    scan_i2c_mux()