Skip to content

Commit

Permalink
Initial README.md
Browse files Browse the repository at this point in the history 
Signed-off-by: Konstantin Polihronov <polychronov@gmail.com>
  • Loading branch information
@theater
theater committed Jun 21, 2023
1 parent db6e9ab commit cf46ddf
Show file tree
Hide file tree
Showing 2 changed files with 70 additions and 44 deletions.
112 changes: 69 additions & 43 deletions bundles/org.openhab.binding.solax/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,69 +1,95 @@
# solax Binding
# Solax Binding

_Give some details about what this binding is meant for - a protocol, system, specific device._
This is a OpenHAB binding for a Solax Wi-fi modules that have the option to be connected directly via HTTP (firmware version 3.x+).
Please note that earlier firmware releases do not support direct connection.

_If possible, provide some resources like pictures (only PNG is supported currently), a video, etc. to give an impression of what can be done with this binding._
_You can place such resources into a `doc` folder next to this README.md._
Currently the Solax cloud services provide an update on every 5 minutes (sometimes even more) and they also happen to be down sometimes, which makes it hard to automate the decision making by OpenHAB if we have more complex rules.

_Put each sentence in a separate line to improve readability of diffs._
For example: I want to charge my car if the battery of my inverter is 90%+ and my overall consumption is only from the solar power.
The binding retrieves structured data from the wifi module, parses it and pushes it into the inverter thing where each channel represents a specific information (inverter output power, voltage, PV1 power, etc)

## Supported Things

_Please describe the different supported things / devices including their ThingTypeUID within this section._
_Which different types are supported, which models were tested etc.?_
_Note that it is planned to generate some part of this based on the XML files within ```src/main/resources/OH-INF/thing``` of your binding._
Hostname/IP address of the wi-fi module (can be any IP address from internal DHCP wi-fi network) [String]
The serial number of the Wi-fi module is the default password (not sure if it can be changed) [String]
Time interval to poll the data from the module [number in seconds]
Please give it a try and provide me a feedback if it works for you. I will update the releases as soon as I implement some of the backlog.
## Supported Things

- `bridge`: Short description of the Bridge, if any
- `sample`: Short description of the Thing with the ThingTypeUID `sample`
| Thing | Thing Type | Description |
|-------------------|------------|-------------------------------------------------------------------------------|
| localConnect | Bridge | The bridge is used to communicate directly to the wifi module of the inverter.|
| inverter | Thing | This is model representation of inverter with all the data available as a channels (Ex. inverter output power, voltage, PV1 power, etc) |

## Discovery

_Describe the available auto-discovery features here._
_Mention for what it works and what needs to be kept in mind when using it._
Discovery is available. Once the localConnect bridge is configured with the necessary parameters, it can discover automatically the inverter with all it's channels as a separate thing.

## Binding Configuration
## Thing Configuration

_If your binding requires or supports general configuration settings, please create a folder ```cfg``` and place the configuration file ```<bindingId>.cfg``` inside it._
_In this section, you should link to this file and provide some information about the options._
_The file could e.g. look like:_
### Local Connect Bridge parameters

```
# Configuration for the solax Binding
#
# Default secret key for the pairing of the solax Thing.
# It has to be between 10-40 (alphanumeric) characters.
# This may be changed by the user for security reasons.
secret=openHABSecret
```
| Parameter | Description |
|-------------------|----------------------------------------|
| refresh | Value is in seconds. Defines the refresh interval when the binding polls from the inverter's wifi module. Optional parameter. Default 10 seconds. |
| password | Password for accessing the Wifi module (the serial number of the wifi). Mandatory parameter. |
| hostname | IP address or hostname of your Wifi module. If hostname is used must be resolvable by OpenHAB. Mandatory parameter. |

_Note that it is planned to generate some part of this based on the information that is available within ```src/main/resources/OH-INF/binding``` of your binding._
The bridge does not have any channels. It is used only to connect to the module and retrieve the data. The data is shown in the Inverter thing

_If your binding does not offer any generic configurations, you can remove this section completely._
### Inverter Thing Configuration

## Thing Configuration
### Inverter Output Channels

