Guide

#Shutters: estimated and actual travel

A shutter actuator has no position sensor in this model. It estimates position from its configured travel time. If it is configured for 20 seconds, 10 seconds of downward travel is reported as 50%. The connected shutter has its own actual travel time. The model tracks both positions separately:

Estimated position: the actuator's value, transmitted on positionStatus.
Actual position: where the connected shutter is, including its physical end stops.
Motor command: the direction currently applied to the output.

Edit in designer ↗

<bus-diagram>
<script type="application/json">
{
  "formatVersion": 2,
  "title": "Shutter: estimated versus actual travel",
  "description": "The actuator is configured for 20 seconds, while the real shutter takes 30 seconds. Compare this with a 30-second setting.",
  "lines": [{ "address": "1.1", "name": "Example installation" }],
  "groupAddresses": [
    { "address": "2/1/1", "name": "Movement", "dpt": "1.008" },
    { "address": "2/1/2", "name": "Stop / step", "dpt": "1.007" },
    { "address": "2/1/3", "name": "Position setpoint", "dpt": "5.001" },
    { "address": "2/1/4", "name": "Estimated position", "dpt": "5.001" }
  ],
  "devices": [
    {
      "id": "pushButton",
      "name": "Three-key push-button",
      "address": "1.1.1",
      "kind": "pushButton",
      "behavior": "pushButton/v1",
      "objects": [
        {
          "id": "move",
          "name": "Movement",
          "ga": "2/1/1",
          "dpt": "1.008",
          "port": "input",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "stop",
          "name": "Stop / slat step",
          "ga": "2/1/2",
          "dpt": "1.007",
          "port": "input",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "target",
          "name": "Setpoint",
          "ga": "2/1/3",
          "dpt": "5.001",
          "port": "input",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "feedback",
          "name": "Received estimated position",
          "ga": "2/1/4",
          "dpt": "5.001",
          "port": "display",
          "flags": { "W": true, "T": false }
        }
      ],
      "buttons": [
        {
          "id": "key1",
          "label": "Key 1 · Up",
          "icon": "up",
          "short": { "object": "stop", "value": 0 },
          "long": { "object": "move", "value": 0 }
        },
        {
          "id": "key2",
          "label": "Key 2 · Down",
          "icon": "down",
          "short": { "object": "stop", "value": 1 },
          "long": { "object": "move", "value": 1 }
        },
        { "id": "key3", "label": "Key 3 · 50 %", "press": { "object": "target", "value": 50 } }
      ],
      "inputs": [
        {
          "id": "position",
          "type": "number",
          "label": "Setpoint (%)",
          "object": "target",
          "min": 0,
          "max": 100,
          "step": 1
        }
      ]
    },
    {
      "id": "shutterActuator",
      "name": "Shutter actuator",
      "address": "1.1.3",
      "kind": "shutterActuator",
      "behavior": "shutterActuator/v1",
      "objects": [
        {
          "id": "move",
          "name": "Movement",
          "ga": "2/1/1",
          "dpt": "1.008",
          "port": "move",
          "channel": "s1",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "stop",
          "name": "Stop / step",
          "ga": "2/1/2",
          "dpt": "1.007",
          "port": "stopStep",
          "channel": "s1",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "target",
          "name": "Requested position",
          "ga": "2/1/3",
          "dpt": "5.001",
          "port": "positionCommand",
          "channel": "s1",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "status",
          "name": "Estimated position",
          "ga": "2/1/4",
          "dpt": "5.001",
          "port": "positionStatus",
          "channel": "s1",
          "flags": { "W": false, "T": true }
        }
      ],
      "channels": [
        {
          "id": "s1",
          "label": "Shutter S1",
          "parameters": { "estimatedTravelTimeMs": 20000 },
          "equipment": { "type": "shutter", "parameters": { "actualTravelTimeMs": 30000 } }
        }
      ]
    }
  ],
  "options": { "speed": 1, "filterTables": false }
}
</script>
</bus-diagram>

