You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 233e97f
Browse filesBrowse the repository at this point in the historyBrowse files
# lumentreeHA — Home Assistant Lumentree Solar Inverter Integration
1
+
# lumentreeHA — Home Assistant Lumentree Solar Inverter Integration
2
2
3
3
HACS custom integration for Lumentree hybrid solar inverters. Real-time MQTT monitoring, energy statistics, battery management, PV power tracking. MIT licensed.
-**Naming**: Follow HA conventions — snake_case files, PascalCase classes
60
-
-**Types**: All new code must have type hints. Pydantic models in `models/` for data structures.
61
-
-**Anti-patterns**: Avoid blocking calls in async context. Use `async_add_executor_job` for MQTT operations.
58
+
-**Naming**: Follow HA conventions — snake_case files, PascalCase classes
59
+
-**Types**: All new code must have type hints.
60
+
-**Anti-patterns**: Avoid blocking calls in async context. Use `async_add_executor_job` for any file or network I/O — coordinators, the API client and the MQTT client all do.
61
+
-**Anti-patterns**: Never call a vendor write endpoint (`bind device`, `register`, `upSnAddress`, `setRemarkName`, `delDevice`, `device/sendMsg`). `iot_class: cloud_polling` means read-only Tier 1 only.
62
62
-**Translation**: All user-facing strings in `strings.json`, no hardcoded English in entities.
63
63
64
64
## MQTT Topic Structure
65
65
66
+
Two topics per inverter, both built in `const.py` and formatted in `core/mqtt_client.py`:
67
+
66
68
```
67
-
lumentree/{serial_number}/pv/input1/power
68
-
lumentree/{serial_number}/pv/input1/voltage
69
-
lumentree/{serial_number}/battery/power
70
-
lumentree/{serial_number}/battery/soc
71
-
lumentree/{serial_number}/grid/power
72
-
lumentree/{serial_number}/load/power
73
-
lumentree/{serial_number}/energy/total
74
-
...
69
+
reportApp/{device_sn} # subscribe — the device publishes its Modbus-RTU frame here
70
+
listenApp/{device_sn} # publish — the integration sends read commands here
75
71
```
76
72
73
+
The payload is a hex-encoded Modbus-RTU frame, not JSON, and there is no per-metric topic tree.
74
+
See [docs/api/REGISTER_MAP.md](docs/api/REGISTER_MAP.md) for the register layout.
75
+
77
76
## HACS
78
77
79
78
-`hacs.json` at root, `manifest.json` for HA metadata
80
79
- Version tracked via GitHub Releases (semantic versioning)
81
-
- HA >= 2024.3.0 required
80
+
- Effective HA floor is **2024.4**, not the `2023.1.0` declared in `hacs.json`: `config_flow.py` does a runtime `from homeassistant.config_entries import ConfigFlowResult`, and that symbol only exists from 2024.4. On 2023.1–2024.3 the integration installs and then fails at setup.
81
+
- Python 3.11+ (`asyncio.timeout` in the coordinators).
- Saved (kWh) and Savings (VND) as state attributes
57
59
-**Daily arrays** for month-view charts (1-31 days)
58
60
59
61
### Yearly Statistics
60
-
-9 metrics with **monthly arrays** for year-view charts (1-12 months)
62
+
-7 metrics with **monthly arrays** for year-view charts (1-12 months)
61
63
- Historical data across multiple years via disk cache
62
64
63
65
### Lifetime/Total Statistics
@@ -75,8 +77,8 @@ High-performance **Home Assistant custom integration** for **Lumentree hybrid so
75
77
76
78
## Requirements
77
79
78
-
-**Home Assistant**: 2023.1+
79
-
-**Python**: 3.9+
80
+
-**Home Assistant**: 2024.4+ (`config_flow.py` imports `ConfigFlowResult`, added in 2024.4; `hacs.json` still declares `2023.1.0`)
81
+
-**Python**: 3.11+ (the coordinators use `asyncio.timeout`, added in 3.11; the parser and sensor modules also annotate signatures with `X | None` without `from __future__ import annotations`, which Python 3.9 evaluates at import time and rejects)
| Power | PV1, PV2, PV Total, Battery, Grid, Load, AC Output, AC Input, Total Load |
114
-
| Voltage | Battery, PV1, PV2, Grid, AC Output, AC Input |
115
-
| Current | Battery |
115
+
| Power | PV Power, PV1, PV2, Battery, Grid, Load, Total Load, AC Output, AC Input, Apparent Power, Generator, CT Trickle Feed |
116
+
| Voltage | Battery, PV1, PV2, Grid, AC Output, AC Input, Equalizing/Boost/Float Charge Voltage, Battery Low Voltage Protection, Battery Recovery Voltage |
117
+
| Current | Battery, AC Input, AC Output, Battery Maximum Charge Current, Maximum Discharge Current |
| Info | Device Temperature, MQTT Device SN, Battery Cell Info |
120
+
| Status | Battery SOC (%), Battery Status, Grid Status, Battery Type, UPS Mode, Master/Slave, AI Mode, Self-Consumption Ratio |
121
+
| Setting (diagnostic) | Battery Capacity, Low Capacity Cutoff Point, Protecting Recovery Point, Equalizing Charge Interval, Equalizing Charge Time, Grid Type, AC Output Frequency Setting, Charge From AC, AC Coupling |
122
+
| Info (diagnostic) | Device Temperature, Work Mode, Battery Mode, Firmware Version, Controller Version, Battery Cell Info, MQTT Device SN |
123
+
124
+
Seven real-time sensors ship disabled by default (PV1/PV2 power and voltage, AC Input Voltage, MQTT Device SN, Last Raw MQTT Hex); enable them in the entity registry if you need them. The voltage, current and setting entities stay `unknown` on units that answer with the shorter common frame, rather than reporting a fabricated value. See [docs/api/REGISTER_MAP.md](docs/api/REGISTER_MAP.md).
119
125
120
126
### Statistics Sensors (28 entities)
121
127
| Period | Metrics | Refresh |
122
128
|--------|---------|---------|
123
129
| Daily (7) | PV, Charge, Discharge, Grid, Load, Essential, Total Load | 5 min |
124
-
| Monthly (7) | Same + Saved (kWh) + Savings (VND)| 5 min |
125
-
| Yearly (7) | Same + monthly arrays for charting | 5 min |
130
+
| Monthly (7) | Same as Daily| 5 min |
131
+
| Yearly (7) | Same, plus monthly arrays as attributes for charting | 5 min |
126
132
| Total (7) | Lifetime cumulative sums | 5 min |
127
133
134
+
Saved energy (kWh) and cost savings (VND) are exposed as state attributes on the statistics sensors, not as separate entities.
0 commit comments