Technical Specification

Transport & Security¶

This section defines the technical characteristics of communication between the Charging Management System (CMS) and upstream systems, focusing on WebSocket connection setup, transport security, and authentication.

WebSocket Connection¶

Communication between the CMS and upstream systems uses the WebSocket protocol (IETF RFC 6455).

Roles¶

CMS acts as the server.
Upstream systems act as clients.

After connection establishment, both can exchange messages bidirectionally, independent of connection initiator.

Connection URL Format¶

wss://<address>:<port>/<path>

wss – Secure WebSocket (TLS-encrypted).
<address> – DNS-resolvable hostname or IP address of CMS endpoint.
<port> – Port number of the endpoint.
<path> – Optional URL path component (can include hierarchy).

Client-Initiated Connection¶

Upstream systems open the WebSocket connection to the CMS at a preconfigured endpoint URL. Example configuration might look like:

wss://cms.betterfleet.local:443/vdv463

Subprotocol Negotiation¶

When establishing the connection, clients can list supported subprotocols via the HTTP header Sec-WebSocket-Protocol. The CMS selects the highest compatible protocol version.

Current supported subprotocol:

Sec-WebSocket-Protocol: v1.463.vdv.de

This mechanism supports future incompatible protocol extensions.

CMS Response and Error Cases¶

Successful Connection

CMS completes the WebSocket handshake and upgrades the connection.
The channel is now ready for message exchange.

Error Cases

If none of the proposed subprotocols are supported, the CMS finalizes the handshake without sending a protocol header and then terminates the connection.

Example Handshake¶

Client Request (Upstream → CMS):

GET /vdv463/BMS400 HTTP/1.1
Host: CMS.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Origin: http://example.com
Sec-WebSocket-Protocol: v1.463.vdv.de, v2.463.vdv.de
Sec-WebSocket-Version: 13

CMS Response:

HTTP/1.1 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: v1.463.vdv.de

Security and Authentication¶

All WebSocket communication must be TLS-encrypted. The CMS must authenticate itself to clients with a certificate, while upstream systems authenticate using HTTP Basic Access Authentication.

Authentication¶

Clients authenticate via HTTP Basic Authentication during the initial WebSocket handshake.
Credentials must be securely stored both in the upstream system and the CMS.
The CMS validates credentials by comparing them with stored values.

Certificates¶

TLS certificates ensure confidentiality, integrity, and authenticity of the data exchanged between CMS and upstream systems.

Supported Certificate Options 1. CA-signed certificate: Traceable to a trusted root via public Certification Authorities. 2. Self-signed certificate: Manually trusted and distributed to upstream systems during setup.

Both CMS and upstream systems must support both options.

Certificate Properties | Property | Specification | |-----------|----------------| | Type | X.509 (IETF RFC 5280) | | Encryption | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 (RFC 5289) | | Key Usage | Digital Signature, Non‑Repudiation, Key Encipherment, Key Agreement | | Extended Key Usage | TLS Web Server Authentication, TLS Web Client Authentication | | TLS Version | (RFC 5246) |

Validation Certificate validation must comply with IETF RFC 5280.

Validity Certificate validity periods depend on the operator’s security policy.

Summary of Security Requirements

Transport: TLS (mandatory)
Authentication: HTTP Basic (client) + X.509 Certificate (server)
Protocol Version: WebSocket RFC 6455
Encryption Cipher: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256

Message Model & Semantics¶

This section defines the common structure, behavior, and semantics of messages exchanged between CMS and upstream systems.

Message Envelope Structure¶

All WebSocket messages follow the same schema where each frame is a JSON array with exactly seven elements in the order shown below:

Index (0-based)	Type	Description
`0`	Integer	Message type (`1` = Request/`req`, `2` = Confirmation/`conf`, `3` = Error/`err`).
`1`	String	Source identifier of the message.
`2`	String	`presystemId` — unique identifier of the upstream system. `BMS = Depot Management Systems, ITCS = Integrated Transport Control System`
`3`	String (`date-time`)	Timestamp of message creation in ISO-8601 format.
`4`	String (`uuid`)	`messageId` — used to correlate requests and responses.
`5`	String	`messageAction` — one of `BootNotification`, `ProvideChargingRequests`, `ProvideChargingInformation`.
`6`	Object	`payload` — message content defined by the corresponding schema for the action.

The array representation is positional. Consumers must not reorder or omit entries; producers must populate all seven elements.

The message envelope is therefore a positional JSON array that must match the schema definitions.

Example Message¶

[ 1, "UpstreamSystemA", "ITCS", "2024-01-01T12:00:00Z", "550e8400-e29b-41d4-a716-446655440000", "ProvideChargingRequests", { /* Payload content */ } ]

