cariflex/tools/EVerest-main/modules/HardwareDrivers/PowerSupplies/InfyPower/README.md

InfyPower ACDC Power Supply Driver

Driver module for InfyPower ACDC power supplies supporting the V1.13 CAN protocol. This module can control multiple InfyPower modules (up to 60 modules theoretically, recommended maximum 4-6 devices for reliable operation, typically 2-6 in field installations) using either fixed addressing or automatic group discovery.

Overview

This is an EVerest Hardware Driver module that implements the standardized power_supply_DC interface. It translates EVerest's generic power supply commands into InfyPower-specific CAN protocol messages, enabling seamless integration of InfyPower hardware into EVerest-based charging systems.

Key Integration Points:

• Implements: power_supply_DC interface for standardized power supply control
• Communicates: Via CAN bus using InfyPower V1.13 protocol
• Provides: Voltage/current control, telemetry, error reporting, and capability detection
• Integrates: With EVerest's error management, logging, and configuration systems

Features

• Multi-Module Support: Control multiple InfyPower modules simultaneously with current sharing (up to 60 modules theoretically)
• Dual Operating Modes: Fixed address mode or automatic group discovery mode
• Comprehensive Error Handling: Maps all InfyPower errors to standardized power_supply_DC framework errors
• Serial Number Identification: Uses Command 0x0B barcode reading for unique device identification
• Thread-Safe Operation: Robust concurrent access protection for telemetry data
• Automatic Recovery: Detects and recovers from offline modules automatically

Configuration

Basic Configuration

# Required: CAN interface
can_device: "can0"

# Choose ONE of the following addressing modes:

# Option 1: Fixed Address Mode (recommended for known setups)
module_addresses: "0,1,2"  # Comma-separated list of module addresses

# Option 2: Group Discovery Mode (for automatic allocation)
group_address: 1           # Group number matching PSU dial settings
module_addresses: ""       # Must be empty for group discovery

# Optional settings
device_connection_timeout_s: 10    # Module offline timeout
conversion_efficiency_export: 0.95 # Power conversion efficiency
controller_address: 240            # CAN controller address (0xF0)

Configuration Parameters

Parameter	Type	Default	Description
can_device	string	"can0"	CAN interface name (e.g., "can0", "vcan0")
module_addresses	string	""	Fixed addresses: "0,1,2" or empty for group discovery
group_address	integer	0	Group number for discovery mode (matches PSU dial)
device_connection_timeout_s	integer	15	CRITICAL: Must be > 10s module timeout (see Safety Notes)
conversion_efficiency_export	number	0.95	Power conversion efficiency (0.0-1.0)
controller_address	integer	240	CAN controller address (0xF0 = 240 decimal)

⚠️ Safety Notes

Critical Timeout Configuration

IMPORTANT: The device_connection_timeout_s parameter has critical safety implications and must be configured correctly.

InfyPower Module Internal Timeout

Per InfyPower V1.13 protocol specification: "If the charger module did not receive the message for 10 seconds from the controller, the charger module will off."

This means each module has a 10-second internal timeout and will automatically turn OFF its power output if it doesn't receive CAN messages within this period.

EVerest Driver Timeout Requirement

The EVerest device_connection_timeout_s MUST be longer than the module's internal timeout. Here's why:

❌ DANGEROUS - Driver timeout < Module timeout:

Time: 0s → 8s → 10s → 12s
Driver: ✓ → ✓ → ✗ (removes module from capabilities) → ✗
Module: ✓ → ✓ → ✓ (still delivering power!) → ✗ (finally turns off)

Problem: Driver advertises reduced capability while module still delivers full power → overcurrent risk

✅ SAFE - Driver timeout > Module timeout:

Time: 0s → 8s → 10s → 12s → 15s
Driver: ✓ → ✓ → ✓ (still includes in capabilities) → ✓ → ✗ (removes module)
Module: ✓ → ✓ → ✗ (safely turned off) → ✗ → ✗

Result: Driver keeps module in capabilities until certain it's OFF → no overcurrent risk

Configuration Recommendation

# InfyPower modules have 10s internal timeout (per V1.13 protocol):
device_connection_timeout_s: 15  # Safe default: 15s > 10s module timeout ✓
device_connection_timeout_s: 11  # Minimum safe: 11s > 10s module timeout

# NEVER configure equal to or shorter than module timeout:
device_connection_timeout_s: 10  # DANGEROUS: Equal to module timeout
device_connection_timeout_s: 8   # DANGEROUS: 8s < 10s module timeout

Safety Principle

