refactor: add binary sensor device class

- Add binary sensor device class enum variant
- Add CommonStates enum for common entity states

Author: zehnm

ucapi/entity.py

@@ -31,6 +31,16 @@ class EntityTypes(str, Enum):
     VOICE_ASSISTANT = "voice_assistant"
 
 
+class CommonStates(str, Enum):
+    """Common entity states available in all entities."""
+
+    UNAVAILABLE = "UNAVAILABLE"
+    """The entity is currently not available.
+    The UI will render the entity as inactive until the entity becomes active again."""
+    UNKNOWN = "UNKNOWN"
+    """The entity is available but the current state is unknown."""
+
+
 class Entity:
     """
     Entity base class.

ucapi/sensor.py

@@ -15,8 +15,12 @@ class States(str, Enum):
     """Sensor entity states."""
 
     UNAVAILABLE = "UNAVAILABLE"
+    """The sensor is currently not available.
+    The UI will render the sensor as inactive until the sensor becomes active again."""
     UNKNOWN = "UNKNOWN"
+    """The sensor is available but the current state is unknown."""
     ON = "ON"
+    """The sensor is available and providing measurements."""
 
 
 class Features(str, Enum):
@@ -27,42 +31,73 @@ class Attributes(str, Enum):
     """Sensor entity attributes."""
 
     STATE = "state"
+    """Optional state of the sensor."""
     VALUE = "value"
+    """The native measurement value of the sensor."""
     UNIT = "unit"
+    """Optional unit of the ``value`` if no default unit is set."""
 
 
 class Commands(str, Enum):
     """Sensor entity commands."""
 
 
 class DeviceClasses(str, Enum):
-    """Sensor entity device classes."""
+    """Sensor entity device classes.
+
+    See https://unfoldedcircle.github.io/core-api/entities/entity_sensor.html
+    for more information about binary sensors.
+    """
 
     CUSTOM = "custom"
+    """Generic sensor with custom unit"""
     BATTERY = "battery"
+    """Battery charge in %"""
     CURRENT = "current"
+    """Electrical current in ampere"""
     ENERGY = "energy"
+    """Energy in kilowatt-hour"""
     HUMIDITY = "humidity"
+    """Humidity in %"""
     POWER = "power"
+    """Power in watt or kilowatt"""
     TEMPERATURE = "temperature"
     VOLTAGE = "voltage"
+    """Voltage in volt"""
+    BINARY = "binary"
+    """Binary sensor.
+     The binary specific device class is stored in the ``unit`` attribute."""
 
 
 class Options(str, Enum):
     """Sensor entity options."""
 
     CUSTOM_UNIT = "custom_unit"
+    """Unit label for a custom sensor if device_class is not specified or to override
+     a default unit."""
     NATIVE_UNIT = "native_unit"
+    """The sensor's native unit of measurement to perform automatic conversion.
+     Applicable to device classes: ``temperature``."""
     DECIMALS = "decimals"
+    """Number of decimal places to show in the UI if the sensor provides the measurement
+     as a number. Not applicable to string values."""
     MIN_VALUE = "min_value"
+    """Not yet supported.
+
+    Optional minimum value of the sensor output. This can be used in the UI for graphs
+    or gauges."""
     MAX_VALUE = "max_value"
+    """Not yet supported.
+
+    Optional maximum value of the sensor output. This can be used in the UI for graphs
+    or gauges."""
 
 
 class Sensor(Entity):
     """
     Sensor entity class.
 
-    See https://github.com/unfoldedcircle/core-api/blob/main/doc/entities/entity_sensor.md
+    See https://unfoldedcircle.github.io/core-api/entities/entity_sensor.html
     for more information.
     """
 
@@ -78,7 +113,7 @@ def __init__(
         area: str | None = None,
     ):
         """
-        Create sensor-entity instance.
+        Create a sensor-entity instance.
 
         :param identifier: entity identifier
         :param name: friendly name