soundshot/README.md

<<<<<<< HEAD

🐳 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

=======

Supported Targets	ESP32

A2DP-SOURCE EXAMPLE

Example of A2DP audio source role

This is the example of using Advanced Audio Distribution Profile (A2DP) APIs to transmit audio stream. Application can take advantage of this example to implement portable audio players or microphones to transmit audio stream to A2DP sink devices.

How to use this example

Hardware Required

This example is able to run on any commonly available ESP32 development board, and is supposed to connect to A2DP sink example in ESP-IDF.

Configure the project

idf.py menuconfig

• Enable Classic Bluetooth and A2DP under Component config --> Bluetooth --> Bluedroid Enable

Build and Flash

Build the project and flash it to the board, then run monitor tool to view serial output.

idf.py -p PORT flash monitor

(Replace PORT with the name of the serial port to use.)

(To exit the serial monitor, type Ctrl-].)

See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.

Example Output

For the first step, this example performs device discovery to search for a target device (A2DP sink) whose device name is "ESP_SPEAKER" and whose "Rendering" bit of its Service Class field is set in its Class of Device (COD). If a candidate target is found, the local device will initiate connection with it.

After connection with A2DP sink is established, the example performs the following running loop 1-2-3-4-1:

1. audio transmission starts and lasts for a while
2. audio transmission stops
3. disconnect with target device
4. reconnect to target device

The example implements an event loop triggered by a periodic "heart beat" timer and events from Bluetooth protocol stack callback functions.

After the local device discovers the target device and initiates connection, there will be logging message like this:

I (4090) BT_AV: Found a target device, address xx:xx:xx:xx:xx:xx, name ESP_SPEAKER
I (4090) BT_AV: Cancel device discovery ...
I (4100) BT_AV: Device discovery stopped.
I (4100) BT_AV: a2dp connecting to peer: ESP_SPEAKER

If connection is set up successfully, there will be such message:

I (5100) BT_AV: a2dp connected

Starting of audio transmission has the following notification message:

I (10880) BT_AV: a2dp media ready checking ...
...
I (10880) BT_AV: a2dp media ready, starting ...
...
I (11400) BT_AV: a2dp media start successfully.

Stop of audio transmission, and disconnection with remote device generate the following notification message:

I (110880) BT_AV: a2dp media stopping...
...
I (110920) BT_AV: a2dp media stopped successfully, disconnecting...
...
I (111040) BT_AV: a2dp disconnected

Troubleshooting

• For current stage, the supported audio codec in ESP32 A2DP is SBC. SBC audio stream is encoded from PCM data normally formatted as 44.1kHz sampling rate, two-channel 16-bit sample data.
• The raw PCM media stream in the example is generated by a sequence of random number, so the sound played on the sink side will be piercing noise.
• As a usage limitation, ESP32 A2DP source can support at most one connection with remote A2DP sink devices. Also, A2DP source cannot be used together with A2DP sink at the same time, but can be used with other profiles such as SPP and HFP.
• Usually, the ACL_CONN_NUM is set to 2 but not 1 as one is used for a2dp connection and the other is used for avrcp connection.

4feb4c0a98