node-red-contrib-dali-sensor/readme.md

Node-RED node for parsing DALI sensor data and outputting motion and lux

# Node-RED `dali-sensor` Node

## Overview
The **DALI Sensor** node is designed for use with the [Lunatone DALI-2 IoT Gateway](https://www.lunatone.com) to easily filter and process **DALI-2 sensor** signals inside Node-RED.  
It allows you to monitor occupancy (motion), lux levels, and lux alarms from connected DALI-2 sensors, with filtering by **short address** and **instance type/number**.

This node is ideal when you want to:
- Extract and use specific **motion** or **lux** data from the DALI bus.
- Convert raw DALI sensor frames into **clean, meaningful outputs**.
- Optionally add **automatic delayed Off** logic for motion detection.

---


## Features

- **Short address filtering** — Only process messages from the target DALI-2 device.
- **Scheme selection** — Supports both:
  - *Device* scheme (instance types)
  - *Device/Instance* scheme (instance numbers)
- **Instance mapping** — Configure which instance is motion and which is lux.
- **Lux setpoint** — Auto-generate a Lux Alarm output when lux drops below the threshold.
- **Boolean or string outputs** — Select `"true"/"false"` or `"On"/"Off"` for binary outputs.
- **Auto-Off option** *(new)* — Motion turns On immediately, then Off after a non-resettable delay.

---


## Outputs

The node has **three outputs**:

| Output Port | Name        | Description                                                                 |
|-------------|-------------|-----------------------------------------------------------------------------|
| 1           | Motion      | Latched occupancy state. Controlled by Auto-Off if enabled.                 |
| 2           | Lux Value   | Raw lux reading (integer).                                                   |
| 3           | Lux Alarm   | Boolean/On-Off depending on whether lux is below the setpoint.               |

---


## Auto-Off Feature

When **Auto Off** is enabled:
- **"On"** is emitted immediately on motion detection.
- First **"Off"** starts a delayed turn-off (non-resettable).
- Further Off frames during countdown are ignored.
- An On during countdown cancels the pending Off.
- Default delay is **30 seconds** (configurable).
- `msg.delay` (in ms) on the message that starts the countdown can override the timeout.
- Status shows a live countdown.

If Node-RED restarts during a countdown, the node will re-arm the remaining delay and emit Off when it expires.

---


## Configuration

| Field             | Description                                                                 |
|-------------------|-----------------------------------------------------------------------------|
| **Name**          | Node label in the flow.                                                     |
| **Short Address** | DALI short address of the target device.                                    |
| **Motion Instance** | Instance number/type for motion (for Device/Instance scheme).             |
| **Lux Instance**  | Instance number/type for lux (for Device/Instance scheme).                  |
| **Lux Setpoint**  | Threshold for triggering Lux Alarm.                                         |
| **Use Boolean**   | Output binary states as `"true"/"false"` instead of `"On"/"Off"`.           |
| **Auto Off**      | Enable automatic delayed Off for motion.                                    |
| **Timeout**       | Delay in seconds before motion turns Off (default 30).                      |

---


## Example Flow

```json
[
    {
        "id": "dali-sensor-example",
        "type": "dali-sensor",
        "name": "Office Motion & Lux",
        "shortAddress": "1",
        "motionInstance": 0,
        "luxInstance": 1,
        "luxSetpoint": 400,
        "useBoolean": true,
        "enableAutoOff": true,
        "autoOffDelaySec": 30,
        "wires": [
            ["debug-motion"],
            ["debug-lux"],
            ["debug-alarm"]
        ]
    }
]