Migration Guide 2.0.1 → 2.1 Section N

Diagnostics — Migration Guide

Use cases N01–N15 (Diagnostics). Covers logging, monitoring, event notifications, customer information, and the new periodic event streams. Perspective: CSMS Developer.

11 Sections
15 Use Cases
N01 – N15

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

Flow Name Description
N11 Set Frequent Periodic Variable Monitoring Set up high-frequency periodic monitoring via efficient event streams
N12 Get Periodic Event Streams Retrieve all currently open periodic event streams
N13 Close Periodic Event Streams Handle or trigger closing of periodic event streams
N14 Adjust Periodic Event Streams Adjust transmission rate of an existing event stream
N15 NotifyPeriodicEventStream Process high-frequency monitoring data via unconfirmed SEND messages

Changed Flows

Flow Change Type Summary
N01 Enhanced New DataCollectorLog log type; URL max length increased; stricter URL requirements
N02 Enhanced VariableMonitoringType gains eventNotificationType field; new MonitorEnumType values; explicit expansion rules
N04 Enhanced New periodicEventStream field on SetMonitoringDataType for event stream configuration
N06 Enhanced New message size configuration variables; auto-close behavior for associated event streams
N07 Enhanced EventDataType gains severity field; expanded Alerting trigger scope; offline queuing behavior
N08 Enhanced Offline queuing behavior documented
N09 Breaking Customer identification rule changed from "at least one SHOULD" to "exactly one MUST"
N10 Enhanced Explicit Local Authorization List handling requirement

Unchanged Flows

  • N03 — Set Monitoring Base — No changes
  • N05 — Set Monitoring Level — No changes

2. New Flows (2.1 Only)

New

N11 — Set Frequent Periodic Variable Monitoring

Enables high-frequency periodic monitoring using efficient event streams instead of individual NotifyEventRequest messages

How It Works

  1. CSMS sends SetVariableMonitoringRequest with the new periodicEventStream field populated.
  2. CS accepts and opens a stream via OpenPeriodicEventStreamRequest (CS → CSMS).
  3. CSMS accepts or rejects via OpenPeriodicEventStreamResponse.
  4. CS sends NotifyPeriodicEventStream SEND messages (no response required).

New Messages

Message Direction Response
OpenPeriodicEventStreamRequest CS → CSMS Accepted / Rejected
NotifyPeriodicEventStream CS → CSMS No response (SEND)

New Data Types

Type Fields
PeriodicEventStreamParamsType interval (seconds between flushes), values (items per flush)
ConstantStreamDataType id (stream ID), variableMonitoringId, params
StreamDataElementType t (time offset in seconds), v (measured value)

CSMS action: Implement handler for OpenPeriodicEventStreamRequest — store stream metadata and map stream ID to monitor data. Implement handler for NotifyPeriodicEventStream SEND messages — reconstruct full event data from compact stream format. Monitor pending field to detect CS data backlog.

New

N12 — Get Periodic Event Streams

Retrieve all open periodic event streams — useful for CSMS recovery after restart

Direction Message
CSMS → CS GetPeriodicEventStreamRequest (empty body)
CS → CSMS GetPeriodicEventStreamResponse (array of ConstantStreamDataType)
New

N13 — Close Periodic Event Streams

Handle the CS closing a stream, or trigger closure indirectly

Message Direction Response
ClosePeriodicEventStreamRequest CS → CSMS ClosePeriodicEventStreamResponse (empty)

Three Closing Scenarios

  • CS-initiated close: CS flushes remaining data, sends ClosePeriodicEventStreamRequest, then reverts to NotifyEventRequest.
  • CSMS clears the monitor (N06): CS auto-closes the associated stream.
  • CSMS replaces the monitor without stream (N04): CS auto-closes the associated stream.
New

N14 — Adjust Periodic Event Streams

Adjust the transmission rate of an existing stream without closing and reopening it

Direction Message
CSMS → CS AdjustPeriodicEventStreamRequest (id, params)
CS → CSMS AdjustPeriodicEventStreamResponse (Accepted / Rejected)
New

N15 — Periodic Event Streams (NotifyPeriodicEventStream)

Process high-frequency periodic data from the CS using the SEND message type (unconfirmed)

Key protocol detail: Uses the SEND message type (unconfirmed). The CSMS does NOT send any response.

Message Format

Field Description
id Stream ID (from OpenPeriodicEventStreamRequest)
basetime Base timestamp
pending Number of data elements still queued on the CS
data[] Array of { t: <offset_seconds>, v: <value> }

3. N01 — Retrieve Log Information

New LogEnumType Value