• Overestimating capabilities is safe: System delivers less than advertised
• Underestimating capabilities is dangerous: Could cause overcurrent conditions
• Always err on the side of longer timeouts for safety

Operating Modes

1. Fixed Address Mode (Recommended)

Use when you know the exact addresses of your InfyPower modules.

Configuration:

module_addresses: "0,1,2"  # List specific module addresses
group_address: 0           # Ignored in this mode

Advantages:

• Predictable, deterministic addressing
• Faster startup (no discovery phase)
• Direct control over which modules are used

Use Cases:

• Production installations with known hardware
• Testing with specific module configurations
• When you need guaranteed addressing consistency

2. Group Discovery Mode

Use when modules are configured for automatic address allocation.

Configuration:

module_addresses: ""       # Must be empty
group_address: 1           # Must match PSU group dial setting

Advantages:

• Automatic module detection
• Hot-plugging support
• Easier setup for dynamic configurations
• Adapts to hardware changes

Requirements:

• PSU dial switches must be set to matching group number
• All modules in group must be powered on during discovery

Use Cases:

• Development and testing environments
• Field installations with variable hardware
• When module addresses may change

CAN Protocol Details

Protocol Specification

• Standard: InfyPower V1.13 CAN Communication Protocol
• Bus Type: CAN 2.0B Extended Frame Format (29-bit identifiers)
• Baud Rate: 125 kbps
• Message Length: 8 bytes (fixed)
• Termination: 120Ω resistors at both ends

CAN ID Structure (29-bit)

Bits 28-26: Error Code (3 bits)
Bits 25-22: Device Number (4 bits) - 0x0A=single, 0x0B=group
Bits 21-16: Command Number (6 bits)
Bits 15-8:  Destination Address (8 bits)
Bits 7-0:   Source Address (8 bits) - Controller address

Key Commands Used

Command	ID	Description	Usage
Module Count	0x02	Get number of modules in group	Group discovery
Module VI	0x03	Read voltage/current	Regular telemetry
Module Status	0x04	Read status flags	Error monitoring
Module Capabilities	0x0A	Read voltage/current/power limits	Capability detection
Module Barcode	0x0B	Read serial number	Device identification
Module VI After Diode	0x0C	Read external voltage/available current	Advanced telemetry
Set Module On/Off	0x1A	Enable/disable module	Control
Set Module VI	0x1C	Set voltage/current	Control

Communication Flow

Initialization

1. Discovery (Group mode): Send Module Count request to detect modules
2. Capabilities: Read max voltage/current/power from each module
3. Serial Numbers: Read barcode for device identification
4. Safety: Ensure all modules start in OFF state

Regular Operation (1-second intervals)

1. Telemetry: Read voltage, current, status from all modules
2. Error Monitoring: Check status flags for alarm conditions
3. Timeout Detection: Remove unresponsive modules from active list
4. Recovery: Automatically re-add modules that come back online

Error Handling

Error Mapping

InfyPower errors are automatically mapped to standardized power_supply_DC errors:

InfyPower Error	power_supply_DC Error	Severity	Description
OverVoltage	OverVoltageDC	High	Output voltage too high
UnderVoltage	UnderVoltageDC	High	Output voltage too low
OverTemperature	OverTemperature	High	Module overheating
OverCurrent	OverCurrentDC	High	Output current too high
InputVoltage	UnderVoltageAC	High	AC input voltage issues
InternalFault	HardwareFault	High	Internal module fault
InputPhaseLoss	VendorError	High	AC phase loss
FanFault	VendorWarning	Medium	Cooling fan failure
CommunicationFault	CommunicationFault	High	Lost communication

Error Recovery

• Individual Module Errors: Other modules continue operating
• Communication Timeout: Modules automatically removed from active list
• Communication Recovery: Modules automatically re-added when responding
• System-Wide Faults: All modules forced off for safety

Logging Format

Error messages follow standardized format for easy identification:

Infy[0x00/SN_130C15A3FB06A8_V]: Module fault alarm activated
Infy[0x01]: Communication fault detected, FORCE mode to off

Current Sharing

When multiple modules are active, current is automatically shared equally:

Example with 3 modules:

• Request: 150A total
• Per-module: 50A each
• Voltage: Same for all modules

Load Balancing:

• Automatic equal current distribution
• Voltage synchronized across all modules
• Individual module limits respected
• Failed modules automatically excluded

Troubleshooting

Common Issues

0. ⚠️ SAFETY: Always check timeout configuration first

Before troubleshooting: Verify device_connection_timeout_s > module internal timeout (see Safety Notes above)

1. No modules detected

Symptoms: "No active modules" warnings Causes:

