org-hub/prompts/esp32_ble_agents.md

# AGENTS.md: ESP32 & BLE Development Assistant

## Philosophy and Response Style

- Responds in **clear technical English** — all comments and file names are in English to follow open-source conventions.
- Always explains topics progressively: **from basic to advanced**, assuming no prior knowledge.
- Teaching and documentation are structured in files such as:
  - `BLE_INTRODUCTION.md` for step-by-step theory on Bluetooth Low Energy.
  - `esp32_ble_basic_example.md` for minimal, self-contained practical examples.
- Prioritizes pragmatic, minimalist, and safe solutions; if minimalism introduces risks, highlights tradeoffs and offers a more robust variant.

## Rules and Conventions

### Do

- Use only standard and open-source libraries with strong community support (ESP-IDF, PlatformIO, FreeRTOS, etc.).
- Show compilable, small, and well-commented examples.
- Explain automation scripts and pipelines in dedicated sections like `BUILD_AND_DEPLOY_PIPELINE.md`.
- Always highlight common risks (undefined behavior, concurrency, etc.).
- Reference official documentation and community tutorials whenever possible.

### Don't

- Avoid proprietary or closed dependencies unless strictly necessary, and always warn about them.
- Never assume prior knowledge: repeat structure from zero (introduction → minimal example → advanced variant).

## Recommended Project Structure

- For each technology, start with a **theoretical introduction** and simple examples.
- Document modifications or extensions in files like:
  - `HOW_TO_MODIFY_UART.md`
  - `CHANGE_LED_BEHAVIOR.md`
- Keep automation scripts and pipelines in separate, documented, and testable files.

## Example Response

**Question:** How do I start a basic BLE project on ESP32?
**Answer:**
1. Create a file `BLE_INTRODUCTION.md` explaining what BLE is and how it works on ESP32.
2. Provide a minimal example in `esp32_ble_basic_example.md` with commented code using ESP-IDF.
3. Add instructions for building and testing, using only standard tools.
4. Always cite the most relevant open-source references.

## Safety and Community

- Always warn about technical risks and safe practices.
- Reference recognized forums, repositories, and wikis in every answer.

## Recommended Commands (in English)

- `idf.py build`
- `idf.py flash`
- `platformio run`
- `platformio test`
- `bash setup_pipeline.sh`

## When Teaching Theory

- Provide explanatory documents with examples, starting from zero, in a new `.md` file.
- Place minimal examples in a separate file, commented line by line.

## Best Practices

- If a command or instruction is repeated or causes confusion, update this AGENTS.md and related explanatory files.

---

## Project Structure & Module Organization

- The root directory contains `CMakeLists.txt` and `sdkconfig.defaults.*` profiles for each chip target. Treat these as read-only templates when setting up new boards.
- The `main/` folder is the single ESP-IDF component:
  - `main.c` bootstraps FreeRTOS.
  - `src/` holds GAP/GATT, LED, heart-rate, and other helper modules.
  - `include/` contains public headers mirroring the module names.
- New subsystems should be added as `*.c`/`*.h` pairs within these folders.
- `idf_component.yml` declares third-party dependencies (e.g., `espressif/led_strip`). Extend it when adding managed components so `idf.py` can fetch them.

## Build, Test, and Development Commands

- `idf.py set-target <chip>`: Selects the SoC for the build folder (e.g., `idf.py set-target esp32s3`).
- `idf.py build`: Configures CMake and compiles all components. Rerun after editing Kconfig values or dependencies.
- `idf.py -p /dev/ttyACM0 flash monitor`: Flashes firmware and opens the serial console (exit with `Ctrl-]`). Use `idf.py monitor` for logs only.
- `idf.py reconfigure`: Refreshes cached settings after changes to `sdkconfig.defaults.*`.

## Coding Style & Naming Conventions

- Follow ESP-IDF C style:
  - Four-space indentation.
  - Braces on the same line.
  - `snake_case` for symbols.
  - Uppercase `TAG`s and macros (e.g., `ESP_LOGI(TAG, ...)`).
- Keep feature logic modular (`heart_rate_*`, `gap_*`, etc.) and expose APIs via headers with include guards.
- Add short Doxygen comments for non-trivial parameters.
- Prefer ESP-IDF helpers (`ESP_ERROR_CHECK`, `nimble_port_*`) over custom utilities.
- Store constants near their usage in `main/src`.

## Testing Guidelines

- Run `idf.py build` as the first gate; investigate warnings rather than suppressing them.
- Validate behavior on real hardware using `idf.py flash monitor` and tools like the nRF Connect mobile app.
- Confirm LED writes, subscription handling, and heart-rate indications.
- For new features, document manual test steps or captured logs in your PR for reproducibility.
- Name helper tasks/tests after their feature (`led_*`, `heart_rate_*`) for easy grepping.

## Commit & Pull Request Guidelines

- Use short, imperative commit subjects (e.g., `gatt: add automation io service`).
- Explain rationale and test commands in the commit body when needed.
- PRs should mention:
  - Target SoC.
  - Relevant `sdkconfig.defaults.*`.
  - Verification commands.
  - Screenshots/log snippets for BLE-centric changes.
- Request reviewers familiar with ESP-IDF BLE for shared GAP/GATT code.
- Ensure CI and `idf.py build` pass before requesting merge.

---

## Project-Specific Customizations

### [Project Name/Feature]
- Add project-specific instructions, chip targets, custom components, or unique workflows here.
- Example:
  - Target SoC: esp32s3
  - Custom component: `my_ble_sensor`
  - Special build flags: `-DCUSTOM_FLAG`
  - Unique test steps: [Describe]

---

## Additional Notes

- Always prefer open-source solutions and community resources.
- Document new concepts or features in separate `.md` files (e.g., `BLE_INTRODUCTION.md`, `esp32_ble_basic_example.md`).
- For automation, use Bash/Linux scripting and document pipelines in files like `BUILD_AND_DEPLOY_PIPELINE.md`.
- If unsure, refer to official ESP-IDF docs and community forums.