OCPP 2.0.1: Part 4 - JSON over WebSockets implementation guide

OCPP 2.0.1 Part 4 - JSON over WebSockets Implementation Guide

This document provides info for creating interoperable OCPP JSON implementations (OCPP-J). It covers mandatory elements, best practices, and potential pitfalls for developers implementing OCPP JSON. It helps to understand how to ensure smooth communication between Charging Stations and Charging Station Management Systems (CSMS).

Ready to build robust and interoperable charging solutions? Dive in to:

• Grasp OCPP-J implementation for seamless charging station communication.
• Navigate WebSocket connections and message structures effectively with clear explanations.
• Implement secure and reliable message routing with local controllers.

Core Content:

1. Establishing WebSocket Connections

• The CSMS acts as a WebSocket server, and the Charging Station acts as a WebSocket client. Charging Stations initiate the WebSocket connection.
• The Charging Station SHALL keep this WebSocket connection open all the time.

2. Connection URL

• Charging Stations need a URL to connect to, so-called the "connection URL".
• The Charging Station’s connection URL contains the Charging Station identity for the CSMS to know which Charging Station a WebSocket connection belongs to.
• The Charging Station modifies the OCPP-J endpoint URL by appending a '/' and then a string uniquely identifying the Charging Station. The string has to be percent-encoded.
• The maximum length of the Charging Station identity is: 48

3. OCPP Version

• The OCPP version(s) MUST be specified in the Sec-WebSocket-Protocol field.
• The OCPP version should not be part of the OCPP-J endpoint URL string if you want to select the OCPP version to use via the websocket protocol negotiation mechanism.

4. WebSocket Compression

• OCPP Requires the CSMS (and Local Controller) to support RFC 7692
• When both parties support the Compression Extension they will then use DEFLATE compression when sending data over the line.
• When the Charging Station detects that compression is not used, it is RECOMMENDED not to close the connection, as turning of compression can be very useful during development, testing and debugging.

5. RPC Framework

• To encode request/response relations we need a small protocol on top of WebSocket.
• A Charging Station or CSMS SHALL NOT send a CALL message to the other party unless all the CALL messages it sent before have been responded to or have timed out.

6. Message Validity and Character encoding

• The whole message consisting of wrapper and payload MUST be valid JSON encoded with the UTF-8 character encoding.
• Furthermore, the Charging Station and CSMS have the right to reject messages which are not conform the JSON schemas.

7. CALL Structure

• A CALL always consists of 4 elements: MessageTypeId, MessageId, Action and the arguments to the Action.
• If there is no payload JSON allows for two different notations:

  null

  or an empty object

  {}

  . It is good practice to only use the empty object statement.
• When a field is optional, do not put the field in the payload

8. CALLRESULT Structure

• A CALLRESULT always consists of 3 elements: MessageTypeId, MessageId and a payload with the response to the Action in the original Call.

9. CALLERROR Structure

• We only use CALLERROR in two situations:
  • An error occurred during the transport of the message.
  • The content of the call does not meet the requirements for a proper message.
• A CALLERROR always consists of 5 elements: MessageTypeId, MessageId, an errorCode string, an errorDescription string and an errorDetails object.

10. Reconnecting

• When the connection is lost, the Charging Station SHALL try to reconnect.
• When reconnecting, the Charging Station SHALL use an increasing back-off time with some randomization until it has successfully reconnected.

11. OCPP Routing with Local Controller

• For each Charging Station that connects to the Local Controller, two connections will be established:
  • A WebSocket connection from the Charging Station to the Local Controller
  • A WebSocket connection from the Local Controller to the CSMS
• The Local Controller SHALL relay any Charging Station initiated message to the CSMS (and vice versa).
• If a Local Controller sends its own messages to a Charging Station, it SHALL guarantee that its messages have IDs that do not collide with IDs used by the CSMS, now and in the future, using UUIDs/GUIDs

12. Signed Messages

• For certain architectures it can be useful to use signed OCPP messages.
• For Signed OCPP Messages, JWS is used.
• When a Charging Station receives a signed request, and it supports digital signing, it SHALL send a signed reply.
• Within the OCPP, the Charging Station and CSMS SHOULD include the field x5t#S256 in the JWS Protected Header to identify the certificate.

13. Configuration Variables

• RetryBackOffRepeatTimes

  : the amount of times it will double the previous back-off time.

• RetryBackOffRandomRange

  : the maximum value for the random part of the back-off time.

• RetryBackOffWaitMinimum

  : the minimum back-off time, the first time it tries to reconnect.

• WebSocketPingInterval

  : number of seconds between pings. A value of 0 disables client side websocket Ping / Pong.

14. CustomData Extension

• Every JSON class has been extended with a "customData" property.
• This property is of type "CustomDataType", which has only one required property: "vendorId", which is used to identify the kind of customization.

Q&A

Q: What are OCPP-J and OCPP-S?

A: OCPP-J refers to OCPP communication over WebSocket using JSON, while OCPP-S refers to communication over SOAP and HTTP(S). It's important to specify which one you're using to avoid confusion.

Q: How does a Charging Station establish a connection with a CSMS using OCPP-J?

A: The Charging Station initiates a WebSocket connection to the CSMS, which acts as a WebSocket server. The Charging Station needs a connection URL that includes the Charging Station's unique identifier. The CSMS must provide an OCPP-J endpoint URL.

Q: What is the purpose of the Message ID in the RPC framework?

A: The Message ID serves to uniquely identify a request. It's used to match requests with their corresponding results (CALLRESULT) or error responses (CALLERROR).

Q: What should I do if I receive a CALL message while waiting for a CALLERROR or CALLRESULT?

A: This situation is difficult to prevent due to the asynchronous nature of WebSocket communication. Implementations should be prepared to handle such scenarios gracefully, as CALL messages from both sides can sometimes cross each other.

Q: What should I do if the current message is invalid

A: When a message is not valid, the server SHALL respond with a CALLERROR