142 lines
3.8 KiB
Markdown
142 lines
3.8 KiB
Markdown
Perfect! Below is the updated `README.md` section with **complete instructions** for setting up the Dockerized ESP-IDF environment on **Windows**, **including installation of the official Espressif VS Code extension**.
|
||
|
||
You can paste this into your repo’s `README.md`. It’s ready to go and designed to guide teammates or collaborators through cloning, launching, and building the project with confidence.
|
||
|
||
---
|
||
|
||
## 🐳 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://github.com/your-username/your-esp-idf-project.git
|
||
cd your-esp-idf-project
|
||
```
|
||
|
||
---
|
||
|
||
#### 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.
|
||
|
||
---
|
||
|
||
### 🔌 Flashing the ESP32 (Optional)
|
||
|
||
If you want to flash from inside the container:
|
||
|
||
1. Connect your ESP32 via USB.
|
||
2. Identify the COM port on Windows (e.g., `COM3`).
|
||
3. Pass the USB device into the container (this may require configuration).
|
||
4. Then run:
|
||
|
||
```bash
|
||
idf.py -p COM3 flash monitor
|
||
```
|
||
|
||
> ⚠️ **Note:** Docker Desktop for Windows doesn’t always expose serial ports to containers directly. You can build firmware inside the container and flash it from your host as a fallback.
|
||
|
||
---
|
||
|
||
### 🧰 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`
|
||
* If USB flashing fails, flash from host or use WSL serial forwarding tools like `socat` or `usbip`
|
||
|
||
---
|
||
|
||
Would you like this `README.md` version to be packaged with:
|
||
|
||
* A **starter repo structure**
|
||
* A prebuilt `.devcontainer/` directory
|
||
* A sample `Dockerfile`, `main.c`, and `CMakeLists.txt`?
|
||
|
||
If yes, I can bundle that up for you — just say the word.
|