OCPP.md — Open Charge Point Protocol Reference for AI Agents

Purpose: This file provides structured context about the OCPP protocol for AI agents working on EV charging infrastructure. It is not a replacement for the official specification but a practical reference to ground AI-assisted development, integration, and troubleshooting.

Last updated: 2026-02-08
Primary spec covered: OCPP 2.0.1 (Part 1: Architecture & Topology, Part 2: Specification)

Source on Github.

#1. What is OCPP?

OCPP (Open Charge Point Protocol) is an open application-level protocol for communication between Electric Vehicle (EV) Charging Stations (also called Charge Points) and a Charging Station Management System (CSMS, formerly called Central System). It is developed and maintained by the Open Charge Alliance (OCA).

OCPP enables interoperability: a charge point from vendor A can be managed by a CSMS from vendor B, as long as both implement OCPP correctly.

#Version History

#Companion Documents

This reference is part of a larger documentation set:

• Smart Charging Deep-Dive — Profile model, composite schedule calculation, AC/DC differences, grid integration, common pitfalls. Includes Examples and ISO 15118 integration.
• Message Sequences — Boot sequence, authorization flows, transaction lifecycle. Includes Operational Sequences (reservation, offline behavior, firmware, diagnostics).
• Data Types Reference — All reusable composite types and enumerations, plus field-level schemas for all 64 messages.
• Methodology — How these documents were produced, provenance tiers, and trust model.
• AI Agent Setup — Full configuration guide for using this reference as a Claude Code plugin.

#2. Architecture Overview (OCPP 2.0.1)

#2.1 Roles

• Charging Station (CS): The physical device that charges EVs. Contains one or more EVSEs.
• CSMS (Charging Station Management System): The backend/server that manages charging stations remotely.

Communication is initiated by the Charging Station, which opens a persistent WebSocket connection to the CSMS. Both sides can then send messages over this connection.

#2.2 Device Model

OCPP 2.0.1 introduced a hierarchical device model:

Charging Station
├── EVSE 1 (Electric Vehicle Supply Equipment)
│   ├── Connector 1 (e.g., CCS)
│   └── Connector 2 (e.g., CHAdeMO)
├── EVSE 2
│   └── Connector 1 (e.g., Type 2)
└── ...

• Charging Station is the top-level entity. It has a single connection to the CSMS.
• EVSE represents a separately controllable charging spot. Each EVSE can charge one EV at a time.
• Connector is a physical socket/plug. An EVSE may have multiple connectors, but only one can be active at a time.

Important: In OCPP 2.0.1, evseId and connectorId are 1-indexed integers. evseId=0 refers to the Charging Station as a whole (used in certain messages like status notifications).

#2.3 Transport

