OCPP 2.1 Edition 2 Section O

Display Message - CSMS Developer Guide

Based on OCPP 2.1 Edition 2 Specification (Part 2), Section O (Display Message). This guide covers all display message flows (O01–O06), including setting, retrieving, replacing, and clearing display messages on Charging Stations from the CSMS perspective.

10 Sections

6 Use Cases

O01 – O06

1. Overview

Introduction

The Display Message feature enables the CSMS (acting on behalf of a CSO) to manage messages displayed on Charging Station screens. These are messages not part of the firmware — they are dynamically configured via OCPP.

CSMS Capabilities

Set Messages

Set new display messages on a Charging Station using SetDisplayMessageRequest.

Retrieve Messages

Get currently configured display messages using GetDisplayMessagesRequest.

Replace Messages

Replace existing display messages by sending a SetDisplayMessageRequest with an existing message ID.

Clear Messages

Remove specific display messages using ClearDisplayMessageRequest.

Key Constraints

Messages can be configured in different languages and formats.
The Charging Station reports supported formats via DisplayMessageSupportedFormats and supported priorities via DisplayMessageSupportedPriorities.
It is not possible to retrieve/modify messages that are coded into the Charging Station firmware — only OCPP-configured messages.

Messages Involved

4 request/response pairs are used in this functional block:

Message	Direction	Initiated By
`SetDisplayMessageRequest / Response`	CSMS → Charging Station	CSMS
`GetDisplayMessagesRequest / Response`	CSMS → Charging Station	CSMS
`NotifyDisplayMessagesRequest / Response`	Charging Station → CSMS	Charging Station
`ClearDisplayMessageRequest / Response`	CSMS → Charging Station	CSMS

2. Shared Data Types & Enumerations

Reference

MessageFormatEnumType

Defines the format of the display message content.

Enum values

"ASCII" | "HTML" | "URI" | "UTF8" | "QRCODE"

Value	Description
`ASCII`	Plain ASCII text
`HTML`	HTML formatted content
`URI`	A URI/URL to display or navigate to
`UTF8`	UTF-8 encoded text (supports international characters)
`QRCODE`	Content to be rendered as a QR code

MessagePriorityEnumType

Controls display priority of the message on the Charging Station.

Enum values

"AlwaysFront" | "InFront" | "NormalCycle"

Value	Behavior
`NormalCycle`	Show in the normal rotation cycle of messages
`InFront`	Show at the configured moment, regardless of normal cycle. Multiple `InFront` messages cycle among themselves
`AlwaysFront`	Show at the configured moment, overriding ALL other messages (including firmware messages). Does NOT cycle. If a new `AlwaysFront` message is set, it replaces the previous one

MessageStateEnumType

Defines during which Charging Station state the message should be shown. When omitted, the message is shown in any state.

Enum values

"Charging" | "Faulted" | "Idle" | "Unavailable" | "Suspended" | "Discharging"

Value	Description
`Charging`	Show only while the station is actively charging
`Faulted`	Show only when the station is in a faulted state
`Idle`	Show only when the station is idle (not in use)
`Unavailable`	Show only when the station is unavailable
`Suspended`	Show only when charging is suspended
`Discharging`	Show only during V2G discharging

DisplayMessageStatusEnumType

Returned in SetDisplayMessageResponse.

Value	Meaning
`Accepted`	Message was accepted and will be displayed
`NotSupportedMessageFormat`	The format in the message is not supported by this Charging Station
`NotSupportedPriority`	The priority is not supported by this Charging Station
`NotSupportedState`	The state is not supported by this Charging Station
`Rejected`	General rejection (e.g. max messages exceeded, unknown display component)
`UnknownTransaction`	The transactionId in the message is not known to the Charging Station
`LanguageNotSupported`	The language in message or messageExtra is not in the station's DisplayMessageLanguage configuration

GetDisplayMessagesStatusEnumType

Value	Meaning
`Accepted`	Station has matching messages and will send them via NotifyDisplayMessagesRequest
`Unknown`	No matching display messages found

ClearMessageStatusEnumType

