Skip to main content
Version: 5.32

Modbus TCP API

This document provides a complete overview of the Modbus Slave features of the Charge Controller.
Based on revision v0.14.

1. Config UI parameters reference for Operators

Parameter nameDescription
Modbus TCP ServerAllows to turn the Charge Controller into a Modbus TCP Server. This allows reading and writing parameters using the Modbus protocol. See the documentation for detailed register information.
Modbus TCP Server Base Port Port number on which the Modbus TCP Server waits for incoming connections on connector 1. In case a second connector is supported, the configured 'port + 1' will be used for that connector.
Modbus TCP Server Register Address Set Choose the set of register addresses that the Modbus TCP Server device will expose to its client.
Modbus TCP Server Allow Start/Stop Transaction Allows transactions to be started/stopped from a Modbus Master device via the controller's Modbus TCP Server interface.
Modbus TCP Server Allow UID Disclose Allows sending the UID over the Ebee Modbus TCP Server protocol

2. Modbus Unit ID

The Modbus TCP Server on the charge controller will reply to messages with any Unit ID from 1 to 255.

3. OCPP multiple connector scenarios

On an OCPP setup with 2 connectors, both controllers are accessible by connecting through the one acting as a master controller. In this case it is necessary to establish a separate connection to each charge controller.

The second connector's controller is accessible on the port corresponding to Modbus TCP Server Base Port + 1.

Assuming that the Modbus TCP Server Base Port is configured on the default port 502, the first connector can be accessed by connecting a Modbus Client to port 502, and the second connector can be accessed by connecting a separate Modbus Client to the first connector charge controller's port 503.

4. Word and byte ordering

With the notable exception of the values in the register destined to error codes (those with names prefixed with ERROR_CODES_ ) which are explained separately in their corresponding section, all other registers are to be read and written with the high byte first and the low byte after. For double registers (32-bit) the order of the words is the high word first and the low word after.

As an example, if registers 200-201 are read and contain a value of 0x0001 for register 200 and a value of 0x1F40 for register 201, these values are to be read as 0x00011F40, that is a decimal value of 73536.

5. Lowering charging current

To lower the charging currant the HEMS shall write to the Register HEMS_CURRENT_LIMIT as described in the HEMS configuration options section.

Please note the actual signaled current as indicated by the register named SIGNALED_CURRENT can be lower than the HEMS_CURRENT_LIMIT since other limitations (such as charging cable, or dynamic load management limits) could apply.

6. Supported function codes

All registers described in this document are HOLDING registers. Therefore, the only supported function codes are:

  • 0x03 -- Read single register
  • 0x06 -- Write single register
  • 0x10 -- Write multiple registers.

7. Bulk read of registers

It is possible to read a range of registers at a time (bulk read) starting at a specified register and within the boundaries of the register section.

info

If there are gaps with undefined register numbers in this range, value '0' will be returned.

ifthen
the requested range ends in the middle of a 32-bit registerthe last register will be discarded and no value returned. Increase the range by 1

8. General system information

The register in the first table that follows contain general information about the system, about its status, error states, FW and protocol versions and other system and configuration information.

note on OCPP_CP_STATUS

The Charge Point Status as defined in OCPP 1.5 and 1.6 is available in the OCPP_CP_STATUS register. Note that there's some difference between the two versions, so for example the value 1, which is used for "Occupied", is only valid for OCPP 1.5 and instead in 1.6 a more detailed value is available. For the descriptions of each of the charge point status values, please refer to the OCPP specification that corresponds to the version in use.

For details on how to read and interpret the registers designated for error handling please refer to the section Error states mask mappings.

