sermatec-opensource / sermatec-inverter Goto Github PK

View Code? Open in Web Editor NEW

4.0 6.0 2.0 766 KB

LAN communication docs and scripts for the Sermatec solar inverter.

License: MIT License

Python 99.67% Dockerfile 0.10% Shell 0.22%

protocol solar solar-inverter sermatec

sermatec-inverter's Introduction

Sermatec Solar Inverter

🚧🚧🚧 NOTICE: currently a big refactoring is in progress. Use master version only for testing. 🚧🚧🚧

This repository contains local API documentation for the Sermatec solar inverter and communication scripts.

Whole communication with the inverter runs through the UART-TCP converter USR-WIFI232-B2, which supports 802.11 b/g/n. It works either in a station mode (for connection to the home AP) or in a access point mode (local connection mode in the official ap). See docs below for more technical information.

Index

Generic contribution guide

If you want to contribute, please check the guidelines first: CONTRIBUTING.md.

Reverse-engineering (development) guides

If you want to help with decoding the proprietary Sermatec protocol, choose if you want to use the physical Android device or a virtual one and continue with the appropriate guide.

RE_AVD.md: Android virtual device configuration.
RE_PHYSICAL_DEVICE.md: Physical device configuration.
RE_DATA_INSPECTION.md: Data inspection guide.

Inverter and protocol docs

PROTOCOL.md: protocol documentation.

Console interface usage

The script takes very few args to run:

the ip of your inverter.
operation to do
- get: retrieve data from inverter, must be followed by type of data:
  - systemInformation, batteryStatus, gridPVStatus, runningStatus, workingParameters, load, bmsStatus
- customget: sent custom query command, must be followed by command code (single byte, decimal or hex):
  - e.g. 0x98
  - use with care, may cause unexpected/dangerous behaviour
- set: set configuration data
  - experimental support, may be dangerous and screw things up,
  - syntax: set <tag> <value>,
  - see section Configurable parameters for supported parameters and their allowed values,
  - some parameters require to shut down the inverter before configuring,
  - the script should refuse setting of invalid values, but either way, be very VERY careful.

The script also takes few optional args:

the -v flag to have a verbose output.
the --port arg to use a different port than default 8899 for inverter connection.
the -h or --help flag to display the help about the command
the --raw arg to not parse a response from the inverter (only raw data will be shown, useful for debugging, testing and development)
the --protocolFilePath arg to supply a custom path to JSON describing the protocol. Usually not needed.

Examples

Having battery info on an inverter with 10.0.0.254 ip:

python3 -m src.sermatec_inverter 10.0.0.254 get batteryStatus

Having grid info using the verbose mode with a 192.168.0.254 inverter with port 8900:

python3 -m src.sermatec_inverter -v --port=8900 192.168.0.254 get gridPVStatus

Configurable parameters

Tag	Description	Supported values	Inverter has to be shut down
`onOff`	Turn inverter on or off.	1: on, 0: off	no
`operatingMode`	Change inverter operating mode.	"General Mode", "Energy Storage Mode", "Micro-grid", "Peak-Valley", "AC Coupling"	no
`antiBackflow`	Enable backflow protection.	1: on, 0: off	yes
`soc`	Change lower-limit of on-grid battery SOC	10-100	no

Download

Newest version: Source

git clone https://github.com/andreondra/sermatec-inverter.git
cd sermatec-inverter
python3 -m src.sermatec_inverter --help

Docker / Docker-compose:

This method require to have both docker and docker compose setup on your computer (docker compose is now embedded officially when you install docker). Refer to this official documentation to have it installed.

Once done: you can use the docker-compose to run the app in a controlled environment:

git clone https://github.com/andreondra/sermatec-inverter.git
cd sermatec-inverter
docker compose run python-bash

Once the container started, you'll be in a bash environment with all your need for working and running the script:

python3 -m sermatec_inverter --help

Stable version: PyPI package

pip install sermatec-inverter
python3 -m sermatec_inverter --help

License

The project is licensed under the MIT License. (C) Ondrej Golasowski

sermatec-inverter's People

Contributors

Stargazers

Watchers

Forkers

mathieupotier jawadhalabimtb

sermatec-inverter's Issues

Add checksum information to the protocol docs

Like a server?

Hello,