Value	Meaning
`Accepted`	Message was found and removed
`Unknown`	No message with that ID exists on the station
`Rejected`	Station cannot execute the clear request

MessageContentType

Contains the actual message text/content to display.

MessageContentType Schema

{
  "format": MessageFormatEnumType,   // REQUIRED - "ASCII"|"HTML"|"URI"|"UTF8"|"QRCODE"
  "content": string,                 // REQUIRED - The message text (max 1024 chars)
  "language": string                 // OPTIONAL - RFC 5646 language tag (max 8 chars), e.g. "en-US"
}

Notes

Max length of content supported by a specific Charging Station is given in OCPPCommCtrlr.FieldLength["MessageContentType.content"], defaulting to 1024.
Language tags MUST follow RFC 5646 format (e.g. "en-US", "nl", "de-DE").

MessageInfoType

The core data structure that describes a display message and all its parameters.

MessageInfoType Schema

{
  "id": integer,                      // REQUIRED - Unique message ID (>= 0)
  "priority": MessagePriorityEnumType, // REQUIRED - "AlwaysFront"|"InFront"|"NormalCycle"
  "message": MessageContentType,       // REQUIRED - Primary message content

  "state": MessageStateEnumType,       // OPTIONAL - When omitted, shown in any state
  "startDateTime": string,             // OPTIONAL - ISO 8601 date-time. When omitted: show immediately
  "endDateTime": string,               // OPTIONAL - ISO 8601 date-time. When reached, message is removed
  "transactionId": string,             // OPTIONAL - Tie message to a transaction (max 36 chars)
  "messageExtra": [MessageContentType], // OPTIONAL - Additional language versions (1-4 items)
  "display": ComponentType             // OPTIONAL - Target a specific display component
}

Field	Type	Required	Description
`id`	integer (>= 0)	Yes	Unique identifier for the message. Used for retrieval, replacement, and clearing.
`priority`	MessagePriorityEnumType	Yes	Controls display priority behavior.
`message`	MessageContentType	Yes	The primary message content (format + text + optional language).
`state`	MessageStateEnumType	No	Restrict display to a specific Charging Station state. Omit to show in all states.
`startDateTime`	ISO 8601 date-time	No	Schedule when the message starts displaying. Omit to display immediately.
`endDateTime`	ISO 8601 date-time	No	Schedule when the message is automatically removed.
`transactionId`	string (max 36)	No	Bind message to a specific transaction. Message is auto-removed when transaction ends.
`messageExtra`	Array of MessageContentType	No	Additional language versions of the message (1 to 4 entries).
`display`	ComponentType	No	Target a specific display on multi-display Charging Stations.

ComponentType (Display Target)

Used to target a specific display on a Charging Station that has multiple displays.

ComponentType Schema

{
  "name": string,       // REQUIRED - Component name (max 50 chars), e.g. "Display"
  "instance": string,   // OPTIONAL - Instance name for multiple components (max 50 chars)
  "evse": {             // OPTIONAL - Target a specific EVSE's display
    "id": integer,      // REQUIRED - EVSE identifier (>= 0)
    "connectorId": integer // OPTIONAL - Specific connector (>= 0)
  }
}

StatusInfoType

Optional additional information returned with response statuses.

StatusInfoType Schema

{
  "reasonCode": string,     // REQUIRED - Predefined code (max 20 chars, case-insensitive)
  "additionalInfo": string  // OPTIONAL - Detailed human-readable information (max 1024 chars)
}

3. O01 — Set DisplayMessage

CSMS-Initiated

Use Case ID	O01
Direction	CSMS → Charging Station
Trigger	CSO wants to set a new display message on a Charging Station
OCPP Messages	SetDisplayMessageRequest / SetDisplayMessageResponse

Flow Diagram

Sequence Diagram (CSMS perspective)

CSO                    CSMS                         Charging Station
 |                      |                                |
 |  Set new message()   |                                |
 |--------------------->|                                |
 |                      |  SetDisplayMessageRequest(...)  |
 |                      |------------------------------->|
 |                      |                                |
 |                      |  SetDisplayMessageResponse(Accepted)
 |                      |<-------------------------------|
 |                      |                                |
 | [opt] notification   |                                |
 |<---------------------|                                |
 |                      |                   [Display message at configured moment]

