212 lines
4.7 KiB
Markdown
212 lines
4.7 KiB
Markdown
## 🐳 ESP-IDF Dockerized Development Environment (Windows)
|
||
|
||
This project includes a fully containerized [ESP-IDF](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/index.html) development environment using **Docker** and **Visual Studio Code**.
|
||
|
||
Follow these instructions to set up, build, and flash the firmware inside a VS Code **Dev Container** on **Windows**.
|
||
|
||
---
|
||
|
||
### ✅ Prerequisites
|
||
Ensure the following are installed on your system:
|
||
|
||
1. [**Docker Desktop for Windows**](https://www.docker.com/products/docker-desktop)
|
||
|
||
* Enable **WSL 2 backend** during installation.
|
||
2. [**Visual Studio Code**](https://code.visualstudio.com/)
|
||
3. [**Dev Containers Extension**](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
|
||
|
||
* In VS Code: `Extensions → Search "Dev Containers" → Install`
|
||
4. [**Espressif IDF Extension** for VS Code](https://marketplace.visualstudio.com/items?itemName=espressif.esp-idf-extension)
|
||
|
||
* In VS Code: `Extensions → Search "ESP-IDF" → Install`
|
||
|
||
> 💡 **Optional (recommended):** Install [WSL 2 with Ubuntu](https://learn.microsoft.com/en-us/windows/wsl/install) for improved Linux compatibility inside Docker.
|
||
|
||
---
|
||
|
||
### 🚀 Getting Started
|
||
|
||
#### 1. Clone this repository
|
||
|
||
```bash
|
||
git clone https://git.sparksoftdesign.com/firstpass/soundshot.git
|
||
cd soundshot
|
||
```
|
||
---
|
||
You can also clone with TortoiseGit or VS Code directly.
|
||
#### 2. Open in Visual Studio Code
|
||
|
||
From the project root:
|
||
|
||
```bash
|
||
code .
|
||
```
|
||
|
||
> Ensure you're opening the folder that contains `.devcontainer/`.
|
||
|
||
---
|
||
|
||
#### 3. Reopen in Dev Container
|
||
|
||
In VS Code:
|
||
|
||
* Press `F1` or `Ctrl+Shift+P`
|
||
* Run: **Dev Containers: Reopen in Container**
|
||
|
||
VS Code will:
|
||
|
||
* Build the Docker image (based on the provided `Dockerfile`)
|
||
* Set up the ESP-IDF environment
|
||
* Install extensions automatically
|
||
|
||
---
|
||
|
||
#### 4. Verify Environment
|
||
|
||
Once setup is complete:
|
||
|
||
* A terminal should launch inside the container
|
||
* Run:
|
||
|
||
```bash
|
||
idf.py --version
|
||
```
|
||
|
||
to confirm ESP-IDF is active and available.
|
||
|
||
---
|
||
|
||
#### 5. Build the Firmware
|
||
|
||
Inside the container’s terminal:
|
||
|
||
```bash
|
||
idf.py build
|
||
```
|
||
|
||
You should see standard ESP-IDF build output and a `.bin` firmware file in the `build/` directory.
|
||
|
||
---
|
||
|
||
## 🛠️ ESP32 Programming Setup & Workflow Guide
|
||
|
||
This project provides a fully portable development and flashing toolchain for ESP32, using Python scripts and configuration-driven workflows.
|
||
|
||
---
|
||
|
||
### 📦 1. Environment Setup
|
||
|
||
> Run once after cloning the repo (Windows only)
|
||
|
||
```bash
|
||
setup-env.bat
|
||
```
|
||
|
||
This:
|
||
|
||
* Creates a `.venv` virtual environment
|
||
* Installs required Python packages (`esptool`, `pyserial`, etc.)
|
||
* Prepares the tooling for flashing and monitoring
|
||
|
||
---
|
||
|
||
### ⚙️ 2. Configure `settings.json`
|
||
|
||
Customize `settings.json` in the project root:
|
||
|
||
```json
|
||
{
|
||
"project_name": "soundshot",
|
||
"chip": "esp32",
|
||
"port": "COM3",
|
||
"baud": 460800,
|
||
"flash_mode": "dio",
|
||
"flash_freq": "48m",
|
||
"flash_size": "2MB",
|
||
"before": "default-reset",
|
||
"after": "hard-reset"
|
||
}
|
||
```
|
||
|
||
This controls:
|
||
|
||
* Flashing chip type and parameters
|
||
* Serial monitor settings
|
||
* Build artifact naming
|
||
|
||
---
|
||
|
||
### 🚀 3. Flashing the Firmware
|
||
|
||
After building your firmware (e.g. via VS Code + Dev Container):
|
||
|
||
```bash
|
||
build/
|
||
├── bootloader/bootloader.bin
|
||
├── soundshot.bin ← ← ← (project_name)
|
||
├── partition_table/partition-table.bin
|
||
```
|
||
|
||
Run the flash tool:
|
||
|
||
```bash
|
||
flash.bat
|
||
```
|
||
|
||
This:
|
||
|
||
* Loads `settings.json`
|
||
* Verifies all required binaries
|
||
* Calls `esptool.py` with all correct arguments and offsets
|
||
|
||
---
|
||
|
||
### 🛰 4. Monitoring Serial Output
|
||
|
||
To view device output:
|
||
|
||
```bash
|
||
monitor.bat
|
||
```
|
||
|
||
Features:
|
||
|
||
* Uses `pyserial`
|
||
* Displays real-time output from the ESP32
|
||
* Preserves color formatting (if enabled in firmware)
|
||
* Cleanly exits with `Ctrl+C` (no "Terminate batch job" prompts)
|
||
|
||
> Tip: Run `idf.py menuconfig` and enable
|
||
> `Component config → Log output → Enable color log output`
|
||
|
||
---
|
||
|
||
### ✅ Workflow Summary
|
||
|
||
| Action | Tool | Command |
|
||
| ------------------ | ------------------- | ----------------- |
|
||
| Install tooling | `setup-env.bat` | `setup-env.bat` |
|
||
| Flash device | `flash.py` script | `flash.bat` |
|
||
| Monitor logs | `monitor.py` script | `monitor.bat` |
|
||
| Configure behavior | `settings.json` | *(edit manually)* |
|
||
|
||
|
||
---
|
||
|
||
### 🧰 Notes
|
||
|
||
* The ESP-IDF version is pinned in the Dockerfile (e.g., `espressif/idf:v5.2.1`)
|
||
* The container automatically runs `source $IDF_PATH/export.sh` to prepare the environment.
|
||
* VS Code extensions (`.devcontainer.json`) include:
|
||
|
||
* `ms-vscode.cpptools`
|
||
* `ms-vscode.cmake-tools`
|
||
* `espressif.esp-idf-extension`
|
||
|
||
---
|
||
|
||
### 🛠 Troubleshooting
|
||
|
||
* If `idf.py` is not found, make sure the container terminal sources `export.sh`
|
||
|