Adding environment setup and instructions

2025-07-22 14:04:27 -05:00
parent 311981ceb4
commit dc2885e02e
23 changed files with 3741 additions and 114 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,211 @@
+## 🐳 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`
+