SetDisplayMessageRequest — Sent by CSMS

Direction: CSMS → Charging Station
Schema ID: urn:OCPP:Cp:2:2025:1:SetDisplayMessageRequest

SetDisplayMessageRequest — Example

{
  "message": {
    "id": 1,
    "priority": "NormalCycle",
    "message": {
      "format": "UTF8",
      "content": "Welcome! Please tap your card to start charging.",
      "language": "en-US"
    },
    "state": "Idle",
    "startDateTime": "2026-01-15T08:00:00Z",
    "endDateTime": "2026-12-31T23:59:59Z",
    "messageExtra": [
      {
        "format": "UTF8",
        "content": "Welkom! Houd uw pas voor de lezer om te starten.",
        "language": "nl"
      }
    ]
  }
}

Field	Type	Description
`message`	MessageInfoType	The complete message object (see Section 2)

Within message (MessageInfoType), the following are required:

Field	Type	Description
`message.id`	integer (>= 0)	Unique message ID. Must not conflict with existing IDs (for new messages).
`message.priority`	MessagePriorityEnumType	Display priority
`message.message`	MessageContentType	Primary message content with format and content (both required)

SetDisplayMessageResponse — Received by CSMS

Direction: Charging Station → CSMS
Schema ID: urn:OCPP:Cp:2:2025:1:SetDisplayMessageResponse

SetDisplayMessageResponse — Example

{
  "status": "Accepted",
  "statusInfo": {
    "reasonCode": "NoError"
  }
}

Field	Type	Required	Description
`status`	DisplayMessageStatusEnumType	Yes	Result of the set operation
`statusInfo`	StatusInfoType	No	Additional details about the status

CSMS Response Handling Logic

Response Handling Decision Tree

RECEIVE SetDisplayMessageResponse:

SWITCH response.status:

  CASE "Accepted":
    -> Message was accepted. Store the message ID locally for future reference.
    -> The Charging Station will display it according to the configured parameters.

  CASE "NotSupportedPriority":
    -> The priority value sent is not supported by this Charging Station.
    -> ACTION: Check DisplayMessageSupportedPriorities config variable.
    -> Retry with a supported priority, or notify the CSO.

  CASE "NotSupportedState":
    -> The state value sent is not supported by this Charging Station.
    -> ACTION: Check DisplayMessageSupportedStates config variable.
    -> Retry with a supported state, or notify the CSO.

  CASE "NotSupportedMessageFormat":
    -> The message format (ASCII/HTML/URI/UTF8/QRCODE) is not supported.
    -> ACTION: Check DisplayMessageSupportedFormats config variable.
    -> Retry with a supported format, or notify the CSO.

  CASE "Rejected":
    -> General rejection. Common causes:
       - Total message count would exceed NumberOfDisplayMessages.maxLimit
       - The display component referenced is unknown to the station
    -> ACTION: Log the rejection. Check statusInfo for details. Consider clearing
       old messages first if the limit is reached.

  CASE "UnknownTransaction":
    -> The transactionId provided is not known to the Charging Station.
    -> ACTION: Verify the transaction is active on this station.

  CASE "LanguageNotSupported":
    -> A language in message or messageExtra is not in the station's
       DisplayMessageLanguage configuration.
    -> ACTION: Check the station's DisplayMessageLanguage config variable.
    -> Retry with supported languages only.

CSMS Implementation Notes

ID Management: The CSMS is responsible for assigning unique id values. Maintain a registry of message IDs per Charging Station.
Capacity Check: Before sending, read the NumberOfDisplayMessages.maxLimit config variable to know how many messages the station can hold.
Language Support: Read DisplayMessageLanguage to know supported languages. If this variable is not present, messageExtra is not supported — sending it will result in Rejected.
Non-transaction messages: When sending a message that does NOT belong to a transaction, the transactionId field MUST be omitted.
startDateTime / endDateTime: These are optional. If startDateTime is omitted, the message shows immediately. If endDateTime is omitted, the message stays until explicitly cleared.
Multi-display stations: If the station has multiple displays, use the display field in MessageInfoType to target a specific one. If omitted, the station SHOULD use the main display(s).

