diff --git a/FIRMWARE_UPLOAD.md b/FIRMWARE_UPLOAD.md new file mode 100644 index 0000000..545a71a --- /dev/null +++ b/FIRMWARE_UPLOAD.md @@ -0,0 +1,280 @@ +# Firmware Upload Guide + +This guide explains how to upload firmware to your ESP32Focuser microcontroller. + +## Prerequisites + +Before uploading firmware, ensure you have the following: + +### Hardware Requirements +- ESP32 development board (as used in the ESP32Focuser hardware) +- USB cable (typically USB-A to Micro-USB or USB-C, depending on your board) +- Computer with USB port + +### Software Requirements +- **USB to UART Bridge Driver**: CP210x driver from [Silicon Labs](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers) + - Windows usually installs this automatically + - Linux and macOS typically have built-in support + +## Method 1: Using PlatformIO (Recommended for Developers) + +PlatformIO is the recommended method if you want to build from source or make modifications. + +### Installation + +1. **Install Visual Studio Code** + - Download from [https://code.visualstudio.com/](https://code.visualstudio.com/) + +2. **Install PlatformIO IDE Extension** + - Open VS Code + - Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X) + - Search for "PlatformIO IDE" + - Click Install + +### Uploading Firmware + +1. **Clone or Download the Repository** + ```bash + git clone https://github.com/simonachmueller/ESP32Focuser.git + cd ESP32Focuser + ``` + +2. **Open Project in VS Code** + - Open VS Code + - File → Open Folder + - Select the ESP32Focuser directory + +3. **Connect Your ESP32** + - Connect your ESP32 board to your computer via USB + - The board should be recognized as a serial port + +4. **Configure Upload Port (if needed)** + - Edit `platformio.ini` and update the `upload_port` line: + - **Windows**: `COM3`, `COM4`, etc. + - **Linux**: `/dev/ttyUSB0`, `/dev/ttyUSB1`, etc. + - **macOS**: `/dev/cu.usbserial-*` or `/dev/cu.SLAB_USBtoUART` + + You can also let PlatformIO auto-detect the port by commenting out or removing the `upload_port` line. + +5. **Build and Upload** + - Click the PlatformIO icon in the left sidebar + - Click "Upload" under "PROJECT TASKS" → "esp32dev" + - Or use the shortcut: Press Ctrl+Alt+U (Cmd+Alt+U on macOS) + - Or use the command line: + ```bash + platformio run --target upload + ``` + +6. **Monitor Serial Output (Optional)** + - Click "Monitor" under "PROJECT TASKS" → "esp32dev" + - Or press Ctrl+Alt+S (Cmd+Alt+S on macOS) + - Or use the command line: + ```bash + platformio device monitor + ``` + +## Method 2: Using esptool.py (For Pre-built Binaries) + +This method is useful when you have a pre-built firmware binary (e.g., from GitHub releases). + +### Installation + +1. **Install Python** (if not already installed) + - Download from [https://www.python.org/downloads/](https://www.python.org/downloads/) + - Make sure to check "Add Python to PATH" during installation + +2. **Install esptool** + ```bash + pip install esptool + ``` + +### Downloading Firmware + +1. **From GitHub Releases** + - Visit [https://github.com/simonachmueller/ESP32Focuser/releases](https://github.com/simonachmueller/ESP32Focuser/releases) + - Download the latest `firmware.bin` file + +2. **From GitHub Actions Artifacts** + - Go to [https://github.com/simonachmueller/ESP32Focuser/actions](https://github.com/simonachmueller/ESP32Focuser/actions) + - Click on the latest successful workflow run + - Download the `firmware.bin` artifact + - Extract the zip file to get `firmware.bin` + +### Uploading Firmware + +1. **Connect Your ESP32** + - Connect your ESP32 board via USB + +2. **Find the Serial Port** + - **Windows**: Check Device Manager → Ports (COM & LPT) + - **Linux**: Run `ls /dev/ttyUSB*` or `ls /dev/ttyACM*` + - **macOS**: Run `ls /dev/cu.*` + +3. **Upload the Firmware** + + Replace `` with your serial port (e.g., `COM3`, `/dev/ttyUSB0`, `/dev/cu.SLAB_USBtoUART`): + + ```bash + esptool.py --chip esp32 --port --baud 460800 write_flash -z 0x10000 firmware.bin + ``` + + Example for Windows: + ```bash + esptool.py --chip esp32 --port COM3 --baud 460800 write_flash -z 0x10000 firmware.bin + ``` + + Example for Linux/macOS: + ```bash + esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash -z 0x10000 firmware.bin + ``` + +4. **Wait for Upload to Complete** + - The process typically takes 10-30 seconds + - You'll see progress indicators during the upload + +## Method 3: Using Arduino IDE (Alternative Method) + +If you prefer Arduino IDE: + +### Installation + +1. **Install Arduino IDE** + - Download from [https://www.arduino.cc/en/software](https://www.arduino.cc/en/software) + +2. **Add ESP32 Board Support** + - Open Arduino IDE + - File → Preferences + - Add to "Additional Board Manager URLs": + ``` + https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json + ``` + - Tools → Board → Boards Manager + - Search for "esp32" + - Install "esp32 by Espressif Systems" + +3. **Install Required Libraries** + - Tools → Manage Libraries + - Search and install: "ESP32Encoder" + +### Uploading Firmware + +1. **Open the Project** + - Open `src/main.cpp` in Arduino IDE + +2. **Configure Board Settings** + - Tools → Board → ESP32 Arduino → ESP32 Dev Module + - Tools → Port → Select your ESP32's port + - Tools → Upload Speed → 115200 + +3. **Upload** + - Click the Upload button (→) or press Ctrl+U + - Wait for the upload to complete + +## Troubleshooting + +### Device Not Detected + +**Problem**: Computer doesn't recognize the ESP32 board. + +**Solutions**: +- Install or reinstall the CP210x USB to UART bridge driver +- Try a different USB cable (some cables are power-only) +- Try a different USB port +- Press and hold the BOOT button on the ESP32 while connecting + +### Upload Fails / Timeout Errors + +**Problem**: Upload starts but fails with timeout or connection errors. + +**Solutions**: +1. **Put ESP32 in Download Mode**: + - Hold the BOOT button + - Press and release the EN (reset) button + - Release the BOOT button + - Try uploading again + +2. **Reduce Upload Speed**: + - For PlatformIO, add to `platformio.ini`: + ```ini + upload_speed = 115200 + ``` + - For esptool, change `--baud 460800` to `--baud 115200` + +3. **Check Port Access** (Linux/macOS): + - Add your user to the dialout group: + ```bash + sudo usermod -a -G dialout $USER + ``` + - Log out and log back in + - Or use sudo: `sudo esptool.py ...` + +### Wrong Port Selected + +**Problem**: Cannot find the correct serial port. + +**Solutions**: +- Disconnect the ESP32, note available ports +- Reconnect the ESP32, check which new port appears +- On Linux, check `dmesg | tail` after connecting +- On Windows, check Device Manager → Ports (COM & LPT) + +### Permission Denied (Linux/macOS) + +**Problem**: Permission errors when accessing the serial port. + +**Solutions**: +```bash +# Add user to dialout group +sudo usermod -a -G dialout $USER + +# Or change port permissions temporarily +sudo chmod 666 /dev/ttyUSB0 +``` + +### Out of Memory or Flash Errors + +**Problem**: Flash operation fails with memory errors. + +**Solutions**: +- Erase the flash completely first: + ```bash + esptool.py --chip esp32 --port erase_flash + ``` +- Then try uploading again + +## Verifying the Upload + +After uploading, verify the firmware is running: + +1. **Check Serial Output** + - Open a serial monitor at 115200 baud + - You should see output from the focuser + + Using PlatformIO: + ```bash + platformio device monitor -b 115200 + ``` + + Using screen (Linux/macOS): + ```bash + screen /dev/ttyUSB0 115200 + ``` + +2. **Test Focuser Connection** + - Follow the installation instructions in the main README.md + - Connect using MoonLite software or ASCOM driver + - Test basic focuser movements + +## Additional Resources + +- **PlatformIO Documentation**: [https://docs.platformio.org/](https://docs.platformio.org/) +- **ESP32 Documentation**: [https://docs.espressif.com/projects/esp-idf/en/latest/esp32/](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/) +- **esptool Documentation**: [https://github.com/espressif/esptool](https://github.com/espressif/esptool) +- **Hardware Repository**: [https://github.com/simonachmueller/ESP32Focuser-hardware](https://github.com/simonachmueller/ESP32Focuser-hardware) + +## Getting Help + +If you encounter issues not covered in this guide: +- Check the [Issues](https://github.com/simonachmueller/ESP32Focuser/issues) page +- Open a new issue with details about your problem +- Include your operating system, board type, and error messages diff --git a/README.md b/README.md index 1770627..e818d5e 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,13 @@ This is a port of an awesome code from https://github.com/Hansastro/Focuser to E # Hardware If you want to build a focuser controller by yourself, please check out a hardware repository https://github.com/simonachmueller/ESP32Focuser-hardware +# Firmware Upload +To upload firmware to your ESP32 microcontroller, see the detailed [Firmware Upload Guide](FIRMWARE_UPLOAD.md). The guide covers multiple upload methods including: +- Using PlatformIO (recommended for developers) +- Using esptool.py for pre-built binaries +- Using Arduino IDE +- Troubleshooting common issues + # Installation for computer-controlled use ## Windows 1. Install CP210x driver from https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers if not installed automatically by windows itself