Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
- `b5`: Battery Lifetime Discharge (Wh) with automatic kWh/MWh conversion.
- `b6`: Battery State (0–9 numeric status code).
- Reorganized the solar array configuration UI to group PVOutput donation parameters (`v7`–`v12` Extended Data and `b1`–`b6` Battery Data) into a collapsible section, separating them from standard free-tier parameters across all supported languages.
- Added support for `number` and `input_number` entities (in addition to `sensor`) on `v7`–`v12`, `b3`, and `b6`, and added a direct link to the PVOutput API Documentation in the configuration UI.

### Bugfixes
- Fixed an issue where clearing optional entity selectors or text fields when editing a system did not persist and reverted to the previously saved values. ([Issue#17](https://github.com/SourceLabOrg/HomeAssistant-PVOutputPublisher/issues/17))
Expand Down
28 changes: 25 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,13 +77,35 @@ This integration is installed via [HACS](https://hacs.xyz/).

### Donation Features (PVOutput Donation Required)
*Expand the **Donation Features** section in the UI to configure:*
* **v7 – v12: Extended Data:** (Optional) Custom donation metrics.
* **v7 – v12: Extended Data:** (Optional) Custom donation metrics (supports `sensor`, `number`, and `input_number` entities).
* **b1: Battery Power (W):** (Optional) Instantaneous battery power (positive for charge, negative for discharge).
* **b2: Battery State of Charge (%):** (Optional) Battery charge percentage (0–100%).
* **b3: Battery Usable Capacity (Wh):** (Optional) Usable battery capacity.
* **b3: Battery Usable Capacity (Wh):** (Optional) Usable battery capacity (supports `sensor`, `number`, and `input_number` entities).
* **b4: Battery Lifetime Charge (Wh):** (Optional) Cumulative lifetime battery charge energy.
* **b5: Battery Lifetime Discharge (Wh):** (Optional) Cumulative lifetime battery discharge energy.
* **b6: Battery State (Code 0-9):** (Optional) Numeric battery status code.
* **b6: Battery State (Code 0-9):** (Optional) Numeric battery status code (`0`: Invalid, `1`: Standby, `2`: Thermal, `3`: Enabled, `4`: Fault, `5–9`: User Defined; supports `sensor`, `number`, and `input_number` entities).

#### Mapping Text Battery States to `b6` with a Template Sensor
Many battery integrations report status as a text string (e.g., `"charging"`, `"discharging"`, `"standby"`, `"fault"`), whereas PVOutput expects a numeric code (`0–9`) for `b6`. You can easily bridge this using a Home Assistant **Template Sensor Helper**:

1. Go to **Settings > Devices & Services > Helpers**.
2. Click **Create Helper** → **Template** → **Template a sensor**.
3. Give it a name (e.g., `PVOutput Battery State`) and paste a state template adapted to your battery sensor:
```jinja2
{% set status = states('sensor.my_battery_status') | lower %}
{% if status in ['charging', 'discharging', 'active', 'enabled'] %}
3
{% elif status in ['standby', 'idle'] %}
1
{% elif status in ['thermal', 'cooling', 'heating'] %}
2
{% elif status in ['fault', 'error', 'alarm'] %}
4
{% else %}
0
{% endif %}
```
4. Select this new `sensor.pvoutput_battery_state` entity in the **b6: Battery State (Code 0-9)** field.

### Managing Multiple Systems
You can add, edit, or remove systems at any time. Simply go to **Settings > Devices & Services**, find the **PVOutput Publisher** integration card, and click **Configure**.
Expand Down
14 changes: 8 additions & 6 deletions custom_components/pvoutput_publisher/config_flow.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
CONF_V1, CONF_V2, CONF_V3, CONF_V4, CONF_V5, CONF_V6,
CONF_V7, CONF_V8, CONF_V9, CONF_V10, CONF_V11, CONF_V12,
CONF_B1, CONF_B2, CONF_B3, CONF_B4, CONF_B5, CONF_B6,
CONF_C1, CONF_NET, CONF_DONATION_FIELDS
CONF_C1, CONF_NET, CONF_DONATION_FIELDS, PVOUTPUT_API_DOCS_URL
)

def _clean_system_input(user_input: dict) -> dict:
Expand Down Expand Up @@ -112,7 +112,7 @@ def _get_system_schema(existing_data=None):
# v7 through v12 (Extended Data - Donation Feature)
for v_key in [CONF_V7, CONF_V8, CONF_V9, CONF_V10, CONF_V11, CONF_V12]:
donation_schema[_optional_field(v_key, donation_data)] = selector.EntitySelector(
selector.EntitySelectorConfig(domain="sensor")
selector.EntitySelectorConfig(domain=["sensor", "number", "input_number"])
)

# b1 (Battery Power - W)
Expand All @@ -127,7 +127,7 @@ def _get_system_schema(existing_data=None):

# b3 (Battery Size / Usable Capacity - Wh)
donation_schema[_optional_field(CONF_B3, donation_data)] = selector.EntitySelector(
selector.EntitySelectorConfig(domain="sensor")
selector.EntitySelectorConfig(domain=["sensor", "number", "input_number"])
)

# b4 (Battery Lifetime Charge - Wh)
Expand All @@ -142,7 +142,7 @@ def _get_system_schema(existing_data=None):

# b6 (Battery State - Code 0-9)
donation_schema[_optional_field(CONF_B6, donation_data)] = selector.EntitySelector(
selector.EntitySelectorConfig(domain="sensor")
selector.EntitySelectorConfig(domain=["sensor", "number", "input_number"])
)

schema[vol.Optional(CONF_DONATION_FIELDS)] = section(
Expand Down Expand Up @@ -184,7 +184,8 @@ async def async_step_add_system(self, user_input=None):
existing_data = self._systems[self._editing_index] if self._editing_index is not None else None
return self.async_show_form(
step_id="add_system",
data_schema=_get_system_schema(existing_data)
data_schema=_get_system_schema(existing_data),
description_placeholders={"api_docs_url": PVOUTPUT_API_DOCS_URL},
)

async def async_step_systems_manager(self, user_input=None):
Expand Down Expand Up @@ -258,7 +259,8 @@ async def async_step_add_system(self, user_input=None):
existing_data = self._systems[self._editing_index] if self._editing_index is not None else None
return self.async_show_form(
step_id="add_system",
data_schema=_get_system_schema(existing_data)
data_schema=_get_system_schema(existing_data),
description_placeholders={"api_docs_url": PVOUTPUT_API_DOCS_URL},
)

async def async_step_edit_api(self, user_input=None):
Expand Down
1 change: 1 addition & 0 deletions custom_components/pvoutput_publisher/const.py
Original file line number Diff line number Diff line change
Expand Up @@ -45,3 +45,4 @@

DEFAULT_FREQUENCY = "5"
PVOUTPUT_API_URL = "https://pvoutput.org/service/r2/addstatus.jsp"
PVOUTPUT_API_DOCS_URL = "https://pvoutput.org/help/api_specification.html#id2"
8 changes: 4 additions & 4 deletions custom_components/pvoutput_publisher/translations/de.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
},
"add_system": {
"title": "Solaranlage konfigurieren",
"description": "Ordnen Sie Ihre Home Assistant-Sensoren den PVOutput-API-Parametern zu. Lassen Sie optionale Sensoren leer, falls nicht zutreffend.",
"description": "Ordnen Sie Ihre Home Assistant-Sensoren den PVOutput-API-Parametern zu ([API-Dokumentation]({api_docs_url})). Lassen Sie optionale Sensoren leer, falls nicht zutreffend.",
"data": {
"name": "Systemname",
"system_id": "System-ID",
Expand Down Expand Up @@ -69,7 +69,7 @@
"b3": "Nutzbare Batteriekapazität in Wattstunden (kWh/MWh werden automatisch umgerechnet).",
"b4": "Kumulierte geladene Lebenszeit-Energie in Wattstunden (kWh/MWh werden automatisch umgerechnet).",
"b5": "Kumulierte entladene Lebenszeit-Energie in Wattstunden (kWh/MWh werden automatisch umgerechnet).",
"b6": "Numerischer Batteriestatuscode (0: Ungültig, 1: Standby, 2: Thermisch, 3: Aktiviert, 4: Fehler, 5-9: Benutzerdefiniert)."
"b6": "Numerischer Batteriestatuscode (0: Ungültig, 1: Standby, 2: Thermisch, 3: Aktiviert, 4: Fehler, 5-9: Benutzerdefiniert). Unterstützt sensor-, number- oder input_number-Entitäten (z. B. einen Template-Sensor-Helfer zur Zuordnung von Textstatus zu 0-9)."
}
}
}
Expand Down Expand Up @@ -104,7 +104,7 @@
},
"add_system": {
"title": "Solaranlage konfigurieren",
"description": "Ordnen Sie Ihre Home Assistant-Sensoren den PVOutput-API-Parametern zu. Lassen Sie optionale Sensoren leer, falls nicht zutreffend.",
"description": "Ordnen Sie Ihre Home Assistant-Sensoren den PVOutput-API-Parametern zu ([API-Dokumentation]({api_docs_url})). Lassen Sie optionale Sensoren leer, falls nicht zutreffend.",
"data": {
"name": "Systemname",
"system_id": "System-ID",
Expand Down Expand Up @@ -163,7 +163,7 @@
"b3": "Nutzbare Batteriekapazität in Wattstunden (kWh/MWh werden automatisch umgerechnet).",
"b4": "Kumulierte geladene Lebenszeit-Energie in Wattstunden (kWh/MWh werden automatisch umgerechnet).",
"b5": "Kumulierte entladene Lebenszeit-Energie in Wattstunden (kWh/MWh werden automatisch umgerechnet).",
"b6": "Numerischer Batteriestatuscode (0: Ungültig, 1: Standby, 2: Thermisch, 3: Aktiviert, 4: Fehler, 5-9: Benutzerdefiniert)."
"b6": "Numerischer Batteriestatuscode (0: Ungültig, 1: Standby, 2: Thermisch, 3: Aktiviert, 4: Fehler, 5-9: Benutzerdefiniert). Unterstützt sensor-, number- oder input_number-Entitäten (z. B. einen Template-Sensor-Helfer zur Zuordnung von Textstatus zu 0-9)."
}
}
}
Expand Down
8 changes: 4 additions & 4 deletions custom_components/pvoutput_publisher/translations/en.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
},
"add_system": {
"title": "Configure Solar System",
"description": "Map your Home Assistant sensors to PVOutput API parameters. Leave any optional sensors blank if not applicable.",
"description": "Map your Home Assistant sensors to PVOutput API parameters ([API Documentation]({api_docs_url})). Leave any optional sensors blank if not applicable.",
"data": {
"name": "System Name",
"system_id": "System ID",
Expand Down Expand Up @@ -69,7 +69,7 @@
"b3": "Usable battery capacity in Watt-hours (converts kWh/MWh automatically).",
"b4": "Cumulative lifetime battery charge energy in Watt-hours (converts kWh/MWh automatically).",
"b5": "Cumulative lifetime battery discharge energy in Watt-hours (converts kWh/MWh automatically).",
"b6": "Numeric battery state code (0: Invalid, 1: Standby, 2: Thermal, 3: Enabled, 4: Fault, 5-9: User Defined)."
"b6": "Numeric battery state code (0: Invalid, 1: Standby, 2: Thermal, 3: Enabled, 4: Fault, 5-9: User Defined). Supports sensor, number, or input_number entities (e.g. a Template Sensor helper to map text statuses to 0-9)."
}
}
}
Expand Down Expand Up @@ -104,7 +104,7 @@
},
"add_system": {
"title": "Configure Solar System",
"description": "Map your Home Assistant sensors to PVOutput API parameters. Leave any optional sensors blank if not applicable.",
"description": "Map your Home Assistant sensors to PVOutput API parameters ([API Documentation]({api_docs_url})). Leave any optional sensors blank if not applicable.",
"data": {
"name": "System Name",
"system_id": "System ID",
Expand Down Expand Up @@ -163,7 +163,7 @@
"b3": "Usable battery capacity in Watt-hours (converts kWh/MWh automatically).",
"b4": "Cumulative lifetime battery charge energy in Watt-hours (converts kWh/MWh automatically).",
"b5": "Cumulative lifetime battery discharge energy in Watt-hours (converts kWh/MWh automatically).",
"b6": "Numeric battery state code (0: Invalid, 1: Standby, 2: Thermal, 3: Enabled, 4: Fault, 5-9: User Defined)."
"b6": "Numeric battery state code (0: Invalid, 1: Standby, 2: Thermal, 3: Enabled, 4: Fault, 5-9: User Defined). Supports sensor, number, or input_number entities (e.g. a Template Sensor helper to map text statuses to 0-9)."
}
}
}
Expand Down
8 changes: 4 additions & 4 deletions custom_components/pvoutput_publisher/translations/es.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
},
"add_system": {
"title": "Configurar sistema solar",
"description": "Asigne sus sensores de Home Assistant a los parámetros de la API de PVOutput. Deje en blanco los sensores opcionales que no correspondan.",
"description": "Asigne sus sensores de Home Assistant a los parámetros de la API de PVOutput ([Documentación de la API]({api_docs_url})). Deje en blanco los sensores opcionales que no correspondan.",
"data": {
"name": "Nombre del sistema",
"system_id": "ID del sistema",
Expand Down Expand Up @@ -69,7 +69,7 @@
"b3": "Capacidad útil de la batería en vatios-hora (kWh/MWh se convierte automáticamente).",
"b4": "Energía de carga acumulada en la vida útil en vatios-hora (kWh/MWh se convierte automáticamente).",
"b5": "Energía de descarga acumulada en la vida útil en vatios-hora (kWh/MWh se convierte automáticamente).",
"b6": "Código numérico de estado de la batería (0: No válido, 1: En espera, 2: Térmico, 3: Habilitado, 4: Fallo, 5-9: Definido por usuario)."
"b6": "Código numérico de estado de la batería (0: No válido, 1: En espera, 2: Térmico, 3: Habilitado, 4: Fallo, 5-9: Definido por usuario). Admite entidades sensor, number o input_number (p. ej., un ayudante de sensor de plantilla para convertir estados de texto a 0-9)."
}
}
}
Expand Down Expand Up @@ -104,7 +104,7 @@
},
"add_system": {
"title": "Configurar sistema solar",
"description": "Asigne sus sensores de Home Assistant a los parámetros de la API de PVOutput. Deje en blanco los sensores opcionales que no correspondan.",
"description": "Asigne sus sensores de Home Assistant a los parámetros de la API de PVOutput ([Documentación de la API]({api_docs_url})). Deje en blanco los sensores opcionales que no correspondan.",
"data": {
"name": "Nombre del sistema",
"system_id": "ID del sistema",
Expand Down Expand Up @@ -163,7 +163,7 @@
"b3": "Capacidad útil de la batería en vatios-hora (kWh/MWh se convierte automáticamente).",
"b4": "Energía de carga acumulada en la vida útil en vatios-hora (kWh/MWh se convierte automáticamente).",
"b5": "Energía de descarga acumulada en la vida útil en vatios-hora (kWh/MWh se convierte automáticamente).",
"b6": "Código numérico de estado de la batería (0: No válido, 1: En espera, 2: Térmico, 3: Habilitado, 4: Fallo, 5-9: Definido por usuario)."
"b6": "Código numérico de estado de la batería (0: No válido, 1: En espera, 2: Térmico, 3: Habilitado, 4: Fallo, 5-9: Definido por usuario). Admite entidades sensor, number o input_number (p. ej., un ayudante de sensor de plantilla para convertir estados de texto a 0-9)."
}
}
}
Expand Down
8 changes: 4 additions & 4 deletions custom_components/pvoutput_publisher/translations/ja.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
},
"add_system": {
"title": "システムの設定",
"description": "Home Assistant のセンサーを PVOutput API パラメータにマッピングします。該当しないセンサーは空欄のままで構いません。",
"description": "Home Assistant のセンサーを PVOutput API パラメータにマッピングします ([API ドキュメント]({api_docs_url}))。該当しないセンサーは空欄のままで構いません。",
"data": {
"name": "システム名",
"system_id": "システム ID",
Expand Down Expand Up @@ -69,7 +69,7 @@
"b3": "バッテリーの有効容量(Wh、kWh/MWhは自動変換)。",
"b4": "生涯累積充電電力量(Wh、kWh/MWhは自動変換)。",
"b5": "生涯累積放電電力量(Wh、kWh/MWhは自動変換)。",
"b6": "バッテリー状態コード(0: 無効, 1: スタンバイ, 2: 熱管理, 3: 有効, 4: 異常, 5-9: ユーザー定義)。"
"b6": "バッテリー状態コード(0: 無効, 1: スタンバイ, 2: 熱管理, 3: 有効, 4: 異常, 5-9: ユーザー定義)。sensor、number、input_number エンティティに対応(テキスト状態を 0-9 に変換するテンプレートセンサーヘルパーなど)。"
}
}
}
Expand Down Expand Up @@ -104,7 +104,7 @@
},
"add_system": {
"title": "システムの設定",
"description": "Home Assistant のセンサーを PVOutput API パラメータにマッピングします。該当しないセンサーは空欄のままで構いません。",
"description": "Home Assistant のセンサーを PVOutput API パラメータにマッピングします ([API ドキュメント]({api_docs_url}))。該当しないセンサーは空欄のままで構いません。",
"data": {
"name": "システム名",
"system_id": "システム ID",
Expand Down Expand Up @@ -163,7 +163,7 @@
"b3": "バッテリーの有効容量(Wh、kWh/MWhは自動変換)。",
"b4": "生涯累積充電電力量(Wh、kWh/MWhは自動変換)。",
"b5": "生涯累積放電電力量(Wh、kWh/MWhは自動変換)。",
"b6": "バッテリー状態コード(0: 無効, 1: スタンバイ, 2: 熱管理, 3: 有効, 4: 異常, 5-9: ユーザー定義)。"
"b6": "バッテリー状態コード(0: 無効, 1: スタンバイ, 2: 熱管理, 3: 有効, 4: 異常, 5-9: ユーザー定義)。sensor、number、input_number エンティティに対応(テキスト状態を 0-9 に変換するテンプレートセンサーヘルパーなど)。"
}
}
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
},
"add_system": {
"title": "配置太阳能发电系统",
"description": "将您的 Home Assistant 传感器映射到 PVOutput API 参数。不适用的可选传感器可留空。",
"description": "将您的 Home Assistant 传感器映射到 PVOutput API 参数([API 文档]({api_docs_url}))。不适用的可选传感器可留空。",
"data": {
"name": "系统名称",
"system_id": "系统 ID",
Expand Down Expand Up @@ -69,7 +69,7 @@
"b3": "可用电池容量(瓦时,kWh/MWh自动转换)。",
"b4": "全生命周期累计充电电量(瓦时,kWh/MWh自动转换)。",
"b5": "全生命周期累计放电电量(瓦时,kWh/MWh自动转换)。",
"b6": "数字电池状态代码(0: 无效, 1: 待机, 2: 热管理, 3: 启用, 4: 故障, 5-9: 用户自定义)。"
"b6": "数字电池状态代码(0: 无效, 1: 待机, 2: 热管理, 3: 启用, 4: 故障, 5-9: 用户自定义)。支持 sensor、number 或 input_number 实体(例如使用模板传感器辅助工具将文本状态映射为 0-9)。"
}
}
}
Expand Down Expand Up @@ -104,7 +104,7 @@
},
"add_system": {
"title": "配置太阳能发电系统",
"description": "将您的 Home Assistant 传感器映射到 PVOutput API 参数。不适用的可选传感器可留空。",
"description": "将您的 Home Assistant 传感器映射到 PVOutput API 参数([API 文档]({api_docs_url}))。不适用的可选传感器可留空。",
"data": {
"name": "系统名称",
"system_id": "系统 ID",
Expand Down Expand Up @@ -163,7 +163,7 @@
"b3": "可用电池容量(瓦时,kWh/MWh自动转换)。",
"b4": "全生命周期累计充电电量(瓦时,kWh/MWh自动转换)。",
"b5": "全生命周期累计放电电量(瓦时,kWh/MWh自动转换)。",
"b6": "数字电池状态代码(0: 无效, 1: 待机, 2: 热管理, 3: 启用, 4: 故障, 5-9: 用户自定义)。"
"b6": "数字电池状态代码(0: 无效, 1: 待机, 2: 热管理, 3: 启用, 4: 故障, 5-9: 用户自定义)。支持 sensor、number 或 input_number 实体(例如使用模板传感器辅助工具将文本状态映射为 0-9)。"
}
}
}
Expand Down
Loading
Loading