Value Version Description
DiagnosticsLog 2.0.1, 2.1 General diagnostics log
SecurityLog 2.0.1, 2.1 Security-specific log
DataCollectorLog 2.1 2.1 only High-frequency measurand samples from the DataCollector

log.remoteLocation Max Length Increased

Version Max Length
2.0.1 512 characters
2.1 2000 characters

New URL Requirements (2.1)

OCPP 2.1 introduces stricter URL validation rules (N01.FR.26-28):

Rule Requirement
N01.FR.26 The upload URL MUST NOT point to a server that responds with a redirect
N01.FR.27 The URL MUST NOT contain a fragment component (#)
N01.FR.28 If the URL includes a query component, it MUST NOT end with a slash (/)

Migration action: Add support for requesting DataCollectorLog type. Update URL field validation to accept up to 2000 characters. Validate generated upload URLs against the new URL rules before sending GetLogRequest.

4. N02 — Get Monitoring Report

VariableMonitoringType Gains eventNotificationType Field

2.0.1: id, transaction, value, type, severity

2.1 adds: eventNotificationType (EventNotificationEnumType) — required in 2.1

Field Type Required Description
eventNotificationType 2.1 EventNotificationEnumType Yes (2.1) Origin type: HardWiredNotification, HardWiredMonitor, PreconfiguredMonitor, CustomMonitor

New MonitorEnumType Values

Value Version Description
UpperThreshold 2.0.1, 2.1 Triggers when value exceeds threshold
LowerThreshold 2.0.1, 2.1 Triggers when value drops below threshold
Delta 2.0.1, 2.1 Triggers when value changes by delta amount
Periodic 2.0.1, 2.1 Triggers at periodic intervals
PeriodicClockAligned 2.0.1, 2.1 Triggers at clock-aligned intervals
TargetDelta 2.1 2.1 only Triggers when actual differs from target by more than +/- value
TargetDeltaRelative 2.1 2.1 only Triggers when actual differs from target by more than +/- (value × target)

Explicit ComponentVariable Expansion Rules (2.1)

OCPP 2.1 explicitly documents how partial componentVariable filter specifications are expanded by the CS:

Omitted Field CS Behavior
Missing variable Reports every variable of the component
Missing variable.instance Reports every instance of that variable
Missing evse.connectorId Reports for every connector of that EVSE
Missing evse.id Reports for every EVSE
Specified component.instance Reports only components with that instance name
Missing component.instance Reports every instance or components without an instance

New Configuration Variable

Variable Description
ItemsPerMessageGetReport Max componentVariable items in GetMonitoringReportRequest

Migration action: Parse and store the eventNotificationType from monitoring report data. Add support for the new TargetDelta and TargetDeltaRelative monitor types. Verify your filter logic aligns with the expansion rules. Respect the ItemsPerMessageGetReport limit.

5. N04 — Set Variable Monitoring

New periodicEventStream Field on SetMonitoringDataType

Field Type Required Description
periodicEventStream 2.1 PeriodicEventStreamParamsType No Parameters for periodic event streaming (N11)

PeriodicEventStreamParamsType

Field Type Required Description
interval integer (≥ 0) No Seconds between stream data flushes
values integer (≥ 0) No Number of items per stream flush

Migration action: When setting a Periodic or PeriodicClockAligned monitor on a 2.1 station, optionally include periodicEventStream to use the efficient event stream mechanism. At least one of interval or values must be provided (N11.FR.09).

6. N06 — Clear / Remove Monitoring

New Message Size Configuration Variables

Variable Description
ItemsPerMessageClearVariableMonitoring Max id items in ClearVariableMonitoringRequest
BytesPerMessageClearVariableMonitoring Max bytes for ClearVariableMonitoringRequest

The CS may respond with:

  • CALLERROR(OccurenceConstraintViolation) if too many IDs are sent (N06.FR.06)
  • CALLERROR(FormatViolation) if message exceeds byte limit (N06.FR.07)

Periodic Event Stream Auto-Close (2.1)

When clearing a monitor that has an associated periodic event stream, the CS will automatically close the stream (N13.FR.05) and send a ClosePeriodicEventStreamRequest.

Migration action: Respect the new message size limits. Handle the ClosePeriodicEventStreamRequest that may follow a ClearVariableMonitoringRequest.

7. N07/N08 — Alert & Periodic Events

N07 — EventDataType Gains severity Field

Field Type Required Description
severity 2.1 integer (0-9) No (SHOULD be present) Severity of the monitor that triggered this event
Aspect OCPP 2.0.1 OCPP 2.1
Severity access Only via monitor config lookup using variableMonitoringId Included directly in event data

Expanded Alerting Trigger Scope

Version Alerting Trigger Covers
2.0.1 UpperThreshold and LowerThreshold monitors
2.1 Also covers TargetDelta and TargetDeltaRelative monitors

Offline Event Queuing Behavior (N07 & N08)

OCPP 2.1 explicitly documents offline queuing behavior for both Alert (N07) and Periodic (N08) events.

  • Events with severity ≤ OfflineMonitoringEventQueuingSeverity are queued by the CS when offline and delivered upon reconnection.
  • The logical chain of events may be broken (e.g., a cleared event may arrive without the CSMS having seen the original trigger).
  • CSMS should delay evaluation of such events until the station is back online.

Migration action: Use the severity field when present to avoid a lookup. Update alert event processing to handle Alerting triggers from target-delta monitor types. Add logic to handle incomplete event chains after a station reconnects.

8. N09/N10 — Customer Information

N09 — Customer Identification Rule Change

Breaking change: Ensure exactly one identifier is provided per request. Sending none or more than one will result in an Invalid response.

Aspect OCPP 2.0.1 OCPP 2.1
Identification fields customerIdentifier, idToken, customerCertificate Same fields
Rule At least one SHOULD be provided Exactly one MUST be provided (N09.FR.04)
None provided CS may still try to process CS returns Invalid
Multiple provided Not explicitly prohibited CS returns Invalid

N09 — Additional Validation Rules (2.1)

  • If both report and clear are false, the CS is recommended to respond with Rejected (N09.FR.07).
  • When using customerCertificate, query installed certificate IDs first via GetInstalledCertificateIdsRequest to determine the correct hashAlgorithm (N09.FR.08).

N10 — Clear Customer Information

Local Authorization List Handling (2.1)

OCPP 2.1 explicitly requires (N10.FR.02): If the customer is in the CS's Local Authorization List, the CSMS SHALL update it via SendLocalListRequest. The CS will remove customer data except from the LocalList (only CSMS can modify the LocalList).

  • After clearing customer data, check if the customer exists in the Local Authorization List and send a SendLocalListRequest to remove them if applicable.
  • When referencing a customer by certificate, the correct hashAlgorithm must match the one used to install the certificate (N10.FR.09).

Migration action: Ensure exactly one identifier per GetCustomerInformationRequest. Ensure at least one of report or clear is true. After clearing customer data, update the Local Authorization List via SendLocalListRequest.

9. Shared Data Types Changes

StatusInfoType

Field OCPP 2.0.1 OCPP 2.1 Change
additionalInfo max length 512 1024 Doubled

IdTokenType

Field OCPP 2.0.1 OCPP 2.1 Change
idToken max length 36 255 Increased
type IdTokenEnumType (enum) string (max 20) Enum → free-form string

2.0.1 enum values: Central, eMAID, ISO14443, ISO15693, KeyCode, Local, MacAddress, NoAuthorization. In 2.1, the type field is now a string (max 20 chars), allowing vendor-specific token types.

EVSEType

Field OCPP 2.0.1 OCPP 2.1 Change
id constraint > 0 ≥ 0 Now allows 0 (entire Charging Station)
connectorId constraint (not specified) ≥ 0 Explicit constraint added

Migration action: Update IdToken handling to accept any string value for type (max 20 chars) instead of validating against a fixed enum. Allow EVSEType.id = 0 in 2.1 (represents the Charging Station itself). Update field length validations accordingly.

10. New Configuration Variables (2.1)

Variable Affects Description
ItemsPerMessageGetReport N02 Max componentVariable items in GetMonitoringReportRequest
ItemsPerMessageClearVariableMonitoring N06 Max id items in ClearVariableMonitoringRequest
BytesPerMessageClearVariableMonitoring N06 Max bytes for ClearVariableMonitoringRequest
OfflineMonitoringEventQueuingSeverity N07, N08 Severity threshold for offline event queuing

11. New CSMS Message Handlers

Incoming Messages (CS → CSMS)

Incoming Message Response Flow
OpenPeriodicEventStreamRequest OpenPeriodicEventStreamResponse (Accepted / Rejected) N11
ClosePeriodicEventStreamRequest ClosePeriodicEventStreamResponse (empty) N13
NotifyPeriodicEventStream No response (SEND) N15

Outgoing Messages (CSMS → CS)

Outgoing Message Response Flow
GetPeriodicEventStreamRequest GetPeriodicEventStreamResponse N12
AdjustPeriodicEventStreamRequest AdjustPeriodicEventStreamResponse N14

OCPP 2.1 Diagnostics Migration Guide — Section N (Use Cases N01–N15) — CSMS Developer Perspective