HomeAssistant ModbusBoard Sensor Custom Integration

The ModbusBoard Sensor integration allows you to read raw Modbus CSV data, apply scaling and offsets, and optionally perform template-based calculations and postprocessing. Configuration is done via YAML files stored in the
custom_components/modbus_board/boards/ folder.

Board and Sensor Configuration

A board configuration file defines default settings that apply to the entire board and can be inherited or overridden by individual sensors. At the board level, you can specify options such as:

• name: A descriptive name for the board.
• modbus_entity: The entity that supplies the raw Modbus CSV data.
• rounding, factor, offset, ignore_values, unit_of_measurement, icon, device_class: Default values that apply to all sensors on the board unless overridden at the sensor level.

Within the board configuration, each sensor is defined under the sensors key. Sensor configurations can override board-level defaults or add additional options as needed. The table below summarizes all available configuration options and outlines their type, default value, allowed levels (Board and/or Sensor), and the order in which they are executed during value processing.

Option	Type	Description	Default	Allowed Levels	Order of Execution
undefined_value	string/number	Value returned when a sensor reading is undefined or invalid.	STATE_UNAVAILABLE	Board, Sensor	0
calculation	string	Jinja2 template to compute the sensor’s raw value. When defined, it overrides the index setting.	None	Sensor	1
ignore_values	list	List of raw values to ignore (e.g., [0, -1]).	[]	Board, Sensor	2
factor	number	Scaling factor applied to the raw value.	1	Board, Sensor	3
offset	number	Offset added after scaling.	0	Board, Sensor	4
min_val / max_val	number	Defines the allowed range for valid sensor values.	None	Board, Sensor	5
rounding	integer	Number of decimal places to round the processed value.	2	Board, Sensor	6
condition	string	Jinja2 template that must evaluate to true for the new value to be accepted. If false, the sensor retains its previous value.	None	Sensor	7
reset	string	Reset interval flag (e.g., "hourly", "daily", "monthly") for counter mode. If defined, the counter resets when the time period changes.	None	Sensor	8
postprocess	string	Jinja2 template to further modify the sensor value after reset—commonly used to increment counters by combining the previous processed value with the current one.	None	Sensor	9
friendly_name	string	Display name for the sensor.	"Unknown Sensor"	Sensor	N/A
modbus_entity	string	Entity ID supplying raw Modbus CSV data.	Required	Board, Sensor	N/A
index	integer	Zero-based index to extract a specific value from the CSV if no calculation is defined.	None	Sensor	N/A
precision	integer	Number of decimal places for display purposes in the UI. Defaults to the value of rounding if not set.	(Same as rounding)	Board, Sensor	N/A
unit_of_measurement	string	Unit displayed in the UI.	None	Board, Sensor	N/A
icon	string	Material Design Icon identifier (mdi icons).	None	Board, Sensor	N/A
device_class	string	Home Assistant sensor device class (see HA Sensor Device Classes).	None	Board, Sensor	N/A
state_class	string	Defines how the sensor’s data is to be interpreted over time (e.g., measurement, total, or total_increasing).	STATE_CLASS_MEASUREMENT	Board, Sensor	N/A

Note: Options listed under "Allowed Levels" can be specified at the board level (applying to all sensors) or at the sensor level for individual sensor overrides. In cases where an option is allowed at both levels, the sensor-level setting takes precedence.

---

Template Variables and Stored Attributes

The integration now uses updated keys for storing and passing sensor state information. These keys are:

Stored Attribute Keys

• cur_val: Current sensor value.
• prev_val: Previous sensor value.
• cur_raw: Current raw sensor value.
• prev_raw: Previous raw sensor value.
• prev_proc: Previous processed (postprocessed) value.

Template Variable Names

When evaluating templates for calculation, condition, and postprocess, the following variables are provided:

• new_val: Candidate new sensor value.
• cur_val: Current sensor state.
• prev_val: Previous sensor state.
• cur_raw: Current raw value.
• prev_raw: Previous raw value.
• prev_proc: Previous processed value.

These variables enable you to implement custom logic—such as incrementing a counter based on a rising edge—in your Jinja2 templates.

---

Example: Counter Sensor Configuration

The following example shows how to configure counter sensors. In this example, a raw rotation count from burner_feeder_signal is used to increment a counter only on a rising edge (i.e., when the previous raw value was 0 and the current raw value is greater than 0). The postprocessing template increments the counter by adding the current processed value (cur_val) to the previous processed counter (prev_proc).

