Error Codes & Handling - EVerest Core

Overview

EVerest Core provides a comprehensive error framework for reporting and handling error conditions. The framework supports:

Structured Errors: Typed error definitions with severity levels
Error History: Persistent error tracking and logging
Error Propagation: Errors propagate through the module tree
Error Recovery: Automatic and manual error clearing
MREC Compliance: Minimum Required Error Codes for ChargeX consortium

Error Framework Architecture

Error Components

Error Definitions: YAML files defining error types
Error Raising: Modules raise errors via the error framework
Error Subscribers: Modules subscribe to error notifications
Error History: Central error logging and tracking
Error Display: User-facing error information

Error Lifecycle

Error Definition Files

Location: errors/ directory Error definitions are YAML files that specify error types:

description: Error description
errors:
  - name: ErrorName
    description: Detailed error description
  - name: AnotherError
    description: Another error description

Available Error Files

EVSE Manager Errors

Source: errors/evse_manager.yamlDescription: Errors for EvseManager. Includes Minimum Required Error Codes (MREC) from ChargeX consortium.Reference: ChargeX MREC Specification

Error List

Internal

error

Internal error of the state machineSeverity: Critical
Recovery: Automatic on state machine reset

MREC4OverCurrentFailure

error

Over current event detectedSeverity: Critical
MREC: Minimum Required Error Code #4
Recovery: Automatic when current returns to normal

MREC5OverVoltage

error

Over voltage event detectedSeverity: Critical
MREC: Minimum Required Error Code #5
Recovery: Automatic when voltage returns to normal

MREC9AuthorizationTimeout

error

No authorization was provided within timeout after pluginSeverity: Warning
MREC: Minimum Required Error Code #9
Recovery: Automatic on new authorization attempt

PowermeterTransactionStartFailed

error

Transaction could not be started at the powermeterSeverity: High
Impact: Cannot start signed metering
Recovery: Manual - check powermeter connection

Inoperative

error

Charging is not possible. Usually caused by another error from one of the requirements.Severity: Critical
Recovery: Automatic when underlying error is cleared

MREC22ResistanceFault

error

An Isolation Monitoring Device tripped due to low resistance to the chassis during active charging.Severity: Critical
MREC: Minimum Required Error Code #22
Recovery: Manual - safety inspection required

MREC11CableCheckFault

error

Cable check failed. Isolation monitor self test failed before charging.Severity: Critical
MREC: Minimum Required Error Code #11
Recovery: Automatic on next plug-in cycle

VoltagePlausibilityFault

error

Voltage plausibility check failed. Standard deviation between voltage measurements from different sources exceeded threshold for configured duration.Severity: High
Recovery: Automatic when measurements align

Generic Errors

Source: errors/generic.yamlDescription: Generic errors used by multiple modules

CommunicationFault

error

Communication with the underlying hardware or device has a faultSeverity: High
Impact: Module cannot communicate with hardware
Recovery: Automatic when communication restored

VendorError

error

Vendor specific error codeSeverity: Variable
Usage: Hardware-specific error conditions
Recovery: Depends on vendor implementation

VendorWarning

warning

Vendor specific warning codeSeverity: Low
Usage: Hardware-specific warning conditions
Recovery: Informational only

Powermeter Errors

Source: errors/powermeter.yamlDescription: Power meter specific errorsCommon powermeter errors include:

Communication failures
Measurement out of range
Calibration errors
Signature verification failures

Board Support Errors

Source: errors/evse_board_support.yamlDescription: EVSE board support package errorsHardware-level errors from board support packages:

PWM generation failures
CP/PP signal errors
RCD (Residual Current Device) trips
Relay failures
Ventilation errors

Connector Lock Errors

Source: errors/connector_lock.yamlDescription: Connector locking mechanism errorsErrors related to physical connector locking:

Lock motor failures
Position sensor errors
Lock timeout
Unlock failures

Isolation Monitor Errors

Source: errors/isolation_monitor.yamlDescription: DC isolation monitoring errorsSafety-critical isolation errors:

Self-test failures
Isolation resistance too low
Device malfunction
Communication errors

Power Supply Errors

Source: errors/power_supply_DC.yamlDescription: DC power supply errorsDC charging power supply errors:

Over temperature
Emergency shutdown
Voltage/current out of range
Communication timeout

System Errors

Source: errors/system.yamlDescription: System-level errorsSystem operation errors:

Firmware update failures
Configuration errors
Storage failures
System resource exhaustion

Other Error Types

Additional error definition files:

errors/ac_rcd.yaml - AC RCD errors
errors/over_voltage_monitor.yaml - Over-voltage protection
errors/payment_terminal.yaml - Payment terminal errors
errors/example.yaml - Example error definitions

Error Severity Levels

Errors have implicit severity based on their impact:

Severity	Impact	Example
Critical	Charging must stop immediately	Over-current, isolation fault
High	Charging cannot start/continue	Powermeter failure, communication fault
Medium	Degraded operation	Single sensor failure with redundancy
Low	Warning only	Informational conditions

Error Interface

Modules interact with errors through the error framework:

Raising Errors

// In module implementation
raise_error("MREC4OverCurrentFailure");

Clearing Errors

// Error cleared automatically when condition resolves
clear_error("MREC4OverCurrentFailure");

Subscribing to Errors

Modules can subscribe to error events:

# In manifest.yaml
requires:
  evse:
    interface: evse_manager

// Subscribe to error events
subscribe_error("evse", [](const Error& error) {
    // Handle error notification
    log_error(error);
});

