From 6ad804fbc57c2505bf684836e83e9006eab0aacd Mon Sep 17 00:00:00 2001
From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com>
Date: Tue, 28 Jul 2026 21:35:07 -0500
Subject: [PATCH] [sgp4x] Rename voc/nox sensor keys to voc_index/nox_index
 (#17723)

---
 esphome/components/const/__init__.py |  2 ++
 esphome/components/sgp4x/sensor.py   | 27 +++++++++++++++------------
 tests/components/sgp4x/common.yaml   |  6 +++---
 3 files changed, 20 insertions(+), 15 deletions(-)

diff --git a/esphome/components/const/__init__.py b/esphome/components/const/__init__.py
index 7e46e81c69..7476385563 100644
--- a/esphome/components/const/__init__.py
+++ b/esphome/components/const/__init__.py
@@ -24,6 +24,7 @@ CONF_IAQ = "iaq"
 CONF_IGNORE_NOT_FOUND = "ignore_not_found"
 CONF_LIBRETINY = "libretiny"
 CONF_LOOP = "loop"
+CONF_NOX_INDEX = "nox_index"
 CONF_ON_PACKET = "on_packet"
 CONF_ON_RECEIVE = "on_receive"
 CONF_ON_STATE_CHANGE = "on_state_change"
@@ -36,6 +37,7 @@ CONF_SHA256 = "sha256"
 CONF_STATE_SAVE_INTERVAL = "state_save_interval"
 CONF_STOP_BITS = "stop_bits"
 CONF_USE_PSRAM = "use_psram"
+CONF_VOC_INDEX = "voc_index"
 CONF_VOLUME_INCREMENT = "volume_increment"
 CONF_VOLUME_INITIAL = "volume_initial"
 CONF_VOLUME_MAX = "volume_max"
diff --git a/esphome/components/sgp4x/sensor.py b/esphome/components/sgp4x/sensor.py
index d407f20a4e..87ef050bc1 100644
--- a/esphome/components/sgp4x/sensor.py
+++ b/esphome/components/sgp4x/sensor.py
@@ -1,5 +1,6 @@
 import esphome.codegen as cg
 from esphome.components import i2c, sensirion_common, sensor
+from esphome.components.const import CONF_NOX_INDEX, CONF_VOC_INDEX
 import esphome.config_validation as cv
 from esphome.const import (
     CONF_ALGORITHM_TUNING,
@@ -35,9 +36,9 @@ CONF_HUMIDITY_SOURCE = "humidity_source"
 
 
 def validate_sensors(config):
-    if CONF_VOC not in config and CONF_NOX not in config:
+    if CONF_VOC_INDEX not in config and CONF_NOX_INDEX not in config:
         raise cv.Invalid(
-            f"At least one sensor is required. Define {CONF_VOC} and/or {CONF_NOX}"
+            f"At least one sensor is required. Define {CONF_VOC_INDEX} and/or {CONF_NOX_INDEX}"
         )
     return config
 
@@ -65,15 +66,17 @@ VOC_SENSOR = _gas_sensor_schema(100)
 NOX_SENSOR = _gas_sensor_schema(1)
 
 CONFIG_SCHEMA = cv.All(
+    cv.rename_key(CONF_VOC, CONF_VOC_INDEX, removed_in="2027.2.0", component="sgp4x"),
+    cv.rename_key(CONF_NOX, CONF_NOX_INDEX, removed_in="2027.2.0", component="sgp4x"),
     cv.Schema(
         {
             cv.GenerateID(): cv.declare_id(SGP4xComponent),
-            cv.Optional(CONF_VOC): sensor.sensor_schema(
+            cv.Optional(CONF_VOC_INDEX): sensor.sensor_schema(
                 icon=ICON_RADIATOR,
                 accuracy_decimals=0,
                 state_class=STATE_CLASS_MEASUREMENT,
             ).extend(VOC_SENSOR),
-            cv.Optional(CONF_NOX): sensor.sensor_schema(
+            cv.Optional(CONF_NOX_INDEX): sensor.sensor_schema(
                 icon=ICON_RADIATOR,
                 accuracy_decimals=0,
                 state_class=STATE_CLASS_MEASUREMENT,
@@ -107,11 +110,11 @@ async def to_code(config):
 
     cg.add(var.set_store_baseline(config[CONF_STORE_BASELINE]))
 
-    if CONF_VOC in config:
-        sens = await sensor.new_sensor(config[CONF_VOC])
+    if CONF_VOC_INDEX in config:
+        sens = await sensor.new_sensor(config[CONF_VOC_INDEX])
         cg.add(var.set_voc_sensor(sens))
-        if CONF_ALGORITHM_TUNING in config[CONF_VOC]:
-            cfg = config[CONF_VOC][CONF_ALGORITHM_TUNING]
+        if CONF_ALGORITHM_TUNING in config[CONF_VOC_INDEX]:
+            cfg = config[CONF_VOC_INDEX][CONF_ALGORITHM_TUNING]
             cg.add(
                 var.set_voc_algorithm_tuning(
                     cfg[CONF_INDEX_OFFSET],
@@ -123,11 +126,11 @@ async def to_code(config):
                 )
             )
 
-    if CONF_NOX in config:
-        sens = await sensor.new_sensor(config[CONF_NOX])
+    if CONF_NOX_INDEX in config:
+        sens = await sensor.new_sensor(config[CONF_NOX_INDEX])
         cg.add(var.set_nox_sensor(sens))
-        if CONF_ALGORITHM_TUNING in config[CONF_NOX]:
-            cfg = config[CONF_NOX][CONF_ALGORITHM_TUNING]
+        if CONF_ALGORITHM_TUNING in config[CONF_NOX_INDEX]:
+            cfg = config[CONF_NOX_INDEX][CONF_ALGORITHM_TUNING]
             cg.add(
                 var.set_nox_algorithm_tuning(
                     cfg[CONF_INDEX_OFFSET],
diff --git a/tests/components/sgp4x/common.yaml b/tests/components/sgp4x/common.yaml
index 4edda8fd1b..88b8166876 100644
--- a/tests/components/sgp4x/common.yaml
+++ b/tests/components/sgp4x/common.yaml
@@ -1,7 +1,7 @@
 sensor:
   - platform: sgp4x
     i2c_id: i2c_bus
-    voc:
+    voc_index:
       name: VOC Index
       id: sgp40_voc_index
       algorithm_tuning:
@@ -11,8 +11,8 @@ sensor:
         gating_max_duration_minutes: 180
         std_initial: 50
         gain_factor: 230
-    nox:
-      name: NOx
+    nox_index:
+      name: NOx Index
       algorithm_tuning:
         index_offset: 100
         learning_time_offset_hours: 12