python-dali 0.12__py3-none-any.whl → 0.13__py3-none-any.whl

dali/device/__init__.py

@@ -9,3 +9,4 @@ import dali.device.sequences
 import dali.device.pushbutton  # noqa: F401
 import dali.device.occupancy  # noqa: F401
 import dali.device.light  # noqa: F401
+import dali.device.general_sensor  # noqa: F401

dali/device/general_sensor.py

@@ -0,0 +1,237 @@
+"""Commands and events from IEC 62386 part 306: General sensors."""
+
+from enum import IntEnum
+
+from dali import command
+from dali.device import general
+
+# IEC 62386-306 instance type.
+instance_type = 6
+
+
+class MeasurementVariable(IntEnum):
+    """DTR0 values for QUERY MEASUREMENT VARIABLE, from Part 306 Table 17.
+
+    Note: each QUERY MEASUREMENT VARIABLE execution auto-increments DTR0 by 1,
+    so DTR0 must be set again before every single-byte read.
+    """
+
+    ALARM_IS_ACTIVATED = 0x00
+    ALARM_TYPE = 0x01
+    INPUT_SIGNAL_SIGNED = 0x02
+    ALARM_0_BYTE_0 = 0x03
+    ALARM_0_BYTE_1 = 0x04
+    ALARM_0_BYTE_2 = 0x05
+    ALARM_1_BYTE_0 = 0x06
+    ALARM_1_BYTE_1 = 0x07
+    ALARM_1_BYTE_2 = 0x08
+    ALARM_2_BYTE_0 = 0x09
+    ALARM_2_BYTE_1 = 0x0A
+    ALARM_2_BYTE_2 = 0x0B
+    ALARM_3_BYTE_0 = 0x0C
+    ALARM_3_BYTE_1 = 0x0D
+    ALARM_3_BYTE_2 = 0x0E
+    ALARM_0_HYSTERESIS_BYTE_0 = 0x0F
+    ALARM_0_HYSTERESIS_BYTE_1 = 0x10
+    ALARM_0_HYSTERESIS_BYTE_2 = 0x11
+    ALARM_1_HYSTERESIS_BYTE_0 = 0x12
+    ALARM_1_HYSTERESIS_BYTE_1 = 0x13
+    ALARM_1_HYSTERESIS_BYTE_2 = 0x14
+    ALARM_2_HYSTERESIS_BYTE_0 = 0x15
+    ALARM_2_HYSTERESIS_BYTE_1 = 0x16
+    ALARM_2_HYSTERESIS_BYTE_2 = 0x17
+    ALARM_3_HYSTERESIS_BYTE_0 = 0x18
+    ALARM_3_HYSTERESIS_BYTE_1 = 0x19
+    ALARM_3_HYSTERESIS_BYTE_2 = 0x1A
+    UNIT_OF_MEASUREMENT = 0x1B
+    UNIT_OF_MEASUREMENT_EXTENDED_0 = 0x1C
+    UNIT_OF_MEASUREMENT_EXTENDED_1 = 0x1D
+    QUANTITY_NAME = 0x1E
+    QUANTITY_NAME_EXTENDED_0 = 0x1F
+    QUANTITY_NAME_EXTENDED_1 = 0x20
+    MAGNITUDE = 0x21
+    MAGNITUDE_PHYSICAL_MAX = 0x22
+    MAGNITUDE_PHYSICAL_MIN = 0x23
+    MAX_MEASURED_VALUE_BYTE_0 = 0x24
+    MAX_MEASURED_VALUE_BYTE_1 = 0x25
+    MAX_MEASURED_VALUE_BYTE_2 = 0x26
+    MAX_MEASURED_VALUE_BYTE_3 = 0x27
+    MIN_MEASURED_VALUE_BYTE_0 = 0x28
+    MIN_MEASURED_VALUE_BYTE_1 = 0x29
+    MIN_MEASURED_VALUE_BYTE_2 = 0x2A
+    MIN_MEASURED_VALUE_BYTE_3 = 0x2B
+
+
+class UnitOfMeasurement(IntEnum):
+    """Standard unit-of-measurement values from Part 306 Annex A, Table A.1."""
+
+    MANUFACTURER_DEFINED = 0
+    DIMENSIONLESS = 1
+    SECOND = 2
+    HERTZ = 3
+    METRE = 4
+    KILOGRAM = 5
+    VOLT = 6
+    AMPERE = 7
+    KELVIN = 8
+    CELSIUS = 9
+    FAHRENHEIT = 10
+    MOLE = 11
+    DEGREE_ANGLE = 12
+    RADIAN = 13
+    STERADIAN = 14
+    NEWTON = 15
+    PASCAL = 16
+    PSI = 17
+    JOULE = 18
+    WATT = 19
+    COULOMB = 20
+    FARAD = 21
+    OHM = 22
+    SIEMENS = 23
+    WEBER = 24
+    TESLA = 25
+    HENRY = 26
+    AMPERE_PER_METRE = 27
+    VOLT_PER_METRE = 28
+    AMPERE_HOUR = 29
+    WATT_HOUR = 30
+    LUMEN = 31
+    LUX = 32
+    CANDELA = 33
+    CANDELA_PER_SQUARE_METRE = 34
+    BECQUEREL = 35
+    GRAY = 36
+    SIEVERT = 37
+    KATAL = 38
+    SQUARE_METRE = 39
+    CUBIC_METRE = 40
+    METRE_PER_SECOND = 41
+    METRE_PER_SECOND_SQUARED = 42
+    CUBIC_METRE_PER_SECOND = 43
+    KILOGRAM_PER_CUBIC_METRE = 44
+    KILOGRAM_PER_SQUARE_METRE = 45
+    CUBIC_METRE_PER_KILOGRAM = 46
+    FOOT = 47
+    NEWTON_METRE = 48
+    DECIBEL = 49
+    PERCENT = 50
+    PART_PER_THOUSAND = 51
+    PART_PER_TEN_THOUSAND = 52
+    PARTS_PER_MILLION = 53
+    DECIBEL_A = 54
+
+
+class QuantityName(IntEnum):
+    """Standard quantity-name values from Part 306 Annex A, Table A.2."""
+
+    MANUFACTURER_DEFINED = 0
+    TIME = 1
+    FREQUENCY = 2
+    LENGTH = 3
+    FORCE = 4
+    WEIGHT = 5
+    MASS = 6
+    VELOCITY = 7
+    ACCELERATION = 8
+    ANGLE = 9
+    AREA = 10
+    VOLUME = 11
+    TORQUE = 12
+    VOLTAGE = 13
+    CURRENT = 14
+    POWER = 15
+    POWER_APPARENT = 16
+    POWER_REACTIVE = 17
+    ENERGY = 18
+    POWER_FACTOR = 19
+    SOUND_PRESSURE_LEVEL = 20
+    CCT = 21
+    CRI = 22
+    RED_LIGHT = 23
+    GREEN_LIGHT = 24
+    BLUE_LIGHT = 25
+    TEMPERATURE = 26
+    WET_BULB_TEMPERATURE = 27
+    ABSOLUTE_HUMIDITY = 28
+    RELATIVE_HUMIDITY = 29
+    DEW_POINT = 30
+    PRESSURE = 31
+    FLOW_RATE = 32
+    SO2 = 33
+    CO2 = 34
+    CO = 35
+    VOC = 36
+    NOX = 37
+    N2O = 38
+    AMMONIA = 39
+    OZONE = 40
+    CHLORINE = 41
+    METHANE = 42
+    ACIDITY = 43
+    PARTICULATE_MATTER_PM10 = 44
+    PARTICULATE_MATTER_PM2_5 = 45
+    AIR_QUALITY_INDEX = 46
+    RSSI_IBEACON = 47
+    RSSI_EDDYSTONE = 48
+    RSSI_ALTBEACON = 49
+    GLOBAL_POSITION_LONGITUDE = 50
+    GLOBAL_POSITION_LATITUDE = 51
+    ALTITUDE = 52
+    RELATIVE_POSITION_X = 53
+    RELATIVE_POSITION_Y = 54
+    RELATIVE_POSITION_Z = 55
+    WIND_SPEED = 56
+    FLUID_LEVEL = 57
+    BATTERY_CHARGE = 58
+    # Clarifications and Recommendations for IEC 62386:
+    GENERAL_PURPOSE_COUNTER = 59
+    PEOPLE_COUNTER = 60
+
+
+class GeneralSensorEvent(general._Event):
+    """A Part 306 measured-value event."""
+
+    _instance_type = instance_type
+    _event_info = 0x20000
+
+    @classmethod
+    def from_event_data(cls, event_data: int):
+        """Return this event class for a measurement event."""
+        return cls if event_data & 0x200 else None
+
+    @property
+    def measured_value(self) -> int:
+        """Return the 9-bit measured-value event payload."""
+        return self.event_data & 0x1FF
+
+    @property
+    def event_data(self) -> int:
+        """Return the encoded event information."""
+        return self._event_info
+
+    def _set_event_data(self, set_data: int, set_frame) -> None:
+        """Encode the measured value into a Part 306 event frame."""
+        if not isinstance(set_data, int) or not 0 <= set_data <= 0x3FF:
+            raise ValueError("GeneralSensorEvent requires 9-bit event data")
+        self._event_info = 0x200 | (set_data & 0x1FF)
+        set_frame[9:0] = self._event_info
+
+
+class InstanceEventFilter(general.InstanceEventFilter):
+    """Part 306 event filters."""
+
+    measured_value = 0x01
+
+
+class QueryMeasurementVariable(general._StandardInstanceCommand):
+    """Query a Part 306 measurement variable selected by DTR0.
+
+    Executing this command auto-increments DTR0 by 1, so DTR0 must be set
+    again before every single-byte read. See MeasurementVariable.
+    """
+
+    inputdev = True
+    uses_dtr0 = True
+    response = command.NumericResponse
+    _opcode = 0x5F