4. O02 — Set DisplayMessage for Transaction

CSMS-Initiated

Use Case ID	O02
Direction	CSMS → Charging Station
Trigger	CSO wants to set a display message bound to a specific active transaction
OCPP Messages	SetDisplayMessageRequest / SetDisplayMessageResponse

This is a variant of Flow O01. The only difference is that the CSMS includes a transactionId field in the MessageInfoType. The message is automatically removed when the transaction ends.

Flow Diagram

Sequence Diagram (CSMS perspective)

CSO                    CSMS                         Charging Station
 |                      |                                |
 |                      |              [Transaction id=123 is ongoing]
 |                      |                                |
 | Set msg(txn=123)     |                                |
 |--------------------->|                                |
 |                      | SetDisplayMessageRequest(      |
 |                      |   transactionId=123, ...)      |
 |                      |------------------------------->|
 |                      |                                |
 |                      | SetDisplayMessageResponse(Accepted)
 |                      |<-------------------------------|
 |                      |                                |
 | [opt] notification   |                   [At configured moment]
 |<---------------------|                   [Display message]
 |                      |                                |
 |                      |              [Transaction 123 ends]
 |                      |              [Auto-remove message]

SetDisplayMessageRequest Example (Transaction-Bound)

CSMS Processing Steps

Verify the transaction is currently active on the target Charging Station.
Build SetDisplayMessageRequest with transactionId set.
Send to the Charging Station and process the response.

SetDisplayMessageRequest — Transaction-Bound

{
  "message": {
    "id": 50,
    "priority": "InFront",
    "message": {
      "format": "UTF8",
      "content": "Charging session in progress. Estimated cost: $12.50",
      "language": "en-US"
    },
    "transactionId": "a1b5c7d8-1234-5678-9abc-def012345678",
    "state": "Charging"
  }
}

CSMS Response Handling

Same as Flow O01, with the addition of the UnknownTransaction case:

UnknownTransaction Handling

CASE "UnknownTransaction":
  -> The transactionId is not recognized by the Charging Station.
  -> POSSIBLE CAUSES:
     - Transaction already ended before message was delivered
     - Wrong Charging Station targeted
     - transactionId is malformed or incorrect
  -> ACTION: Verify the transaction state in your system. If the transaction
     has ended, discard the message. If it should be active, investigate.

CSMS Implementation Notes

Transaction Lifecycle: The message is auto-removed by the Charging Station when the transaction ends. The CSMS does NOT need to send a ClearDisplayMessageRequest for these.
Timing: Ensure the transaction is still active when sending the request. There is a race condition if the transaction is about to end.
Use Cases: Ideal for showing charging progress, estimated cost, energy delivered, or tariff information during an active session.

5. O03 — Get All DisplayMessages

CSMS-Initiated

Use Case ID	O03
Direction	CSMS → Charging Station (request) / Charging Station → CSMS (notify)
Trigger	CSO wants to retrieve all display messages currently configured on a Charging Station
OCPP Messages	GetDisplayMessagesRequest/Response, NotifyDisplayMessagesRequest/Response

Flow Diagram

Sequence Diagram (CSMS perspective)

CSO                    CSMS                         Charging Station
 |                      |                                |
 | Get all messages     |                                |
 |--------------------->|                                |
 |                      | GetDisplayMessagesRequest(     |
 |                      |   requestId=42)                |
 |                      |------------------------------->|
 |                      |                                |
 |                      | GetDisplayMessagesResponse(Accepted)
 |                      |<-------------------------------|
 |                      |                                |
 |                      |    [loop: for each batch]      |
 |                      |                                |
 |                      | NotifyDisplayMessagesRequest(   |
 |                      |   requestId=42,                |
 |                      |   messageInfo=[...],           |
 |                      |   tbc=true)                    |
 |                      |<-------------------------------|
 |                      |                                |
 |                      | NotifyDisplayMessagesResponse() |
 |                      |------------------------------->|
 |                      |                                |
 |                      | NotifyDisplayMessagesRequest(   |
 |                      |   requestId=42,                |
 |                      |   messageInfo=[...],           |
 |                      |   tbc=false)                   |
 |                      |<-------------------------------|
 |                      |                                |
 |                      | NotifyDisplayMessagesResponse() |
 |                      |------------------------------->|
 |                      |                                |
 | [opt] notification   |                                |
 |<---------------------|                                |

