polymech/firmware-base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
809d3d2219
firmware-base/scripts/README-upload.md

4.7 KiB
Raw Blame History

ESP32-S3 Upload Scripts (Windows)

Upload firmware and LittleFS without PlatformIO dependency.

Prerequisites

Install required tools:

# Install esptool
pip install esptool pyserial

# Optional: Download mklittlefs.exe for LittleFS support
# From: https://github.com/earlephilhower/mklittlefs/releases

Quick Start

1. Complete Upload (Default - Recommended)

# Build everything first
npm run build
npm run web:build-dist && npm run web:sync && npm run web:uploadfs

# Upload firmware + LittleFS (default behavior)
scripts/upload-all.sh            # Linux/macOS
scripts\upload-all.bat           # Windows

2. Firmware Only Upload

# Build firmware first (requires PlatformIO)
npm run build

# Upload firmware only (skip LittleFS)
scripts/upload-all.sh --firmware-only      # Linux/macOS
scripts\upload-all.bat --firmware-only     # Windows

3. Upload LittleFS Only

# Upload LittleFS filesystem only
scripts/upload-littlefs.sh --auto    # Linux/macOS
scripts\upload-littlefs.bat --auto   # Windows

Advanced Usage

Complete Upload (Main Scripts)

# Upload everything (firmware + LittleFS) - DEFAULT
scripts/upload-all.sh

# Upload firmware only (skip LittleFS)
scripts/upload-all.sh --firmware-only

# Specify environment
scripts/upload-all.sh --env waveshare-release

# Specify port
scripts/upload-all.sh --port COM17

# All options
scripts/upload-all.sh --env waveshare-release --port COM17

# Windows equivalent
scripts\upload-all.bat --env waveshare-release --port COM17

Upload Firmware (Python - Advanced)

# Auto-detect all files (recommended)
python scripts/upload_firmware.py --auto

# With specific environment
python scripts/upload_firmware.py --auto --env waveshare-release

# With specific port
python scripts/upload_firmware.py --port COM17 --auto

# Manual file specification
python scripts/upload_firmware.py \
  --firmware .pio/build/waveshare/firmware.bin \
  --bootloader .pio/build/waveshare/bootloader.bin \
  --partitions .pio/build/waveshare/partitions.bin \
  --boot-app0 ~/.platformio/packages/framework-arduinoespressif32/tools/partitions/boot_app0.bin

Upload LittleFS (Standalone Scripts)

# Upload PlatformIO-built LittleFS (recommended)
scripts/upload-littlefs.sh --auto
scripts\upload-littlefs.bat --auto

# Specify environment
scripts/upload-littlefs.sh --auto --env waveshare-release

# Specify port
scripts/upload-littlefs.sh --auto --port COM17

Upload LittleFS (Python - Advanced)

# Auto-detect PlatformIO-built LittleFS
python scripts/upload_littlefs.py --auto

# Build and upload from data/ directory
python scripts/upload_littlefs.py --data-dir data

# Upload existing image
python scripts/upload_littlefs.py --image littlefs.bin

# Build only (no upload)
python scripts/upload_littlefs.py --data-dir data --build-only

# Custom flash address and size
python scripts/upload_littlefs.py \
  --data-dir data \
  --address 6750208 \
  --size 1572864

Alternative Options

Option 1: ESP32 Flash Download Tools (GUI)

Option 2: espflash (Rust-based)

# Install via cargo
cargo install espflash

# Upload firmware
espflash flash --chip esp32s3 firmware.bin

# Upload filesystem
espflash write-bin 0x670000 littlefs.bin

Option 3: Custom esptool commands

# Erase flash
python -m esptool --chip esp32s3 --port COM17 erase_flash

# Upload complete firmware (matches PlatformIO)
python -m esptool --chip esp32s3 --port COM17 --baud 115200 \
  write_flash -z --flash_mode dio --flash_freq 80m --flash_size 8MB \
  0x0000 bootloader.bin \
  0x8000 partitions.bin \
  0xe000 boot_app0.bin \
  0x10000 firmware.bin

# Upload LittleFS  
python -m esptool --chip esp32s3 --port COM17 --baud 115200 \
  write_flash -z --flash_mode dio --flash_freq 80m --flash_size 8MB \
  0x670000 littlefs.bin

Flash Memory Map (ESP32-S3)

Address Size Content
0x0000 0x8000 Bootloader
0x8000 0x6000 Partition Table
0xe000 0x2000 boot_app0
0x10000 0x660000 Firmware
0x670000 0x180000 LittleFS

Troubleshooting

Port Detection Issues

# List available ports
python -c "import serial.tools.list_ports; [print(f'{p.device}: {p.description}') for p in serial.tools.list_ports.comports()]"

Permission Issues

  • Run as Administrator if needed
  • Close other serial monitors (Arduino IDE, PlatformIO)

mklittlefs.exe Not Found

  • Install PlatformIO: pip install platformio
  • Or download manually from GitHub releases
  • Place in PATH or scripts/ directory