Modbus Integration with ESPHome Packages

One of the most powerful features of boneIO is its ability to communicate with advanced external devices, such as heat pumps, heat recovery ventilators (HRVs), or energy meters. These devices often use the Modbus RTU protocol for communication.

Manually configuring Modbus in ESPHome can be complicated. To simplify this process as much as possible, we have prepared ESPHome Packages—ready-made configuration templates that do all the complex work for you.

How does it work?

An ESPHome package is simply a YAML file with pre-built logic. Instead of writing dozens of lines of code, you just need to include our package and fill in a few simple variables in the substitutions section, such as the Modbus address of your device. That's it!

Step-by-Step Configuration

The following example shows how to read temperatures from a Modbus device (e.g., a heat pump) and expose them as sensors in Home Assistant.

Prerequisites

• A working ESPHome add-on installed.
• Your boneIO device is adopted in the ESPHome dashboard.
• You know how to edit the YAML configuration file.

Step 1: Include the Modbus Package

In your YAML configuration file for the boneIO device, add the packages section and point it to our eg sdm630.yaml file. This will import all the necessary logic for handling the RS485 bus.

packages:
  remote_package:
    url: https://github.com/boneIO-eu/esphome-packages
    ref: main
    files: [sdm630.yaml]

Step 2: Fill in the substitutions section

Now, add the substitutions section. This is where you "fill out a form" with the details of your Modbus device. You don't need to understand the complex code—just provide values for the variables below.

substitutions:
  # --- Basic Modbus Bus Configuration ---
  modbus_update_interval: "60s" # How often to query the device, e.g., every 60 seconds.
  modbus_address: "1" # The Modbus address of your device (check its manual).

  # --- Example Sensor Configuration (find the registers in your device's manual) ---
  temp_co_name: "Central Heating Temp" # Sensor name in Home Assistant
  temp_co_register: "30005" # The Modbus register number for the CH temperature

  temp_cwu_name: "Hot Water Temp"
  temp_cwu_register: "30006"

  temp_zewnetrzna_name: "Outdoor Temp"
  temp_zewnetrzna_register: "30007"

Step 3: Save and Upload

After saving the file, upload the new configuration to your boneIO device. After a successful restart, new entities with the read temperatures will automatically appear in Home Assistant, ready to be used in automations and dashboards!

Full code examples can be found in the Readme of our repository https://github.com/boneIO-eu/esphome_packages.