RpcApi¶
Handwritten Documentation¶
Version Information¶
Version history of the module:
Version |
Description |
|---|---|
1.0.0 |
Initial version of the RpcApi module |
Introduction¶
The RPC API provides a standardized interface for external applications to interact with an EVerest-based ChargePoint. It is designed as a lightweight and transport-independent communication layer that enables monitoring, control, and integration into higher-level energy management systems.
The API follows the JSON-RPC 2.0 standard and uses WebSocket as the default transport channel, offering a persistent and bidirectional connection between client and server. This ensures low latency, efficient message exchange, and clear request–response semantics.
Typical use cases include:
Integration of ChargePoints into energy or fleet management platforms
Building mobile or web applications for end-users
Monitoring charging sessions
Controlling operational parameters such as charging power, current, or connector states
Accessing structured error and status information for diagnostics
Key features:
Transport independence – designed to work over WebSocket today, extendable to other transports in the future
Request/response and notifications – methods for configuration and control, notifications for event-driven updates
Structured data model – standardized objects and enums for consistent integration
Scalable design – suitable for single-user tools as well as multi-user systems
In short, the RPC API serves as the communication bridge between the charging infrastructure and external applications, providing a reliable, extensible, and system-friendly interface for monitoring and control.
General¶
Feature Overview¶
Feature |
Supported |
|---|---|
WebSocket transport - no TLS |
✅ |
WebSocket transport - with TLS |
❌ |
Authentication / Permission handling |
❌ |
Scope configuration |
❌ |
Support for multiple EVSEs |
✅ |
Support for multiple connectors |
❌ |
EVSE information retrieval |
✅ |
EVSE status retrieval |
✅ |
Hardware capabilities retrieval |
✅ |
Meter data retrieval |
✅ |
Control of charging current (AC) |
✅ |
Control of charging power (DC) |
✅ |
Control of phase count (AC) |
✅ |
Connector enable/disable |
✅ |
Error monitoring (active errors) |
✅ |
Notifications for status/capabilities |
✅ |
DC charge parameters |
❌ |
DC charge status |
❌ |
Display parameters (ISO15118-20 data) |
❌ |
Authentication¶
(Currently not supported)
The API should optionally support a client authentication mechanism. This can be used to introduce permission management, which can be used to control which functions a client may access, and which functions it may not.
If authentication is required, each call, except the initial messages to exchange e.g. the used API version, is required to contain a valid authentication token. How this authentication token is created is not part of this specification and must be specified during client and server development.
Tools¶
The tools subdirectory contains a Python-based JSON-RPC GUI client. This client allows testing of the interface implementation and can serve as a reference example for developing your own client.
API Methods and Notifications¶
General¶
The JSON API is generated from the json_rpc_api.yaml specification. This YAML file serves as the primary reference for all available methods and notifications. It also defines which parameters are required and which are optional.
Hierarchy of methods & notifications¶
API – general methods, no effect on charge point
ChargePoint – affects the entire charging station
EVSE – relates to a specific EVSE (Electric Vehicle Supply Equipment)
Methods¶
This includes all calls that can be executed by the client. Please note that if authentication is active, a token must be included in the request except for API.Hello. Otherwise, the request will be rejected. The following chapter headings represent the method name of the JSON-RPC protocol. The response and requests objects shown in the following chapters map the “params” value in the JSON-RPC object. If “params” is marked as “{}” it means that no parameters are required and the “params” object can be omitted. An example JSON-RPC request without “params” is shown in the API.Hello request section and an example JSON-RPC request with “params” is shown in the EVSE.GetInfo request section.
Note
Configuring charging parameters (such as charging current limits) via the API interface cannot always be guaranteed, since these values may also be influenced by other sources within EVerest. For example, if EVerest has been configured with an upper limit of 12A, this value cannot be exceeded via the API interface. In this specific case, if a client attempts to configure 16A through the API, the applied value will still be limited to 12A. Therefore, it is important to always observe the configured values returned via the EVSE.StatusChanged notification.
In future versions, unsuccessful configuration attempts may also result in an error response instead of silently applying the nearest valid limit.
API.Hello¶
This method is used to perform an initial handshake with the server. It must be called by the client within 5 seconds after establishing a connection; otherwise, the server will automatically close the connection.
The response message contains basic information from the EVerest ChargePoint, such as the API version in use, to enable further communication. While the Hello call does not necessarily require a token, it may be called with one. If a token is provided, the server verifies it, and the reply includes information about the token’s validity as well as the associated user and permissions.
In case authentication is required, the optional parameter permission_scopes can be used to indicate the permissions (e.g., read/write access) the client has when using the given token.
Note
The fields authenticated, permission_scopes and everest_version are currently not supported.
Request:
{}
Example JSON RPC Request:
{"jsonrpc": "2.0", "method": "API.Hello", "id": 1}
Response:
{
"authentication_required": "bool",
"authenticated": "bool", // optional, always false for now
"permission_scopes": "PermissionScopes", // optional, not yet defined
"api_version": "string",
"everest_version": "string", // currently not supported
"charger_info": "$ChargerInfoObj"
}
ChargePoint.GetEVSEInfos¶
This method is used to obtain general information about all configured EVSE’s of the charge point.
Request:
{}
Response: Returns an array of type “EVSEInfoObj” of all configured EVSE’s of the charge point.
{
"infos": "[Array of $EVSEInfoObj]",
"error": "$ResponseErrorEnum"
}
ChargePoint.GetActiveErrors¶
This method returns a structured list of all currently active error conditions of the charger. It is intended for diagnostic purposes and remote monitoring.
Request:
{}
Response:
{
"active_errors": "[Array of $ErrorObj]", // Empty array if no errors
"error": "$ResponseErrorEnum"
}
EVSE.GetInfo¶
This method is used to obtain general information about an EVSE.
Request:
{
"evse_index": "int"
}
Example JSON RPC Request:
{"jsonrpc": "2.0", "method": "EVSE.GetInfo", "id": 1, "params": {"evse_index": 1}}
Response:
{
"info": "$EVSEInfoObj",
"error": "$ResponseErrorEnum"
}
EVSE.GetStatus¶
This method is used to obtain the current status of the EVSE.
Request:
{
"evse_index": "int"
}
Response:
{
"status": "$EVSEStatusObj",
"error": "$ResponseErrorEnum"
}
EVSE.GetHardwareCapabilities¶
This method is used to obtain hardware capabilities of the EVSE. Please note that the hardware capabilities can be updated via notification EVSE.HardwareCapabilitiesChanged by the EVSE.
Request:
{
"evse_index": "int"
}
Response:
{
"hardware_capabilities": "$HardwareCapabilitiesObj",
"error": "$ResponseErrorEnum"
}
EVSE.SetChargingAllowed¶
This method is used to explicitly allow charging on an EVSE or to remove the release. Regardless of the authorisation status of the EV, this method can be used to delay a charging process or to initiate a charging pause on EVSE’s side.
Request:
{
"evse_index": "int",
"charging_allowed": "bool"
}
Response:
{
"error": "$ResponseErrorEnum"
}
EVSE.GetMeterData¶
Request:
{
"evse_index": "int"
}
Response:
{
"meter_data": "$MeterDataObj",
"error": "$ResponseErrorEnum"
}
EVSE.SetACChargingCurrent¶
This method is used to configure the AC charging current of an EVSE.
Request:
{
"evse_index": "int",
"max_current": "float"
}
Response: Returns an error parameter to show if the configuration of the charging current was successful.
{
"error": "$ResponseErrorEnum"
}
EVSE.SetACChargingPhaseCount¶
This method is used to configure the AC phase count of an EVSE.
Request:
{
"evse_index": "int",
"phase_count": "int"
}
Response: Returns an error parameter to show if the configuration of the charging current was successful.
{
"error": "$ResponseErrorEnum"
}
EVSE.SetDCChargingPower¶
This method is used to configure the DC charging power an EVSE.
Request:
{
"evse_index": "int",
"max_power": "float"
}
Response: Returns an error parameter to show if the configuration was successful.
{
"error": "$ResponseErrorEnum"
}
EVSE.EnableConnector¶
Method to enable or disable a connector on the EVSE. connector_index is a positive integer identifying the connector that should be enabled. If the connector_index is 0 the whole EVSE is enabled.
Request:
{
"evse_index": "int",
"connector_index": "int",
"enable": "bool",
"priority": "int"
}
Response:
Returns an error parameter to show if the configuration of the charging current was successful.
{
"error": "$ResponseErrorEnum"
}
Notifications¶
Notifications are signaled by the server as soon as a property within the parameters has changed.
ChargePoint.ActiveErrorsChanged¶
{
"active_errors": "[Array of $ErrorObj]"
}
EVSE.HardwareCapabilitiesChanged¶
{
"evse_index": "int",
"hardware_capabilities": "$HardwareCapabilitiesObj"
}
EVSE.StatusChanged¶
{
"evse_index": "int",
"evse_status": "$EVSEStatusObj"
}
EVSE.MeterDataChanged¶
{
"evse_index": "int",
"meter_data": "$MeterDataObj"
}
Enums¶
ResponseErrorEnum¶
Enumeration to differentiate between the various error cases that can occur after a method request.
"NoError",
"ErrorInvalidParameter",
"ErrorOutOfRange",
"ErrorValuesNotApplied",
"ErrorInvalidEVSEIndex",
"ErrorInvalidConnectorId",
"ErrorNoDataAvailable",
"ErrorUnknownError"
EnergyTransferModeEnum¶
Enumeration to differentiate between the various energy transfer modes
"AC_single_phase_core",
"AC_two_phase",
"AC_three_phase_core",
"DC_core",
"DC_extended",
"DC_combo_core",
"DC_unique",
"DC",
"AC_BPT",
"AC_BPT_DER",
"AC_DER",
"DC_BPT",
"DC_ACDP",
"DC_ACDP_BPT",
"WPT"
ChargeProtocolEnum¶
"Unknown",
"IEC61851",
"DIN70121",
"ISO15118",
"ISO15118_20"
EVSEStateEnum¶
"Unplugged",
"Disabled",
"Preparing",
"Reserved",
"AuthRequired",
"Charging",
"ChargingPausedEV",
"ChargingPausedEVSE",
"Finished",
"SwitchingPhases"
ConnectorTypeEnum¶
"cCCS1",
"cCCS2",
"cG105",
"cTesla",
"cType1",
"cType2",
"s309_1P_16A",
"s309_1P_32A",
"s309_3P_16A",
"s309_3P_32A",
"sBS1361",
"sCEE_7_7",
"sType2",
"sType3",
"Other1PhMax16A",
"Other1PhOver16A",
"Other3Ph",
"Pan",
"wInductive",
"wResonant",
"Undetermined",
"Unknown"
EVSEErrorEnum¶
EVSEErrorEnum can be used to show more details of an EVSE error for example in a service tool application for the technician. The enum naming is identical to EVerest error handler semantic.
Example (excerpt):
"NoError",
"power_supply_DC/HardwareFault",
"power_supply_DC/OverTemperature",
"power_supply_DC/UnderTemperature",
"power_supply_DC/UnderVoltageAC",
"power_supply_DC/OverVoltageAC",
"power_supply_DC/UnderVoltageDC",
"power_supply_DC/OverVoltageDC",
"power_supply_DC/OverCurrentAC",
"power_supply_DC/OverCurrentDC",
"power_supply_DC/VendorError",
"power_supply_DC/VendorWarning",
"evse_board_support/MREC2GroundFailure",
"evse_board_support/MREC3HighTemperature",
"evse_board_support/MREC4OverCurrentFailure",
"evse_board_support/MREC5OverVoltage",
"evse_board_support/MREC6UnderVoltage",
"evse_board_support/MREC8EmergencyStop",
"evse_board_support/MREC10InvalidVehicleMode",
"evse_board_support/MREC14PilotFault",
"evse_board_support/MREC15PowerLoss",
"evse_board_support/MREC17EVSEContactorFault",
"evse_board_support/MREC18CableOverTempDerate",
"evse_board_support/MREC19CableOverTempStop",
"evse_board_support/MREC20PartialInsertion",
"evse_board_support/MREC23ProximityFault",
"evse_board_support/MREC24ConnectorVoltageHigh",
"evse_board_support/MREC25BrokenLatch",
"evse_board_support/MREC26CutCable",
...
JSON Objects¶
EVSEInfoObj¶
This object contains static information about a EVSE of a charge point. This parameter is derived from the EvseManager identifier from the EVerest configuration. The “index” parameter is essential to perform EVSE specific method calls. The “id” parameter is the EVSE ID. The EVSE ID is a globally unique identifier defined in ISO 15118 to represent a specific EVSE. The “supported_energy_transfer_modes” must be used to distinguish between DC and AC charging. Depending on this, the optional parameters of object “EVSEStatusObj” are configured. In addition, it is possible to determine whether BPT is supported.
{
"index": "int",
"id": "string",
"description": "string", // optional
"available_connectors": "[ConnectorInfoObj]",
"supported_energy_transfer_modes": "[EnergyTransferModeEnum]"
}
EVSEStatusObj¶
This object contains all information about the current status of a charge point EVSE. These parameters change dynamically, depending on the current EVSE state, which is indicated by the “state” parameter. The parameters “ac_charge_param” and “ac_charge_status” are only configured in a AC charging session and parameters “dc_charge_param” and “dc_charge_status” are only configured in a DC charging session. These parameters mainly contain parameters that are transmitted in an HLC session. The connector info (e.g. to identify if it is a DC or AC charger) is part of object “EVSEInfoObj“. The “active_connector_index” information can also be used by GUI applications to display the active connector correctly.
{
"charged_energy_wh": "float",
"discharged_energy_wh": "float",
"charging_duration_s": "int",
"charging_allowed": "bool",
"available": "bool",
"active_connector_index": "int",
"error_present": "bool",
"charge_protocol": "$ChargeProtocolEnum",
"ac_charge_param": "$ACChargeParametersObj", // optional, only if AC supported
"dc_charge_param": "$DCChargeParametersObj", // optional, only if DC supported
"ac_charge_status": "$ACChargeStatusObj", // optional, only if AC supported
"dc_charge_status": "$DCChargeStatusObj", // optional, only if DC supported
"display_parameters": "$DisplayParametersObj",
"state": "$EVSEStateEnum"
}
ConnectorInfoObj¶
This object contains static information about a connector of an EVSE. This parameter is derived from the from the EVerest configuration. The “index” parameter is essential to perform connector specific method calls. The “type” must be used to distinguish between DC and AC charging. Depending on this, the optional parameters of object “EVSEStatusObj” are configured.
{
"index": "int",
"type": "ConnectorTypeEnum",
"description": "string" // optional
}
HardwareCapabilitiesObj¶
This object contains all hardware related limits of a charge point EVSE.
{
"max_current_A_export": "float",
"max_current_A_import": "float",
"max_phase_count_export": "int",
"max_phase_count_import": "int",
"min_current_A_export": "float",
"min_current_A_import": "float",
"min_phase_count_export": "int",
"min_phase_count_import": "int",
"phase_switch_during_charging": "bool"
}
MeterDataObj¶
This object contains the following meter data of a charge point EVSE:
timestamp: Timestamp of measurement, represented as RFC3339 string energy_Wh_import: Imported energy in Wh (from grid) meter_id: A (user defined) meter if (e.g. id printed on the case) serial_number: Serial number of the meter phase_seq_error: AC only: true for 3 phase rotation error (ccw) energy_Wh_export: Exported energy in Wh (to grid) power_W: Instantaneous power in Watt. Negative values are exported, positive values imported Energy. voltage_V: Voltage in Volts current_A: Current in Ampere frequency_Hz: Grid frequency in Hertz
{
"current_A": {"L1": "float","L2": "float","L3": "float","N": "float"},
"energy_Wh_import": {"L1": "float","L2": "float","L3": "float","total": "float"},
"energy_Wh_export": {"L1": "float","L2": "float","L3": "float","total": "float"}, // optional
"frequency_Hz": {"L1": "float","L2": "float","L3": "float"}, // optional
"meter_id": "string",
"serial_number": "string", // optional
"phase_seq_error": "bool", // optional
"power_W": {"L1": "float","L2": "float","L3": "float","total": "float"}, // optional
"timestamp": "string",
"voltage_V": {"L1": "float","L2": "float","L3": "float"} // optional
}
ACChargeParametersObj¶
This object contains all AC related parameters of a charge point EVSE. Parameters like “evse_maximum_discharge_power” are only transmitted if a BPT (bidirectional power transfer) session is active. Currently only “evse_max_current” and “evse_max_phase_count“ are supported.
{
"evse_nominal_voltage": "float",
"evse_max_current": "float",
"evse_max_phase_count": "int",
"evse_maximum_charge_power": "float",
"evse_minimum_charge_power": "float",
"evse_nominal_frequency": "float",
"evse_maximum_discharge_power": "float",
"evse_minimum_discharge_power": "float"
}
DCChargeParametersObj¶
Currently not supported.
This object contains all DC related parameters of a charge point EVSE. Parameters like “evse_maximum_discharge_power” are only transmitted if a BPT (bidirectional power transfer) session is active.
{
"evse_maximum_charge_current": "float",
"evse_maximum_charge_power": "float",
"evse_maximum_voltage": "float",
"evse_minimum_charge_current": "float",
"evse_minimum_charge_power": "float",
"evse_minimum_voltage": "float",
"evse_energy_to_be_delivered": "float",
"evse_maximum_discharge_current": "float",
"evse_maximum_discharge_power": "float",
"evse_minimum_discharge_current": "float",
"evse_minimum_discharge_power": "float"
}
ACChargeStatusObj¶
This object contains all DC related parameters of a charge point EVSE. Parameters like “evse_maximum_discharge_power” are only transmitted if a BPT (bidirectional power transfer) session is active. Currently only “evse_max_current” and “evse_max_phase_count“ are supported.
{
"evse_active_phase_count": "int"
}
DCChargeStatusObj¶
Currently not supported. This object contains all DC related parameters during charging of a charge point EVSE.
{
"evse_present_current": "float",
"evse_present_voltage": "float",
"evse_power_limit_achieved": "bool",
"evse_current_limit_achieved": "bool",
"evse_voltage_limit_achieved": "bool"
}
DisplayParametersObj¶
Currently not supported.
This object contains additional information which can be displayed in a GUI. These parameters are for display purposes only and must not, under any circumstances, influence the EVSE behavior. Most of the parameters are only transmitted in an ISO15118-20 charging session.
{
"start_soc": "int",
"present_soc": "int",
"minimum_soc": "int",
"target_soc": "int",
"maximum_soc": "int",
"remaining_time_to_minimum_soc": "int",
"remaining_time_to_target_soc": "int",
"remaining_time_to_maximum_soc": "int",
"charging_complete": "bool",
"battery_energy_capacity": "float",
"inlet_hot": "bool"
}
ChargerInfoObj¶
This object contains well-known general charger information, e.g. vendor and model name, firmware version etc.
{
"vendor": "string",
"model": "string",
"serial": "string",
"friendly_name": "string",
"manufacturer": "string",
"manufacturer_url": "string",
"model_url": "string",
"model_no": "string",
"revision": "string",
"board_revision": "string",
"firmware_version": "string"
}
ErrorObj¶
The ErrorObj structure represents a detailed description of an charger error. It includes the error type, origin, severity, and timestamp, along with optional context like EVSE or connector index. Each error is uniquely identified by a UUID and may include a vendor-specific ID and custom message.
{
"type": "string",
"sub_type": "string",
"message": "string",
"description": "string",
"origin": {
"module_id": "string",
"implementation_id": "string",
"evse_index": "int", // optional
"connector_index": "int" // optional
},
"vendor_id": "string",
"severity": "SeverityEnum",
"timestamp": "string",
"uuid": "string"
}
What can a simple sequence look like?¶
The sequence diagram below is a simple sequence diagram based on the defined WebSocket methods and notifications. The diagram is simplified for better visualization and therefore only shows the relevant parameters within the objects.
Initialization¶
The first diagram illustrates how a client establishes a connection to the server and how the server initializes a single EVSE. After that, the client application is prepared to process incoming notifications of the API, for example caused by plugging in an EV.
Session handling¶
The second sequence diagram shows the notifications that are triggered as soon as an EV is plugged in and recognized by the EVSE. It also shows how the client can actively adjust the charging current of a running session.
