feat: calculate user age from date of birth

- Store optional date_of_birth in user profiles; derive the current age
  with a birthday-aware calculation (no more annual age updates).
- Handshake and body-composition math receive the derived age using the
  HA-local date; derived sensors refresh once per HA-local day.
- Safe migration: legacy age-only profiles keep working unchanged; no DOB
  is fabricated. Entering a DOB makes it the source of truth.
- Options/Config flow: replace the Age field with Date of birth plus
  validation (invalid/future dates rejected with clear UI errors).
- New DOB tests (age math, leap days, validation, migration, handshake
  age byte, multi-user independence). 104 tests total.

Author: kapilmahawar

CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.3] - 2026-09-09
+
+### Added
+- **Date-of-birth based user profiles**: the user profile stores an optional
+  `date_of_birth` instead of collecting an age; the current age is derived
+  from it with a birthday-aware calculation, so it never needs a manual
+  yearly update. The handshake and body-composition math receive the
+  derived age (HA-local date, no UTC off-by-one around birthdays), and
+  derived sensors refresh once per HA-local day.
+- **Safe migration for existing profiles**: profiles created before DOB
+  support keep their stored age and load unchanged; no DOB is ever
+  fabricated. Enter a date of birth once through Options → Edit user and it
+  becomes the source of truth (the age key is dropped on save). A blank DOB
+  stays allowed for legacy profiles while they keep using their stored age.
+- DOB input validation: invalid dates and future dates are rejected with
+  clear UI errors (`YYYY-MM-DD`, year 1900+).
+- Unit tests: birthday-aware age math (including leap days), DOB
+  validation, legacy profile loading, serialization round-trips, handshake
+  age byte and multi-user independence (`tests/test_dob.py`).
+
+### Changed
+- Options/Config flow user forms: "Age" replaced by "Date of birth" with an
+  explanatory note ("your age is calculated automatically from this date").
+  No stable ids, device/entity relationships, Person links, measurement
+  history or deletion behavior changed.
+
 ## [0.8.2] - 2026-09-09
 
 ### Changed (repository presentation only - no functionality changes)
@@ -350,7 +376,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `realme_scale_measurement` HA event and `realme_scale.reconnect` service.
 - Unit tests + hardware-free protocol smoke test (`tests/`).
 
-[Unreleased]: https://github.com/kapilmahawar/realme-scale-ha/compare/v0.8.2...HEAD
+[Unreleased]: https://github.com/kapilmahawar/realme-scale-ha/compare/v0.8.3...HEAD
+[0.8.3]: https://github.com/kapilmahawar/realme-scale-ha/compare/v0.8.2...v0.8.3
 [0.8.2]: https://github.com/kapilmahawar/realme-scale-ha/compare/v0.8.1...v0.8.2
 [0.8.1]: https://github.com/kapilmahawar/realme-scale-ha/compare/v0.8.0...v0.8.1
 [0.8.0]: https://github.com/kapilmahawar/realme-scale-ha/compare/v0.7.0...v0.8.0

README.md

@@ -41,6 +41,8 @@ all without cloud services.
 - Optional linking of users to existing Home Assistant **People**
 - Ambiguous or unrecognized readings stay **unassigned** — nothing is
   silently guessed
+- **Date of birth based profiles**: the current age is derived from the
+  stored date of birth, so age never needs a manual yearly update
 
 ### Body composition
 
@@ -129,9 +131,11 @@ https://github.com/kapilmahawar/realme-scale-ha
 
 1. Add the integration and pick the discovered scale, or enter its Bluetooth
    address (`AA:BB:CC:DD:EE:FF`).
-2. Create the **first user** — a profile with sex, age, height and activity
-   level, plus an optional expected weight and identification tolerances.
-   You may link it to an existing Home Assistant **Person**.
+2. Create the **first user** — a profile with sex, date of birth, height and
+   activity level, plus an optional expected weight and identification
+   tolerances. You may link it to an existing Home Assistant **Person**.
+   Your age is calculated automatically from your date of birth, so you do
+   not need to update it every year.
 3. Add further users later under
    **Settings → Devices & services → Realme Smart Scale → Configure**.
 