Message Type Semantics¶

Type	Meaning
`Request (req)`	Message initiated by a sender (e.g., `ProvideChargingRequests.req`).
`Confirmation (conf)`	Acknowledgement from the receiver confirming receipt and syntactic correctness.
`Error (err)`	Indicates the receiver cannot process the message due to syntax or unknown action.

Notes:

Each request (req) must be answered with either a confirmation or an error message.
An error message still serves as a technical confirmation of receipt.
Messages are correlated by matching MessageId between request and response.

Transmission Rules¶

The sender must wait for confirmation before sending the next message to the same recipient.
The waiting period (timeout) and retry count are configurable per system.
If a confirmation or error is not received within the waiting time, the sender retries until the maximum number of retries is reached.

Ping/Pong Mechanism¶

Upstream systems periodically send a ping to maintain connection health.
CMS responds with a pong.
Interval is configurable on both sides.
If no ping is received within the defined interval, CMS assumes the upstream system is unreachable.

Message Initiators and Actions¶

Initiator	Message Types	Description
Upstream System → CMS	`BootNotification.req` `ProvideChargingRequests.req`	Upstream-originated requests for registration or request updates.
CMS → Upstream System	`ProvideChargingInformation.req`	CMS-originated updates about depot/station/point/vehicle status.

BootNotification¶

Used by an upstream system to register with the CMS.

BootNotification.req¶

Sent when:

Initially connecting to CMS.
Reconnecting after a connection loss.
Changing PresystemId (after re-establishing connection).

BootNotification.conf¶

CMS response indicating whether communication is accepted.

Field	Type	Description
`status`	Enum {`Accepted`, `Rejected`}	Indicates CMS acceptance or rejection.

ProvideChargingRequests¶

Message from upstream systems to the CMS.

Purpose¶

Transmits all valid charging requests — including new, modified, and terminated ones.

Behavior¶

Missing requests in subsequent messages are treated as deletions (if not started).
Ongoing requests are cancelled only when chargingInstruction = Terminate.
After establishing a connection, the first ProvideChargingRequests.req is sent only after receiving a ProvideChargingInformation.req from the CMS.

Responses¶

ProvideChargingRequests.conf — Empty payload confirmation from CMS.

ProvideChargingInformation¶

Message from CMS to upstream systems.

Purpose¶

Reports the current state of depots, charging stations, charging points, and connected vehicles.

Behavior¶

Sent at a configurable interval per upstream system.
Each message must be acknowledged with a ProvideChargingInformation.conf (empty payload).

Responses¶

ProvideChargingInformation.conf — Confirms receipt.

Error Handling¶

If a receiver cannot process a message due to unknown MessageAction or invalid data syntax: - Respond with an Error (MessageType = 3). - Include a descriptive payload string explaining the problem.

This response replaces a confirmation message for that MessageId.

Offline and Reconnection Behavior¶

Connection Loss¶

If the WebSocket connection drops:

Upstream System Failure: CMS waits for reconnection.
CMS Failure: Upstream periodically attempts to reconnect at a configurable interval.

Recovery Procedure¶

Upon reconnection, upstream re-registers with a BootNotification.req.
CMS replies with BootNotification.conf.
CMS sends ProvideChargingInformation.req.
Upstream resumes sending ProvideChargingRequests.req.

Persistence¶

Systems are not required to buffer or resend historical messages beyond retry attempts during connection loss.

Summary of Communication Flow:

Upstream: BootNotification.req  →  CMS: BootNotification.conf
Upstream: ProvideChargingRequests.req  →  CMS: ProvideChargingRequests.conf
CMS: ProvideChargingInformation.req  →  Upstream: ProvideChargingInformation.conf

Enumeration Types¶

ChargingInstruction¶

Type describing the kind of charging order.

Value	Meaning
`Normal`	New/normal charging order.
`Changed`	The charging order was updated.
`Terminate`	Terminate the associated charging request immediately.

Note: When charging orders are transmitted, all charging orders known to the upstream system are transmitted.

ChargingPointFaultCode¶

Fault codes for charging point faults.

Value	Meaning
`NoFaultKnown`	No fault known to the system.
`UsageFailure`	Usage error; user interaction required.
`CommunicationFailure`	IT network problem; IT expert required (OCPP: `CP-EV-CommFailure`).
`OtherChargingPointFailure`	Product failure; inform charging station/point manufacturer.

ChargingPointStatus¶

Current status of a charging point (aligned with OCPP).