Error History Interface

Interface: error_history The error history interface provides:

Error Logging: Persistent storage of all errors
Error Retrieval: Query historical errors
Error Statistics: Error frequency and patterns
Error Filtering: Filter by type, severity, time

Using Error History

# In configuration
error_history:
  module: ErrorHistory
  requires:
    error_sources:     # All modules that can raise errors
      - evse_manager
      - powermeter
      - board_support

MREC Compliance

The ChargeX Minimum Required Error Codes (MREC) define standardized error codes for EV charging:

Implemented MRECs

MREC	Name	Description
MREC4	OverCurrentFailure	Over-current protection triggered
MREC5	OverVoltage	Over-voltage protection triggered
MREC9	AuthorizationTimeout	Authorization not received in time
MREC11	CableCheckFault	Pre-charge cable check failed
MREC22	ResistanceFault	Isolation resistance fault during charging

MREC Benefits

Standardization: Consistent error codes across vendors
Interoperability: OCPP error code mapping
User Experience: Clear, standardized error messages
Diagnostics: Simplified troubleshooting

Error Handling Best Practices

For Module Developers

Define Clear Errors: Create descriptive error definitions
Raise Early: Detect and raise errors as soon as conditions are detected
Clear Automatically: Clear errors when conditions resolve
Document Recovery: Specify recovery procedures
Test Error Paths: Test error detection and recovery

Error Definition Guidelines

description: Clear description of error category
errors:
  - name: DescriptiveErrorName        # Use clear, descriptive names
    description: >-                   # Provide detailed description
      Detailed description of what causes this error,
      what the impact is, and how to recover.

Error Naming Conventions

Use PascalCase for error names
Include MREC prefix for standardized codes
Be specific about the fault condition
Examples: MREC4OverCurrentFailure, PowermeterTransactionStartFailed

OCPP Error Integration

Errors integrate with OCPP for remote monitoring:

Error to OCPP Mapping

EVerest Error	OCPP Error Code
MREC4OverCurrentFailure	OverCurrentFailure
MREC5OverVoltage	OverVoltage
MREC22ResistanceFault	GroundFailure
CommunicationFault	OtherError

StatusNotification

Errors trigger OCPP StatusNotification messages:

{
  "status": "Faulted",
  "errorCode": "OverCurrentFailure",
  "info": "MREC4: Over current detected on phase L1",
  "timestamp": "2026-03-04T12:34:56Z"
}

Error Display

Errors can be displayed to users via:

Display Message Interface

Use display_message interface for user notifications:

display_message({
    .message = "Charging stopped: Over current detected",
    .priority = MessagePriority::AlwaysFront,
    .state = MessageState::Faulted
});

LED Indicators

Hardware BSP modules can map errors to LED patterns:

Red solid: Critical error (over-current, isolation fault)
Red blinking: High severity error (communication fault)
Yellow: Medium severity warning

Debugging Errors

Error Logging

Enable debug logging for error framework:

# In config
logging:
  error_framework: debug

Error History Query

Query error history for diagnostics:

// Get last 100 errors
auto errors = error_history.get_errors(100);

for (const auto& error : errors) {
    std::cout << error.timestamp << ": " 
              << error.type << " - " 
              << error.message << std::endl;
}

Common Error Scenarios

Authorization Timeout

Error: MREC9AuthorizationTimeoutCause: EV plugged in but no authorization received within timeoutResolution:

Check auth token provider (RFID reader, autocharge)
Verify connection timeout configuration
Check authorization backend connectivity

Powermeter Communication

Error: CommunicationFault (from powermeter)Cause: Cannot communicate with power meterResolution:

Check serial/Modbus connection
Verify baud rate and settings
Check cable connections
Verify power meter is powered on

Isolation Fault

Error: MREC22ResistanceFaultCause: DC isolation resistance too lowResolution:

CRITICAL SAFETY ISSUE
Stop charging immediately (automatic)
Inspect vehicle and cable for damage
Check isolation monitor device
May require professional inspection

Next Steps

Review Interface Reference for error-related interfaces
Explore Module Development to implement error handling
Check EVSE Manager for session error flows
Study source error YAML files in errors/ directory

Reference

​Overview

​Error Framework Architecture

​Error Components

​Error Lifecycle

​Error Definition Files

​Available Error Files

​Error List

​Error Severity Levels

​Error Interface

​Raising Errors

​Clearing Errors

​Subscribing to Errors

​Error History Interface

​Using Error History

​MREC Compliance

​Implemented MRECs

​MREC Benefits

​Error Handling Best Practices

​For Module Developers

​Error Definition Guidelines

​Error Naming Conventions

​OCPP Error Integration

​Error to OCPP Mapping

​StatusNotification

​Error Display

​Display Message Interface

​LED Indicators

​Debugging Errors

​Error Logging

​Error History Query

​Common Error Scenarios

​Next Steps

Build docs developers (and LLMs) love

Overview

Error Framework Architecture

Error Components

Error Lifecycle

Error Definition Files

Available Error Files

Error List

Error Severity Levels

Error Interface

Raising Errors

Clearing Errors

Subscribing to Errors

Error History Interface

Using Error History

MREC Compliance

Implemented MRECs

MREC Benefits

Error Handling Best Practices

For Module Developers

Error Definition Guidelines

Error Naming Conventions

OCPP Error Integration

Error to OCPP Mapping

StatusNotification

Error Display

Display Message Interface

LED Indicators

Debugging Errors

Error Logging

Error History Query

Common Error Scenarios

Next Steps