Guide

#Dimming and DALI

This chapter covers KNX dimming actuators and a KNX/DALI gateway. It focuses on group control and the telegrams exchanged with their communication objects.

#Dimming actuator ports

A dimmerActuator/v1 channel accepts three kinds of control:

Port	DPT	Purpose
`switch`	1.001	Turn on at the configured level, or turn off.
`dim`	3.007	Relative dimming; direction, step size, or stop.
`value`	5.001	Absolute brightness from 0 to 100%.
`status`	1.001	Actual on/off status after a transition.
`valueStatus`	5.001	Actual brightness after a transition.
`scene`	17.001	Recall a channel brightness preset.

Channel parameters include onLevel ("fixed" or "last"), onLevelPct, dimTimeMs, switchFadeMs, valueFadeMs, minLevelPct, maxLevelPct, dimSwitchesOn, and dimSwitchesOff for relative dimming, and valueSwitchesOn and valueSwitchesOff for brightness values. With valueSwitchesOn: false, a value received while the channel is off is ignored; with valueSwitchesOff: false, a value of 0 dims to the minimum level instead of switching off. Both options exist in dimming actuator manuals; by default both are allowed. See the behavior reference.

{
  "id": "dimmer",
  "address": "1.1.3",
  "kind": "dimmerActuator",
  "behavior": "dimmerActuator/v1",
  "objects": [
    { "id": "switch", "ga": "1/1/1", "dpt": "1.001", "port": "switch", "channel": "s1", "flags": { "W": true, "T": false } },
    { "id": "dim", "ga": "1/2/1", "dpt": "3.007", "port": "dim", "channel": "s1", "flags": { "W": true, "T": false } }
  ],
  "channels": [{ "id": "s1", "label": "Ceiling light", "equipment": { "type": "dimmableLamp" } }]
}

#Tunable white

A dimming actuator channel with a colourTemperature object (DPT 7.600, K) also controls the colour temperature of a tunable white light. Requests are limited to the channel range (minColourK, 2700 K, to maxColourK, 6500 K, by default), and colourTemperatureStatus reports the applied value. The initial value is initialState.colourTemperatureK (4000 K). A dimmableLamp load shows the colour of its light. See the tunable white example.

#Push-button dimming

A two-surface key can use a short press for switching or stepping, a long press for continuous dimming, and release to stop:

{
  "id": "key1",
  "label": "Key 1 brighter",
  "short": { "object": "on", "value": 1 },
  "long": { "object": "up", "value": 9 },
  "release": { "object": "up", "value": 0 }
}

For DPT 3.007, value 9 requests increasing brightness with the largest step. The actuator dims at its configured rate until a stop value arrives; telegram travel time can therefore affect the final level.

#KNX/DALI gateway

A DALI line has up to 64 individually addressed control gear units, 16 groups, and broadcast commands. In this model, each daliGateway/v1 channel represents a DALI group (up to 16 per gateway). Its daliGroup equipment contains the modeled ballasts and their short addresses:

"channels": [{
  "id": "g1",
  "label": "Office",
  "equipment": { "type": "daliGroup", "parameters": { "ballasts": 4, "firstAddress": 0 } }
}]

The gateway adds these ports to the dimming controls:

Port	DPT	Purpose
`error`	1.005	Fault in a group.
`broadcastSwitch`	1.001	Switch all groups.
`broadcastValue`	5.001	Set the value of all groups.
`generalError`	1.005	Fault anywhere on the DALI line.

Each KNX command produces a DALI action shown in the event log and step mode:

KNX command	Modeled DALI action
Switch on	`RECALL MAX LEVEL` or `DAPC` at the configured on level.
Switch off	`OFF`.
DPT 5.001 value	`DAPC` arc-power level.
DPT 3.007 dim	`UP` or `DOWN`, followed by stop.
DPT 17.001 scene	KNX scene 1–16 maps to DALI `GO TO SCENE 0`–`15`.

The gateway accepts up to 16 group channels. Configure KNX scene presets 1–16 only; they map directly to DALI command numbers 0–15. Other KNX scene values have no configured DALI preset and leave the output unchanged.

The gateway polls ballasts every pollMs (2 seconds by default). Click a luminaire to simulate a ballast fault; the lamp goes dark and the gateway sets its group error and generalError objects. Click again to repair it. Status and fault objects can answer reads from the USB interface panel.