Value	Meaning
`Available`	Plug available.
`Occupied`	Charging point in use.
`Reserved`	Plug reserved for a job.
`Unavailable`	Plug disabled via higher-level command (OCPP `ChangeAvailability`).
`Faulted`	Fault present; not available for energy transfer.

ChargingStationFaultCode¶

Error codes for charging station faults.

Value	Meaning
`NoFaultKnown`	No fault known.
`UsageFailure`	Usage error; user interaction required (OCPP: `DoorOpenFailure`).
`CommunicationFailure`	IT network problem; operating staff needed (OCPP: `CSMS-CS-CommFailure`).
`ElectricalOperationFailure`	Electrical system failure; notify ops (OCPP: `GroundFailure`, `PowerSupplyFailure`, `TempOutsideSpecOperationRangeFailure`).
`ConfigurationFailure`	Contact CSMS admin or station manufacturer (OCPP: `LocalListConflictFailure`, `FirmwareUpdateFailure`).
`OtherChargingStationFailure`	Product failure; contact station manufacturer (OCPP: `InternalSWFailure`, `InternalHWFailure`).

ChargingStationStatus¶

Current status of a charging station (aligned with OCPP).

Value	Meaning
`Available`	Station is available.
`Unavailable`	Station is not available.
`Faulted`	Fault present; not available for power transfer.

PreconditioningRequest (VDV 261)¶

Value	Meaning
`WarmWaterAndVentilation`	Only warm water and ventilation.
`HotWaterAndHeating`	Hot water and heating.
`NoWaterCoolingOrVentilation`	No hot water, cooling, or ventilation.
`NoClimaticPreconditioningOrSNA`	No climatic preconditioning or SNA.

ProcessStatus¶

Status of a charging process (aligned with OCPP where possible).

Value	Meaning
`Preparing`	Connector not free for a new vehicle; energy transfer not yet started.
`Charging`	Vehicle is charging.
`SuspendedEVSE`	Vehicle connected; station not supplying power.
`SuspendedEV`	Station supplying power; vehicle not charging.
`Finishing`	Transfer finished; connector not yet available for new vehicle.
`Queued`	Process queued. (Extension)
`ChargingRejectedTechnically`	Order rejected for technical reasons. (Extension)

VehicleChargingStatus (VDV 261)¶

Value	Meaning
`ReadyToCharge`	Vehicle can accept power.
`Charging`	Vehicle is charging.
`ChargingImpossible`	Vehicle cannot accept power (malfunction).
`Unknown`	No VDV connection between management and vehicle.

VehicleFaultCode¶

Currently, no universally valid vehicle fault codes are defined.

BatteryStatus¶

Condensed health status of the traction battery.

Value	Meaning
`OK`	Battery operating within expected parameters.
`NOK`	Fault detected; operator attention required.
`NA`	Status not available from vehicle.

H2TankStatus¶

Condensed health status of the hydrogen tank.

Value	Meaning
`OK`	H2 tank operating within expected parameters.
`NOK`	Fault detected; operator attention required.
`NA`	Status not available from vehicle.

ErrorCode¶

Error codes for message processing outcomes.

ErrorCode	Category	Typical Use Case / Meaning
`InvalidRequest`	Protocol	Request message malformed, missing mandatory fields.
`UnknownAction`	Protocol	`MessageAction` not recognized or supported.
`Unauthorized`	Security	Authentication or authorization failed.
`NotSupported`	Protocol	Requested operation not supported by this system.
`InternalError`	System	Generic internal system error or exception.
`Timeout`	Communication	Response not received from downstream system (e.g., OCPP backend).
`ResourceUnavailable`	System	Required resource (e.g., charging point) is offline or not ready.
`RejectedTechnically`	Business	LMS rejects a charging request for technical reasons (mirrors “ChargingRejectedTechnically” semantics).
`RejectedOperationally`	Business	Request cannot be fulfilled due to scheduling, depot, or operational constraints.
`InvalidState`	Business	Action not allowed in current charging or depot state.
`Conflict`	Business	Another operation conflicts with the request (e.g., slot already occupied).

Information Flow: Upstream System → CMS (ProvideChargingRequests)¶

The chargingRequestList contains all requests or updates known to the upstream system. If a chargingRequestId exists from a previous delivery, the entry is interpreted as an update.

ChargingRequest¶

Attributes¶