Register Addr.Bit fieldSizeTypeNameDescription
100-10131:032-BitREADFIRMWARE_VERSIONEbee Application version number. example: 0.91 = (0x30, 0x2E, 0x39, 0x31), 4.40 = (0x34, 0x2E, 0x34, 0x34).
10415:016-BitREADOCPP_CP_STATUS0 = Available 1 = Occupied 2 = Reserved 3 = Unavailable 4 = Faulted 5 = Preparing 6 = Charging 7 = SuspendedEVSE 8 = SuspendedEV 9 = Finishing
105-10631:032-BitREADERROR_CODES_1See Error states mask mappings section for mask bit values.
107-10863:3232-BitREADERROR_CODES_2
109-11095:6432-BitREADERROR_CODES_3
111-112127:9632-BitREADERROR_CODES_4
120-12131:032-BitREADPROTOCOL_VERSIONEbee Modbus Slave Protocol Version number (example: 0.6 = 54). This corresponds to the Doc. Revision at the top of this document.
12215:016-BitREADVEHICLE_STATEControl Pilot vehicle state in decimal format: A = 1, B = 2, C = 3, D = 4, E = 5
12415:016-BitREAD & WRITECP_AVAILABILITYRead or set the Charge Point availability. 0 = Operative. 1 = Inoperative.
13115:016-BitREAD & WRITESAFE_CURRENTMax. charge current under communication failure with the Modbus Master.
168-16931:032-BitREADMANU_SERIAL_1Identifies the serial number as set by the Manufacturer.
This is a non-null terminated ASCII string of maximum 25 characters.
If the string is fewer than 25 characters, it is padded on the left (the lowermost registers) with blank-space ASCII characters.
170-17163:3232-BitREADMANU_SERIAL_2
172-17395:6432-BitREADMANU_SERIAL_3
174-175127:9632-BitREADMANU_SERIAL_4
176-177159:12832-BitREADMANU_SERIAL_5
178-179191:16032-BitREADMANU_SERIAL_6
180207:19216-BitREADMANU_SERIAL_7

9. Meter values from OCPP primary meter

Meter values are unsigned and sent in 32-bit words.

tip

When not available, registers contain a 0xffffffff value to indicate that no meter value for the requested register is present.

ifbecausethen
the line-specific power and energy isn't availablethe installation is single-phasedonly the Total Power and Total Energy is available
the meter doesn't support readings
tip

For maintaining backwards compatibility with previous systems, where the METER_TOTAL_ENERG and METER_TOTAL_POW registers were not present, the Total Power and Total Energy values can also be read from the Power and Energy registers corresponding to L1. In that case, the Power and Energy registers for L2 and L3 will return 0xffffffff.

Register Addr.Bit fieldSizeTypeNameDescription
200-20131:032-BitREADMETER_ENERG_L1Energy in Wh (phase 1) from primary meter
202-20331:032-BitREADMETER_ENERG_L2Energy in Wh (phase 2) from primary meter
204-20531:032-BitREADMETER_ENERG_L3Energy in Wh (phase 3) from primary meter
206-20731:032-BitREADMETER_POW_L1Power in W (phase 1) from primary meter
208-20931:032-BitREADMETER_POW_L2Power in W (phase 2) from primary meter
210-21131:032-BitREADMETER_POW_L3Power in W (phase 3) from primary meter
212-21331:032-BitREADMETER_CUR_L1Current in mA (phase 1) from primary meter
214-21531:032-BitREADMETER_CUR_L2Current in mA (phase 2) from primary meter
216-21731:032-BitREADMETER_CUR_L3Current in mA (phase 3) from primary meter
218-21931:032-BitREADMETER_TOTAL_ENERGTotal Energy in Wh from primary meter
220-22131:032-BitREADMETER_TOTAL_POWTotal Power in W from primary meter
222-22331:032-BitREADMETER_VOL_L1Voltage in V (phase 1) from primary meter
224-22531:032-BitREADMETER_VOL_L2Voltage in V (phase 2) from primary meter
226-22731:032-BitREADMETER_VOL_L3Voltage in V (phase 3) from primary meter

10. Dynamic Load Management (DLM)

This is information mostly concerning the DLM Master. Everything except for register 600 will be available only for devices with a DLM Master role set (meaning a value of 1 or 2 is returned on this register). | -->

