Profiles review improvements

README.md

@@ -13,10 +13,10 @@ The profiles are organized hierarchically to allow for flexible composition base
    - Components are modular and focused on a specific functionality
    - Components can be composed to create complete device profiles
 
-2. **Device Implementations (`/energy`)** - Complete device profiles organized by type:
+2. **Device Implementations (`/energy`, `/sensor`)** - Complete device profiles organized by domain:
    - Each implementation combines multiple library profiles
-   - Implementations are organized by device type
-   - Ready-to-use profiles for common energy devices
+   - Implementations are organized by device type within each domain directory
+   - Ready-to-use profiles for common energy and sensor devices
 
 ## Usage
 
@@ -26,6 +26,55 @@ Profiles are used in Enapter Blueprints to specify the capabilities and the inte
 2. **Extend with Components**: Add additional library components to the device blueprint if needed.
 3. **Submit a Proposal**: If a profile for your device doesn't exist, create a new one and submit a pull request.
 
+## Conventions
+
+### Sign Conventions
+
+Power and current signs are defined so that the energy balance `pv_power + battery_power + grid_power = load_power` holds naturally:
+
+| Measurement Point | Positive (+) | Negative (-) |
+|---|---|---|
+| Battery current/power | Discharging | Charging |
+| Inverter AC power | Delivering to loads/grid | Consuming (e.g. standby) |
+| Grid power | Importing from grid | Exporting to grid |
+| Load power | Consumed by loads | N/A (typically) |
+| PV power | Generating | N/A |
+
+**Rule of thumb:** if the measurement represents energy being delivered to the system, it is positive. If it represents energy being absorbed, it is negative.
+
+For unidirectional measurements where the direction is clear from context (e.g. `power_consumption` for a device that only consumes), positive values representing the natural physical quantity are acceptable.
+
+### Naming Conventions
+
+- All field names use `snake_case`
+- Battery fields use `battery_` prefix
+- Inverter AC fields use `ac_` prefix (DC side is either battery or PV and has its own prefix)
+- PV fields use `pv_` prefix with `s1`/`s2`/etc. for individual strings
+- Grid fields use `grid_` prefix
+- Load fields use `load_` prefix
+- Power meter total fields (`total_power`, `total_current`, `energy_total`) omit the `ac_` prefix because power meters only measure one type of current, so the prefix is redundant. Per-phase fields keep the `ac_` prefix since they follow the same naming as inverter per-phase measurements.
+- Three-phase measurements use `l1`/`l2`/`l3` suffixes (IEC convention)
+- Units follow [UCUM](https://ucum.org/) notation. See the [units introduction](https://v3.developers.enapter.com/docs/units/introduction) and [frequently used units](https://v3.developers.enapter.com/docs/units/frequently-used) for the full reference.
+- Status fields must use a context-appropriate prefix instead of the bare `status` name (e.g. `inverter_status`, `charger_status`, `relay_state`). The bare `status` is a reserved field name in the Enapter platform with [special meaning](https://developers.enapter.com/docs/reference/manifest#device-status) and is intentionally left for the Blueprint developer to expose the native device status. Profiles define a separate prefixed field with a unified set of operational states (e.g. `off`, `operating`, `fault`) so that UIs and automation can treat all devices of the same type consistently, while the native status remains available for device-specific diagnostics.
+
+### Unit Conventions
+
+Some physical quantities appear in different units across device types. There are two ways to handle this, depending on whether the units are interchangeable:
+
+- **Separate profiles per unit**: when units measure different physical quantities and silent conversion would hide precision loss. Blueprint authors implement whichever profile their device supports natively; consumers must handle both explicitly. See `lib.energy.battery.energy` (Wh) and `lib.energy.battery.charge` (Ah) as an example.
+- **Single canonical unit with required conversion**: when the same quantity can be meaningfully expressed in either unit and one is clearly more appropriate. Blueprint authors must convert to the canonical unit. See `lib.energy.battery.limits` (W, with a documented formula for devices that only report in A) as an example.
+
+## Versioning
+
+Profiles use **append-only immutability with composition-based extension**:
+
+- **Published profiles are immutable.** Once a profile is published (non-draft), its YAML cannot change. This guarantees that existing Blueprints on deployed Gateways never become invalid.
+- **No field removal.** If a profile needs incompatible changes, create a new profile version (e.g. `energy.battery_v2`) that implements the old one plus new library components.
+- **Field addition via composition.** New capabilities are added by creating new library components and composing them into a new device profile that `implements` the previous version.
+- **Draft mode.** Profiles start as drafts and can be iterated freely. Once promoted to non-draft, they become immutable. A non-draft profile cannot implement a draft profile, preventing unstable dependencies from leaking into production.
+
+In practice, keeping profiles minimal reduces the need for breaking changes. When extension is needed, the composition model allows new profiles to build on existing ones without invalidating older Blueprints.
+
 ## Development
 
 ### Device Profile

energy/battery.yml

@@ -1,7 +1,7 @@
 blueprint_spec: profile/1.0
 
 display_name: Battery/BMS Profile
-description: A profile for battery and battery management systems
+description: A profile for battery systems and battery management systems (BMS). Covers state of charge, charge/discharge power and current, and nameplate attributes. Suitable for standalone battery banks and integrated BESS units.
 
 implements:
   - lib.device.nameplate

energy/battery_inverter/1_phase.yml

@@ -1,7 +1,7 @@
 blueprint_spec: profile/1.0
 
 display_name: Single-Phase Battery Inverter
-description: A single-phase battery inverter profile combining all relevant capabilities
+description: A profile for single-phase battery inverters (off-grid and grid-tied). Covers battery state of charge and charge/discharge power, AC output measurements, grid import/export and load power, operational status, and nameplate attributes.
 
 implements:
   - lib.device.nameplate

energy/battery_inverter/3_phase.yml

@@ -1,7 +1,7 @@
 blueprint_spec: profile/1.0
 
 display_name: Three-Phase Battery Inverter
-description: A three-phase battery inverter profile combining all relevant capabilities
+description: A profile for three-phase battery inverters (off-grid and grid-tied). Covers battery state of charge and charge/discharge power, AC output measurements, grid import/export and load power, operational status, and nameplate attributes.
 
 implements:
   - lib.device.nameplate

energy/hybrid_inverter/1_phase.yml

@@ -1,7 +1,7 @@
 blueprint_spec: profile/1.0
 
 display_name: Single-Phase Hybrid Inverter
-description: A single-phase hybrid inverter profile combining battery and PV capabilities
+description: A profile for single-phase hybrid inverters with integrated PV input and battery management. Covers PV input power, battery state of charge and power, AC output measurements, grid and load power, operational status, and nameplate attributes.
 
 implements:
   - lib.device.nameplate

energy/hybrid_inverter/3_phase.yml

@@ -1,7 +1,7 @@
 blueprint_spec: profile/1.0
 
 display_name: Three-Phase Hybrid Inverter
-description: A three-phase hybrid inverter profile combining battery and PV capabilities
+description: A profile for three-phase hybrid inverters with integrated PV input and battery management. Covers PV input power, battery state of charge and power, AC output measurements, grid and load power, operational status, and nameplate attributes.
 
 implements:
   - lib.device.nameplate

energy/power_meter/ac/1_phase.yml

@@ -1,7 +1,7 @@
 blueprint_spec: profile/1.0
 
 display_name: Single-Phase Power Meter
-description: A single-phase power meter profile
+description: A profile for single-phase AC power meters. Covers voltage, current, power, and cumulative energy consumption.
 
 implements:
   - lib.device.nameplate

energy/power_meter/ac/3_phase.yml

@@ -1,7 +1,7 @@
 blueprint_spec: profile/1.0
 
 display_name: Three-Phase Power Meter
-description: A three-phase power meter profile
+description: A profile for three-phase AC power meters. Covers per-phase and total voltage, current, power, and cumulative energy consumption.
 
 implements:
   - lib.device.nameplate

energy/pv_charge_controller.yml

@@ -1,7 +1,7 @@
 blueprint_spec: profile/1.0
 
 display_name: PV Charge Controller
-description: A profile for PV charge controllers
+description: A profile for solar charge controllers (MPPT and PWM). Covers PV input power, battery state of charge, charge/discharge current, and battery nameplate attributes.
 
 implements:
   - lib.device.nameplate

energy/pv_inverter/1_phase.yml

@@ -1,7 +1,7 @@
 blueprint_spec: profile/1.0
 
 display_name: Single-Phase PV Inverter
-description: A single-phase PV inverter profile combining all relevant capabilities
+description: A profile for single-phase grid-tied PV inverters. Covers PV input power, AC output voltage/current/power, total AC power, operational status, and nameplate capacity.
 
 implements:
   - lib.device.nameplate

energy/pv_inverter/3_phase.yml

@@ -1,7 +1,7 @@
 blueprint_spec: profile/1.0
 
 display_name: Three-Phase PV Inverter
-description: A three-phase PV inverter profile combining all relevant capabilities
+description: A profile for three-phase grid-tied PV inverters. Covers PV input power, per-phase and total AC output power, operational status, and nameplate capacity.
 
 implements:
   - lib.device.nameplate