Introduction - CSMS Developer Guide

This document is OCPP 1.6 edition 2. It describes the same protocol as the original OCPP 1.6 (October 2015) — no message-level changes were made. Edition 2 merges all known errata (including v3.0), improves documentation, and clarifies ambiguities.

OCPP 1.6 has two transport flavors. The base protocol document defines message semantics and payloads. It must be paired with one of the transport protocol specifications for implementation.

For improved interoperability between Central Systems and Charge Points, it is advised to meet the requirements stated in the OCPP 1.6 Compliance testing documentation.

3.2a.1 Connection URL

The Charge Point derives its connection URL from the Central System's OCPP-J endpoint URL by following these steps:

Endpoint URL:   ws://centralsystem.example.com/ocpp
CP Identity:    CP001
Connection URL: ws://centralsystem.example.com/ocpp/CP001

Endpoint URL:   wss://centralsystem.example.com/ocppj
CP Identity:    RDAM 123
Connection URL: wss://centralsystem.example.com/ocppj/RDAM%20123

3.2a.2 Subprotocol Negotiation

The OCPP version MUST be specified in the Sec-WebSocket-Protocol header during the WebSocket handshake.

WebSocket Handshake Example

GET /webServices/ocpp/CP3211 HTTP/1.1
Host: some.server.com:33033
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Protocol: ocpp1.6, ocpp1.5
Sec-WebSocket-Version: 13

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: ocpp1.6

3.2a.3 RPC Framework

OCPP-J defines a lightweight RPC framework on top of WebSocket, inspired by WAMP. It provides the request/response correlation that WebSocket itself lacks.

Message Types

Message ID Rules

CALL

[<MessageTypeId>, "<UniqueId>", "<Action>", {<Payload>}]

[2, "19223201", "BootNotification", {"chargePointVendor": "VendorX", "chargePointModel": "SingleSocketCharger"}]

CALLRESULT

[<MessageTypeId>, "<UniqueId>", {<Payload>}]

[3, "19223201", {"status":"Accepted", "currentTime":"2013-02-01T20:53:32.486Z", "heartbeatInterval":300}]

CALLERROR

[<MessageTypeId>, "<UniqueId>", "<ErrorCode>", "<ErrorDescription>", {<ErrorDetails>}]

RPC Error Codes

3.2a.4 Connection Management

WebSocket Ping vs OCPP Heartbeat

3.2a.5 Security