• WebSocket (RFC 6455) over TLS (wss://)
• Sub-protocol: ocpp2.0.1
• The Charging Station connects to the CSMS at a URL like: wss://csms.example.com/ocpp/<charging_station_id>
• The Charging Station ID is typically included in the WebSocket URL path.
• JSON-RPC-like message framing (see Section 3).

#2.4 Security Profiles

OCPP 2.0.1 defines three security profiles:

#3. Message Structure (RPC Framework)

OCPP uses a JSON-based RPC framework over WebSocket. There are three message types:

#3.1 CALL (Request)

[2, "<messageId>", "<action>", {<payload>}]

• 2 — MessageTypeId for CALL
• messageId — Unique string identifier for this request (used to correlate response)
• action — The name of the operation (e.g., "BootNotification", "Authorize")
• payload — JSON object with the request parameters

#3.2 CALLRESULT (Response)

[3, "<messageId>", {<payload>}]

• 3 — MessageTypeId for CALLRESULT
• messageId — Must match the CALL it responds to
• payload — JSON object with the response data

#3.3 CALLERROR (Error Response)

[4, "<messageId>", "<errorCode>", "<errorDescription>", {<errorDetails>}]

• 4 — MessageTypeId for CALLERROR
• Standard error codes include: NotImplemented, NotSupported, InternalError, ProtocolError, SecurityError, FormatViolationError, PropertyConstraintViolation, OccurrenceConstraintViolation, TypeConstraintViolation, GenericError

#3.4 Message Flow Rules

• Only one CALL can be outstanding at a time per direction (CS→CSMS or CSMS→CS). A new CALL must not be sent until a CALLRESULT or CALLERROR is received for the previous one.
• Both sides can initiate CALLs independently since the connection is bidirectional.
• Messages initiated by the CS are called CS→CSMS messages; messages initiated by the CSMS are CSMS→CS messages.

#4. Key Messages (OCPP 2.0.1)

#4.1 Provisioning & Lifecycle

#4.2 Authorization

idToken types: Central, eMAID, ISO14443, ISO15693, KeyCode, Local, MacAddress, NoAuthorization

AuthorizationStatus values: Accepted, Blocked, ConcurrentTx, Expired, Invalid, NoCredit, NotAllowedTypeEVSE, NotAtThisLocation, NotAtThisTime, Unknown

#4.3 Transactions

OCPP 2.0.1 uses a simplified transaction model compared to 1.6.

#TransactionEvent Details

TransactionEvent replaces the old StartTransaction, StopTransaction, and MeterValues from OCPP 1.6. It carries:

• eventType: Started, Updated, Ended
• triggerReason: Authorized, CablePluggedIn, ChargingRateChanged, ChargingStateChanged, Deauthorized, EnergyLimitReached, EVCommunicationLost, EVConnectTimeout, MeterValueClock, MeterValuePeriodic, TimeLimitReached, Trigger, UnlockCommand, StopAuthorized, EVDeparted, EVDetected, RemoteStart, RemoteStop, AbnormalCondition, SignedDataReceived, ResetCommand
• transactionInfo: Contains transactionId (string, assigned by CS), chargingState (Charging, EVConnected, SuspendedEV, SuspendedEVSE, Idle), and optionally stoppedReason and remoteStartId.
• meterValue: Array of sampled meter values (energy, power, current, voltage, SoC, etc.)
• idToken: The token used for authorization.
• evse: Which EVSE the transaction is on.

#Transaction Lifecycle (typical flow)

1. User presents RFID → CS sends Authorize
2. CSMS responds Accepted
3. User plugs in cable
4. CS sends TransactionEvent(Started, triggerReason=Authorized)
5. Charging begins → periodic TransactionEvent(Updated, triggerReason=MeterValuePeriodic)
6. User stops → TransactionEvent(Ended, triggerReason=StopAuthorized)

#4.4 Metering

Meter values are embedded within TransactionEvent messages (not sent as separate MeterValues messages as in 1.6).

A MeterValue contains a timestamp and an array of sampledValue entries, each with:

• value — decimal number
• measurand — Energy.Active.Import.Register (Wh, cumulative), Power.Active.Import (W), Current.Import (A), Voltage (V), SoC (%), Frequency (Hz), and more
• phase — L1, L2, L3, N, L1-N, L2-N, L3-N, L1-L2, L2-L3, L3-L1 (optional)
• context — Transaction.Begin, Sample.Periodic, Sample.Clock, Transaction.End, Trigger, Interruption.Begin, Interruption.End
• location — Body, Cable, EV, Inlet, Outlet
• unitOfMeasure — e.g., { unit: "Wh", multiplier: 0 }

#4.5 Smart Charging

Deep-dive: For comprehensive coverage of smart charging — profile model, composite schedule calculation, AC/DC differences, grid integration, and common pitfalls — see the Smart Charging Deep-Dive, Examples, and ISO 15118 integration.

Smart charging allows the CSMS to control how much power/current a CS delivers.

#Charging Profile Structure

{
  "id": 1,
  "stackLevel": 0,
  "chargingProfilePurpose": "TxDefaultProfile",
  "chargingProfileKind": "Recurring",
  "recurrencyKind": "Daily",
  "chargingSchedule": [{
    "id": 1,
    "chargingRateUnit": "A",
    "chargingSchedulePeriod": [
      { "startPeriod": 0, "limit": 32.0 },
      { "startPeriod": 28800, "limit": 16.0 },
      { "startPeriod": 72000, "limit": 32.0 }
    ]
  }]
}

Profile purposes (stack priority, highest first):

1. ChargingStationExternalConstraints — Grid operator / external limits
2. ChargingStationMaxProfile — Max power for entire station
3. TxDefaultProfile — Default for transactions on an EVSE
4. TxProfile — Specific to an active transaction

Profiles at the same purpose level use stackLevel to determine priority (higher wins).

#4.6 Firmware Management

#4.7 Diagnostics & Logging

#4.8 Reservation

#4.9 Remote Triggers

#4.10 Certificate Management

#4.11 Local Auth & Display

#4.12 Data Transfer

#5. Functional Blocks

OCPP 2.0.1 organizes features into Functional Blocks that can be independently supported:

#6. Key Configuration Variables

OCPP 2.0.1 uses a Component/Variable model for configuration. Some important ones:

#7. OCPP 1.6 vs 2.0.1 — Key Differences

This section is useful for agents working on migrations or systems that support both versions.

#1.6 Message → 2.0.1 Mapping

#8. Common Implementation Patterns

Deep-dive: For detailed sequence diagrams covering boot loops (Pending/Rejected), authorization with groupId/parent tokens, full transaction lifecycle, reservations, offline queueing, and firmware updates — see the Message Sequences and Operational Sequences.

#8.1 Boot Sequence

CS                                  CSMS
 |                                    |
 |--- WebSocket Connect ------------->|
 |--- BootNotification --------------->|
 |<-- BootNotificationResponse --------|  (status: Accepted/Pending/Rejected)
 |                                    |
 |--- StatusNotification (per conn) -->|  (report connector statuses)
 |                                    |
 |--- Heartbeat ---------------------->|  (periodic, per interval from boot response)

If BootNotificationResponse.status is Pending, the CS should retry after the interval and must not send any other messages except BootNotification until Accepted. If Rejected, the CS should retry but at the given interval.

#8.2 Offline Behavior

When the CS loses connection to the CSMS:

• It should queue TransactionEvent messages and replay them in order upon reconnection.
• It can use the Local Authorization List or Authorization Cache for offline authorization.
• Configuration variable OfflineTxForUnknownIdEnabled controls whether unknown tokens can start transactions offline.

#8.3 Reconnection Strategy

The CS should implement exponential backoff when reconnecting:

• Wait at least RetryBackOffWaitMinimum seconds
• Add a random value between 0 and RetryBackOffRandomRange
• Repeat up to RetryBackOffRepeatTimes times
• This prevents thundering herd when a CSMS restarts and many stations reconnect simultaneously.

#9. JSON Schema Validation

All OCPP 2.0.1 messages have JSON Schemas published by OCA. Implementations should validate incoming messages against these schemas. The schemas define:

• Required vs optional fields
• Data types and formats (e.g., dateTime in RFC 3339 format)
• String length constraints
• Enum values
• Nested object structures

Schemas are available from the OCA website and are typically named like BootNotificationRequest.json, BootNotificationResponse.json, etc.

#Detailed Schema Reference

Complete field-level documentation for all 64 messages (request + response) is available in these companion files:

• Data Types Reference — All reusable composite types and enumerations
• Provisioning — BootNotification, Heartbeat, GetVariables, SetVariables, Reset, DataTransfer, etc.
• Authorization — Authorize, SendLocalList, GetLocalListVersion, ClearCache
• Transactions — TransactionEvent, RequestStartTransaction, RequestStopTransaction, MeterValues
• Smart Charging — SetChargingProfile, GetChargingProfiles, GetCompositeSchedule, etc.
• Firmware — UpdateFirmware, PublishFirmware, FirmwareStatusNotification
• Security — Certificates, CSR signing, ISO 15118
• Diagnostics — GetLog, NotifyEvent, variable monitoring
• Availability — ChangeAvailability, UnlockConnector, TriggerMessage
• Reservation — ReserveNow, CancelReservation
• Display — SetDisplayMessage, CostUpdated, etc.

#10. Testing & Compliance

• OCA Compliance Testing — The Open Charge Alliance provides a compliance testing tool and test cases.
• OCTT (OCPP Compliance Testing Tool) — Official tool for validating OCPP implementations.
• Common test scenarios include: boot sequence, authorization flows, transaction lifecycle, offline behavior, smart charging profile application, firmware update, and security profile negotiation.

#11. Useful Resources

• OCA Official Site: https://openchargealliance.org
• OCPP 2.0.1 Specification: Available for download from OCA (requires free registration)
• OCPP 2.0.1 JSON Schemas: Published alongside the specification
• OCA GitHub: Example implementations and schemas

#12. Using with AI Coding Agents

This reference is available as a Claude Code plugin. Install it once and your AI assistant gets structured OCPP 2.0.1 knowledge in every project.

#Quick Setup

/plugin marketplace add https://github.com/alexeimoisseev/ocpp.md
/plugin install ocpp@ocpp

Once installed, the plugin activates automatically when working with OCPP code. You can also invoke it directly:

/ocpp                    # General OCPP assistance
/ocpp smart-charging     # Smart charging deep-dive
/ocpp transactions       # Transaction handling
/ocpp authorize          # Authorization flow

#What the Agent Gets

The plugin provides a hybrid reference: a compact inline summary (all 64 messages, key types, escalation model) is always available, while detailed schemas, sequence diagrams, and worked examples are loaded on demand when needed.

#Escalation Handling

The OCPP spec has areas that are silent, vendor-dependent, or policy-dependent. The plugin prevents the agent from silently guessing in these areas. By default it uses strict mode (stops and asks). To switch to pragmatic mode, add to your CLAUDE.md:

For OCPP: use pragmatic escalation mode.

• strict (default) — agent stops and asks before making assumptions
• pragmatic — agent flags ambiguity with a code comment but picks a reasonable default

See the full AI Agent Setup guide for manual installation and detailed configuration.

#13. Glossary

This document is a community reference for AI agents. It is not affiliated with or endorsed by the Open Charge Alliance. For the authoritative specification, refer to the official OCPP 2.0.1 documents from OCA.