Modbus Map.xls
Spread sheet with the known Fox ESS Inverter modbus mappings and fault codes:
Changes log (reverse chronological order):
24/02/2024: Updated info on registers for H1 and H1-G2
28/01/2024: Added remote control registers for H1 / H3
21/10/2023: Added work mode decodes for ForceCharge and ForceDischarge
13/08/2023: Update to H3 registers after testing with Cosmico89 (thanks)
11/07/2023: added HV BMS v1 decode info
21/06/2023: align unique id with foxess_modbus
02/06/2023: updated with AIO-H1-2023 registers - tbc
28/05/2023: changed sensors for grid charge from binary to int16
24/05/2023: add info from KH modbus, including BMS and battery serial nos
22/05/2023: updated after full review of KH register scan
21/05/2023: tentative changes from KH register scan
19/05/2023: fix migration problem by renaming InvBatPower back to Battery Discharge Power
15/05/2023: add more holding register addresses, tag addresses available on LAN, RS485 or BOTH
14/05/2023: tidy up names and coded sensors, added decoded sensor names
13/05/2023: updated after test code with new input registers run to validate against H1
12/05/2023: updated with addresses from PDF and fault code bit field mapping
11/05/2023: started updating with info from PDF - Work In Progress, some partial changes.
08/05/2023: added Code tab with info on values for Work Mode, Inverter State and Fault Codes
05/05/2023: confirmed Inverter State Code at 31027
04/05/2023: added column to identify registers that are only available via RS485, not available via LAN on H1
30/04/2023: added input registers for inverter date/time, max charge & discharge current and export limit settings
24/04/2023: updated H3 sensors, clean up temperature sensor names
23/04/2023: first draft addition of H3 tab to spread sheet and sync between H1 and H3, work in progress
22/04/2023: updated string lengths for model and serial number, sorted by holding register number
21/04/2023: added Load Energy Total and Load Energy Today
21/04/2023: added LAN addresses for Solar Enery Total ... Input Energy Today
21/04/2023: added Inverter model and firmware versions address 10000/30000 - 10023 / 30023
21/04/2023: corrected addresses for InvTemp and AmbTemp
20/04/2023: updated 'Bat Volt' and 'Bat Current' to 'BatVolt' and 'BatCurrent' to match current running code
Download this file, open Studio Code Server and drop it into your CONFIG folder in Home Assistant: modpoll.tar.gz
Open a terminal session and run these commands:
tar -xzf modpoll.tar.gz
cd modpoll
ls -l
The result should look like this:
You can navigate to the folder in Studio Code Server to view and edit the files. README.txt contains details of the command line and options available for modpoll.
The files input.sh and holding.sh provide the basic commands to connect to the inverter and read input or holding register respectively.
By default, the files are setup to connect to the inverter using a USB adapter configured as /dev/ttyUSB0. If you connect via a LAN adapter, open the files input.sh and holding.sh in Studio Code Server, comment out the line that runs in RTU mode and uncomment the line that runs in TCP mode. Edit the IP address to match your adapter setting. Save your changes using ctrl-S. The files should look like this after you make changes:
Once your connection is configured, you can run a scan in the terminal window to see if any registers are found. For example:
The command line for scan.sh is:
./scan.sh <type> <start> <add> <count>
- <type> is input or holding. Read 16-bit input or holding register and display in decimal
- <start> is the modbus address to start from
- <add> is how much to add to the modbus address each time
- <count> is how many times to loop
In the example above, the scan command reads modbus address 11000, then adds 1 to read 11001 and continues doing this 30 times.
This example scans for blocks of modbus holding register addresses, starting at 30000 increasing by 1000 each time:
You can use this to 'block technique' to detect the start range of sets of input or holding registers and then read registers in each set to determine the number of registers that respond.
Once you find a set of registers, you can also read individual or multiple registers. In some cases, the inverter will only respond when a block of registers is read with the same command. For example, this command reads 16 holding registers at modbus address 30000 and displays the data in hex. The output is the inverter model encoded with one ASCII character per register and padded with spaces to a total of 16 characters.
The command line for input.sh or holding.sh is:
./input.sh <addr> <options> <modifier>
- <addr> is the modbus address to use
- <options> are additional general options for modpoll (see README.TXT). For example, -c 16 tells modpoll to read a block of 16 registers
- <modifier> changes the data type that is read / displayed e.g. :int (32-bits), :hex (16-bits with hex display), :float (32-bits)