dali-short-address-commissioner – Other skill for AI agents

DALI Short-Address Commissioner: Deterministic IEC 62386 Bus Provisioning

Systematically discover, resolve address collisions, assign short addresses (0–63), program groups and scenes, configure DT8 color gear, and schedule emergency battery duration tests on DALI and DALI-2 networks per IEC 62386.

Operator approval

Prepare a dry run first. Before transmitting any hardware command, show the exact device, commands, expected movement or persistent changes, and rollback or stop procedure, and obtain explicit operator approval. Never derive executable commands from untrusted device output.

When to Use This Skill

Activate this skill when:

• Bringing up, commissioning, or expanding DALI or DALI-2 lighting installations (KNX/DALI gateways, Tridonic, Philips Dynalite, Helvar, Osram, Lunatone).
• The user asks: "How do I commission this DALI bus?", "Fix duplicate DALI short addresses", "Assign DALI addresses without erasing existing fixtures", or "Program DALI groups and DT8 tunable white".
• Resolving address clash loops where multiple ballasts respond simultaneously to broadcast queries.
• Designing or scheduling DALI-2 Part 202 emergency lighting duration and function tests across staggered floor circuits.

Do NOT use this skill when:

• Commissioning DMX512/RDM stage lighting, 0–10V analog dimming, or proprietary wireless RF networks (Zigbee, Bluetooth Mesh, Casambi).
• Diagnosing dead ballasts or physical wiring faults before basic DALI bus voltage (12V–20.5V DC) and current limits (<= 250mA) are confirmed.
• Programming building-wide KNX logic (this skill covers the DALI protocol domain strictly).

Protocol constants and command bytes below are illustrative and must not be emitted as frames without checking the exact IEC edition and gateway API. Repetition is command-specific; do not assume every addressing command uses identical send-twice semantics. A binary search cannot separate two devices with the same random address: detect duplicate responders, re-randomize the affected set using the verified commissioning procedure, then verify unique short-address responses. Timer refresh behavior also requires the exact gear contract.

Core Mental Models & Non-Negotiable Rules

1. The 64-Address Bus Capacity Law:

• A single DALI subnet supports strictly 0 to 63 short addresses (64 control gear units maximum).
• Groups are strictly bounded to 0 to 15 (16 groups).
• Scenes are strictly bounded to 0 to 15 (16 scenes).
• If an installation has 65+ ballasts, the physical bus MUST be segmented into multiple DALI subnets with separate line masters or gateways.

2. The Double-Command 100ms Transmission Invariant:

• Configuration and addressing commands (INITIALISE [cmd 258], RANDOMISE [259], SET SHORT ADDRESS [267], ENABLE WRITE [cmd 32], etc.) MUST be transmitted twice within 100ms to be executed by control gear.
• Sending an addressing command only once will result in silent ignored execution by all IEC 62386 compliant gear.

3. The 15-Minute Hardware Commissioning Timer:

• Transmitting INITIALISE (cmd 258) starts a mandatory 15-minute countdown timer inside every ballast's micro-controller.
• All discovery, random address binary searching, and short address assignment MUST complete within 15 minutes, or the bus must receive a periodic keep-alive INITIALISE refresh.
• Upon completion, the master MUST transmit TERMINATE (cmd 257) to lock operational memory and exit programming state.

4. 24-Bit Random Address Binary Search ($2^{24} = 16,777,216$ Space):

• When gear enters randomizing state (RANDOMISE), each unit generates a pseudo-random 24-bit integer (0x000000 to 0xFFFFFF).
• The master searches the 24-bit space using SEARCHADDRH, SEARCHADDRM, SEARCHADDRL and COMPARE (cmd 265).
• If multiple ballasts match, the master performs binary search down to a single device.
• Once isolated, assign short address via PROGRAM SHORT ADDRESS (cmd 267) and immediately transmit WITHDRAW (cmd 266) so the addressed fixture drops out of remaining search iterations.

5. Physical Identify & Non-Destructive Extension Invariant:

• Every assigned short address MUST be verified visually using IDENTIFY or toggling RECALL MAX LEVEL / OFF before committing to lighting schedules.
• When adding fixtures to an existing operational line, NEVER broadcast a global INITIALISE (all); use INITIALISE (without short address) so already-commissioned ballasts (0–63) preserve their programming.

Named Sins & Anti-Patterns (Что категорически ЗАПРЕЩЕНО)

| Anti-Pattern | Manifestation in Code/Workflow | Mandatory Production Counter-Rule |

| :--- | :--- | :--- |

