Migration Guide 2.0.1 → 2.1 Section O

Display Message — Migration Guide

All changes in the Display Message functional block (Section O) between OCPP 2.0.1 Edition 4 and OCPP 2.1 Edition 2 from the CSMS implementation perspective.

9 Sections
6 Use Cases
O01 – O06

Created by tzi.app — your guide to migrating from OCPP 2.0.1 to OCPP 2.1.

1. Summary of Changes

New Flows Added in OCPP 2.1

None. The same six flows (O01–O06) exist in both versions.

Changed Flows

Flow Change Type Summary
O01 Enhanced New messageExtra field for multi-language support; new LanguageNotSupported response status; new QRCODE format
O02 Enhanced Same enhancements as O01 (inherits messageExtra, LanguageNotSupported, QRCODE)
O05 Enhanced New Rejected status added to ClearMessageStatusEnumType

Unchanged Flows

Flow Name
O03 Get All DisplayMessages
O04 Get Specific DisplayMessages
O06 Replace DisplayMessage

2. Shared Data Types Changes

MessageFormatEnumType — New Value

Value 2.0.1 2.1 Notes
ASCII Yes Yes
HTML Yes Yes
URI Yes Yes
UTF8 Yes Yes
QRCODE NEW No Yes New in 2.1. Content to be rendered as a QR code on the Charging Station display.

CSMS impact: If sending QRCODE format messages, verify the station supports it via DisplayMessageSupportedFormats. Stations running 2.0.1 firmware will reject this format.

MessageStateEnumType — New Values

Value 2.0.1 2.1 Notes
Charging Yes Yes
Faulted Yes Yes
Idle Yes Yes
Unavailable Yes Yes
Suspended NEW No Yes New in 2.1. Show only when charging is suspended.
Discharging NEW No Yes New in 2.1. Show only during V2G discharging.

CSMS impact: These new states enable more granular message targeting. Before using them, check the station's DisplayMessageSupportedStates configuration variable (also new in 2.1).

MessagePriorityEnumType — Clarified Behavior

The enum values (AlwaysFront, InFront, NormalCycle) are unchanged, but 2.1 provides more explicit behavioral descriptions:

Value Clarification Added in 2.1
AlwaysFront Explicitly stated: does NOT cycle. If a new AlwaysFront message is set, it replaces the previous one. Overrides ALL messages including firmware messages.
InFront Explicitly stated: multiple InFront messages cycle among themselves.

CSMS impact: No code changes required; this is a specification clarification. However, CSMS logic that sets multiple AlwaysFront messages should be aware that only the latest one will actually display.

DisplayMessageStatusEnumType — New Value

Value 2.0.1 2.1 Notes
Accepted Yes Yes
NotSupportedMessageFormat Yes Yes
Rejected Yes Yes
NotSupportedPriority Yes Yes
NotSupportedState Yes Yes
UnknownTransaction Yes Yes
LanguageNotSupported NEW No Yes New in 2.1. Returned when a language in message or messageExtra is not in the station's DisplayMessageLanguage configuration.

CSMS impact: Add handling for the LanguageNotSupported status in SetDisplayMessageResponse processing. When received, check the station's DisplayMessageLanguage configuration variable and retry with supported languages only.

ClearMessageStatusEnumType — New Value

Value 2.0.1 2.1 Notes
Accepted Yes Yes
Unknown Yes Yes
Rejected NEW No Yes New in 2.1. The Charging Station cannot execute the clear request.

CSMS impact: Add handling for Rejected status in ClearDisplayMessageResponse processing. Check statusInfo for details and retry later if appropriate.

MessageContentType — Max Length Increase

Field 2.0.1 2.1 Notes
content max 512 chars max 1024 chars (configurable) Default max is 1024. Actual max supported by a specific station is given in OCPPCommCtrlr.FieldLength["MessageContentType.content"].

CSMS impact: Messages can now contain up to 1024 characters by default (doubled from 512). Check the station's FieldLength configuration to determine actual supported length before sending longer content.

MessageInfoType — New messageExtra Field

Field 2.0.1 2.1 Notes
id Yes Yes
priority Yes Yes
state Yes Yes
startDateTime Yes Yes
endDateTime Yes Yes
transactionId Yes Yes
message Yes Yes
display Yes Yes
messageExtra NEW No Yes New in 2.1. Array of MessageContentType (1–4 items). Provides additional language versions of the message.

CSMS impact: The messageExtra field enables native multi-language message support. Instead of sending separate messages for different languages, the CSMS can include all translations in a single SetDisplayMessageRequest. The Charging Station selects the appropriate language version based on user preference or configuration.

Important constraint: If the station's DisplayMessageLanguage configuration variable is not present, messageExtra is NOT supported — sending it will result in a Rejected response. Always check for this variable before using messageExtra.

