OpenEMS Modbus-API (grid)
The OpenEMS Modbus-API is a software interface built into the OpenEMS Edge energy management platform. Configured as a grid meter component, it exposes the grid connection point's real-time data over Modbus TCP on port 502. This template reads two key channels: instantaneous grid active power at address 315 and cumulative grid energy at address 359. Both are floating-point values polled directly from the OpenEMS _sum component block. Connecting the ModbusCloud Gateway to any OpenEMS Edge installation running the Modbus-API Controller gives installers continuous grid visibility inside the ModbusCloud portal without additional hardware.
- Protocol
- Modbus TCP
- Connection
- Ethernet, Modbus TCP
- Registers
- 2, read only
- Brand
- OpenEMS
- Compatible models
- Modbus-API
- Last updated
Registers (2)
2 read, 0 write
| Name | Unit | Access | Address (Hidden until you enter your email) | Function (hidden) | Type (hidden) |
|---|---|---|---|---|---|
| power | W | Read | |||
| energy | Wh | Read |
Loading registers…
Send your device list
If a device is not in the library yet, we build the template for free as soon as we have the register data.
Use cases
- Monitor instantaneous grid import and export power to verify self-consumption ratios on PV-coupled sites.
- Track cumulative grid energy over billing periods to cross-check utility meter readings for accuracy.
- Alert on sustained grid import above a threshold to detect unexpected load increases on managed sites.
- Compare grid power trends before and after battery storage commissioning to verify peak-shaving results.
- Report daily and monthly grid exchange figures for energy performance contracts or grid operator submissions.
Installation
Enable the Modbus-API Controller in the OpenEMS Edge configuration interface under Apps or Components, and confirm it is set to listen on TCP port 502 with the _sum component exported.
Connect the ModbusCloud Gateway to the same IP network as the OpenEMS Edge device, ensuring no firewall rule blocks TCP port 502 between the Gateway and the Edge host.
In the ModbusCloud portal, add your Gateway, import the OpenEMS Modbus-API (grid) template, and set the Modbus unit ID to 1, which is the default slave address used by the OpenEMS Modbus-API Controller.
Spot-check register 315 in the portal's live register view: a float32 value in the range consistent with your site's grid connection confirms the link is working correctly.
Things to watch for
The Gateway connects but both registers return no value. What now?
Verify that the Modbus-API Controller is active in OpenEMS Edge and that the _sum component is listed in its export configuration. If the controller is disabled or the component is not exported, the address block containing registers 315 and 359 will not exist and all reads will return exceptions.
Register 315 reads a plausible value but register 359 is always zero or NaN.
Address 359 is a float64 spanning four consecutive holding registers (FC3). Some Modbus masters default to reading only two registers for any address. Confirm the ModbusCloud template is configured with type float64, which instructs the Gateway to request all four registers in a single transaction. A partial read will produce an invalid value.
I get a connection refused error on port 502. How do I fix it?
The OpenEMS Edge Modbus-API Controller must be running and bound to the Edge device's network interface. Check that the controller is enabled in the OpenEMS configuration, that no local firewall or router ACL is blocking port 502, and that you are targeting the correct IP address of the Edge host, not a gateway or NAT address.
After an OpenEMS Edge firmware update, my register values shifted or disappeared.
The OpenEMS Modbus-API generates a dynamic register table that depends on which components are configured and in what order. A firmware update or component reconfiguration can shift block offsets. Re-download the System Profile Excel from the OpenEMS UI to confirm that addresses 315 and 359 still map to the expected grid power and energy channels in your updated installation.
Want to see how it works?
