From 4b14a2af5f23dc854aac890a6759b511df2af790 Mon Sep 17 00:00:00 2001 From: Stephen Minakian Date: Wed, 9 Jul 2025 11:18:55 -0600 Subject: [PATCH] Added README, slowed step time --- README.md | 380 ++++++++++++++++++++++++++++++++++++++ main/maxxfan-controller.c | 2 +- 2 files changed, 381 insertions(+), 1 deletion(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4a29cb2 --- /dev/null +++ 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. \ No newline at end of file diff --git a/main/maxxfan-controller.c b/main/maxxfan-controller.c index 5cbf04f..da2b92c 100755 --- 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