Merge pull request #16 from ronnnnnnnnnnnnn/multi-user

Multi user support

Author: ronnnnnnnnnnnnn

.github/workflows/hassfest.yaml

@@ -2,8 +2,7 @@ name: Validate with Hassfest
 
 on:
   push:
-    branches:
-      - main
+    branches: ["*"]
 
   pull_request:
     branches: ["*"]

.github/workflows/lint.yaml

@@ -2,11 +2,9 @@ name: "Lint"
 
 on:
   push:
-    branches:
-      - "main"
+    branches: ["*"]
   pull_request:
-    branches:
-      - "main"
+    branches: ["*"]
 
 jobs:
   ruff:

.github/workflows/validate.yaml

@@ -2,8 +2,7 @@ name: Validate with Hacs
 
 on:
   push:
-    branches:
-      - main
+    branches: ["*"]
 
   pull_request:
     branches: ["*"]

README.md

@@ -7,6 +7,10 @@ This custom integration allows you to connect your Etekcity Bluetooth Low Energy
 ## Features
 
 - Automatic discovery of Etekcity BLE fitness scales
+- Intelligent multi-user support:
+    - Automatically detects which person is using the scale based on their weight history.
+    - Uses an adaptive tolerance system that adjusts to each user's weight fluctuations over time.
+    - Supports linking users to Home Assistant Person entities to exclude users who are `not_home`.
 - Real-time weight and impedance measurements
 - Optional body composition metrics calculation including:
     - Body Mass Index (BMI)
@@ -47,6 +51,8 @@ This custom integration allows you to connect your Etekcity Bluetooth Low Energy
 
 ## Configuration
 
+### Initial Setup
+
 1. In Home Assistant, go to "Configuration" > "Integrations".
 2. Click the "+" button to add a new integration.
 3. Search for "Etekcity Fitness Scale BLE" and select it.
@@ -58,6 +64,102 @@ This custom integration allows you to connect your Etekcity Bluetooth Low Energy
         - Enter your date of birth
         - Enter your height
 
+### User Profile Configuration Options
+
+When adding or editing user profiles (**Settings > Devices & Services > Etekcity Fitness Scale BLE > Configure**), you can configure the following options:
+
+- **User Name:** Display name for the user profile.
+
+- **Person Entity (optional):** Link this user profile to a Home Assistant person entity. When linked, the integration uses the person's location state to improve automatic assignment:
+  - If the person is marked as `not_home`, they are excluded from automatic assignment for new measurements
+  - This helps avoid incorrectly assigning measurements when household members are away
+
+- **Mobile Devices (optional):** Select one or more mobile devices (via Home Assistant companion app) to receive actionable notifications for ambiguous measurements:
+  - When enabled, you'll receive a mobile notification with tap-to-assign buttons directly on your phone
+  - Each candidate user gets a personalized notification with "This is me" and "Not me" buttons
+
+- **Enable body composition metrics:** Calculate additional health metrics (BMI, body fat %, etc.) based on impedance measurements. Requires sex, date of birth, and height.
+
+## Multi-User Support
+
+This integration is designed for households with multiple users. You can create a unique profile for each person using the scale.
+
+### Person Detection
+
+When a new measurement is received, the integration attempts to automatically assign it to the correct person based on two factors:
+
+1. **Weight History:** The measurement is compared against each user's weight history.
+2. **Location:** If a user profile is linked to a Home Assistant `person` entity, the integration checks if that person is `home`. Users who are `not_home` are excluded from automatic assignment.
+
+If a single user is a clear match, the measurement is assigned automatically.
+
+### Ambiguous Measurements
+
+If the measurement is ambiguous (e.g., two users have similar weights, or a new user has no history), the integration will notify you:
+
+- **Mobile Notifications (if configured):** Each candidate user receives a personalized notification on their mobile device with actionable buttons:
+  - "This is me" - Assigns the measurement to you
+  - "Not me" - Dismisses your notification (measurement remains available for others)
+
+- **Persistent Notifications:** A notification appears in the Home Assistant notifications panel with instructions to manually assign the measurement using the `assign_measurement` service.
+
+### Managing Users
+
+You can manage user profiles by navigating to your device in **Settings > Devices & Services > Etekcity Fitness Scale BLE**. Click **CONFIGURE** to:
+- **Add a new user:** Create a new profile with optional person entity link and mobile notification settings.
+- **Edit a user:** Update a user's name, linked person entity, mobile devices, or body metric settings.
+- **Remove a user:** Delete a user's profile and all associated sensor entities.
+
+## Legacy Default User (Old Version Migration)
+
+If you used the original single-user version of the integration, migrating to this version keeps your existing sensors by creating a "Default User" whose `user_id` is an empty string (`""`):
+- Sensors for the legacy user keep their original entity IDs (no name prefix) so dashboards and automations continue working.
+- When calling services, set `user_id: ""` anytime you want to target the legacy profile.
+
+## Services
+
+The integration provides services to manage measurements, especially for handling ambiguous weigh-ins. You can use these in scripts or automations, or call them directly from **Developer Tools > Actions**.
+
+### `etekcity_fitness_scale_ble.assign_measurement`
+Assign a pending (ambiguous) measurement to a specific user. The `timestamp` and candidate `user_id`s are provided in the persistent notification.
+
+**Example:**
+```yaml
+service: etekcity_fitness_scale_ble.assign_measurement
+data:
+  device_id: <your_scale_device_id>
+  timestamp: "2025-11-06T15:30:00.123456"
+  user_id: "jane" # or "" for legacy user
+```
+
+### `etekcity_fitness_scale_ble.reassign_measurement`
+Reassign the most recent measurement from one user to another. This is useful if a measurement was automatically but incorrectly assigned.
+
+**Example:**
+```yaml
+service: etekcity_fitness_scale_ble.reassign_measurement
+data:
+  device_id: <your_scale_device_id>
+  from_user_id: "john2"
+  to_user_id: "jane" # or "" for legacy user
+```
+
+### `etekcity_fitness_scale_ble.remove_measurement`
+Remove the last measurement for a specific user. This will revert the user's sensors to their previous values.
+
+**Example:**
+```yaml
+service: etekcity_fitness_scale_ble.remove_measurement
+data:
+  device_id: <your_scale_device_id>
+  user_id: "john2" # or "" for legacy user
+```
+
+## Diagnostic Sensors
+
+The integration creates two diagnostic sensors to provide visibility into its state:
+- **User Directory:** Shows the number of configured user profiles and lists their details (including `user_id`) in the attributes.
+- **Pending Measurements:** Shows the number of ambiguous measurements awaiting manual assignment and lists their timestamps in the attributes.
 
 ## Supported Devices