Skip to content
This repository was archived by the owner on Jan 15, 2026. It is now read-only.

Latest commit

 

History

History
158 lines (121 loc) · 8 KB

USER_GUIDE.md

File metadata and controls

158 lines (121 loc) · 8 KB

User Guide — KNX to OpenHAB Generator

This guide explains how to prepare your ETS project, configure the generator, and understand how KNX data types are mapped to OpenHAB items.

Table of Contents

  1. Configuration (config.json)
  2. ETS Project Preparation
  3. Logic & Mappings
  4. Troubleshooting

Configuration (config.json)

The config.json file controls global settings for the generator.

Key Settings

  • drop_words: A list of words to remove from item labels to keep them short.

    • Example: If you have a group address "Kitchen Light Right", and "Light" is in drop_words, the label becomes "Kitchen Right" (assuming the icon already indicates it's a light).
    • Note: Words are NOT dropped if doing so would result in an empty label.

  • openhab_path: The output directory for generated files.

    • Default is openhab.
    • If running on the OpenHAB server, this might point to /etc/openhab.

  • dimmer: Configuration for dimmer detection.

    • absolut_suffix: Suffixes in the GA name identifying the absolute dimming value (e.g., "Dimmen absolut", "Helligkeitswert").
    • status_suffix: Suffixes identifying the status GA (e.g., "Status Dimmwert", "Rückmeldung Dimmen").

  • switch: Configuration for switch detection.

    • status_suffix: Suffixes identifying the status GA (e.g., "Status", "Rückmeldung").

ETS Project Preparation

The generator relies partly on your ETS project structure and naming conventions. You can also use the Description field of Group Addresses (GAs) in ETS to pass special instructions.

Description Field Tags

You can add multiple tags to a GA's description field, separated by semicolons (;).

Tag Effect Example
influx Automatically persist this item to InfluxDB. influx
debug Adds a visibility tag. Item is hidden unless extended_view is enabled. debug;influx
semantic=... Overrides the default Semantic Model tag. See options. semantic=Projector
icon=... Sets a specific icon. icon=pump
location Adds location tags to the first two layers of the GA structure. location
ignore Completely skips importing this GA. ignore
Scene Mapping Maps raw scene numbers to text labels. 1='Cooking', 2='TV'

Example Description: semantic=Pump;icon=pump;debug;influx

Logic & Mappings

The generator automatically determines the OpenHAB Item type based on the Data Point Type (DPT) assigned in ETS.

1. Automatic Type Mapping (Based on DPT)

ETS DPT OpenHAB Item Unit/Note Semantic
DPST-1-1 Switch On/Off Control
DPST-1-5 Switch Alarm Alarm
DPST-1-11 Switch Status Measurement, Status
DPST-1-19 Contact Window/Door Contact OpenState, Opening
DPST-1-24 Switch Window Day/Night Control
DPST-1-100 Switch Heating/Cooling Status Measurement, Status
DPST-5-1 Dimmer Percentage (0-100%) Measurement
DPST-5-010 Number:Dimensionless HVAC Mode (Komfort/Standby/Nacht/Frostschutz) HVAC
DPST-7-12 Number:ElectricCurrent Ampere (A) Measurement, Current
DPST-9-1 Number:Temperature Temperature (°C) Measurement, Temperature
DPST-9-4 Number:Illuminance Brightness (Lux) Measurement, Light
DPST-9-5 Number:Speed Wind Speed (m/s) Measurement, Wind
DPST-9-7 Number:Dimensionless Humidity (%) Measurement, Humidity
DPST-9-8 Number:Dimensionless Air Quality (ppm) Measurement
DPST-12-1200 Number:Volume Volume (L) Measurement, Volume
DPST-13-10 Number:Energy Energy (Wh) Measurement, Energy
DPST-13-100 Number:Time Duration/Time Measurement, Duration
DPST-14-56 Number:Power Power (W) Measurement, Power
DPST-16-0 / DPT-16 String Text/String -
DPST-17-1 Number Scene Number -
DPST-19-1 DateTime Date and Time -
DPST-20-102 Number:Dimensionless HVAC Mode (with Alexa/HomeKit) HVAC

Notes:

  • DPTs with "Number:X" use OpenHAB's Unit of Measurement (UoM) system
  • Some DPTs have specific Alexa/HomeKit integrations configured (e.g., Temperature, Humidity, Window Contact)
  • HVAC modes (DPST-5-010, DPST-20-102) include predefined state options (Komfort=1, Standby=2, Nacht=3, Frostschutz=4)

2. Name-Based Detection

Some complex items require specific naming conventions to be detected correctly, as the DPT alone is not sufficient to group them properly.

Rollershutters

  • Detects Rollershutters based on common naming patterns in the GA name.
  • Combines multiple GAs:
    • Up/Down: "Auf/Ab", "Jalousie Auf/Ab", "Rollladen Auf/Ab" (DPST-1-8)
    • Stop: "Stop", "Stopp", "Lamellenverstellung / Stopp" (DPST-1-10, DPST-1-9, DPST-1-7)
    • Absolute Position: "absolute Position" (DPST-5-1)
    • Status: "Status", "Rückmeldung", "Status aktuelle Position" (DPST-5-1)

Dimmers

  • Looks for a pair or trio of GAs:
    1. Control GA: Name ends with configured absolut_suffix (e.g., "Dimmen absolut", "Helligkeitswert").
    2. Status GA: Name ends with status_suffix (e.g., "Status Dimmwert", "Rückmeldung Dimmen").
    3. Switch GA (optional): Name ends with switch suffix (e.g., "Schalten", "Ein/Aus").
    4. Switch Status GA (optional): Name ends with switch status suffix (e.g., "Status Ein/Aus", "Rückmeldung").
  • The generator merges these into a single OpenHAB Dimmer item.
  • Special metadata override for specific dimmer types:
    • Farbtemperatur: Color temperature control (no Alexa/HomeKit)
    • Lamellenposition: Blind slat position (with Alexa TiltAngle & HomeKit support)
    • Stellwert: HVAC actuator value

Switches (Status Pairing)

  • Looks for a Status GA with the same base name + status_suffix.
  • Example: "Licht Küche" (Cmd) + "Licht Küche Status" (Status) → Single Switch Item with status feedback.
  • Metadata override based on switch name:
    • Licht: Mapped to Light equipment with Alexa/HomeKit integration
    • Steckdose: Mapped to PowerOutlet
    • Heizen: Mapped to HVAC/Heating
    • Audio: Mapped to Speaker

Heating

  • Combines heating mode GAs:
    • Mode Control: "Betriebsmodus", "Betriebsartvorwahl" (DPST-5-010, DPST-20-102)
    • Mode Status: "Status Betriebsmodus", "DPT_HVAC Mode: Reglerstatus senden" (DPST-5-010, DPST-20-102)

Troubleshooting

"My device shows as a generic Number"

  • Cause: DPT is missing or not specific enough in ETS.
  • Fix: Open ETS, select the Group Address, and ensure the correct "Data Type" is selected (e.g., set to "temperature (℃)" instead of just "2-byte float").

"Dimmer not working"

  • Cause: Naming mismatch between Control and Status GAs.
  • Fix: Check config.json for dimmer.absolut_suffix and dimmer.status_suffix, and ensure your ETS names match exactly with one of the configured suffixes.

"Rollershutter not detected"

  • Cause: GA names don't match the expected patterns.
  • Fix: Ensure your GAs follow common naming conventions like "Auf/Ab", "Stop", "absolute Position" or add custom suffixes to the rollershutter section in config.json.

"Item names are too long"

  • Fix: Add common words (like "Licht", "Steckdose", "Fensterkontakt") to the drop_words list in config.json.

"HVAC mode not showing correct options"

  • Cause: Wrong DPT selected in ETS.
  • Fix: Use DPST-5-010 or DPST-20-102 for heating modes. These DPTs have predefined options (1=Komfort, 2=Standby, 3=Nacht, 4=Frostschutz).

"Units not displaying correctly"

  • Cause: Unit of Measurement (UoM) not configured or DPT doesn't specify units.
  • Fix: Use specific DPTs like DPST-9-1 for temperature, DPST-14-56 for power, etc. Generic DPTs (like 9.xxx without subtype) may not include units.