From da939aed20a189bad76556bf58e5dc5d4a860c8c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 19 Feb 2026 15:21:03 +0000
Subject: [PATCH 1/2] Initial plan


From 9715e9a5fe21df4eb44f8a844395cc1ee3b0ee23 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 19 Feb 2026 15:23:22 +0000
Subject: [PATCH 2/2] Add .github/copilot-instructions.md with repository
 guidelines

Co-authored-by: finger563 <213467+finger563@users.noreply.github.com>
---
 .github/copilot-instructions.md | 113 ++++++++++++++++++++++++++++++++
 1 file changed, 113 insertions(+)
 create mode 100644 .github/copilot-instructions.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 000000000..30814fc77
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,113 @@
+# Copilot Instructions for ESPP
+
+## Repository Overview
+
+ESPP (Espressif++) is a C++ component library for ESP32/ESP-IDF. It targets ESP-IDF v5.5.1+ and provides ~120 reusable components published to the [ESP Component Registry](https://components.espressif.com) under the `espp` namespace.
+
+## Repository Structure
+
+```
+components/          # All library components (one directory per component)
+doc/                 # Documentation (Doxygen + Sphinx/RST)
+.github/workflows/   # CI: build.yml and upload_components.yml
+lib/                 # External library submodules
+pc/                  # PC-side utilities
+python/              # Python utilities
+```
+
+## Component Structure
+
+Every component follows this layout (use `components/task` as a reference):
+
+```
+components/<name>/
+├── CMakeLists.txt          # idf_component_register(...)
+├── README.md               # Component overview
+├── idf_component.yml       # IDF Component Manager manifest
+├── include/
+│   └── <name>.hpp          # Public header(s)
+├── src/
+│   └── <name>.cpp          # Implementation (if any)
+└── example/
+    ├── CMakeLists.txt      # ESP-IDF project cmake
+    ├── README.md           # Example documentation
+    ├── sdkconfig.defaults  # Default config (add more for multiple targets)
+    └── main/
+        ├── CMakeLists.txt  # idf_component_register(...)
+        └── <name>_example.cpp
+```
+
+Some examples also include `partitions.csv` or multiple `sdkconfig.defaults.*` files for different hardware targets.
+
+## When Adding a New Component
+
+Complete **all** of the following steps (in alphabetical order where required):
+
+### 1. Component Files
+- Create the full directory structure above under `components/<name>/`
+- `CMakeLists.txt`: use `idf_component_register(INCLUDE_DIRS "include" SRC_DIRS "src" REQUIRES ...)`
+- `idf_component.yml`: include license, description, url, repository, maintainers, documentation, examples, tags, and dependencies
+- `example/CMakeLists.txt`: set `EXTRA_COMPONENT_DIRS` to `"../../../components/"` and list required components
+
+### 2. Documentation — `doc/Doxyfile`
+Add entries in **alphabetical order** to both sections:
+
+```
+INPUT = \
+  ...
+  $(PROJECT_PATH)/components/<name>/include/<name>.hpp \
+  ...
+
+EXAMPLE_PATH = \
+  ...
+  $(PROJECT_PATH)/components/<name>/example/main/<name>_example.cpp \
+  ...
+```
+
+### 3. Documentation — `doc/en/`
+Add two files (use existing files as a template):
+
+- `doc/en/<name>.rst` — RST page describing the component API. Include a `toctree` pointing to the example and an `include-build-file` directive for the API reference.
+- `doc/en/<name>_example.md` — Markdown file that simply includes the component's example README:
+  ````
+  ```{include} ../../components/<name>/example/README.md
+  ```
+  ````
+
+If the component belongs to a logical group (e.g., `display`, `imu`, `network`), place the files in the appropriate subdirectory under `doc/en/`.
+
+### 4. CI — `.github/workflows/build.yml`
+Add a matrix entry in **alphabetical order** inside the `strategy.matrix.test` list. Choose the most appropriate target (`esp32`, `esp32s3`, or `esp32p4`):
+
+```yaml
+- path: 'components/<name>/example'
+  target: esp32s3
+```
+
+### 5. CI — `.github/workflows/upload_components.yml`
+Add the component path in **alphabetical order** inside the `components:` block:
+
+```yaml
+components/<name>
+```
+
+## Code Style
+
+- C++20 standard
+- Follow `.clang-format` for formatting
+- Use `espp` namespace
+- Follow the patterns of existing components for logging (`espp::Logger`), configuration structs (`Config`), and task usage
+
+## Building & Testing
+
+- Build examples using ESP-IDF v5.5.1: `idf.py build` from the example directory
+- CI uses `espressif/esp-idf-ci-action@v1` with `esp_idf_version: v5.5.1`
+- Pre-commit hooks are configured in `.pre-commit-config.yaml`
+
+## Keeping Things Up to Date
+
+When modifying an **existing** component:
+- Update `README.md` and example `README.md` if behavior changes
+- Update `idf_component.yml` version as appropriate
+- Update the RST file in `doc/en/` if the API description changes
+- Keep all entries in `Doxyfile`, `build.yml`, and `upload_components.yml` in alphabetical order