@@ -140,11 +144,17 @@ People, remove users, set the handshake profile, adjust automatic
 identification defaults, assign or reassign measurements, and **Save &
 Close** to apply everything.
 
+**Existing users:** profiles created before date-of-birth support keep using
+their stored age until you enter a date of birth once under
+*Options → Edit user*. The profile keeps working normally in the meantime
+— nothing is guessed or overwritten.
+
 > Three different roles should not be confused:
 >
 > - a **configured user** is a profile you created;
-> - the **handshake profile** is the profile whose sex/age/height is written
->   into the scale during the Bluetooth handshake;
+> - the **handshake profile** is the profile whose sex/date of birth/height
+>   is written into the scale during the Bluetooth handshake (age is
+>   calculated from the date of birth);
 > - the **attributed user** is who automatic identification decides was on
 >   the scale for a given measurement.
 >

custom_components/realme_scale/config_flow.py

@@ -3,9 +3,10 @@
 The scale is discovered through Home Assistant's Bluetooth integration
 (local adapter or proxy that relays advertisements).  Because the RMH2011
 only streams data to an *active* GATT client, the flow additionally asks for
-the first user profile (sex / age / height / activity level / initial
-weight) that is written into the handshake and used for the local BIA
-calculation.
+the first user profile (sex / date of birth / height / activity level /
+initial weight) that is written into the handshake and used for the local
+BIA calculation.  The user's age is derived from their date of birth, so it
+never needs a manual yearly update.
 
 The options flow is a menu for managing **multiple users** after install:
 add / edit / remove users, pick the active (handshake) user, tune the
@@ -16,6 +17,7 @@
 from __future__ import annotations
 
 import re
+from datetime import date, datetime, timezone
 from typing import Any
 from uuid import uuid4
 
@@ -32,12 +34,13 @@
 )
 from homeassistant.const import CONF_ADDRESS, CONF_NAME
 from homeassistant.core import HomeAssistant, callback