Register Addr.Bit fieldSizeTypeNameDescription
60015:016-BitREADDLM_MODEIndicates the DLM mode configured for this device.
The following values represent each mode:
0 = Disabled
1 = DLM Master (With internal DLM-Slave)
2 = DLM Master (Standalone)
3 = DLM Slave (Master-Auto-Discovery)
4 = DLM Slave (Master-Fixed-IP)
61015:016-BitREADDLM_EVSE_SUB_DISTRIBUTION_LIMIT_L1Overall current limit for DLM available for distribution to Evs.
These three registers are for L1, L2, and L3 respectively and the values are in Amps.
61115:016-BitREADDLM_EVSE_SUB_DISTRIBUTION_LIMIT_L2
61215:016-BitREADDLM_EVSE_SUB_DISTRIBUTION_LIMIT_L3
61315:016-BitREAD & WRITEDLM_OPERATOR_EVSE_SUB_DISTRIBUTION_LIMIT_L1Operator current limit for DLM available for distribution to EVs. The 'Operator EVSE Sub-Distribution Limit' is equal or smaller than the 'EVSE Sub-Distribution Limit'.
These three registers are for L1, L2, and L3 respectively and the values are in Amps.
61415:016-BitREAD & WRITEDLM_OPERATOR_EVSE_SUB_DISTRIBUTION_LIMIT_L2
61515:016-BitREAD & WRITEDLM_OPERATOR_EVSE_SUB_DISTRIBUTION_LIMIT_L3
62015:016-BitREADDLM_EXTERNAL_METER_SUPPORTIf enabled, an external, secondary meter allows to also consider the power consumption of additional load. The power available for charging EVs will be adjusted accordingly. Please make sure, 'Meter configuration (Second)' is configured, preferrably to a 3-phase, phase aware meter.
Value of this register is 1 when enabled, 0 when disabled.
62115:016-BitREADDLM_NUM_SLAVES_CONNECTEDThe number of DLM Slaves connected to this Master device.
63015:016-BitREADDLM_OVERALL_CURRENT_APPLIED_L1Overall Current the DLM Master is currently applying (sum of current distributed among the slaves).
These three registers are for L1, L2, and L3 respectively and the values are in Amps.
63115:016-BitREADDLM_OVERALL_CURRENT_APPLIED_L2
63215:016-BitREADDLM_OVERALL_CURRENT_APPLIED_L3
63315:016-BitREADDLM_OVERALL_CURRENT_AVAILABLE_L1Overall Current the DLM Master has available to distribute among the slaves.
These three registers are for L1, L2, and L3 respectively and the values are in Amps.
63415:016-BitREADDLM_OVERALL_CURRENT_AVAILABLE_L2
63515:016-BitREADDLM_OVERALL_CURRENT_AVAILABLE_L3

11. Charge process information

Charge process information is information collected during, or inferred from, the charging process.

info
Deprecation Note

Registers

  • 705
  • 709

are deprecated and only to be used for clients that implement until version 10 of this protocol.

When using versionUse
< version 10 of this protocol705 and 609
>= version 11 of this protocolinstead of 705 → 716-717
instead of 705 → 709

The older registers can still be read in newer versions for backwards compatibility, but it is discouraged to do so in newer implementations.

Once the values in those registers reach their maximum, they will stay at the maximum value until the next session is started or until the charging process is finished according to each case.