chargingPointId (optional) — Identifier of the charging point at which the vehicle is to be charged. May be assigned late by BMS.
vehicleId — Identifier of the vehicle (typically VIN, as per VDV 261).
chargingRequestId — Unique reference per upstream system to the currently valid charging request.
chargingProcessId (required when referencing an existing process) — Reference to the charging process being changed; enables modifying spontaneous charging processes not originally commissioned.
priority — Importance of the charging process. Lower values = higher priority if multiple requests exist.
chargingInstruction — Type of charging order (see ChargingInstruction).
chargingRequestData — Substructure containing charging request data (see 2).
automaticPreconditioning — Substructure for automatic preconditioning (see 3).
manualPreconditioning — Substructure for manual preconditioning (see 4).

ChargingRequestData¶

Represents data of a charging request.

Attributes¶

expectedArrivalTimeAtChargingPoint — Estimated arrival time of the vehicle at the charging point.
expectedSocAtArrival — Expected SoC (%) upon arrival, relative to current available capacity.
minTargetSoc — Minimum SoC target (%) relative to the current maximum capacity (considering SoH).
maxTargetSoc — Maximum SoC target (%) relative to the current maximum capacity (considering SoH).
requestedTimeForDeparture — Desired departure time when the bus is unplugged from the charging infrastructure.
adHocCharging — Immediate charging flag. If true, start charging immediately after vehicle arrival. If multiple ad‑hoc requests exist, their priority values determine scheduling order.

minTargetSoc and maxTargetSoc are mandatory per the schema; the remaining attributes are optional.

AutomaticPreconditioning¶

Describes automatic preconditioning parameters for the vehicle.

Attributes¶

preconditioningRequest — Type of preconditioning, following VDV definitions. (Required)
requestedStartTime — Start time for the automatic preconditioning sequence.
ambientTemperature — External ambient temperature (°C) outside the underground car park or depot.
requestedFinishTime — Time by which the preconditioning should be completed (before vehicle unplug).

ManualPreconditioning¶

Used when vehicles do not support automatic preconditioning or for unscheduled trips.

Attributes¶

hvacPreconditioningStartTime — Start time for climatic preconditioning. (Required)
hvacAuxiliaryConsumerPower — Power specification for climatic preconditioning (air conditioning/heating) in kW.
systemPreconditioningStartTime — Start time for system-level preconditioning (24V systems, compressed air, traction battery, etc.). (Required)
systemAuxiliaryConsumerPower — Power specification for system preconditioning (in kW).

Implementation Note: Preconditioning structures (automaticPreconditioning and manualPreconditioning) enable upstream systems to specify environmental or system preparation before vehicle operation, aligning with the VDV 261 preconditioning framework.

Information Flow: CMS → Upstream System (ProvideChargingInformation)¶

The depotInfoList is used for the exchange of information from the Charging Management System (CMS) to upstream systems regarding depots, charging stations, and charging points (including vehicles and electrical parameters).

This information is typically transmitted cyclically so that upstream systems can monitor charging station and process status.

DepotInfo¶

Information structure for a depot.

Attributes¶

depotId — Identifier of the depot (e.g., URI or reference ID).
name — Human-readable name of the depot.
chargingStationInfoList — List of charging stations assigned to this depot (see 2).

ChargingStationInfo¶

Information about an individual charging station.

Attributes¶

chargingStationId — Unique identifier for the charging station (unique across depots).
chargingStationStatus — Current status (see ChargingStationStatus).
chargingPointInfoList — List of charging points assigned to this station (see 3).
chargingStationFaultInfo — Fault information at the station level (see 18).
totalPower — Current total power drawn from the energy supplier (kW).

ChargingPointInfo¶

Status information of a charging point.

A charging point is a location where a vehicle can be charged — typically associated with at least one parking space.

Attributes¶

chargingPointId — Unique identifier of the charging point.
chargingPointStatus — Current status (see ChargingPointStatus).
chargingPointFaultInfo — Fault information (see 4).
insideTemperature — Internal temperature (°C). Optional; useful for fault detection.
outsideTemperature — External temperature (°C). Optional.
connectorTemperature — Temperature at the charging interface (°C). Optional.
presentPower — Currently available power (kW). Optional.
energyMeterReading — Cumulative energy meter value (Wh). Optional.
vehicleInfo — Substructure for vehicle data (see 5). Must be present if a vehicle communicates with the charging point.
chargingProcessInfo — Substructure for charging process data (see 11). Must be present when charging occurs.
scheduledChargingProcessList — List of planned charging processes (see 17).

ChargingPointFaultInfo¶

Describes faults at the charging point level.

Attributes¶

chargingPointFaultCode — Fault code (see ChargingPointFaultCode).
faultText — Textual fault description.
faultTimeStamp — Date/time of fault occurrence.

VehicleInfo¶

Vehicle-related data at the charging station.

Attributes¶

