src/charging-station/ocpp/OCPPServiceUtils.ts

   1 import fs from 'node:fs';
   2
   3 import type { DefinedError, ErrorObject, JSONSchemaType } from 'ajv';
   4
   5 import { OCPP16Constants, OCPP20Constants } from './internal';
   6 import { type ChargingStation, ChargingStationConfigurationUtils } from '../../charging-station';
   7 import { BaseError } from '../../exception';
   8 import {
   9   ChargePointErrorCode,
  10   type ConnectorStatusEnum,
  11   ErrorType,
  12   FileType,
  13   IncomingRequestCommand,
  14   type JsonObject,
  15   type JsonType,
  16   MessageTrigger,
  17   MessageType,
  18   MeterValueMeasurand,
  19   type MeterValuePhase,
  20   type OCPP16StatusNotificationRequest,
  21   type OCPP20StatusNotificationRequest,
  22   OCPPVersion,
  23   RequestCommand,
  24   type SampledValueTemplate,
  25   StandardParametersKey,
  26   type StatusNotificationRequest,
  27   type StatusNotificationResponse,
  28 } from '../../types';
  29 import { Constants, FileUtils, Utils, logger } from '../../utils';
  30
  31 export class OCPPServiceUtils {
  32   protected constructor() {
  33     // This is intentional
  34   }
  35
  36   public static ajvErrorsToErrorType(errors: ErrorObject[]): ErrorType {
  37     for (const error of errors as DefinedError[]) {
  38       switch (error.keyword) {
  39         case 'type':
  40           return ErrorType.TYPE_CONSTRAINT_VIOLATION;
  41         case 'dependencies':
  42         case 'required':
  43           return ErrorType.OCCURRENCE_CONSTRAINT_VIOLATION;
  44         case 'pattern':
  45         case 'format':
  46           return ErrorType.PROPERTY_CONSTRAINT_VIOLATION;
  47       }
  48     }
  49     return ErrorType.FORMAT_VIOLATION;
  50   }
  51
  52   public static getMessageTypeString(messageType: MessageType): string {
  53     switch (messageType) {
  54       case MessageType.CALL_MESSAGE:
  55         return 'request';
  56       case MessageType.CALL_RESULT_MESSAGE:
  57         return 'response';
  58       case MessageType.CALL_ERROR_MESSAGE:
  59         return 'error';
  60       default:
  61         return 'unknown';
  62     }
  63   }
  64
  65   public static isRequestCommandSupported(
  66     chargingStation: ChargingStation,
  67     command: RequestCommand
  68   ): boolean {
  69     const isRequestCommand = Object.values<RequestCommand>(RequestCommand).includes(command);
  70     if (
  71       isRequestCommand === true &&
  72       !chargingStation.stationInfo?.commandsSupport?.outgoingCommands
  73     ) {
  74       return true;
  75     } else if (
  76       isRequestCommand === true &&
  77       chargingStation.stationInfo?.commandsSupport?.outgoingCommands
  78     ) {
  79       return chargingStation.stationInfo?.commandsSupport?.outgoingCommands[command] ?? false;
  80     }
  81     logger.error(`${chargingStation.logPrefix()} Unknown outgoing OCPP command '${command}'`);
  82     return false;
  83   }
  84
  85   public static isIncomingRequestCommandSupported(
  86     chargingStation: ChargingStation,
  87     command: IncomingRequestCommand
  88   ): boolean {
  89     const isIncomingRequestCommand =
  90       Object.values<IncomingRequestCommand>(IncomingRequestCommand).includes(command);
  91     if (
  92       isIncomingRequestCommand === true &&
  93       !chargingStation.stationInfo?.commandsSupport?.incomingCommands
  94     ) {
  95       return true;
  96     } else if (
  97       isIncomingRequestCommand === true &&
  98       chargingStation.stationInfo?.commandsSupport?.incomingCommands
  99     ) {
 100       return chargingStation.stationInfo?.commandsSupport?.incomingCommands[command] ?? false;
 101     }
 102     logger.error(`${chargingStation.logPrefix()} Unknown incoming OCPP command '${command}'`);
 103     return false;
 104   }
 105
 106   public static isMessageTriggerSupported(
 107     chargingStation: ChargingStation,
 108     messageTrigger: MessageTrigger
 109   ): boolean {
 110     const isMessageTrigger = Object.values(MessageTrigger).includes(messageTrigger);
 111     if (isMessageTrigger === true && !chargingStation.stationInfo?.messageTriggerSupport) {
 112       return true;
 113     } else if (isMessageTrigger === true && chargingStation.stationInfo?.messageTriggerSupport) {
 114       return chargingStation.stationInfo?.messageTriggerSupport[messageTrigger] ?? false;
 115     }
 116     logger.error(
 117       `${chargingStation.logPrefix()} Unknown incoming OCPP message trigger '${messageTrigger}'`
 118     );
 119     return false;
 120   }
 121
 122   public static isConnectorIdValid(
 123     chargingStation: ChargingStation,
 124     ocppCommand: IncomingRequestCommand,
 125     connectorId: number
 126   ): boolean {
 127     if (connectorId < 0) {
 128       logger.error(
 129         `${chargingStation.logPrefix()} ${ocppCommand} incoming request received with invalid connector id ${connectorId}`
 130       );
 131       return false;
 132     }
 133     return true;
 134   }
 135
 136   public static convertDateToISOString<T extends JsonType>(obj: T): void {
 137     for (const key in obj) {
 138       if (obj[key] instanceof Date) {
 139         (obj as JsonObject)[key] = (obj[key] as Date).toISOString();
 140       } else if (obj[key] !== null && typeof obj[key] === 'object') {
 141         OCPPServiceUtils.convertDateToISOString<T>(obj[key] as T);
 142       }
 143     }
 144   }
 145
 146   public static buildStatusNotificationRequest(
 147     chargingStation: ChargingStation,
 148     connectorId: number,
 149     status: ConnectorStatusEnum,
 150     evseId?: number
 151   ): StatusNotificationRequest {
 152     switch (chargingStation.stationInfo.ocppVersion ?? OCPPVersion.VERSION_16) {
 153       case OCPPVersion.VERSION_16:
 154         return {
 155           connectorId,
 156           status,
 157           errorCode: ChargePointErrorCode.NO_ERROR,
 158         } as OCPP16StatusNotificationRequest;
 159       case OCPPVersion.VERSION_20:
 160       case OCPPVersion.VERSION_201:
 161         return {
 162           timestamp: new Date(),
 163           connectorStatus: status,
 164           connectorId,
 165           evseId,
 166         } as OCPP20StatusNotificationRequest;
 167       default:
 168         throw new BaseError('Cannot build status notification payload: OCPP version not supported');
 169     }
 170   }
 171
 172   public static startHeartbeatInterval(chargingStation: ChargingStation, interval: number): void {
 173     if (!chargingStation.heartbeatSetInterval) {
 174       chargingStation.startHeartbeat();
 175     } else if (chargingStation.getHeartbeatInterval() !== interval) {
 176       chargingStation.restartHeartbeat();
 177     }
 178   }
 179
 180   public static async sendAndSetConnectorStatus(
 181     chargingStation: ChargingStation,
 182     connectorId: number,
 183     status: ConnectorStatusEnum,
 184     evseId?: number
 185   ) {
 186     OCPPServiceUtils.checkConnectorStatusTransition(chargingStation, connectorId, status);
 187     await chargingStation.ocppRequestService.requestHandler<
 188       StatusNotificationRequest,
 189       StatusNotificationResponse
 190     >(
 191       chargingStation,
 192       RequestCommand.STATUS_NOTIFICATION,
 193       OCPPServiceUtils.buildStatusNotificationRequest(chargingStation, connectorId, status, evseId)
 194     );
 195     chargingStation.getConnectorStatus(connectorId).status = status;
 196   }
 197
 198   protected static checkConnectorStatusTransition(
 199     chargingStation: ChargingStation,
 200     connectorId: number,
 201     status: ConnectorStatusEnum
 202   ): boolean {
 203     const fromStatus = chargingStation.getConnectorStatus(connectorId).status;
 204     let transitionAllowed = false;
 205     switch (chargingStation.stationInfo.ocppVersion) {
 206       case OCPPVersion.VERSION_16:
 207         if (
 208           connectorId === 0 &&
 209           OCPP16Constants.ChargePointStatusChargingStationTransitions.findIndex(
 210             (transition) => transition.from === fromStatus && transition.to === status
 211           ) !== -1
 212         ) {
 213           transitionAllowed = true;
 214         } else if (
 215           OCPP16Constants.ChargePointStatusConnectorTransitions.findIndex(
 216             (transition) => transition.from === fromStatus && transition.to === status
 217           ) !== -1
 218         ) {
 219           transitionAllowed = true;
 220         }
 221         break;
 222       case OCPPVersion.VERSION_20:
 223       case OCPPVersion.VERSION_201:
 224         if (
 225           connectorId === 0 &&
 226           OCPP20Constants.ChargingStationStatusTransitions.findIndex(
 227             (transition) => transition.from === fromStatus && transition.to === status
 228           ) !== -1
 229         ) {
 230           transitionAllowed = true;
 231         } else if (
 232           OCPP20Constants.ConnectorStatusTransitions.findIndex(
 233             (transition) => transition.from === fromStatus && transition.to === status
 234           ) !== -1
 235         ) {
 236           transitionAllowed = true;
 237         }
 238         break;
 239       default:
 240         throw new BaseError(
 241           // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
 242           `Cannot check connector status transition: OCPP version ${chargingStation.stationInfo.ocppVersion} not supported`
 243         );
 244     }
 245     if (transitionAllowed === false) {
 246       logger.warn(
 247         `${chargingStation.logPrefix()} OCPP ${
 248           chargingStation.stationInfo.ocppVersion
 249         } connector id ${connectorId} status transition from '${
 250           chargingStation.getConnectorStatus(connectorId).status
 251         }' to '${status}' is not allowed`
 252       );
 253     }
 254     return transitionAllowed;
 255   }
 256
 257   protected static parseJsonSchemaFile<T extends JsonType>(
 258     filePath: string,
 259     ocppVersion: OCPPVersion,
 260     moduleName?: string,
 261     methodName?: string
 262   ): JSONSchemaType<T> {
 263     try {
 264       return JSON.parse(fs.readFileSync(filePath, 'utf8')) as JSONSchemaType<T>;
 265     } catch (error) {
 266       FileUtils.handleFileException(
 267         filePath,
 268         FileType.JsonSchema,
 269         error as NodeJS.ErrnoException,
 270         OCPPServiceUtils.logPrefix(ocppVersion, moduleName, methodName),
 271         { throwError: false }
 272       );
 273     }
 274   }
 275
 276   protected static getSampledValueTemplate(
 277     chargingStation: ChargingStation,
 278     connectorId: number,
 279     measurand: MeterValueMeasurand = MeterValueMeasurand.ENERGY_ACTIVE_IMPORT_REGISTER,
 280     phase?: MeterValuePhase
 281   ): SampledValueTemplate | undefined {
 282     const onPhaseStr = phase ? `on phase ${phase} ` : '';
 283     if (Constants.SUPPORTED_MEASURANDS.includes(measurand) === false) {
 284       logger.warn(
 285         `${chargingStation.logPrefix()} Trying to get unsupported MeterValues measurand '${measurand}' ${onPhaseStr}in template on connector id ${connectorId}`
 286       );
 287       return;
 288     }
 289     if (
 290       measurand !== MeterValueMeasurand.ENERGY_ACTIVE_IMPORT_REGISTER &&
 291       ChargingStationConfigurationUtils.getConfigurationKey(
 292         chargingStation,
 293         StandardParametersKey.MeterValuesSampledData
 294       )?.value?.includes(measurand) === false
 295     ) {
 296       logger.debug(
 297         `${chargingStation.logPrefix()} Trying to get MeterValues measurand '${measurand}' ${onPhaseStr}in template on connector id ${connectorId} not found in '${
 298           StandardParametersKey.MeterValuesSampledData
 299         }' OCPP parameter`
 300       );
 301       return;
 302     }
 303     const sampledValueTemplates: SampledValueTemplate[] =
 304       chargingStation.getConnectorStatus(connectorId)?.MeterValues;
 305     for (
 306       let index = 0;
 307       Utils.isNotEmptyArray(sampledValueTemplates) === true && index < sampledValueTemplates.length;
 308       index++
 309     ) {
 310       if (
 311         Constants.SUPPORTED_MEASURANDS.includes(
 312           sampledValueTemplates[index]?.measurand ??
 313             MeterValueMeasurand.ENERGY_ACTIVE_IMPORT_REGISTER
 314         ) === false
 315       ) {
 316         logger.warn(
 317           `${chargingStation.logPrefix()} Unsupported MeterValues measurand '${measurand}' ${onPhaseStr}in template on connector id ${connectorId}`
 318         );
 319       } else if (
 320         phase &&
 321         sampledValueTemplates[index]?.phase === phase &&
 322         sampledValueTemplates[index]?.measurand === measurand &&
 323         ChargingStationConfigurationUtils.getConfigurationKey(
 324           chargingStation,
 325           StandardParametersKey.MeterValuesSampledData
 326         )?.value?.includes(measurand) === true
 327       ) {
 328         return sampledValueTemplates[index];
 329       } else if (
 330         !phase &&
 331         !sampledValueTemplates[index].phase &&
 332         sampledValueTemplates[index]?.measurand === measurand &&
 333         ChargingStationConfigurationUtils.getConfigurationKey(
 334           chargingStation,
 335           StandardParametersKey.MeterValuesSampledData
 336         )?.value?.includes(measurand) === true
 337       ) {
 338         return sampledValueTemplates[index];
 339       } else if (
 340         measurand === MeterValueMeasurand.ENERGY_ACTIVE_IMPORT_REGISTER &&
 341         (!sampledValueTemplates[index].measurand ||
 342           sampledValueTemplates[index].measurand === measurand)
 343       ) {
 344         return sampledValueTemplates[index];
 345       }
 346     }
 347     if (measurand === MeterValueMeasurand.ENERGY_ACTIVE_IMPORT_REGISTER) {
 348       const errorMsg = `Missing MeterValues for default measurand '${measurand}' in template on connector id ${connectorId}`;
 349       logger.error(`${chargingStation.logPrefix()} ${errorMsg}`);
 350       throw new BaseError(errorMsg);
 351     }
 352     logger.debug(
 353       `${chargingStation.logPrefix()} No MeterValues for measurand '${measurand}' ${onPhaseStr}in template on connector id ${connectorId}`
 354     );
 355   }
 356
 357   protected static getLimitFromSampledValueTemplateCustomValue(
 358     value: string,
 359     limit: number,
 360     options: { limitationEnabled?: boolean; unitMultiplier?: number } = {
 361       limitationEnabled: true,
 362       unitMultiplier: 1,
 363     }
 364   ): number {
 365     options.limitationEnabled = options?.limitationEnabled ?? true;
 366     options.unitMultiplier = options?.unitMultiplier ?? 1;
 367     const parsedInt = parseInt(value);
 368     const numberValue = isNaN(parsedInt) ? Infinity : parsedInt;
 369     return options?.limitationEnabled
 370       ? Math.min(numberValue * options.unitMultiplier, limit)
 371       : numberValue * options.unitMultiplier;
 372   }
 373
 374   private static logPrefix = (
 375     ocppVersion: OCPPVersion,
 376     moduleName?: string,
 377     methodName?: string
 378   ): string => {
 379     const logMsg =
 380       Utils.isNotEmptyString(moduleName) && Utils.isNotEmptyString(methodName)
 381         ? ` OCPP ${ocppVersion} | ${moduleName}.${methodName}:`
 382         : ` OCPP ${ocppVersion} |`;
 383     return Utils.logPrefix(logMsg);
 384   };
 385 }