Added README, slowed step time

2025-07-09 11:18:55 -06:00
parent 2febf4f902
commit 4b14a2af5f
2 changed files with 381 additions and 1 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,380 @@
+# Maxxfan Smart Controller
+
+A WiFi-enabled smart controller for the Maxxfan Deluxe 6401K using ESP32 and BTS7960 motor driver. Transform your manual RV fan into a remotely controllable smart device with variable speed control, bidirectional operation, and smooth motor ramping.
+
+## 🌟 Features
+
+- **WiFi Remote Control** - Control your fan from anywhere on your network
+- **Variable Speed Control** - 0-100% speed adjustment via web interface
+- **Bidirectional Operation** - Switch between exhaust and intake modes
+- **Smooth Motor Ramping** - Gradual speed changes prevent mechanical stress
+- **Real-time Status** - Live updates of fan mode, current speed, and target speed
+- **Ramping Visualization** - See when speed changes are in progress
+- **Mobile-Friendly Interface** - Responsive web design works on phones and tablets
+- **Enhanced Error Handling** - Visual connection status and error messages
+- **CORS Support** - Cross-origin requests properly handled
+- **Compact Design** - Optimized for ESP32 memory constraints
+- **Connection Status** - Shows "Connected", "Connecting", or "Error" status
+- **REST API** - Enhanced JSON API for integration with home automation systems
+- **Watchdog Protection** - Automatic system recovery from crashes
+- **Homebridge Compatible** - Easy integration with HomeKit
+
+## 🔧 Hardware Requirements
+
+### Main Components
+- **ESP32 Development Board** (tested with SparkFun ESP32 Thing Plus)
+- **BTS7960 Motor Driver Module** (43A high-power motor driver)
+- **Maxxfan Deluxe 6401K** (or compatible 12V DC fan)
+- **12V Power Supply** (adequate for your fan's current draw)
+
+### Wiring Connections
+
+```
+ESP32 GPIO → BTS7960 Pin
+GPIO 18    → R_EN (Right Enable)
+GPIO 19    → L_EN (Left Enable) 
+GPIO 21    → R_PWM (Right PWM)
+GPIO 22    → L_PWM (Left PWM)
+GPIO 13    → LED (Status Indicator)
+3.3V       → VCC (Logic Power)
+GND        → GND
+
+BTS7960 → Fan Motor
+B+         → Fan Positive
+B-         → Fan Negative
+
+Power Supply
+12V        → BTS7960 Motor Power + Fan Power Input
+GND        → Common Ground
+```
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Docker installed on Ubuntu (recommended) or Mac
+- ESP32 connected via USB
+- WiFi network credentials
+
+### 1. Set Up Development Environment
+
+```bash
+# Create project directory
+mkdir ~/maxxfan-controller
+cd ~/maxxfan-controller
+
+# Pull official ESP-IDF Docker image (v5.x recommended)
+docker pull espressif/idf:latest
+
+# Create new ESP-IDF project
+docker run --rm -v $PWD:/project -w /project -it espressif/idf:latest
+idf.py create-project maxxfan-controller
+exit
+```
+
+### 2. Configure WiFi Credentials
+
+Edit the WiFi credentials in `main/maxxfan-controller.c`:
+
+```c
+#define WIFI_SSID "YOUR_WIFI_NAME"
+#define WIFI_PASS "YOUR_WIFI_PASSWORD"
+```
+
+### 3. Build and Flash
+
+```bash
+cd maxxfan-controller
+
+# Build
+docker run --rm -v $PWD:/project -w /project -it espressif/idf:latest idf.py build
+
+# Flash (replace /dev/ttyUSB0 with your device)
+docker run --rm -v $PWD:/project -w /project --device=/dev/ttyUSB0 -it espressif/idf:latest idf.py flash -p /dev/ttyUSB0
+
+# Monitor serial output
+docker run --rm -v $PWD:/project -w /project --device=/dev/ttyUSB0 -it espressif/idf:latest idf.py monitor -p /dev/ttyUSB0
+```
+
+### 4. Access Web Interface
+
+1. Note the IP address from serial monitor output:
+   ```
+   I (xxx) HTTP_MOTOR: got ip:192.168.1.123
+   ```
+
+2. Open your browser and navigate to: `http://192.168.1.123`
+
+## 🌐 Enhanced Web Interface
+
+The improved web interface provides:
+
+- **Real-time Status Display** - Current fan mode, speed, and target speed
+- **Ramping Indicator** - Visual feedback when speed changes are in progress
+- **Quick Controls** - One-click buttons for common operations
+- **Speed Slider** - Precise speed adjustment (0-100%)
+- **Real-time Updates** - Status refreshes every 1 second for live ramping visualization
+- **Error Handling** - Visual connection status and network error feedback
+- **Persistent State** - Settings maintained across page reloads
+- **Memory Optimized** - Compact HTML (~2KB) ensures reliable loading
+
+### Controls Available
+
+- **Turn OFF** - Stops the fan completely
+- **Exhaust (50%)** - Sets exhaust mode at 50% speed with smooth ramping
+- **Intake (50%)** - Sets intake mode at 50% speed with smooth ramping
+- **Custom Speed** - Use slider + "Set Exhaust/Intake Speed" buttons
+
+### Motor Ramping Features
+
+- **Smooth Startup** - Motors start at minimum speed (10%) then ramp to target
+- **Gradual Changes** - Speed changes in 5% increments every 50ms
+- **Direction Changes** - Proper sequencing prevents mechanical stress
+- **Visual Feedback** - Ramping indicator shows when changes are in progress
+
+## 📡 Enhanced REST API
+
+### Get Status
+```bash
+GET /status
+```
+Enhanced Response:
+```json
+{
+  "mode": "exhaust",
+  "current_speed": 65,
+  "target_speed": 80,
+  "ramping": true
+}
+```
+
+### Control Fan
+```bash
+POST /fan
+Content-Type: application/json
+
+{
+  "mode": "exhaust",  // "off", "exhaust", or "intake"
+  "speed": 75         // 0-100
+}
+```
+
+### Example cURL Commands
+```bash
+# Turn fan off (immediate stop)
+curl -X POST http://192.168.1.123/fan -H "Content-Type: application/json" -d '{"mode":"off","speed":0}'
+
+# Set exhaust mode at 80% (with ramping)
+curl -X POST http://192.168.1.123/fan -H "Content-Type: application/json" -d '{"mode":"exhaust","speed":80}'
+
+# Set intake mode at 60% (with ramping)
+curl -X POST http://192.168.1.123/fan -H "Content-Type: application/json" -d '{"mode":"intake","speed":60}'
+
+# Get current status (includes ramping state)
+curl http://192.168.1.123/status
+```
+
+## 🏠 Homebridge Integration
+
+Add to your Homebridge `config.json`:
+
+```json
+{
+  "accessories": [
+    {
+      "accessory": "HTTP-FAN",
+      "name": "Maxxfan",
+      "getUrl": "http://192.168.1.123/status",
+      "setUrl": "http://192.168.1.123/fan",
+      "on": {
+        "setOn": "http://192.168.1.123/fan",
+        "setOff": "http://192.168.1.123/fan"
+      },
+      "speed": {
+        "setSpeed": "http://192.168.1.123/fan"
+      }
+    },
+    {
+      "accessory": "HTTP-SWITCH",
+      "name": "Maxxfan Direction",
+      "getUrl": "http://192.168.1.123/status",
+      "setUrl": "http://192.168.1.123/fan",
+      "mapOn": "intake",
+      "mapOff": "exhaust"
+    }
+  ]
+}
+```
+
+Requires: `npm install -g homebridge-http-accessory`
+
+## 🔧 Technical Details
+
+### Enhanced Motor Control Logic
+
+The BTS7960 is a dual H-bridge motor driver with improved control sequencing:
+
+- **Exhaust Mode**: R_EN=HIGH, L_EN=LOW, PWM on R_PWM pin
+- **Intake Mode**: R_EN=LOW, L_EN=HIGH, PWM on L_PWM pin  
+- **Off Mode**: Both enables LOW, PWM stopped
+- **Ramping**: Gradual speed changes using FreeRTOS timers
+
+### Motor Ramping Configuration
+```c
+#define RAMP_STEP_MS 50          // Time between ramp steps (50ms)
+#define RAMP_STEP_SIZE 5         // PWM duty change per step (~2% speed)
+#define MIN_MOTOR_SPEED 10       // Minimum speed to overcome inertia
+```
+
+### PWM Configuration
+- **Frequency**: 1kHz (optimal for motor control)
+- **Resolution**: 8-bit (256 levels of speed control)
+- **Speed Range**: 0-100% mapped to 0-255 PWM duty cycle
+
+### Memory Optimization
+The web interface HTML has been optimized to ~2KB (down from ~8KB) to ensure:
+- Complete page loading without truncation
+- Reliable JavaScript execution
+- Proper function definitions and event handling
+- Stable operation on ESP32's limited memory
+
+### Safety & Reliability Features
+- **Watchdog Timer**: Automatic system recovery from crashes
+- **Enable Sequencing**: Enable pins activated before PWM signals
+- **Direction Switching**: Proper delays prevent shoot-through current
+- **Error Handling**: Robust JSON parsing and HTTP error responses
+- **CORS Headers**: Cross-origin support for web integrations
+- **Compact HTML**: Optimized web interface for ESP32 memory constraints
+- **Real-time Updates**: 1-second polling for live status updates
+- **Visual Feedback**: Connection status and ramping progress indicators
+
+## 🛠️ Development
+
+### Project Structure
+```
+maxxfan-controller/
+├── main/
+│   ├── maxxfan-controller.c    # Enhanced application code
+│   └── CMakeLists.txt          # Build configuration
+├── CMakeLists.txt              # Project configuration
+└── sdkconfig                   # ESP-IDF configuration
+```
+
+### Key Components
+- **GPIO Control**: Direct hardware pin management
+- **LEDC PWM**: Hardware PWM generation for speed control
+- **FreeRTOS Timers**: Motor ramping control
+- **Task Watchdog**: System reliability monitoring
+- **WiFi Station**: Connect to existing network
+- **HTTP Server**: Built-in ESP-IDF web server with CORS support
+- **JSON Parsing**: cJSON library for enhanced API requests
+
+### Building from Source
+
+The project uses ESP-IDF v5.x with these main dependencies:
+- `driver/gpio.h` - GPIO control
+- `driver/ledc.h` - PWM generation  
+- `esp_http_server.h` - Web server
+- `esp_task_wdt.h` - Watchdog timer
+- `freertos/timers.h` - Motor ramping timers
+- `cJSON.h` - JSON parsing
+- `esp_wifi.h` - WiFi connectivity
+
+## 📋 Troubleshooting
+
+### Common Boot Messages (Normal)
+```
+W (501) spi_flash: Detected size(16384k) larger than the size in the binary image header(2048k)
+```
+This warning is normal - your ESP32 has more flash than the project uses.
+
+### WiFi Connection Issues
+- Verify SSID and password in code
+- Check 2.4GHz network (ESP32 doesn't support 5GHz)
+- Monitor serial output for connection status
+
+### Motor Not Responding
+- Check all wiring connections
+- Verify 12V power supply to BTS7960
+- Ensure common ground between ESP32 and motor circuit
+- Test with multimeter on enable pins (should show 3.3V when active)
+- Check for ramping messages in serial output
+
+### Web Interface Issues
+- Confirm IP address from serial monitor
+- Check browser developer console (F12) for JavaScript errors
+- Look for CORS or network errors
+- Try different browser or incognito mode
+
+### JavaScript Console Errors
+If you see "Unexpected end of script" or "Can't find variable" errors:
+- These indicate HTML truncation due to memory constraints
+- The current compact HTML should resolve these issues
+- Check browser developer console (F12) for specific errors
+- Verify complete page load by viewing page source
+- If errors persist, try clearing browser cache and refreshing
+
+### Connection Status Issues
+If the web interface shows "Connection Error":
+- Check that ESP32 is connected to WiFi (serial monitor should show IP)
+- Verify you're accessing the correct IP address
+- Check that both devices are on the same network
+- Try accessing `/status` endpoint directly: `http://[ESP32_IP]/status`
+- Look for CORS-related errors in browser console
+
+### Watchdog Timer Messages
+If you see watchdog errors, check:
+- Main loop is running (should see periodic status updates)
+- No infinite loops in code
+- Adequate task stack sizes
+
+### Serial Port Issues (Ubuntu)
+```bash
+# Add user to dialout group
+sudo usermod -a -G dialout $USER
+
+# Check available ports
+ls /dev/tty* | grep -E "(USB|ACM)"
+
+# Fix permissions if needed
+sudo chmod 666 /dev/ttyUSB0
+```
+
+### Flash Size Warning Fix (Optional)
+To use full 16MB flash and eliminate warning:
+```bash
+idf.py menuconfig
+# Navigate to: Serial flasher config → Flash size → 16MB
+```
+
+## 🔒 Security Considerations
+
+### Current Implementation
+- **Open Access**: No authentication required
+- **Local Network Only**: Not accessible from internet
+- **HTTP Only**: Unencrypted communication
+- **CORS Enabled**: Allows cross-origin requests
+
+### Recommended Improvements for Production
+- **Network Isolation**: Use dedicated IoT VLAN
+- **Basic Authentication**: Add username/password protection
+- **HTTPS**: Enable SSL/TLS encryption
+- **Firewall Rules**: Restrict access to specific devices
+
+## 📄 License
+
+This project is open source. Use at your own risk. Always follow electrical safety practices when working with 12V systems.
+
+## 🤝 Contributing
+
+Feel free to submit issues, feature requests, or pull requests to improve this project.
+
+## ⚠️ Disclaimer
+
+This project involves working with electrical systems and motor control. Always:
+- Follow proper electrical safety practices
+- Use appropriate fuses and circuit protection
+- Test thoroughly before permanent installation
+- Ensure adequate ventilation and mounting
+- Check local electrical codes and regulations
+
+The authors are not responsible for any damage or injury resulting from the use of this project.
--- a/main/maxxfan-controller.c
+++ b/main/maxxfan-controller.c
@ -34,7 +34,7 @@
 #define PWM_L_CHANNEL LEDC_CHANNEL_1

 // Motor ramping configuration
-#define RAMP_STEP_MS 50          // Time between ramp steps (milliseconds)
+#define RAMP_STEP_MS 150          // Time between ramp steps (milliseconds)
 #define RAMP_STEP_SIZE 5         // PWM duty change per step (0-255)
 #define MIN_MOTOR_SPEED 10       // Minimum speed to overcome motor inertia