SCD4x ambient pressure compensation unit confusion #19751

The problem

The SCD4x component's ambient_pressure_compensation value is defined and documented with different units of pressure.

• The documentation states that the units are mbar.
• The Python config validation uses cv.pressure whose default units are bar.
• The C++ implementation does not perform any scaling on the received value so it assumes they are in mbar as specified in the scd4x datasheet.

Unlike SCD30's unit confusion (esphome/esphome.io#7449), this confusion is not just a documentation error. If the SCD4x configuration specifies a value with units then the metric prefix scaling will apply during validation and an unexpected value will be provided to the component during initialization.

• Given ambient_pressure_compensation: 1013
  • Docs imply this is 1013 mbar
  • Python config validation defaults units are bar so technically this is 1013 bar, oops
  • C++ implementation receives the value 1013 and wants mbar, ok
  • The mistakes cancel out so everything works out at runtime
• Given ambient_pressure_compensation: 1013 mbar
  • Python config validation sees m prefix on bar so divides by 1000 to get 1.013 bar
  • C++ implementation receives the value 1.013 and wants mbar, oops
  • The wrong value will be applied at runtime

Fixing this unit confusion may require a breaking change. Perhaps something like:

• Change the docs to indicate that the units are in bar (part of the same fix as for SCD30).
• Add a cv.float_range(0.4, 1.1) check to catch the case where a large unitless value that was assumed to be mbar was provided. The fix for this breakage is to simply add the mbar unit to the configuration.
• Change to_code to multiply the configured value by 1000 to yield a pressure in mbar (aka. hpa) as required by the C++ code.

Which version of ESPHome has the issue?

2026.10.0-dev

What type of installation are you using?

Home Assistant Add-on

What platform are you using?

ESP8266

Component causing the issue

scd4x

YAML Config

sensor:
  platform: scd4x
  ambient_pressure_compensation: 1013 mbar  # actually interpreted as 1.013 bar
  # etc...

Anything in the logs that might be useful for us?

Additional information

No response