soundshot/README.md

🐳 ESP-IDF Dockerized Development Environment (Windows)

This project includes a fully containerized ESP-IDF 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

   • Enable WSL 2 backend during installation.

2. Visual Studio Code

3. Dev Containers Extension

   • In VS Code: Extensions → Search "Dev Containers" → Install

4. Espressif IDF Extension for VS Code

   • In VS Code: Extensions → Search "ESP-IDF" → Install

💡 Optional (recommended): Install WSL 2 with Ubuntu for improved Linux compatibility inside Docker.

---

🚀 Getting Started

1. Clone this repository

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:

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:

  idf.py --version
  

  to confirm ESP-IDF is active and available.

---

5. Build the Firmware

Inside the container’s terminal:

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)

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:

{
  "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):

build/
├── bootloader/bootloader.bin
├── soundshot.bin                ← ← ← (project_name)
├── partition_table/partition-table.bin

Run the flash tool:

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:

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