Async Python 3 library to read ModBus from an AlphaESS inverter. Tested and assumes using a Raspberry Pi as the host for RTU.
Uses asynciominimalmodbus for ModBus/RS485 RTU communication. Uses pymodbys for Modbus TCP communication.
See alphaess_collector which uses this library to store values in MySQL.
Compatible with RTU:
Device | Baud | Tested |
---|---|---|
SMILE5 | 9600 | ✅ |
SMILE-B3 | 9600 | |
SMILE-T10 | 9600 | |
Storion T30 | 19200 |
More information (and pictures) in the Notes section below.
- Use the inverter menu to enable modbus in slave mode.
- Snip one end of an ethernet cable off and connect (may vary):
- Blue/white to RS485 A
- Blue to RS485 B
- RS485 RX to GPIO 15
- RS485 TX to GPIO 14
- Enable serial port on Raspberry Pi with
raspi-config
. - Connect other end of ethernet cable to the inverter CAN port.
Install with:
python3 -m pip install alphaess-modbus
Checkout example.py
or example-tcp.py
to get started
Clone repo and run example.py
:
git clone git@github.com:SorX14/alphaess_modbus.git
cd ./alphaess_modbus
./example.py
[Sun, 20 Nov 2022 21:36:54] INFO [example.py.main:27] PV: 0W GRID: 1078W USE: 1078W Battery: 0W
Done! 🎉
This library concentrates on reading data, but writing is possible.
Uses a JSON definition file containing all the ModBus registers and how to parse them - lookup the register you want from the PDF and request it using the reader functions below.
For example, to get the capacity of your installed system, find the item in the PDF:
Copy the name - PV Capacity of Grid Inverter
- and request with await reader.get_value("PV Capacity of Grid Inverter")
An excerpt from registers.json
:
{
"name": "pv2_current",
"address": 1058,
"hex": "0x0422",
"type": "register",
"signed": false,
"decimals": 1,
"units": "A"
},
which would be used when called with:
await reader.get_value("PV2 current") # or await reader.get_value("pv2_current")
It will read register 0x0422
, process the result as unsigned, divide it by 10, and optionally add A
as the units.
The default JSON file was created with alphaess_pdf_parser. You can override the default JSON file with Reader(json_file=location)
Create a new RTU reader
import asyncio
from alphaess_modbus import Reader
async def main():
reader: Reader = Reader()
definition = await reader.get_definition("pv2_voltage")
print(definition)
asyncio.run(main())
Optionally change the defaults with:
decimalAddress=85
serial='/dev/serial0'
debug=False
baud=9600
json_file=None
formatter=None
Create a new TCP reader
import asyncio
from alphaess_modbus import ReaderTCP
async def main():
reader: ReaderTCP = ReaderTCP(ip="192.168.1.100", port=502)
definition = await reader.get_definition("pv2_voltage")
print(definition)
asyncio.run(main())
Optionally change the defaults with:
ip=None
port=502
slave_id=int(0x55)
json_file=None
formatter=None
Requests a value from the inverter.
grid = await reader.get_value("total_active_power_grid_meter")
print(grid)
# 1234
Prints the current grid usage as an integer.
Get units (if any) for a register name.
grid_units = await reader.get_units("total_active_power_grid_meter")
print(grid_units)
# W
Same as get_value()
but returns a string with units. If a formatter is defined for the register, a different return type is possible.
grid = await reader.get_formatted_value("total_active_power_grid_meter")
print(grid)
# 1234W
Set use_formatter
to False
to prevent a formatter from being invoked.
Get the JSON entry for an item. Useful if you're trying to write a register.
item = await reader.get_definition("inverter_power_total")
print(item)
# {'name': 'inverter_power_total', 'address': 1036, 'hex': '0x040C', 'type': 'long', 'signed': True, 'decimals': 0, 'units': 'W'}
Some registers are special and not just simple numbers - they could contain ASCII, hex-encoded numbers or another format.
For example, 0x0809
Local IP
returns 4 bytes of the current IP, e.g. 0xC0,0xA8,0x01,0x01
(192.168.1.1
).
To help, there is a built-in formatter which will be invoked when calling .get_formatted_value()
e.g:
ip = await reader.get_formatted_value("Local IP")
print(ip)
# 192.168.0.1
Not all registers have a formatter, and you might have a preference on how the value is returned (e.g. time-format). To help with this, you can pass a formatter
to Reader()
and override or add to the default:
class my_custom_formatter:
def local_ip(self, val) -> str:
bytes = val.to_bytes(4, byteorder='big')
return f"IP of device: {int(bytes[0])} - {int(bytes[1])} - {int(bytes[2])} - {int(bytes[3])}"
reader: Reader = Reader(formatter=my_customer_formatter)
local_ip = await reader.get_formatted_value("local_ip")
print(local_ip)
# IP of device: 192 - 168 - 0 - 0
Each formatting function is based on the conformed name of a register. You can find the conformed name of a register by searching registers.json
or by using await reader.get_definition(name)
☠️ ModBus gives full control of the inverter. There are device-level protections in place but be very careful ☠️
This library is intended to read values, but you can get a reference to the internal ModBus library with reader.instrument
:
# Using internal reference to read a value
read = await reader.instrument.read_long(int(0x0021), 3, False)
print(read)
# Untested, but should set system language
await reader.instrument.write_register(int(0x071D), 1, 0)
Read the library docs for what to do next: https://minimalmodbus.readthedocs.io/en/stable/
Use the AlphaESS manual for how each register works.
While my parsing script did its best, there are likely to be many faults and missing entries. I only need a few basic registers so haven't tested them all.
Some registers are longer than the default 4 bytes and won't work- you'll have to use the internal reader instead.
PR's are welcome 🙂
There are a lot of registers, but they might not all be relevant depending on your system setup. For example, the PV meter section is useless if your AlphaESS is in DC mode.
I've had the connection break a few times while testing, make sure you handle reconnecting correctly. example.py
will output the full exception should one happen.
Some of the more recent AlphaESS inverters have this out of the box, but mine didn't. The original RTU setup was to bridge this gap.
Eventually, I purchased a WaveShare RS485 TO POE Ethernet Converter but I'm sure there are alternatives. You want something that converts a RTU device to TCP.
The WaveShare one is powered by PoE, it was simple to unplug my RTU setup and put this in its place.
Added a small piece of DIN rail next to my inverter and gave the converter a static IP.
I used a m5stamp RS485 module with a digital isolator and DC/DC isolator.
Installed in an enclosure with a PoE adapter to power the Pi and provide connectivity.
Enabled ModBus interface on the inverter. You'll need the service password, mine was set to the default of 1111
.
Then connected to the CAN port.
Special thanks go to https://github.com/CharlesGillanders/alphaess where I originally started playing around with my PV system. Their project uses the AlphaESS dashboard backend API to unofficially get inverter values from the cloud.
Invaluable resource for discussing with other users. Highly recommend reading CharlesGillanders/alphaess#9 which ended up with AlphaESS creating an official API to retrieve data - https://github.com/alphaess-developer/alphacloud_open_api
Another great resource is https://github.com/dxoverdy/Alpha2MQTT which uses a ESP8266 instead of a Raspberry PI to communicate with the inverter - again - highly recommended.
https://github.com/scanapi/scanapi for 'helping' with github actions (I used their workflow actions as templates for this project).