Check My Solar Modbus Bridge

Local Docker stack for Fox ESS inverters (H1, H3, KH, and OEM variants). Polls live data over Modbus TCP and sends snapshots to Check My Solar through a private tunnel.

The bridge auto-detects your inverter model.

Full guide: checkmy.solar/docs/using-the-app/modbus-bridge/

Supported inverters

Register profiles (auto-detected from the model string):

Profile	Example models
h1g2	H1-G2, AC1-G2, P1
h1Series	H1, AC1, AIO-H1 (G1 / LAN)
kh	KH10.5, KH-5.0
h3Legacy	H3, AC3, AIO-H3, Kuara, SK-HWR, STAR, Solavita SP, a-TroniX AX
h3Modern	H3-Pro, H3-Smart, P3-SH, Enpal I-X, 1KOMMA5, EVO

Override auto-detect with INVERTER_PROFILE if needed.

Quick start

Create a token in Menu → Account → Modbus Bridge, then on your home server:

export CMS_BRIDGE_TOKEN='cms_bridge_...'          # from the app
export MODBUS_HOST='192.168.1.100'              # Modbus adapter IP
export BRIDGE_HOSTNAME='bridge-....modbus.internal'  # from the app
export TUNNEL_TOKEN='eyJ...'                       # from the app
export SITE_TIMEZONE='Europe/London'              # IANA timezone for hour buckets
# export MODBUS_CONNECTION=aux                      # default; use lan for direct inverter LAN
# export INVERTER_PROFILE=h3Modern                  # optional override
# export BRIDGE_VERBOSE_LOG=true                    # log each Modbus poll and HTTP request
# export MODBUS_DEBUG_LOG=true                      # log low-level Modbus reads (batching, retries, blacklisting)
docker compose up -d

Test inverter connectivity

Confirm Modbus works from your LAN before setting up tokens or Docker:

npm install
npm run build
MODBUS_HOST=192.168.1.100 npm run probe

From Docker:

docker run --rm -e MODBUS_HOST=192.168.1.100 ghcr.io/checkmysolar/modbus-bridge:latest npm run probe

If the stack is already running, probe inside the modbus container:

docker compose exec modbus npm run probe

Development

npm install
npm test
npm run build

Acknowledgements

The Modbus register maps and inverter logic in this bridge are adapted from foxess_modbus - a community Home Assistant integration. Thanks to Nathan Marlor and everyone who contributes to that project.