Two security approaches are available: Network-Level Security (VPN, private network) and OCPP-J over TLS (wss://).

HTTP Basic Authentication

Charge Point identity: AL1000
Authorization key:     0001020304050607FFFFFFFFFFFFFFFFFFFFFFFF

HTTP Header:
Authorization: Basic QUwxMDAwOgABAgMEBQYH/////////////////

Authorization Key Rotation Flow

Charge Point                                     Central System
     |                                                  |
     |--- WS Connect (HTTP GET + auth: <old key>) ----->|
     |<--------------- HTTP 101 Upgrade ----------------|
     |                                                  |
     |--- BootNotification.req ------------------------>|
     |<-- BootNotification.conf (status=Pending) -------|
     |                                                  |
     |<-- ChangeConfiguration.req("AuthorizationKey",   |
     |        <new key hex>) ---------------------------|
     |--- ChangeConfiguration.conf(Accepted) ---------->|
     |                                                  |
     |<========= Central System closes WS ==============|
     |                                                  |
     |--- WS Connect (HTTP GET + auth: <new key>) ----->|
     |<--------------- HTTP 101 Upgrade ----------------|
     |                                                  |
     |--- BootNotification.req ------------------------>|
     |<-- BootNotification.conf (status=Accepted) ------|

Core Profile

Firmware Management Profile

Local Auth List Management Profile

Reservation Profile

Smart Charging Profile

Remote Trigger Profile

Typical Transaction Flow

A typical charging transaction involves authorization, starting the transaction, optionally re-authorizing for a different user to stop, and then stopping the transaction.

Charge Point                                              Central System
    |                                                            |
    |  Authorize.req(idTag)                                      |
    | ─────────────────────────────────────────────────────────> |
    |  Authorize.conf(idTagInfo)                                 |
    | <───────────────────────────────────────────────────────── |
    |                                                            |
    |  [Start Charging]                                          |
    |                                                            |
    |  StartTransaction.req(connectorId, idTag,                  |
    |        meterStart, timestamp, [reservationId])             |
    | ─────────────────────────────────────────────────────────> |
    |  StartTransaction.conf(idTagInfo, transactionId)           |
    | <───────────────────────────────────────────────────────── |
    |                                                            |
    |  [Charging...]                                             |
    |                                                            |
    |  Authorize.req(idTag)  — to stop by different user         |
    | ─────────────────────────────────────────────────────────> |
    |  Authorize.conf(idTagInfo)                                 |
    | <───────────────────────────────────────────────────────── |
    |                                                            |
    |  [Stop Charging]                                           |
    |                                                            |
    |  StopTransaction.req(meterStop, timestamp,                 |
    |        transactionId, [reason], [idTag],                   |
    |        [transactionData])                                  |
    | ─────────────────────────────────────────────────────────> |
    |  StopTransaction.conf([idTagInfo])                         |
    | <───────────────────────────────────────────────────────── |

Key Rules

• • A Charge Point authenticates the user first (Authorize.req), then informs the Central System that charging has started (StartTransaction.req).
• • To stop, the CP verifies the user is the same who started, or is in the same group (parentIdTag), and is thus allowed to stop.
• • A Charge Point MUST NOT send an Authorize.req before stopping a transaction if the presented idTag is the same as the idTag presented to start the transaction.

A CP MAY implement an Authorization Cache that autonomously maintains a record of previously presented identifiers. The following rules apply:

Synchronized with the Central System. Contains authorization status of all (or a selection of) identifiers. Identifiers can be marked as:

Synchronized via two methods:

When offline, a CP MAY allow automatic authorization of any "unknown" identifier not in the Local Authorization List or Authorization Cache.

Controlled by the AllowOfflineTxForUnknownId configuration key.

This subsection is informative. It describes the relationship between the overarching Charging Session, the Transaction, Energy Offer Periods, and Energy Transfer Periods. A transaction encompasses the full lifecycle from when all preconditions are met until the Charge Point irrevocably leaves that state.

┌───────────────────────────────────────────────────────────┐
│ Charging Session                                          │
│  (First interaction with user/EV → station available)     │
│                                                           │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ Transaction                                         │  │
│  │  (All preconditions met → irrevocably leaves state) │  │
│  │                                                     │  │
│  │  ┌──────────────────────────────────┐               │  │
│  │  │ Energy Offer Period              │               │  │
│  │  │  (EVSE ready and willing)        │               │  │
│  │  │                                  │               │  │
│  │  │  ┌────────────────────────┐      │               │  │
│  │  │  │ Energy Transfer Period │      │               │  │
│  │  │  │  (Actual energy flow)  │      │               │  │
│  │  │  └────────────────────────┘      │               │  │
│  │  └──────────────────────────────────┘               │  │
│  │                                                     │  │
│  │  ┌──────────────────────────────────┐               │  │
│  │  │ Energy Offer Suspend Period      │               │  │
│  │  │  (Smart Charging / local balance)│               │  │
│  │  └──────────────────────────────────┘               │  │
│  │                                                     │  │
│  │  ┌──────────────────────────────────┐               │  │
│  │  │ Energy Offer Period              │               │  │
│  │  │  ┌────────────────────────┐      │               │  │
│  │  │  │ Energy Transfer Period │      │               │  │
│  │  │  └────────────────────────┘      │               │  │
│  │  └──────────────────────────────────┘               │  │
│  └─────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────┘

Key Points

• • There MAY be multiple Energy Transfer Periods during a single Transaction.
• • Suspensions can be EVSE-initiated or EV-initiated.
• • The Central System MAY deduce the start/end of an Energy Transfer Period from StatusNotification messages: Charging, SuspendedEV, SuspendedEVSE.
• • Some EVs don't go to SuspendedEV state — they might trickle charge instead.
• • Some Charge Points don't have an electrical meter.

Transaction-related messages are those directly associated with a charging transaction. They require special handling, especially regarding delivery order and offline queuing.

Transaction-Related Messages

• • StartTransaction.req
• • StopTransaction.req
• • Periodic or clock-aligned MeterValues.req messages

Delivery Rules

1. 1 The Charge Point SHOULD deliver transaction-related messages in chronological order as soon as possible.
2. 2 When offline, the Charge Point MUST queue transaction-related messages that it would have sent if online.
3. 3 Non-transaction-related messages MAY be delivered immediately without waiting for the queue to empty — they skip ahead.
4. 4 New transaction-related messages SHALL wait until the queue has been emptied.
5. 5 The Central System should process historical queued messages the same as any other.

3.8 Connector Numbering

ConnectorIds MUST be numbered consistently across the Charge Point.

3.9 ID Tokens

IdToken data is usually a 4 or 7 byte UID value of a physical RFID card, typically represented as 8/14 hexadecimal digit characters.

Rules

3.10 Parent idTag

A Central System can treat a set of identity tokens as a "group", allowing any token in the group to start a transaction and any other token in the group to stop it.

Implementation

3.11 Reservations

Reservation is possible using the ReserveNow operation:

• • Reserves a Charge Point until a certain expiry time for a specific idTag.
• • A parentIdTag may be included for "group" reservations.
• • Can reserve a specific connector (connectorId > 0) or any connector (connectorId = 0).
• • A reservation is released when:
  • – The reserved idTag is used on the reserved connector.
  • – The expiry time is reached.
  • – The reservation is explicitly canceled (CancelReservation).

{
  "connectorId": integer,       // REQUIRED — 0 = any connector
  "expiryDate": "date-time",    // REQUIRED
  "idTag": "string (max 20)",   // REQUIRED
  "parentIdTag": "string (max 20)",  // optional — for group reservations
  "reservationId": integer      // REQUIRED
}

{
  "status": "Accepted" | "Faulted" | "Occupied" | "Rejected" | "Unavailable"
}

{
  "reservationId": integer
}

{
  "status": "Accepted" | "Rejected"
}

Three types of charging profile purposes are defined:

It is allowed to stack charging profiles of the same purpose to describe complex calendars.

Precedence Rules

The Composite Schedule is calculated by taking the minimum value for each time interval across all profile purposes. When the CP has more than one Connector, the ChargePointMaxProfile limit applies to all connectors combined.

Three use cases are defined for Smart Charging:

3.13.5 Discovery

The following configuration keys are used to discover the Smart Charging capabilities of a Charge Point:

3.14 Time Zones

OCPP does not prescribe a specific time zone. It is strongly recommended to use UTC for all time values.

3.15 Time Notations

Implementations MUST use ISO 8601 date time notation. Message receivers must be able to handle fractional seconds and time zone offsets.

3.16 Metering Data

Two obvious use cases for extensive metering data:

• • Charging Session Meter Values
• • Clock-Aligned Meter Values

Both MAY be reported in standalone MeterValues.req messages and/or as part of StopTransaction.req.

{
  "timestamp": "2024-01-15T10:30:00Z",
  "sampledValue": [
    {
      "value": "1234.5",
      "context": "...",
      "format": "...",
      "measurand": "...",
      "phase": "...",
      "location": "...",
      "unit": "..."
    }
  ]
}

SampledValue Fields

Measurand Values

3.16.1 Charging Session Meter Values

Frequent (e.g. 1-5 minute interval) meter readings. Controlled by the following configuration keys:

3.16.2 Clock-Aligned Meter Values

Grid Operator may require meter readings at specific clock-aligned times. Controlled by the following configuration keys:

3.16.3 Multiple Locations/Phases

When the Charge Point can measure the same measurand on multiple locations or phases, all possible locations and/or phases SHALL be reported.

3.16.4 Unsupported Measurands

If a ChangeConfiguration.req contains measurands not supported by the Charge Point, the CP SHALL respond with status = Rejected. No changes SHALL be made.

Core Messages

Authorize

{
  "idTag": "string (max 20)"  // REQUIRED
}

{
  "idTagInfo": {
    "status": "Accepted" | "Blocked" | "Expired" | "Invalid" | "ConcurrentTx",
    "expiryDate": "date-time",
    "parentIdTag": "string (max 20)"
  }
}

BootNotification

{
  "chargePointVendor": "string (max 20)",
  "chargePointModel": "string (max 20)",
  "chargePointSerialNumber": "string (max 25)",
  "chargeBoxSerialNumber": "string (max 25)",
  "firmwareVersion": "string (max 50)",
  "iccid": "string (max 20)",
  "imsi": "string (max 20)",
  "meterType": "string (max 25)",
  "meterSerialNumber": "string (max 25)"
}

{
  "status": "Accepted" | "Pending" | "Rejected",
  "currentTime": "date-time",
  "interval": integer
}

Heartbeat

{}

{
  "currentTime": "date-time"
}

StartTransaction

{
  "connectorId": integer,
  "idTag": "string (max 20)",
  "meterStart": integer,
  "timestamp": "date-time",
  "reservationId": integer
}

{
  "idTagInfo": {
    "status": "Accepted" | "Blocked" | "Expired" | "Invalid" | "ConcurrentTx",
    "expiryDate": "date-time",
    "parentIdTag": "string (max 20)"
  },
  "transactionId": integer
}

StopTransaction

{
  "transactionId": integer,
  "timestamp": "date-time",
  "meterStop": integer,
  "idTag": "string (max 20)",
  "reason": "EmergencyStop" | "EVDisconnected" | "HardReset" | "Local" | "Other" | "PowerLoss" | "Reboot" | "Remote" | "SoftReset" | "UnlockCommand" | "DeAuthorized",
  "transactionData": [MeterValue]
}

{
  "idTagInfo": { ... }
}

StatusNotification

{
  "connectorId": integer,
  "errorCode": "ConnectorLockFailure" | "EVCommunicationError" | "GroundFailure" | "HighTemperature" | "InternalError" | "LocalListConflict" | "NoError" | "OtherError" | "OverCurrentFailure" | "PowerMeterFailure" | "PowerSwitchFailure" | "ReaderFailure" | "ResetFailure" | "UnderVoltage" | "OverVoltage" | "WeakSignal",
  "status": "Available" | "Preparing" | "Charging" | "SuspendedEVSE" | "SuspendedEV" | "Finishing" | "Reserved" | "Unavailable" | "Faulted",
  "info": "string (max 50)",
  "timestamp": "date-time",
  "vendorId": "string (max 255)",
  "vendorErrorCode": "string (max 50)"
}

{}

MeterValues

{
  "connectorId": integer,
  "transactionId": integer,
  "meterValue": [MeterValue]
}

{}

ChangeAvailability

{
  "connectorId": integer,
  "type": "Inoperative" | "Operative"
}

{
  "status": "Accepted" | "Rejected" | "Scheduled"
}

ChangeConfiguration

{
  "key": "string (max 50)",
  "value": "string (max 500)"
}

{
  "status": "Accepted" | "Rejected" | "RebootRequired" | "NotSupported"
}

ClearCache

{}

{
  "status": "Accepted" | "Rejected"
}

GetConfiguration

{
  "key": ["string (max 50)"]
}

{
  "configurationKey": [
    { "key": "string", "readonly": boolean, "value": "string" }
  ],
  "unknownKey": ["string"]
}

RemoteStartTransaction

{
  "connectorId": integer,
  "idTag": "string (max 20)",
  "chargingProfile": { ... }
}

{
  "status": "Accepted" | "Rejected"
}

RemoteStopTransaction

{
  "transactionId": integer
}

{
  "status": "Accepted" | "Rejected"
}

Reset

{
  "type": "Hard" | "Soft"
}

{
  "status": "Accepted" | "Rejected"
}

UnlockConnector

{
  "connectorId": integer
}

{
  "status": "Unlocked" | "UnlockFailed" | "NotSupported"
}

DataTransfer

{
  "vendorId": "string (max 255)",
  "messageId": "string (max 50)",
  "data": "string"
}

{
  "status": "Accepted" | "Rejected" | "UnknownMessageId" | "UnknownVendorId",
  "data": "string"
}

Firmware Management

GetDiagnostics

{
  "location": "uri-string",
  "retries": integer,
  "retryInterval": integer,
  "startTime": "date-time",
  "stopTime": "date-time"
}

{
  "fileName": "string (max 255)"
}

DiagnosticsStatusNotification

{
  "status": "Idle" | "Uploaded" | "UploadFailed" | "Uploading"
}

{}

FirmwareStatusNotification

{
  "status": "Downloaded" | "DownloadFailed" | "Downloading" | "Idle" | "InstallationFailed" | "Installing" | "Installed"
}

{}

UpdateFirmware

{
  "location": "uri-string",
  "retrieveDate": "date-time",
  "retries": integer,
  "retryInterval": integer
}

{}

Local Auth List Management

GetLocalListVersion

{}

{
  "listVersion": integer
}

SendLocalList

{
  "listVersion": integer,
  "updateType": "Differential" | "Full",
  "localAuthorizationList": [
    { "idTag": "string", "idTagInfo": { ... } }
  ]
}

{
  "status": "Accepted" | "Failed" | "NotSupported" | "VersionMismatch"
}

Remote Trigger

TriggerMessage

{
  "requestedMessage": "BootNotification" | "DiagnosticsStatusNotification" | "FirmwareStatusNotification" | "Heartbeat" | "MeterValues" | "StatusNotification",
  "connectorId": integer
}

{
  "status": "Accepted" | "Rejected" | "NotImplemented"
}

Smart Charging

SetChargingProfile

{
  "connectorId": integer,
  "csChargingProfiles": {
    "chargingProfileId": integer,
    "transactionId": integer,
    "stackLevel": integer,
    "chargingProfilePurpose": "ChargePointMaxProfile" | "TxDefaultProfile" | "TxProfile",
    "chargingProfileKind": "Absolute" | "Recurring" | "Relative",
    "recurrencyKind": "Daily" | "Weekly",
    "validFrom": "date-time",
    "validTo": "date-time",
    "chargingSchedule": {
      "duration": integer,
      "startSchedule": "date-time",
      "chargingRateUnit": "A" | "W",
      "chargingSchedulePeriod": [
        { "startPeriod": integer, "limit": number, "numberPhases": integer }
      ],
      "minChargingRate": number
    }
  }
}

{
  "status": "Accepted" | "Rejected" | "NotSupported"
}

ClearChargingProfile

{
  "id": integer,
  "connectorId": integer,
  "chargingProfilePurpose": "ChargePointMaxProfile" | "TxDefaultProfile" | "TxProfile",
  "stackLevel": integer
}

{
  "status": "Accepted" | "Unknown"
}

GetCompositeSchedule

{
  "connectorId": integer,
  "duration": integer,
  "chargingRateUnit": "A" | "W"
}

{
  "status": "Accepted" | "Rejected",
  "connectorId": integer,
  "scheduleStart": "date-time",
  "chargingSchedule": { ... }
}

Connector Status State Machine

The following diagram illustrates the state transitions of a connector. A connector begins in the Available state and transitions through Preparing, Charging, and Finishing during a normal transaction lifecycle. Charging may be suspended by either the EVSE or the EV.

                   ┌──────────┐
         ┌─────────│ Available│◄──────────────────┐
         │         └─────┬────┘                   │
         │               │ (EV connects /         │
         │               │  user authenticates)   │
         │               ▼                        │
         │         ┌──────────┐                   │
         │         │Preparing │                   │
         │         └─────┬────┘                   │
         │               │ (all preconditions     │
         │               │  met, power offered)   │
         │               ▼                        │
         │         ┌──────────┐                   │
         │    ┌───►│ Charging │◄───┐              │
         │    │    └────┬─┬───┘    │              │
         │    │         │ │        │              │
         │    │    ┌────┘ └────┐   │              │
         │    │    ▼           ▼   │              │
         │    │ ┌───────────┐ ┌───────────┐       │
         │    │ │Suspended  │ │Suspended  │       │
         │    └─┤   EVSE    │ │    EV     ├───┘   │
         │      └───────────┘ └───────────┘       │
         │               │                        │
         │               │ (transaction ends)     │
         │               ▼                        │
         │         ┌──────────┐                   │
         │         │Finishing │───────────────────┘
         │         └──────────┘
         │
         │         ┌──────────┐
         ├────────►│ Reserved │  (via ReserveNow)
         │         └──────────┘
         │
         │         ┌────────────┐
         ├────────►│Unavailable │  (via ChangeAvailability)
         │         └────────────┘
         │
         │         ┌──────────┐
         └────────►│ Faulted  │  (hardware/software error)
                   └──────────┘

All Configuration Keys

Comprehensive list of configuration keys used across all OCPP 1.6 feature profiles. These keys are read and written via GetConfiguration and ChangeConfiguration.

Developer Implementation Checklist

Use this checklist when implementing a CSMS (Central System / Management System) that communicates with Charge Points over OCPP 1.6-J.