A few days ago I used tcpdump and noticed that the inverter tries every second to connect to the client's IP on tcp/port 18899.

My assumption is that for debugging purposes, the developers "simulate" the server on their local connection and that this connection attempt exists for all connected IPs.

Does anyone have a tcpdump file with actual data they could send me? I do not have a connection with a European or Chinese serer on my inverter.

Another question, does anyone have firmware files or could tell me where I can find them? I have a old one "PCU5KSL_412.bin".

THANKS.

Add hex type support in protocol parser

Document a development using AVD

There is now a possibility to use an Android emulator (thus eliminating the need of a compatible rooted Android device). The only requirement is that the inverter's server is reachable at 10.10.100.254, which is the only address the official app can use (it cannot be changed). There are many ways to achieve that, the obvious one is the direct connection to the inverter in the AP mode, which is not always possible (inverter too far from the development machine running the Android emulator etc.). The way I use is bridging the inverter's network to the main network; for that you will need a router/AP/other network device which supports switching the wlan card to the station mode.

This method shall be documented in the near future, when I have enough time to do so.

`0C` command different when powered off

If the inverter is powered off, the 0C command response is shorter, this needs to be investigated.

Grid power down does not work as expected

Oh yeah, good ol Sermatec and their horrible naming. Need to find the correct sensor.

Fix 95, 9D commands

As a response to 95 query, the inverter actually returns two packets containing 95 and 9D. __sendQuery function will have to be fixed.

Add dry run to the protocol parser

The protocol parser should work even without data to generate list of supported sensors/actions. This is required by sermatec-opensource/homeassistant-sermatec-inverter#38

Add listing of all supported commands with names

Add support for onePosition field type

Low priority, not needed for now

Figure out the checksum function

Before this issue is resolved, we cannot reliably send parameter changes to the inverter.

Try to query data multiple times

Process protocol.json

A file describing whole protocol was found - it can't be published in its original form but it will probably help to implement the rest of the protocol without a need of a packet sniffing.

Translate from Chinese
Verify the information in the file
~~Rewrite the information from the file to the documentation~~
(future issues) Implement

Represent single-bit values as binary sensors

Add translation to field values as well

e.g. battery names, same treatment as with sensor names --> lookup in csv

Create protocol docs generator

Because we know have a self-supporting protocol.json, we are able to generate a Markdown documentation automatically.

We can use this lib.

Fix error when received data is too small

  File "/home/golas/Repos/sermatec-inverter/src/sermatec_inverter/protocol_parser.py", line 239, in parseReply
    newField["value"] = int(binString[fieldBitPosition])
                            ~~~~~~~~~^^^^^^^^^^^^^^^^^^
IndexError: string index out of range

Create protocol.json parser

This new class will be able to load all the information from the protocol.json.

We can get the inverter's software version (command 98, which is available on every inverter's SW version) and then decide which commands will be available in the script for the particular version. There are version keys in the recent protocol.json files, so I suppose they were added for a backward compatibility with non-updated inverters.

~~This can probably be a separate PyPI module to provide an independent parsing library.~~ not now

Expected features:

if no tag is provided in the protocol, we should create the tag from the name,
load error code from relevant files and replace the codes with strings

Add parameter configuration functions

For the preliminary support, ability to configure these will suffice:

Power on/off
lower battery SOC limit
Operating mode
Anti-backflow function on/off

Add checksum calculation

Now we can calculate the checksum, instead copying it from the protocol. This means we will be soon able to send configuration command 0x66.

Ignore unnecessary stuff in protocol.json

e.g. the how_many_sets_of_data_are_there

Move integrity checks from parsing function

Received data should be checked by the __sendCommandAndReceiveData, not by parsing functions (getBatteryInfo etc.).

Double check all raised exceptions and their handling

Cleanup

Clean old code (used when no protocol JSON was available)

Add console interface (when running as a script)

Use argparse module.

Unify addressing in protocol docs - start from zero

As for now, addresses in the request/response docs are indexed from the start of the data (including the header). Now when the structure of the protocol is known and it is always same for every request and response, we can start documenting only the request/response payload, thus eliminating redundancy.

Add unit parsing to protocol parser

Add nice output for not silent mode

If the script output is set to human-readable, the json data should be formatted accordingly