Example: 2.1 multi-language message

SetDisplayMessageRequest (2.1) 
{
  "message": {
    "id": 1,
    "priority": "NormalCycle",
    "message": {
      "format": "UTF8",
      "content": "Welcome! Tap your card to start.",
      "language": "en-US"
    },
    "messageExtra": [
      {
        "format": "UTF8",
        "content": "Welkom! Houd uw pas voor de lezer.",
        "language": "nl"
      },
      {
        "format": "UTF8",
        "content": "Willkommen! Halten Sie Ihre Karte an den Leser.",
        "language": "de"
      }
    ]
  }
}

StatusInfoType — Max Length Increase

Field 2.0.1 2.1 Notes
additionalInfo max 512 chars max 1024 chars Doubled max length for more detailed error information.

CSMS impact: Ensure parsing/storage for additionalInfo can handle up to 1024 characters.

EVSEType — Constraint Change

Field 2.0.1 2.1 Notes
id integer (> 0) integer (>= 0) 2.1 allows id = 0 (representing the Charging Station itself, not a specific EVSE).
connectorId integer (no constraint) integer (>= 0) Explicit lower bound added.

CSMS impact: EVSE ID 0 is now valid and refers to the Charging Station as a whole rather than a specific EVSE. Update validation logic if it currently rejects id = 0.

3. O01 — Set DisplayMessage

Changes

Aspect 2.0.1 2.1
MessageInfoType.messageExtra Not available New optional field: array of MessageContentType (1–4 items) for multi-language support
SetDisplayMessageResponse statuses 6 values 7 values — adds LanguageNotSupported
MessageFormatEnumType 4 values 5 values — adds QRCODE
MessageContentType.content max length 512 1024 (configurable)

Migration Actions

1

Add LanguageNotSupported response handling in the SetDisplayMessageResponse handler.

2

Optionally support messageExtra to send multi-language messages in a single request.

3

Optionally support QRCODE format for QR code display on station screens.

4

Update content length validation to allow up to 1024 characters (or the station-specific configured limit).

4. O02 — Set DisplayMessage for Transaction

Changes

Same as O01. This flow inherits all MessageInfoType and response enum changes.

Migration Actions

Same as O01.

5. O03 — Get All DisplayMessages

Changes

No structural changes to the flow, request, or response messages.

The NotifyDisplayMessagesRequest payload may now include messageExtra fields in the returned MessageInfoType objects (if the station supports multi-language messages).

Migration Actions

1

Parse messageExtra when processing NotifyDisplayMessagesRequest — returned messages may contain additional language versions.

6. O04 — Get Specific DisplayMessages

Changes

No structural changes. Same consideration as O03 regarding messageExtra in returned messages.

The state filter now accepts the new Suspended and Discharging values.

Migration Actions

1

Parse messageExtra in returned messages.

2

Optionally use new state filters (Suspended, Discharging) when querying messages.

7. O05 — Clear a DisplayMessage

Changes

Aspect 2.0.1 2.1
ClearMessageStatusEnumType 2 values (Accepted, Unknown) 3 values — adds Rejected

Migration Actions

1

Add Rejected response handling in the ClearDisplayMessageResponse handler. When received, check statusInfo for details. The station cannot execute the clear request — retry later if appropriate.

8. O06 — Replace DisplayMessage

Changes

No structural changes to the flow itself. This flow uses SetDisplayMessageRequest, so it inherits all the changes from O01 (new messageExtra field, LanguageNotSupported response, QRCODE format, increased content length).

Migration Actions

Same as O01.

9. Configuration Variables Changes

New in 2.1

Variable Description CSMS Impact
DisplayMessageSupportedStates NEW List of supported MessageStateEnumType values Check before setting messages with a state filter to avoid NotSupportedState rejection. Particularly important for the new Suspended and Discharging states.
DisplayMessageLanguage NEW Default language and list of supported languages Critical for messageExtra support. If this variable is not present on the station, messageExtra is NOT supported and will result in Rejected. If present, only send languages listed in valuesList.
OCPPCommCtrlr.FieldLength["MessageContentType.content"] NEW Max content length supported by the station Default is 1024 characters. Check to avoid truncation or rejection when sending long message content.

Existing (unchanged)

Variable Description
DisplayMessageCtrlr.Available Whether the DisplayMessage feature is available
DisplayMessageCtrlr.Enabled Whether the DisplayMessage feature is enabled
NumberOfDisplayMessages Maximum number of display messages the station can store
DisplayMessageSupportedFormats Supported MessageFormatEnumType values (now may include QRCODE)
DisplayMessageSupportedPriorities Supported MessagePriorityEnumType values