---
title: Telegraf Documentation
description: Telegraf plugin for collecting metrics from KNX
url: https://docs.influxdata.com/telegraf/v1/input-plugins/knx_listener/
estimated_tokens: 1651
product: Telegraf
version: v1
---

-   Telegraf v1.19.0+

# KNX Input Plugin

This service plugin listens for messages on the [KNX home-automation bus](https://www.knx.org) by connecting via a KNX-IP interface. Information about supported KNX datapoint-types can be found at the underlying [`knx-go` project](https://github.com/vapourismo/knx-go).

**Introduced in:** Telegraf v1.19.0 **Tags:** iot **OS support:** all

## Service Input

This plugin is a service input. Normal plugins gather metrics determined by the interval setting. Service plugins start a service to listen and wait for metrics or events to occur. Service plugins have two key differences from normal plugins:

1. The global or plugin specific `interval` setting may not apply
2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce output for this plugin

## Global configuration options

Plugins support additional global and plugin configuration settings for tasks such as modifying metrics, tags, and fields, creating aliases, and configuring plugin ordering. See [CONFIGURATION.md](/telegraf/v1/configuration/#plugins) for more details.

## Configuration

```toml
# Listener capable of handling KNX bus messages provided through a KNX-IP Interface.
[[inputs.knx_listener]]
  ## Type of KNX-IP interface.
  ## Can be either "tunnel_udp", "tunnel_tcp", "tunnel" (alias for tunnel_udp) or "router".
  # service_type = "tunnel"

  ## Address of the KNX-IP interface.
  service_address = "localhost:3671"

  ## Measurement definition(s)
  # [[inputs.knx_listener.measurement]]
  #   ## Name of the measurement
  #   name = "temperature"
  #   ## Datapoint-Type (DPT) of the KNX messages
  #   dpt = "9.001"
  #   ## Use the string representation instead of the numerical value for the
  #   ## datapoint-type and the addresses below
  #   # as_string = false
  #   ## List of Group-Addresses (GAs) assigned to the measurement
  #   addresses = ["5/5/1"]

  # [[inputs.knx_listener.measurement]]
  #   name = "illumination"
  #   dpt = "9.004"
  #   addresses = ["5/5/3"]
```

### Related tools

-   [knx-telegraf-config-generator](https://github.com/svsool/knx-telegraf-config-generator): generates a Telegraf configuration from a KNX project file

### Measurement configurations

Each measurement contains only one datapoint-type (DPT) and assigns a list of addresses to this measurement. You can, for example group all temperature sensor messages within a “temperature” measurement. However, you are free to split messages of one datapoint-type to multiple measurements.

You should not assign a group-address (GA) to multiple measurements!

## Metrics

Received KNX data is stored in the named measurement as configured above using the “value” field. Additional to the value, there are the following tags added to the datapoint:

-   `groupaddress`: KNX group-address corresponding to the value
-   `unit`: unit of the value
-   `source`: KNX physical address sending the value

To find out about the datatype of the datapoint please check your KNX project, the KNX-specification or the “knx-go” project for the corresponding DPT.

## Example Output

This section shows example output in Line Protocol format.

```text
illumination,groupaddress=5/5/4,host=Hugin,source=1.1.12,unit=lux value=17.889999389648438 1582132674999013274
temperature,groupaddress=5/5/1,host=Hugin,source=1.1.8,unit=°C value=17.799999237060547 1582132663427587361
windowopen,groupaddress=1/0/1,host=Hugin,source=1.1.3 value=true 1582132630425581320
```

#### Related

-   [Configure plugins](/telegraf/v1/configure_plugins/)
-   [KNX Plugin Source](https://github.com/influxdata/telegraf/tree/v1.38.4/plugins/inputs/knx_listener/README.md)