GetDisplayMessagesRequest — Sent by CSMS

Direction: CSMS → Charging Station
Schema ID: urn:OCPP:Cp:2:2025:1:GetDisplayMessagesRequest

GetDisplayMessagesRequest — Get ALL messages

{
  "requestId": 42
}

Field	Type	Required	Description
`requestId`	integer	Yes	Unique request identifier. The Charging Station echoes this back in NotifyDisplayMessagesRequest to correlate responses.
`id`	array of integers	No	Omit for "get all". Filter by specific message IDs.
`priority`	MessagePriorityEnumType	No	Omit for "get all". Filter by priority.
`state`	MessageStateEnumType	No	Omit for "get all". Filter by state.

Key Rule: To get ALL messages, omit all optional filter fields. Only send requestId.

GetDisplayMessagesResponse — Received by CSMS

Direction: Charging Station → CSMS
Schema ID: urn:OCPP:Cp:2:2025:1:GetDisplayMessagesResponse

GetDisplayMessagesResponse — Example

{
  "status": "Accepted"
}

Response Handling

RECEIVE GetDisplayMessagesResponse:

SWITCH response.status:

  CASE "Accepted":
    -> The Charging Station has matching messages.
    -> WAIT for one or more incoming NotifyDisplayMessagesRequest messages.
    -> The Charging Station will send them asynchronously.

  CASE "Unknown":
    -> No display messages are configured on the Charging Station.
    -> ACTION: Update local state — this station has zero OCPP-configured messages.
    -> No NotifyDisplayMessagesRequest will follow.

NotifyDisplayMessagesRequest — Received by CSMS

After receiving GetDisplayMessagesResponse with status Accepted, the Charging Station will send one or more NotifyDisplayMessagesRequest messages containing the actual message data.

NotifyDisplayMessagesRequest — Example

{
  "requestId": 42,
  "tbc": true,
  "messageInfo": [
    {
      "id": 1,
      "priority": "NormalCycle",
      "message": {
        "format": "UTF8",
        "content": "Welcome!",
        "language": "en-US"
      },
      "state": "Idle"
    },
    {
      "id": 2,
      "priority": "InFront",
      "message": {
        "format": "UTF8",
        "content": "Maintenance scheduled for tomorrow.",
        "language": "en-US"
      },
      "startDateTime": "2026-02-16T00:00:00Z",
      "endDateTime": "2026-02-17T23:59:59Z"
    }
  ]
}

Field	Type	Required	Description
`requestId`	integer	Yes	Echoed from the original GetDisplayMessagesRequest. Use this to correlate.
`tbc`	boolean	No	"To be continued". true = more messages coming. false or omitted = last batch. Default: false.
`messageInfo`	Array of MessageInfoType	No	The display messages. May be absent if no messages match.

NotifyDisplayMessagesResponse: The CSMS MUST respond to every NotifyDisplayMessagesRequest with a NotifyDisplayMessagesResponse. The response has no required fields — it is simply an empty acknowledgement {}.

CSMS Processing Logic

NotifyDisplayMessagesRequest Handler

ON RECEIVE NotifyDisplayMessagesRequest:

  1. Correlate using requestId to the original GetDisplayMessagesRequest.

  2. Extract messageInfo array and store/update local message state for this station.

  3. Check the tbc (to-be-continued) field:
     - IF tbc == true:
       -> More NotifyDisplayMessagesRequest messages will follow.
       -> Continue accumulating results.
     - IF tbc == false OR tbc is absent:
       -> This is the LAST batch.
       -> All messages have been received. Finalize processing.

  4. ALWAYS respond with NotifyDisplayMessagesResponse (empty body: {}).

  5. After all batches received (tbc=false), reconcile local CSMS message registry
     with the actual messages reported by the Charging Station.

