src/charging-station/ChargingStationUtils.ts

   1 import { createHash, randomBytes } from 'node:crypto';
   2 import type { EventEmitter } from 'node:events';
   3 import { basename, dirname, join } from 'node:path';
   4 import { fileURLToPath } from 'node:url';
   5
   6 import chalk from 'chalk';
   7 import {
   8   addDays,
   9   addSeconds,
  10   addWeeks,
  11   differenceInDays,
  12   differenceInSeconds,
  13   differenceInWeeks,
  14   isAfter,
  15   isBefore,
  16   isWithinInterval,
  17   toDate,
  18 } from 'date-fns';
  19
  20 import type { ChargingStation } from './ChargingStation';
  21 import { BaseError } from '../exception';
  22 import {
  23   AmpereUnits,
  24   AvailabilityType,
  25   type BootNotificationRequest,
  26   BootReasonEnumType,
  27   type ChargingProfile,
  28   ChargingProfileKindType,
  29   ChargingRateUnitType,
  30   type ChargingSchedulePeriod,
  31   type ChargingStationInfo,
  32   type ChargingStationTemplate,
  33   ChargingStationWorkerMessageEvents,
  34   ConnectorPhaseRotation,
  35   type ConnectorStatus,
  36   ConnectorStatusEnum,
  37   CurrentType,
  38   type EvseTemplate,
  39   type OCPP16BootNotificationRequest,
  40   type OCPP20BootNotificationRequest,
  41   OCPPVersion,
  42   RecurrencyKindType,
  43   Voltage,
  44 } from '../types';
  45 import {
  46   ACElectricUtils,
  47   Constants,
  48   DCElectricUtils,
  49   cloneObject,
  50   convertToDate,
  51   convertToInt,
  52   isArraySorted,
  53   isEmptyObject,
  54   isEmptyString,
  55   isNotEmptyArray,
  56   isNotEmptyString,
  57   isNullOrUndefined,
  58   isUndefined,
  59   isValidDate,
  60   logger,
  61   secureRandom,
  62 } from '../utils';
  63
  64 const moduleName = 'ChargingStationUtils';
  65
  66 export const getChargingStationId = (
  67   index: number,
  68   stationTemplate: ChargingStationTemplate,
  69 ): string => {
  70   // In case of multiple instances: add instance index to charging station id
  71   const instanceIndex = process.env.CF_INSTANCE_INDEX ?? 0;
  72   const idSuffix = stationTemplate?.nameSuffix ?? '';
  73   const idStr = `000000000${index.toString()}`;
  74   return stationTemplate?.fixedName
  75     ? stationTemplate.baseName
  76     : `${stationTemplate.baseName}-${instanceIndex.toString()}${idStr.substring(
  77         idStr.length - 4,
  78       )}${idSuffix}`;
  79 };
  80
  81 export const countReservableConnectors = (connectors: Map<number, ConnectorStatus>) => {
  82   let reservableConnectors = 0;
  83   for (const [connectorId, connectorStatus] of connectors) {
  84     if (connectorId === 0) {
  85       continue;
  86     }
  87     if (connectorStatus.status === ConnectorStatusEnum.Available) {
  88       ++reservableConnectors;
  89     }
  90   }
  91   return reservableConnectors;
  92 };
  93
  94 export const getHashId = (index: number, stationTemplate: ChargingStationTemplate): string => {
  95   const chargingStationInfo = {
  96     chargePointModel: stationTemplate.chargePointModel,
  97     chargePointVendor: stationTemplate.chargePointVendor,
  98     ...(!isUndefined(stationTemplate.chargeBoxSerialNumberPrefix) && {
  99       chargeBoxSerialNumber: stationTemplate.chargeBoxSerialNumberPrefix,
 100     }),
 101     ...(!isUndefined(stationTemplate.chargePointSerialNumberPrefix) && {
 102       chargePointSerialNumber: stationTemplate.chargePointSerialNumberPrefix,
 103     }),
 104     ...(!isUndefined(stationTemplate.meterSerialNumberPrefix) && {
 105       meterSerialNumber: stationTemplate.meterSerialNumberPrefix,
 106     }),
 107     ...(!isUndefined(stationTemplate.meterType) && {
 108       meterType: stationTemplate.meterType,
 109     }),
 110   };
 111   return createHash(Constants.DEFAULT_HASH_ALGORITHM)
 112     .update(`${JSON.stringify(chargingStationInfo)}${getChargingStationId(index, stationTemplate)}`)
 113     .digest('hex');
 114 };
 115
 116 export const checkChargingStation = (
 117   chargingStation: ChargingStation,
 118   logPrefix: string,
 119 ): boolean => {
 120   if (chargingStation.started === false && chargingStation.starting === false) {
 121     logger.warn(`${logPrefix} charging station is stopped, cannot proceed`);
 122     return false;
 123   }
 124   return true;
 125 };
 126
 127 export const getPhaseRotationValue = (
 128   connectorId: number,
 129   numberOfPhases: number,
 130 ): string | undefined => {
 131   // AC/DC
 132   if (connectorId === 0 && numberOfPhases === 0) {
 133     return `${connectorId}.${ConnectorPhaseRotation.RST}`;
 134   } else if (connectorId > 0 && numberOfPhases === 0) {
 135     return `${connectorId}.${ConnectorPhaseRotation.NotApplicable}`;
 136     // AC
 137   } else if (connectorId > 0 && numberOfPhases === 1) {
 138     return `${connectorId}.${ConnectorPhaseRotation.NotApplicable}`;
 139   } else if (connectorId > 0 && numberOfPhases === 3) {
 140     return `${connectorId}.${ConnectorPhaseRotation.RST}`;
 141   }
 142 };
 143
 144 export const getMaxNumberOfEvses = (evses: Record<string, EvseTemplate>): number => {
 145   if (!evses) {
 146     return -1;
 147   }
 148   return Object.keys(evses).length;
 149 };
 150
 151 const getMaxNumberOfConnectors = (connectors: Record<string, ConnectorStatus>): number => {
 152   if (!connectors) {
 153     return -1;
 154   }
 155   return Object.keys(connectors).length;
 156 };
 157
 158 export const getBootConnectorStatus = (
 159   chargingStation: ChargingStation,
 160   connectorId: number,
 161   connectorStatus: ConnectorStatus,
 162 ): ConnectorStatusEnum => {
 163   let connectorBootStatus: ConnectorStatusEnum;
 164   if (
 165     !connectorStatus?.status &&
 166     (chargingStation.isChargingStationAvailable() === false ||
 167       chargingStation.isConnectorAvailable(connectorId) === false)
 168   ) {
 169     connectorBootStatus = ConnectorStatusEnum.Unavailable;
 170   } else if (!connectorStatus?.status && connectorStatus?.bootStatus) {
 171     // Set boot status in template at startup
 172     connectorBootStatus = connectorStatus?.bootStatus;
 173   } else if (connectorStatus?.status) {
 174     // Set previous status at startup
 175     connectorBootStatus = connectorStatus?.status;
 176   } else {
 177     // Set default status
 178     connectorBootStatus = ConnectorStatusEnum.Available;
 179   }
 180   return connectorBootStatus;
 181 };
 182
 183 export const checkTemplate = (
 184   stationTemplate: ChargingStationTemplate,
 185   logPrefix: string,
 186   templateFile: string,
 187 ): void => {
 188   if (isNullOrUndefined(stationTemplate)) {
 189     const errorMsg = `Failed to read charging station template file ${templateFile}`;
 190     logger.error(`${logPrefix} ${errorMsg}`);
 191     throw new BaseError(errorMsg);
 192   }
 193   if (isEmptyObject(stationTemplate)) {
 194     const errorMsg = `Empty charging station information from template file ${templateFile}`;
 195     logger.error(`${logPrefix} ${errorMsg}`);
 196     throw new BaseError(errorMsg);
 197   }
 198   if (isEmptyObject(stationTemplate.AutomaticTransactionGenerator!)) {
 199     stationTemplate.AutomaticTransactionGenerator = Constants.DEFAULT_ATG_CONFIGURATION;
 200     logger.warn(
 201       `${logPrefix} Empty automatic transaction generator configuration from template file ${templateFile}, set to default: %j`,
 202       Constants.DEFAULT_ATG_CONFIGURATION,
 203     );
 204   }
 205   if (isNullOrUndefined(stationTemplate.idTagsFile) || isEmptyString(stationTemplate.idTagsFile)) {
 206     logger.warn(
 207       `${logPrefix} Missing id tags file in template file ${templateFile}. That can lead to issues with the Automatic Transaction Generator`,
 208     );
 209   }
 210 };
 211
 212 export const checkConnectorsConfiguration = (
 213   stationTemplate: ChargingStationTemplate,
 214   logPrefix: string,
 215   templateFile: string,
 216 ): {
 217   configuredMaxConnectors: number;
 218   templateMaxConnectors: number;
 219   templateMaxAvailableConnectors: number;
 220 } => {
 221   const configuredMaxConnectors = getConfiguredNumberOfConnectors(stationTemplate);
 222   checkConfiguredMaxConnectors(configuredMaxConnectors, logPrefix, templateFile);
 223   const templateMaxConnectors = getMaxNumberOfConnectors(stationTemplate.Connectors!);
 224   checkTemplateMaxConnectors(templateMaxConnectors, logPrefix, templateFile);
 225   const templateMaxAvailableConnectors = stationTemplate.Connectors![0]
 226     ? templateMaxConnectors - 1
 227     : templateMaxConnectors;
 228   if (
 229     configuredMaxConnectors > templateMaxAvailableConnectors &&
 230     !stationTemplate?.randomConnectors
 231   ) {
 232     logger.warn(
 233       `${logPrefix} Number of connectors exceeds the number of connector configurations in template ${templateFile}, forcing random connector configurations affectation`,
 234     );
 235     stationTemplate.randomConnectors = true;
 236   }
 237   return { configuredMaxConnectors, templateMaxConnectors, templateMaxAvailableConnectors };
 238 };
 239
 240 export const checkStationInfoConnectorStatus = (
 241   connectorId: number,
 242   connectorStatus: ConnectorStatus,
 243   logPrefix: string,
 244   templateFile: string,
 245 ): void => {
 246   if (!isNullOrUndefined(connectorStatus?.status)) {
 247     logger.warn(
 248       `${logPrefix} Charging station information from template ${templateFile} with connector id ${connectorId} status configuration defined, undefine it`,
 249     );
 250     delete connectorStatus.status;
 251   }
 252 };
 253
 254 export const buildConnectorsMap = (
 255   connectors: Record<string, ConnectorStatus>,
 256   logPrefix: string,
 257   templateFile: string,
 258 ): Map<number, ConnectorStatus> => {
 259   const connectorsMap = new Map<number, ConnectorStatus>();
 260   if (getMaxNumberOfConnectors(connectors) > 0) {
 261     for (const connector in connectors) {
 262       const connectorStatus = connectors[connector];
 263       const connectorId = convertToInt(connector);
 264       checkStationInfoConnectorStatus(connectorId, connectorStatus, logPrefix, templateFile);
 265       connectorsMap.set(connectorId, cloneObject<ConnectorStatus>(connectorStatus));
 266     }
 267   } else {
 268     logger.warn(
 269       `${logPrefix} Charging station information from template ${templateFile} with no connectors, cannot build connectors map`,
 270     );
 271   }
 272   return connectorsMap;
 273 };
 274
 275 export const initializeConnectorsMapStatus = (
 276   connectors: Map<number, ConnectorStatus>,
 277   logPrefix: string,
 278 ): void => {
 279   for (const connectorId of connectors.keys()) {
 280     if (connectorId > 0 && connectors.get(connectorId)?.transactionStarted === true) {
 281       logger.warn(
 282         `${logPrefix} Connector id ${connectorId} at initialization has a transaction started with id ${connectors.get(
 283           connectorId,
 284         )?.transactionId}`,
 285       );
 286     }
 287     if (connectorId === 0) {
 288       connectors.get(connectorId)!.availability = AvailabilityType.Operative;
 289       if (isUndefined(connectors.get(connectorId)?.chargingProfiles)) {
 290         connectors.get(connectorId)!.chargingProfiles = [];
 291       }
 292     } else if (
 293       connectorId > 0 &&
 294       isNullOrUndefined(connectors.get(connectorId)?.transactionStarted)
 295     ) {
 296       initializeConnectorStatus(connectors.get(connectorId)!);
 297     }
 298   }
 299 };
 300
 301 export const resetConnectorStatus = (connectorStatus: ConnectorStatus): void => {
 302   connectorStatus.idTagLocalAuthorized = false;
 303   connectorStatus.idTagAuthorized = false;
 304   connectorStatus.transactionRemoteStarted = false;
 305   connectorStatus.transactionStarted = false;
 306   delete connectorStatus?.transactionStart;
 307   delete connectorStatus?.transactionId;
 308   delete connectorStatus?.localAuthorizeIdTag;
 309   delete connectorStatus?.authorizeIdTag;
 310   delete connectorStatus?.transactionIdTag;
 311   connectorStatus.transactionEnergyActiveImportRegisterValue = 0;
 312   delete connectorStatus?.transactionBeginMeterValue;
 313 };
 314
 315 export const createBootNotificationRequest = (
 316   stationInfo: ChargingStationInfo,
 317   bootReason: BootReasonEnumType = BootReasonEnumType.PowerUp,
 318 ): BootNotificationRequest => {
 319   const ocppVersion = stationInfo.ocppVersion ?? OCPPVersion.VERSION_16;
 320   switch (ocppVersion) {
 321     case OCPPVersion.VERSION_16:
 322       return {
 323         chargePointModel: stationInfo.chargePointModel,
 324         chargePointVendor: stationInfo.chargePointVendor,
 325         ...(!isUndefined(stationInfo.chargeBoxSerialNumber) && {
 326           chargeBoxSerialNumber: stationInfo.chargeBoxSerialNumber,
 327         }),
 328         ...(!isUndefined(stationInfo.chargePointSerialNumber) && {
 329           chargePointSerialNumber: stationInfo.chargePointSerialNumber,
 330         }),
 331         ...(!isUndefined(stationInfo.firmwareVersion) && {
 332           firmwareVersion: stationInfo.firmwareVersion,
 333         }),
 334         ...(!isUndefined(stationInfo.iccid) && { iccid: stationInfo.iccid }),
 335         ...(!isUndefined(stationInfo.imsi) && { imsi: stationInfo.imsi }),
 336         ...(!isUndefined(stationInfo.meterSerialNumber) && {
 337           meterSerialNumber: stationInfo.meterSerialNumber,
 338         }),
 339         ...(!isUndefined(stationInfo.meterType) && {
 340           meterType: stationInfo.meterType,
 341         }),
 342       } as OCPP16BootNotificationRequest;
 343     case OCPPVersion.VERSION_20:
 344     case OCPPVersion.VERSION_201:
 345       return {
 346         reason: bootReason,
 347         chargingStation: {
 348           model: stationInfo.chargePointModel,
 349           vendorName: stationInfo.chargePointVendor,
 350           ...(!isUndefined(stationInfo.firmwareVersion) && {
 351             firmwareVersion: stationInfo.firmwareVersion,
 352           }),
 353           ...(!isUndefined(stationInfo.chargeBoxSerialNumber) && {
 354             serialNumber: stationInfo.chargeBoxSerialNumber,
 355           }),
 356           ...((!isUndefined(stationInfo.iccid) || !isUndefined(stationInfo.imsi)) && {
 357             modem: {
 358               ...(!isUndefined(stationInfo.iccid) && { iccid: stationInfo.iccid }),
 359               ...(!isUndefined(stationInfo.imsi) && { imsi: stationInfo.imsi }),
 360             },
 361           }),
 362         },
 363       } as OCPP20BootNotificationRequest;
 364   }
 365 };
 366
 367 export const warnTemplateKeysDeprecation = (
 368   stationTemplate: ChargingStationTemplate,
 369   logPrefix: string,
 370   templateFile: string,
 371 ) => {
 372   const templateKeys: { deprecatedKey: string; key?: string }[] = [
 373     { deprecatedKey: 'supervisionUrl', key: 'supervisionUrls' },
 374     { deprecatedKey: 'authorizationFile', key: 'idTagsFile' },
 375     { deprecatedKey: 'payloadSchemaValidation', key: 'ocppStrictCompliance' },
 376   ];
 377   for (const templateKey of templateKeys) {
 378     warnDeprecatedTemplateKey(
 379       stationTemplate,
 380       templateKey.deprecatedKey,
 381       logPrefix,
 382       templateFile,
 383       !isUndefined(templateKey.key) ? `Use '${templateKey.key}' instead` : undefined,
 384     );
 385     convertDeprecatedTemplateKey(stationTemplate, templateKey.deprecatedKey, templateKey.key);
 386   }
 387 };
 388
 389 export const stationTemplateToStationInfo = (
 390   stationTemplate: ChargingStationTemplate,
 391 ): ChargingStationInfo => {
 392   stationTemplate = cloneObject<ChargingStationTemplate>(stationTemplate);
 393   delete stationTemplate.power;
 394   delete stationTemplate.powerUnit;
 395   delete stationTemplate.Connectors;
 396   delete stationTemplate.Evses;
 397   delete stationTemplate.Configuration;
 398   delete stationTemplate.AutomaticTransactionGenerator;
 399   delete stationTemplate.chargeBoxSerialNumberPrefix;
 400   delete stationTemplate.chargePointSerialNumberPrefix;
 401   delete stationTemplate.meterSerialNumberPrefix;
 402   return stationTemplate as unknown as ChargingStationInfo;
 403 };
 404
 405 export const createSerialNumber = (
 406   stationTemplate: ChargingStationTemplate,
 407   stationInfo: ChargingStationInfo,
 408   params: {
 409     randomSerialNumberUpperCase?: boolean;
 410     randomSerialNumber?: boolean;
 411   } = {
 412     randomSerialNumberUpperCase: true,
 413     randomSerialNumber: true,
 414   },
 415 ): void => {
 416   params = { ...{ randomSerialNumberUpperCase: true, randomSerialNumber: true }, ...params };
 417   const serialNumberSuffix = params?.randomSerialNumber
 418     ? getRandomSerialNumberSuffix({
 419         upperCase: params.randomSerialNumberUpperCase,
 420       })
 421     : '';
 422   isNotEmptyString(stationTemplate?.chargePointSerialNumberPrefix) &&
 423     (stationInfo.chargePointSerialNumber = `${stationTemplate.chargePointSerialNumberPrefix}${serialNumberSuffix}`);
 424   isNotEmptyString(stationTemplate?.chargeBoxSerialNumberPrefix) &&
 425     (stationInfo.chargeBoxSerialNumber = `${stationTemplate.chargeBoxSerialNumberPrefix}${serialNumberSuffix}`);
 426   isNotEmptyString(stationTemplate?.meterSerialNumberPrefix) &&
 427     (stationInfo.meterSerialNumber = `${stationTemplate.meterSerialNumberPrefix}${serialNumberSuffix}`);
 428 };
 429
 430 export const propagateSerialNumber = (
 431   stationTemplate: ChargingStationTemplate,
 432   stationInfoSrc: ChargingStationInfo,
 433   stationInfoDst: ChargingStationInfo,
 434 ) => {
 435   if (!stationInfoSrc || !stationTemplate) {
 436     throw new BaseError(
 437       'Missing charging station template or existing configuration to propagate serial number',
 438     );
 439   }
 440   stationTemplate?.chargePointSerialNumberPrefix && stationInfoSrc?.chargePointSerialNumber
 441     ? (stationInfoDst.chargePointSerialNumber = stationInfoSrc.chargePointSerialNumber)
 442     : stationInfoDst?.chargePointSerialNumber && delete stationInfoDst.chargePointSerialNumber;
 443   stationTemplate?.chargeBoxSerialNumberPrefix && stationInfoSrc?.chargeBoxSerialNumber
 444     ? (stationInfoDst.chargeBoxSerialNumber = stationInfoSrc.chargeBoxSerialNumber)
 445     : stationInfoDst?.chargeBoxSerialNumber && delete stationInfoDst.chargeBoxSerialNumber;
 446   stationTemplate?.meterSerialNumberPrefix && stationInfoSrc?.meterSerialNumber
 447     ? (stationInfoDst.meterSerialNumber = stationInfoSrc.meterSerialNumber)
 448     : stationInfoDst?.meterSerialNumber && delete stationInfoDst.meterSerialNumber;
 449 };
 450
 451 export const getAmperageLimitationUnitDivider = (stationInfo: ChargingStationInfo): number => {
 452   let unitDivider = 1;
 453   switch (stationInfo.amperageLimitationUnit) {
 454     case AmpereUnits.DECI_AMPERE:
 455       unitDivider = 10;
 456       break;
 457     case AmpereUnits.CENTI_AMPERE:
 458       unitDivider = 100;
 459       break;
 460     case AmpereUnits.MILLI_AMPERE:
 461       unitDivider = 1000;
 462       break;
 463   }
 464   return unitDivider;
 465 };
 466
 467 export const getChargingStationConnectorChargingProfilesPowerLimit = (
 468   chargingStation: ChargingStation,
 469   connectorId: number,
 470 ): number | undefined => {
 471   let limit: number | undefined, matchingChargingProfile: ChargingProfile | undefined;
 472   // Get charging profiles for connector id and sort by stack level
 473   const chargingProfiles =
 474     cloneObject<ChargingProfile[]>(
 475       chargingStation.getConnectorStatus(connectorId)!.chargingProfiles!,
 476     )?.sort((a, b) => b.stackLevel - a.stackLevel) ?? [];
 477   // Get charging profiles on connector 0 and sort by stack level
 478   if (isNotEmptyArray(chargingStation.getConnectorStatus(0)?.chargingProfiles)) {
 479     chargingProfiles.push(
 480       ...cloneObject<ChargingProfile[]>(
 481         chargingStation.getConnectorStatus(0)!.chargingProfiles!,
 482       ).sort((a, b) => b.stackLevel - a.stackLevel),
 483     );
 484   }
 485   if (isNotEmptyArray(chargingProfiles)) {
 486     const result = getLimitFromChargingProfiles(
 487       chargingStation,
 488       connectorId,
 489       chargingProfiles,
 490       chargingStation.logPrefix(),
 491     );
 492     if (!isNullOrUndefined(result)) {
 493       limit = result?.limit;
 494       matchingChargingProfile = result?.matchingChargingProfile;
 495       switch (chargingStation.getCurrentOutType()) {
 496         case CurrentType.AC:
 497           limit =
 498             matchingChargingProfile?.chargingSchedule?.chargingRateUnit ===
 499             ChargingRateUnitType.WATT
 500               ? limit
 501               : ACElectricUtils.powerTotal(
 502                   chargingStation.getNumberOfPhases(),
 503                   chargingStation.getVoltageOut(),
 504                   limit!,
 505                 );
 506           break;
 507         case CurrentType.DC:
 508           limit =
 509             matchingChargingProfile?.chargingSchedule?.chargingRateUnit ===
 510             ChargingRateUnitType.WATT
 511               ? limit
 512               : DCElectricUtils.power(chargingStation.getVoltageOut(), limit!);
 513       }
 514       const connectorMaximumPower =
 515         chargingStation.getMaximumPower() / chargingStation.powerDivider;
 516       if (limit! > connectorMaximumPower) {
 517         logger.error(
 518           `${chargingStation.logPrefix()} ${moduleName}.getChargingStationConnectorChargingProfilesPowerLimit: Charging profile id ${matchingChargingProfile?.chargingProfileId} limit ${limit} is greater than connector id ${connectorId} maximum ${connectorMaximumPower}: %j`,
 519           result,
 520         );
 521         limit = connectorMaximumPower;
 522       }
 523     }
 524   }
 525   return limit;
 526 };
 527
 528 export const getDefaultVoltageOut = (
 529   currentType: CurrentType,
 530   logPrefix: string,
 531   templateFile: string,
 532 ): Voltage => {
 533   const errorMsg = `Unknown ${currentType} currentOutType in template file ${templateFile}, cannot define default voltage out`;
 534   let defaultVoltageOut: number;
 535   switch (currentType) {
 536     case CurrentType.AC:
 537       defaultVoltageOut = Voltage.VOLTAGE_230;
 538       break;
 539     case CurrentType.DC:
 540       defaultVoltageOut = Voltage.VOLTAGE_400;
 541       break;
 542     default:
 543       logger.error(`${logPrefix} ${errorMsg}`);
 544       throw new BaseError(errorMsg);
 545   }
 546   return defaultVoltageOut;
 547 };
 548
 549 export const getIdTagsFile = (stationInfo: ChargingStationInfo): string | undefined => {
 550   return (
 551     stationInfo.idTagsFile &&
 552     join(dirname(fileURLToPath(import.meta.url)), 'assets', basename(stationInfo.idTagsFile))
 553   );
 554 };
 555
 556 export const waitChargingStationEvents = async (
 557   emitter: EventEmitter,
 558   event: ChargingStationWorkerMessageEvents,
 559   eventsToWait: number,
 560 ): Promise<number> => {
 561   return new Promise<number>((resolve) => {
 562     let events = 0;
 563     if (eventsToWait === 0) {
 564       resolve(events);
 565     }
 566     emitter.on(event, () => {
 567       ++events;
 568       if (events === eventsToWait) {
 569         resolve(events);
 570       }
 571     });
 572   });
 573 };
 574
 575 const getConfiguredNumberOfConnectors = (stationTemplate: ChargingStationTemplate): number => {
 576   let configuredMaxConnectors = 0;
 577   if (isNotEmptyArray(stationTemplate.numberOfConnectors) === true) {
 578     const numberOfConnectors = stationTemplate.numberOfConnectors as number[];
 579     configuredMaxConnectors =
 580       numberOfConnectors[Math.floor(secureRandom() * numberOfConnectors.length)];
 581   } else if (isUndefined(stationTemplate.numberOfConnectors) === false) {
 582     configuredMaxConnectors = stationTemplate.numberOfConnectors as number;
 583   } else if (stationTemplate.Connectors && !stationTemplate.Evses) {
 584     configuredMaxConnectors = stationTemplate.Connectors[0]
 585       ? getMaxNumberOfConnectors(stationTemplate.Connectors) - 1
 586       : getMaxNumberOfConnectors(stationTemplate.Connectors);
 587   } else if (stationTemplate.Evses && !stationTemplate.Connectors) {
 588     for (const evse in stationTemplate.Evses) {
 589       if (evse === '0') {
 590         continue;
 591       }
 592       configuredMaxConnectors += getMaxNumberOfConnectors(stationTemplate.Evses[evse].Connectors);
 593     }
 594   }
 595   return configuredMaxConnectors;
 596 };
 597
 598 const checkConfiguredMaxConnectors = (
 599   configuredMaxConnectors: number,
 600   logPrefix: string,
 601   templateFile: string,
 602 ): void => {
 603   if (configuredMaxConnectors <= 0) {
 604     logger.warn(
 605       `${logPrefix} Charging station information from template ${templateFile} with ${configuredMaxConnectors} connectors`,
 606     );
 607   }
 608 };
 609
 610 const checkTemplateMaxConnectors = (
 611   templateMaxConnectors: number,
 612   logPrefix: string,
 613   templateFile: string,
 614 ): void => {
 615   if (templateMaxConnectors === 0) {
 616     logger.warn(
 617       `${logPrefix} Charging station information from template ${templateFile} with empty connectors configuration`,
 618     );
 619   } else if (templateMaxConnectors < 0) {
 620     logger.error(
 621       `${logPrefix} Charging station information from template ${templateFile} with no connectors configuration defined`,
 622     );
 623   }
 624 };
 625
 626 const initializeConnectorStatus = (connectorStatus: ConnectorStatus): void => {
 627   connectorStatus.availability = AvailabilityType.Operative;
 628   connectorStatus.idTagLocalAuthorized = false;
 629   connectorStatus.idTagAuthorized = false;
 630   connectorStatus.transactionRemoteStarted = false;
 631   connectorStatus.transactionStarted = false;
 632   connectorStatus.energyActiveImportRegisterValue = 0;
 633   connectorStatus.transactionEnergyActiveImportRegisterValue = 0;
 634   if (isUndefined(connectorStatus.chargingProfiles)) {
 635     connectorStatus.chargingProfiles = [];
 636   }
 637 };
 638
 639 const warnDeprecatedTemplateKey = (
 640   template: ChargingStationTemplate,
 641   key: string,
 642   logPrefix: string,
 643   templateFile: string,
 644   logMsgToAppend = '',
 645 ): void => {
 646   if (!isUndefined(template[key as keyof ChargingStationTemplate])) {
 647     const logMsg = `Deprecated template key '${key}' usage in file '${templateFile}'${
 648       isNotEmptyString(logMsgToAppend) ? `. ${logMsgToAppend}` : ''
 649     }`;
 650     logger.warn(`${logPrefix} ${logMsg}`);
 651     console.warn(chalk.yellow(`${logMsg}`));
 652   }
 653 };
 654
 655 const convertDeprecatedTemplateKey = (
 656   template: ChargingStationTemplate,
 657   deprecatedKey: string,
 658   key?: string,
 659 ): void => {
 660   if (!isUndefined(template[deprecatedKey as keyof ChargingStationTemplate])) {
 661     if (!isUndefined(key)) {
 662       (template as unknown as Record<string, unknown>)[key!] =
 663         template[deprecatedKey as keyof ChargingStationTemplate];
 664     }
 665     delete template[deprecatedKey as keyof ChargingStationTemplate];
 666   }
 667 };
 668
 669 interface ChargingProfilesLimit {
 670   limit: number;
 671   matchingChargingProfile: ChargingProfile;
 672 }
 673
 674 /**
 675  * Charging profiles shall already be sorted by connector id and stack level (highest stack level has priority)
 676  *
 677  * @param chargingStation -
 678  * @param connectorId -
 679  * @param chargingProfiles -
 680  * @param logPrefix -
 681  * @returns ChargingProfilesLimit
 682  */
 683 const getLimitFromChargingProfiles = (
 684   chargingStation: ChargingStation,
 685   connectorId: number,
 686   chargingProfiles: ChargingProfile[],
 687   logPrefix: string,
 688 ): ChargingProfilesLimit | undefined => {
 689   const debugLogMsg = `${logPrefix} ${moduleName}.getLimitFromChargingProfiles: Matching charging profile found for power limitation: %j`;
 690   const currentDate = new Date();
 691   const connectorStatus = chargingStation.getConnectorStatus(connectorId);
 692   for (const chargingProfile of chargingProfiles) {
 693     if (
 694       (isValidDate(chargingProfile.validFrom) &&
 695         isBefore(currentDate, chargingProfile.validFrom!)) ||
 696       (isValidDate(chargingProfile.validTo) && isAfter(currentDate, chargingProfile.validTo!))
 697     ) {
 698       logger.debug(
 699         `${logPrefix} ${moduleName}.getLimitFromChargingProfiles: Charging profile id ${
 700           chargingProfile.chargingProfileId
 701         } is not valid for the current date ${currentDate.toISOString()}`,
 702       );
 703       continue;
 704     }
 705     const chargingSchedule = chargingProfile.chargingSchedule;
 706     if (connectorStatus?.transactionStarted && !chargingSchedule?.startSchedule) {
 707       logger.debug(
 708         `${logPrefix} ${moduleName}.getLimitFromChargingProfiles: startSchedule is not defined in charging profile id ${chargingProfile.chargingProfileId}. Trying to set it to the connector transaction start date`,
 709       );
 710       // OCPP specifies that if startSchedule is not defined, it should be relative to start of the connector transaction
 711       chargingSchedule.startSchedule = connectorStatus?.transactionStart;
 712     }
 713     if (!(chargingSchedule?.startSchedule instanceof Date)) {
 714       logger.warn(
 715         `${logPrefix} ${moduleName}.getLimitFromChargingProfiles: startSchedule is not a Date object in charging profile id ${chargingProfile.chargingProfileId}. Trying to convert it to a Date object`,
 716       );
 717       chargingSchedule.startSchedule = convertToDate(chargingSchedule?.startSchedule)!;
 718     }
 719     if (
 720       chargingProfile.chargingProfileKind === ChargingProfileKindType.RECURRING &&
 721       isNullOrUndefined(chargingProfile.recurrencyKind)
 722     ) {
 723       logger.error(
 724         `${logPrefix} ${moduleName}.getLimitFromChargingProfiles: Recurring charging profile id ${chargingProfile.chargingProfileId} has no recurrencyKind defined`,
 725       );
 726       continue;
 727     }
 728     if (chargingProfile.chargingProfileKind === ChargingProfileKindType.RECURRING) {
 729       prepareRecurringChargingProfile(chargingProfile, currentDate, logPrefix);
 730     } else if (
 731       chargingProfile.chargingProfileKind === ChargingProfileKindType.RELATIVE &&
 732       connectorStatus?.transactionStarted
 733     ) {
 734       chargingSchedule.startSchedule = connectorStatus?.transactionStart;
 735     }
 736     if (isNullOrUndefined(chargingSchedule?.duration)) {
 737       logger.error(
 738         `${logPrefix} ${moduleName}.getLimitFromChargingProfiles: Charging profile id ${chargingProfile.chargingProfileId} has no duration defined, not yet supported`,
 739       );
 740       continue;
 741     }
 742     // Check if the charging profile is active
 743     if (
 744       isValidDate(chargingSchedule?.startSchedule) &&
 745       isWithinInterval(currentDate, {
 746         start: chargingSchedule.startSchedule!,
 747         end: addSeconds(chargingSchedule.startSchedule!, chargingSchedule.duration!),
 748       })
 749     ) {
 750       if (isNotEmptyArray(chargingSchedule.chargingSchedulePeriod)) {
 751         const chargingSchedulePeriodCompareFn = (
 752           a: ChargingSchedulePeriod,
 753           b: ChargingSchedulePeriod,
 754         ) => a.startPeriod - b.startPeriod;
 755         if (
 756           isArraySorted<ChargingSchedulePeriod>(
 757             chargingSchedule.chargingSchedulePeriod,
 758             chargingSchedulePeriodCompareFn,
 759           ) === false
 760         ) {
 761           logger.warn(
 762             `${logPrefix} ${moduleName}.getLimitFromChargingProfiles: Charging profile id ${chargingProfile.chargingProfileId} schedule periods are not sorted by start period`,
 763           );
 764           chargingSchedule.chargingSchedulePeriod.sort(chargingSchedulePeriodCompareFn);
 765         }
 766         // Check if the first schedule period start period is equal to 0
 767         if (chargingSchedule.chargingSchedulePeriod[0].startPeriod !== 0) {
 768           logger.error(
 769             `${logPrefix} ${moduleName}.getLimitFromChargingProfiles: Charging profile id ${chargingProfile.chargingProfileId} first schedule period start period ${chargingSchedule.chargingSchedulePeriod[0].startPeriod} is not equal to 0`,
 770           );
 771           continue;
 772         }
 773         // Handle only one schedule period
 774         if (chargingSchedule.chargingSchedulePeriod.length === 1) {
 775           const result: ChargingProfilesLimit = {
 776             limit: chargingSchedule.chargingSchedulePeriod[0].limit,
 777             matchingChargingProfile: chargingProfile,
 778           };
 779           logger.debug(debugLogMsg, result);
 780           return result;
 781         }
 782         let lastButOneSchedule: ChargingSchedulePeriod | undefined;
 783         // Search for the right schedule period
 784         for (const [index, schedulePeriod] of chargingSchedule.chargingSchedulePeriod.entries()) {
 785           // Find the right schedule period
 786           if (
 787             isAfter(
 788               addSeconds(chargingSchedule.startSchedule!, schedulePeriod.startPeriod),
 789               currentDate,
 790             )
 791           ) {
 792             // Found the schedule period: last but one is the correct one
 793             const result: ChargingProfilesLimit = {
 794               limit: lastButOneSchedule!.limit,
 795               matchingChargingProfile: chargingProfile,
 796             };
 797             logger.debug(debugLogMsg, result);
 798             return result;
 799           }
 800           // Keep it
 801           lastButOneSchedule = schedulePeriod;
 802           // Handle the last schedule period within the charging profile duration
 803           if (
 804             index === chargingSchedule.chargingSchedulePeriod.length - 1 ||
 805             (index < chargingSchedule.chargingSchedulePeriod.length - 1 &&
 806               chargingSchedule.duration! >
 807                 differenceInSeconds(
 808                   addSeconds(
 809                     chargingSchedule.startSchedule!,
 810                     chargingSchedule.chargingSchedulePeriod[index + 1].startPeriod,
 811                   ),
 812                   chargingSchedule.startSchedule!,
 813                 ))
 814           ) {
 815             const result: ChargingProfilesLimit = {
 816               limit: lastButOneSchedule.limit,
 817               matchingChargingProfile: chargingProfile,
 818             };
 819             logger.debug(debugLogMsg, result);
 820             return result;
 821           }
 822         }
 823       }
 824     }
 825   }
 826 };
 827
 828 /**
 829  * Adjust recurring charging profile startSchedule to the current recurrency time interval if needed
 830  *
 831  * @param chargingProfile -
 832  * @param currentDate -
 833  * @param logPrefix -
 834  */
 835 const prepareRecurringChargingProfile = (
 836   chargingProfile: ChargingProfile,
 837   currentDate: Date,
 838   logPrefix: string,
 839 ) => {
 840   const chargingSchedule = chargingProfile.chargingSchedule;
 841   let recurringInterval: Interval;
 842   switch (chargingProfile.recurrencyKind) {
 843     case RecurrencyKindType.DAILY:
 844       recurringInterval = {
 845         start: chargingSchedule.startSchedule!,
 846         end: addDays(chargingSchedule.startSchedule!, 1),
 847       };
 848       checkRecurringChargingProfileDuration(chargingProfile, recurringInterval, logPrefix);
 849       if (
 850         !isWithinInterval(currentDate, recurringInterval) &&
 851         isBefore(recurringInterval.end, currentDate)
 852       ) {
 853         chargingSchedule.startSchedule = addDays(
 854           recurringInterval.start,
 855           differenceInDays(currentDate, recurringInterval.start),
 856         );
 857         recurringInterval = {
 858           start: chargingSchedule.startSchedule,
 859           end: addDays(chargingSchedule.startSchedule, 1),
 860         };
 861       }
 862       break;
 863     case RecurrencyKindType.WEEKLY:
 864       recurringInterval = {
 865         start: chargingSchedule.startSchedule!,
 866         end: addWeeks(chargingSchedule.startSchedule!, 1),
 867       };
 868       checkRecurringChargingProfileDuration(chargingProfile, recurringInterval, logPrefix);
 869       if (
 870         !isWithinInterval(currentDate, recurringInterval) &&
 871         isBefore(recurringInterval.end, currentDate)
 872       ) {
 873         chargingSchedule.startSchedule = addWeeks(
 874           recurringInterval.start,
 875           differenceInWeeks(currentDate, recurringInterval.start),
 876         );
 877         recurringInterval = {
 878           start: chargingSchedule.startSchedule,
 879           end: addWeeks(chargingSchedule.startSchedule, 1),
 880         };
 881       }
 882       break;
 883   }
 884   if (!isWithinInterval(currentDate, recurringInterval!)) {
 885     logger.error(
 886       `${logPrefix} ${moduleName}.prepareRecurringChargingProfile: Recurring ${
 887         chargingProfile.recurrencyKind
 888       } charging profile id ${chargingProfile.chargingProfileId} recurrency time interval [${toDate(
 889         recurringInterval!.start,
 890       ).toISOString()}, ${toDate(
 891         recurringInterval!.end,
 892       ).toISOString()}] is not properly translated to current date ${currentDate.toISOString()} `,
 893     );
 894   }
 895 };
 896
 897 const checkRecurringChargingProfileDuration = (
 898   chargingProfile: ChargingProfile,
 899   interval: Interval,
 900   logPrefix: string,
 901 ) => {
 902   if (isNullOrUndefined(chargingProfile.chargingSchedule.duration)) {
 903     logger.warn(
 904       `${logPrefix} ${moduleName}.checkRecurringChargingProfileDuration: Recurring ${
 905         chargingProfile.chargingProfileKind
 906       } charging profile id ${
 907         chargingProfile.chargingProfileId
 908       } duration is not defined, set it to the recurrency time interval duration ${differenceInSeconds(
 909         interval.end,
 910         interval.start,
 911       )}`,
 912     );
 913     chargingProfile.chargingSchedule.duration = differenceInSeconds(interval.end, interval.start);
 914   } else if (
 915     chargingProfile.chargingSchedule.duration! > differenceInSeconds(interval.end, interval.start)
 916   ) {
 917     logger.warn(
 918       `${logPrefix} ${moduleName}.checkRecurringChargingProfileDuration: Recurring ${
 919         chargingProfile.chargingProfileKind
 920       } charging profile id ${chargingProfile.chargingProfileId} duration ${
 921         chargingProfile.chargingSchedule.duration
 922       } is greater than the recurrency time interval duration ${differenceInSeconds(
 923         interval.end,
 924         interval.start,
 925       )}`,
 926     );
 927     chargingProfile.chargingSchedule.duration = differenceInSeconds(interval.end, interval.start);
 928   }
 929 };
 930
 931 const getRandomSerialNumberSuffix = (params?: {
 932   randomBytesLength?: number;
 933   upperCase?: boolean;
 934 }): string => {
 935   const randomSerialNumberSuffix = randomBytes(params?.randomBytesLength ?? 16).toString('hex');
 936   if (params?.upperCase) {
 937     return randomSerialNumberSuffix.toUpperCase();
 938   }
 939   return randomSerialNumberSuffix;
 940 };