OCPP transport specification - SRPC over WebSocket

Version History

Version Date Author Description
DRAFT1 2013-02-14 gir Initial version

1. Context

Historically, OCPP uses SOAP over HTTP as a transport. This document defines a new transport binding for OCPP, using SRPC over WebSocket.

1.1. Conventions

The words "MUST", "MUST NOT", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are to be interpreted as described in RFC 2119.

1.2. Terminology

2. Specification

2.1. Architecture

The central system embeds a WebSocket server, and the charge point embeds a WebSocket client. Connections are initiated from the charge point to the central system.

+------------------------+             +------------------------+
|      Charge Point      |             |     Central System     |
+------------------------+             +------------------------+
            |                                      |
            V                                      V
+------------------------+   connect   +------------------------+
|     WebSocket Client   |------------>|     WebSocket Server   |
+------------------------+             +------------------------+

SRPC is designed to answer the need for bi-directional RPC between two endpoints. Once a WebSocket connection has been established, both charge point and central system can trigger and handle remote calls: each endpoint is both caller and callee.

+------------------------+                     +------------------------+
|      Charge Point      |                     |     Central System     |
+------------------------+                     +------------------------+
  |                                                                   |
  |                                                                   |
  | +------------------------+             +------------------------+ |
  +>|          Caller        |------------>|          Callee        |<+
  | +------------------------+    SRPC     +------------------------+ |
  |                           (e.g. MeterValue)                       |
  |                                                                   |
  | +------------------------+             +------------------------+ |
  +>|          Callee        |<------------|          Caller        |<+
    +------------------------+    SRPC     +------------------------+
                              (e.g. Reset)

2.2. Messages format

SPRC messages were inspired by the WAMP protocol.

SRPC requires:

SRPC is based on 3 messages:

Message name Message ID Direction
CALL 2 Caller to Callee
CALLRESULT 3 Callee to Caller
CALLERROR 4 Callee to Caller

The caller initiates a RPC by sending a CALL message to the callee.

When receiving a CALL message, the callee executes the corresponding remote procedure, then replies with a CALLRESULT or CALLERROR message.

The callee MUST use the callID obtained from a CALL message in the associated CALLRESULT or CALLERROR response.

When receiving a CALLRESULT or CALLERROR message, the caller uses the callId field to associate the message with the originating call.

The execution and sending is asynchronous, and there MAY be more than one RPC outstanding. From the caller point of view, a RPC is outstanding when a CALL message has been sent, and no corresponding CALLRESULT or CALLERROR message has been received yet.

2.3. CALL message

A CALL message is a JSON list with 4 items:

[ 2 , callID , procedureName, request ]

See 2.8 for PDUs definition.


2.4. CALLRESULT message

When remote procedure execution succeeds, the callee replies with a CALLRESULT message. A CALLRESULT message is a JSON list with 3 items:

[ 3 , callID , response ]

See 2.8 for PDUs definition.


2.5. CALLERROR message

When the callee cannot process the request and the corresponding response PDU doesn't have to ability to report the error, a CALLERROR message SHOULD be used. A CALLERROR message is a JSON list with 5 items:

[ 4 , callID , errorName , errorDesc , errorDetails ]


2.6. Websocket binding

2.6.1 Charge Box Identity

To allow the central system to uniquely identify a charge point, a charge point MUST send its identifier by appending it to the central system URL. The identifier MUST be properly encoded if needed, as defined by RFC 3986.

2.6.2 OCPP protocol version

The charge point MUST specify the OCPP protocol version as the WebSocket subprotocol, using the Sec-WebSocket-Protocol header.

Valid protocol versions are:

Version Services
ocpp1.2 Central System service: urn://Ocpp/Cp/2010/08/
Charge Point service: urn://Ocpp/Cs/2010/08/
ocpp1.5 Central System service: urn://Ocpp/Cp/2012/06/
Charge Point service: urn://Ocpp/Cs/2012/06/

The central system MAY use the protocol version to handle multiple versions on a single endpoint.

2.6.3 OCPP Heartbeat and WebSocket ping

WebSocket defines ping/pong frames that may be used for keepalive, or to check that the remote endpoint is still responsive. This is also the purpose of the OCPP Heartbeat call. Additionally, OCPP Heartbeat provides a mean for the chargepoint to stay synchronized with the central system clock.

When using SRPC over WebSocket as a transport, a charge point still sends heartbeats as defined in the OCPP specification.

A new standard configuration keyword is added to define the WebSocket ping frequency (section 6.9.1, "Standard Configuration Key Names & Values", in OCPP 1.5 specification):

Key-Name Format Units Key-Value
WebSocketPingInterval int seconds Interval of inactivity (no WebSocket exchanges) with central system after which the charge point should send a WebSocket ping frame.

For optimal bandwidth consumption, it is RECOMMENDED to use WebSocket ping as a keepalive (small interval, typically a few minutes), and to use OCPP Heartbeat only for clock synchronization (larger interval, typically a few hours).

2.6.4 WebSocket handshake request example

Given a central system URL "http://example.com/my/end/point", and a charge point identifier "foobar 1234", the charge point initiates the WebSocket handshake with:

GET /my/end/point/foobar%201234 HTTP/1.1
Host: example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Protocol: ocpp1.5

2.7. Errors

This section defines possible values for the errorName field in CALLERROR messages. This list is exhaustive.

Names try to be consistent with similar errors in SOAP, to facilitate the transition from SOAP to SRPC. The IdentityMismatch error was dropped, as it is no longer relevant for this OCPP transport specification (see 2.6.1).

errorName Description
NotImplemented Method name is not recognized.
NotSupported Method name is recognized but not supported by the receiver.
InternalError An internal error occured and the receiver is not able to complete the operation.
ProtocolError Sender's message does not comply with protocol specification.
SecurityError Sender failed authentication or is not authorized to use the requested operation.
FormationViolation Sender's message is not well-formed.
PropertyConstraintViolation A property name in sender's message is not conform to the PDU structure.
OccurenceConstraintViolation Sender's message violates occurence constraints.
TypeConstraintViolation Sender's message violates data type constraints.
GenericError Other error.

2.8. PDUs definition.