6. O04 — Get Specific DisplayMessages

CSMS-Initiated

Use Case ID	O04
Direction	CSMS → Charging Station (request) / Charging Station → CSMS (notify)
Trigger	CSO wants to retrieve specific display messages by filtering on IDs, priority, and/or state
OCPP Messages	GetDisplayMessagesRequest/Response, NotifyDisplayMessagesRequest/Response

Flow Diagram

Sequence Diagram (CSMS perspective)

CSO                    CSMS                         Charging Station
 |                      |                                |
 | Query messages       |                                |
 |--------------------->|                                |
 |                      | GetDisplayMessagesRequest(     |
 |                      |   requestId=55,                |
 |                      |   id=[1,5,10],                 |
 |                      |   priority="InFront")          |
 |                      |------------------------------->|
 |                      |                                |
 |                      | GetDisplayMessagesResponse(Accepted)
 |                      |<-------------------------------|
 |                      |                                |
 |                      |    [loop: matching messages]   |
 |                      |                                |
 |                      | NotifyDisplayMessagesRequest(   |
 |                      |   requestId=55,                |
 |                      |   messageInfo=[...],           |
 |                      |   tbc=false)                   |
 |                      |<-------------------------------|
 |                      |                                |
 |                      | NotifyDisplayMessagesResponse() |
 |                      |------------------------------->|
 |                      |                                |
 | [opt] notification   |                                |
 |<---------------------|                                |

Filter Examples

Filter by specific IDs

{
  "requestId": 55,
  "id": [1, 5, 10]
}

Filter by priority

{
  "requestId": 56,
  "priority": "AlwaysFront"
}

Filter by state

{
  "requestId": 57,
  "state": "Charging"
}

Combined filters (IDs + priority)

{
  "requestId": 58,
  "id": [1, 2, 3, 4, 5],
  "priority": "InFront"
}

Field	Type	Description
`id`	array of integers (min 1 item)	Return only messages with these IDs. Do NOT include more IDs than NumberOfDisplayMessages.maxLimit.
`priority`	MessagePriorityEnumType	Return only messages with this priority.
`state`	MessageStateEnumType	Return only messages configured for this state.

Note: All filters are optional. When one or more are provided, the Charging Station returns only messages matching all the specified criteria.

CSMS Response Handling

Identical to Flow O03. The CSMS handles the GetDisplayMessagesResponse and incoming NotifyDisplayMessagesRequest messages the same way, including proper tbc handling and sending NotifyDisplayMessagesResponse for each.

Response Handling

RECEIVE GetDisplayMessagesResponse:

  CASE "Accepted":
    -> Matching messages found. Wait for NotifyDisplayMessagesRequest(s).

  CASE "Unknown":
    -> No messages match the provided filter criteria.
    -> No NotifyDisplayMessagesRequest will follow.

7. O05 — Clear a DisplayMessage

CSMS-Initiated

Use Case ID	O05
Direction	CSMS → Charging Station
Trigger	CSO wants to remove a specific display message from a Charging Station
OCPP Messages	ClearDisplayMessageRequest / ClearDisplayMessageResponse

Flow Diagram

Sequence Diagram (CSMS perspective)

CSO                    CSMS                         Charging Station
 |                      |                                |
 | Clear msg(id=12)     |                                |
 |--------------------->|                                |
 |                      | ClearDisplayMessageRequest(    |
 |                      |   id=12)                       |
 |                      |------------------------------->|
 |                      |                                |
 |                      |              [Remove Message(id=12)]
 |                      |                                |
 |                      | ClearDisplayMessageResponse(Accepted)
 |                      |<-------------------------------|
 |                      |                                |
 | [opt] notification   |                                |
 |<---------------------|                                |

ClearDisplayMessageRequest — Sent by CSMS

Direction: CSMS → Charging Station
Schema ID: urn:OCPP:Cp:2:2025:1:ClearDisplayMessageRequest