Register Addr.Bit fieldSizeTypeNameDescription
701-70231:032-BitREADSCHED_DEP_TIME_15118Scheduled departure time (format is hhmmss in big-endian packed BCD with left zero padding) – 15118 only
703-70431:032-BitREADSCHED_DEP_DATE_15118Scheduled departure time (format is ddmmyy in big-endian packed BCD with left zero padding) – 15118 only
70515:016-BitREADDEPRECATED
CHARGED_ENERGY
(Please see the note above this table.)
70615:016-BitREADSIGNALED_CURRENTThe maximum current that’s being signaled to the EV for charging
707-70831:032-BitREADSTART_TIMEFormat is the same as in SCHED_DEP_TIME_15118
70915:016-BitREADDEPRECATED
CHARGE_DURATION
(Please see the note above this table.)
710-71131:032-BitREADEND_TIMEFormat is the same as in SCHED_DEP_TIME_15118
71215:016-BitREADMINIMUM_CUR_LIMITMinimum current limit for charging.
713-71431:032-BitREADREQ_ENERGY_15118EV Required Energy – 15118 only
71515:016-BitREADMAX_CUR_EVThis is the maximum current with which the EV can charge.
It may come from the cable's PR value in analog vehicles, or from the maximum reported by the vehicle via 15118, whichever is lower.
716-71731:032-BitREADCHARGED_ENERGYSum of charged energy for the current session (Wh).
The amount of charged energy will stay at its maximum until the next session is started
718-71931:032-BitREADCHARGE_DURATIONDuration of the charging process in seconds
720-72131:032-BitREADREAD_IDTAG_1OCPP IdTag. This is a non-null terminated string with a max. length of 20 bytes, represented here in five 32-bit registers (or ten consecutive 16-bit regs.).
The string is padded with blank-space characters on the left, or completely filled with blank-space characters when no IdTag is present.
When a charging session is not in progress or the IdTag is not available these registers contain all ASCII-whitespaces.
722-72331:032-BitREADREAD_IDTAG_2
724-72531:032-BitREADREAD_IDTAG_3
726-72731:032-BitREADREAD_IDTAG_4
728-72931:032-BitREADREAD_IDTAG_5
73015:016-BitREADEV_RESS_SOCState of charge of the EV’s battery (Rechargeable Energy Storage System) – 15118 only.
74015:016-BitREADSMART_EV_DETECTED_15118Returns 1 if an EV currently connected is a smart vehicle, or 0 if no EV connected or it is not a smart vehicle.
741-74231:032-BitREADEVCCID_15118_1ASCII representation of the Hex. Values corresponding to the EVCCID. The EVCCID value is 6 bytes, so the ASCII Hex. representation of it has a length of exactly 12 bytes.
This is a non-null terminated string.
Values are all zero when no vehicle is connected, or when the vehicle is not a 15118-capable smart vehicle.
743-74431:032-BitREADEVCCID_15118_2
745-74631:032-BitREADEVCCID_15118_3
74731:032-BitREADREM_TIME_TO_FULL_SOCReturns the remaining time in seconds to full SoC – 15118 only.
74915:016-BitREADIS_IN_CHARGING_LOOP_15118Returns 1 if the EV/EVSE are on a charging loop, 0 otherwise.
750-75131:032-BitREADDC_POWER_DELIVERYReturns the DC power currently delivered in Watts.
75215:016-BitREADAUTH_SOURCESource of authorization. Possible values:
0 = NONE
1 = RFID
2 = INPUT_SWITCH
3 = REMOTE
4 = 15118
5 = AUTOCHARGE
6 = FREECHARGING
7 = POWER_LOSS

12. HEMS configuration options

Register Addr.Bit fieldSizeTypeNameDescription
100015:016-bitREAD & WRITEHEMS_CURRENT_LIMITCurrent limit of the HEMS module in Amps. This register is intended to be modified by an Energy Manager. If the charge session shall be paused, the register needs to be set to "0"

13. Authorization with IDTag

Please note that for these registers to be enabled, the corresponding option must be set in the controller HEMS/Modbus setting named Modbus Slave Allow Start/Stop Transaction.

When writing to these registers, the effect will be exactly the same as if one physically presented an RFID card in fron of the card reader. That means it will start/stop the transaction accordingly based on each scenario's workflow.

Note that the registers in this table are WRITE only. To READ the IDTAG currently in use please refer to the registers prefixed with READ_ID_TAG_ on their name.

Register Addr.Bit fieldSizeTypeNameDescription
1110-111131:032-BitWRITEWRITE_IDTAG_1Same format as registers 720-729.
If the IdTag string is fewer than 20 characters, it must be padded on the left (the lowermost registers) with blank-space ASCII characters.
1112-111331:032-BitWRITEWRITE_IDTAG_2
1114-111531:032-BitWRITEWRITE_IDTAG_3
1116-111731:032-BitWRITEWRITE_IDTAG_4
1118-111931:032-BitWRITEWRITE_IDTAG_5

14. Error states mask mappings

In order to represent any simultaneous error states, the value read from the ERROR_CODES registers can be AND'ed with different mask mappings to identify which individual errors may be present at any given time in the system.

Since only bits 0 to 21 are used in the current specification, it is possibly to read only from registers 111-112 in order to optimize the fetching of values.

