OCPP In-Depth Guide

The Charge Controller family implements the OCPP standard based on the official OCPP 1.6 standard defined by the Open Charge Alliance. Download relevant documents from the Open Charge Alliance website.

• OCPP 1.6
• OCA ISO 15118 (scroll down to "Application Notes")
• Secure transfer of the Eichrecht OCPP public key via hastobe spec
• EVSE Check V3

1. Setting up the connection and verifying it

1. Basic Requirements

   • Valid ChargePointID (found under BACKEND > OCPP)
   • Working network connection (GSM, Ethernet, or WLAN)
   • OCPP backend URL (format: ws://backend:8080/OCPPJProxy/v16/)

2. Connection Verification

   • Check BACKEND > Connection Status
   • Verify heartbeat messages are being sent/received
   • Confirm transaction messages are flowing

2. Troubleshooting guide

2.1. Common connection issues

1. No Backend Connection

   • Check network connectivity (ping test)
   • Verify ChargePointID is correct
   • Confirm backend URL format
   • Check SSL certificates if using WSS

2. Connection Drops

   • Check network stability
   • Verify heartbeat interval settings
   • Monitor system logs for timeout errors

3. Authentication Failures

   • Verify basic auth credentials
   • Check authorization key format
   • Confirm OCPP version compatibility

2.2. Diagnostic Steps

1. Check real-time logs:

   • DIAGNOSTICS > OCPP Status
   • DIAGNOSTICS > System Logs

2. Verify network settings:

   • BACKEND > Connection Type
   • NETWORK > Configuration

3. Test backend communication:

   • Initiate test transaction
   • Monitor message exchange
   • Check error responses

3. Supported feature profiles

Feature profile	Features	Compliance	Info
The Charge Controller family provides mature support for the OCPP 1.6 protocol.
Some specifications leave room for propietary implementations. Where this is the case, details are outlined.

Feature profile	Features	Compliance	Info
Core	Authorize BootNotification ChangeAvailability ChangeConfiguration ClearCache DataTransfer GetConfiguration Heartbeat MeterValues RemoteStartTransaction RemoteStopTransaction Reset StartTransaction StatusNotification StopTransaction UnlockConnector	compliant	Basic Charge Station functionality comparable with OCPP 1.5 without support for firmware updates, local authorization list management and reservations.
Firmware Management	GetDiagnostics DiagnosticsStatusNotification FirmwareStatusNotification UpdateFirmware	compliant	Support for firmware update management and diagnostic log file download
Local Auth List Management	GetLocalListVersion SendLocalList	compliant	Features to manage the local authorization list in Charge Stations
Reservation	CancelReservation ReserveNow	compliant	Support for reservation of a Charge Station
Smart Charging	ClearChargingProfile GetCompositeSchedule SetChargingProfile	compliant	Support for basic Smart Charging, for instance using control pilot
Remote Trigger	TriggerMessage	compliant (proprietary implementation)	Support for remote triggering of Charge Station messages
Firmware Management	GetDiagnostics DiagnosticsStatusNotification FirmwareStatusNotification UpdateFirmware	compliant	Support for firmware update management and diagnostic log file download
Local Auth List Management	GetLocalListVersion SendLocalList	compliant	Features to manage the local authorization list in Charge Stations
Reservation	CancelReservation ReserveNow	compliant	Support for reservation of a Charge Station
Smart Charging	ClearChargingProfile GetCompositeSchedule SetChargingProfile	compliant	Support for basic Smart Charging, for instance using control pilot
Remote Trigger	TriggerMessage	compliant (proprietary implementation)	Support for remote triggering of Charge Station messages

4. Supported messages based on "Open Charge Point Protocol 1.6"

Message	"Open Charge Point Protocol 1.6" (edition 2 FINAL, 2017-09-28) chapter numbers
Authorize	Ch. 6.1 — 6.2
BootNotification	Ch. 6.3 — 6.4
CancelReservation	Ch. 6.5 — 6.6
ChangeAvailability	Ch. 6.7 — 6.8
ChangeConfiguration	Ch. 6.9 — 6.10
ClearCache	Ch. 6.11 — 6.12
ClearChargingProfile	Ch. 6.13 — 6.14
DataTransfer	Ch. 6.15 — 6.16
DiagnosticsStatusNotification	Ch. 6.17 — 6.18
FirmwareStatusNotification	Ch. 6.19 — 6.20
GetCompositeSchedule	Ch. 6.21 — 6.22
GetConfiguration	Ch. 6.23 — 6.24
GetDiagnostics	Ch. 6.25 — 6.26
GetLocalListVersion	Ch. 6.27 — 6.28
Heartbeat	Ch. 6.29 — 6.30
MeterValues	Ch. 6.31 — 6.32
RemoteStartTransaction	Ch. 6.33 — 6.34
RemoteStopTransaction	Ch. 6.35 — 6.36
ReserveNow	Ch. 6.37 — 6.38
Reset	Ch. 6.39 — 6.40
SendLocalList	Ch. 6.41 — 6.42
SetChargingProfile	Ch. 6.43 — 6.44
StartTransaction	Ch. 6.45 — 6.46
StatusNotification	Ch. 6.47 — 6.48
StopTransaction	Ch. 6.49 — 6.50
TriggerMessage	Ch. 6.51 — 6.52
UnlockConnector	Ch. 6.53 — 6.54
UpdateFirmware	Ch. 6.55 — 6.56

5. Supported messages based on "Using ISO 15118 Plug & Charge with OCPP 1.6"

Request message	"Using ISO 15118 Plug & Charge with OCPP 1.6" (v1.0, 2020-09-16) chapter numbers
Authorize	Ch. 6.1.1 — 6.1.2
CertificateSigned	Ch. 6.2.1 — 6.2.2
DeleteCertificate	Ch. 6.3.1 — 6.3.2
Get15118EVCertificate	Ch. 6.4.1 — 6.4.2
GetCertificateStatus	Ch. 6.5.1 — 6.5.2
GetInstalledCertificateIds	Ch. 6.6.1 — 6.6.2
InstallCertificate	Ch. 6.7.1 — 6.7.2
SignCertificate	Ch. 6.8.1 — 6.8.2
TriggerMessage	Ch. 6.9.1 — 6.9.2

6. List of all configuration keys and equivalent Config UI labels

7. OCPP-relevant configuration parameters in Config UI

Category	Parameter	Purpose	Cleaned-up Remarks
General	Connection Type	Physical connection method for OCPP Backend communication	Defines the preferred connection method, but if both Ethernet and GSM are active, Ethernet is always used automatically. If no Backend is configured, no OCPP communication occurs.
	OCPP ChargeBoxIdentity (ChargePointID)	Unique identifier for the Charge Controller	Required for proper communication with the OCPP backend.
	OCPP Mode	Defines the OCPP version and transport protocol	Always set to <Value>OCPP-J 1.6</Value>.
	WebSockets JSON OCPP URL of the Backend	URL of the OCPP central system for WebSocket	Use the format ws://backend:8080/OCPP/v16/. Do not include the ChargePointID in the URL, even if some backends suggest it.
	WebSockets proxy	Proxy server for WebSocket connections	Optional WebSocket proxy in the format HOST:PORT. If no port is given, 80 is used by default.
	WebSockets keep-alive interval	Interval for WebSocket ping messages	Value in seconds (0–10000). Use 60 seconds to help maintain connection stability. Use this if the backend connection drops unexpectedly.
Security	OCPP connection strictness	Security level for OCPP connections	Sets minimum encryption standard. Use only-secure-cyphers when possible. Set to all-cyphers if the backend doesn't support modern encryption.
	HTTP Basic Authentication password	Password for OCPP authentication	Used if required by the backend. Username is automatically set to the ChargePointID.
Connection Behavior	Force Heartbeat request messages	Whether to force sending heartbeat messages	Some backends need this to maintain a stable connection. Enable if you witness frequent disconnects.
	TCP Watchdog Timeout	Timeout for TCP connection monitoring
	Display backend disconnect as error	Whether to show disconnection as an error
StatusNotification	Send informative StatusNotifications	Whether to send informational status updates	Sends additional status info, helpful for debugging or to enhance backend insights.
	Send error StatusNotifications	Whether to send error status updates	Enables more detailed error reporting to the backend.
	Send USB error StatusNotifications	Whether to send USB-specific error updates	Controls if USB-related errors are reported to the backend.
Maintenance & UI Events	State 'unavailable' at FW update begin	Set status to unavailable during firmware updates
	Force OCPP connector state	Override connector availability state
	Send status for webui login event	Send notification when web UI is accessed	Sends an info-level status message to the backend when someone logs into the web UI.
Compatibility & Legacy	Strategy for StatusNotification	When to change connector status to Occupied	Deprecated. Legacy setting from OCPP 1.5. Can be ignored.
	Allow long get configuration keys	Support for longer configuration key names
	Integer values for boolean config keys	Use integers instead of booleans in responses
Retry & Timeout Settings	Backend connection timeout	Timeout for OCPP connection attempts
	Number of transaction message attempts	Retries for transaction messages
	Eichrecht transaction message attempts	Retries for Eichrecht-specific messages
	Disallow charging if OCPP queue full	Block charging when message queue is full
	SSL Strictness as client	SSL/TLS security level
Metering & Reporting	DataTransfer for Tariff And Total Usage	Send tariff and usage data via DataTransfer
	Meter values sampled data (OCPP)	Meter values to be sent based on sampling interval
	Meter Value Sample Interval (OCPP)	Time between meter value samples
	Meter values aligned data (OCPP)	Meter values to be sent at regular intervals
	Clock aligned data interval (OCPP)	Interval for clock-aligned meter values
	Retransmit MeterValues	Whether to retry sending meter values

8. OCPP-Relevant Configuration Parameters

Category	Parameter	Purpose	Cleaned-up Remarks
General Connectivity	Connection Type	Physical connection method for OCPP Backend communication	Defines the preferred connection method. If both Ethernet and GSM are active, Ethernet is always used automatically. If no Backend is configured, no OCPP communication occurs.
	OCPP ChargeBoxIdentity (ChargePointID)	Unique identifier for the Charge Controller	Required for proper communication with the OCPP backend.
	OCPP Mode	Defines the OCPP version and transport protocol	Always set this to OCPP-J 1.6.
	WebSockets JSON OCPP URL of the Backend	URL of the OCPP central system for WebSocket	Use the format ws://backend:8080/OCPP/v16/. Do not include the ChargePointID in the URL, even if some backends suggest it.
	WebSockets proxy	Proxy server for WebSocket connections	WebSocket proxy in the format HOST:PORT. If no port is given, 80 is used by default.
	WebSockets keep-alive interval	Interval for WebSocket ping messages	Value in seconds (0–10000). Use 60 seconds to help maintain connection stability. Use this if the backend connection drops unexpectedly. More
Security & Authentication	OCPP connection strictness	Security level for OCPP connections	Sets minimum encryption standard. Use only-secure-cyphers when possible. Set to all-cyphers if the backend doesn't support modern encryption.
	HTTP Basic Authentication password	Password for OCPP authentication	Used if required by the backend. Username is automatically set to the ChargePointID.
	Send status for webui login event	Send notification when web UI is accessed	Sends an info-level status message to the backend when someone logs into the web UI. More
	SSL Strictness as client	SSL/TLS security level	Set to Skip host check if DNS server fails and you use IP addresses in place of domain names. More
Connection Behavior	Force Heartbeat request messages	Whether to force sending heartbeat messages	Some backends need this to maintain a stable connection. Enable if you witness frequent disconnects.
	TCP Watchdog Timeout	Timeout for TCP connection monitoring	If the TCP Watchdog Timeout is reached and the Backend cannot be reached, a reboot on the Charge Controller is triggered. More
	Backend connection timeout	Timeout for OCPP connection attempts	(OCPP standard: BackendConnectionTimeout). Default: 60s. Range: 3-300s. Full behavior details
	Disallow charging if OCPP queue full	Block charging when message queue is full	Charging is blocked when the internal OCPP message queue is full. Prevents new sessions that would result in message loss — especially critical for Eichrecht compliance. More
	Display backend disconnect as error	Whether to show disconnection as an error on the HMI	Error is shown on the HMI in case a Backend is configured but connection fails.
StatusNotification Control	Send informative StatusNotifications	Whether to send informational status updates	Sends additional status info, helpful for debugging or to enhance backend insights. More
	Send error StatusNotifications	Whether to send error status updates	Enables more detailed error reporting to the backend. More
	Send USB error StatusNotifications	Whether to send USB-specific error updates	Controls if USB-related errors are reported to the backend. More
	State 'unavailable' at FW update begin	Set status to unavailable when firmware is being downloaded
Maintenance & Overrides	Force OCPP connector state	Override connector availability state	Overrides the connector availability state regardless of Backend-side state.
Compatibility & Legacy	Strategy for StatusNotification	When to change connector status to Occupied	Deprecated. Legacy setting from OCPP 1.5. Can be ignored.
	Allow long get configuration keys	Extends the max. length of configuration key values to 500+ characters	Allows more than the OCPP standard for the value length of GetConfiguration requests. Needed for proprietary certificate exchange.
	Integer values for boolean config keys	Use integers instead of booleans in responses	(Deprecated) Scoped to standard OCPP configuration key values. Behavior to output those values as integer is deprecated.
Retry Logic	Number of transaction message attempts	Retries for transaction messages	Used for all transaction-related messages except Eichrecht-bound ones. More
	Eichrecht transaction message attempts	Retries for Eichrecht-specific messages	Used only if Eichrecht is active and message is Start/Stop/MeterValues tied to a transaction. More
Metering & Reporting	DataTransfer for Tariff And Total Usage	Send tariff and usage data via DataTransfer
	Meter values sampled data (OCPP)	Meter values to be sent based on sampling interval
	Meter Value Sample Interval (OCPP)	Time between meter value samples
	Meter values aligned data (OCPP)	Meter values to be sent at regular intervals
	Clock aligned data interval (OCPP)	Interval for clock-aligned meter values
	Retransmit MeterValues	Whether to retry sending meter values	When enabled, transaction-bound MeterValues are held in the queue and retried until success or limit reached. Affects queue size and charging availability. More

9. In-Depth Explanations

9.1. Connectivity keep-alive troubleshooting

Purpose: Maintain a persistent connection with the OCPP backend.

Details:

• If your backend frequently disconnects, try enabling Force Heartbeat and/or lowering the WebSockets keep-alive interval to 60 seconds.
• This setting works alongside the TCP watchdog.
• Pings sent prevent NAT/firewall timeout issues in some networks.

9.2. Informative StatusNotifications

Controlled by: Send informative StatusNotifications (INFO_STATUS_NOTIFICATIONS)

Details:

• Sends info-level updates like:

  • Energy flow start/stop
  • Temperature readings
  • Web UI logins
  • GPIO state changes

• Useful for debugging, UI feedback, and backend analytics.

• Does not include error-level data.

Triggered Informational StatusNotifications:

• Energy Flow:

  • "Energy is flowing to vehicle"
  • "No energy flowing to vehicle"
  • "Energy flow to vehicle is unknown"

• Temperature Reports:

  • "Temperatures: CPU: [temp] RFID: [temp]"
  • "Charging paused. Temperature: +XX.X C"
  • "Signaled current reduced. Temperature: +XX.X C"
  • "Signaled current back to nominal. Temp: +XX.X C"

• Ventilation & Heating: State change notifications

• Web UI Login Events: If enabled

• GPIO State Changes: Depends on related GPIO notify setting

• Triggered by backend: "Triggered status report" via TriggerMessage

9.3. Error StatusNotifications

Controlled by: Send error StatusNotifications (ERROR_STATUS_NOTIFICATIONS)

Examples of Static Info Strings:

• "Residual current detected via sensor"
• "Vehicle signals error"
• "Vehicle diode check failed - tamper detection"
• "MCB of type 2 socket triggered"
• "RCD may be triggered (OCPP meter power loss)"
• "Contactor welded"
• "Plug locking failed"
• "Housing temperature too high - charging paused"
• "Temperature reaches safety limit - emergency stop"
• "GSM SIM card is missing"
• "USB communication errors."
• "Message queue is full"

Examples of Dynamic Info Strings:

• GSM signal strength: gsm_get_ocpp_status_info_string()
• Firmware update status: net_firmware_get_status_info_string()
• USB hotplug: usb_hotplug_progress_string()
• Phase errors: phase_monitor_get_phase_err_msg()
• Internal diagnostics: component manager, PIC24, etc.

9.4. USB error StatusNotifications

Controlled by: Send USB error StatusNotifications (USB_ERROR_STATUS_NOTIFICATIONS)

• Sends:

  • "USB communication errors."
  • "USB stick handling: Finalized - Remove USB stick"
  • "USB stick handling failed - Remove USB stick"

• Often sent together with log file diagnostics or update failures

9.5. SSL strictness and IP address use

Problem: When using IP addresses instead of domain names, TLS certificate validation fails due to hostname mismatch.

Solution:

• Set SSL Strictness as client to Skip host check
• This disables hostname validation but maintains encryption

9.6. Backend connection timeout details

Parameter: Backend connection timeout (BackendConnectionTimeout)

Default: 60s Range: 3–300s

Behavior:

• Used for:

  • APN and proxy connection timeout
  • OCPP request-response timeout

• Retries use exponential backoff:

  • Timeout doubles per failure (±20% jitter)
  • Max delay: 12h (43,200s)
  • After max: triggers reboot

• Volatile messages are discarded after timeout

• Persistent messages are retried

• Triggers backend reset via tcpip_comm_manage_generic_error(0)

9.7. TCP watchdog timeout

Parameter: TCP Watchdog Timeout

Purpose:

• Acts as a global failsafe
• If no TCP activity over a long period, reboot is triggered
• Log example: "No tcp connection for long time. Rebooting"

9.8. OCPP queue full behavior

Parameter: Disallow charging if OCPP queue full

Name: OCPP_QUEUE_FULL_AS_ERROR_STATE (OCPP: "OcppQueueFullAsErrorState") Default: OFF Type: ON/OFF option File: ocpp_logic_parameters.c:1370–1383

Purpose:

• Charging is blocked if the internal OCPP message queue is full
• Prevents starting new sessions that would generate unsent messages
• Especially important for Eichrecht-compliant operations

9.9. Queue implementation and limits

Total queue capacity:

• 350 messages maximum: Hard-coded limit (PERS_LIST_ELEM_NUM_MAX)
• 70 message threshold for StatusNotifications: If 70+ items in queue, additional StatusNotifications are suppressed (PERS_LIST_ELEM_NUM_MSG_LIMIT)

Technical Behavior:

• Before sending any new message, the system checks queue fullness

• If full:

  • A log warning is created
  • The message is discarded silently
  • If the feature is enabled: triggers error state ERR_OCPP_MSG_QUEUE_FULL
  • Error marked as pause_during_error = 1, which blocks or stops charging

Error state properties:

• OCPP Status: "Message queue is full"
• Internal Code: 01-05-006
• Recovery trigger: Queue no longer full
• Recovery behavior: Clears error and automatically resumes charging

9.10. Charging impact

• When queue is full and this setting is enabled:

  • Charging stops
  • New sessions cannot start
  • State persists until queue drains

• When disabled:

  • Queue full only suppresses new messages silently, does not affect charging

9.11. Operational Notes

• Message queue stats are not visible in the UI
• May correlate with watchdog reboots or intermittent disconnects
• When queue is full, all message types compete for limited space
• Retransmissions (like MeterValues) hold up queue until backend responds

9.12. Recommendations

• Enable only in legally constrained scenarios
• Avoid on unstable connections unless retries are optimized
• Use with infinite retry for transaction messages to prevent data loss

9.13. Transaction message retry logic

Parameter: TRANSACTION_MESSAGE_ATTEMPTS (OCPP: "TransactionMessageAttempts")

Default: 5 attempts Range: 0–5 attempts Special value: 0 = infinite retries File: ocpp_logic_parameters.c:1293-1311

Behavior:

• Applies when Eichrecht is not active

• Retries are limited to the value set in the parameter

• When retries are exhausted:

  1. Message is logged as deleted
  2. Removed from persistent queue
  3. Memory is freed
  4. No error state is triggered — message is silently dropped

Retry Interval:

• Controlled by TRANSACTION_MESSAGE_RETRY_INTERVAL (OCPP: "TransactionMessageRetryInterval")
• Default: 0 seconds
• Range: 0–1000 seconds
• Sets how long the ChargePoint waits before resubmitting a transaction-relevant message
• File: ocpp_logic_parameters.c:1334–1350

Transaction-Relevant Messages Include:

• StartTransaction
• StopTransaction
• MeterValues with transaction ID
• (Also TransactionEvent in OCPP 2.0)

9.14. Eichrecht transaction message attempts

Parameter: EICHRECHT_TRANSACTION_MESSAGE_ATTEMPTS (OCPP: "EichrechtTransactionMessageAttempts")

Default: 0 (infinite retries) Range: -1 to 5 Special values:

• 0: Infinite retries
• -1: Use value of TRANSACTION_MESSAGE_ATTEMPTS File: ocpp_logic_parameters.c:1312–1332

Applies when:

• Eichrecht is active AND

• Message is:

  • StartTransaction
  • StopTransaction
  • MeterValues with transaction ID

Priority behavior:

if (eichrecht_is_active() && ocpp_client_is_message_transaction_relevant(message, 0))
    return PS_GET(EICHRECHT_TRANSACTION_MESSAGE_ATTEMPTS, unsigned int);
return PS_GET(TRANSACTION_MESSAGE_ATTEMPTS, unsigned int);

Eichrecht active condition:

• Eichrecht-certified meter is selected (eHZ, DZG, etc.) OR
• System is in Eichrecht locked state File: eichrecht.c:216–227

Fallback logic:

• If parameter = -1 → use TRANSACTION_MESSAGE_ATTEMPTS

9.15. Retransmit MeterValues (cross-linked with queue behavior)

Parameter: Retransmit MeterValues

Purpose: Determines whether MeterValues messages are retried upon backend failure.

Behavior:

• When enabled:

  • MeterValues with transaction ID are treated as persistent
  • Retried according to transaction message attempt logic (TransactionMessageAttempts, EichrechtTransactionMessageAttempts)
  • Held in queue until successfully sent or max attempts exceeded
  • Increases queue pressure, see OCPP queue full behavior

• When disabled:

  • MeterValues are considered volatile
  • If backend is unreachable, messages are dropped immediately after timeout

Dependencies:

• Queue size: 350 message limit affects retried MeterValues
• If queue is full and OcppQueueFullAsErrorState is enabled, charging is blocked (see Queue full behavior)
• Retransmit setting only applies to transaction-bound MeterValues

Implementation:

• Retransmission logic tied to message persistence flag
• Controlled via config UI flag or internal preset
• File references: ocpp_client.c, persistent_list.c

Recommendation:

• Enable in Eichrecht or legally regulated environments
• Disable in unstable networks where queue overflow is a risk

see CANNED response on this if existing

-->