Skip to content

Commit 3c80e67

Browse files
CrimCrim
committed
update readme, add translations
1 parent 16e9a5d commit 3c80e67

5 files changed

Lines changed: 254 additions & 27 deletions

File tree

‎README.md‎

Lines changed: 32 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,35 @@
11
# Home Assistant PVOutput Publisher
22

3-
A custom Home Assistant integration that pushes your live solar generation or daily cumulative energy data directly to [PVOutput.org](https://pvoutput.org/).
3+
A custom Home Assistant integration that actively pushes your solar generation, home consumption, and local temperature data directly to [PVOutput.org](https://pvoutput.org/).
44

5-
Unlike the official Home Assistant PVOutput integration (which only *downloads* data), this integration actively *publishes* your local Home Assistant sensor data up to your PVOutput account.
5+
Unlike the official Home Assistant PVOutput integration (which only *downloads* data), this integration acts as an automated publisher, bridging your local Home Assistant sensors to your public PVOutput dashboard.
66

77
## Disclaimer: AI-Generated Project
8-
Please note that the code and documentation for this project were primarily generated with the assistance of an AI. While it has been actively tested and confirmed to work within Home Assistant, it is provided "as is." Please review the code and use it at your own discretion.
8+
Please note that the code and documentation for this project were primarily generated with the assistance of an AI. While it has been actively tested and confirmed to work perfectly within Home Assistant, it is provided "as is." Please review the code and use it at your own discretion.
99

1010
---
1111

1212
## Features
13-
* **UI Config Flow:** Fully configurable via the Home Assistant UI. No YAML required!
13+
* **UI Config Flow:** Fully configurable via the Home Assistant UI. No YAML required.
1414
* **Multi-System Support:** Publish data for multiple solar arrays or inverters to different PVOutput System IDs using a single API key.
15-
* **Customizable Frequency:** Choose how often to publish data (5, 10, 15, 30, 60, or 180 minutes).
16-
* **Smart Power vs. Energy Detection:** Automatically formats the payload based on the sensor you select (see below).
15+
* **Smart Data Detection:** Automatically formats the payload based on the units of your selected sensors (Watts vs. Watt-hours, Celsius vs. Fahrenheit).
16+
* **Lifetime Energy Support:** Automatically detects `state_class: total` sensors and flags PVOutput to calculate your daily yield and instantaneous power curves for you.
17+
* **Comprehensive Metrics:** Supports pushing Generation, Consumption, and Temperature data simultaneously.
1718
* **Last Upload Sensor:** Creates a timestamp entity in Home Assistant so you can monitor exactly when the last successful push occurred.
19+
* **Multi-Language Support:** Fully translated into English, Japanese, Spanish, and German.
1820

1921
---
2022

21-
## Smart Sensor Detection (Power vs. Energy)
22-
PVOutput expects data in one of two formats. This integration looks at the `unit_of_measurement` of your selected sensor and automatically sends the correct data type:
23+
## Smart Sensor Detection
24+
PVOutput requires data to be formatted precisely. This integration looks at the `unit_of_measurement` and `state_class` of your selected sensors and automatically handles the conversions:
2325

24-
### 1. Instantaneous Power (Watts / kW)
25-
If you select a sensor measuring **Watts** or **kW** (e.g., current live generation), the integration automatically converts it to pure Watts and sends it to PVOutput as the `v2` (Power Generation) parameter.
26-
* *Best for 5-minute update frequencies.*
26+
### Generation & Consumption
27+
* **Power (Watts / kW):** Automatically converted to Watts and sent as `v2` (Generation) or `v4` (Consumption).
28+
* **Daily Energy (Wh / kWh):** Automatically converted to Watt-hours and sent as `v1` (Generation) or `v3` (Consumption).
29+
* **Lifetime Energy:** If your sensor tracks lifetime yield (e.g., `state_class: total_increasing`), the integration sends the `&c1=1` flag. PVOutput will automatically calculate your daily generation and live power curves by comparing the intervals.
2730

28-
### 2. Cumulative Energy (Wh / kWh)
29-
If you select a sensor measuring **Wh** or **kWh** (e.g., "Daily Solar Energy"), the integration converts it to pure Watt-hours and sends it as the `v1` (Energy Generation) parameter. PVOutput will automatically calculate the average power for the interval based on the change in energy.
30-
* *Best for longer update frequencies (30+ minutes) to ensure you don't miss generation data if clouds pass over between updates.*
31+
### Temperature
32+
* If your Home Assistant sensor uses Fahrenheit (`°F`), it will automatically be converted to Celsius before uploading, as PVOutput strictly requires Celsius for its `v5` parameter.
3133

3234
---
3335

@@ -38,11 +40,10 @@ This integration is installed via [HACS](https://hacs.xyz/).
3840
1. Open **HACS** in your Home Assistant instance.
3941
2. Go to **Integrations**.
4042
3. Click the three dots in the top right corner and select **Custom repositories**.
41-
4. Paste the URL of this GitHub repository.
43+
4. Paste the URL of this GitHub repository `https://github.com/SourceLabOrg/HomeAssistant-PVOutputPublisher`
4244
5. Select **Integration** as the Category and click **Add**.
4345
6. Search for **PVOutput Publisher** in HACS and click **Download**.
4446
7. **Restart Home Assistant**.
45-
8. *(Important)* Hard-refresh your browser to clear the frontend cache.
4647

4748
---
4849

@@ -53,10 +54,12 @@ This integration is installed via [HACS](https://hacs.xyz/).
5354
3. Search for **PVOutput Publisher**.
5455
4. Enter your global **PVOutput API Key** (found in your PVOutput account settings).
5556
5. Add your first system by providing:
56-
* **System Name:** A friendly name for your reference.
57-
* **System ID:** Your PVOutput System ID.
58-
* **Solar Sensor Entity:** The Home Assistant sensor tracking your solar generation.
59-
* **Update Frequency:** How often to push data to PVOutput.
57+
* **System Name:** A friendly name for your reference.
58+
* **System ID:** Your PVOutput System ID.
59+
* **Solar Generation Sensor:** Your inverter's power or energy sensor.
60+
* **Power/Energy Consumption Sensor:** (Optional) Your home's power draw or energy usage sensor.
61+
* **Temperature Sensor:** (Optional) Outside temperature.
62+
* **Update Frequency:** How often to push data to PVOutput (5 to 180 minutes).
6063

6164
### Managing Multiple Systems
6265
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**.
@@ -72,4 +75,12 @@ This sensor tracks the exact date and time of the last successful HTTP 200 OK re
7275
---
7376

7477
## Troubleshooting & Logs
75-
If data is not appearing in PVOutput, check your Home Assistant logs (**Settings > System > Logs**). The integration will gracefully handle network drops, but will print detailed error messages if the PVOutput API rejects your payload (e.g., invalid API key, incorrect System ID, or pushing data too far in the past).
78+
If data is not appearing in PVOutput, check your Home Assistant logs (**Settings > System > Logs**). The integration gracefully handles network drops, but will print detailed error messages if the PVOutput API rejects your payload (e.g., invalid API key, incorrect System ID, or pushing data too far in the past). You can view the raw outbound payload by setting the logging level for `custom_components.pvoutput_publisher` to `info` in your `configuration.yaml`.
79+
80+
```yaml
81+
## Logging
82+
logger:
83+
default: warning
84+
logs:
85+
custom_components.pvoutput_publisher: debug
86+
```

‎TODO.md‎

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎custom_components/pvoutput_publisher/translations/de.json‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
{
2+
"config": {
3+
"step": {
4+
"user": {
5+
"title": "PVOutput Publisher Konfiguration",
6+
"description": "Geben Sie Ihren globalen PVOutput API-Schlüssel ein.",
7+
"data": {
8+
"api_key": "API-Schlüssel"
9+
}
10+
},
11+
"add_system": {
12+
"title": "System Konfigurieren",
13+
"description": "Wählen Sie die Sensoren für dieses System aus.",
14+
"data": {
15+
"name": "Systemname",
16+
"system_id": "System-ID",
17+
"entity_id": "Solarerzeugungs-Sensor",
18+
"consumption_entity_id": "Stromverbrauch-Sensor",
19+
"temperature_entity_id": "Temperatursensor",
20+
"frequency": "Aktualisierungsintervall"
21+
},
22+
"data_description": {
23+
"name": "Ein benutzerfreundlicher Name für Ihre Übersicht.",
24+
"consumption_entity_id": "(Optional) Erfasst den Energieverbrauch Ihres Hauses.",
25+
"temperature_entity_id": "(Optional) Erfasst die Außentemperatur."
26+
}
27+
},
28+
"systems_manager": {
29+
"title": "Systeme Verwalten",
30+
"description": "Wählen Sie eine Aktion zur Verwaltung Ihrer Anlagen aus.",
31+
"data": {
32+
"action": "Aktion"
33+
}
34+
}
35+
},
36+
"error": {},
37+
"abort": {
38+
"already_configured": "Diese Integration ist bereits konfiguriert."
39+
}
40+
},
41+
"options": {
42+
"step": {
43+
"systems_manager": {
44+
"title": "PVOutput Publisher Verwalten",
45+
"description": "Wählen Sie eine Aktion zur Aktualisierung Ihrer Einstellungen aus.",
46+
"data": {
47+
"action": "Aktion"
48+
}
49+
},
50+
"edit_api": {
51+
"title": "API-Schlüssel Bearbeiten",
52+
"data": {
53+
"api_key": "API-Schlüssel"
54+
}
55+
},
56+
"add_system": {
57+
"title": "System Konfigurieren",
58+
"data": {
59+
"name": "Systemname",
60+
"system_id": "System-ID",
61+
"entity_id": "Solarerzeugungs-Sensor",
62+
"consumption_entity_id": "Stromverbrauch-Sensor",
63+
"temperature_entity_id": "Temperatursensor",
64+
"frequency": "Aktualisierungsintervall"
65+
},
66+
"data_description": {
67+
"name": "Ein benutzerfreundlicher Name für Ihre Übersicht.",
68+
"consumption_entity_id": "(Optional) Erfasst den Energieverbrauch Ihres Hauses.",
69+
"temperature_entity_id": "(Optional) Erfasst die Außentemperatur."
70+
}
71+
}
72+
}
73+
}
74+
}

‎custom_components/pvoutput_publisher/translations/es.json‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
{
2+
"config": {
3+
"step": {
4+
"user": {
5+
"title": "Configuración de PVOutput Publisher",
6+
"description": "Introduzca su clave API global de PVOutput.",
7+
"data": {
8+
"api_key": "Clave API"
9+
}
10+
},
11+
"add_system": {
12+
"title": "Configurar Sistema",
13+
"description": "Seleccione los sensores para este sistema.",
14+
"data": {
15+
"name": "Nombre del Sistema",
16+
"system_id": "ID del Sistema",
17+
"entity_id": "Sensor de Generación Solar",
18+
"consumption_entity_id": "Sensor de Consumo Eléctrico",
19+
"temperature_entity_id": "Sensor de Temperatura",
20+
"frequency": "Frecuencia de Actualización"
21+
},
22+
"data_description": {
23+
"name": "Un nombre descriptivo para su propia referencia.",
24+
"consumption_entity_id": "(Opcional) Registra el uso de energía de su hogar.",
25+
"temperature_entity_id": "(Opcional) Registra la temperatura exterior."
26+
}
27+
},
28+
"systems_manager": {
29+
"title": "Gestionar Sistemas",
30+
"description": "Seleccione una acción para gestionar sus sistemas.",
31+
"data": {
32+
"action": "Acción"
33+
}
34+
}
35+
},
36+
"error": {},
37+
"abort": {
38+
"already_configured": "Esta integración ya está configurada."
39+
}
40+
},
41+
"options": {
42+
"step": {
43+
"systems_manager": {
44+
"title": "Gestionar PVOutput Publisher",
45+
"description": "Seleccione una acción para actualizar su configuración.",
46+
"data": {
47+
"action": "Acción"
48+
}
49+
},
50+
"edit_api": {
51+
"title": "Editar Clave API",
52+
"data": {
53+
"api_key": "Clave API"
54+
}
55+
},
56+
"add_system": {
57+
"title": "Configurar Sistema",
58+
"data": {
59+
"name": "Nombre del Sistema",
60+
"system_id": "ID del Sistema",
61+
"entity_id": "Sensor de Generación Solar",
62+
"consumption_entity_id": "Sensor de Consumo Eléctrico",
63+
"temperature_entity_id": "Sensor de Temperatura",
64+
"frequency": "Frecuencia de Actualización"
65+
},
66+
"data_description": {
67+
"name": "Un nombre descriptivo para su propia referencia.",
68+
"consumption_entity_id": "(Opcional) Registra el uso de energía de su hogar.",
69+
"temperature_entity_id": "(Opcional) Registra la temperatura exterior."
70+
}
71+
}
72+
}
73+
}
74+
}

‎custom_components/pvoutput_publisher/translations/ja.json‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
{
2+
"config": {
3+
"step": {
4+
"user": {
5+
"title": "PVOutput Publisher の設定",
6+
"description": "グローバル PVOutput API キーを入力してください。",
7+
"data": {
8+
"api_key": "API キー"
9+
}
10+
},
11+
"add_system": {
12+
"title": "システムの設定",
13+
"description": "このシステムをトラッキングするセンサーを選択してください。",
14+
"data": {
15+
"name": "システム名",
16+
"system_id": "システム ID",
17+
"entity_id": "太陽光発電センサー",
18+
"consumption_entity_id": "電力/エネルギー消費センサー",
19+
"temperature_entity_id": "温度センサー",
20+
"frequency": "更新頻度"
21+
},
22+
"data_description": {
23+
"name": "管理用のわかりやすい名前。",
24+
"consumption_entity_id": "(オプション) 自宅のエネルギー使用量を記録します。",
25+
"temperature_entity_id": "(オプション) 外気温を記録します。"
26+
}
27+
},
28+
"systems_manager": {
29+
"title": "システムの管理",
30+
"description": "以下からアクションを選択してアレイを管理します。",
31+
"data": {
32+
"action": "アクション"
33+
}
34+
}
35+
},
36+
"error": {},
37+
"abort": {
38+
"already_configured": "このインテグレーションはすでに設定されています。"
39+
}
40+
},
41+
"options": {
42+
"step": {
43+
"systems_manager": {
44+
"title": "PVOutput Publisher の管理",
45+
"description": "以下からアクションを選択して設定を更新してください。",
46+
"data": {
47+
"action": "アクション"
48+
}
49+
},
50+
"edit_api": {
51+
"title": "API キーの編集",
52+
"data": {
53+
"api_key": "API キー"
54+
}
55+
},
56+
"add_system": {
57+
"title": "システムの設定",
58+
"data": {
59+
"name": "システム名",
60+
"system_id": "システム ID",
61+
"entity_id": "太陽光発電センサー",
62+
"consumption_entity_id": "電力/エネルギー消費センサー",
63+
"temperature_entity_id": "温度センサー",
64+
"frequency": "更新頻度"
65+
},
66+
"data_description": {
67+
"name": "管理用のわかりやすい名前。",
68+
"consumption_entity_id": "(オプション) 自宅のエネルギー使用量を記録します。",
69+
"temperature_entity_id": "(オプション) 外気温を記録します。"
70+
}
71+
}
72+
}
73+
}
74+
}

0 commit comments

Comments
 (0)