demus/openhab-addons
1
0
Fork 0
mirror of https://github.com/openhab/openhab-addons.git synced 2025-01-25 14:55:55 +01:00
Code Issues Packages Projects Releases Wiki Activity
98ee2417af
openhab-addons/bundles/org.openhab.binding.solarman/README.md

291 lines
25 KiB
Markdown
Raw Normal View History

[solarman] Initial contribution (#16835) * Initial commit for the Solarman Binding. Signed-off-by: Catalin Sanda <catalin.sanda@gmail.com>
2024-07-30 23:46:28 +02:00
# Solarman Logger Binding
Binding used to communicate with Solarman (IGEN-Tech) v5 based solar inverter data loggers in direct-mode over the local network.
More information about the different types of stick loggers is available on the [Solarman](https://www.solarmanpv.com/products/data-logger/stick-logger/) site.
These data loggers are used by inverters from a lot of manufacturers, just to name a few:
- Deye
- Sofar
- Solis
- ZCS Azzurro
- KStar
## Supported Things
The `solarman:logger` thing supports reading data from a Solarman LSW-3 Stick Logger (it might also work with LSE-3 and maybe others) when connected to a supported inverter.
It was tested on a SUN-12K-SG04LP3-EU only, but because the implementation uses the inverter definitions created as part of Stephan Joubert's Home Assistant plugin it **might** work with the other inverters supported by the plugin.
## Thing Configuration
To connect the logger you need the IP address of the logger and its serial number.
The IP address can be obtained from your router and the serial number can either be read from the label of the logger, or by connecting to the logger with a browser (default user/pass: admin/admin) and getting it from the Status page.
*Please note* that you need the "Device serial number" from the "Device information" section, not the "Inverter serial number".
### `logger` Thing Configuration
| Name | Type | Description | Default | Required | Advanced |
|--------------------|---------|--------------------------------------------------------|---------|----------|----------|
| hostname | text | Hostname or IP address of the Solarman logger | N/A | yes | no |
| serialNumber | text | Serial number of the Solarman logger | N/A | yes | no |
| inverterType | text | The type of inverter connected to the logger | N/A | yes | no |
| port | integer | Port of the Solarman logger | 8899 | no | yes |
| refreshInterval | integer | Interval the device is polled in sec. | 60 | no | yes |
| additionalRequests | text | Additional requests besides the ones in the definition | N/A | no | yes |
The `inverterType` parameter governs what registers the binding will read from the logger and what channels it will expose.
Possible values:
| Inverter Type | Inverters supported | Notes |
|--------------------|---------------------------------------------|------------------------------------------------------------------|
| deye_hybrid | DEYE/Sunsynk/SolArk Hybrid inverters | used when no lookup specified |
| deye_sg04lp3 | DEYE/Sunsynk/SolArk Hybrid 8/12K-SG04LP3 | e.g. 12K-SG04LP3-EU |
| deye_string | DEYE/Sunsynk/SolArk String inverters | e.g. SUN-4/5/6/7/8/10/12K-G03 Plus |
| deye_2mppt | DEYE Microinverter with 2 MPPT Trackers | e.g. SUN600G3-EU-230 / SUN800G3-EU-230 / SUN1000G3-EU-230 |
| deye_4mppt | DEYE Microinverter with 4 MPPT Trackers | e.g. SUN1300G3-EU-230 / SUN1600G3-EU-230 / SUN2000G3-EU-230 |
| sofar_lsw3 | SOFAR Inverters | |
| sofar_g3hyd | SOFAR Hybrid Three-Phase inverter | HYD 6000 or rebranded (three-phase), ex. ZCS Azzurro 3PH HYD-ZSS |
| sofar_hyd3k-6k-es | SOFAR Hybrid Single-Phase inverter | HYD 6000 or rebranded (single-phase), ex. ZCS Azzurro HYD-ZSS |
| solis_hybrid | SOLIS Hybrid inverter | |
| solid_1p8k-5g | SOLIS 1P8K-5G | |
| zcs_azzurro-ktl-v3 | ZCS Azzurro KTL-V3 inverters | ZCS Azzurro 3.3/4.4/5.5/6.6 KTL-V3 (rebranded Sofar KTLX-G3) |
The `additionalRequests` allows the user to specify additional address ranges to be polled. The format of the value is `mb_functioncode1:start1-end1, mb_functioncode2:start2-end2,...`
For example `"0x03:0x27D-0x27E"` will issue an additional read for Holding Registers between `0x27D` and `0x27E`.
This is useful when coupled with user defined channels, for example a thing definition like the one below will also read the register for the AC frequency on a Deye inverter, besides the ones pre-defined in the `deye_sg04lp3` inverter definition.
```java
Thing solarman:logger:local [ hostname="x.x.x.x", inverterType="deye_sg04lp3", serialNumber="1234567890", additionalRequests="0x03:0x27D-0x27E" ] {
Channels:
Type number : Inverter_Frequency [scale="0.01", uom="Hz", rule="3", registers="0x27E"]
}
```
**Please note** As of this writing inverter types besides the `deye_sg04lp3` were not tested to work.
If you have one of those inverters and it works, please drop me a message, if it doesn't work, please open an issue and I'll try to fix it.
## Channels
The list of channels is not static, it is generated dynamically based on the inverter type selected.
This is the list you get for the `deye_sg04lp3` inverter type:
| Channel | Type | Read/Write | Description |
|------------------------------------------|--------|--------------|-------------------------------------------------------|
| alert-alert | Number | R | Alert \[0x0229,0x022A,0x022B,0x022C,0x022D,0x022E\] |
| battery-battery-current | Number | R | Battery Current \[0x024F\] |
| battery-battery-power | Number | R | Battery Power \[0x024E\] |
| battery-battery-soc | Number | R | Battery SOC \[0x024C\] |
| battery-battery-temperature | Number | R | Battery Temperature \[0x024A\] |
| battery-battery-voltage | Number | R | Battery Voltage \[0x024B\] |
| battery-daily-battery-charge | Number | R | Daily Battery Charge \[0x0202\] |
| battery-daily-battery-discharge | Number | R | Daily Battery Discharge \[0x0203\] |
| battery-total-battery-charge | Number | R | Total Battery Charge \[0x0204,0x0205\] |
| battery-total-battery-discharge | Number | R | Total Battery Discharge \[0x0206,0x0207\] |
| grid-daily-energy-bought | Number | R | Daily Energy Bought \[0x0208\] |
| grid-daily-energy-sold | Number | R | Daily Energy Sold \[0x0209\] |
| grid-external-ct-l1-power | Number | R | External CT L1 Power \[0x0268\] |
| grid-external-ct-l2-power | Number | R | External CT L2 Power \[0x0269\] |
| grid-external-ct-l3-power | Number | R | External CT L3 Power \[0x026A\] |
| grid-grid-voltage-l1 | Number | R | Grid Voltage L1 \[0x0256\] |
| grid-grid-voltage-l2 | Number | R | Grid Voltage L2 \[0x0257\] |
| grid-grid-voltage-l3 | Number | R | Grid Voltage L3 \[0x0258\] |
| grid-internal-ct-l1-power | Number | R | Internal CT L1 Power \[0x025C\] |
| grid-internal-ct-l2-power | Number | R | Internal CT L2 Power \[0x025D\] |
| grid-internal-ct-l3-power | Number | R | Internal CT L3 Power \[0x025E\] |
| grid-total-energy-bought | Number | R | Total Energy Bought \[0x020A,0x020B\] |
| grid-total-energy-sold | Number | R | Total Energy Sold \[0x020C\] |
| grid-total-grid-power | Number | R | Total Grid Power \[0x0271\] |
| grid-total-grid-production | Number | R | Total Grid Production \[0x020C,0x020D\] |
| inverter-ac-temperature | Number | R | AC Temperature \[0x021D\] |
| inverter-communication-board-version-no- | Number | R | Communication Board Version No \[0x0011\] |
| inverter-control-board-version-no- | Number | R | Control Board Version No \[0x000D\] |
| inverter-current-l1 | Number | R | Current L1 \[0x0276\] |
| inverter-current-l2 | Number | R | Current L2 \[0x0277\] |
| inverter-current-l3 | Number | R | Current L3 \[0x0278\] |
| inverter-dc-temperature | Number | R | DC Temperature \[0x021C\] |
| inverter-frequency | Number | R | Number Value \[0x27E\] |
| inverter-inverter-id | String | R | Inverter ID \[0x0003,0x0004,0x0005,0x0006,0x0007\] |
| inverter-inverter-l1-power | Number | R | Inverter L1 Power \[0x0279\] |
| inverter-inverter-l2-power | Number | R | Inverter L2 Power \[0x027A\] |
| inverter-inverter-l3-power | Number | R | Inverter L3 Power \[0x027B\] |
| solar-daily-production | Number | R | Daily Production \[0x0211\] |
| solar-pv1-current | Number | R | PV1 Current \[0x02A5\] |
| solar-pv1-power | Number | R | PV1 Power \[0x02A0\] |
| solar-pv1-voltage | Number | R | PV1 Voltage \[0x02A4\] |
| solar-pv2-current | Number | R | PV2 Current \[0x02A7\] |
| solar-pv2-power | Number | R | PV2 Power \[0x02A1\] |
| solar-pv2-voltage | Number | R | PV2 Voltage \[0x02A6\] |
| solar-total-production | Number | R | Total Production \[0x0216,0x0217\] |
| upload-daily-load-consumption | Number | R | Daily Load Consumption \[0x020E\] |
| upload-load-l1-power | Number | R | Load L1 Power \[0x028A\] |
| upload-load-l2-power | Number | R | Load L2 Power \[0x028B\] |
| upload-load-l3-power | Number | R | Load L3 Power \[0x028C\] |
| upload-load-voltage-l1 | Number | R | Load Voltage L1 \[0x0284\] |
| upload-load-voltage-l2 | Number | R | Load Voltage L2 \[0x0285\] |
| upload-load-voltage-l3 | Number | R | Load Voltage L3 \[0x0286\] |
| upload-total-load-consumption | Number | R | Total Load Consumption \[0x020F,0x0210\] |
| upload-total-load-power | Number | R | Total Load Power \[0x028D\] |
## Full Example
This is an example for a DEYE 12kW (SUN-12K-SG04LP3-EU) hybrid inverter
### `solarman.things`
Please replace the `hostname` and `serialNumber` with the correct values for your logger.
```java
Thing solarman:logger:local [hostname="x.x.x.x",inverterType="deye_sg04lp3",serialNumber="1234567890"]
```
### `solarman.items`
Items file example for a SUN-12K-SG04LP3-EU inverter
```text
Number:Dimensionless Communication_Board_Version_No "Communication Board Version No [%s]" (solarman) {channel="solarman:logger:local:inverter-communication-board-version-no-"}
Number:Dimensionless Control_Board_Version_No "Control Board Version No [%s]" (solarman) {channel="solarman:logger:local:inverter-control-board-version-no-"}
String Inverter_Id "Inverter Id [%s]" (solarman) {channel="solarman:logger:local:inverter-inverter-id"}
Number:Temperature AC_Temperature "AC Temperature [%.1f °C]" (solarman) {channel="solarman:logger:local:inverter-ac-temperature", unit="°C"}
Number:Temperature DC_Temperature "DC Temperature [%.1f °C]" (solarman) {channel="solarman:logger:local:inverter-dc-temperature", unit="°C"}
Number:Power Inverter_L1_Power "Inverter L1 Power [%d W]" (solarman) {channel="solarman:logger:local:inverter-inverter-l1-power", unit="W"}
Number:Power Inverter_L2_Power "Inverter L2 Power [%d W]" (solarman) {channel="solarman:logger:local:inverter-inverter-l2-power", unit="W"}
Number:Power Inverter_L3_Power "Inverter L3 Power [%d W]" (solarman) {channel="solarman:logger:local:inverter-inverter-l3-power", unit="W"}
Number:ElectricCurrent Current_L1 "Current L1 [%.1f A]" (solarman) {channel="solarman:logger:local:inverter-current-l1", unit="A"}
Number:ElectricCurrent Current_L2 "Current L2 [%.1f A]" (solarman) {channel="solarman:logger:local:inverter-current-l2", unit="A"}
Number:ElectricCurrent Current_L3 "Current L3 [%.1f A]" (solarman) {channel="solarman:logger:local:inverter-current-l3", unit="A"}
Number:Power External_CT_L1_Power "External CT L1 Power [%d W]" (solarman) {channel="solarman:logger:local:grid-external-ct-l1-power", unit="W"}
Number:Power External_CT_L2_Power "External CT L2 Power [%d W]" (solarman) {channel="solarman:logger:local:grid-external-ct-l2-power", unit="W"}
Number:Power External_CT_L3_Power "External CT L3 Power [%d W]" (solarman) {channel="solarman:logger:local:grid-external-ct-l3-power", unit="W"}
Number:Power Internal_CT_L1_Power "Internal CT L1 Power [%d W]" (solarman) {channel="solarman:logger:local:grid-internal-ct-l1-power", unit="W"}
Number:Power Internal_CT_L2_Power "Internal CT L2 Power [%d W]" (solarman) {channel="solarman:logger:local:grid-internal-ct-l2-power", unit="W"}
Number:Power Internal_CT_L3_Power "Internal CT L3 Power [%d W]" (solarman) {channel="solarman:logger:local:grid-internal-ct-l3-power", unit="W"}
Number:ElectricPotential Grid_Voltage_L1 "Grid Voltage L1 [%d V]" (solarman) {channel="solarman:logger:local:grid-grid-voltage-l1", unit="V"}
Number:ElectricPotential Grid_Voltage_L2 "Grid Voltage L2 [%d V]" (solarman) {channel="solarman:logger:local:grid-grid-voltage-l2", unit="V"}
Number:ElectricPotential Grid_Voltage_L3 "Grid Voltage L3 [%d V]" (solarman) {channel="solarman:logger:local:grid-grid-voltage-l3", unit="V"}
Number:Power Total_Grid_Power "Total Instant Grid Power [%d W]" (solarman) {channel="solarman:logger:local:grid-total-grid-power", unit="W"}
Number:Energy Total_Grid_Production "Total Grid Feed-in [%.1f kWh]" (solarman) {channel="solarman:logger:local:grid-total-grid-production", unit="kWh"}
Number:Energy Daily_Energy_Sold "Daily Energy Sold [%d Wh]" (solarman) {channel="solarman:logger:local:grid-daily-energy-sold", unit="Wh"}
Number:Energy Total_Energy_Sold "Total Energy Sold [%d kWh]" (solarman) {channel="solarman:logger:local:grid-total-energy-sold", unit="kWh"}
Number:Energy Total_Energy_Bought "Total Energy Bought [%d kWh]" (solarman) {channel="solarman:logger:local:grid-total-energy-bought", unit="kWh"}
Number:Energy Daily_Energy_Bought "Daily Energy Bought [%d kWh]" (solarman) {channel="solarman:logger:local:grid-daily-energy-bought", unit="kWh"}
Number:Energy Daily_Production "Daily Production [%.1f kWh]" (solarman) {channel="solarman:logger:local:solar-daily-production", unit="kWh"}
Number:Energy Total_Production "Total Production [%d kWh]" (solarman) {channel="solarman:logger:local:solar-total-production", unit="kWh"}
Number:Energy Daily_Load_Consumption "Daily Load Consumption [%.1f kWh]" (solarman) {channel="solarman:logger:local:upload-daily-load-consumption", unit="kWh"}
Number:Energy Total_Load_Consumption "Total Load Consumption [%d kWh]" (solarman) {channel="solarman:logger:local:upload-total-load-consumption", unit="kWh"}
Number:Power Load_L1_Power "Load L1 Power [%d W]" (solarman) {channel="solarman:logger:local:upload-load-l1-power", unit="W"}
Number:Power Load_L2_Power "Load L2 Power [%d W]" (solarman) {channel="solarman:logger:local:upload-load-l2-power", unit="W"}
Number:Power Load_L3_Power "Load L3 Power [%d W]" (solarman) {channel="solarman:logger:local:upload-load-l3-power", unit="W"}
Number:Power Total_Load_Power "Total Load Power [%d W]" (solarman) {channel="solarman:logger:local:upload-total-load-power", unit="W"}
Number:ElectricPotential Load_Voltage_L1 "Load Voltage L1 [%d V]" (solarman) {channel="solarman:logger:local:upload-load-voltage-l1", unit="V"}
Number:ElectricPotential Load_Voltage_L2 "Load Voltage L2 [%d V]" (solarman) {channel="solarman:logger:local:upload-load-voltage-l2", unit="V"}
Number:ElectricPotential Load_Voltage_L3 "Load Voltage L3 [%d V]" (solarman) {channel="solarman:logger:local:upload-load-voltage-l3", unit="V"}
Number:Energy Daily_Energy_Consumption "Daily Energy Consumption [%d kWh]" (solarman) {channel="solarman:logger:local:upload-daily-load-consumption", unit="kWh"}
Number:Energy Total_Energy_Consumption "Total Energy Consumption [%d kWh]" (solarman) {channel="solarman:logger:local:upload-total-load-consumption", unit="kWh"}
Number:ElectricCurrent PV1_Current "PV1 Current [%.1f A]" (solarman) {channel="solarman:logger:local:solar-pv1-current", unit="A"}
Number:Power PV1_Power "PV1 Power [%d W]" (solarman) {channel="solarman:logger:local:solar-pv1-power", unit="W"}
Number:ElectricPotential PV1_Voltage "PV1 Voltage [%d V]" (solarman) {channel="solarman:logger:local:solar-pv1-voltage", unit="V"}
Number:ElectricCurrent PV2_Current "PV2 Current [%.1f A]" (solarman) {channel="solarman:logger:local:solar-pv2-current", unit="A"}
Number:Power PV2_Power "PV2 Power [%d W]" (solarman) {channel="solarman:logger:local:solar-pv2-power", unit="W"}
Number:ElectricPotential PV2_Voltage "PV2 Voltage [%d V]" (solarman) {channel="solarman:logger:local:solar-pv2-voltage", unit="V"}
Number:Dimensionless Battery_SOC "Battery SOC [%d %%]" (solarman) {channel="solarman:logger:local:battery-battery-soc", unit="%"}
Number:ElectricCurrent Battery_Current "Battery Current [%.1f A]" (solarman) {channel="solarman:logger:local:battery-battery-current", unit="A"}
Number:Power Battery_Power "Battery Power [%d W]" (solarman) {channel="solarman:logger:local:battery-battery-power", unit="W"}
Number:ElectricPotential Battery_Voltage "Battery Voltage [%.2f V]" (solarman) {channel="solarman:logger:local:battery-battery-voltage", unit="V"}
Number:Temperature Battery_Temperature "Battery Temperature [%.1f °C]" (solarman) {channel="solarman:logger:local:battery-battery-temperature", unit="°C"}
Number:Energy Daily_Battery_Charge "Daily Battery Charge [%.1f kWh]" (solarman) {channel="solarman:logger:local:battery-daily-battery-charge", unit="kWh"}
Number:Energy Daily_Battery_Discharge "Daily Battery Discharge [%.1f kWh]" (solarman) {channel="solarman:logger:local:battery-daily-battery-discharge", unit="kWh"}
Number:Energy Total_Battery_Charge "Total Battery Charge [%d kWh]" (solarman) {channel="solarman:logger:local:battery-total-battery-charge", unit="kWh"}
Number:Energy Total_Battery_Discharge "Total Battery Discharge [%d kWh]" (solarman) {channel="solarman:logger:local:battery-total-battery-discharge", unit="kWh"}
Number Alert "Alert [%s]" (solarman) {channel="solarman:logger:local:alert-alert"}
```
### `solarman.sitemap`
Sitemap example for a SUN-12K-SG04LP3-EU inverter
```perl
sitemap solarman label="Solarman"
{
Frame label="Inverter"{
Text item=Communication_Board_Version_No icon="solar"
Text item=Control_Board_Version_No icon="solar"
Text item=Inverter_Id icon="solar"
Text item=AC_Temperature icon="temperature"
Text item=DC_Temperature icon="temperature"
Text item=Inverter_L1_Power icon="poweroutlet"
Text item=Inverter_L2_Power icon="poweroutlet"
Text item=Inverter_L3_Power icon="poweroutlet"
Text item=Current_L1 icon="line"
Text item=Current_L2 icon="line"
Text item=Current_L3 icon="line"
}
Frame label="Battery"{
Text item=Battery_SOC icon="battery"
Text item=Battery_Current icon="current"
Text item=Battery_Power icon="power"
Text item=Battery_Voltage icon="voltage"
Text item=Battery_Temperature icon="temperature"
Text item=Daily_Battery_Charge icon="renewable"
Text item=Daily_Battery_Discharge icon="battery"
Text item=Total_Battery_Charge icon="renewable"
Text item=Total_Battery_Discharge icon="battery"
}
Frame label="Solar"{
Text item=Total_Production icon="solar"
Text item=Daily_Production icon="solar"
Text item=PV1_Current icon="solar"
Text item=PV1_Power icon="solar"
Text item=PV1_Voltage icon="solar"
Text item=PV2_Current icon="solar"
Text item=PV2_Power icon="solar"
Text item=PV2_Voltage icon="solar"
}
Frame label="Grid"{
Text item=Total_Grid_Production icon="power"
Text item=Total_Grid_Power icon="power"
Text item=External_CT_L1_Power icon="power"
Text item=External_CT_L2_Power icon="power"
Text item=External_CT_L3_Power icon="power"
Text item=Internal_CT_L1_Power icon="power"
Text item=Internal_CT_L2_Power icon="power"
Text item=Internal_CT_L3_Power icon="power"
Text item=Grid_Voltage_L1 icon="power"
Text item=Grid_Voltage_L2 icon="power"
Text item=Grid_Voltage_L3 icon="power"
Text item=Daily_Energy_Sold icon="power"
Text item=Total_Energy_Sold icon="power"
Text item=Daily_Energy_Bought icon="power"
Text item=Total_Energy_Bought icon="power"
}
Frame label="Load"{
Text item=Daily_Load_Consumption icon="power"
Text item=Total_Load_Consumption icon="power"
Text item=Load_L1_Power icon="power"
Text item=Load_L2_Power icon="power"
Text item=Load_L3_Power icon="power"
Text item=Load_Voltage_L1 icon="power"
Text item=Load_Voltage_L2 icon="power"
Text item=Load_Voltage_L3 icon="power"
Text item=Total_Load_Power icon="power"
}
Frame label="Alert"{
Text item=Alert icon="alert"
}
}
```
## Acknowledgments
The code's creation draws significant inspiration from [Stephan Joubert's Home Assistant plugin](https://github.com/StephanJoubert/home_assistant_solarman), which provides the inverter definitions used in the project.
Additionally, the [pysolarmanv5 module](https://pysolarmanv5.readthedocs.io/en/latest/index.html) was a valuable resource, as it offers an excellent explanation of the Solarman V5 protocol.
Reference in New Issue Copy Permalink