Fox ESS Modbus Bridge

By default, Check My Solar reads live data from Fox Cloud the same path as the Fox ESS app. That works well, but Fox Cloud updates up to every 5 minutes, which can make the Today view feel a little slow.

The Modbus Bridge is an optional add-on for Fox ESS inverters. A small Docker stack on your home network reads the inverter directly over Modbus TCP, then Check My Solar pulls that snapshot through a secure private tunnel. When the bridge is online, the dashboard can refresh live numbers about every 10 seconds on the Today view, and immediately after opening the app.

When to use it

The Modbus Bridge is a good fit if you:

• Have a Fox ESS inverter with Modbus TCP enabled (typically via an RS485-to-Ethernet adapter on your LAN)
• Run a home server, NAS, or always-on machine that can host Docker
• Want faster live updates on the Today dashboard without waiting on Fox Cloud polling

Supported inverters

The bridge auto-detects the register profile from your inverter model string. Supported families include:

If auto-detect fails, set INVERTER_PROFILE manually (see Environment variables).

You do not need the bridge for normal use. Linking Fox Cloud is enough for charts, history, forecasts, and notifications.

Architecture overview

At a high level, data flows from your inverter to the app like this:

Protocols along the path: Modbus TCP between inverter and bridge; HTTP GET /v1/realtime on your Docker network; outbound Cloudflare Tunnel to Check My Solar’s private backend.

Latency: End-to-end from a Modbus read on your LAN to the value appearing on the Today dashboard is typically about 100 ms-inverter → bridge → tunnel → Check My Solar backend → app. The dashboard polls about every 10 seconds while you are on Today, so you get fresh numbers quickly.

Components

Live variables replaced

When the bridge is online, these Today live fields come from Modbus instead of Fox Cloud:

Today’s totals replaced

When the bridge is online, these Today kWh totals also come from Modbus instead of Fox Cloud:

If the bridge goes offline or data goes stale, the app shows a status message and does not fall back to Fox Cloud for these fields by default - historical charts still load from Fox as usual. You can enable Fox Cloud fallback in Menu → Account → Modbus Bridge to use Fox Cloud live data when the bridge is unreachable.

When the bridge is online, work mode on Today also comes from Modbus (instead of Fox device settings). You can open the Work mode modal from the Today view to see what each mode does. Changing work mode from the app requires a read-write bridge - see Read-only mode and work mode control.

What stays on Fox Cloud

The bridge only replaces live telemetry and today’s totals for the current day. Everything else still comes from Fox Cloud:

• Historical charts (week, month, year)
• Daily totals for past days and other time views
• Export limit, scheduler, and most other device settings
• Forecasts and notifications (Fox Cloud users rely on periodic polling; Modbus Bridge users get near-instant battery, grid, and mode alerts)

Work mode changes from the app are only available when the bridge is configured for read-write access (MODBUS_READ_ONLY=false). Otherwise the app still shows the live work mode from Modbus, but cannot write a new mode.

Prerequisites

1. Home server capable of running Docker - an always-on machine on the same LAN as your inverter (home server, NAS, Raspberry Pi, etc.). It only needs to run the small Modbus Bridge Docker stack.
2. RS485 adapter - connects your inverter’s RS485 port to your network as Modbus TCP (default port 502, unit ID 247). Examples community members use:
   • Industrial Serial Server RS485 to RJ45 Ethernet (The Pi Hut)
   • Elfin EW11 - compact WiFi-to-RS485 with Modbus TCP
3. Fox ESS inverter with Modbus TCP enabled on the adapter
4. Check My Solar account with the inverter already linked via Fox Cloud
5. Network access from the Docker host to the Modbus adapter IP

You can test Modbus connectivity before setting up the bridge - from your host or from Docker (see Test inverter connectivity below).

Setup

git clone https://github.com/checkmysolar/modbus-bridge.git
cd modbus-bridge
export CMS_BRIDGE_TOKEN='cms_bridge_...'          # from the app
export MODBUS_HOST='192.168.1.100'              # your Modbus adapter IP
export BRIDGE_HOSTNAME='bridge-....modbus.internal'  # from the app
export TUNNEL_TOKEN='eyJ...'                       # from the app
# Optional: set MODBUS_READ_ONLY=false to allow work mode changes from the app (default is true)
docker compose up -d

git clone https://github.com/checkmysolar/modbus-bridge.git
cd modbus-bridge
npm install
npm run build
MODBUS_HOST=192.168.1.100 npm run probe

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

docker compose exec modbus dist/probe.js

How the dashboard uses bridge data

When you view Today:

1. The app loads Fox Cloud data as usual for charts
2. If a bridge is active, it also polls the Modbus endpoint in the background
3. When bridge data is fresh (sampled within the last 60 seconds), live fields on the energy flow diagram are updated from the bridge
4. Polling stops automatically if data goes stale or you switch away from Today

Read-only mode and work mode control

By default, the bridge runs in read-only mode (MODBUS_READ_ONLY=true). It polls inverter registers for live telemetry and today’s totals, but never writes holding registers. That is the safest default: Check My Solar can read your inverter faster without the bridge being able to change settings.

What read-only affects

Enable work mode changes

To let Check My Solar change work mode through the bridge, set:

MODBUS_READ_ONLY=false

Add it to your Docker environment (for example in .env or docker compose overrides), then restart the modbus container.

In the app