Added default value to protocolFilePath in Sermatec constructor

This will be handy for usage with homeassistant integration

sth like (Path(__file__).parent / "protocol-en.json").absolute()

Fix units in protocol json

The goal is to be compatible with home assistant, also it is a good idea to use SI units wherever applicable

Add friendly_name key

This name should be extracted from CSV files mentioned in #42

Add parsing for fields with known meanings

For now, I will edit the protocol.json and add custom keys indicating that the field is parsable. However, better idea may be to identify these fields using names, which should be unique?

Add backup load value support

Note: It is required to shut off the circuit breaker to force the inverter to run in a backup mode.

[improvment] trying to send a request when not connected should raise an exception

Hi,

https://github.com/andreondra/sermatec-inverter/blob/5f23bc843e42ab281610316e8df63fefad561614/src/sermatec_inverter/__init__.py#L45

Trying to send a request when not connected should raise an exception.
There is no difference between bad checksum and not connected behavior.

Document a development using AVD

There is now a possibility to use an Android emulator (thus eliminating the need of a compatible rooted Android device). The only requirement is that the inverter's server is reachable at 10.10.100.254, which is the only address the official app can use (it cannot be changed). There are many ways to achieve that, the obvious one being the direct connection to the inverter in the AP mode, which is not always possible (inverter too far from the development machine running the Android emulator etc.). The way I use is bridging the inverter's network to the main network; for that you will need a router/AP/other network device which supports switching the wlan card to the station mode.

This method shall be documented in the near future, when I have enough time to do so.

Extend generateRequest with payload possibility

The function should also calculate message length correctly.

Add more translations

Now, as the multi-language functionality is implemented, more translations can be created. If you are interesting in creating translation for any language, refer to the CONTRIBUTING.md file in the repo's root.

Add language param to cmdline interface

For now the language can be only selected by directly using Sermatec class, not via built-in cmdline interface. New optional param like --lang should be added. Supported options can be enumerated by listing csv file names in translations folder.

Tracking of supported and planned commands

Query

Setting

0x64: Set inverter state (on/off)
0x66: Set operating modes

Add sensor names translations

There should be a separate CSV for every language in this format: "key";"translation". This will be handy for usage with Home Assistant.

Example:
en.csv
"grid_voltage_frequency";"Grid Frequency"
cs.csv
"grid_voltage_frequency";"Frekvence sítě"

Add tests

implement a mock server to allow automatic testing,
implement some integration tests to test against real inverter.

Details: use unittest and maybe tox.

Add possibility to send any command (raw mode)

The script should check if the inverter is compatible (version in 0x98), if not, decline (add bypass possibility with some flag --disable-checks).

Change hardcoded reply keys to ones got from protocol_parser

Add device class? (To use with home assistant)

sermatec-ess

Hello alls,

I think my work about a full CLI and MQTT proxy using protocol.json is near production ready. Is someone want to test?

I was happy to be able to contribute.

If you want to add my MIT code to "sermatec-opensource", you can.

Have a nice day.

Move irrelevant parts to docs

Everything about reverse-engineering and protocol

Add silent/quiet mode

Suppress all message except output (to make output easy to integrate with other scripts)

Use a docker container to run the script in dev purpose

Hi,

I think that taking advantage of docker in order to run the script in a fully under control environment, instead of running directly from your computer python install, that could be different from a computer to another.

It could avoid the "it works on my computer" effect.

I know pretty well docker, that's why I suggest this, but I know that python have is own system venv but I'm not confident with it...

What do you think about it ?

Create protocol.json preprocessor

This script should preprocess the protocol.json as described in this comment. The main goal is to create a self-supporting all-containing file that will be used to generate docs and available commands in the communication script.

The main things to be processed/added are:

translation of the comments
tags
- they should be unique, so we can use them e.g. in Home Assistant integration,
- they should also follow the current snake_case format (grid_frequency, battery_max_charging_current, ...)
units - e.g. there should be % in the battery SOC and SOH

All stuff should be pulled from the CSV or similar file as it is here.

I essentially target at expanding a functionality of the existing bash script. Because it will be needed only in preprocessing, it can remain coded in bash or we can create a Python script.

@sbechet If you are interested in expanding your script, it would be wonderful! 😄. Otherwise I'll look into it myself.