ClearDisplayMessageRequest — Example

{
  "id": 12
}

Field	Type	Required	Description
`id`	integer (>= 0)	Yes	The unique ID of the message to remove.

Constraint: Only messages configured via OCPP (i.e., via SetDisplayMessageRequest) can be cleared. Firmware-embedded messages cannot be removed.

ClearDisplayMessageResponse — Received by CSMS

Direction: Charging Station → CSMS
Schema ID: urn:OCPP:Cp:2:2025:1:ClearDisplayMessageResponse

ClearDisplayMessageResponse — Example

{
  "status": "Accepted"
}

Field	Type	Required	Description
`status`	ClearMessageStatusEnumType	Yes	Result of the clear operation
`statusInfo`	StatusInfoType	No	Additional details

CSMS Response Handling Logic

Response Handling Decision Tree

RECEIVE ClearDisplayMessageResponse:

SWITCH response.status:

  CASE "Accepted":
    -> Message was successfully removed from the Charging Station.
    -> ACTION: Remove the message ID from local CSMS registry for this station.

  CASE "Unknown":
    -> No message with this ID exists on the Charging Station.
    -> POSSIBLE CAUSES:
       - Message was already cleared (duplicate request)
       - Message expired (endDateTime passed) and was auto-removed
       - Transaction-bound message was auto-removed when transaction ended
       - The ID was never set on this station
    -> ACTION: Log the event. Clean up local registry if the ID is still tracked.

  CASE "Rejected":
    -> The Charging Station cannot execute the clear request.
    -> ACTION: Check statusInfo for details. Retry later if appropriate.

8. O06 — Replace DisplayMessage

CSMS-Initiated

Use Case ID	O06
Direction	CSMS → Charging Station
Trigger	CSO wants to replace an existing display message with new content/parameters
OCPP Messages	SetDisplayMessageRequest / SetDisplayMessageResponse

This flow uses the same SetDisplayMessageRequest as Flow O01. The difference is that the id in the MessageInfoType matches an already-configured message on the Charging Station.

Flow Diagram

Sequence Diagram (CSMS perspective)

CSO                    CSMS                         Charging Station
 |                      |                                |
 |                      |              [Message id=15 is configured]
 |                      |                                |
 | Replace msg(id=15)   |                                |
 |--------------------->|                                |
 |                      | SetDisplayMessageRequest(      |
 |                      |   id=15, ...)                  |
 |                      |------------------------------->|
 |                      |                                |
 |                      | SetDisplayMessageResponse(Accepted)
 |                      |<-------------------------------|
 |                      |                                |
 | [opt] notification   |                                |
 |<---------------------|                                |
 |                      |              [Display updated message]

SetDisplayMessageRequest Example (Replace)

CSMS Processing Steps

Identify the existing message ID to replace.
Build a SetDisplayMessageRequest with the SAME id but new content/parameters.
Send to the Charging Station.

SetDisplayMessageRequest — Replace Example

{
  "message": {
    "id": 15,
    "priority": "InFront",
    "message": {
      "format": "UTF8",
      "content": "UPDATED: New tariff rates effective March 1st!",
      "language": "en-US"
    },
    "state": "Idle",
    "endDateTime": "2026-03-01T00:00:00Z"
  }
}

CSMS Response Handling

When replacing, the Charging Station replaces the existing message entirely (all parameters are overwritten with the new values) and responds with SetDisplayMessageResponse with status: Accepted. The response handling is identical to Flow O01 — all the same error statuses apply.

CSMS Implementation Notes

Full replacement: All fields are replaced. If the old message had an endDateTime and the new one does not, the message will no longer have an end time. The CSMS must re-specify all desired parameters.
Prerequisites: A message with the same ID must already exist on the Charging Station. If the ID does not exist, it will be treated as a new message (Flow O01 behavior — the station will create it).

9. Configuration Variables Reference

Reference

These Charging Station configuration variables are relevant to the Display Message feature. The CSMS should read these (via GetVariables) to understand station capabilities before sending requests.

