Add support for KH series

[canton7]

https://github.com/TonyM1958/HA-FoxESS-Modbus/issues/4#issuecomment-1517860676

[canton7]

https://github.com/nathanmarlor/foxess_modbus/issues/202#issuecomment-1527287063

[MJW911]

I have managed to setup direct access on my KH series with Energy cube stack via modbus and a cheap USB dongle using @TonyM1958/HA-FoxESS-Modbus setup and @nathanmarlor 's Fox ESS Energy management setup. works like a charm and am working my way through ensuring all the registers are readable and correctly named. what is needed to add support for the KH series to this integration? i kept getting a "device unsupported" error when i tried to use @nathanmarlor 's integration.

(new to GH and HA so still getting my head around things)

[canton7]

Yep, we don't support the KH series yet - I really need someone with a KH to test things with.

The things we need to know are:

1. The values of holding registers 30000 - 30015. They contain the model number, which we use the detect the model
2. Exactly which holding registers are available over a direct lan connection, and which input registers are available over RS485 (although based on one of the comments above it doesn't make any input registers available). TonyM1958's integration just tries to poll all possible registers all of the time, and ignores any errors from the inverter saying that register isn't available, which doesn't work for us as we read multiple registers at a time.

Annoyingly I'm unwell and can't make it to a computer at the moment, and it's a bit hard to help from a mobile. If you're comfortable using modpoll, getting the values of 30000-30015, and seeing which of the registers in TonyM1958's yaml file are actually available on the KH (and which throw errors), that should be all we need. If you're a software person and are happy setting up a dev environment, that even better and I can guide you through which bits to change to add support.

[MJW911]

Hope you return to health speedily!

I used Node-Red to read the values of holding registers 30000 - 30015:

they return as: 0: 75 1: 72 2: 49 3: 48 4: 46 5: 53 6: 32 7: 32 8: 32 9: 32 10: 32 11: 32 12: 32 13: 32 14: 32

I will work my way through the logs and see which input registers are available and revert.

not a software person, but can get through most things through a methodical approach!

[canton7]

Cheers! That's "KH105", with no funky business, which is great.

Are you connected using an RS485 adapter, or a direct lan connection? (Fox's inverters often expose different sets of registers over those two connection types)

[MJW911]

It was one of the first KH10.5 systems installed in South Africa, have 3x energy cube high voltage series batteries installed as well. I have a WiFi 2.0 dongle installed and running as well.

there isn’t a LAN port on the KH other than the BMS connection, so RS485 is the only local option for connection.

I used a RUNCCI-YUN-USB-to-RS485-Converter to connect to my odroid n2+ running HASS natively.

I polled registers 10000-10007 as well, and get the same values for the model details.

will work my way through the registers and put a spreadsheet together for the KH10.5

[canton7]

Aha, good to know ta! I believe it's got much the same as the H1, see here: https://github.com/TonyM1958/HA-FoxESS-Modbus/wiki/H1-H3-Modbus-Map.xls. We just need to know if there are any which aren't supported (return an error when read)

[MJW911]

i've had a look through all of the logs for @TonyM1958's integration, and all of them are working on the KH10.5 via USB serial! so i reckon they are all supported.

Ive gone through the .XLS sheet, and these are the missing values i can locate from the modbus TCP document i have. not sure if they are relevant for the single phase devices, some seem to be replicated.

[MJW911]

from what i can figure out, the "H" series from Fox ESS all use the same modbus protocols and registers. let me know if you need me to work on something else, id love to have the KH 10.5 included in @nathanmarlor 's integration. it seems to be the current "best access scenario" for using modbus to integrate locally into HA.

[canton7]

Ah, if you're just looking for errors from TonyM1958's integration, I think you need to ramp up the log level of pymodbus? I'll put together a beta which assumes the KH supports everything the H1 supports anysay (when I'm able to), and we'll quickly find out if there's a gap!

More importantly though... You've got a modbus document?! Is that from FoxESS? Are you able to share it?

[canton7]

from what i can figure out, the "H" series from Fox ESS all use the same modbus protocols and registers

Ish, the AIO seems to be missing some registers

[MJW911]

Energy Storage Inverter Modbus TCP Communication protocols for FOXESS.pdf

hope this helps!

Send me whatever you need tested, im happy to be a part of getting it sorted and working for the KH10.5 and AIO6kw (installing HA on an odroid for my dads one soon)

[MJW911]

Energy Storage Inverter Modbus TCP Communication protocols for FOXESS.pdf appologies, i think that will load the file correctly..

[canton7]

Amazing! Where did you find that?

[canton7]

You won't believe the number of hours which have gone into trying to reconstruct that table through trial and error... I think we probably managed to get most of it flicking through, but the fault codes in particular are a goldmine

[canton7]

@TonyM1958 FYI

[MJW911]

Thank you for all your hard work and effort it’s greatly appreciated! @canton7 @TonyM1958 @nathanmarlor

I spent many hours trying to get into the registers via modbus polling, and tried to get into the WiFi dongle to access data with no success. At least we can work from here!

[nathanmarlor]

Thank you for all your hard work and effort it’s greatly appreciated! @canton7 @TonyM1958 @nathanmarlor

I spent many hours trying to get into the registers via modbus polling, and tried to get into the WiFi dongle to access data with no success. At least we can work from here!

FYI if you want to play with the WiFi dongle you can NAT the traffic and intercept/manipulate. I did a PoC here but haven't had time to develop it further -> https://github.com/nathanmarlor/fox-local

[rand12345]

@MJW911 If you have access to can protocol information I would be grateful for anything you have on the FoxESS protocol. It's 95% reverse engineered but some parts are difficult to resolve. Likewise with their parallelisation protocol.

[MJW911]

Thank you for all your hard work and effort it’s greatly appreciated! @canton7 @TonyM1958 @nathanmarlor I spent many hours trying to get into the registers via modbus polling, and tried to get into the WiFi dongle to access data with no success. At least we can work from here!

FYI if you want to play with the WiFi dongle you can NAT the traffic and intercept/manipulate. I did a PoC here but haven't had time to develop it further -> https://github.com/nathanmarlor/fox-local

That ship sailed for me when I hit a dead end on my own (didn’t know this existed), so went modbus via USB! may well be worth tinkering with further, will have a look and see.

[TonyM1958]

Energy Storage Inverter Modbus TCP Communication protocols for FOXESS.pdf appologies, i think that will load the file correctly..

Just looking through this pdf. Some of the information explains values I've been looking at - for example, true, reactive and apparent power values for inverter grid and EPS output fills in some of the gaps.

I'll work through and look at updating the spread sheet with names and unique ID, scale, precision, units over the next few days and validate against my H1 so we have a common reference.

[TonyM1958]

BTW - although the PDF gives addresses in the 11000 input range, we have already mapped some of them to registers in the 31000 holding range, so I'll try document both where I can.

Possibly important as, from what I have seen so far, KH presents holding registers rather than input registers via modbus RTU. In my integration code, where I can, I use the holding registers for sensors to allow the same code to work on both H1 and KH.

I also don't (yet) know if we will be able to infer more about H3 addresses from the PDF?

[TonyM1958]

Also found this on AWS a few days ago: Fox.Cloud.API.Protocol.pdf

Does not add anything in terms of address, but does contain a list of fault codes and messages that correspond to the alarm codes raised by Fox e.g. e.g. Grid Volt Fault = ID26. I've added the codes from this to a new tab in the spread sheet.

I will look at how this relates to the bit fields in the other PDF when I get a chance. So far, there seem to be ID1-ID256 in this document (which I had assumed meant a unsigned byte code) but there are 8 x 16-bit fields (=128 bits) in the latest PDF. Some mapping from bits to code seems to be required here?

[calum-mcfarlane]

You won't believe the number of hours which have gone into trying to reconstruct that table through trial and error... I think we probably managed to get most of it flicking through, but the fault codes in particular are a goldmine

I find it quite baffling that these documents aren't publically available and easily found on their website, since they've gone to the engineering effort of making it available via Modbus and specifically mention the use case in the user manual.

[canton7]

There is a document somewhere which says if you're making some kit to integrate with a foxess inverter, you need to get in contact, sign an NDA, and they'll tell you about just the registers you'll need.

[canton7]

I also don't (yet) know if we will be able to infer more about H3 addresses from the PDF?

I suspect not, although just getting then fault codes would be a huge bonus.

[calum-mcfarlane]

Three is a document somewhere which says if you're making some kit to integrate with a foxess inverter, you need to get in contact, sign an NDA, and they'll tell you about just the registers you'll need.

Instructive to compare to eg https://www.kamstrup.com/en-en/heat-solutions/meters-devices/modules/hc00382-modbus-kmp-tcpip which is documented to the Nth degree. Cultural differences between different mfrs, perhaps. Anyway, getting well OT now, good that the info is out there for all to use, NDA or not!

[canton7]

I've created the beta v1.5.1b1 with my first attempt at KH-series support.

@MJW911 Please try it out, and let me know what works / doesn't work.

Thanks!

[MJW911]

Epic!

Feedback:

1. Downloaded and installed without issue.
2. selected the RUNNYUCCI device from the USB serial menu, and initially got this error:

after trying a few restarts with no success, i went looking for what else was accessing the modbus device... Node-Red was the culprit. I disabled all of the nodes related to modbus, restarted HA, and success!

I have also downloaded and installed @nathanmarlor 's energy management GH which is also working.

will work through checking sensors and matching data with the system readings on the screen to assess accuracy and performance and revert.

not sure is its an issue with the whole integration, but i cannot see a total PV power entity, only the readings for each string (i have two strings running on 2/4 MPPT's on the system.

[canton7]

Aha perfect, thank you! Yep, please check that each sensor looks correct, compared to the foxess app etc, if you can.

Yeah, the inverter doesn't provide a total PV power register (although it does provide total PV energy). You can add a template sensor, or wait for #129

[MJW911]

i've updated to ver 1.5.2 and gone through all the sensors and compared to foxcloud and the machine screen. all are accurate and the system appears to be stable in operation.

The KH series has 4x MPPT's available, so there will be registers for PV3 and PV4 but i cannot seem to locate them.

is there a sensor available for Min SOC (On-Grid), register 41011 (16bit) and a toggle functionality? i see that it keeps defaulting back to 10%. In SA we have loadshedding (4 hours at a time, up to 16 hours/24 hour period) so using the min SOC (on Grid) as a buffer is essential for functionality in keeping a buffer present. would also like to be able to adjust it according to weather, upcoming scheduled heavy use power periods and the loadshedding data (integrated via an API from a data pool)

the number of batteries connected, cycle count, and an estimate of their lifespan would also be useful, along with a reading of residual energy (remaining battery BMS power).

having mapped the foxcloud data, app data, and data available on the device screen, its great to be able to see entities via modbus which aren't available on other platforms.

[canton7]

i've updated to ver 1.5.2 and gone through all the sensors and compared to foxcloud and the machine screen. all are accurate and the system appears to be stable in operation.

Great, thanks!

The KH series has 4x MPPT's available, so there will be registers for PV3 and PV4 but i cannot seem to locate them.

:(

is there a sensor available for Min SOC (On-Grid), register 41011 (16bit) and a toggle functionality?

If the register exists and is writable, yes I can add a sensor. However, as far as I know, the KH only exposes holding registers (not input registers) and 41001 is an input register (and has to be, as it's writable).

So, you tell me: does that register exist and is it writable? You can test with modpoll.

the number of batteries connected, cycle count, and an estimate of their lifespan would also be useful, along with a reading of residual energy (remaining battery BMS power).

Again, depends on whether the KH exposes registers for these. The register for kWh remaining is input register 11037 -- does that exist on the KH? Please test with modpoll.

[MJW911]

i am learning a lot and getting my head around the programming and how this all works and the programming side of things, and whilst i can dimestack weld a fart onto a rainbow in a thunderstorm, i am coming short on getting modpoll to work on my setup. could you assist?

i have tried node red, but as soon as i poll from node red, the modbus foxess integration throws an ex-wife and refuses to communicate and i have to re set it all. i have tried to get modpoll working on my setup, but am not coming right. (odroid n2+ running HASSIO native. accessing via Macbook m2, but have a windows VM on the mac if needed).

i really want to contribute meaningfully to this project, but am phoning-a-friend on this...

[TonyM1958]

Matt: I can access modbus on both LAN and RS485 on H1, but there is only the RS485 port on KH so I am guessing you are polling the same connection that HA is using, so your messages are probably getting mixed up and confusing HA. Sounds like you are going to have to turn HA off while you are polling. In my case, I unplug the USB adapter from HA and plug it into a PC to poll for registers on RS485.

This is the tool that I use: https://github.com/ClassicDIY/ModbusTool. Its a windows GUI that can read a block of addresses. Use whichever tool works best for you.

Poll holding registers 31000 to 31005 to start with - these are PV1 Voltage, Current and Power and PV2 Voltage, Current and Power so you can see what the values look like. I think you are looking for a similar set of 6 consequetive registers for PV3 and PV4, somewhere higher than 31039? When you run out of registers, you will get an error.

If you record or screen shot the values you get back for any registers you find it would be useful to post them. I'm still looking for holding registers addresses for some of the input registers we now know about and can probably recognise some of them.

You can also check if you have any input registers in the range 11000 - 11095 as discussed above. We get both holding and input registers on H1, but so far, have only detected holding registers when looking at KH.

[MJW911]

thanks Tony!

that makes sense, i will do that and revert!

[MJW911]

righto, after some serious pain with Mac and windows running on VM, we have success!

so the KH series DOES expose input registers!

the challenge with establishing where the PV3 and PV4 addresses are stems from the fact i only have PV1 and PV2 installed with strings...

these are the holding registers i could poll

will work through what i have polled and see how it relates to data recorded from foxcloud and through @TonyM1958 's spreadsheet.

[canton7]

Oh fantastic, nice one! My guess is that it's probably almost identical to the H1, but with PV3 and PV4 tacked on somewhere

[TonyM1958]

Not for the faint hearted, so don't try if not completely confident... you could switch off DC from panels if you have an isolator and swap PV1, PV2 to PV3, PV4 and look for where they pop up? Warning though, possible high DC voltages as panels will be live...?

[canton7]

I'd definitely only recommend doing that after dark! Hundreds of volts is in the "might kill you" range, even though the connectors look fairly safe.

[TonyM1958]

Definitely, unless they are wired through an external DC isolator switch that means you can disconnect safely.

[MJW911]

it seems to be a bit of a blend between the H1 and H3 registers, with some overlap between the input and holding registers in some entities. lets see if fox has the protocol document for all the registers...

in the meantime, i guess its a case of balancing between accessing the entities you need, and having access to all of the registers.

ill try anything twice, so when i get a gap ill disconnect the PV1 and PV2 strings and see where they pop up on PV3 and PV4.

both are on dual-pole isolators, with heir own surge protectors so it wont be an issue to switch across. I WOULD NOT RECOMMEND ANYONE JUST TRY THIS! ( theres live AC in&out, Battery DC in, and Panel DC connections all in close proximity)

whilst we love the high voltage capabilities of the fox systems, the amount of damage DC voltage and current that high will cause wont buff out!!

[TonyM1958]

We can look at what's common and what different and add a KH tab if needed. H3 has 3 x PV inputs but only 2 x MPPT and hence only 2 sets of PV registers. So far as I can tell PV1 and PV2 operate in parallel so, technically PV2 registers are really PV3.

KH has 4 x MPPT however, so I expect there will be 4 sets of registers. Also PV3 and PV4 are listed on the foxesscloud, so I don't think we are barking up the wrong tree here...

[TonyM1958]

If you can't identify registers, here's what I tend to do: create a dummy sensor e.g. called 31039 in HA that just scans the 16 bit register every minute or 2 and let it run for 24 hours. You can then go through the dummy sensors to see how they behaved. Stuff like PV has an obvious signature. Others correspond to battery charge or discharge, load power etc. Often you find another sensor with a similar shape that gives you a strong clue to what is going on.

[canton7]

Another approach I've used is to compare the holding registers (which we're pretty confident in, as they seem to be the same as the H1) to the input registers. E.g. if you're looking for PV1, read the current value of the PV1 holding register, then scan through the input registers for a register with the same value (being aware that the holding register might change its value as you do this!).

Once you've found a candidate, poll the input and holding registers together for a bit: if they change to the same values at the same time, they probably represent the same value.

[canton7]

Also, are you using the W610? If you are, be aware that it can't reliably read more than 8 registers or so, and the modbus tool will often just give you garbage / zeros for any register beyond this.

[MJW911]

I’m using a cheapie USB to Modbus converter. Downloaded the RTU to TCP converter app from the iOS App Store and it works great!

I’m limited to 10 registers at a time for polling, but have managed to switch between windows on the VM running the classic DIY modbus tool, and the converter app easily to check things in batches.

the plan is to work through the holding registers first and ensure the values are accurate, and then work my way through the inputs to match values.

Once I’ve narrowed in, I can poll the holding and inputs at the same time to see if they’re matching. Will take some time…

[TonyM1958]

Matt, quick look through the registers... looks like most match what I expect for H1 in latest spreadsheet so I don't think you need to spend ages comparing the ones already documented if the values are in the right ball park. Hope I can look later and try to pick out stuff with values that is not documented.

From what I recall, I didn't add the registers around 42000 to the spread sheet as it's mostly specialised grid and inverter settings that it's probably best not to mess with as understanding the effects might be very hard or even worst case void warranties...

[MJW911]

Thanks Tony! imho, its pretty slack on the part of Fox to allow modbus connections, without some element of control or publishing the registers for values.

Given the cost of these things i'm very cautious with what is done to and with the data, would hate to have a "rapid unscheduled disassembly" on any of it!

is there a spreadsheet for this project which sets out the goals for what is intended to be achieved in terms of monitoring entities, adjusting specific settings, or tracking specific data values? i believe for most folks its a case of "knowing what the time is" at the end of the day, without "needing to know how the watch works".

[TonyM1958]

For me, it's understanding what is there and how it can be used to better monitor and support users and solve issues that come up. The spreadsheet is documenting what I find as a reference. My code is a test bed for looking at sensors on my H1 and what they show me (and others, if they want), For me, during this development phase, it's a bit more agile than the production code developed by Nathan and Antony so I can play with stuff but that may change in the future. It's entirely up to Nathan / Antony what they decide to incorporate into their code - mostly driven by their own use, user comments and issues added here, it seems.

Other people are down and getting dirty looking into the battery CAN bus, delving a lot deeper into stuff. I think I'm here to look at the system rather than its component, if that makes sense.

BTW - looking at your data is useful. Registers 11056 and 11061 to 11068 are telling me your inverter had a recoverable fault when you did the scan. Grid Lost / Grid Volt Fault. We don't often see active faults in the data. I hear Load Shedding Events are quite common in SA? Be useful to look for the same pattern in the holding registers - 31027 is the inverter state as a starting point but that is now telling me you switched to EPS and the fault codes, possibly 31031 to 31038, went away?

[TonyM1958]

From what I recall, I didn't add the registers around 42000 to the spread sheet as it's mostly specialised grid and inverter settings that it's probably best not to mess with as understanding the effects might be very hard or even worst case void warranties...

What I meant by this is that there is almost certainly some factory calibration of the inverter after it's built. From the PDF, some of these settings look like they might relate to this, so could well vary from one inverter to another and require test rigs to set. Changing or trying to compare calibration settings across different inverters would be bad and probably a waste of time.