From 1f47797007419e10046513b7eb49d18fa200d1e2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20=C4=8Cerm=C3=A1k?= <jakub@jcermak.cz>
Date: Sat, 29 Nov 2025 23:26:25 +0100
Subject: [PATCH] Add MEASUREMENT_ANGLE to SensorStateClass  (#12085)

---
 esphome/components/api/api.proto        | 1 +
 esphome/components/api/api_pb2.h        | 1 +
 esphome/components/api/api_pb2_dump.cpp | 2 ++
 esphome/components/sensor/__init__.py   | 1 +
 esphome/components/sensor/sensor.cpp    | 2 ++
 esphome/components/sensor/sensor.h      | 1 +
 esphome/const.py                        | 3 +++
 tests/components/sensor/common.yaml     | 7 +++++++
 8 files changed, 18 insertions(+)

diff --git a/esphome/components/api/api.proto b/esphome/components/api/api.proto
index 74a8e8ff7..5450c2536 100644
--- a/esphome/components/api/api.proto
+++ b/esphome/components/api/api.proto
@@ -589,6 +589,7 @@ enum SensorStateClass {
   STATE_CLASS_MEASUREMENT = 1;
   STATE_CLASS_TOTAL_INCREASING = 2;
   STATE_CLASS_TOTAL = 3;
+  STATE_CLASS_MEASUREMENT_ANGLE = 4;
 }
 
 // Deprecated in API version 1.5
diff --git a/esphome/components/api/api_pb2.h b/esphome/components/api/api_pb2.h
index 93ece74d8..74d3834bf 100644
--- a/esphome/components/api/api_pb2.h
+++ b/esphome/components/api/api_pb2.h
@@ -51,6 +51,7 @@ enum SensorStateClass : uint32_t {
   STATE_CLASS_MEASUREMENT = 1,
   STATE_CLASS_TOTAL_INCREASING = 2,
   STATE_CLASS_TOTAL = 3,
+  STATE_CLASS_MEASUREMENT_ANGLE = 4,
 };
 #endif
 enum LogLevel : uint32_t {
diff --git a/esphome/components/api/api_pb2_dump.cpp b/esphome/components/api/api_pb2_dump.cpp
index a985e052a..bea7fc53c 100644
--- a/esphome/components/api/api_pb2_dump.cpp
+++ b/esphome/components/api/api_pb2_dump.cpp
@@ -179,6 +179,8 @@ template<> const char *proto_enum_to_string<enums::SensorStateClass>(enums::Sens
       return "STATE_CLASS_TOTAL_INCREASING";
     case enums::STATE_CLASS_TOTAL:
       return "STATE_CLASS_TOTAL";
+    case enums::STATE_CLASS_MEASUREMENT_ANGLE:
+      return "STATE_CLASS_MEASUREMENT_ANGLE";
     default:
       return "UNKNOWN";
   }
diff --git a/esphome/components/sensor/__init__.py b/esphome/components/sensor/__init__.py
index f83226d10..027d9a69b 100644
--- a/esphome/components/sensor/__init__.py
+++ b/esphome/components/sensor/__init__.py
@@ -182,6 +182,7 @@ STATE_CLASSES = {
     "measurement": StateClasses.STATE_CLASS_MEASUREMENT,
     "total_increasing": StateClasses.STATE_CLASS_TOTAL_INCREASING,
     "total": StateClasses.STATE_CLASS_TOTAL,
+    "measurement_angle": StateClasses.STATE_CLASS_MEASUREMENT_ANGLE,
 }
 validate_state_class = cv.enum(STATE_CLASSES, lower=True, space="_")
 
diff --git a/esphome/components/sensor/sensor.cpp b/esphome/components/sensor/sensor.cpp
index df6bd644e..49dc56eda 100644
--- a/esphome/components/sensor/sensor.cpp
+++ b/esphome/components/sensor/sensor.cpp
@@ -44,6 +44,8 @@ const LogString *state_class_to_string(StateClass state_class) {
       return LOG_STR("total_increasing");
     case STATE_CLASS_TOTAL:
       return LOG_STR("total");
+    case STATE_CLASS_MEASUREMENT_ANGLE:
+      return LOG_STR("measurement_angle");
     case STATE_CLASS_NONE:
     default:
       return LOG_STR("");
diff --git a/esphome/components/sensor/sensor.h b/esphome/components/sensor/sensor.h
index a4210e5e6..5d387a1ad 100644
--- a/esphome/components/sensor/sensor.h
+++ b/esphome/components/sensor/sensor.h
@@ -31,6 +31,7 @@ enum StateClass : uint8_t {
   STATE_CLASS_MEASUREMENT = 1,
   STATE_CLASS_TOTAL_INCREASING = 2,
   STATE_CLASS_TOTAL = 3,
+  STATE_CLASS_MEASUREMENT_ANGLE = 4
 };
 
 const LogString *state_class_to_string(StateClass state_class);
diff --git a/esphome/const.py b/esphome/const.py
index 2b6b60d39..59bf0e8b8 100644
--- a/esphome/const.py
+++ b/esphome/const.py
@@ -1346,6 +1346,9 @@ STATE_CLASS_NONE = ""
 # The state represents a measurement in present time
 STATE_CLASS_MEASUREMENT = "measurement"
 
+# The state represents a measurement in present time for angles measured in degrees (°)
+STATE_CLASS_MEASUREMENT_ANGLE = "measurement_angle"
+
 # The state represents a total that only increases, a decrease is considered a reset.
 STATE_CLASS_TOTAL_INCREASING = "total_increasing"
 
diff --git a/tests/components/sensor/common.yaml b/tests/components/sensor/common.yaml
index 2180f66da..1961c9868 100644
--- a/tests/components/sensor/common.yaml
+++ b/tests/components/sensor/common.yaml
@@ -236,3 +236,10 @@ sensor:
           - multiply: 2.0
           - offset: 10.0
           - lambda: return x * 3.0;
+
+  # Testing measurement_angle state class
+  - platform: template
+    name: "Angle Sensor"
+    lambda: return 42.0;
+    update_interval: 1s
+    state_class: "measurement_angle"