dali/device/helpers.py

@@ -19,7 +19,7 @@ from dali.device.general import (
 )
 from dali.exceptions import MissingResponse, ResponseError
 from dali.frame import BackwardFrameError
-from dali.sequences import progress as seq_progress
+from dali.sequences import progress as seq_progress, sleep
 
 
 def check_bad_rsp(r: Response | None) -> bool:
@@ -85,7 +85,10 @@ class DeviceInstanceTypeMapper:
         return self._mapping
 
     def autodiscover(
-        self, addresses: int | tuple[int, int] | Iterable[int] = (0, 63)
+        self,
+        addresses: int | tuple[int, int] | Iterable[int] = (0, 63),
+        quiescent_settle: float = 0.2,
+        status_attempts: int = 3,
     ) -> Generator[Command, Response, None]:
         """
         A generator sequence to scan a DALI bus for control device instances,
@@ -99,6 +102,11 @@ class DeviceInstanceTypeMapper:
         which case all addresses between the provided values will be scanned;
         or finally can be an iterable of ints in which case each address, in
         the iterator will be scanned.
+        :param quiescent_settle: Seconds to wait after entering quiescent mode
+        before probing, so an event frame already in flight does not corrupt
+        the first address probe.
+        :param status_attempts: How many times to probe an address whose status
+        reply collides with a spontaneous event before treating it as empty.
         :return: A generator function, to use with e.g. `driver.run_sequence()`
 
         Needs to be used through an appropriate driver, with `run_sequence()`,
@@ -111,6 +119,12 @@ class DeviceInstanceTypeMapper:
 
         # Use quiescent mode to reduce bus contention from input devices
         yield StartQuiescentMode(DeviceBroadcast())
+        # Quiescent mode is not instant and an input device may already have an
+        # event frame in flight. Let the bus settle so the first probe is not
+        # corrupted by a colliding backward frame, which would otherwise make a
+        # present device look absent.
+        if quiescent_settle:
+            yield sleep(quiescent_settle)
 
         if isinstance(addresses, int):
             addresses = (n for n in range(0, addresses))
@@ -120,8 +134,16 @@ class DeviceInstanceTypeMapper:
         for addr_int in addresses:
             addr = DeviceShort(addr_int)
 
-            # Check that the device exists and responds
-            rsp = yield QueryDeviceStatus(device=addr)
+            # Check that the device exists and responds. A framing error means a
+            # device answered but its backward frame collided with a spontaneous
+            # event, so retry; a missing response means the address is empty, so
+            # stop probing it immediately.
+            for _attempt in range(status_attempts):
+                rsp = yield QueryDeviceStatus(device=addr)
+                if not check_bad_rsp(rsp):
+                    break
+                if not isinstance(getattr(rsp, "raw_value", None), BackwardFrameError):
+                    break
             if check_bad_rsp(rsp):
                 continue
             if isinstance(rsp, QueryDeviceStatusResponse):
@@ -140,7 +162,13 @@ class DeviceInstanceTypeMapper:
             rsp = yield QueryNumberOfInstances(device=addr)
             if check_bad_rsp(rsp):
                 continue
-            num_inst = rsp.value
+            # Instance numbers are 0..31 (IEC 62386-103), so a device can have
+            # at most 32 instances. Cap the count defensively: a device
+            # reporting more, or a value corrupted by a colliding event frame,
+            # would otherwise build an out-of-range InstanceNumber and abort the
+            # whole scan. Non-existent instances are skipped when they do not
+            # respond to QueryInstanceEnabled below.
+            num_inst = min(rsp.value, 32)
 
             # For each instance, check it is enabled and then query the type
             for inst_int in range(num_inst):

dali/device/sequences.py

@@ -6,14 +6,18 @@ from __future__ import annotations
 import types
 from typing import Generator, Optional, Type
 
-from dali.address import DeviceShort, InstanceNumber
+from dali.address import DeviceBroadcast, DeviceShort, InstanceNumber
 from dali.command import Command, Response
 from dali.device.general import (
     DTR0,
     DTR1,
     DTR2,
+    Compare,
     EventScheme,
+    Initialise,
     InstanceEventFilter,
+    ProgramShortAddress,
+    QueryDeviceStatus,
     QueryResolution,
     QueryInputValue,
     QueryInputValueLatch,
@@ -22,11 +26,22 @@ from dali.device.general import (
     QueryEventFilterM,
     QueryEventScheme,
     QueryEventSchemeResponse,
+    Randomise,
+    SearchAddrH,
+    SearchAddrL,
+    SearchAddrM,
     SetEventFilter,
     SetEventScheme,
+    SetShortAddress,
+    StartQuiescentMode,
+    StopQuiescentMode,
+    Terminate,
+    VerifyShortAddress,
+    Withdraw,
 )
 from dali.device.helpers import check_bad_rsp
-from dali.exceptions import DALISequenceError
+from dali.exceptions import DALISequenceError, ProgramShortAddressFailure
+from dali.sequences import progress, sleep
 
 
 def SetEventSchemes(
@@ -275,3 +290,161 @@ def query_input_value(
         value >>= 8 - resolution
 
     return value
+
+
+# INITIALISE data byte values for control devices, from IEC 62386-103:2014
+# Table 21. Unlike control gear (part 102), devices use 0xff for "all" and
+# 0x7f for "no short address" (short address == MASK).
+_INITIALISE_ALL = 0xFF
+_INITIALISE_UNADDRESSED = 0x7F
+
+
+def _find_next(
+    low: int, high: int
+) -> Generator[Command, Optional[Response], Optional[int | str]]:
+    """Binary search the 24-bit random address space for a responding device.
+
+    Returns the random address of the device with the lowest address in the
+    ``low..high`` range, ``"clash"`` if two devices share the current address,
+    or ``None`` if no device answers in the range.
+    """
+    yield SearchAddrH((high >> 16) & 0xFF)
+    yield SearchAddrM((high >> 8) & 0xFF)
+    yield SearchAddrL(high & 0xFF)
+
+    r = yield Compare()
+
+    if low == high:
+        if r.value is True:
+            return "clash" if r.raw_value.error else low
+        return None
+
+    if r.value is True:
+        midpoint = (low + high) // 2
+        res = yield from _find_next(low, midpoint)
+        if res is not None:
+            return res
+        return (yield from _find_next(midpoint + 1, high))
+
+    return None
+
+
+def Commissioning(
+    available_addresses: Optional[list[int]] = None,
+    readdress: bool = False,
+    dry_run: bool = False,
+) -> Generator[Command, Optional[Response], list[DeviceShort]]:
+    """Assign short addresses to 24-bit (part 103) control devices.
+
+    This mirrors :func:`dali.sequences.Commissioning` for control gear, using
+    the part 103 addressing commands. Use with an appropriate DALI driver
+    instance, through its ``run_sequence()`` method.
+
+    The bus is placed in quiescent mode for the duration so that spontaneous
+    event messages do not collide with the addressing backward frames.
+
+    :param available_addresses: If passed, only these short addresses will be
+        assigned; otherwise all 64 short addresses are considered available.
+    :param readdress: If set, all existing short addresses are cleared first
+        and every device is readdressed; otherwise only devices that are
+        currently unaddressed are assigned a short address.
+    :param dry_run: If set, no short addresses are actually programmed. Useful
+        for testing the search without altering the bus.
+    :return: The list of short addresses that are in use once the sequence
+        completes.
+    """
+    used_addresses: list[DeviceShort] = []
+    if available_addresses is None:
+        available_addresses = list(range(64))
+    else:
+        available_addresses = list(available_addresses)
+
+    if readdress:
+        if dry_run:
+            yield progress(
+                message="dry_run is set: not deleting existing short addresses"
+            )
+        else:
+            yield DTR0(255)
+            yield SetShortAddress(DeviceBroadcast())
+    else:
+        # Devices that already have a short address answer QueryDeviceStatus at
+        # that address, so those addresses are considered already in use.
+        for a in list(available_addresses):
+            in_use = yield QueryDeviceStatus(DeviceShort(a))
+            if not check_bad_rsp(in_use):
+                available_addresses.remove(a)
+                used_addresses.append(DeviceShort(a))
+        yield progress(message=f"Available addresses: {available_addresses}")
+
+    yield Terminate()
+    yield StartQuiescentMode(DeviceBroadcast())
+    yield Initialise(_INITIALISE_ALL if readdress else _INITIALISE_UNADDRESSED)
+
+    # A verify failure must still leave the bus addressable, so the error is
+    # recorded and raised only after quiescent mode has been exited below;
+    # yielding during exception unwinding is unsafe because the sequence runner
+    # closes the generator via GeneratorExit on failure.
+    failed_address: Optional[int] = None
+    finished = False
+    # Loop to cope with multiple devices picking the same random search
+    # address; when that clash is detected we re-randomise and begin again.
+    # Devices that already received addresses are unaffected.
+    while not finished:
+        yield Randomise()
+        # Randomise can take up to 200ms to settle.
+        yield sleep(0.2)
+
+        low = 0
+        high = 0xFFFFFF
+
+        while low is not None:
+            yield progress(completed=low, size=high)
+            low = yield from _find_next(low, high)
+            if low == "clash":
+                yield progress(
+                    message="Multiple devices picked the same random "
+                    "address; restarting"
+                )
+                break
+            if low is None:
+                finished = True
+                break
+            yield progress(message=f"Device found at address {low:#x}")
+            if available_addresses:
+                new_addr = available_addresses.pop(0)
+                if dry_run:
+                    yield progress(
+                        message="Not programming short address "
+                        f"{new_addr} because dry_run is set"
+                    )
+                else:
+                    yield progress(
+                        message=f"Programming short address {new_addr}"
+                    )
+                    yield ProgramShortAddress(new_addr)
+                    r = yield VerifyShortAddress(new_addr)
+                    if r.value is not True:
+                        failed_address = new_addr
+                        finished = True
+                        break
+                    used_addresses.append(DeviceShort(new_addr))
+            else:
+                yield progress(
+                    message="Device found but no short addresses left"
+                )
+            yield Withdraw()
+            if low < high:
+                low = low + 1
+            else:
+                low = None
+                finished = True
+
+    yield Terminate()
+    yield StopQuiescentMode(DeviceBroadcast())
+
+    if failed_address is not None:
+        raise ProgramShortAddressFailure(failed_address)
+
+    yield progress(message="Addressing complete")
+    return used_addresses