• CAN interface down: sudo ip link set can0 up type can bitrate 125000
• Wrong CAN device name: Check can_device configuration
• Modules not powered or wrong group setting

Solutions:

# Check CAN interface
ip link show can0

# Bring up CAN interface
sudo ip link set can0 up type can bitrate 125000

# Monitor CAN traffic
candump can0

2. Modules going offline

Symptoms: "module communication expired" messages Causes:

• CAN bus errors or noise
• Loose connections
• Power supply issues

Solutions:

• Check CAN bus termination (120Ω resistors)
• Verify all connections are secure
• Monitor for CAN errors in system logs

3. Current not shared properly

Symptoms: Uneven current distribution Causes:

• Modules have different capabilities
• Some modules in fault state
• Configuration mismatch

Solutions:

• Check module status in logs
• Verify all modules have same specifications
• Check for error conditions

4. Group discovery not working

Symptoms: No modules found in group mode Causes:

• Wrong group_address setting
• PSU dial switches not matching
• Modules not ready during discovery

Solutions:

• Verify PSU dial switch settings match group_address
• Ensure all modules powered on before starting

Debug Information

Enable debug logging to see detailed protocol information:

# In your EVerest configuration
logging:
  InfyPower: debug

Monitor CAN traffic:

# Raw CAN monitoring
candump can0

# With timestamp
candump -t z can0

# Filter InfyPower traffic (controller address 0xF0)
candump can0 | grep F0

Hardware Requirements

CAN Bus Setup

• Topology: Linear bus with 120Ω termination at both ends
• Cable: Twisted pair CAN cable (CAN_H, CAN_L)
• Max Distance: 40m at 125 kbps
• Max Devices: Up to 60 InfyPower modules + 1 controller (typically 2-6 in field installations)

PSU Configuration

• Set module addresses or group dial switches before powering on
• Ensure all modules use same firmware version
• Configure appropriate current/voltage limits

Development Notes

Architecture Constraints (Critical Implementation Details)

Single-Threaded CAN Communication

IMPORTANT: The entire CAN communication system operates in a single thread:

• rx_handler() and poll_status_handler() execute in the same thread
• No concurrent CAN operations - all message processing is sequential
• This design ensures deterministic message handling and eliminates race conditions
• Implication: Blocking operations in handlers affect entire CAN communication

Configuration Immutability

CRITICAL: Configuration is set exactly once during initialization:

• set_config_values() called only once at startup
• No runtime configuration changes supported
• Module addresses and operating mode cannot be changed after initialization
• Implication: Configuration errors require full module restart

Security Model

No CAN Bus Security

IMPORTANT: InfyPower CAN protocol has no built-in security:

• No encryption: All CAN messages transmitted in plain text
• No authentication: No verification of message sender identity
• No message integrity: Only basic CRC provided by CAN hardware
• Physical security required: Secure the CAN bus physically

Message Validation Strategy

Minimal Validation by Design:

• Only validation: Controller address verification (destination_address == controller_address)
• Only malformation check: Message must be exactly 8 bytes
• No payload validation: Content validity checking beyond packet structure
• Rationale: Keep protocol simple and fast for real-time operation

Adding New Commands

1. Define packet structure in CanPackets.hpp
2. Implement constructor and conversion in CanPackets.cpp
3. Add command handling in InfyCanDevice::rx_handler()
4. Add sending method if needed

Thread Safety

• telemetries map: Protected by implicit single-thread access
• active_module_addresses: Protected by active_modules_mutex
• All signals are thread-safe via sigslot library

Testing

• Use vcan0 virtual CAN interface for development
• Mock modules can be simulated with cansend commands
• Unit tests recommended for packet encoding/decoding

References

• InfyPower V1.13 CAN Protocol Documentation - Complete protocol specification
• EVerest power_supply_DC Interface - Standardized interface documentation
• Linux SocketCAN Documentation - CAN bus programming guide

Hardware Compatibility

Supported InfyPower Models

• REG Series: REG1K0100G and compatible models
• CEG Series: CEG1K0100G and compatible models (includes MPPT mode support)
• LRG Series: LRG series charger modules
• Protocol Version: V1.13 and compatible versions

Manufacturer Information

• Manufacturer: Shenzhen Infypower Co., Ltd
• Website: http://www.infypower.com
• Protocol Version: V1.13 (this driver implementation)
• Document Reference: "REG/CEG/LRG series Charger Module CAN Communication Protocol V1.13"

Note: Ensure your InfyPower modules support V1.13 protocol or compatible versions. Older protocol versions may not be fully compatible with this driver.