Outback MATE python interface
Python
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
matenet
LICENSE
README.md
cstruct.py
mate_serial_communicationsguide.pdf
matecom.py
plot.py
readout.py
util.py
value.py

README.md

pyMATE

pyMATE

pyMATE is a python library that can be used to emulate an Outback MATE unit, and talk to any supported Outback Power Inc. device such as an MX charge controller, an FX inverter, a FlexNET DC monitor, or a hub with multiple devices attached to it.

You will need a simple adapter circuit and a TTL serial port. For more details, see jared.geek.nz/pymate

Also, to see the library in action, check out my post on connecting it with Grafana! jared.geek.nz/grafana-outback-solar

MX Interface

To set up communication with an MX charge controller:

mate_mx = MateMX('COM1')         # Windows
mate_mx = MateMX('/dev/ttyUSB0') # Linux
mate_mx.scan(0)  # 0: No hub. 1-9: Hub port? (Untested)

You can now communicate with the MX as though you are a MATE device.

Status

You can query a status with mate_mx.get_status(). This will return an MXStatusPacket with the following information:

status = mate_mx.get_status()
status.amp_hours       # 0 - 255 Ah
status.kilowatt_hours  # 0.0 - 6553.5 kWh
status.pv_current      # 0 - 255 A
status.bat_current     # 0 - 255 A
status.pv_voltage      # 0.0 - 6553.5 V
status.bat_voltage     # 0.0 - 6553.5 V
status.status          # A status code. See MXStatusPacket.STATUS_* constants.
status.errors          # A 8 bit bit-field (documented in Outback's PDF)

All values are floating-point numbers with units attached. You can convert them to real floats with eg. float(status.pv_voltage) # 123.4, or display them as a human-friendly string with str(status.pv_voltage) # '123.4 V'

Log Pages

You can also query a log page (just like you can on the MATE), up to 127 days in the past: (Logpages are stored at midnight, 0 is the current day so far)

logpage = mate_mx.get_logpage(-1)  # Yesterday's logpage
logpage.bat_max         # 0.0 - 102.3 V
logpage.bat_min         # 0.0 - 102.3 V
logpage.kilowatt_hours  # 0.0 - 409.5 kWh
logpage.amp_hours       # 0 - 16383 Ah
logpage.volts_peak      # 0 - 255 Vpk
logpage.amps_peak       # 0.0 - 102.3 Apk
logpage.absorb_time     # 4095 min  (minutes)
logpage.float_time      # 4095 min
logpage.kilowatts_peak  # 0.000 - 2.047 kWpk
logpage.day             # 0 .. -127

Properties

Additionally, you can query individual registers (just like you can on the MATE - though it's buried quite deep in the menus somewhere)

mate_mx.charger_watts
mate_mx.charger_kwh
mate_mx.charger_amps_dc
mate_mx.bat_voltage
mate_mx.panel_voltage
mate_mx.status
mate_mx.aux_relay_mode
mate_mx.max_battery
mate_mx.voc
mate_mx.max_voc
mate_mx.total_kwh_dc
mate_mx.total_kah
mate_mx.max_wattage
mate_mx.setpt_absorb
mate_mx.setpt_float

Note that to read each of these properties a separate message must be sent, so it will be slower than getting values from a status packet.

FX Interface

I don't have an FX unit to test with, so I cannot guarantee this will function. I determined everything by poking values at the MATE, and seeing what it sends back.

To set up communication with an FX inverter:

mate_fx = MateFX('COM2')         # Windows
mate_fx = MateFX('/dev/ttyUSB1') # Linux
mate_fx.scan(0)

status = mate_fx.get_status()
errors = mate_fx.errors
warnings = mate_fx.warnings

There's still a few unknowns, so you'll have to look through the source code (fx.py to work out what this produces, at least until I have a unit to test with myself.

Controls

You can control an FX unit like you can through the MATE unit (untested though!):

mate_fx.inverter_control = 0  # 0: Off, 1: Search, 2: On
mate_fx.acin_control = 0      # 0: Drop, 1: Use
mate_fx.charge_control = 0    # 0: Off, 1: Auto, 2: On
mate_fx.aux_control = 0       # 0: Off, 1: Auto, 2: On
mate_fx.eq_control = 0        # 0: Off, ??? not sure

These are implemented as python properties, so you can read and write them. Writing to them affects the FX unit.

Properties

There are a bunch of interesting properties, a lot not available from the status packet

mate_fx.disconn_status
mate_fx.sell_status
mate_fx.temp_battery
mate_fx.temp_air
mate_fx.temp_fets
mate_fx.temp_capacitor
mate_fx.output_voltage
mate_fx.input_voltage
mate_fx.inverter_current
mate_fx.charger_current
mate_fx.input_current
mate_fx.sell_current
mate_fx.battery_actual
mate_fx.battery_temp_compensated
mate_fx.absorb_setpoint
mate_fx.absorb_time_remaining
mate_fx.float_setpoint
mate_fx.float_time_remaining
mate_fx.refloat_setpoint
mate_fx.equalize_setpoint
mate_fx.equalize_time_remaining

I am open to contributions, especially if you can test it with any devices I don't have.