For completion however, it is clarified here how to read and interpret the values when reading all 8 registers.

To test for each error individually, the resulting value of reading all registers has to be masked against the corresponding error mask. An example is given below on how to achieve this.

Supposing the following value (presented here in HEX) is read from the ERROR_CODES registers:

Register: 105-106 107-108 109-110 111-112

Value: 0000 0000 0000 0000 0000 0000 4100 0000

Please focus first in the value of registers 111-112.

The bits of a double word are numbered from 0 through 31 with bit 0 being the least significant bit. The word containing bit 0 is the low word and the word containing bit 31 is the high word. Each 32-bit register has the low word first, and each word has the low byte first.

So in the case of registers 111-112 the words must first be inverted, to get a value of 0000 4100, and then the bytes of each word must be inverted too, in order to get a value of 0000 0041.

That is to be done for each register pair (105-106, 107-108, 109-110, 111-112), and once it is done, then the whole resulting value can be simply assembled from all registers by starting from a value of 0, and going through each word (register) in order, first shifting to the left then adding.

The result from the case above would be:

0000 0000 0000 0000 0000 0000 0000 0041

Finally, to identify which individual errors are present this value must be AND'ed to each error mask. So by doing the following operation:

0000 0000 0000 0000 0000 0000 0000 0041

AND

0000 0000 0000 0000 0000 0000 0000 0001

Ii is possible to identify that an error "ERR_RCMB_TRIGGERED" is present.

And by continuing doing for example:

0000 0000 0000 0000 0000 0000 0000 0041

AND

0000 0000 0000 0000 0000 0000 0000 0040

It can be observed that also there is an error "ERR_CONTACTOR_WELD" present.


Mask values for bits 0 to 21 (LSB 0) are specified in the following table. Bits 22 to 127 are reserved.

Bit number
(LSB 0)
Mask ValueMask NameDescription
00x01ERR_RCMB_TRIGGEREDResidual current detected via sensor.
10x02ERR_VEHICLE_STATE_EVehicle signals error.
20x04ERR_MODE3_DIODE_CHECKVehicle diode check failed - tamper detection.
30x08ERR_MCB_TYPE2_TRIGGEREDMCB of type 2 socket triggered.
40x10ERR_MCB_SCHUKO_TRIGGEREDMCB of domestic socket triggered.
50x20ERR_RCD_TRIGGEREDRCD triggered.
60x40ERR_CONTACTOR_WELDContactor welded.
70x80ERR_BACKEND_DISCONNECTEDBackend disconnected.
80x100ERR_ACTUATOR_LOCKING_FAILEDPlug locking failed.
90x200ERR_ACTUATOR_LOCKING_WITHOUT_PLUG_FAILEDLocking without plug error.
100x400ERR_ACTUATOR_STUCKActuator stuck cannot unlock.
110x800ERR_ACTUATOR_DETECTION_FAILEDActuator detection failed.
120x1000ERR_FW_UPDATE_RUNNINGFW Update in progress.
130x2000ERR_TILTThe charge point is tilted.
140x4000ERR_WRONG_CP_PR_WIRINGCP/PR wiring issue
150x8000ERR_TYPE2_OVERLOAD_THR_2Car current overload, charging stopped.
160x10000ERR_ACTUATOR_UNLOCKED_WHILE_CHARGINGActuator unlocked while charging.
170x20000ERR_TILT_PREVENT_CHARGING_UNTIL_REBOOTThe charge point was tilted and it is not allowed to charge until the charge point is rebooted.
180x40000ERR_PIC24PIC24 error.
190x80000ERR_USB_STICK_HANDLINGUSB stick handling in progress.
200x100000ERR_INCORRECT_PHASE_INSTALLATIONIncorrect phase rotation direction detected.
210x200000ERR_NO_POWERNo power on mains detected.
220x400000ERR_METER_SECOND_NOT_COMMUNICATINGMeter second not communicating.
230x800000ERR_MONITORING_RELAY_INPUT_TRIGGEREDRCD-MCB Unique input triggered.
240x1000000ERR_STATE_DCharging is paused because state D is detected.
250x2000000DC_ERR_DOOR_OPENDC wallbox door is open
260x4000000ERR_RCD_MAYBE_TRIGGEREDRCD maybe triggered, detected by communication (power) loss on primary meter