{
  "formatVersion": 2,
  "title": "Shutter: estimated versus actual travel",
  "description": "The actuator is configured for 20 seconds, while the real shutter takes 30 seconds. Compare this with a 30-second setting.",
  "lines": [{ "address": "1.1", "name": "Example installation" }],
  "groupAddresses": [
    { "address": "2/1/1", "name": "Movement", "dpt": "1.008" },
    { "address": "2/1/2", "name": "Stop / step", "dpt": "1.007" },
    { "address": "2/1/3", "name": "Position setpoint", "dpt": "5.001" },
    { "address": "2/1/4", "name": "Estimated position", "dpt": "5.001" }
  ],
  "devices": [
    {
      "id": "pushButton",
      "name": "Three-key push-button",
      "address": "1.1.1",
      "kind": "pushButton",
      "behavior": "pushButton/v1",
      "objects": [
        {
          "id": "move",
          "name": "Movement",
          "ga": "2/1/1",
          "dpt": "1.008",
          "port": "input",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "stop",
          "name": "Stop / slat step",
          "ga": "2/1/2",
          "dpt": "1.007",
          "port": "input",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "target",
          "name": "Setpoint",
          "ga": "2/1/3",
          "dpt": "5.001",
          "port": "input",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "feedback",
          "name": "Received estimated position",
          "ga": "2/1/4",
          "dpt": "5.001",
          "port": "display",
          "flags": { "W": true, "T": false }
        }
      ],
      "buttons": [
        {
          "id": "key1",
          "label": "Key 1 · Up",
          "icon": "up",
          "short": { "object": "stop", "value": 0 },
          "long": { "object": "move", "value": 0 }
        },
        {
          "id": "key2",
          "label": "Key 2 · Down",
          "icon": "down",
          "short": { "object": "stop", "value": 1 },
          "long": { "object": "move", "value": 1 }
        },
        { "id": "key3", "label": "Key 3 · 50 %", "press": { "object": "target", "value": 50 } }
      ],
      "inputs": [
        {
          "id": "position",
          "type": "number",
          "label": "Setpoint (%)",
          "object": "target",
          "min": 0,
          "max": 100,
          "step": 1
        }
      ]
    },
    {
      "id": "shutterActuator",
      "name": "Shutter actuator",
      "address": "1.1.3",
      "kind": "shutterActuator",
      "behavior": "shutterActuator/v1",
      "objects": [
        {
          "id": "move",
          "name": "Movement",
          "ga": "2/1/1",
          "dpt": "1.008",
          "port": "move",
          "channel": "s1",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "stop",
          "name": "Stop / step",
          "ga": "2/1/2",
          "dpt": "1.007",
          "port": "stopStep",
          "channel": "s1",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "target",
          "name": "Requested position",
          "ga": "2/1/3",
          "dpt": "5.001",
          "port": "positionCommand",
          "channel": "s1",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "status",
          "name": "Estimated position",
          "ga": "2/1/4",
          "dpt": "5.001",
          "port": "positionStatus",
          "channel": "s1",
          "flags": { "W": false, "T": true }
        }
      ],
      "channels": [
        {
          "id": "s1",
          "label": "Shutter S1",
          "parameters": { "estimatedTravelTimeMs": 20000 },
          "equipment": { "type": "shutter", "parameters": { "actualTravelTimeMs": 30000 } }
        }
      ]
    }
  ],
  "options": { "speed": 1, "filterTables": false }
}

With a 50% target and a configured travel time of 20 seconds, the actuator runs down for 10 seconds and reports 50%. A real shutter that needs 30 seconds to complete its travel reaches only about 33%. Compare the result with a correctly configured actuator:

Edit in designer ↗

{
  "formatVersion": 2,
  "title": "Shutter with correct actuator settings",
  "description": "The same installation with the actuator travel time set to 30 seconds, matching the real shutter. Estimated and actual positions now agree.",
  "lines": [{ "address": "1.1", "name": "Example installation" }],
  "groupAddresses": [
    { "address": "2/1/1", "name": "Movement", "dpt": "1.008" },
    { "address": "2/1/2", "name": "Stop / step", "dpt": "1.007" },
    { "address": "2/1/3", "name": "Position setpoint", "dpt": "5.001" },
    { "address": "2/1/4", "name": "Estimated position", "dpt": "5.001" }
  ],
  "devices": [
    {
      "id": "pushButton",
      "name": "Three-key push-button",
      "address": "1.1.1",
      "kind": "pushButton",
      "behavior": "pushButton/v1",
      "objects": [
        {
          "id": "move",
          "name": "Movement",
          "ga": "2/1/1",
          "dpt": "1.008",
          "port": "input",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "stop",
          "name": "Stop / slat step",
          "ga": "2/1/2",
          "dpt": "1.007",
          "port": "input",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "target",
          "name": "Setpoint",
          "ga": "2/1/3",
          "dpt": "5.001",
          "port": "input",
          "flags": { "W": false, "T": true }
        },
        {
          "id": "feedback",
          "name": "Received estimated position",
          "ga": "2/1/4",
          "dpt": "5.001",
          "port": "display",
          "flags": { "W": true, "T": false }
        }
      ],
      "buttons": [
        {
          "id": "key1",
          "label": "Key 1 · Up",
          "icon": "up",
          "short": { "object": "stop", "value": 0 },
          "long": { "object": "move", "value": 0 }
        },
        {
          "id": "key2",
          "label": "Key 2 · Down",
          "icon": "down",
          "short": { "object": "stop", "value": 1 },
          "long": { "object": "move", "value": 1 }
        },
        { "id": "key3", "label": "Key 3 · 50 %", "press": { "object": "target", "value": 50 } }
      ],
      "inputs": [
        {
          "id": "position",
          "type": "number",
          "label": "Setpoint (%)",
          "object": "target",
          "min": 0,
          "max": 100,
          "step": 1
        }
      ]
    },
    {
      "id": "shutterActuator",
      "name": "Shutter actuator",
      "address": "1.1.3",
      "kind": "shutterActuator",
      "behavior": "shutterActuator/v1",
      "objects": [
        {
          "id": "move",
          "name": "Movement",
          "ga": "2/1/1",
          "dpt": "1.008",
          "port": "move",
          "channel": "s1",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "stop",
          "name": "Stop / step",
          "ga": "2/1/2",
          "dpt": "1.007",
          "port": "stopStep",
          "channel": "s1",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "target",
          "name": "Requested position",
          "ga": "2/1/3",
          "dpt": "5.001",
          "port": "positionCommand",
          "channel": "s1",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "status",
          "name": "Estimated position",
          "ga": "2/1/4",
          "dpt": "5.001",
          "port": "positionStatus",
          "channel": "s1",
          "flags": { "W": false, "T": true }
        }
      ],
      "channels": [
        {
          "id": "s1",
          "label": "Shutter S1",
          "parameters": { "estimatedTravelTimeMs": 30000 },
          "equipment": { "type": "shutter", "parameters": { "actualTravelTimeMs": 30000 } }
        }
      ]
    }
  ],
  "options": { "speed": 1, "filterTables": false }
}

