cariflex/tools/EVerest-main/modules/HardwareDrivers/PowerSupplies/Winline

Winline Power Supply Driver

Driver module for Winline power supplies supporting the Winline CAN protocol. This module can control multiple Winline modules 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 Winline-specific CAN protocol messages, enabling seamless integration of Winline hardware into EVerest-based charging systems.

Key Integration Points:

• Implements: power_supply_DC interface for standardized power supply control
• Communicates: Via CAN bus using Winline 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 Winline modules simultaneously with current sharing
• Dual Operating Modes: Fixed address mode or automatic group discovery mode
• Comprehensive Error Handling: Maps all Winline errors to standardized power_supply_DC framework errors
• Serial Number Identification: Uses register-based serial number reading for unique device identification
• Thread-Safe Operation: Robust concurrent access protection for telemetry data
• Automatic Recovery: Detects and recovers from offline modules automatically
• Enhanced Status Monitoring: Comprehensive status tracking and trend analysis
• Power State Verification: Verifies power commands with actual module status

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 module settings
module_addresses: ""       # Must be empty for group discovery

# Optional settings
device_connection_timeout_s: 15    # Module offline timeout
conversion_efficiency_export: 0.95 # Power conversion efficiency
controller_address: 240            # CAN controller address
power_state_grace_period_ms: 2000  # Grace period for power state verification
altitude_setting_m: 1000           # Working altitude in meters
input_mode: "AC"                   # Input mode: "AC" or "DC"
module_current_limit_point: 1.0    # Current limit multiplier

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
device_connection_timeout_s	integer	15	Module offline timeout
conversion_efficiency_export	number	0.95	Power conversion efficiency (0.0-1.0)
controller_address	integer	240	CAN controller address
power_state_grace_period_ms	integer	2000	Grace period for power state verification
altitude_setting_m	integer	1000	Working altitude in meters
input_mode	string	"AC"	Input mode: "AC" or "DC"
module_current_limit_point	number	1.0	Current limit multiplier

Operating Modes

1. Fixed Address Mode (Recommended)

Use when you know the exact addresses of your Winline 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 module group setting

Advantages:

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

Requirements:

• Module group settings must match group_address
• 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: Winline 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)
Bits 21-16: Command Number (6 bits)
Bits 15-8:  Destination Address (8 bits)
Bits 7-0:   Source Address (8 bits) - Controller address

Key Registers Used

Register	Address	Description	Usage
Voltage	0x0001	Read output voltage	Regular telemetry
Current	0x0002	Read output current	Regular telemetry
Status	0x0003	Read status flags	Error monitoring
Rated Power	0x0004	Read rated output power	Capability detection
Rated Current	0x0005	Read rated output current	Capability detection
Serial Low	0x0054	Read serial number (low)	Device identification
Serial High	0x0055	Read serial number (high)	Device identification
Group Info	0x0043	Read group information	Group discovery
Set Voltage	0x0021	Set output voltage	Control
Set Current	0x001B	Set output current	Control
Power Control	0x001A	Enable/disable module	Control

Communication Flow

Initialization

1. Discovery (Group mode): Send Group Info request to detect modules
2. Capabilities: Read max voltage/current/power from each module
3. Serial Numbers: Read serial number registers for device identification
4. Configuration: Set altitude, input mode, and current limit point
5. 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
5. Power Verification: Verify power commands with actual module status

Error Handling

Error Mapping

Winline errors are automatically mapped to standardized power_supply_DC errors:

Winline 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
• Automatic Recovery: Attempts automatic recovery for overvoltage and short circuit faults

Logging Format

Error messages follow standardized format for easy identification:

Winline[0x00/SN_12345678]: Module fault alarm activated
Winline[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

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
• Module group settings not matching
• Modules not ready during discovery

Solutions:

• Verify module group 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:
  Winline: debug

Monitor CAN traffic:

# Raw CAN monitoring
candump can0

# With timestamp
candump -t z can0

# Filter Winline 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: Multiple Winline modules + 1 controller

Module Configuration

• Set module addresses or group settings before powering on
• Ensure all modules use same firmware version
• Configure appropriate current/voltage limits
• Set correct altitude and input mode

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: Winline 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
• 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 register constants in CanPackets.hpp
2. Implement packet structures in CanPackets.cpp
3. Add command handling in WinlineCanDevice::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

• EVerest power_supply_DC Interface - Standardized interface documentation
• Linux SocketCAN Documentation - CAN bus programming guide

Hardware Compatibility

Supported Winline Models

• Protocol Version: Winline protocol and compatible versions
• Module Types: Various Winline power supply modules

Manufacturer Information

• Manufacturer: Winline
• Protocol Version: Winline protocol V1.50 (this driver implementation)

Note: Ensure your Winline modules support the protocol version used by this driver. Older protocol versions may not be fully compatible.