+from homeassistant.util import dt as dt_util
 
 from .const import (
     ACTIVITY_LEVELS,
     CONF_ACTIVITY_LEVEL,
-    CONF_AGE,
     CONF_AUTO_ASSIGN_KG,
+    CONF_DATE_OF_BIRTH,
     CONF_EXPECTED_WEIGHT,
     CONF_HEIGHT,
     CONF_IMPEDANCE_TOL_OHM,
@@ -61,6 +64,8 @@
 from .scale_controller import (
     ScaleUser,
     build_user_options,
+    dob_error,
+    parse_dob,
     parse_user_options,
 )
 
@@ -109,6 +114,14 @@ def person_choices(hass: HomeAssistant) -> dict[str, str]:
     return choices
 
 
+def _local_date(hass: HomeAssistant) -> date:
+    """Today's date in the HA-configured time zone (flow validation)."""
+    tz = dt_util.get_time_zone(hass.config.time_zone)
+    if tz is None:  # pragma: no cover - HA always sets a time zone
+        tz = timezone.utc
+    return datetime.now(tz=tz).date()
+
+
 def profile_schema(
     data: dict[str, Any] | None = None,
     persons: dict[str, str] | None = None,
@@ -117,6 +130,11 @@ def profile_schema(
 
     ``persons`` adds an optional dropdown linking the profile to an existing
     Home Assistant person entity (the profile name auto-fills from it).
+
+    The user's age is *not* collected: ``date_of_birth`` is stored and the
+    current age is derived from it.  New-user steps enforce the DOB being
+    present in code (like the other fields); editing a legacy profile may
+    leave it blank so its stored age keeps being used until a DOB is given.
     """
     data = data or {}
     schema: dict[vol.Marker, Any] = {
@@ -128,10 +146,10 @@ def profile_schema(
             CONF_SEX,
             default=data.get(CONF_SEX, SEX_MALE),
         ): vol.In(_sex_options()),
-        vol.Required(
-            CONF_AGE,
-            default=data.get(CONF_AGE, 30),
-        ): vol.All(vol.Coerce(int), vol.Range(min=1, max=120)),
+        vol.Optional(
+            CONF_DATE_OF_BIRTH,
+            default=data.get(CONF_DATE_OF_BIRTH, ""),
+        ): str,
         vol.Required(
             CONF_HEIGHT,
             default=data.get(CONF_HEIGHT, 175.0),
@@ -185,22 +203,31 @@ def _profile_from_input(
     user_input: dict[str, Any],
     user_id: str,
     persons: dict[str, str] | None = None,
+    *,
+    legacy_age: int = 30,
 ) -> ScaleUser:
     """Build a ScaleUser from validated form input.
 
     When no name was typed but a person was picked, the profile name is
     taken from that person so setup can be a single dropdown + confirm.
+
+    The form collects ``date_of_birth``; the age is derived from it at run
+    time.  A blank DOB (legacy profile being edited without one yet) keeps
+    the profile's stored age via ``legacy_age``.
     """
     name = str(user_input.get(CONF_USER_NAME, "")).strip()
     person = str(user_input.get(CONF_PERSON_ENTITY, ""))
     if not name and person and persons:
         name = str(persons.get(person, "")).strip()
+    dob_raw = str(user_input.get(CONF_DATE_OF_BIRTH, "") or "").strip()
+    dob = parse_dob(dob_raw)
     return ScaleUser(
         user_id=user_id,
         name=name,
         person_entity_id=person,
         sex=str(user_input[CONF_SEX]),
-        age=int(user_input[CONF_AGE]),
+        age=legacy_age if dob is None else 30,
+        date_of_birth=dob.isoformat() if dob is not None else "",
         height_cm=float(user_input[CONF_HEIGHT]),
         activity_level=str(user_input[CONF_ACTIVITY_LEVEL]),
         initial_weight=float(user_input.get(CONF_INITIAL_WEIGHT, 0.0)),
@@ -217,7 +244,7 @@ def _profile_prefill(user: ScaleUser) -> dict[str, Any]:
     return {
         CONF_USER_NAME: user.name,
         CONF_SEX: user.sex,
-        CONF_AGE: user.age,
+        CONF_DATE_OF_BIRTH: user.date_of_birth,
         CONF_HEIGHT: user.height_cm,
         CONF_ACTIVITY_LEVEL: user.activity_level,
         CONF_INITIAL_WEIGHT: user.initial_weight,
@@ -380,19 +407,26 @@ async def async_step_profile(
 
         Offers a dropdown of existing HA People: picking one auto-fills the
         profile name; the profile numbers still need confirming once
-        (they drive the handshake and body-composition math).
+        (they drive the handshake and body-composition math).  Age is
+        derived from the date of birth, which is required for a new user.
         """
         errors: dict[str, str] = {}
         persons = person_choices(self.hass)
         if user_input is not None:
-            user = _profile_from_input(user_input, _new_user_id(), persons)
-            return self.async_create_entry(
-                title=f"{self._name} ({self._address})",
-                data={CONF_ADDRESS: self._address, CONF_NAME: self._name},
-                options=build_user_options(
-                    [user], user.user_id, DEFAULT_AUTO_ASSIGN_KG
-                ),
+            dob_err = dob_error(
+                user_input.get(CONF_DATE_OF_BIRTH), on=_local_date(self.hass)
             )
+            if dob_err is not None:
+                errors[CONF_DATE_OF_BIRTH] = dob_err
+            else:
+                user = _profile_from_input(user_input, _new_user_id(), persons)
+                return self.async_create_entry(
+                    title=f"{self._name} ({self._address})",
+                    data={CONF_ADDRESS: self._address, CONF_NAME: self._name},
+                    options=build_user_options(
+                        [user], user.user_id, DEFAULT_AUTO_ASSIGN_KG
+                    ),
+                )
 
         return self.async_show_form(
             step_id="profile",
@@ -526,15 +560,24 @@ async def async_step_menu(
     async def async_step_add_user(
         self, user_input: dict[str, Any] | None = None
     ) -> ConfigFlowResult:
-        """Collect a new user profile (optionally linked to an HA person)."""
+        """Collect a new user profile (optionally linked to an HA person).
+
+        A new user must provide a date of birth: age is derived from it, so
+        there is no age input to fall back to.
+        """
         errors: dict[str, str] = {}
         persons = person_choices(self.hass)
         if user_input is not None:
             name_blank = not str(user_input.get(CONF_USER_NAME, "")).strip()
             person = str(user_input.get(CONF_PERSON_ENTITY, ""))
             if name_blank and not person:
                 errors[CONF_USER_NAME] = "name_required"
-            else:
+            dob_err = dob_error(
+                user_input.get(CONF_DATE_OF_BIRTH), on=_local_date(self.hass)
+            )
+            if dob_err is not None:
+                errors[CONF_DATE_OF_BIRTH] = dob_err
+            if not errors:
                 user = _profile_from_input(user_input, _new_user_id(), persons)
                 self._users_or_default().append(user)
                 return await self.async_step_init()
@@ -566,7 +609,12 @@ async def async_step_edit_user(
     async def async_step_edit_user_form(
         self, user_input: dict[str, Any] | None = None
     ) -> ConfigFlowResult:
-        """Edit one user's profile (person link optional)."""
+        """Edit one user's profile (person link optional).
+
+        A legacy profile without a date of birth may keep using its stored
+        age by leaving the DOB blank.  Once a DOB is set it becomes the
+        source of truth, so it cannot be silently cleared back to nothing.
+        """
         users = self._users_or_default()
         target_id = self._edit_user_id
         target = next((u for u in users if u.user_id == target_id), None)
@@ -580,8 +628,18 @@ async def async_step_edit_user_form(
             person = str(user_input.get(CONF_PERSON_ENTITY, ""))
             if name_blank and not person:
                 errors[CONF_USER_NAME] = "name_required"
-            else:
-                updated = _profile_from_input(user_input, target_id, persons)
+            raw_dob = str(user_input.get(CONF_DATE_OF_BIRTH, "") or "").strip()
+            if raw_dob or target.date_of_birth:
+                # Entering a new DOB, or keeping/editing an existing one:
+                # it must be a valid, non-future date.
+                dob_err = dob_error(raw_dob, on=_local_date(self.hass))
+                if dob_err is not None:
+                    errors[CONF_DATE_OF_BIRTH] = dob_err
+            # blank DOB on a legacy profile -> keep its stored age.
+            if not errors:
+                updated = _profile_from_input(
+                    user_input, target_id, persons, legacy_age=target.age
+                )
                 users[users.index(target)] = updated
                 return await self.async_step_init()
 

custom_components/realme_scale/const.py

@@ -52,7 +52,11 @@
 CONF_USER_NAME: Final = "user_name"
 CONF_PERSON_ENTITY: Final = "person_entity_id"  # optional HA person.* link
 CONF_SEX: Final = "sex"            # "male" | "female"
-CONF_AGE: Final = "age"            # years (int)
+CONF_AGE: Final = "age"            # legacy years (int); kept for migration
+# Date of birth, ISO "YYYY-MM-DD". Empty/absent = not configured yet; the
+# current age is derived from it (CONF_AGE remains the fallback for legacy
+# profiles that predate date-of-birth support).
+CONF_DATE_OF_BIRTH: Final = "date_of_birth"
 CONF_HEIGHT: Final = "height"      # cm (float)
 CONF_ACTIVITY_LEVEL: Final = "activity_level"  # openScale ActivityLevel name
 CONF_INITIAL_WEIGHT: Final = "initial_weight"  # kg (float); 0 -> 0xFFFF sentinel