vehicleId — Vehicle identifier (e.g., VIN). Required.
evccId — MAC address of the Electric Vehicle Communication Controller (ISO 15118).
mileage — Vehicle odometer reading (km).
tractionBatteryInfo — See 6.
h2TankInfo — See 7.
vehicleStatusInfo — See 8. Required.
vehicleChargingStatus — Status per VehicleChargingStatus. Required.
vehicleFaultInfo — See 9.
preconditioningInfo — See 10. Required.

TractionBatteryInfo¶

Information about the vehicle’s traction battery.

Attributes¶

stateOfCharge — Current SoC (%) relative to available max capacity.
stateOfHealth — Current SoH (%) relative to nominal max capacity.
temperature — Battery temperature (°C).
batteryStatus — Condensed health status (OK, NOK, NA).

H2TankInfo¶

Hydrogen tank status information (if available).

Attributes¶

h2TankStatus — Condensed health status (OK, NOK, NA).

VehicleStatusInfo¶

Status of the vehicle systems.

Attributes¶

conservationChargingActive — Whether conservation charging is active.
systemPreconditioningActive — Whether the vehicle is preconditioning systems (24V, air, traction battery).
hvacPreconditioningActive — Whether climatic preconditioning (heating/cooling) is active.
balancingActive — Whether battery cell balancing is active.
fossilFlameControlActive — Whether fossil flame control is active.
batteryChargingVoltage — Current voltage of the 12/24V system (V).

VehicleFaultInfo¶

Describes vehicle-level faults.

Attributes¶

vehicleFaultCode — Fault code (see VehicleFaultCode).
faultText — Textual fault description.
faultTimeStamp — Date/time of fault occurrence.

PreconditioningInfo¶

Structure for vehicle preconditioning data (VDV 261). Required within VehicleInfo.

Attributes¶

hvBatteryPreconditioningTime — Duration (minutes) for HV battery preconditioning.
hvBatteryChargingEnergy — Required energy (kWh) for HV battery (includes pre-heating/cooling energy).
vehiclePreconditioningTime — Duration (minutes) for vehicle preconditioning.
vehiclePreconditioningEnergy — Energy (kWh) needed for vehicle preconditioning.

ChargingProcessInfo¶

Represents information about a charging process.

Attributes¶

chargingProcessId — CMS-assigned unique identifier; constant for process lifetime.
presystemId — Optional; identifies upstream system controlling this process.
chargingRequestId — Upstream-assigned request reference; empty for unplanned charging.
processStatus — Status per ProcessStatus. Required.
startTime — Start timestamp of the process.
chargingPredictionData — Substructure for charging predictions (see 12). Required.
electricData — Substructure for electrical data (see 16). Required.
deliveredEnergy — Energy delivered in this process (Wh); informational only.

ChargingPredictionData¶

Collects forecasts for an ongoing charging process.

Attributes¶

chargingPredictionDataMinSoc — See 1
chargingPredictionDataFinalSoc — See 14.
chargingPredictionDataDepartureTime — See 15.

ChargingPredictionDataMinSoc¶

Forecast for reaching the minimum SoC target.

Attributes¶

requestedMinSoc — Target minimum SoC (%).
predictedTime — Predicted time when the minimum SoC will be reached.

ChargingPredictionDataFinalSoc¶

Forecast for the final SoC target.

Attributes¶

predictedFinalSoc — Forecast SoC (%) expected at target time.
predictedTime — Forecast time when predictedFinalSoc is achieved.

Optional — may represent intermediate or max SoC. Omit if identical to ChargingPredictionDataMinSoc.

ChargingPredictionDataDepartureTime¶

Forecast for the state of charge at a fixed departure time.

Attributes¶

predictedDepartureTimeSoc — Forecast SoC (%) at the specified departure time.
predictedTime — Departure timestamp used for the prediction.

ElectricData¶

Electrical parameters of the ongoing charging process.

Attributes¶

chargingCurrent — Current charging current (A).
chargingVoltage — Charging voltage (V).
chargingPower — Active power (kW).
reactivePower — Reactive power (kvar).

Negative values possible (regeneration).

ScheduledChargingProcess¶

Represents a planned charging process not yet started.

Attributes¶

presystemId — Upstream system identifier.
chargingRequestId — Upstream request reference.
chargingProcessId — CMS-assigned process ID.
vehicleId — Vehicle identifier.
startTime — Planned charging start.
chargingPredictionData — See 12.

ChargingStationFaultInfo¶

Represents fault data at the charging station level.

Attributes¶

chargingStationFaultCode — Error code (see ChargingStationFaultCode).
faultText — Textual description of the fault.
faultTimeStamp — Date/time of fault occurrence.