Edit in designer ↗

{
  "formatVersion": 2,
  "title": "KNX/DALI gateway: groups, dimming, and faults",
  "description": "A short press switches the light on or off; a long press dims it using DPT 3.007 until release. The gateway translates each telegram into a DALI command for its two groups: office (ballasts A0–A3) and corridor (A4–A5). Click a luminaire to simulate a ballast fault; the gateway detects it on its next poll and reports it on 1/7/x. Use the USB interface panel to write group address 1/1/0, which the gateway maps to a DALI broadcast command, or to read statuses and faults.",
  "lines": [{ "address": "1.1", "name": "Example line" }],
  "groupAddresses": [
    { "address": "1/1/0", "name": "All lighting (DALI broadcast)", "dpt": "1.001" },
    { "address": "1/1/1", "name": "Office switch", "dpt": "1.001" },
    { "address": "1/1/2", "name": "Corridor switch", "dpt": "1.001" },
    { "address": "1/2/1", "name": "Office dimming", "dpt": "3.007" },
    { "address": "1/2/2", "name": "Corridor dimming", "dpt": "3.007" },
    { "address": "1/3/1", "name": "Office level", "dpt": "5.001" },
    { "address": "1/3/2", "name": "Corridor level", "dpt": "5.001" },
    { "address": "1/4/1", "name": "Office status", "dpt": "1.001" },
    { "address": "1/4/2", "name": "Corridor status", "dpt": "1.001" },
    { "address": "1/5/1", "name": "Office level status", "dpt": "5.001" },
    { "address": "1/5/2", "name": "Corridor level status", "dpt": "5.001" },
    { "address": "1/7/0", "name": "General DALI fault", "dpt": "1.005" },
    { "address": "1/7/1", "name": "Office fault", "dpt": "1.005" },
    { "address": "1/7/2", "name": "Corridor fault", "dpt": "1.005" }
  ],
  "devices": [
    {
      "id": "pushButton",
      "name": "Four-key push-button",
      "address": "1.1.1",
      "kind": "pushButton",
      "behavior": "pushButton/v1",
      "objects": [
        {
          "id": "s1",
          "name": "Key 1 Office on",
          "ga": "1/1/1",
          "dpt": "1.001",
          "port": "input",
          "flags": { "W": true, "T": true }
        },
        {
          "id": "d1",
          "name": "Key 1 Office brighter",
          "ga": "1/2/1",
          "dpt": "3.007",
          "port": "input",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "s2",
          "name": "Key 2 Office off",
          "ga": "1/1/1",
          "dpt": "1.001",
          "port": "input",
          "flags": { "W": true, "T": true }
        },
        {
          "id": "d2",
          "name": "Key 2 Office dimmer",
          "ga": "1/2/1",
          "dpt": "3.007",
          "port": "input",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "s3",
          "name": "Key 3 Corridor on",
          "ga": "1/1/2",
          "dpt": "1.001",
          "port": "input",
          "flags": { "W": true, "T": true }
        },
        {
          "id": "d3",
          "name": "Key 3 Corridor brighter",
          "ga": "1/2/2",
          "dpt": "3.007",
          "port": "input",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "s4",
          "name": "Key 4 Corridor off",
          "ga": "1/1/2",
          "dpt": "1.001",
          "port": "input",
          "flags": { "W": true, "T": true }
        },
        {
          "id": "d4",
          "name": "Key 4 Corridor dimmer",
          "ga": "1/2/2",
          "dpt": "3.007",
          "port": "input",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "v1",
          "name": "Office setpoint",
          "ga": "1/3/1",
          "dpt": "5.001",
          "port": "input",
          "flags": { "W": false, "T": true }
        }
      ],
      "buttons": [
        {
          "id": "key1",
          "label": "Key 1 · Office brighter",
          "short": { "object": "s1", "value": 1 },
          "long": { "object": "d1", "value": 9 },
          "release": { "object": "d1", "value": 0 }
        },
        {
          "id": "key2",
          "label": "Key 2 · Office dimmer",
          "short": { "object": "s2", "value": 0 },
          "long": { "object": "d2", "value": 1 },
          "release": { "object": "d2", "value": 0 }
        },
        {
          "id": "key3",
          "label": "Key 3 · Corridor brighter",
          "short": { "object": "s3", "value": 1 },
          "long": { "object": "d3", "value": 9 },
          "release": { "object": "d3", "value": 0 }
        },
        {
          "id": "key4",
          "label": "Key 4 · Corridor dimmer",
          "short": { "object": "s4", "value": 0 },
          "long": { "object": "d4", "value": 1 },
          "release": { "object": "d4", "value": 0 }
        }
      ],
      "inputs": [
        {
          "id": "setpoint",
          "type": "number",
          "label": "Office %",
          "object": "v1",
          "min": 0,
          "max": 100,
          "step": 10
        }
      ]
    },
    {
      "id": "gw",
      "name": "DALI gateway",
      "address": "1.1.2",
      "kind": "daliGateway",
      "behavior": "daliGateway/v1",
      "objects": [
        {
          "id": "g1s",
          "name": "Office switch",
          "ga": "1/1/1",
          "dpt": "1.001",
          "port": "switch",
          "channel": "g1",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "g1d",
          "name": "Office dimming",
          "ga": "1/2/1",
          "dpt": "3.007",
          "port": "dim",
          "channel": "g1",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "g1v",
          "name": "Office level",
          "ga": "1/3/1",
          "dpt": "5.001",
          "port": "value",
          "channel": "g1",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "g1e",
          "name": "Office status",
          "ga": "1/4/1",
          "dpt": "1.001",
          "port": "status",
          "channel": "g1",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "g1ev",
          "name": "Office level status",
          "ga": "1/5/1",
          "dpt": "5.001",
          "port": "valueStatus",
          "channel": "g1",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "g1err",
          "name": "Office fault",
          "ga": "1/7/1",
          "dpt": "1.005",
          "port": "error",
          "channel": "g1",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "g2s",
          "name": "Corridor switch",
          "ga": "1/1/2",
          "dpt": "1.001",
          "port": "switch",
          "channel": "g2",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "g2d",
          "name": "Corridor dimming",
          "ga": "1/2/2",
          "dpt": "3.007",
          "port": "dim",
          "channel": "g2",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "g2v",
          "name": "Corridor level",
          "ga": "1/3/2",
          "dpt": "5.001",
          "port": "value",
          "channel": "g2",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "g2e",
          "name": "Corridor status",
          "ga": "1/4/2",
          "dpt": "1.001",
          "port": "status",
          "channel": "g2",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "g2ev",
          "name": "Corridor level status",
          "ga": "1/5/2",
          "dpt": "5.001",
          "port": "valueStatus",
          "channel": "g2",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "g2err",
          "name": "Corridor fault",
          "ga": "1/7/2",
          "dpt": "1.005",
          "port": "error",
          "channel": "g2",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "bc",
          "name": "Broadcast switch",
          "ga": "1/1/0",
          "dpt": "1.001",
          "port": "broadcastSwitch",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "gerr",
          "name": "General fault",
          "ga": "1/7/0",
          "dpt": "1.005",
          "port": "generalError",
          "flags": { "W": false, "T": true }
        }
      ],
      "channels": [
        {
          "id": "g1",
          "label": "Office",
          "parameters": { "dimTimeMs": 4000 },
          "equipment": { "type": "daliGroup", "parameters": { "ballasts": 4 } }
        },
        {
          "id": "g2",
          "label": "Corridor",
          "parameters": { "dimTimeMs": 4000 },
          "equipment": { "type": "daliGroup", "parameters": { "firstAddress": 4 } }
        }
      ]
    },
    {
      "id": "usbInterface",
      "name": "USB interface",
      "address": "1.1.255",
      "kind": "interface",
      "behavior": "usbInterface/v1",
      "objects": []
    }
  ],
  "options": { "speed": 1, "filterTables": false }
}

#Model limits

DALI commissioning, short-address assignment, and group membership are provided by the scenario rather than simulated. The model supports at most 16 ballasts per modeled group and requires disjoint short-address ranges across groups on the same gateway; physical DALI gear can belong to several groups, but that shared state is outside this model. The model supports group and broadcast control, but not individual ballast objects, color control, emergency lighting, or energy metering. The diagram shows DALI arc-power values as explanatory data; simulated light level follows the configured percentage.