OCPP Module Specification for EV Charging Stations
1. System Overview
1.1 General Architecture
graph TB
subgraph "Backend Infrastructure"
CSMS[Central System Management Service]
end
subgraph "EV Charging Station"
subgraph "Your Responsibility"
OCPP[OCPP Communication Module]
WS[WebSocket Client]
PARSER[Message Parser/Generator]
QUEUE[Message Queue]
end
subgraph "Station System (Existing)"
STATION[Station Controller]
HARDWARE[Hardware Controllers]
end
end
CSMS <--> WS
WS <--> OCPP
OCPP <--> PARSER
OCPP <--> QUEUE
OCPP <--> STATION
STATION <--> HARDWARE
1.2 Module Purpose
Primary Function: Provide bidirectional communication between mobile charging station and CSMS using OCPP 2.0.1 protocol
Usage Context: Mobile charging stations that technicians bring to customers or to base for recharging. Charging control via station control panel or CSMS mobile application.
Interfaces:
- External: WebSocket connection with CSMS
- Internal: API for integration with station system
1.3 OCPP Module Methods Table
Methods for Implementation on Station Side
| Method | Description | When Called |
|---|---|---|
initialize(config) |
Initialize module with configuration | During system startup |
connect() |
Establish connection to CSMS | After initialization |
disconnect() |
Terminate connection to CSMS | During shutdown/maintenance |
sendStationEvent(event) |
Send station event | When station state changes |
sendMeterData(data) |
Send meter readings | Every 10 seconds during charging |
sendStatusUpdate(status) |
Send status update | When station state changes |
handleStartCharging(params) |
Handle start charging command | On command from CSMS |
handleStopCharging(transactionId) |
Handle stop charging command | On command from CSMS |
handleDataRequest(requestType) |
Handle data request | On command from CSMS |
getStationStatus() |
Get current station status | On request from CSMS |
getBatteryData() |
Get station battery data | On request from CSMS |
getLocationData() |
Get station GPS coordinates | On request from CSMS |
Methods for Implementation on CSMS Side
| Method | Description | When Called |
|---|---|---|
handleBootNotification(stationData) |
Handle station startup notification | When station connects |
handleStatusNotification(status) |
Handle status notification | When station status changes |
handleTransactionEvent(event) |
Handle transaction events | When charging starts/ends |
handleMeterValues(values) |
Handle meter readings | Every 10 seconds during charging |
handleNotifyEvent(event) |
Handle error notifications | When errors occur |
sendRemoteStart(stationId, params) |
Send remote start command | On user request |
sendRemoteStop(transactionId) |
Send remote stop command | On user request |
requestStationData(stationId, dataType) |
Request station data | On user request |
updateStationConfig(stationId, config) |
Update station configuration | When settings change |
2. Mobile Charging Station States
2.1 Primary Station States
stateDiagram-v2
[*] --> Standby
Standby --> CustomerCharging: Technician starts customer charging
Standby --> StationCharging: Technician starts station charging
CustomerCharging --> Standby: Customer charging completed
StationCharging --> Standby: Station charging completed
note right of Standby
Station powered on
No charging in progress
Ready for operation
end note
note right of CustomerCharging
Customer vehicle charging
Data every 10 seconds
end note
note right of StationCharging
Station self-charging
Data every 10 seconds
end note
2.2 Data by State
2.2.1 "Standby" State (Station powered on, no charging in progress)
Data to send to CSMS:
{
"stationStatus": "Available",
"batteryLevel": 75,
"batteryVoltage": 48.2,
"batteryTemperature": 25.5,
"location": {
"latitude": 55.7558,
"longitude": 37.6176,
"accuracy": 10
},
"signalStrength": -65,
"internalTemperature": 22.0,
"outputVoltage": 0.0,
"outputCurrent": 0.0,
"outputPower": 0.0,
"connectorStatus": "Available",
"errorCodes": [],
"lastMaintenanceDate": "2025-07-10T09:00:00Z"
}
Send Frequency: On state change + on request from CSMS
2.2.2 "CustomerCharging" State (Customer vehicle charging in progress)
Data to send to CSMS every 10 seconds:
{
"stationStatus": "Charging",
"transactionId": "TXN_123456",
"transactionType": "customer_charging",
"chargingStartTime": "2025-07-12T10:30:00Z",
"chargingDuration": 1800,
"energyDelivered": 5.2,
"currentPower": 7200,
"outputVoltage": 230.5,
"outputCurrent": 31.2,
"vehicleBatteryLevel": 65,
"estimatedTimeToComplete": 2400,
"batteryLevel": 68,
"batteryVoltage": 47.8,
"batteryTemperature": 28.0,
"location": {
"latitude": 55.7558,
"longitude": 37.6176,
"accuracy": 10
},
"signalStrength": -68,
"internalTemperature": 32.0,
"connectorStatus": "Occupied",
"connectorTemperature": 35.0,
"errorCodes": [],
"chargingEfficiency": 92.5
}
Send Frequency: Every 10 seconds during charging
2.2.3 "StationCharging" State (Station self-charging in progress)
Data to send to CSMS every 10 seconds:
{
"stationStatus": "SelfCharging",
"transactionId": "TXN_SELF_789",
"transactionType": "station_charging",
"chargingStartTime": "2025-07-12T14:00:00Z",
"chargingDuration": 3600,
"energyReceived": 15.8,
"inputPower": 5000,
"inputVoltage": 220.0,
"inputCurrent": 22.7,
"batteryLevel": 85,
"batteryVoltage": 49.2,
"batteryTemperature": 30.0,
"estimatedTimeToComplete": 1800,
"location": {
"latitude": 55.7520,
"longitude": 37.6140,
"accuracy": 5
},
"signalStrength": -72,
"internalTemperature": 28.0,
"connectorStatus": "SelfCharging",
"chargingSource": "grid",
"errorCodes": [],
"chargingEfficiency": 94.2
}
Send Frequency: Every 10 seconds during charging
3. OCPP Module Interface
3.1 Integration API with Station System
flowchart LR
subgraph "Station System"
CONTROLLER[Station Controller]
end
subgraph "OCPP Module API"
direction TB
IN[Incoming Events]
OUT[Outgoing Commands]
STATUS[Status Queries]
CONFIG[Configuration]
end
subgraph "CSMS"
BACKEND[Backend Server]
end
CONTROLLER -->|Events| IN
OUT -->|Commands| CONTROLLER
CONTROLLER -->|Query| STATUS
CONTROLLER -->|Setup| CONFIG
IN -.->|OCPP Messages| BACKEND
BACKEND -.->|OCPP Messages| OUT
3.2 Incoming Events from Station
{
"eventType": "station_event",
"events": [
{
"type": "cable_connected",
"targetType": "customer|station",
"evseId": 1,
"connectorId": 1,
"timestamp": "2025-07-12T10:30:00Z"
},
{
"type": "charging_started",
"chargingType": "customer_charging|station_charging",
"transactionId": "TXN_123",
"evseId": 1,
"connectorId": 1,
"initiatedBy": "technician|remote",
"timestamp": "2025-07-12T10:30:00Z"
},
{
"type": "meter_reading",
"chargingType": "customer_charging|station_charging",
"evseId": 1,
"readings": {
"energy": 5.2,
"power": 7200,
"voltage": 230.5,
"current": 31.2,
"batteryLevel": 68,
"batteryTemperature": 28.0,
"vehicleBatteryLevel": 65,
"estimatedTimeToComplete": 2400
},
"timestamp": "2025-07-12T10:31:00Z"
},
{
"type": "charging_stopped",
"chargingType": "customer_charging|station_charging",
"transactionId": "TXN_123",
"reason": "technician_stopped|remote_stopped|completed|error",
"finalEnergy": 8.5,
"duration": 900,
"timestamp": "2025-07-12T10:45:00Z"
},
{
"type": "error_detected",
"errorCode": "connector_lock_failure|overheat|power_loss|communication_error",
"severity": "warning|alert|critical",
"component": "charging_connector|battery|power_system|communication",
"chargingType": "customer_charging|station_charging|none",
"timestamp": "2025-07-12T10:35:00Z"
},
{
"type": "status_changed",
"evseId": 1,
"connectorId": 1,
"newStatus": "available|preparing|charging|self_charging|faulted|unavailable",
"previousStatus": "available",
"reason": "technician_action|remote_command|auto_transition|error",
"timestamp": "2025-07-12T10:30:00Z"
},
{
"type": "location_changed",
"location": {
"latitude": 55.7558,
"longitude": 37.6176,
"accuracy": 10,
"address": "Moscow, Tverskaya St., 1"
},
"movementDetected": true,
"timestamp": "2025-07-12T10:30:00Z"
}
]
}
3.3 Outgoing Commands to Station
{
"commandType": "csms_command",
"commands": [
{
"type": "start_customer_charging",
"evseId": 1,
"chargingProfile": {
"maxPower": 7200,
"phases": 1,
"duration": 3600
},
"estimatedCost": 500.0,
"customerInfo": {
"customerId": "CUST_001",
"vehicleType": "Tesla Model 3"
}
},
{
"type": "start_station_charging",
"chargingSource": "grid|solar",
"maxInputPower": 5000,
"targetBatteryLevel": 100,
"chargingLocation": "base|customer_site"
},
{
"type": "stop_charging",
"transactionId": "TXN_123",
"chargingType": "customer_charging|station_charging",
"reason": "remote_stop|emergency_stop|maintenance"
},
{
"type": "request_data",
"dataType": "battery_status|location|diagnostics|transaction_history",
"requestId": "REQ_001",
"timeRange": {
"from": "2025-07-12T00:00:00Z",
"to": "2025-07-12T23:59:59Z"
}
},
{
"type": "update_configuration",
"parameters": {
"heartbeatInterval": 300,
"meterValueSampleInterval": 10,
"maxChargingPower": 7200,
"emergencyContactNumber": "+7-495-123-4567"
}
},
{
"type": "set_location",
"location": {
"latitude": 55.7558,
"longitude": 37.6176,
"address": "Moscow, Tverskaya St., 1",
"locationType": "customer_site|base|service_center"
}
},
{
"type": "technician_notification",
"message": "Customer charging completed. Cable can be disconnected.",
"priority": "low|normal|high|urgent",
"requiresAcknowledgment": true
},
{
"type": "reset_station",
"resetType": "soft|hard",
"reason": "maintenance|error_recovery|firmware_update"
}
]
}
4. OCPP Communication Flow
4.1 Connection Establishment
sequenceDiagram
participant Station as Station System
participant OCPP as OCPP Module
participant CSMS as CSMS Server
Station->>OCPP: Initialize Connection
Note over OCPP: Config: server URL, API key, station ID
OCPP->>CSMS: WebSocket Connect
Note over OCPP,CSMS: wss://csms.server.com/ocpp/{stationId}<br/>Authorization: Bearer {apiKey}
CSMS->>OCPP: Connection Accepted
OCPP->>CSMS: BootNotification
Note over OCPP: Station info, firmware version
CSMS->>OCPP: BootNotification Response
Note over CSMS: Status: Accepted, Heartbeat interval
OCPP->>Station: Connection Established
loop Heartbeat
OCPP->>CSMS: Heartbeat (every interval)
CSMS->>OCPP: Heartbeat Response
end
4.2 Event Processing by Station State
4.2.1 "Standby" State (Station ready for operation)
sequenceDiagram
participant Technician as Technician
participant Station as Station System
participant OCPP as OCPP Module
participant CSMS as CSMS Server
Note over Technician,CSMS: Station powered on, awaiting commands
Station->>OCPP: status_changed event (Available)
OCPP->>CSMS: StatusNotification (Available)
CSMS->>OCPP: StatusNotification Response
Note over Technician,CSMS: Technician connects cable to customer vehicle
Technician->>Station: Cable connected to customer vehicle
Station->>OCPP: cable_connected event (customer)
OCPP->>CSMS: StatusNotification (Preparing)
CSMS->>OCPP: StatusNotification Response
Note over Technician,CSMS: Technician starts charging via control panel
Technician->>Station: Start customer charging
Station->>OCPP: charging_started event (customer)
OCPP->>CSMS: TransactionEvent (Started, customer_charging)
CSMS->>OCPP: TransactionEvent Response
Note over Technician,CSMS: Alternative: start via CSMS
CSMS->>OCPP: RemoteStartTransaction
OCPP->>Station: start_charging command
Station->>OCPP: Command accepted
OCPP->>CSMS: RemoteStartTransaction Response (Accepted)
4.2.2 "CustomerCharging" State (Customer charging)
sequenceDiagram
participant Station as Station System
participant OCPP as OCPP Module
participant CSMS as CSMS Server
Note over Station,CSMS: Customer charging active
loop Every 10 seconds
Station->>OCPP: meter_reading event (customer data)
OCPP->>CSMS: MeterValues (customer charging data)
Note over OCPP: Includes: energyDelivered, currentPower,<br/>outputVoltage, vehicleBatteryLevel,<br/>station batteryLevel, location
CSMS->>OCPP: MeterValues Response
end
Note over Station,CSMS: Event processing during charging
alt Charging error
Station->>OCPP: error_detected event
OCPP->>CSMS: NotifyEvent (Charging error)
OCPP->>CSMS: StatusNotification (SuspendedEVSE)
else Charging completed by technician
Station->>OCPP: charging_stopped event (user_stopped)
OCPP->>CSMS: TransactionEvent (Ended)
OCPP->>CSMS: StatusNotification (Available)
else Remote stop
CSMS->>OCPP: RemoteStopTransaction
OCPP->>Station: stop_charging command
Station->>OCPP: charging_stopped event (remote_stopped)
OCPP->>CSMS: TransactionEvent (Ended)
end
4.2.3 "StationCharging" State (Station charging)
sequenceDiagram
participant Technician as Technician
participant Station as Station System
participant OCPP as OCPP Module
participant CSMS as CSMS Server
Note over Technician,CSMS: Technician connects station to power source
Technician->>Station: Connect to charging source
Station->>OCPP: station_charging_started event
OCPP->>CSMS: TransactionEvent (Started, station_charging)
CSMS->>OCPP: TransactionEvent Response
OCPP->>CSMS: StatusNotification (SelfCharging)
Note over Station,CSMS: Station charging process
loop Every 10 seconds
Station->>OCPP: meter_reading event (station data)
OCPP->>CSMS: MeterValues (station charging data)
Note over OCPP: Includes: energyReceived, inputPower,<br/>batteryLevel, batteryTemperature,<br/>estimatedTimeToComplete, location
CSMS->>OCPP: MeterValues Response
end
Note over Station,CSMS: Station charging completion
alt Battery fully charged
Station->>OCPP: station_charging_complete event
OCPP->>CSMS: TransactionEvent (Ended, BatteryFull)
OCPP->>CSMS: StatusNotification (Available)
else Technician stopped charging
Technician->>Station: Stop station charging
Station->>OCPP: station_charging_stopped event
OCPP->>CSMS: TransactionEvent (Ended, UserStopped)
OCPP->>CSMS: StatusNotification (Available)
else Charging error
Station->>OCPP: error_detected event (charging_fault)
OCPP->>CSMS: NotifyEvent (Station charging error)
OCPP->>CSMS: StatusNotification (Faulted)
end
4.3 CSMS Command Processing
sequenceDiagram
participant CSMS as CSMS Server
participant OCPP as OCPP Module
participant Station as Station System
participant Technician as Technician
Note over CSMS,Technician: Remote customer charging start
CSMS->>OCPP: RemoteStartTransaction (customer_charging)
OCPP->>Station: start_customer_charging command
Station->>OCPP: Command accepted
OCPP->>CSMS: RemoteStartTransaction Response (Accepted)
Station->>Technician: Notification: "Start customer charging"
Note over CSMS,Technician: Station data request
CSMS->>OCPP: GetReport (Battery + Location)
OCPP->>Station: request_data command
Station->>OCPP: Data response (battery 75%, GPS coordinates)
OCPP->>CSMS: GetReport Response
OCPP->>CSMS: NotifyReport (Station data)
Note over CSMS,Technician: Remote charging stop
CSMS->>OCPP: RemoteStopTransaction
OCPP->>Station: stop_charging command
Station->>Technician: Notification: "Charging stopped by dispatcher"
Station->>OCPP: Command accepted
OCPP->>CSMS: RemoteStopTransaction Response (Accepted)
5. Detailed OCPP Message Specification
5.1 Outgoing Messages (Station → CSMS)
BootNotification (at startup)
{
"reason": "PowerUp",
"chargingStation": {
"model": "get_from_station_system",
"vendorName": "get_from_station_system",
"firmwareVersion": "get_from_station_system",
"serialNumber": "get_from_station_system"
}
}
StatusNotification (on status change)
{
"timestamp": "get_from_station_system",
"connectorStatus": "Available|Preparing|Charging|SuspendedEVSE|SuspendedEV|Finishing|Reserved|Unavailable|Faulted",
"evseId": "get_from_station_system",
"connectorId": "get_from_station_system"
}
TransactionEvent (transaction events)
{
"eventType": "Started|Updated|Ended",
"timestamp": "get_from_station_system",
"triggerReason": "ChargingStateChanged|ChargingRateChanged|EnergyLimitReached|TimeLimitReached|RemoteStop|RemoteStart|TechnicianStart|TechnicianStop|StationChargingStart|StationChargingComplete",
"seqNo": "incremental_number",
"transactionInfo": {
"transactionId": "get_from_station_system",
"chargingState": "Charging|EVConnected|SuspendedEV|SuspendedEVSE|Idle",
"chargingType": "customer_charging|station_charging"
},
"evse": {
"id": "get_from_station_system",
"connectorId": "get_from_station_system"
},
"customData": {
"technicianId": "get_from_station_system",
"customerInfo": "get_from_station_system_if_customer_charging",
"chargingLocation": "get_from_station_system"
},
"meterValue": [
{
"timestamp": "get_from_station_system",
"sampledValue": [
{
"value": "get_from_station_system",
"measurand": "Energy.Active.Import.Register|Power.Active.Import|Voltage|Current.Import|Temperature",
"unit": "kWh|kW|V|A|Celsius"
}
]
}
]
}
MeterValues (telemetry every 10 seconds during charging)
{
"evseId": "get_from_station_system",
"meterValue": [
{
"timestamp": "get_from_station_system",
"sampledValue": [
{
"value": "get_from_station_system",
"measurand": "Energy.Active.Import.Register|Power.Active.Import|Voltage|Current.Import|Temperature",
"unit": "kWh|kW|V|A|Celsius"
}
]
}
]
}
NotifyEvent (errors and events)
{
"generatedAt": "current_time",
"eventData": [
{
"eventId": "unique_id",
"timestamp": "get_from_station_system",
"trigger": "Alerting|Delta|Periodic",
"eventType": "get_from_station_system",
"component": {
"name": "get_from_station_system"
},
"variable": {
"name": "get_from_station_system"
},
"eventNotificationType": "HardWiredNotification|HardWiredMonitor|PreconfiguredMonitor|CustomMonitor"
}
]
}
5.2 Incoming Messages (CSMS → Station)
RemoteStartTransaction
Received from CSMS:
{
"evseId": 1,
"chargingType": "customer_charging|station_charging",
"chargingProfile": {
"id": 1,
"stackLevel": 0,
"chargingProfilePurpose": "TxProfile",
"chargingProfileKind": "Absolute",
"chargingSchedule": [
{
"id": 1,
"startSchedule": "2025-07-12T10:30:00Z",
"duration": 3600,
"chargingRateUnit": "W",
"chargingSchedulePeriod": [
{
"startPeriod": 0,
"limit": 7200
}
]
}
]
},
"customData": {
"customerInfo": {
"customerId": "CUST_001",
"vehicleType": "Tesla Model 3"
},
"technicianId": "TECH_005",
"estimatedDuration": 3600
}
}
Send to station_system:
{
"type": "start_customer_charging",
"evseId": 1,
"maxPower": 7200,
"duration": 3600,
"customerInfo": {
"customerId": "CUST_001",
"vehicleType": "Tesla Model 3"
},
"technicianId": "TECH_005"
}
Response to CSMS:
{
"status": "Accepted|Rejected",
"statusInfo": {
"reasonCode": "NoError|Busy|Occupied|Faulted"
}
}
RemoteStopTransaction
Received from CSMS:
{
"transactionId": "TXN_123456"
}
Send to station_system:
{
"type": "stop_charging",
"transactionId": "TXN_123456",
"reason": "remote_stop"
}
GetReport
Received from CSMS:
{
"requestId": 1,
"componentVariable": [
{
"component": {"name": "BatteryManagement"},
"variable": {"name": "StateOfCharge"}
}
]
}
Send to station_system:
{
"type": "request_data",
"requestId": 1,
"dataType": "battery_status"
}
Receive from station_system:
{
"requestId": 1,
"batteryLevel": 85,
"batteryVoltage": 48.2,
"batteryTemperature": 25.5
}
Send to CSMS (NotifyReport):
{
"requestId": 1,
"generatedAt": "current_time",
"reportData": [
{
"component": {"name": "BatteryManagement"},
"variable": {"name": "StateOfCharge"},
"variableAttribute": {
"value": "85",
"unit": "Percent"
}
}
]
}
6. Error Handling and Reconnection
6.1 Reconnection Strategy
flowchart TD
DISCONNECT[Connection Lost] --> LOG[Log Disconnect Event]
LOG --> QUEUE[Queue Outgoing Messages]
QUEUE --> WAIT[Wait Period]
WAIT --> RETRY[Attempt Reconnection]
RETRY --> SUCCESS{Connected?}
SUCCESS -->|Yes| BOOT[Send BootNotification]
SUCCESS -->|No| BACKOFF[Increase Wait Period]
BACKOFF --> MAXWAIT{Max Wait Reached?}
MAXWAIT -->|No| WAIT
MAXWAIT -->|Yes| RESET[Reset Wait Period]
RESET --> WAIT
BOOT --> SYNC[Send Queued Messages]
SYNC --> OPERATIONAL[Operational Mode]
6.2 Timeout Handling
sequenceDiagram
participant OCPP as OCPP Module
participant CSMS as CSMS Server
participant Station as Station System
OCPP->>CSMS: Request Message
Note over OCPP: Start 30s timeout timer
alt Response received
CSMS->>OCPP: Response Message
Note over OCPP: Clear timeout, process response
else Timeout occurred
Note over OCPP: 30s elapsed, no response
OCPP->>Station: Notify timeout error
OCPP->>OCPP: Queue message for retry
end
7. Module Configuration
7.1 Connection Parameters
{
"connection": {
"serverUrl": "wss://csms.example.com/ocpp",
"stationId": "STATION_001",
"apiKey": "your-api-key-here",
"reconnectInterval": 30,
"maxReconnectInterval": 300,
"messageTimeout": 30,
"heartbeatInterval": 300
},
"station": {
"model": "EV-CHARGER-V1",
"vendorName": "YourCompany",
"serialNumber": "SN123456789",
"firmwareVersion": "1.0.0"
},
"intervals": {
"meterValueSampleInterval": 10,
"clockAlignedDataInterval": 900,
"connectionTimeOut": 60
}
}
7.2 Management Methods
// Pseudo-code for module API
class OCPPModule {
// Initialization
initialize(config) { }
// Connection management
connect() { }
disconnect() { }
isConnected() { }
// Send events from station
sendStationEvent(event) { }
// Receive commands for station (callback)
onStationCommand(callback) { }
// Module status
getStatus() { }
getLastError() { }
// Logging
enableLogging(level) { }
}
8. Communication Protocol with Station System
8.1 Module Initialization
sequenceDiagram
participant Station as Station System
participant OCPP as OCPP Module
Station->>OCPP: Initialize(config)
OCPP->>OCPP: Load configuration
OCPP->>Station: Initialization complete
Station->>OCPP: SetEventHandler(callback)
OCPP->>Station: Handler registered
Station->>OCPP: Connect()
OCPP->>OCPP: Establish WebSocket connection
OCPP->>Station: onStationCommand("connection_established")
8.2 Runtime Event Processing
sequenceDiagram
participant Station as Station System
participant OCPP as OCPP Module
participant CSMS as CSMS Server
Note over Station,CSMS: Normal event flow
Station->>OCPP: sendStationEvent(cable_connected)
OCPP->>CSMS: StatusNotification
CSMS->>OCPP: StatusNotification Response
Note over Station,CSMS: Command from CSMS
CSMS->>OCPP: RemoteStartTransaction
OCPP->>Station: onStationCommand(start_charging)
Station->>OCPP: Command response (accepted)
OCPP->>CSMS: RemoteStartTransaction Response
This specification defines requirements for OCPP communication module for integration with charging station system.
No comments to display
No comments to display