#Communication-object ports

Port	DPT	Effect
`move`	1.008	0 raises toward 0%; 1 lowers toward 100%.
`stopStep`	1.007	Stops a moving shutter. At rest, turns the slats of a venetian blind by one step; has no effect on a roller shutter unless `stepPct` is set.
`positionCommand`	5.001	Sets a target position.
`positionStatus`	5.001	Sends the estimated position after a stop, with a delay.
`scene`	17.001	Recalls a channel position preset.
`slatCommand` / `slatStatus`	5.001	Slat angle setpoint and estimated angle of a venetian blind (0 % open, 100 % closed).
`windAlarm`	1.005, 1.001	1 raises the shutter and ignores other commands; 0 releases it where it is. Without `channel`, applies to all channels.

The position convention is 0% open (top), 100% closed (bottom). A motor wired in reverse is described on the shutter with "wiringReversed": true in its equipment parameters; the actuator's invertOutput compensates it without changing the DPT direction convention. When the two disagree, the shutter moves opposite to the commands and a configuration warning is shown above the diagram.

#Actuator rules

A shutter usually rises more slowly than it falls. estimatedTravelTimeUpMs on the actuator channel and actualTravelTimeUpMs on the shutter set the upward times; without them, the upward time equals the downward time.
startDelayMs (300 ms by default) separates a start or reversal from the previous motor command, preventing simultaneous power in both directions.
A new command replaces a pending start, stop, or status transmission.
At an estimated end stop, a command may have no effect even when the real shutter is elsewhere. endSupplementPct can add extra travel to reach the physical stop; its default is 0.
While a wind alarm is active, move, stop/step, position, and scene commands are ignored and noted in the event log. The end of the alarm does not restore the previous position. See the weather protection example.
A stop/step command at rest turns the slats of a venetian blind (see below). On a roller shutter without slats it has no effect, as in the KNX stop/step function and in most actuator manuals. Some actuators instead move a roller shutter by a small step; set stepPct (for example 5) on the channel to model them.

#Venetian blinds and slats

A venetian blind uses the same motor to turn its slats and to move. Set slatTravelMs, the time for the slats to turn from open to closed, on both sides:

on the actuator channel (parameters.slatTravelMs): the configured time used for the estimate;
on the shutter equipment (equipment.parameters.slatTravelMs): the actual time of the blind.

A movement first turns the slats: closed (100 %) before going down, open (0 %) before going up. A stop/step command at rest turns the slats by slatStepPct (20 % by default) instead of moving the blind. The slatCommand port (DPT 5.001) turns the slats to an angle without moving the blind, and slatStatus reports the estimated angle after each stop. The diagram draws the slats thicker as they close. See the venetian blind example.

#Parameters

"channels": [{
  "id": "s1",
  "label": "Shutter S1",
  "parameters": { "estimatedTravelTimeMs": 20000 },
  "initialState": { "estimatedPositionPct": 0 },
  "equipment": {
    "type": "shutter",
    "parameters": { "actualTravelTimeMs": 30000 },
    "initialState": { "positionPct": 0 }
  }
}]

See the behavior reference for all parameters.