## 🐳 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`