Configuration Variable	Description	Usage
`NumberOfDisplayMessages.maxLimit`	Maximum number of messages the station can store	Check before setting messages to avoid Rejected
`DisplayMessageSupportedFormats`	List of supported MessageFormatEnumType values	Check before setting messages to avoid NotSupportedMessageFormat
`DisplayMessageSupportedPriorities`	List of supported MessagePriorityEnumType values	Check before setting messages to avoid NotSupportedPriority
`DisplayMessageSupportedStates`	List of supported MessageStateEnumType values	Check before setting messages to avoid NotSupportedState
`DisplayMessageLanguage`	Default language and list of supported languages	If not present, messageExtra is NOT supported and will result in Rejected. If present, only send languages in the valuesList.
`OCPPCommCtrlr.FieldLength["MessageContentType.content"]`	Max content length supported	Default is 1024 characters

10. CSMS Implementation Checklist

Reference

Message Lifecycle Management

Maintain a local registry of message IDs per Charging Station
Generate unique message IDs (integer >= 0) for each new message
Track message state: active, expired, cleared, transaction-bound
Auto-clean registry entries for expired messages ( endDateTime passed)
Auto-clean registry entries for transaction-bound messages when transaction ends

Outgoing Request Handlers (CSMS → Charging Station)

Handler	When to Call	Key Considerations
`Send SetDisplayMessageRequest`	CSO wants to create or replace a message	Check station capacity; validate format/priority/state/language support
`Send GetDisplayMessagesRequest`	CSO wants to see current messages	Use requestId for correlation; set filters as needed
`Send ClearDisplayMessageRequest`	CSO wants to remove a message	Only OCPP-configured messages can be cleared

Incoming Request Handlers (Charging Station → CSMS)

Handler	Message	Required Response	Key Logic
`Handle NotifyDisplayMessagesRequest`	Received after GetDisplayMessages	Send `NotifyDisplayMessagesResponse` (empty body)	Correlate via requestId; accumulate batches when tbc=true; finalize when tbc=false

Response Handlers (for CSMS-initiated requests)

Response	Possible Statuses	Actions
`SetDisplayMessageResponse`	Accepted, NotSupportedMessageFormat, Rejected, NotSupportedPriority, NotSupportedState, UnknownTransaction, LanguageNotSupported	Update local registry on Accepted; log and handle errors for all others
`GetDisplayMessagesResponse`	Accepted, Unknown	On Accepted: prepare to receive NotifyDisplayMessagesRequest(s). On Unknown: no messages exist.
`ClearDisplayMessageResponse`	Accepted, Unknown, Rejected	On Accepted: remove from local registry. On Unknown: message doesn't exist (clean up local state).

Pre-Send Validation Checklist

Before sending any SetDisplayMessageRequest, the CSMS should verify:

Format: Is the message.message.format in the station's DisplayMessageSupportedFormats?
Priority: Is the message.priority in the station's DisplayMessageSupportedPriorities?
State: If message.state is set, is it in the station's DisplayMessageSupportedStates?
Capacity: Will this message push the total count above NumberOfDisplayMessages.maxLimit?
Language: If messageExtra is included, is DisplayMessageLanguage present on the station? Are all languages in the supported list?
Transaction: If transactionId is set, is the transaction currently active on the target station?
Content Length: Is message.message.content within the station's max content length?

Complete JSON Schema Reference

Schema File	Direction	Description
`SetDisplayMessageRequest.json`	CSMS → CS	Set or replace a display message
`SetDisplayMessageResponse.json`	CS → CSMS	Response to set/replace
`GetDisplayMessagesRequest.json`	CSMS → CS	Query display messages (all or filtered)
`GetDisplayMessagesResponse.json`	CS → CSMS	Initial response (Accepted/Unknown)
`NotifyDisplayMessagesRequest.json`	CS → CSMS	Actual message data delivery (may be multi-part)
`NotifyDisplayMessagesResponse.json`	CSMS → CS	Acknowledgement of notification (empty body)
`ClearDisplayMessageRequest.json`	CSMS → CS	Remove a message by ID
`ClearDisplayMessageResponse.json`	CS → CSMS	Response to clear