KNX (Building Automation)

KNX is a standardized building automation protocol (ISO/IEC 14543) widely used in Europe for controlling lighting, HVAC, blinds, and energy metering. energy2mqtt connects to KNX/IP gateways via UDP tunneling to read energy meter data and expose it to Home Assistant.

How KNX Works

KNX devices communicate over a twisted-pair bus (KNX TP) or via IP (KNX/IP). energy2mqtt connects to a KNX/IP gateway or interface that bridges the bus to your network. It sends read requests to group addresses and caches the responses for publishing to MQTT.

Typical Setup

[KNX Energy Meter] ---(KNX Bus)---> [KNX/IP Gateway] ---(UDP)---> [energy2mqtt] ---> [Home Assistant]

Common KNX/IP gateways include:

• Weinzierl KNX IP Interface 731
• ABB IPR/S 3.5.1
• MDT SCN-IP100.03
• JUNG IPR 300 SREG
• Siemens N 148/22

Protocol Details

Group Addresses

KNX uses group addresses to identify data points. They are written in a 3-level format:

Main/Middle/Sub

Examples:

• 1/2/3 - Main group 1, middle group 2, sub address 3
• 2/3/82 - Typical energy meter address

Datapoint Types (DPT)

Values on the KNX bus are encoded according to Datapoint Types. energy2mqtt supports the following DPTs for energy metering:

Corresponding Configuration Values

Configuration

KNX configuration in energy2mqtt uses a hierarchical structure:

• Adapters - KNX/IP gateways to connect to
• Meters - Energy meters with their group addresses
• Phases - Individual phases for 3-phase meters
• Switches - On/off switches (optional)

Basic Configuration Example

knx:
  - name: "Main KNX Line"
    host: "192.168.1.100"
    port: 3671
    enabled: true
    meters:
      - name: "Heat Pump"
        manufacturer: "ABB"
        model: "Energy Meter EM/S"
        read_interval: 60
        phases:
          - name: "L1"
            voltage_ga: "2/3/10"
            current_ga: "2/3/20"
            power_ga: "2/3/30"
            energy_ga: "2/3/40"
          - name: "L2"
            voltage_ga: "2/3/11"
            current_ga: "2/3/21"
            power_ga: "2/3/31"
            energy_ga: "2/3/41"
          - name: "L3"
            voltage_ga: "2/3/12"
            current_ga: "2/3/22"
            power_ga: "2/3/32"
            energy_ga: "2/3/42"
        total_energy_ga: "2/3/50"
        calculate_totals: true

Adapter Parameters

Meter Parameters

Single-Phase Meter Example

For simple single-phase meters, you can configure group addresses directly:

knx:
  - name: "Office Line"
    host: "192.168.1.101"
    meters:
      - name: "Office Meter"
        voltage_ga: "3/1/10"
        current_ga: "3/1/11"
        power_ga: "3/1/12"
        energy_ga: "3/1/13"
        energy_type: ActiveEnergyWh  # Values in Wh, converted to kWh

Phase Parameters

Total Values

For 3-phase meters, totals can come from the bus or be calculated:

meters:
  - name: "Main Meter"
    phases:
      - name: "L1"
        # ... phase config
    # Option 1: Read totals from bus
    total_energy_ga: "2/3/50"
    total_power_ga: "2/3/51"
    total_current_ga: "2/3/52"

    # Option 2: Calculate from phases
    calculate_totals: true  # Sums power/current/energy, averages voltage

Output Data

After processing, energy2mqtt publishes meter data to MQTT and creates Home Assistant auto-discovery entries.

MQTT Topics

State topic: energy2mqtt/devs/KNX/{meter_id}

Example output:

{
  "voltage_l1": 230.5,
  "voltage_l2": 231.2,
  "voltage_l3": 229.8,
  "current_l1": 5.2,
  "current_l2": 4.8,
  "current_l3": 5.0,
  "power_l1": 1196.6,
  "power_l2": 1110.96,
  "power_l3": 1149.0,
  "energy_l1": 1234.567,
  "energy_l2": 1198.432,
  "energy_l3": 1212.891,
  "voltage_avg": 230.5,
  "current_all": 15.0,
  "power_all": 3456.56,
  "energy_all": 3645.89
}

Home Assistant Entities

energy2mqtt creates the following entities in Home Assistant:

Diagnostic Data

Each KNX adapter also exposes diagnostic statistics:

Troubleshooting

Common Issues

“Connection timeout”

• Verify the KNX/IP gateway IP address and port
• Check that the gateway is reachable: ping 192.168.1.100
• Ensure no firewall blocks UDP port 3671
• Check if another client is using the tunnel (most gateways only support one tunnel)

“No values received”

• Verify group addresses are correct (check ETS project)
• Ensure read flags (R) are set on the group addresses in ETS
• Some devices only send values on change; try increasing response_wait
• Check that the energy meter is actually transmitting data

“Wrong values or units”

• Verify the correct datapoint type is configured
• Check if the meter uses Wh or kWh for energy (use ActiveEnergyWh or ActiveEnergyKwh)
• Ensure power values use the correct DPT (2-byte float vs 4-byte float)

“Connection drops frequently”

• Increase connection_timeout and read_timeout
• Check for network stability issues
• Some gateways have limited tunnel sessions; ensure only energy2mqtt connects

Getting Group Addresses

If you don’t have access to the ETS project:

1. Ask your installer - They should provide a group address list
2. Use a KNX monitor - Tools like KNXtools can show bus traffic
3. Check device documentation - Energy meters often have standard address schemes
4. Bus scan - Some gateways support scanning for active addresses

Device Hierarchy

energy2mqtt creates a logical device hierarchy in Home Assistant:

e2m_management (energy2mqtt)
└── KNX Adapter (e.g., "Main KNX Line")
    ├── Meter 1 (e.g., "Heat Pump")
    ├── Meter 2 (e.g., "Solar Inverter")
    └── ...

Each meter appears as a separate device linked to its adapter via via_device.