• Menu → Account → Modbus Bridge shows Access as Read-only or Read and write for the connected inverter.
• On Today, tap the work mode label to open the Work mode modal. If the bridge is read-only, you can still read about each mode, but Set buttons are hidden.
• Work mode control requires bridge version 1.4.0 or later and a supported inverter profile (H1 G2, KH, H3 Pro/Smart/EVO over LAN, and others as listed in the bridge release notes).

Security and privacy

• Post-quantum encryption - Traffic between your home cloudflared container and Check My Solar travels over a Cloudflare Tunnel protected by TLS 1.3 with hybrid post-quantum key agreement (X25519 + ML-KEM).
• The bridge token is a bearer secret - treat it like a password. Store it only on your home server.
• Check My Solar stores an encrypted copy server-side so the backend can authenticate to your bridge; the plain token is shown only once at creation.
• Communication from Check My Solar to your bridge uses a private Cloudflare Tunnel hostname (*.modbus.internal), not a public URL on your home IP.
• Your inverter is never exposed directly to the internet - only the bridge container talks to it on your LAN.
• Read-only by default - unless you set MODBUS_READ_ONLY=false, the bridge cannot write Modbus registers, so it cannot change work mode or other inverter settings from Check My Solar.
• Revoking a token in the app tears down the tunnel and invalidates access.

See Privacy & data for how Check My Solar handles account and device data generally.

Managing tokens

From Menu → Account → Modbus Bridge you can:

• Create a token for the selected inverter (one active bridge per account)
• Revoke a token - disconnects the tunnel and stops bridge access
• Check bridge status and last sample time
• See connected inverter details, including bridge version, firmware, and Access (read-only vs read-write)
• Toggle Fox Cloud fallback when the bridge is unreachable

How to update

When the app shows a bridge update is available, pull the latest image and restart the modbus container. You do not need a new bridge token or tunnel token.

Docker Compose (recommended):

cd modbus-bridge
docker compose pull modbus
docker compose up -d modbus

Docker run:

docker pull ghcr.io/checkmysolar/modbus-bridge:latest
docker stop modbus-bridge && docker rm modbus-bridge
# Re-run your original docker run command from the app, or use the same env/volume flags as before

Your .env, tunnel, and bridge_data volume are unchanged. After restart, reopen Menu → Account → Modbus Bridge and confirm the Bridge version matches the latest release.

Troubleshooting

Environment variables

What the bridge does not provide

Historical charts and daily totals for past days always come from Fox Cloud regardless of bridge status.

FAQ

How does the Docker stack work?

docker compose up starts two containers on a private Docker network (cms_net):

The modbus container is the only one that talks to your inverter. It needs MODBUS_HOST set to your RS485-to-Ethernet adapter IP on your home network.

When you create a token in the app, Check My Solar also provisions a Cloudflare Tunnel and a private hostname route for your account. You copy the tunnel run token and hostname into your environment variables and start the stack at home.

How does the tunnel reach the bridge?

The private hostname (for example bridge-abc123….modbus.internal) is registered as a Docker network alias on the modbus container. Both containers share the same cms_net network, so cloudflared can resolve that hostname to the bridge container’s internal IP.

When Check My Solar needs live data, its backend calls your private hostname over Cloudflare’s private network. The request arrives at your home cloudflared container through the tunnel, and cloudflared forwards it to http://<BRIDGE_HOSTNAME>:8080 on the Docker network - not to a public IP or a port on your router.

Can I access the bridge from my LAN?

Not by default. We do not expose the bridge HTTP API on your home network. Port 8080 is only reachable on the internal Docker network between modbus and cloudflared, and Check My Solar reaches it through the encrypted tunnel.

You can expose it on your LAN if you want to - for example, by adding a ports mapping to the modbus service in docker-compose.yml so other devices on your network can call GET /v1/realtime. That is optional and not required for Check My Solar.

Can I change the private hostname?

No. The hostname is generated when you create a bridge token and is tied to your Check My Solar account and that token’s tunnel configuration. It always ends in .modbus.internal.

Use the exact value shown in Menu → Account → Modbus Bridge for BRIDGE_HOSTNAME. If you revoke the token and create a new one, you get a new hostname and new secrets - update your Docker environment and restart the stack.

Why are there two containers instead of one?

They do different jobs:

• modbus - inverter polling and the local HTTP API
• cloudflared - secure outbound tunnel only; it does not talk to your inverter directly

Do I need to open ports on my router?

No. All traffic from Check My Solar to your bridge flows outbound from cloudflared through the tunnel. You do not need port forwarding, a static public IP, or inbound firewall rules for the bridge.

How fast is it?

End-to-end latency is typically about 100 ms from the inverter to your dashboard: Modbus read on your LAN → local bridge snapshot → Cloudflare Tunnel → Check My Solar backend → Today view. That is much faster than Fox Cloud live data, which can lag by up to several minutes.

While you are on Today with a healthy bridge, the app polls for new snapshots about every 10 seconds, so live power, battery, and grid numbers stay current without hammering your inverter or home network.

Why is the bridge read-only by default?

Read-only mode means the bridge only reads Modbus registers. Check My Solar gets faster live data without the bridge being able to change inverter settings. If you want to change work mode from the app, set MODBUS_READ_ONLY=false on the bridge container and restart - see Read-only mode and work mode control.

Related pages

• Dashboard overview
• Time views (Today, Week, Month)
• Real-time production via Fox Cloud
• Account & settings
• Discord community