15. Error events mask mappings

The same as described in chapter above applies here, except:

Supposing the following value (presented here in HEX) is read from the ERR_EVT_CODES registers:

Register: 158-159 160-161 162-163 164-165

Value: 0000 0000 0000 0000 0000 0000 4100 0000

Please focus first in the value of registers 164-165.

Bit number
(LSB 0)
Mask ValueMask NameDescription
00x01ERR_EVENT_ACTUATOR_LOCKunused
10x02ERR_EVENT_ACTUATOR_LOCK_WITHOUT_PLUGunused
20x04ERR_EVENT_REBOOT_IN_PROGRESSCharge point reboot was issued
30x08ERR_EVENT_AUTHORIZATION_FAILEDAuthorization failed
40x10ERR_EVENT_AUTHORIZATION_FAILED_NO_STATUSNOTIFAuthorization failed (w/o notification of OCPP backend)
50x20ERR_EVENT_FW_UPDATE_PAUSED_ACTIVE_TRANSACTIONunused
60x40ERR_EVENT_FW_UPDATE_FAILUREFirmware update failed (internet connection?).
70x80ERR_EVENT_FW_UPDATE_ROLLED_BACK_AFTER_FAILUREunused
80x100ERR_EVENT_FW_UPDATE_PACKAGE_MANAGER_FAULTFirmware update failed because the package manager refused the update.
90x200ERR_EVENT_MONITORING_UNINTENDED_RESETUnintended Reset - Power Outage?
100x400ERR_EVENT_TRANSACTION_STOPPED_AFTER_RESETChargePoint rebooted while a transaction (charging) was active. Transaction was implicitely terminated.
110x800ERR_EVENT_SLAVE_DISCONNECTEDA slave disconnected from the master.
120x1000ERR_EVENT_DIAGNOSTICS_FAILUREDiagnostics failed (internet connection?).
130x2000ERR_EVENT_RCMB_ERRORRCMB error
140x4000ERR_EVENT_TEMPERATURE_ALERTunused
150x8000ERR_EVENT_15118_COMMUNICATION_FAILURETCP/TLS 15118 communication failed
160x10000ERR_EVENT_15118_AUTHORIZATION_FAILURE15118 authorization for PnC failed. The signature validation failed
170x20000ERR_EVENT_15118_AUTHENTICATION_FAILURE15118 authentication for PnC failed
180x40000ERR_EVENT_15118_CERT_INSTALLATION_FAILURE15118 Certificate Installation failed
190x80000ERR_EVENT_15118_DEPARTURE_TIME15118 departure time received
200x100000ERR_EVENT_15118_EAMOUNT15118 Energy Amount received
210x200000ERR_EVENT_15118_V2G_SEQUENCE_TIMEOUT15118 V2G Sequence timeout
220x400000ERR_EVENT_15118_V2G_SEQUENCE_ERROR15118 V2G Sequence error
230x800000ERR_EVENT_15118_DC_CABLE_CHECKCable Check error - Not in state C/D
240x1000000ERR_EVENT_15118_DC_POWER_STOPPower stop error - Not in state B
250x2000000ERR_EVENT_15118_DC_ISOLATION_FAULTCable isolation fault
260x4000000ERR_EVENT_15118_DC_UNEXPECTED_CP_STATEUnexpected CP state
270x8000000ERR_EVENT_15118_DC_EVSE_INITIATED_SHUTDOWNEVSE normal shutdown
280x10000000ERR_EVENT_GENERIC_INFORMGeneric event
290x20000000ERR_EVENT_IDTAG_ADDED_OKAdding tag to Auth List or FLL succeeded
300x40000000ERR_EVENT_IDTAG_ADDED_FAILUREAdding tag to Auth List or FLL failed
310x80000000ERR_EVENT_SYSTEM_NOT_READYSystem not yet ready

16. Appendix

16.1. Exhaustive list of Modbus registers

Here's an exhaustive list of Modbus registers for convinience:

info

All data is transferred in network byte order/big endian.