Modbus API reference

Caution

The Modbus API is under development and not available yet. The content of this page is a DRAFT and may change at any time.

Feel free to reach out to us for suggestions, requests and similar.

The novolto P2300(G)/P3000(G) and Sense implement a SunSpec Modbus server for direct local control as an alternative to the MQTT API. Detailed documentation on SunSpec is available at sunspec.org.

Only holding registers are used. All modbus register addresses in this document are zero-based and do not contain prefix-digits to refer to register types.

General

The modbus server is disabled by default. It can be enabled via the modbus.enable setting. A restart is required for the setting to take effect.

The server is reachable on the standard modbus port 502. The connection is not encrypted. A valid modbus unit id between 1 and 247 must be used, otherwise requests are dropped.

The SunSpec ‘SunS’ marker and following model chain are located at holding register address 40000.

Available SunSpec Models

In addition to the required model 1 (Common), the following models are provided on each product type.

In the list of implemented points, scale factors are not listed explicitly. Scale factors are implemented if a field using the scale factor is implemented.

P2300(G)/P3000(G)

Note

If modbus is used without MQTT, make sure to disable the heating.require_mqtt setting, otherwise heating will be disabled with an error.

Water heaters provide the following models:

Model 701 (DER AC Measurements)

Provides information about the device’s electricity measurements.

The following points are implemented:

Point(s)	Notes
ACType	Set to SINGLE_PHASE
St	ON if heating is active, OFF otherwise
Alrm, MnAlrmInfo	The exact errors are only for display, exact implementation may change at any time
WL1	Provided as an average over 5s
VAL1, VarL1, PFL1, AL1, VL1	Provided as an average over 300ms

Model 704 (DER AC Controls)

Allows manual control of power output.

The following points are implemented:

Point(s)	Notes
WSetEna	Maps to the heating.mode setting. DISABLED maps to off. Other modes are represented by ENABLED when reading, writing ENABLED sets the mode to manual. We recommend not using modes other than off and manual if modbus is used.
WSet	Maps to the heating.target_power setting. Values must be negative and are clamped between -heating.target_power.max and 0.
WSetRvrt, WSetRvrtTms, WSetEnaRvrt, WSetRvrtRem	TBD: Reversion timer system is not yet implemented in firmware.

Manufacturer-specific Model

The exact details on this model are TBD.

To contain read/write points for the following settings:

• heating.target_temp
• heating.temp_hyst and heating.temp_hyst_mode

To contain readonly points for the following measurements:

• Tank water temperature (or in 701 AC Measurements TmpOt point)

Sense

Senses provide the Model 201 (Meter single phase) model to forward data from the connected electricity meter.

Caution

The implementation slightly deviates from the SunSpec specification by not always providing truly valid values in mandatory fields.

Mandatory values are provided as 0 if no meter is connected (see Evt field) or if not given by the connected electricity meter.

The implementation will make a best effort to forward data from fitting OBIS values into the SunSpec fields if available from the meter. Not all matching OBIS numbers might be understood. If the value is not available, the field is marked as not implemented (if non-mandatory) or zero (if mandatory).

The following points are supported:

Point(s)	Notes
A, PhV, Hz, W, TotWhExp, TotWhImp	Set if available from the electricity meter, 0 otherwise
Evt	Bit Missing_Sensor is set if no meter is currently connected.