Add dual proportional flow valve configuration support with hardware jumper selection

LifeTrac-v25/CHANGELOG_FLOW_VALVES.md

@@ -0,0 +1,258 @@
+# LifeTrac v25 - Flow Valve Configuration Feature
+
+## Overview
+
+Added support for two different proportional flow valve configurations to the LifeTrac v25:
+- **Option 1 (Default)**: Single valve controls all hydraulics
+- **Option 2 (Advanced)**: Dual valves for independent left/right control
+
+This feature addresses the need for more advanced maneuvering capabilities while maintaining backward compatibility with existing single valve systems.
+
+## Changes Made
+
+### Code Changes (`arduino_opta_controller/lifetrac_v25_controller.ino`)
+
+#### 1. New Pin Definitions
+- Added `FLOW_CONTROL_PIN_1` (O2) - Primary flow valve (replaces old FLOW_CONTROL_PIN)
+- Added `FLOW_CONTROL_PIN_2` (O3) - Secondary flow valve for dual valve configuration
+- Added `FLOW_CONFIG_JUMPER_PIN` (D11) - Jumper detection for configuration selection
+
+#### 2. New Configuration System
+- Added `FlowValveConfig` enum with `ONE_VALVE` and `TWO_VALVES` modes
+- Added `flowConfig` global variable (defaults to `ONE_VALVE`)
+- Added `readFlowValveConfig()` function to detect jumper at startup
+
+#### 3. Modified Functions
+
+**`setup()`:**
+- Added initialization of D11 as INPUT_PULLUP for jumper detection
+- Added initialization of O3 analog output for second flow valve
+- Added call to `readFlowValveConfig()` before mode switch detection
+
+**`setFlowControl()`:**
+- Complete rewrite to support both configurations
+- **Single valve mode**: Uses minimum non-zero absolute value of all joystick inputs (flow limiting strategy)
+- **Dual valve mode**: 
+  - Calculates actual left and right track speeds
+  - Valve 1 flow based on: left track speed + arms
+  - Valve 2 flow based on: right track speed + bucket
+  - Enables independent speed control for advanced maneuvering
+
+**`stopAllMovement()`:**
+- Updated to stop both flow valves (set both O2 and O3 to 4mA)
+
+#### 4. Header Comments
+- Updated hardware list to show "1-2x Proportional Flow Control Valves (configurable)"
+- Added flow valve configuration documentation to file header
+
+### Documentation Changes
+
+#### 1. New Files
+- **FLOW_VALVE_CONFIGURATION.md** (12KB): Comprehensive guide covering:
+  - Hardware configuration and wiring
+  - Control behavior differences
+  - Installation instructions for both configurations
+  - Detailed example scenarios
+  - Hydraulic circuit modifications
+  - Additional hardware requirements
+  - Advantages/disadvantages comparison
+  - Troubleshooting guide
+  - Testing procedures
+  - Safety considerations
+
+- **QUICK_REFERENCE_FLOW_VALVES.md** (2KB): Quick reference for:
+  - Decision guide (which configuration to choose)
+  - Quick setup steps
+  - Hardware jumper location diagram
+  - Quick troubleshooting
+  - Cost comparison
+
+- **CHANGELOG_FLOW_VALVES.md** (this file): Complete change summary
+
+#### 2. Updated Files
+
+**README.md:**
+- Added "Configurable Flow Control" to features list
+- Updated hardware BOM to show "1-2x" flow control valves
+- Added reference to FLOW_VALVE_CONFIGURATION.md in documentation section
+
+**WIRING_DIAGRAM.md:**
+- Added D11 to Digital I/O Extension connections table
+- Added flow valve configuration jumper logic description
+- Split Analog Extension section into two diagrams:
+  - Single Valve Configuration (default)
+  - Dual Valve Configuration (jumper installed)
+- Added clear indication of which outputs are used in each mode
+
+## Hardware Requirements
+
+### Base Configuration (Single Valve - Default)
+- Arduino Opta WiFi
+- Arduino Pro Opta Ext D1608S (Digital I/O extension)
+- Arduino Pro Opta Ext A0602 (Analog extension)
+- 1x Brand Hydraulics EFC Proportional Flow Control Valve
+- 1x Burkert 8605 Type 316532 Flow Valve Controller
+
+### Advanced Configuration (Dual Valve)
+**Additional hardware needed:**
+- 1x Additional Brand Hydraulics EFC Proportional Flow Control Valve
+- 1x Additional Burkert 8605 Type 316532 Flow Valve Controller
+- Hydraulic flow splitter
+- Additional hydraulic distribution manifold
+- 1x Jumper wire or 2.54mm jumper (to connect D11 to GND)
+- Additional hydraulic hoses and fittings
+
+**Estimated additional cost:** $1000-1500 USD
+
+## Configuration Selection
+
+### Default (Single Valve)
+- Leave D11 pin disconnected (no jumper)
+- System reads D11=HIGH (internal pullup)
+- Controller operates in ONE_VALVE mode
+- Serial output: "ONE_VALVE (Single valve for all)"
+
+### Advanced (Dual Valve)
+- Install jumper connecting D11 to GND
+- System reads D11=LOW
+- Controller operates in TWO_VALVES mode
+- Serial output: "TWO_VALVES (Valve 1: left+arms, Valve 2: right+bucket)"
+
+## Behavior Differences
+
+### Single Valve Mode
+- All hydraulic functions (left track, right track, arms, bucket) share one flow rate
+- Flow rate determined by the minimum non-zero joystick input across all axes
+- Simple turning: can drive forward on one side while stopping the other
+- Speed limited by the lowest non-zero demand movement
+- Adequate for most operations
+
+### Dual Valve Mode
+- Independent flow rates for left side (left track + arms) and right side (right track + bucket)
+- Each side can operate at different speeds simultaneously
+- Advanced turning capabilities:
+  - Variable-radius turns with smooth speed differential
+  - Zero-radius turning (spin in place with tracks running opposite directions)
+  - More precise maneuvering in tight spaces
+- Better control for complex movements
+
+### Example: Zero-Radius Turn
+This demonstrates the key advantage of dual valve mode:
+
+**Joystick Input:** Left Y=0, Left X=1.0 (full right turn, no forward/backward)
+
+**Single Valve Mode:**
+- Left track: forward at full speed
+- Right track: backward at full speed
+- But: Both limited by single flow valve at 20mA
+- Result: Spin in place, but flow may be insufficient for both tracks
+
+**Dual Valve Mode:**
+- Left track: forward at full speed (Valve 1: 20mA)
+- Right track: backward at full speed (Valve 2: 20mA)
+- Independent flow valves provide full flow to each side
+- Result: Smooth, powerful zero-radius turn
+
+## Backward Compatibility
+
+✅ **Fully backward compatible** with existing single valve installations:
+- Default configuration is ONE_VALVE mode (no jumper required)
+- Single valve systems work exactly as before
+- No code changes required for existing installations
+- Simply upload new firmware to get configuration capability
+
+## Testing Status
+
+⚠️ **Hardware testing required**
+- Code changes are complete and syntactically correct
+- Logic has been verified
+- Requires testing on actual hardware:
+  - Single valve configuration (default)
+  - Dual valve configuration (with jumper)
+  - Mode switching between configurations
+  - Flow valve response verification
+  - Maneuvering capability testing
+
+## Migration Guide
+
+### For Existing Single Valve Systems
+1. Upload new firmware to Arduino Opta
+2. No hardware changes needed
+3. System will automatically detect ONE_VALVE configuration
+4. Verify serial output shows correct configuration
+5. Test system operation (should be identical to before)
+
+### To Upgrade to Dual Valve System
+1. Install second Brand Hydraulics EFC valve and Burkert controller
+2. Wire second controller to Arduino Opta O3 output
+3. Modify hydraulic circuit to split flow:
+   - Valve 1 → Left track + Arms
+   - Valve 2 → Right track + Bucket
+4. Install jumper connecting D11 to GND on Arduino Opta
+5. Power on system
+6. Verify serial output shows "TWO_VALVES" configuration
+7. Test all movements and turning capabilities
+
+## Safety Notes
+
+⚠️ **Important Safety Considerations:**
+- Test new configuration in safe, open area
+- Start with slow movements to verify correct operation
+- Ensure all personnel are clear during testing
+- Have emergency stop readily accessible
+- Consult qualified hydraulic technician for installation
+- Zero-radius turning in dual valve mode is powerful - use with caution
+- Follow all manufacturer safety guidelines
+
+## Future Enhancements
+
+Possible future improvements:
+- Add flow rate adjustment via MQTT/BLE commands
+- Implement different control modes (tank steering vs direct wheel control)
+- Add flow rate status reporting
+- Support for more than two valves
+- Configurable valve groupings
+
+## Technical Details
+
+### Pin Usage
+| Pin | Function | Single Valve | Dual Valve |
+|-----|----------|--------------|------------|
+| D11 | Config Jumper | HIGH (no jumper) | LOW (jumper to GND) |
+| O2 | Flow Valve 1 | Active (all hydraulics) | Active (left + arms) |
+| O3 | Flow Valve 2 | Inactive (4mA) | Active (right + bucket) |
+
+### Flow Control Ranges
+- No input: 4 mA (no flow)
+- Minimum movement: 6 mA (~12.5% flow)
+- Half input: 12 mA (50% flow)
+- Maximum input: 20 mA (100% flow)
+
+### Startup Sequence
+1. Initialize hardware pins
+2. Wait 1 second for stabilization
+3. Read D11 jumper state → determine flow configuration
+4. Read D9 mode switch → determine control mode (BLE/MQTT)
+5. Initialize appropriate services
+6. Begin normal operation
+
+## References
+
+- **Issue**: Different Proportional Flow Valve Options
+- **Pull Request**: [Link to be added]
+- **Documentation**: 
+  - FLOW_VALVE_CONFIGURATION.md (comprehensive guide)
+  - QUICK_REFERENCE_FLOW_VALVES.md (quick reference)
+  - WIRING_DIAGRAM.md (updated with dual valve wiring)
+
+## Contributors
+
+- Implementation: GitHub Copilot
+- Issue Reporter: [Original issue author]
+- Testing: [To be added after hardware testing]
+
+---
+
+**Version:** 1.0  
+**Date:** 2024  
+**Status:** Code complete, hardware testing pending