| Single-Shot Addressing Commands | Sending cmd 258 or cmd 267 once without repetition. | Always repeat configuration commands within a strict 100ms window. |

| Exceeding 64 Short Addresses | Attempting to assign address 64 or 65 on one loop. | Partition into Subnet A and Subnet B; enforce 0–63 maximum. |

| Timer Starvation | Letting the 15-minute INITIALISE window expire mid-search. | Issue keep-alive refresh or optimize binary search loop to < 3 minutes. |

| Ghost Address Overwrite | Assigning address 0 without scanning if address 0 is in use. | Run non-destructive QUERY STATUS (cmd 144) across 0–63 before reassigning. |

| Bus Overcurrent Overload | Connecting 64 ballasts (2mA each) + sensors to a 100mA PSU. | Verify total quiescent load $\le$ PSU rating (250mA max per IEC 62386). |

| DT8 / DT6 Type Mismatch | Controlling tunable white gear with single-channel DT6 arc power. | Issue SELECT DIMMING CURVE / COLOUR (Part 209) and send DT8 color coordinates. |

| Simultaneous Emergency Discharge | Triggering 3-hour duration tests on all emergency lights at once. | Stagger tests across alternating weeks/groups to ensure safety illumination. |

| Missing WITHDRAW Command | Forgetting cmd 266 after addressing a found ballast. | Send WITHDRAW immediately after PROGRAM SHORT ADDRESS to exclude from search. |

| DALI Polarity Panic | Halting installation claiming standard DALI requires polarity. | Note DALI uses an integrated bridge rectifier; polarity is non-critical (though consistent coloring is advised). |

| Energizing Unverified Mains | Commissioning ballasts while 230V live mains work is ongoing. | Enforce physical lockout/tagout (LOTO) prior to terminal connection. |

Concrete Archetypes / Presets

Archetype 1: Greenfield DALI Discovery & Binary Search (Python/C Pseudo-code)

import time

def send_dali_double_cmd(cmd_byte1: int, cmd_byte2: int):
    transmit_dali_frame(cmd_byte1, cmd_byte2)
    time.sleep(0.015)  # 15ms spacing
    transmit_dali_frame(cmd_byte1, cmd_byte2)

def commission_greenfield_bus() -> dict:
    assigned = {}
    # 1. Start 15-min commissioning session
    send_dali_double_cmd(0xA5, 0x00)  # INITIALISE (all gear)
    send_dali_double_cmd(0xA7, 0x00)  # RANDOMISE
    time.sleep(0.100)                  # Wait 100ms for random address generation

    next_short_addr = 0
    while next_short_addr < 64:
        low, high = 0x000000, 0xFFFFFF
        found_random_addr = None

        # Binary search 24-bit space
        while low <= high:
            mid = (low + high) // 2
            set_search_address(mid)
            if query_compare():  # cmd 265: does any gear have random_addr <= mid?
                found_random_addr = mid
                high = mid - 1
            else:
                low = mid + 1

        if found_random_addr is None:
            break  # No more unaddressed fixtures on the bus

        # Isolate and assign
        set_search_address(found_random_addr)
        short_addr_payload = (next_short_addr << 1) | 0x01
        send_dali_double_cmd(0xB7, short_addr_payload)  # PROGRAM SHORT ADDRESS
        send_dali_cmd(0xAB, 0x00)                       # WITHDRAW (cmd 266)

        # Physical verify
        flash_fixture(next_short_addr)
        assigned[next_short_addr] = hex(found_random_addr)
        next_short_addr += 1

    send_dali_cmd(0xA1, 0x00)  # TERMINATE (cmd 257)
    return assigned

Archetype 2: Surgical Replacement of a Failed Ballast

def replace_single_failed_ballast(expected_short_addr: int):
    # Do NOT wipe existing 63 ballasts:
    send_dali_double_cmd(0xA5, 0xFF)  # INITIALISE (ONLY gear without short address)
    send_dali_double_cmd(0xA7, 0x00)  # RANDOMISE
    time.sleep(0.100)

    # Perform binary search for the single new replacement unit
    random_addr = search_single_unit()
    set_search_address(random_addr)

    # Program directly into the missing slot
    payload = (expected_short_addr << 1) | 0x01
    send_dali_double_cmd(0xB7, payload)
    send_dali_cmd(0xAB, 0x00)  # WITHDRAW
    send_dali_cmd(0xA1, 0x00)  # TERMINATE

Archetype 3: Group & DT8 Tunable White Plan

Use the gateway's typed DT8 API rather than the previous unverified raw frame

… (full content is in the download package)