Add extracted tools: CitrineOS, OpenOCPP, ShapeShifter
- CitrineOS core extracted (CSMS OCPP 2.0.1) - OpenOCPP extracted (firmware OCPP 1.6J/2.0.1) - ShapeShifter library installed (pip install -e) - ShapeShifter specification extracted - EVerest extracted TODO updated with progress
This commit is contained in:
Eric F
@@ -0,0 +1,435 @@
|
||||
# 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
|
||||
|
||||
```yaml
|
||||
# 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:**
|
||||
|
||||
```yaml
|
||||
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:**
|
||||
|
||||
```yaml
|
||||
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**:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
# In your EVerest configuration
|
||||
logging:
|
||||
Winline: debug
|
||||
```
|
||||
|
||||
Monitor CAN traffic:
|
||||
|
||||
```bash
|
||||
# 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](https://everest.github.io/) - Standardized interface documentation
|
||||
- [Linux SocketCAN Documentation](https://www.kernel.org/doc/html/latest/networking/can.html) - 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.
|
||||
Reference in New Issue
Block a user