The Developer's Guide to OCPP 2.0.1

OCPP 2.0.1 — Open Charge Point Protocol

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.

Primary spec covered: OCPP 2.0.1 (Part 1: Architecture & Topology, Part 2: Specification)

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

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

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

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:

1. Wait at least RetryBackOffWaitMinimum seconds
2. Add a random value between 0 and RetryBackOffRandomRange
3. 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.

10. Glossary