OpenEMS Modbus-API (battery)
OpenEMS Modbus-API is the built-in Modbus TCP slave interface of OpenEMS Edge, an open-source energy management system used in residential and commercial battery storage installations. The Modbus-API Controller generates a dynamic register map that exposes internal OpenEMS channels to external systems over TCP port 502. This battery template reads two key values from the _sum component: state of charge (register 302, mapped to _sum/EssSoc) and battery active power (register 415). Connect the ModbusCloud Gateway to the same network as the OpenEMS Edge host and import this template to track battery behavior without additional configuration.
- 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 | |||
| soc | % | 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 battery state of charge continuously to detect abnormal self-discharge between charge cycles.
- Track active power at register 415 to verify the battery is charging or discharging as scheduled.
- Alert on state of charge dropping below a threshold during overnight discharge to protect battery longevity.
- Compare power values across multiple OpenEMS Edge sites from one ModbusCloud multi-site dashboard.
- Verify that battery power returns to zero after a scheduled charge window ends, confirming controller behaviour.
Installation
Enable the Modbus-API Controller in your OpenEMS Edge instance: open the Apache Felix Web Console, add the component Controller.Api.ModbusTcp.ReadWrite or Controller.Api.ModbusTcp.ReadOnly, and confirm it is active on TCP port 502.
Connect the ModbusCloud Gateway to the same LAN segment as the OpenEMS Edge host, ensuring no firewall rule blocks port 502 between Gateway and Edge.
In the ModbusCloud portal, add the Gateway, then import the OpenEMS Modbus-API (battery) template and set the Modbus unit ID to match the slave ID configured in your Edge instance (default is 1).
Spot-check the connection by reading register 302 (soc) in the portal live view; the value should match the state of charge shown in the OpenEMS UI dashboard.
Things to watch for
Why does register 302 always return zero or null?
Register 302 maps to _sum/EssSoc and is only populated when at least one ESS component is active in OpenEMS Edge. If no battery device is configured and running, the channel remains undefined and the Modbus API returns zero. Confirm that an ESS component appears as active in the Apache Felix Web Console before polling.
The Gateway connects on port 502 but no values appear. What now?
Check that the Modbus-API Controller component is in state RUNNING in OpenEMS Edge, not just configured. Also verify the unit ID: the default OpenEMS Modbus slave ID is 1. If your Edge instance was reconfigured, the slave ID may differ. Confirm under the Controller configuration in Felix Web Console.
Why does register 415 read as NaN or an implausible float value?
Register 415 uses the float32 type spanning two consecutive 16-bit registers. If your polling client reads only a single register word, the float decodes incorrectly. Ensure the ModbusCloud Gateway template is applied correctly and that no other Modbus master is polling the same address simultaneously, which can corrupt the two-register read.
The register map on my Edge instance differs from this template. Why?
OpenEMS Modbus-API generates a dynamic register map based on which components are exported. The addresses in this template (302 for soc, 415 for power) match the standard _sum component block. If your Edge configuration exports additional or different components, register addresses can shift. Download the site-specific register map from the OpenEMS UI under System Profile to verify.
More OpenEMS templates
Want to see how it works?
