const moduleName = 'OCPP16IncomingRequestService'
+/**
+ * OCPP 1.6 Incoming Request Service - handles and processes all incoming requests
+ * from the Central System (CS) to the Charging Station (CP) using OCPP 1.6 protocol.
+ *
+ * This service class is responsible for:
+ * - **Request Reception**: Receiving and routing OCPP 1.6 incoming requests from Central System
+ * - **Payload Validation**: Validating incoming request payloads against OCPP 1.6 JSON schemas
+ * - **Request Processing**: Executing business logic for each OCPP 1.6 request type
+ * - **Response Generation**: Creating and sending appropriate responses back to Central System
+ * - **Error Handling**: Managing protocol-level and application-level errors
+ *
+ * Supported OCPP 1.6 Incoming Request Types:
+ * - **Configuration Management**: ChangeConfiguration, GetConfiguration, GetLocalListVersion
+ * - **Remote Operations**: RemoteStartTransaction, RemoteStopTransaction, UnlockConnector
+ * - **Firmware Management**: GetDiagnostics, UpdateFirmware, Reset
+ * - **Reservation Management**: ReserveNow, CancelReservation
+ * - **Charging Profiles**: SetChargingProfile, ClearChargingProfile, GetCompositeSchedule
+ * - **Monitoring**: GetLocalListVersion, TriggerMessage
+ *
+ * Architecture Pattern:
+ * This class extends OCPPIncomingRequestService and implements OCPP 1.6-specific
+ * request handling logic. It uses a handler mapping pattern where each request type
+ * is mapped to a specific handler method, providing clean separation of concerns.
+ *
+ * Validation Workflow:
+ * 1. Incoming request received and parsed
+ * 2. Payload validated against OCPP 1.6 JSON schema
+ * 3. Request routed to appropriate handler method
+ * 4. Business logic executed with charging station state management
+ * 5. Response payload validated and sent back to Central System
+ * @see {@link validatePayload} Request payload validation method
+ * @see {@link handleRequestRemoteStartTransaction} Example request handler
+ */
+
export class OCPP16IncomingRequestService extends OCPPIncomingRequestService {
protected payloadValidatorFunctions: Map<OCPP16IncomingRequestCommand, ValidateFunction<JsonType>>
])
this.payloadValidatorFunctions = OCPP16ServiceUtils.createPayloadValidatorMap(
OCPP16ServiceUtils.createIncomingRequestPayloadConfigs(),
- OCPP16ServiceUtils.createIncomingRequestFactoryOptions(moduleName, 'constructor'),
+ OCPP16ServiceUtils.createIncomingRequestPayloadOptions(moduleName, 'constructor'),
this.ajv
)
// Handle incoming request events
}
}
+ /**
+ * Handles OCPP 1.6 RemoteStartTransaction request from central system
+ * Initiates charging transaction on specified or available connector
+ * @param chargingStation - The charging station instance processing the request
+ * @param commandPayload - RemoteStartTransaction request payload with connector and ID tag
+ * @returns Promise resolving to GenericResponse indicating operation success or failure
+ */
private async handleRequestRemoteStartTransaction (
chargingStation: ChargingStation,
commandPayload: RemoteStartTransactionRequest
}
}
- // Simulate charging station restart
+ /**
+ * Handles incoming Reset request and initiates station reset
+ * @param chargingStation - The charging station instance processing the request
+ * @param commandPayload - Reset request payload containing reset type
+ * @returns OCPP response indicating acceptance of the reset request
+ */
private handleRequestReset (
chargingStation: ChargingStation,
commandPayload: ResetRequest
}
}
+ /**
+ * Validates incoming OCPP 1.6 request payload against JSON schema
+ * @param chargingStation - The charging station instance processing the request
+ * @param commandName - OCPP 1.6 command name to validate against
+ * @param commandPayload - JSON payload to validate
+ * @returns True if payload validation succeeds, false otherwise
+ */
private validatePayload (
chargingStation: ChargingStation,
commandName: OCPP16IncomingRequestCommand,
type JsonObject,
type JsonType,
OCPP16ChargePointStatus,
- type OCPP16MeterValue,
OCPP16RequestCommand,
type OCPP16StartTransactionRequest,
OCPPVersion,
case OCPP16RequestCommand.DIAGNOSTICS_STATUS_NOTIFICATION:
return commandParams as unknown as Request
case OCPP16RequestCommand.FIRMWARE_STATUS_NOTIFICATION:
- logger.debug(
- `${chargingStation.logPrefix()} ${moduleName}.buildRequestPayload: Building ${OCPP16RequestCommand.FIRMWARE_STATUS_NOTIFICATION} payload`
- )
return commandParams as unknown as Request
case OCPP16RequestCommand.HEARTBEAT:
return OCPP16Constants.OCPP_REQUEST_EMPTY as unknown as Request
...(chargingStation.stationInfo?.transactionDataMeterValues === true && {
transactionData: OCPP16ServiceUtils.buildTransactionDataMeterValues(
// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
- chargingStation.getConnectorStatus(connectorId!)!
- .transactionBeginMeterValue! as OCPP16MeterValue,
+ chargingStation.getConnectorStatus(connectorId!)!.transactionBeginMeterValue!,
OCPP16ServiceUtils.buildTransactionEndMeterValue(
chargingStation,
// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
connectorId!,
energyActiveImportRegister
- ) as OCPP16MeterValue
+ )
),
}),
...commandParams,
const moduleName = 'OCPP16ResponseService'
+/**
+ * OCPP 1.6 Response Service - handles and processes all outgoing request responses
+ * from the Charging Station (CP) to the Central System (CS) using OCPP 1.6 protocol.
+ *
+ * This service class is responsible for:
+ * - **Response Reception**: Receiving responses to requests sent from the Charging Station
+ * - **Payload Validation**: Validating response payloads against OCPP 1.6 JSON schemas
+ * - **Response Processing**: Processing Central System responses and updating station state
+ * - **Error Handling**: Managing response errors and protocol-level exceptions
+ * - **State Synchronization**: Ensuring charging station state reflects Central System responses
+ *
+ * Supported OCPP 1.6 Response Types:
+ * - **Authentication**: Authorize responses with authorization status updates
+ * - **Transaction Management**: StartTransaction, StopTransaction response handling
+ * - **Status Updates**: BootNotification, StatusNotification, MeterValues responses
+ * - **Configuration**: Responses to configuration queries and updates
+ * - **Heartbeat**: Heartbeat response processing for connection maintenance
+ * - **Data Transfer**: Custom data transfer response handling
+ *
+ * Architecture Pattern:
+ * This class extends OCPPResponseService and implements OCPP 1.6-specific response
+ * processing logic. It follows a handler mapping pattern where each response type
+ * is processed by dedicated handler methods that manage charging station state updates.
+ *
+ * Response Validation Workflow:
+ * 1. Response received from Central System for previously sent request
+ * 2. Response payload validated against OCPP 1.6 JSON schema
+ * 3. Response routed to appropriate handler based on original request type
+ * 4. Charging station state updated based on response content
+ * 5. Any follow-up actions triggered (transactions, status changes, etc.)
+ * @see {@link validatePayload} Response payload validation method
+ * @see {@link handleResponse} Response processing methods
+ */
+
export class OCPP16ResponseService extends OCPPResponseService {
public incomingRequestResponsePayloadValidateFunctions: Map<
OCPP16IncomingRequestCommand,
await OCPP16ServiceUtils.restoreConnectorStatus(chargingStation, connectorId, connectorStatus)
}
+ /**
+ * Validates incoming OCPP 1.6 response payload against JSON schema
+ * @param chargingStation - The charging station instance receiving the response
+ * @param commandName - OCPP 1.6 command name to validate against
+ * @param payload - JSON response payload to validate
+ * @returns True if payload validation succeeds, false otherwise
+ */
private validatePayload (
chargingStation: ChargingStation,
commandName: OCPP16RequestCommand,
}
}
- /**
- * Factory options for OCPP 1.6 Incoming Request Service
- * @param moduleName - Name of the OCPP module
- * @param methodName - Name of the method/command
- * @returns Factory options object for OCPP 1.6 incoming request validators
- */
- public static createIncomingRequestFactoryOptions = (moduleName: string, methodName: string) =>
- OCPP16ServiceUtils.PayloadValidatorOptions(
- OCPPVersion.VERSION_16,
- 'assets/json-schemas/ocpp/1.6',
- moduleName,
- methodName
- )
-
/**
* OCPP 1.6 Incoming Request Service validator configurations
* @returns Array of validator configuration tuples
],
]
+ /**
+ * Factory options for OCPP 1.6 Incoming Request Service
+ * @param moduleName - Name of the OCPP module
+ * @param methodName - Name of the method/command
+ * @returns Factory options object for OCPP 1.6 incoming request validators
+ */
+ public static createIncomingRequestPayloadOptions = (moduleName: string, methodName: string) =>
+ OCPP16ServiceUtils.PayloadValidatorOptions(
+ OCPPVersion.VERSION_16,
+ 'assets/json-schemas/ocpp/1.6',
+ moduleName,
+ methodName
+ )
+
/**
* Factory options for OCPP 1.6 Incoming Request Response Service
* @param moduleName - Name of the OCPP module
const moduleName = 'OCPP20IncomingRequestService'
+/**
+ * OCPP 2.0+ Incoming Request Service - handles and processes all incoming requests
+ * from the Central System (CSMS) to the Charging Station using OCPP 2.0+ protocol.
+ *
+ * This service class is responsible for:
+ * - **Request Reception**: Receiving and routing OCPP 2.0+ incoming requests from CSMS
+ * - **Payload Validation**: Validating incoming request payloads against OCPP 2.0+ JSON schemas
+ * - **Request Processing**: Executing business logic for each OCPP 2.0+ request type
+ * - **Response Generation**: Creating and sending appropriate responses back to CSMS
+ * - **Enhanced Features**: Supporting advanced OCPP 2.0+ features like variable management
+ *
+ * Supported OCPP 2.0+ Incoming Request Types:
+ * - **Transaction Management**: RequestStartTransaction, RequestStopTransaction
+ * - **Configuration Management**: SetVariables, GetVariables, GetBaseReport
+ * - **Security Operations**: CertificatesSigned, SecurityEventNotification
+ * - **Charging Management**: SetChargingProfile, ClearChargingProfile, GetChargingProfiles
+ * - **Diagnostics**: TriggerMessage, GetLog, UpdateFirmware
+ * - **Display Management**: SetDisplayMessage, ClearDisplayMessage
+ * - **Customer Management**: ClearCache, SendLocalList
+ *
+ * Key OCPP 2.0+ Enhancements:
+ * - **Variable Model**: Advanced configuration through standardized variable system
+ * - **Enhanced Security**: Improved authentication and authorization mechanisms
+ * - **Rich Messaging**: Support for display messages and customer information
+ * - **Advanced Monitoring**: Comprehensive logging and diagnostic capabilities
+ * - **Flexible Charging**: Enhanced charging profile management and scheduling
+ *
+ * Architecture Pattern:
+ * This class extends OCPPIncomingRequestService and implements OCPP 2.0+-specific
+ * request handling logic. It integrates with the OCPP20VariableManager for advanced
+ * configuration management and maintains backward compatibility concepts while
+ * providing next-generation OCPP features.
+ *
+ * Validation Workflow:
+ * 1. Incoming request received and parsed
+ * 2. Payload validated against OCPP 2.0+ JSON schema
+ * 3. Request routed to appropriate handler method
+ * 4. Business logic executed with variable model integration
+ * 5. Response payload validated and sent back to CSMS
+ * @see {@link validatePayload} Request payload validation method
+ * @see {@link handleRequestRequestStartTransaction} Example OCPP 2.0+ request handler
+ * @see {@link OCPP20VariableManager} Variable management integration
+ */
+
export class OCPP20IncomingRequestService extends OCPPIncomingRequestService {
protected payloadValidatorFunctions: Map<OCPP20IncomingRequestCommand, ValidateFunction<JsonType>>
])
this.payloadValidatorFunctions = OCPP20ServiceUtils.createPayloadValidatorMap(
OCPP20ServiceUtils.createIncomingRequestPayloadConfigs(),
- OCPP20ServiceUtils.createIncomingRequestFactoryOptions(moduleName, 'constructor'),
+ OCPP20ServiceUtils.createIncomingRequestPayloadOptions(moduleName, 'constructor'),
this.ajv
)
// Handle incoming request events
}
}
+ /**
+ * Handles OCPP 2.0 RequestStartTransaction request from central system
+ * Initiates charging transaction on specified EVSE with enhanced authorization
+ * @param chargingStation - The charging station instance processing the request
+ * @param commandPayload - RequestStartTransaction request payload with EVSE, ID token and profiles
+ * @returns Promise resolving to RequestStartTransactionResponse with status and transaction details
+ */
private async handleRequestRequestStartTransaction (
chargingStation: ChargingStation,
commandPayload: OCPP20RequestStartTransactionRequest
return true
}
+ /**
+ * Validates incoming OCPP 2.0 request payload against JSON schema
+ * @param chargingStation - The charging station instance processing the request
+ * @param commandName - OCPP 2.0 command name to validate against
+ * @param commandPayload - JSON payload to validate
+ * @returns True if payload validation succeeds, false otherwise
+ */
private validatePayload (
chargingStation: ChargingStation,
commandName: OCPP20IncomingRequestCommand,
const moduleName = 'OCPP20ResponseService'
+/**
+ * OCPP 2.0+ Response Service - handles and processes all outgoing request responses
+ * from the Charging Station to the Central System Management System (CSMS) using OCPP 2.0+ protocol.
+ *
+ * This service class is responsible for:
+ * - **Response Reception**: Receiving responses to requests sent from the Charging Station
+ * - **Payload Validation**: Validating response payloads against OCPP 2.0+ JSON schemas
+ * - **Response Processing**: Processing CSMS responses and updating station state
+ * - **Variable Management**: Handling variable-based configuration responses
+ * - **Enhanced State Management**: Managing OCPP 2.0+ advanced state and feature coordination
+ *
+ * Supported OCPP 2.0+ Response Types:
+ * - **Authentication**: Authorize responses with enhanced authorization mechanisms
+ * - **Transaction Management**: TransactionEvent responses for flexible transaction handling
+ * - **Status Updates**: BootNotification, StatusNotification, NotifyReport responses
+ * - **Variable Operations**: Responses to GetVariables, SetVariables operations
+ * - **Security**: Responses to security-related operations and certificate management
+ * - **Heartbeat**: Enhanced heartbeat response processing with additional metadata
+ *
+ * Key OCPP 2.0+ Features:
+ * - **Variable Model Integration**: Seamless integration with OCPP 2.0+ variable system
+ * - **Enhanced Transaction Model**: Support for flexible transaction event handling
+ * - **Security Framework**: Advanced security response processing and validation
+ * - **Rich Data Model**: Support for complex data structures and enhanced messaging
+ * - **Backward Compatibility**: Maintains compatibility concepts while extending functionality
+ *
+ * Architecture Pattern:
+ * This class extends OCPPResponseService and implements OCPP 2.0+-specific response
+ * processing logic. It works closely with OCPP20VariableManager and other OCPP 2.0+
+ * components to provide comprehensive protocol support with enhanced features.
+ *
+ * Response Validation Workflow:
+ * 1. Response received from CSMS for previously sent request
+ * 2. Response payload validated against OCPP 2.0+ JSON schema
+ * 3. Response routed to appropriate handler based on original request type
+ * 4. Charging station state and variable model updated based on response content
+ * 5. Enhanced follow-up actions triggered based on OCPP 2.0+ capabilities
+ * @see {@link validatePayload} Response payload validation method
+ * @see {@link handleResponse} Response processing methods
+ * @see {@link OCPP20VariableManager} Variable management integration
+ */
+
export class OCPP20ResponseService extends OCPPResponseService {
public incomingRequestResponsePayloadValidateFunctions: Map<
OCPP20IncomingRequestCommand,
)
}
+ /**
+ * Validates incoming OCPP 2.0 response payload against JSON schema
+ * @param chargingStation - The charging station instance receiving the response
+ * @param commandName - OCPP 2.0 command name to validate against
+ * @param payload - JSON response payload to validate
+ * @returns True if payload validation succeeds, false otherwise
+ */
private validatePayload (
chargingStation: ChargingStation,
commandName: OCPP20RequestCommand,
import { OCPP20Constants } from './OCPP20Constants.js'
export class OCPP20ServiceUtils extends OCPPServiceUtils {
- /**
- * Factory options for OCPP 2.0 Incoming Request Service
- * @param moduleName - Name of the OCPP module
- * @param methodName - Name of the method/command
- * @returns Factory options object for OCPP 2.0 incoming request validators
- */
- public static createIncomingRequestFactoryOptions = (moduleName: string, methodName: string) =>
- OCPP20ServiceUtils.PayloadValidatorOptions(
- OCPPVersion.VERSION_201,
- 'assets/json-schemas/ocpp/2.0',
- moduleName,
- methodName
- )
-
/**
* OCPP 2.0 Incoming Request Service validator configurations
* @returns Array of validator configuration tuples
],
]
+ /**
+ * Factory options for OCPP 2.0 Incoming Request Service
+ * @param moduleName - Name of the OCPP module
+ * @param methodName - Name of the method/command
+ * @returns Factory options object for OCPP 2.0 incoming request validators
+ */
+ public static createIncomingRequestPayloadOptions = (moduleName: string, methodName: string) =>
+ OCPP20ServiceUtils.PayloadValidatorOptions(
+ OCPPVersion.VERSION_201,
+ 'assets/json-schemas/ocpp/2.0',
+ moduleName,
+ methodName
+ )
+
/**
* Factory options for OCPP 2.0 Incoming Request Response Service
* @param moduleName - Name of the OCPP module
return OCPPConstants.OCPP_RESPONSE_REJECTED
}
+ /**
+ * Validates incoming request payload against JSON schema
+ * @param chargingStation - The charging station instance processing the request
+ * @param commandName - OCPP command name to validate against
+ * @param payload - JSON payload to validate
+ * @returns True if payload validation succeeds, false otherwise
+ */
// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
protected validateIncomingRequestPayload<T extends JsonType>(
chargingStation: ChargingStation,
)
}
+ /**
+ * Validates outgoing request payload against JSON schema
+ * @param chargingStation - The charging station instance sending the request
+ * @param commandName - OCPP command name to validate against
+ * @param payload - JSON payload to validate
+ * @returns True if payload validation succeeds, false otherwise
+ */
// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
private validateRequestPayload<T extends JsonType>(
chargingStation: ChargingStation,
}
if (!this.payloadValidatorFunctions.has(commandName as RequestCommand)) {
logger.warn(
- `${chargingStation.logPrefix()} ${moduleName}.validateRequestPayload: No JSON schema found for command '${commandName}' PDU validation`
+ `${chargingStation.logPrefix()} ${moduleName}.validateRequestPayload: No JSON schema validation function found for command '${commandName}' PDU validation`
)
return true
}
requestPayload: ReqType
): Promise<void>
+ /**
+ * Validates incoming response payload against JSON schema
+ * @param chargingStation - The charging station instance receiving the response
+ * @param commandName - OCPP command name to validate against
+ * @param payload - JSON response payload to validate
+ * @returns True if payload validation succeeds, false otherwise
+ */
// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
protected validateResponsePayload<T extends JsonType>(
chargingStation: ChargingStation,
}
}
+/**
+ * Utility class providing core OCPP (Open Charge Point Protocol) service functionality
+ * and common operations across all OCPP versions and protocol implementations.
+ *
+ * This class serves as the foundation for OCPP protocol handling, providing:
+ * - JSON schema-based payload validation using AJV (Another JSON Schema Validator)
+ * - Common OCPP operations like connector status management and transaction handling
+ * - Utility functions for meter value processing and ID tag authorization
+ * - Shared functionality between OCPP 1.6 and OCPP 2.0+ implementations
+ *
+ * Key Features:
+ * - **Schema Validation**: Centralized JSON schema loading and validation functions
+ * - **Protocol Agnostic**: Provides utilities that work across OCPP versions
+ * - **Transaction Management**: Utilities for transaction lifecycle and meter values
+ * - **Status Management**: Connector and charging station status operations
+ * - **Static Interface**: All functionality exposed as static methods for easy access
+ *
+ * Usage Pattern:
+ * This class is typically used by other OCPP service classes (incoming request services,
+ * response services) to perform common operations and validation. It acts as a shared
+ * utility layer that prevents code duplication across OCPP version-specific implementations.
+ * @see {@link parseJsonSchemaFile} Core JSON schema parsing functionality
+ * @see {@link validatePayload} Payload validation methods in service classes
+ */
+
// eslint-disable-next-line @typescript-eslint/no-extraneous-class
export class OCPPServiceUtils {
public static readonly buildTransactionEndMeterValue = buildTransactionEndMeterValue
schemaDir,
}) as const
+ /**
+ * Parses and loads a JSON schema file for OCPP payload validation
+ * Handles file reading, JSON parsing, and error recovery for schema validation
+ * @param relativePath - Path to the schema file relative to the OCPP utils directory
+ * @param ocppVersion - The OCPP version for error logging context
+ * @param moduleName - Optional module name for error logging
+ * @param methodName - Optional method name for error logging
+ * @returns Parsed JSON schema object or empty object if parsing fails
+ */
protected static parseJsonSchemaFile<T extends JsonType>(
relativePath: string,
ocppVersion: OCPPVersion,
repositories / e-mobility-charging-stations-simulator.git / commitdiff