| Channel | Type | Description |
|--------------------------|----------------------------|-------------------------------------------------------------------------------------------|
| inverterOutputPower | system.electric-power | The output power of the inverter [W] |
| inverterCurrent | system.electric-current | The output current of the inverter [A] |
| inverterVoltage | system.electric-voltage | The output voltage of the inverter [V] |
| inverterFrequency | Number:ElectricPotential | The frequency of the output voltage [Hz] |

### Photovoltaic Panels Production Channels

| Channel | Type | Description |
|--------------------------|----------------------------|----------------------------------------|
| pv1Voltage | system.electric-voltage | The voltage of PV1 string [V] |
| pv2Voltage | system.electric-voltage | The voltage of PV2 string [V] |
| pv1Current | system.electric-current | The current of PV1 string [A] |
| pv2Current | system.electric-current | The current of PV2 string [A] |
| pv1Power | system.electric-power | The output power PV1 string [W] |
| pv2Power | system.electric-power | The output power PV2 string [W] |
| pvTotalPower | system.electric-power | The total output power of both PV strings [W] |
| pvTotalCurrent | system.electric-current | The total current of both PV strings [A] |

### Battery channels

_Describe what is needed to manually configure a thing, either through the UI or via a thing-file._
_This should be mainly about its mandatory and optional configuration parameters._
| Channel | Type | Description |
|--------------------------|----------------------------|------------------------------------------------------------------------------------------------|
| batteryPower | system.electric-power | The power to / from battery (negative means power is pulled from battery and vice-versa) [W] |
| batteryCurrent | system.electric-current | The current to / from battery (negative means power is pulled from battery and vice-versa) [A] |
| batteryVoltage | system.electric-voltage | The voltage of the battery [V] |
| batteryTemperature | Number:Temperature | The temperature of the battery [C/F] |
| batteryStateOfCharge | system.battery-level | The state of charge of the battery [%] |

_Note that it is planned to generate some part of this based on the XML files within ```src/main/resources/OH-INF/thing``` of your binding._
### Grid related channels

### `sample` Thing Configuration
| Channel | Type | Description |
|--------------------------|----------------------------|------------------------------------------------------------------------------------------------|
| feedInPower | system.electric-power | The power to / from grid (negative means power is pulled from the grid and vice-versa) [W] |
| onGridTotalYield* | system.electric-power | Total Yield from PV strings [W] |
| onGridDailyYield* | system.electric-power | The power to / from grid (negative means power is pulled from the grid and vice-versa) [W] |
| onTotalFeedinEnergy* | system.electric-power | The power to / from grid (negative means power is pulled from the grid and vice-versa) [W] |
| onTotalFeedinEnergy* | system.electric-power | The power to / from grid (negative means power is pulled from the grid and vice-versa) [W] |

| Name | Type | Description | Default | Required | Advanced |
|-----------------|---------|---------------------------------------|---------|----------|----------|
| hostname | text | Hostname or IP address of the device | N/A | yes | no |
| password | text | Password to access the device | N/A | yes | no |
| refreshInterval | integer | Interval the device is polled in sec. | 600 | no | yes |
_* experimental channels. So far the data does not seem reliable. Either it's taken from wrong source of the JSON or it's calculated wrong in the inverter._

## Channels

_Here you should provide information about available channel types, what their meaning is and how they can be used._
### Properties

_Note that it is planned to generate some part of this based on the XML files within ```src/main/resources/OH-INF/thing``` of your binding._
| Property | Description |
|-------------------|-------------------------------------------|
| serialWifi | The wifi module's serial number |
| inverterType | Inverter Type (for example X1_HYBRID_G4) |

| Channel | Type | Read/Write | Description |
|---------|--------|------------|-----------------------------|
| control | Switch | RW | This is the control channel |

## Full Example

Expand Down
2 changes: 1 addition & 1 deletion bundles/org.openhab.binding.solax/src/main/resources/OH-INF/thing/inverter.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@
<channel id="onGridTotalYield" typeId="system.electric-power"/>
<channel id="onGridDailyYield" typeId="system.electric-power"/>
<channel id="onTotalFeedinEnergy" typeId="system.electric-power"/>
<channel id="onTotalConsumption" typeId="system.electric-power"/>
<channel id="onTotalFeedinEnergy" typeId="system.electric-power"/>
</channels>

<properties>
Expand Down

0 comments on commit cf46ddf

Please sign in to comment.