friendly_name: "Basement EBYTE-831-RTU module"
name: e831rtu_basement
sensors:
  burner_feeder_signal:
    friendly_name: "Burner Feeder Signal"
    modbus_entity: sensor.modbus_e831rtu_01_count
    index: 0
    rounding: 0
    precision: 0
    undefined_value: 0
    unit_of_measurement: rotations
    icon: mdi:rotate-right

  burner_feeder_counter_day:
    friendly_name: "Burner Feeder Counter Day"
    # Calculation retrieves the current raw rotations.
    calculation: "{{ states('sensor.burner_feeder_signal')|int(0) }}"
    # Condition: increment only on a rising edge.
    condition: "{{ (prev_raw|int(0)) == 0 and (cur_raw|int(0)) > 0 }}"
    reset: daily
    # Postprocessing: add the previous processed counter to the current calculated value.
    postprocess: "{{ prev_proc|int(0) + cur_val|int(0) }}"
    unit_of_measurement: "rotations/day"
    icon: mdi:calendar-today

  burner_feeder_counter_month:
    friendly_name: "Burner Feeder Counter Month"
    calculation: "{{ states('sensor.burner_feeder_signal')|int(0) }}"
    condition: "{{ (prev_raw|int(0)) == 0 and (cur_raw|int(0)) > 0 }}"
    reset: monthly
    postprocess: "{{ prev_proc|int(0) + cur_val|int(0) }}"
    unit_of_measurement: "rotations/month"
    icon: mdi:calendar-month

  burner_feeder_counter_till_low:
    friendly_name: "Burner Feeder Counter Till Low"
    calculation: "{{ states('sensor.burner_feeder_signal')|int(0) }}"
    condition: "{{ (prev_raw|int(0)) == 0 and (cur_raw|int(0)) > 0 }}"
    # No reset interval defined for this sensor.
    postprocess: "{{ prev_proc|int(0) + cur_val|int(0) }}"
    unit_of_measurement: rotations
    icon: mdi:fuel

---

Service: modbus_board.reset_sensor

This service resets a counter-type sensor to a specified value.

Parameter	Type	Required	Default	Description
entity_id	string	Yes	—	The sensor entity to reset.
new_value	string	No	"0"	Value to reset the counter to.

---

Reloading Configuration

To apply changes without restarting Home Assistant:

1. Navigate to Settings → Devices & Services.
2. Find the ModbusBoard integration and click Configure.
3. Use the reload option in the options flow, or call the service config_entries.reload with the entry ID.

---

Troubleshooting

• Sensor Not Updating:
  Verify that the Modbus device is online and that the modbus_entity exists in Developer Tools → States.
• Template Errors:
  Test your calculation, condition, and postprocess templates in Developer Tools → Templates.
• Ignored Values:
  Check your ignore_values list if a sensor state is unexpectedly unavailable.

CSV Values from Modbus Integration

The Modbus integration in Home Assistant allows you to read raw data from Modbus devices and process it for use in sensors. The data is returned in a CSV format, where each value corresponds to a Modbus register.

Configuration Example

- name: modbus_wp9038adam_01_dio
  slave: 10
  address: 10
  count: 2
  input_type: holding
  data_type: custom
  structure: ">2h"
  scan_interval: 60
- name: modbus_wp9038adam_01_ai
  slave: 10
  address: 0
  count: 5
  input_type: holding
  data_type: custom
  structure: ">5h"
  scan_interval: 30

Parameters

• slave: Modbus slave ID.
• address: Starting register address.
• count: Number of registers to read.
• input_type: Type of Modbus register (e.g., "holding").
• data_type: Defines the structure of the data.
• structure: Format for decoding the raw data (e.g., ">2h" for two 16-bit integers).
• scan_interval: Time interval between polling.

Data Polling and Processing

Modbus data is polled based on the scan_interval, and the raw data is returned as a CSV string. For example:

• Sensor data for modbus_wp9038adam_01_dio might return:
  12, 34

• Sensor data for modbus_wp9038adam_01_ai might return:
  25, 50, 75, 100, 125

This data is then processed with configured scaling factors, offsets, and calculations. For instance, if factor: 0.1 is set for a sensor, the raw value 25 would be converted to 2.5.

Official Home Assistant Modbus Documentation

For detailed information, refer to the Modbus Integration documentation.