论坛首页 › 『HomeAssistant』新手入门区 › HA官方文档/KNX汉化

whxciotw 发表于 2022-11-11 23:08:24

HA官方文档/KNX汉化

本帖最后由 whxciotw 于 2022-11-11 23:07 编辑

HA官方文档原文链接：KNX - Home Assistant (home-assistant.io)
中文译稿更新时间：2022.11.11
翻译者：whxciotw

前言：业余翻译，敬请斧正。
以下为正文：

使用Home Assistant的KNX集成，能够连接到KNX/IP设备。
本集成需要使用到KNX/IP接口或路由，它将会为Home Assistant与KNX总线间建立连接。
Home Assistant中目前支持如下设备类型：
- Binary Sensor 二元传感器
- Button 按键
- Climate 空调
- Cover 窗帘
- Fan 风扇
- Light 灯
- Notify 通知
- Number 数字
- Scene 场景
- Select 选择器
- Sensor 传感器
- Switch 开关
- Weather 天气
# Configration 配置
点击“(https://my.home-assistant.io/red ... ow_start?domain=knx)”按钮，可以在前端直接添加KNX集成到Home Assistant中。
## Manual configuration steps 手动配置步骤
如果上述的“(https://my.home-assistant.io/red ... ow_start?domain=knx)”按钮点击无效，也可以按照如下步骤手动添加KNX集成：
- 进入Home Assistant；
- 点击侧边栏的“设置”按钮；
- 在配置菜单中选择“设备与服务”；
- 点击底部右侧的“添加集成”按钮；
- 从列表中搜索并选择“KNX”；
- 根据指引完成设置。
# Basic Configuration 基本配置
为了使用KNX的多种功能，用户需要在设置文件中添加相应的配置。这些配置可以在Home Assistant的```configuration.yaml```文件中添加，也可以在拆分出单独的YAML文件中添加。详见[拆分配置文件](https://www.home-assistant.io/do ... ting_configuration/)。
```
knx:
# 在configuration.yaml文件中直接配置KNX功能
binary_sensor:
    - name: "My first binary sensor"
      state_address: "1/2/3"
    # 其他
# 在单独拆分的文件中配置KNX功能
sensor: !include knx_sensor.yaml
```
在下述相应部分可以查看具体如何配置。
## Group Addresses 组地址
组地址为字符串或整数的形式，3级组地址结构为“1/2/3”，2级组地址结构为“1/2”，1级组地址或者无组地址结构时为“1”。
KNX集成使用`state_address`或`*_state_address`来更新功能的状态。这些组地址在Home Assistant启动时通过组地址数值读取（GroupValueRead）请求来读取，也会在1小时内未接收到报文时读取（`sync_state`默认为1小时）。
用户也可以为每个KNX功能（除了`expose`和`notify`）配置被动/监听组地址。针对某一功能，可以配置多个组地址来更新其状态（例如，灯的亮度）。当组地址由一列字符串组成时，第一个字符串为主动发送或读取状态的地址，其余的字符串为被动的地址。这种与ETS的配置方式相类似，即第一个字符串为“发送”地址，而其他字符串仅用于更新通讯对象。
如果你的KNX设备提供了主动的状态通讯对象，则建议使用`*_state_address`而非被动地址来进行配置。这样可以减少配置的复杂度，并且避免错误的设备状态（例如，当通道被逻辑锁定时）。
```
knx:
switch:
    - name: "Switch without passive addresses"
      address: "1/1/1" # 这是发送的目标地址
      state_address: "8/8/8"# 这是组地址数值读取请求发送的目标地址
    - name: "Switch with passive addresses"
      address:
      - "1/1/1" # 这是发送的目标地址
      - "1/1/2" # 这是被动地址
      - "1/1/3"
      state_address:
      - "8/8/8" # 这是组地址数值读取请求发送的目标地址
      - "8/8/2" # 这是被动地址
      - "8/8/3"
```
# Connection 连接
在添加KNX集成时需要设置连接参数，后续可以在集成面板中修改。
如果你的KNX/IP设备在不同的子网网段中，则需使用`route back`。
## KNX Secure KNX安全
KNX集成目前支持IP隧道安全连接，尚不支持IP路由安全连接。
使用IP安全连接，需要在配置过程中选择“隧道连接”->“IP安全的TCP连接”。
你可以手动或者通过`.knxkeys`文件来配置IP安全连接凭据，其中`.knxkeys`文件可以由ETS导出，ETS截图如下。

`.knxkeys`文件必须放置在`config/.storage/knx/yourfile.knxkeys`。
如果你手动配置IP安全连接，则需要用户ID、用户密码和设备认证密码。
用户ID中，0是系统保留用户ID，1是用于管理任务，因此你需要根据使用的隧道通道指定用户ID为≥2。
下方截图展示如何在ETS中获取设备认证密码。

下方截图展示如何在ETS中获取用户密码。

# Events 事件
```
knx:
event:
    - address:
      - "0/1/*"
    - address:
      - "1/2/*"
      - "1/3/2-4"
      type: "2byte_unsigned"
    - address:
      - "3/4/5"
      type: "2byte_float"
```
## Configuration Variables 配置变量
### address 事件地址（列表，字符串，必需）
符合KNX组地址规范的一系列地址。含有目标地址的报文，将会以```knx_event```事件发送到Home Assistant的事件总线。
***
### type 类型（字符串，整数，可选）
在同一区块内，`knx_event`事件中报文的值将会以指定的数据点类型（DPT）解码，解码后的值将会被写入事件数据`value`值。如果未指定类型，则`value`值为`None`-即`data`值将保留为原始值（用于DPT1,2,3）。传感器的类型均为有效的类型，详见(https://www.home-assistant.io/integrations/knx/#sensor)部分（比如，2byte_float或1 byte_signed）。
***
在事件总线上，每个符合目标地址范式的报文将会被播报为`knx_event`事件，并且其中包含如下数据特性：
- `data`数据，包含原始的值的数据（比如，1或"")；
- `destination`目标地址，报文发送的目标组地址，为字符串格式（比如，1/2/3）；
- `direction`方向，报文的方向，为字符串格式（接收/发送）；
- `source`源，发送方的KNX设备的物理地址，为字符串格式（比如，“1.2.3”）；
- `telegramtype`报文类型，报文的APCI服务。“组地址写入”、“组地址读取”或“组地址反馈”可生成`kxn_event`事件；
- `value`值，如果指定了`type`类型，则`value`为解码后的值。在“组地址读取”的报文中，`value`值为`None`。
# Services 服务
可以使用如下服务直接与KNX总线交互：
## Send 发送
```
Domain: knx
Service: send
Service Data: {"address": "1/0/15", "payload": 0, "type": "temperature"}
```
## Configuration Variables 配置变量
### address 地址（字符串）
KNX组地址
### payload 值（字符串，列表）
发送到总线的值。如果未指定`type`类型，则发送原始数据。DPT 1/2/3的值为整数。对于DPTs＞6 bits，应发送列表。每个值代表1个octet（0-255）。 使用0来填充DPT字节长度。
***
### type 类型（字符串，整数，浮点）
如果设置了类型，则数值将不再以原始数据发送，而是以给到的DPT类型解码后发送。传感器的类型均为有效的类型，详见(https://www.home-assistant.io/integrations/knx/#sensor)部分。
***
### response 反馈（布尔值）
如果设置为`true`，则报文以`GroupValueResponse`组地址反馈来发送，而非以`GroupValueWrite`组地址写入来发送。
***
## Read 读取
对于某个实体的所有`*state_address`，你可以使用`homeassistant.update_entity`服务来发送组地址数据读取请求。使用`knx.read`服务来手动发送组地址数据读取请求，在`knx_event`KNX事件中可以查看其反馈，且KNX实体将得到其反馈结果。
## Configuration Variables 配置变量
### address 组地址（字符串，列表）
要读取的组地址。以列表的形式展示要读取的多个组地址。
```
# 自动化示例：窗帘发生动作10s后，更新其窗帘位置
automation:
- trigger:
      - platform: event
      event_type: knx_event
      event_data:
          # 窗帘发生动作触发
          destination: "0/4/20"
    action:
      - delay: 0:0:10
      - service: knx.read
      data:
          # 窗帘位置地址
          address: "0/4/21"

- trigger:
      - platform: homeassistant
      event: start
    action:
      # 注册组地址以触发knx_event事件
      - service: knx.event_register
      data:
          # 窗帘发生动作触发
          address: "0/4/20"
      - service: knx.read
      data:
          # 窗帘位置地址
          address: "0/4/21"
```
## Register Event 注册事件
`knx.event_register`服务可以通过注册（或取消注册）组地址来激活`kxn_event`事件。如果在`congfiguration.yaml`中配置了`event`的值，则事件中的组地址不能取消注册。详见(https://www.home-assistant.io/integrations/knx/#events)。
## Configuration Variables 配置变量
### address 组地址（字符串，列表，必需）
将被添加或移除的组地址。
***
### remove 移除（布尔值，可选，默认为false）
如果设为`true`，则组地址会被移除。
***
### type 类型（字符串，整数，可选）
如果设置了类型，则该值将以指定的DPT类型解码后发送。传感器的类型均为有效的类型，详见(https://www.home-assistant.io/integrations/knx/#sensor)部分。
## Register Exposure 注册曝光
`knx.exposure_register`服务可以注册（或取消注册）至KNX总线的曝光。如果在`congfiguration.yaml`中配置了曝光，则曝光不能取消注册。每个组地址仅能注册一个曝光。详见(https://www.home-assistant.io/in ... -or-time-to-knx-bus)。
## Configuration Variables 配置变量
### remove 移除（布尔值，可选，默认为false）
如果设为`true`，则曝光会被移除。移除时仅需提供组地址。
***
# Exposing entity states, entity attributes or time to KNX bus 向KNX总线曝光实体状态、属性或时间
KNX集成能够向KNX总线曝光实体的状态或属性。KNX集成将向KNX总线广播曝光值的任一改动，也会响应特定组地址的读取请求。KNX集成也可以曝光当前时间。
```
# 配置文件如下
knx:
expose:
    - type: temperature
      entity_id: sensor.owm_temperature
      address: "0/0/2"
    - type: string
      address: "0/6/4"
      entity_id: sensor.owm_weather
    - type: binary
      entity_id: binary_sensor.kitchen_window
      address: "0/6/5"
    - type: binary
      entity_id: light.office
      address: "0/3/0"
      default: false
    - type: percentU8
      entity_id: light.office
      attribute: brightness
      default: 0
      address: "0/3/1"
    - type: time
      address: "0/0/1"
    - type: datetime
      address: "0/0/23"
```
## Configuration Variables 配置变量
### address 组地址（字符串，必需）
状态或属性的更新所发送的目标组地址。将会响应组地址读取请求。
***
### type 类型（字符串，整数，必需）
曝光的值的类型。包括`binary`二元传感器, `time`时间, `date`日期, `datetime`日期时间，或者是(https://www.home-assistant.io/integrations/knx/#sensor)支持的任意类型（比如“temperature温度”或“humidity湿度”）。
***
### entity_id 实体ID（字符串，可选）
曝光的实体ID。对于`time`时间, `date`日期, `datetime`日期时间，无需填写。
***
### attribute 属性（字符串，可选）
被发送至KNX总线的实体的属性。如果不填写（或者填写`None`），则将发送该实体的状态。比如，对于一个灯，其状态是开或关，使用`attribute`，则可以曝光其亮度。
***
### default 默认（布尔值，字符串，整数，浮点，可选，默认为None）
状态或属性为`None`时，发送至总线的默认值。比如，一个关着的、且没有亮度属性的灯，可以使用`0`作为其默认值。如果不填写（或者填写`None`），则不会向总线发送任何值，并且将通过请求该组地址的状态以反馈其最后已知的值。
***
# Binary Sensor 二元传感器
KNX二元传感器功能可以监控KNX的二元传感器设备。
二元传感器为只读。如需向KNX总线写入数据，则需使用KNX Expose功能。
```
knx:
binary_sensor:
    - name: "Sensor 1"
      state_address: "6/0/2"
```
##Configuration Variables 配置变量
### state_address 状态组地址（字符串，列表，必需）
二元传感器的KNX组地址。DPT 1。
***
### name 名称（字符串，可选）
该设备在Home Assistant中展示的名称。
***
### sync_state 同步状态（布尔值，字符串，整数，可选，默认为true）
主动从总线读取状态。如果设置为`false`，则不会向总线发送组地址数值读取请求的报文，即不从总线读取状态。`sync_state`设置为`init`时，仅在启动时读取其状态；`sync_state`设置为`expire <miniutes>`时，在未收到报文的指定时间后读取其状态；`sync_state`设置为`every <miniutes>`时，为每隔指定时间后读取其状态。分钟数的最大值可设定为1440。如果仅配置了一个数字，则此时使用的是在未收到报文的指定时间后读取其状态。默认为`true`，此时是expire 60。
***
### device_class 设备类型（字符串，可选）
设定[设备类型](https://www.home-assistant.io/integrations/binary_sensor/)。可以在前端展示时改变设备的状态和图标。
***
### reset_after 重置（浮点，可选）
在指定的秒数后，将实体状态重新设定为off。
***
### invert 反转（布尔值，可选，默认为false）
将报文的数值反转。该选项将优先于`context_timeout`和`reset_after`生效。
***
### ignore_internal_state 忽略内部状态（布尔值，可选，默认为false）
如果需要忽略报文的内部状态，并且始终触发Home Assistant的状态更新，则设置为`true`。
***
### context_timeout 文本超时（浮点，可选，默认为None）
用于触发自动化时，多个特定报文之间的秒数时间间隔。比如，一个按键开关的自动化，为单击时开关某一个灯，双击时开关另一组灯。此时该设置定义了第二次按键作为双击时所允许的秒数时间间隔。如果你设置为3.0，则在3秒内按下第二次按键，可视作为双击。如果配置文件中添加了`ignore_internal_state`，则默认为`true`。秒数时间间隔允许的最大值为10.0。
***
### entity_category 实体种类（字符串，可选，默认为None）
详见实体的[种类](https://developers.home-assistan ... #generic-properties)。
***
## Support for automations 自动化的支持
你可以使用内置的事件来触发自动化（比如，按某一开关时，打开灯）。
假设你有一个名称为`Livingroom.Switch`的二元传感器，希望单击时打开某一个灯、双击时打开另外两个灯，此时需要在配置文件中添加`context_timeout`。
```
# automation.yaml自动化文件配置示例
automation:
- trigger:
      platform: numeric_state
      entity_id: binary_sensor.livingroom_switch
      attribute: counter
      above: 0
      below: 2
    condition:
      - condition: state
      entity_id: binary_sensor.cover_abstell
      state: "on"
    action:
      - entity_id: light.hue_color_lamp_1
      service: light.turn_on
- trigger:
      platform: numeric_state
      entity_id: binary_sensor.livingroom_switch
      attribute: counter
      above: 1
      below: 3
    condition:
      - condition: state
      entity_id: binary_sensor.cover_abstell
      state: "on"
    action:
      - entity_id: light.hue_bloom_1
      service: homeassistant.turn_on
      - entity_id: light.hue_bloom_2
      service: homeassistant.turn_on
```

## Configuration Variables 配置变量
### name 名称（字符串，可选）
设备在Home Assistant中的名称。
***
### counter 计数（整数，可选，默认为1）
如需双击，则设置2；如需三击，则设置为3。
***
### hook 钩子（字符串，可选，默认为on）
自动化执行时二元传感器所需的状态，为on或off。
***
### action 动作（列表，可选）
根据[自动化规则](https://www.home-assistant.io/docs/automation/action/)设定动作。
# Button 按键
用户可以通过KNX按键功能在前端或使用服务来发送预定的值。用户点击按键时，向KNX总线发送原始值。
>注意：从KNX总线收到的按钮组地址的数值，不能作为按钮的新状态。如果要配置基于特定组地址数值的自动化，需使用`knx_event`。

```
# configuration.yaml配置文件示例
knx:
button:
    - name: "DPT 1 - True button"
      address: "0/0/1"
    - name: "100% button"
      address: "0/0/2"
      payload: 0xFF
      payload_length: 1
    - name: "Temperature button"
      address: "0/0/3"
      value: 21.5
      type: temperature
```
>注意：当配置了`type`时，则`value`为必需项，且`payload`将无效。当配置了`payload_length`时，则`value`将无效。
## Configuration Variables 配置变量
### name 名称（字符串，可选）
设备在Home Assistant中的名称。
***
### address 组地址（字符串，列表，必需）
发送的目标组地址。
***
### payload 数值（整数，可选，默认为1）
发送的原始数值。
***
### payload_length 数值长度（整数，可选，默认为0）
报文中数值的长度。DPT 1、2、3为0。
***
### value 数值（整数，浮点，字符串，可选）
根据`type`编码后发送的值。
***
### type 类型（整数，浮点，字符串，可选）
从[数值类型表格](https://www.home-assistant.io/integrations/knx/#value-types)中选择类型，并根据此来编码相应的数值。
***
### entity_category 实体类型（字符串，可选，默认为None）
实体的[类型](https://developers.home-assistan ... #generic-properties)。
***
# Climate 空调
使用KNX空调功能可以与KNX温控器相连接。配置如下：
```
# configuration.yaml配置文件示例
knx:
climate:
    - name: "Kitchen"
      temperature_address: "5/1/1"
      setpoint_shift_address: "5/1/2"
      setpoint_shift_state_address: "5/1/3"
      target_temperature_state_address: "5/1/4"
      operation_mode_address: "5/1/5"
      operation_mode_state_address: "5/1/6"
```
如果你设备的除霜模式、夜晚模式、舒适模式有另外的组地址，则配置示例如下：
```
# configuration.yaml配置示例
knx:
climate:
    - name: "Kitchen"
      temperature_address: "5/1/1"
      setpoint_shift_address: "5/1/2"
      setpoint_shift_state_address: "5/1/3"
      target_temperature_state_address: "5/1/4"
      operation_mode_frost_protection_address: "5/1/5"
      operation_mode_night_address: "5/1/6"
      operation_mode_comfort_address: "5/1/7"
      operation_mode_state_address: "5/1/8"
```
如果你的设备不支持设定点偏移计算（即，没有`setpoint_shift_address`的组地址），为了避免在前端显示错误，需要设置空调的`min_temp`和`max_temp`属性，并且需要设置`target_temperature_address`的组地址），示例如下：
```
# configuration.yaml配置示例如下
knx:
climate:
    - name: "Kitchen"
      temperature_address: "5/1/2"
      target_temperature_address: "5/1/4"
      target_temperature_state_address: "5/1/1"
      operation_mode_frost_protection_address: "5/1/5"
      operation_mode_night_address: "5/1/6"
      operation_mode_comfort_address: "5/1/7"
      operation_mode_state_address: "5/1/8"
      operation_mode_standby_address: "5/1/9"
      min_temp: 7.0
      max_temp: 32.0
```
`setpoint_shift_mode`可以使用如下两种数据点类型：
- DPT6002（1字节整数）
- DPT9002（2字节浮点）
示例如下：
```
# configuration.yaml配置示例如下
knx:
climate:
    - name: "Kitchen"
      temperature_address: "5/1/1"
      setpoint_shift_address: "5/1/2"
      setpoint_shift_state_address: "5/1/3"
      setpoint_shift_mode: "DPT9002"
      target_temperature_state_address: "5/1/4"
      operation_mode_address: "5/1/5"
      operation_mode_state_address: "5/1/6"
```
如果设置了运行模式组地址`operation_mode_address`，则除霜、夜晚、舒适、待机模式的组地址都不需要设置（`operation_mode_frost_protection_address`、`operation_mode_night_address`、`operation_mode_comfort_address`、`operation_mode_standby_address`）。如果设备没有状态组地址，则配置文件中状态组地址`*_state_address`可以和写入组地址`*_address`相同。在ETS中，必须将状态组地址`*_state_address`设置为可读，以便支持数据的初始读取（比如，HA启动时）。
对于制冷、制热的写入地址和状态地址`heat_cool_address`和`heat_cool_sate_address`，可用以下值来配置：
- `0`（制冷）
- `1`（制热）
Home Assistant中KNX空调的`hvac_mode`属性支持以下值，具体可以通过`controller_modes`来配置：
- `off`（关，对应`HVAC_MODE_OFF`）
- `Auto`（自动，对应`HVAC_MODE_AUTO`）
- `Heat`（制热，对应`HVAC_MODE_HEAT`）
- `Cool`（制冷，对应`HVAC_MODE_COOL`）
- `Fan only`（仅送风，对应`HVAC_MODE_FAN_ONLY`）
- `Dry`（干燥，对应`HVAC_MODE_DRY`）
Home Assistant中KNX空调的`preset_mode`属性支持以下值，具体可以通过`operation_modes`来配置：
- `Auto`（自动，对应`none`)
- `Comfort`（舒适，对应`comfort`)
- `Standby`（待机，对应`away`)
- `Night`（睡眠，对应`sleepp`)
- `Frost Protection`（除霜，对应`eco`)
## Configuration Variables 配置变量
### name 名称（字符串，可选，默认：KNX Climate）
设备在Home Assistant中的名称。
***
### temperature_address 当前温度状态组地址（字符串，列表，必需）
从KNX总线读取的当前环境温度的组地址。DPT 9.001。
***
### temperature_step 温度最小调整值（浮点，可选，默认为：0.1）
每次调整温度时的最小调整值。
***
### target_temerature_address 目标温度写入组地址（浮点，列表，可选）
设定目标温度的组地址。DPT 9.001。
***
### target_temerature_state_address 目标温度状态组地址（浮点，列表，可选）
读取目标温度的组地址。DPT 9.001。
***
### setpoint_shift_address 设定点偏移写入组地址（字符串，列表，可选）
设定点偏移的写入组地址。`setpoint_shift_mode`中为DPT 6.010 or DPT 9.002。
***
### setpoint_shift_state_address 设定点偏移状态组地址（字符串，列表，可选）
读取设定点偏移状态的组地址。`setpoint_shift_state_mode`中为DPT 6.010 or DPT 9.002。
***
### setpoint_shift_mode 设定点偏移模式（字符串，可选，默认为：None）
定义内部设备使用的数据点类型，为‘DPT6010’、‘DPT9002’或None。当设置为`None`或省略不设置时，DPT值将根据首次接受到的报文自动分配。
***
### setpoint_shift_min 设定点偏移最小值（浮点，可选，默认为：-6）
设定点偏移的最小值。
***
### setpoint_shift_max 设定点偏移最大值（浮点，可选，默认为：6）
设定点偏移的最大值。
***
### active_state_address 活动状态组地址（字符串，列表，可选）
读取目前空调状态的组地址，`0`为空闲，`1`为活动。DPT 1。
***
### command_value_state_address 命令值状态组地址（字符串，列表，可选）
以百分比形式来读取当前命令值的KNX组地址。如果未设定`active_state_address`，则此时`0`为设定空调至空闲。DPT 5.001。
***
### operation_mode_address 运行模式写入组地址（字符串，列表，可选）
设定运行模式的组地址（除霜、睡眠、舒适）。DPT 20.102。
***
### operation_mode_state_address 运行模式状态组地址（字符串，列表，可选）
读取运行模式的组地址。DPT 20.102。
***
### controller_status_address 控制器状态写入组地址（字符串，列表，可选）
设定空调控制器状态的组地址（依据KNX AN 097/07 rev 3）。
***
### controller_status_state_address 控制器状态写入组地址（字符串，列表，可选）
读取空调控制器状态的组地址。
***
### controller_mode_address 控制器模式写入组地址（字符串，列表，可选）
设定空调控制器模式的组地址。DPT 20.105。
***
### controller_mode_state_address 控制器模式状态组地址（字符串，列表，可选）
读取空调控制器模式的组地址。DPT 20.105。
***
### heat_cool_address 制冷制热模式写入组地址（字符串，列表，可选）
切换制冷、制热模式的组地址。DPT 1.100。
***
### heat_cool_state_address 制冷制热模式状态组地址（字符串，列表，可选）
读取制冷、制热模式的组地址。DPT 1.100。
***
### operation_mode_frost_protection_address 除霜模式写入组地址（字符串，列表，可选）
开/关除霜模式/热保护模式的组地址。DPT 1。
***
### operation_mode_night_address 睡眠模式写入组地址（字符串，列表，可选）
开/关睡眠模式的组地址。DPT 1。
***
### operation_mode_comfort_address 舒适模式写入组地址（字符串，列表，可选）
开/关舒适模式的组地址。DPT 1。
***
### operation_mode_standby_address 待机模式写入组地址（字符串，列表，可选）
开/关待机模式的组地址。DPT 1。
***
### operation_modes 运行模式（列表，可选）
覆盖原先的运行模式。需提供你的设备所支持的`preset_mode`预设模式的值。
***
### controller_modes 控制器模式（列表，可选）
覆盖原先的控制器模式。需提供你的设备所支持的`hvac_mode`空调控制器模式的值。
***
### default_controller_mode 默认控制器模式（字符串，可选，默认为：制热）
覆盖默认的控制器模式。可以配置为Home Assistant中任一`hvac_mode`中的模式。比如，可以将仅支持制冷的设备设置为`cool`制冷。
***
### on_off_address 开关写入组地址（字符串，列表，可选）
切换设备开/关的组地址。DPT 1。
***
### on_off_invert 开关反转（布尔值，可选，默认为：false）
将切换设备开/关的值反转。
***
### on_off_state_address 开关状态组地址（字符串，列表，可选）
读取设备开/关的状态的组地址。DPT 1。
***
### min_temp 最低温度（浮点，可选）
覆盖原先的最低温度值。
***
### max_temp 最高温度（浮点，可选）
覆盖原先的最高温度值。
***
### entity_category 实体种类（字符串，可选，默认为：None）
实体的[种类](https://developers.home-assistan ... #generic-properties)。
***
# Cover 窗帘
使用KNX窗帘功能可以与KNX窗帘相连接。
> 注意：与大多数KNX设备不同，Home Assistant将0%定义为关闭、100%定义为完全开启。相应数值的反转，将由KNX集成内部来完成计算。

配置如下：
```
# configuration.yaml配置文件示例
knx:
cover:
    - name: "Kitchen shutter"
      move_long_address: "3/0/0"
      move_short_address: "3/0/1"
      stop_address: "3/0/4"
      position_address: "3/0/3"
      position_state_address: "3/0/2"
      travelling_time_down: 51
      travelling_time_up: 61
```
## Configuration Variables 配置变量
### name 名称（字符串，可选，默认：KNX Cover）
设备在Home Assistant中的名称。
***
### move_long_address 长开合组地址（字符串，列表，可选）
完全开/关窗帘的组地址。DPT 1。
***
### move_short_address 渐开合组地址（字符串，列表，可选）
逐渐开/关窗帘的组地址。如果某些KNX窗帘未指定`stop_address`停止开合组地址，则可以使用该功能来停止开合。DPT 1。
***
### stop_address 停止开合组地址（字符串，列表，可选）
停止开/关窗帘的组地址。DPT 1。
***
### position_address 位置写入组地址（字符串，列表，可选）
开/关窗帘至指定位置的组地址。DPT 5.001。
***
### position_state_address 位置状态组地址（字符串，列表，可选）
读取窗帘当前开/关位置的组地址。DPT 5.001。
***
### angle_address 角度写入组地址（字符串，列表，可选）
调整窗帘至指定角度的组地址。DPT 5.001。
***
### angle_state_address 角度状态组地址（字符串，列表，可选）
读取窗帘当前调整角度的组地址。DPT 5.001。
***
### travelling_time_down 下降时长（整数，可选，默认为：25）
窗帘完全下降所需的时长（秒）。
***
### travelling_time_up 上升时长（整数，可选，默认为：25）
窗帘完全上升所需的时长（秒）。
***
### invert_updown 上下反转（布尔值，可选，默认为：false）
设置为`true`时，可以将上升与下降命令反转。默认0是上升，1是下降。
***
### invert_position 位置反转（布尔值，可选，默认为：false）
设置为`true`时，则将0%设置为关闭。
***
### invert_angle 角度反转（布尔值，可选，默认为：false）
设置为`true`时，则将0%设置为关闭。
***
### device_class 设备种类（字符串，可选）
通过设置[设备种类](https://www.home-assistant.io/integrations/cover/)，可以改变前端展示的设备状态和图标。
***
### entity_category 实体种类（字符串，可选，默认为：None）
实体的[种类](https://developers.home-assistan ... #generic-properties)。
***

# Fan 风扇
通过KNX风扇集成，可以控制KNX的风扇设备。以下为支持的控制模式：
- 百分比控制：按照0-100%来设置风速。
- 阶梯控制：按照固定的阶梯数值来设置风速。集成自动将百分比转换成阶梯数值。通过配置`max_step`，可设置风速的最大数值，其中不包含`off`关闭状态。比如：某个风扇支持的风速阶梯数值为0到3，则`max_step`需设置为`3`，且`66%`代表阶梯`2`。
配置如下：
```
# configuration.yaml配置文件示例
knx:
fan:
    - name: "Ceiling fan"
      address: "9/0/1"
      state_address: "9/0/2"
```
## Configuration Variables 配置变量
### name 名称（字符串，可选）
设备在Home Assistant中的名称。
***
### address 风速写入组地址（字符串，列表，必需）
写入风速百分比或阶梯的组地址。DPT 5.001或DPT 5.010。
***
### state_address 风速状态组地址（字符串，列表，可选）
读取风速百分比或阶梯的组地址。DPT 5.001或DPT 5.010。
***
### oscillation_address 摆动写入组地址（字符串，列表，可选）
切换风扇是否摆动的组地址。DPT 1。
***
### oscillation_state_address 摆动状态组地址（字符串，列表，可选）
读取风扇是否摆动的组地址。DPT 1。
***
### max_step 最大阶梯数值（整数，可选）
风扇风速以阶梯控制时的最大风速数值。如果配置了该项，集成将自动将百分比转换成阶梯数值。
***
### entity_category 实体种类（字符串，可选，默认为：None）
实体的[种类](https://developers.home-assistan ... #generic-properties)。
***

# Light 灯
通过KNX灯集成，可以控制KNX的灯具执行器设备，比如：
- 开关执行器
- 调光执行器
- LED控制器
- DALI网关
配置如下：
```
# configuration.yaml配置文件示例
knx:
light:
    - name: "Kitchen"
      address: "1/0/9"
```
## Configuration Variables 配置变量
### name 名称（字符串，可选）
设备在Home Assistant中的名称。
***
### address 开关写入组地址（字符串，列表，必需）
切换灯的开关的组地址。DPT 1.001。
***
### state_address 开关状态组地址（字符串，列表，可选）
读取灯的开关状态的组地址。DPT 1.001。
***
### brightness_address 亮度写入组地址（字符串，列表，可选）
设定灯的亮度百分比（绝对调光）的组地址。DPT 5.001。
***
### brightness_state_address 亮度状态组地址（字符串，列表，可选）
读取灯的亮度百分比的组地址。DPT 5.001。
***
### color_address RGB颜色写入组地址（字符串，列表，可选）
设定灯的RGB颜色的组地址。DPT 232.600。
***
### color_state_address RGB颜色状态组地址（字符串，列表，可选）
读取灯的RGB颜色状态的组地址。DPT 232.600。
***
### rgbw_address RGBW颜色写入组地址（字符串，列表，可选）
设定灯的RGBW颜色的组地址。DPT 232.600。
***
### rgbw_state_address RGBW颜色写入组地址（字符串，列表，可选）
读取灯的RGBW颜色状态的组地址。DPT 232.600。
***
### hue_address 色调写入组地址（字符串，列表，可选）
设定灯的颜色色调的组地址。DPT 5.003。
***
### hue_state_address 色调状态组地址（字符串，列表，可选）
读取灯的颜色色调状态的组地址。DPT 5.003。
***
### saturation_address 饱和度写入组地址（字符串，列表，可选）
设定灯的颜色饱和度的组地址。DPT 5.001。
***
### saturation_state_address 饱和度状态组地址（字符串，列表，可选）
读取灯的颜色饱和度状态的组地址。DPT 5.001。
***
### xyy_address xyY颜色写入组地址（字符串，列表，可选）
设定灯的xyY颜色的组地址。DPT 242.600。
***
### xyy_state_address xyY颜色状态组地址（字符串，列表，可选）
读取灯的xyY颜色状态的组地址。DPT 242.600。
***
### individual_colors 独立颜色设定（匹配，可选）
当KNX执行器仅支持独立颜色的组地址时，使用该参数进行配置。且配置该参数后，灯的`address`地址项将被忽略。
***
#### red 红色（匹配，必需）
红色相关的组地址设定
***
##### address 红色开关写入组地址（字符串，列表，可选）
切换灯的红色开关的组地址。DPT 1.001。
***
##### state_address 红色开关状态组地址（字符串，列表，可选）
读取灯的红色开关状态的组地址。DPT 1.001。
***
##### brightness_address 红色亮度写入组地址（字符串，列表，必需）
设定灯的红色亮度的组地址。DPT 5.001。
***
##### brightness_state_address 红色亮度状态组地址（字符串，列表，可选）
读取灯的红色亮度状态的组地址。DPT 5.001。
***
#### green 绿色（匹配，必需）
配置方式与红色相同。
***
#### blue 蓝色（匹配，必需）
配置方式与红色相同。
***
#### white 白色（匹配，可选）
配置方式与红色相同。
***
### color_temperature_address 色温写入组地址（字符串，列表，可选）
设定灯的色温的组地址。不同色温模式下，数据点类型不同，绝对色温为DPT 5.001，相对色温为DPT 7.600。
***
### color_temperature_state_address 色温状态组地址（字符串，列表，可选）
读取灯的色温状态的组地址。绝对色温为DPT 7.600，相对色温为DPT 5.001。
***
### color_temperature_mode 色温模式（字符串，可选，默认为：absolute）
设定色温模式。`absolute`，绝对色温，用开尔文温度表示，数据类型为
为DPT 7.600；`relative`，相对色温，用冷白百分比表示（0%为最暖，100%为最冷），数据类型为为DPT 5.001。
***
### min_kelvin 最小开尔文温度（整数，可选，默认为：2700）
最暖色温的开尔文温度值，可与`color_temperature_address`同时使用。
***
### max_kelvin 最大开尔文温度（整数，可选，默认为：6000）
最冷色温的开尔文温度值，可与`color_temperature_address`同时使用。
***
### entity_category 实体种类（字符串，可选，默认为：None）
实体的[种类](https://developers.home-assistan ... #generic-properties)。
***
许多KNX设备可以在不向KNX总线发送数据的情况下，直接于设备内部改变其的状态（比如，配置了场景或计时器）。此时通过配置`state_address`状态组地址，可以使Home Assistant同步其状态。
某些开关/灯等执行器不含有单独用于状态通讯的对象和组地址，即仅通过1个组地址来控制。此时，你可以将`state_address`状态组地址与`address`写入组地址设置相同值。
*关于白色调光的注意事项*：Home Assistant使用Mireds迈尔德作为色温单位，然而KNX中单位是Kelvin开尔文，两种色温单位互为倒数、非线性的。因此，Home Assistant中的色温选择器（滑动模块）与KNX中的色温选择并非线性对应。
## Extended configuration examples 扩展配置示例
```
knx:
light:
    # 调光灯
    # 颜色模式：亮度
    - name: "Dimmable light"
      address: "1/0/9"
      state_address: "1/1/9"
      brightness_address: "1/2/9"
      brightness_state_address: "1/3/9"
    # XYY调色灯
    # 颜色模式：xyy
    - name: "XYY light"
      address: "1/0/9"
      state_address: "1/1/9"
      brightness_address: "1/2/9"# 可选，如果未设定亮度，则亮度将以xyy数据点的形式发送
      brightness_state_address: "1/3/9"
      xyy_address: "1/4/9"
      xyy_state_address: "1/5/9"
    # HUE饱和度调光灯
    # 颜色模式：HUE饱和度
    - name: "HS light"
      address: "1/0/9"
      state_address: "1/1/9"
      brightness_address: "1/2/9"# 必需
      brightness_state_address: "1/3/9"
      hue_address: "1/4/8"
      hue_state_address: "1/5/8"# 必需
      saturation_address: "1/4/9"
      saturation_state_address: "1/5/9"# 必需
    # RGB调光灯
    # 调光膜是: rgb
    - name: "RGB light"
      address: "1/0/9"
      state_address: "1/1/9"
      brightness_address: "1/2/9"# 可选
      brightness_state_address: "1/3/9"
      color_address: "1/4/9"
      color_state_address: "1/5/9"
    # RGBW调光灯
    # 颜色模式: rgbw
    - name: "RGBW light"
      address: "0/4/83"
      state_address: "0/4/84"
      brightness_address: "0/4/85"# 可选
      brightness_state_address: "0/4/86"
      rgbw_address: "0/4/87"
      rgbw_state_address: "0/4/88"
    # RGB(W)独立颜色调光灯
    # 颜色模式: rgb / rgbw
    - name: "RGBW individual light"
      address: "1/0/9"# 可选
      individual_colors:
      red:
          brightness_address: "0/4/61"
          brightness_state_address: "0/5/61"
      green:
          brightness_address: "0/4/62"
          brightness_state_address: "0/5/62"
      blue:
          brightness_address: "0/4/63"
          brightness_state_address: "0/5/63"
      white:
          brightness_address: "0/4/64"
          brightness_state_address: "0/5/64"
    # 白色调光灯
    # 颜色模式: color_temp
    - name: "TW light"
      address: "1/0/21"
      state_address: "1/1/21"
      brightness_address: "1/2/21"
      brightness_state_address: "1/3/21"
      color_temperature_address: "1/4/21"
      color_temperature_state_address: "1/5/21"
      color_temperature_mode: absolute
      min_kelvin: 2550
      max_kelvin: 6200
    # KNX执行器不含有单独用于状态通讯的对象和组地址
    # 颜色模式: onoff
    - name: "Simple light"
      address: "1/0/5"
      state_address: "1/0/5"
```
# Notify
使用KNX通知功能，可以向KNX设备发送通知（数据点类型为DPT16字符串）。
```
knx:
notify:
    - name: "Alarm"
      address: "5/1/10"
```
## Configuration Variables 配置变量
### name 名称（字符串，可选）
设备在Home Assistant中的名称。
***
### address 通知组地址（字符串，必需）
发送通知的目标组地址。
***
### type 类型（字符串，可选，默认为：latin_1）
数据点类型，表示用于对通知进行编码的文本值（为 “string” or “latin_1” ，详见(https://www.home-assistant.io/integrations/knx/#sensor)）。

***

# Number 数字
通过KNX数字功能，可以向KNX总线发送数字，也可以从总线接收数字。对于写入组地址的读取请求，也可以选择性反馈。
> 注意：Home Assistant重启后，未配置`state_address`状态组地址的数字实体将恢复其最后一次已知的状态，配置`state_address`状态组地址的数字实体将从KNX总线读取其目前的状态。

```
# configuration.yaml文件配置示例
knx:
number:
    - name: "Duration"
      address: "0/0/1"
      type: time_period_sec
    - name: "Volume"
      address: "0/0/2"
      state_address: "0/0/3"
      type: percent
    - name: "Temperature threshold"
      address: "0/0/4"
      respond_to_read: true
      type: temperature
      min: 20
      max: 24.5
      step: 0.1
      mode: slider
```
## Configuration Variables
### name 名称（字符串，可选）
设备在Home Assistant中的名称。
***
### address 数字写入组地址（字符串，列表，必需）
发送数字的目标组地址。
***
### state_address 数字状态组地址（字符串，列表，可选）
读取数字状态的组地址。
***
### type 类型（字符串，整数，必需）
(https://www.home-assistant.io/integrations/knx/#sensor)所支持的任一类型（例如：`percent`百分比或`temperature`温度）。
***
### respond_to_read 数字写入组地址读取反馈（布尔值，可选，默认为：false）
是否反馈对于`address`数字写入组地址的读取请求。
***
### min 最小值（浮点，可选）
可发送的最小值。默认为`type`类型中的DPT所允许的最小值。
***
### max 最大值（浮点，可选）
可发送的最大值。默认为`type`类型中的DPT所允许的最大值。
***
### step 步长阶梯数值（浮点，可选）
步长阶梯数值。默认为KNX规范中DPT定义的步长阶梯数值。
***
### mode 模式（字符串，可选，默认为：auto）
指定在前端显示时的模式。有`auto`自动、`box`方框或`slider`滑块可选。
***
### entity_category 实体种类（字符串，可选，默认为：None）
实体的[种类](https://developers.home-assistan ... #generic-properties)。
***

# Scene 场景
通过KNX场景功能，你可以触发KNX场景，且这些实体仅可写入。
```
# configuration.yaml文件配置示例
knx:
scene:
    - name: "Romantic"
      address: 8/8/8
      scene_number: 23
```
## Configuration Variables 配置变量
### name 名称（字符串，可选）
设备在Home Assistant中的名称。
***
### address 场景写入组地址（字符串，列表，必需）
KNX场景的组地址。DPT 17.001。
***
### scene_number 场景编号（整数，必需）
激活场景的编号（从1至64）。
***
### entity_category 实体种类（字符串，可选，默认为：None）
实体的[种类](https://developers.home-assistan ... #generic-properties)。
***
# Select 选择
通过KNX选择功能，用户可以向KNX总线发送所选择的值。收到报文后，可以更新所选实体的状态。对于写入组地址的读取请求，也可以选择性反馈。
> 注意：Home Assistant重启后，未配置`state_address`状态组地址的选择实体将恢复其最后一次已知的状态，配置`state_address`状态组地址的选择实体将从KNX总线读取其目前的状态。

```
# configuration.yaml配置文件示例
knx:
select:
    - name: "DPT 2 selector"
      address: "0/0/1"
      payload_length: 0
      options:
      - option: "No control"
          payload: 0
      - option: "Control On"
          payload: 0b10
      - option: "Control Off"
          payload: 0b11
    - name: "DHWMode"
      address: "0/0/2"
      state_address: "0/0/3"
      payload_length: 1
      options:
      - option: "Auto"
          payload: 0
      - option: "LegioProtect"
          payload: 1
      - option: "Normal"
          payload: 2
      - option: "Reduced"
          payload: 3
      - option: "Off/FrostProtect"
          payload: 4
```
## Configuration Variables
### name 名称（字符串，可选）
设备在Home Assistant中的名称。
***
### address 值写入组地址（字符串，列表，必需）
发送值的目标组地址。
***
### state_address 值状态组地址（字符串，列表，可选）
读取值状态的组地址。
***
### payload_length 值长度（整数，必需）
不同DPT类型的值的长度。DPT 1,2,3使用`0`。
***
### options 选项（列表，必需）
供选择的列表选项。每一个`option`和`payload`都必须是唯一的。
#### option 选项（字符串，必需）
选项名称，用于触发指定的`payload`值。
****
#### payload 值（整数，必需）
指定的`option`选项所触发的值。
### respond_to_read 数字写入组地址读取反馈（布尔值，可选，默认为：false）
是否反馈对于`address`写入组地址的读取请求。
***
### sync_state 同步状态（布尔值，字符串，整数，可选，默认为true）
主动从总线读取状态。如果设置为```false```，则不会向总线发送组地址数值读取请求的报文，即不从总线读取状态。```sync_state```设置为```init```时，仅在启动时读取其状态；```sync_state```设置为```expire <miniutes>```时，则在未收到报文的指定时间后读取其状态；```sync_state```设置为```every <miniutes>```时，则为每隔指定时间后读取其状态。分钟数的最大值可设定为1440。如果仅配置了一个数字，则此时使用的是在未收到报文的指定时间后读取其状态。默认为```true```，此时是expire 60。
***
### entity_category 实体种类（字符串，可选，默认为：None）
实体的[种类](https://developers.home-assistan ... #generic-properties)。
***
# Sensor 传感器
通过KNX传感器功能，你可以来监控KNX传感器的状态。
传感器实体为只读。如需向KNX总线写入，则需配置`number`数字、向KNX总线曝光，或者使用`knx.send`发送服务。
```
# configuration.yaml配置文件示例
knx:
sensor:
    - name: "Heating Valve 1"
      state_address: "2/0/0"
      type: percent
```
如需每隔30分钟从总线读取状态，则需在`configuration`配置文件中添加`sycn_state`同步状态如下：
```
# configuration.yaml配置文件示例
knx:
sensor:
    - name: "Heating Valve 1"
      state_address: "2/0/0"
      type: percent
      sync_state: every 30
```
## Configuration Variables 配置变量
### name 名称（字符串，可选）
设备在Home Assistant中的名称。
***
### state_address 传感器状态组地址（字符串，列表，可选）
读取传感器状态的组地址。
***
### type 类型（字符串，整数，必需）
从[数值类型表格](https://www.home-assistant.io/integrations/knx/#value-types)中选择类型。
***
### sync_state 同步状态（布尔值，字符串，整数，可选，默认为true）
主动从总线读取状态。如果设置为```false```，则不会向总线发送组地址数值读取请求的报文，即不从总线读取状态。```sync_state```设置为```init```时，仅在启动时读取其状态；```sync_state```设置为```expire <miniutes>```时，则在未收到报文的指定时间后读取其状态；```sync_state```设置为```every <miniutes>```时，则为每隔指定时间后读取其状态。分钟数的最大值可设定为1440。如果仅配置了一个数字，则此时使用的是在未收到报文的指定时间后读取其状态。默认为```true```，此时是expire 60。
***
### always_callback 总是返回（布尔值，可选，默认为：false）
如果连续两次报文数值相同，在Home Assistant中是否更新其状态。
### state_class 状态分类（字符串，可选）
设定传感器的[状态分类](https://developers.home-assistan ... lable-state-classes)。
***
### entity_category 实体种类（字符串，可选，默认为：None）
实体的[种类](https://developers.home-assistan ... #generic-properties)。
***
## Value Types 值类型
KNX DPT|类型|字节大小|范围|单位
--|:--:|:--:|:--:|:--:
5|1byte_unsigned|1|0 … 255|
5.001|percent|1|0 … 100|%
5.003|angle|1|0 … 360|°
5.004|percentU8|1|0 … 255|%
5.005|decimal_factor|1|0 … 255|
5.006|tariff|1|0 … 254|
5.010|pulse|1|0 … 255|counter pulses
6|1byte_signed|1|-128 … 127|
6.001|percentV8|1|-128 … 127|%
6.010|counter_pulses|1|-128 … 127|counter pulses
7|2byte_unsigned|2|0 … 65535|
7.001|pulse_2byte|2|0 … 65535|pulses
7.002|time_period_msec|2|0 … 65535|ms
7.003|time_period_10msec|2|0 … 65535|ms
7.004|time_period_100msec|2|0 … 65535|ms
7.005|time_period_sec|2|0 … 65535|s
7.006|time_period_min|2|0 … 65535|min
7.007|time_period_hrs|2|0 … 65535|h
7.011|length_mm|2|0 … 65535|mm
7.012|current|2|0 … 65535|mA
7.013|brightness|2|0 … 65535|lx
7.600|color_temperature|2|0 … 65535|K
8|2byte_signed|2|-32768 … 32767|
8.001|pulse_2byte_signed|2|-32768 … 32767|pulses
8.002|delta_time_ms|2|-32768 … 32767|ms
8.003|delta_time_10ms|2|-32768 … 32767|ms
8.004|delta_time_100ms|2|-32768 … 32767|ms
8.005|delta_time_sec|2|-32768 … 32767|s
8.006|delta_time_min|2|-32768 … 32767|min
8.007|delta_time_hrs|2|-32768 … 32767|h
8.010|percentV16|2|-32768 … 32767|%
8.011|rotation_angle|2|-32768 … 32767|°
9|2byte_float|2|-671088.64 … 670760.96|
9.001|temperature|2|-273 … 670760|°C
9.002|temperature_difference_2byte|2|-670760 … 670760|K
9.003|temperature_a|2|-670760 … 670760|K/h
9.004|illuminance|2|0 … 670760|lx
9.005|wind_speed_ms|2|0 … 670760|m/s
9.006|pressure_2byte|2|0 … 670760|Pa
9.007|humidity|2|0 … 670760|%
9.008|ppm|2|-671088.64 … 670760.96|ppm
9.010|time_1|2|-670760 … 670760|s
9.011|time_2|2|-670760 … 670760|ms
9.020|voltage|2|-671088.64 … 670760.96|mV
9.021|curr|2|-671088.64 … 670760.96|mA
9.022|power_density|2|-671088.64 … 670760.96|W/m²
9.023|kelvin_per_percent|2|-671088.64 … 670760.96|K/%
9.024|power_2byte|2|-671088.64 … 670760.96|kW
9.025|volume_flow|2|-671088.64 … 670760.96|l/h
9.026|rain_amount|2|-671088.64 … 670760.96|l/m²
9.027|temperature_f|2|-459.6 … 670760|°F
9.028|wind_speed_kmh|2|0 … 670760|km/h
9.?|enthalpy|2|-671088.64 … 670760.96|H
12|4byte_unsigned|4|0 … 4294967295|
12.1200|volume_liquid_litre|4|0 … 4294967295|l
12.1201|volume_m3|4|0 … 4294967295|m³
13|4byte_signed|4|-2147483648 … 2147483647|
13.001|pulse_4byte|4|-2147483648 … 2147483647|pulses
13.002|flow_rate_m3h|4|-2147483648 … 2147483647|m³/h
13.010|active_energy|4|-2147483648 … 2147483647|Wh
13.011|apparant_energy|4|-2147483648 … 2147483647|VAh
13.012|reactive_energy|4|-2147483648 … 2147483647|VARh
13.013|active_energy_kwh|4|-2147483648 … 2147483647|kWh
13.014|apparant_energy_kvah|4|-2147483648 … 2147483647|kVAh
13.015|reactive_energy_kvarh|4|-2147483648 … 2147483647|kVARh
13.100|long_delta_timesec|4|-2147483648 … 2147483647|s
14|4byte_float|4||
14.000|acceleration|4||m/s²
14.001|acceleration_angular|4||rad/s²
14.002|activation_energy|4||J/mol
14.003|activity|4||s⁻¹
14.004|mol|4||mol
14.005|amplitude|4||
14.006|angle_rad|4||rad
14.007|angle_deg|4||°
14.008|angular_momentum|4||J s
14.009|angular_velocity|4||rad/s
14.010|area|4||m²
14.011|capacitance|4||F
14.012|charge_density_surface|4||C/m²
14.013|charge_density_volume|4||C/m³
14.014|compressibility|4||m²/N
14.015|conductance|4||S
14.016|electrical_conductivity|4||S/m
14.017|density|4||kg/m³
14.018|electric_charge|4||C
14.019|electric_current|4||A
14.020|electric_current_density|4||A/m²
14.021|electric_dipole_moment|4||C m
14.022|electric_displacement|4||C/m²
14.023|electric_field_strength|4||V/m
14.024|electric_flux|4||c
14.025|electric_flux_density|4||C/m²
14.026|electric_polarization|4||C/m²
14.027|electric_potential|4||V
14.028|electric_potential_difference|4||V
14.029|electromagnetic_moment|4||A m²
14.030|electromotive_force|4||V
14.031|energy|4||J
14.032|force|4||N
14.033|frequency|4||Hz
14.034|angular_frequency|4||rad/s
14.035|heatcapacity|4||J/K
14.036|heatflowrate|4||W
14.037|heat_quantity|4||J
14.038|impedance|4||Ω
14.039|length|4||m
14.040|light_quantity|4||lm s
14.041|luminance|4||cd/m²
14.042|luminous_flux|4||lm
14.043|luminous_intensity|4||cd
14.044|magnetic_field_strength|4||A/m
14.045|magnetic_flux|4||Wb
14.046|magnetic_flux_density|4||T
14.047|magnetic_moment|4||A m²
14.048|magnetic_polarization|4||T
14.049|magnetization|4||A/m
14.050|magnetomotive_force|4||A
14.051|mass|4||kg
14.052|mass_flux|4||kg/s
14.053|momentum|4||N/s
14.054|phaseanglerad|4||rad
14.055|phaseangledeg|4||°
14.056|power|4||W
14.057|powerfactor|4||cosΦ
14.058|pressure|4||Pa
14.059|reactance|4||Ω
14.060|resistance|4||Ω
14.061|resistivity|4||Ω m
14.062|self_inductance|4||H
14.063|solid_angle|4||sr
14.064|sound_intensity|4||W/m²
14.065|speed|4||m/s
14.066|stress|4||Pa
14.067|surface_tension|4||N/m
14.068|common_temperature|4||°C
14.069|absolute_temperature|4||K
14.070|temperature_difference|4||K
14.071|thermal_capacity|4||J/K
14.072|thermal_conductivity|4||W/mK
14.073|thermoelectric_power|4||V/K
14.074|time_seconds|4||s
14.075|torque|4||N m
14.076|volume|4||m³
14.077|volume_flux|4||m³/s
14.078|weight|4||N
14.079|work|4||J
16.000|string|14|ASCII|
16.001|latin_1|14|ISO 8859-1 / Latin-1|
17.001|scene_number|1|1 … 64|
## More examples 更多示例
```
# configuration.yaml配置文件示例
knx:
sensor:
    - name: "Heating Valve 1"
      state_address: "2/0/0"
      sync_state: init
      type: percent
    - name: "Kitchen Temperature"
      state_address: "6/2/1"
      sync_state: every 60
      type: temperature
      state_class: measurement
```
# Switch 开关
使用KNX开关功能可以与KNX开关执行器相连接。
```
knx:
switch:
    - name: "Kitchen coffee maker"
      address: "1/1/6"
```
## Configuration Variables 配置变量
### name 名称（字符串，可选）
设备在Home Assistant中的名称。
***
### address 开关写入组地址（字符串，列表，必需）
切换开关的开启/关闭的组地址。DPT 1。
***
### state_address 开关状态组地址（字符串，列表，可选）
读取开关状态的组地址。DPT 1。
***
### invert 反转（布尔值，可选，默认为false）
将报文的数值反转。
***
### respond_to_read 写入组地址读取反馈（布尔值，可选，默认为：false）
是否反馈对于`address`写入组地址的读取请求。
***
### entity_category 实体种类（字符串，可选，默认为：None）
实体的[种类](https://developers.home-assistan ... #generic-properties)。
***
### device_class 设备类型（字符串，可选）
设置[设备类型](https://www.home-assistant.io/integrations/switch/)。可以在前端展示时改变设备的状态和图标。
***
通过配置`state_address`状态组地址，可以使Home Assistant同步实体的状态，此时其状态的改变将不由`address`写入组地址来触发。（比如，配置了计时器）。
Home Assistant重启后，未配置`state_address`状态组地址的开关实体将恢复其最后一次已知的状态，配置`state_address`状态组地址的开关实体将从KNX总线读取其目前的状态。

# Weather 天气
使用KNX天气功能可以与KNX气象站相连接。
配置如下：
```
# configuration.yaml配置文件示例
knx:
weather:
    - name: "Home"
      address_temperature: "7/0/0"
      address_brightness_south: "7/0/1"
      address_brightness_west: "7/0/2"
      address_brightness_east: "7/0/3"
      address_brightness_north: "7/0/11"
      address_wind_speed: "7/0/4"
      address_rain_alarm: "7/0/5"
      address_frost_alarm: "7/0/6"
      address_wind_alarm: "7/0/7"
      address_day_night: "7/0/8"
      address_air_pressure: "7/0/9"
      address_humidity: "7/0/10"
      sync_state: true
```
## Configuration Variables 配置变量
### name 名称（字符串，可选）
设备在Home Assistant中的名称。
***
### address_temperatuer 温度组地址（字符串，列表，必需）
从KNX总线读取当前外部温度的组地址。DPT 9.001。
***
### address_brightness_south 南侧亮度组地址（字符串，列表，可选）
南侧亮度的组地址。DPT 9.004。
***
### address_brightness_west 西侧亮度组地址（字符串，列表，可选）
西侧亮度的组地址。DPT 9.004。
***
### address_brightness_east 东侧亮度组地址（字符串，列表，可选）
东侧亮度的组地址。DPT 9.004。
***
### address_brightness_north 北侧亮度组地址（字符串，列表，可选）
北侧亮度的组地址。DPT 9.004。
***
### address_wind_bearing 风向组地址（字符串，列表，可选）
风向的组地址。DPT 5.003。
***
### address_wind_speed 风速组地址（字符串，列表，可选）
风速的组地址。DPT 9.005。
***
### address_rain_alarm 雨水警告组地址（字符串，列表，可选）
雨水警告开启/关闭的组地址。
***
### address_frost_alarm 霜冻警告组地址 （字符串，列表，可选）
从KNX总线读取霜冻警告开启/关闭的组地址。
***
### address_wind_alarm 刮风警告组地址（字符串，列表，可选）
刮风警告开启/关闭的组地址。
***
### address_day_night 昼夜组地址（字符串，列表，可选）
读取白天/黑夜的组地址。
***
### address_air_pressure （字符串，列表，可选）
气压的组地址。DPT 9.006。
***
### address_humidity （字符串，列表，可选）
湿度的组地址。DPT 9.007。
***
### sync_state 同步状态（布尔值，字符串，整数，可选，默认为true）
主动从总线读取状态。如果设置为```false```，则不会向总线发送组地址数值读取请求的报文，即不从总线读取状态。
***
### entity_category 实体种类（字符串，可选，默认为：None）
实体的[种类](https://developers.home-assistan ... #generic-properties)。
***
# Troubleshooting / Common issues 疑难及常见问题
## Logs for the KNX integration KNX集成的日志
KNX通讯中使用`xknx`库，其提供了多种日志查看方式。在`configuration.yaml`文件中添加如下配置以查看日志：
```
logger:
default: warning
logs:
    # `xnx.log`、`xknx.knx`或`xknx.telegram`为常见的debug方式。
    xknx: debug# 设定所有日志的级别。
    xknx.log: debug# 提供一般信息（连接信息等）。
    xknx.raw_socket: debug# 以十六进制查看收到的UDP帧
    xknx.knx: debug# 在socket层查看接收和发送的KNX/IP帧。
    xknx.telegram: debug# 查看在设备层处理前或发送到接口前的报文。
    xknx.state_updater: debug# 提供状态更新的信息。
```
你可以使用`logger.set_level`设定日志级别服务来直接改变所需处理的日志级别。
## Group address can not be read 无法读取组地址
如果没有针对某个实体单独配置，则Home Assistant将会在启动时依次读取每一个实体的`*_state_address`状态地址。如果日志中出现如下错误，表示Home Assistant无法及时读取该组地址。
```
> Could not sync group address '1/2/3' (Entity name - Feature)
> Error: KNX bus did not respond in time (2.0 secs) to GroupValueRead request for: '1/2/3'
```
### No communication object (CO) assigned to the group address (GA) has the Read-Flag set in ETS ETS中，组地址的通讯对象未勾选可读
- 在ETS中将该组地址表示当前状态的通讯对象勾选为可读（例如，调光执行器的`brightness_state_address`）。
### Response telegrams are not passing a line coupler, router or other filter in the installation 反馈报文无法通过支线耦合器、路由或其他的过滤器。
- 这个可以在ETS在线目录中找到一个空白设备，并添加至ETS。将空白设备分配到Home Assistant可连接的支线，并分配组地址。在更新其应用后，ETS将生成该支线下的过滤表。
### Unresponsive system 系统未反馈
- 当组地址读取请求进入发送队列时，记录错误的超时（2秒）日志则开始计时。系统层面，会将高负荷的信息延迟发送（比如，树莓派在启动时加载多项集成）。此时，系统会稍后处理接收中的反馈报文，但信息不会丢失。
## Duplicate entities 重复的实体
如果日志中出现了如下错误，意味着你可能在配置文件中添加了重复的实体。
```
Platform knx does not generate unique IDs. ID 1/2/3 already exists - ignoring platform.name
```
KNX实体的`unique_id`唯一ID是根据必要的配置参数生成：
- binary_sensor 二元传感器： `state_address`状态组地址。
- climate 空调：`temperature_address`当前温度状态组地址、 `target_temperature_state_address`目标温度状态组地址、`target_temperature_address`目标温度写入组地址、`setpoint_shift_address`设定点偏移写入组地址。
- cover 窗帘：`move_long_address`长开合组地址、`position_address`渐开合组地址。
- fan 风扇：`address`风速写入组地址。
- light 灯：`address`开关写入组地址，如果仅使用了`individual_colors`独立颜色设定，则根据`brightness_address`亮度写入组地址一同生成。
- notify 通知： `address`通知组地址。
- scene 场景：`address`场景写入组地址和`scene_number`场景编号。
- sensor 传感器：`state_address`传感器状态地址。
- switch 开关：`address`开关写入组地址。
- weather 温度： `address_temperature`温度组地址。

在同一个功能中，即使其他配置变量不同，也不能给多个实体使用相同的组地址。
## xknx.yaml configuration xknx.yaml文件配置
```
> The 'config_file' option near /homeassistant/configuration.yaml:42 is deprecated, please remove it from your configuration
> Invalid config for : is an invalid option for . Check: knx->knx->config_file.
```
该功能是在`configuration.yaml`配置文件中通过`config_file:`指定xknx配置模式文件，其自Home Assistant 2021.4版本起已失效。你可以使用(https://xknx.io/config-converter/)将其转换为与Home Assistant兼容的`configuration.yaml`配置文件模式。

Ari 发表于 2022-11-11 23:33:39

顶起来，好帖子。感谢分享

Midnight 发表于 2022-11-12 13:39:58

顶起来，感谢版主的无私奉献

SilverWolf 发表于 2022-11-12 15:02:24

楼主辛苦，这么多确实顶。感谢版主无私奉献。

chnpeterx 发表于 2022-12-24 18:25:01

谢谢楼主的成果

solitudeycq 发表于 2023-1-28 10:13:52

支持支持，感谢分享

Midnight 发表于 2023-1-28 11:22:24

楼主辛苦，这么多确实顶。感谢版主无私奉献。

Oranje123 发表于 2023-6-24 23:28:52

感谢楼主！

liyachuan 发表于 2023-6-25 21:18:56

感谢楼主，真的

rickyshen 发表于 2023-8-12 11:05:51

太有用了，感谢楼主。

查看完整版本: HA官方文档/KNX汉化