esphome / esphome/feature-requests

Substitutions per package

Open
#1,928 2 comments 0 reactions 0 assignees View on GitHub
Project: ESPHome
Dominant language
No language data
Stars
450
Forks
29
PR merge metrics
No merged PRs in 30d

Description

**Describe the problem you have/What new integration you would like**

The idea I have is making it possible to optionally pass substitutions to individual packages like this:

```
packages:
config: !include device-config.yaml
substitutions:
my_config_param1: my config value 1
my_config_param2: my config value 2
control: !include device-control-entities.yaml
diagnostics: !include device-diagnostics-entities.yaml
```

**Please describe your use case for this integration and alternatives you've tried:**

I made use of packages for my use case, which is a gas/water/electricity meter based on pulse counting. I extracted the whole metering logic to a separate package to be able to reuse it for different meters. Also, I used substitutions to be able to specify parameters like name, friendly name, pulse per unit, unit, icon etc.

Now I would like to create a multi-purpose device, where metering will be only one of its features. But since substitutions are global, I will have to use prefixes to distinguish those parameters that are specific to the metering logic, not to confuse them with those that will be used for other features. But then the prefix will seem like a redundant piece of text from the point of view of the single-purpose devices, where the metering package represents the only purpose the devices are used for.

So this

```yaml
substitutions:
# general parameters
name: gas-meter
friendly_name: "Gas meter"

# meter-specific parameters
device_class: gas
unit_of_measurement: "m³"
accuracy_decimals: "2"
pulses_per_unit: "100"
max_pulse_interval_s: "60"
medium_icon: "mdi:counter"

log_level: INFO
```

would have to be transformed to this to be clear in terms what context it is used in

```yaml
substitutions:
# general parameters
name: my-multifunctional-device
friendly_name: "My multifunctional device"

# meter-specific parameters
meter_device_class: gas
meter_unit_of_measurement: "m³"
meter_accuracy_decimals: "2"
meter_pulses_per_unit: "100"
meter_max_pulse_interval_s: "60"
meter_medium_icon: "mdi:counter"

log_level: INFO
```

But I would rather want to have it configured like this (or so):

```
packages:
config: !include device-config.yaml
control: !include device-control-entities.yaml
diagnostics: !include device-diagnostics-entities.yaml
meter: !include custom-pulse-meter.yaml
substitutions:
device_class: gas
unit_of_measurement: "m³"
accuracy_decimals: "2"
pulses_per_unit: "100"
max_pulse_interval_s: "60"
medium_icon: "mdi:counter"
```

**Additional context**

Contributor guide

No contributing guide indexed for this repository

Research direction

No files, tests, or entry points are named. Start by locating the package/include processing and substitution handling described in the YAML examples, then determine how package-local values should interact with global substitutions. Done means individual packages can receive substitutions without requiring prefixed global names, while existing package configuration continues to work.

Written by the indexing model from the issue text.

Assessment

Tech stack
yaml
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.