ESPHome Components

This repository contains custom ESPHome components for devices developed by IoTLabs.

panasonic_aquarea

This component allows to communicate with Panasonic Aquarea heat pumps using their serial interface. It supports reading various parameters from the heat pump, such as temperature, pressure, and operating mode.

Heavily based on Heishamon. Thanks to the authors for grunt work of reverse-engineering the proprietary protocol used by Panasonic Aquarea heat pumps and making it available to the public.

Example configuration:

uart:
  - id: heatpump_uart
    tx_pin: GPIO0
    rx_pin: GPIO1
    baud_rate: 9600
    data_bits: 8
    parity: EVEN
    stop_bits: 1
# optional UART for CZ-TAW1 remote controller
  - id: remote_uart
    tx_pin: GPIO2
    rx_pin: GPIO3
    baud_rate: 9600
    data_bits: 8
    parity: EVEN
    stop_bits: 1

panasonic_aquarea:
  uart_id: heatpump_uart
  external_controller_uart_id: remote_uart

sensor:
  - platform: panasonic_aquarea
    top: 1
  - platform: panasonic_aquarea
    top: 5

switch:
  - platform: panasonic_aquarea
    set: 1
  - platform: panasonic_aquarea
    set: 10

All available entities are listed in the catalogs:

• by Entity Type
• by Heishamon ID
• by Name

socket_transmitter

This component is used to send data to a remote server using a socket connection. It supports both TCP and UDP protocols. Especially is made for sending wM-Bus packets to a remote server for further processing.

Example configuration:

socket_transmitter:
  id: transmitter
  ip_address: <remote_host>
  port: <remote_port>
  protocol: <tcp|udp>

interval:
  - interval: 10s
    then:
      - socket_transmitter.send:
          id: transmitter
          data: "Hello, World!"

wmbus_common

This component decodes wM-Bus telegrams with the driver definitions of wmbusmeters, compiled into the firmware at build time. See components/wmbus_common/README.md for details.

Example configuration:

wmbus_common:
    drivers: all
    # or specify specific drivers
    drivers:
      - apator162
      - amiplus
    # or specify drivers and their fields to be loaded
    drivers:
      - name: apator162
        fields:
          - total_m3
      - amiplus
      - name: sensostar
        fields:
          - total_kwh
      - waterstarm

If you use wmbus_meter component, you may not need to configure wmbus_common component, as it will be automatically included as a dependency. Dependent components will automatically load required drivers and fields based on their configuration, so specifying them on this level is redundant.

However, if you want to load specific drivers or fields that are not required by any dependent component, you should specify them in wmbus_common configuration. These are also the drivers a meter with type: auto chooses from.

wmbus_meter

This component provides abstraction for Meter object for wM-Bus devices. Attaching instance to the wmbus_radio component allows to receive, decrypt and parse wM-Bus packets from the radio interface.

Example configuration:

wmbus_meter:
  id: my_water_meter
  radio_id: radio_component
  meter_id: 12345678
  type: apator162
  key: "00000000000000000000000000000000"
  on_telegram:
    - socket_transmitter.send:
        id: transmitter
        data: !lambda return meter->as_json();
    - wmbus_meter.send_telegram_with_mqtt:
        topic: test/topic

type is the driver name, or auto to detect the driver from the first telegram among the drivers listed in wmbus_common. key parameter is optional and allows to decrypt packets using AES-128-CBC encryption. It should be provided as hexadecimal or ASCII encoded string. If not set, packets will be processed as unencrypted.

Attention! By default, component will not load any fields to reduce memory footprint. If you need specific fields (or all fields) you can specify them in wmbus_common component configuration. Only specified fields will be available in meter variable in on_telegram trigger, will be serialized with as_json method etc.

Component provides on_telegram trigger that can be used to send data to a remote server or process it in any other way. It can be used to send data to MQTT broker, HTTP server, or any other service. meter variable is available in the following lambdas. Additionally, wmbus_meter.send_telegram_with_mqtt action can be used to send JSON-encoded meter data to MQTT broker. It requires mqtt component to be configured in ESPHome.

meter->as_json() returns the media and the meter's fields: {"media":"water","total_m3":123.456,"status":"OK"}.

On the wmbus_meter platform, you can use the following sensors to provide data to Home Assistant/MQTT:

• sensor: as abstraction for numerical values from the meter, such as consumption, volume, etc.

  sensor:
    - platform: wmbus_meter
      id: my_water_meter_consumption
      parent_id: my_water_meter
      name: "Water Meter Total Consumption"
      field: total_m3

  By default, unit of measurement and accuracy decimals are picked from the field name, but you can override them. To publish the value in another unit, ESPHome's multiply filter may be useful.

• text_sensor

  text_sensor:
    - platform: wmbus_meter
      id: some_sensor
      parent_id: my_water_meter
      name: My Water Meter Timestamp
      field: timestamp

  Besides the driver's fields, timestamp and media are available.

When you use sensor and text_sensor platforms, required fields will be automatically loaded for corresponding driver, so you don't need to specify them in wmbus_common component configuration.

For both sensor and text_sensor, all config from generic Sensor and Text Sensor components is available, so you can use filters, icons, etc.

wmbus_radio

This component provides a radio interface for 868 MHz LoRa transceivers, allowing it to receive wM-Bus packets. It supports Semtech SX1276 (RFM95/RFM96) and SX1262 modules. It needs ESPHome 2026.8.0 or newer and an spi component configured.

SX1276 example:

spi:
  clk_pin: GPIO0
  mosi_pin: GPIO1
  miso_pin: GPIO2
  id: spi_bus

wmbus_radio:
  id: radio_component
  radio_type: SX1276
  cs_pin: GPIO3
  reset_pin: GPIO4
  dio1_pin: GPIO5
  on_frame:
    - wmbus_radio.send_frame_with_socket:
        id: transmitter
        format: rtlwmbus

reset_pin and dio1_pin go to the RESET and DIO1 pins of the radio module. irq_pin is the old name of dio1_pin; it still works with a deprecation warning and will be removed in 2027.3.0.

SX1262 example:

spi:
  clk_pin: GPIO0
  mosi_pin: GPIO1
  miso_pin: GPIO2

wmbus_radio:
  id: radio_component
  radio_type: SX1262
  cs_pin: GPIO3
  reset_pin: GPIO4
  busy_pin: GPIO5
  dio1_pin: GPIO6
  rf_switch: true
  tcxo_voltage: 1.8V
  use_dcdc: true

SX1262 also needs busy_pin wired to its BUSY pin. tcxo_voltage is optional and accepts the supported SX1262 voltages: 1.6V, 1.7V, 1.8V, 2.2V, 2.4V, 2.7V, 3.0V, or 3.3V. It defaults to 0V, for modules where DIO3 does not control a TCXO. rf_switch defaults to false; enable it only when DIO2 drives the RF switch. use_dcdc defaults to true. rx_boost (default false) switches the receiver to boosted gain, trading a little more current for better sensitivity.

The on_frame trigger can be used to send received wM-Bus packets to a remote server using socket_transmitter component. It can also be used to process packets in any other way, such as sending them to MQTT broker or HTTP server.

Disclaimer

wmbus_* components are based on work of SzczepanLeon's ESPHome Components repository. Thanks to the authors for their work and making it available to the public.