{"id":34990349,"url":"https://github.com/sivakov512/esp-idf-project-template","last_synced_at":"2026-05-25T05:01:34.777Z","repository":{"id":319362264,"uuid":"1076363735","full_name":"sivakov512/esp-idf-project-template","owner":"sivakov512","description":"A clean ESP-IDF project template with pre-configured development tools and build settings","archived":false,"fork":false,"pushed_at":"2026-03-30T02:56:38.000Z","size":71,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T05:37:26.363Z","etag":null,"topics":["c","cmake","cpp","ctest","embedded","esp-idf","esp32","espressif","firmware","template"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sivakov512.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-14T18:52:21.000Z","updated_at":"2026-03-30T02:56:42.000Z","dependencies_parsed_at":null,"dependency_job_id":"d76a00aa-5aec-4a19-9428-5e8a9138105d","html_url":"https://github.com/sivakov512/esp-idf-project-template","commit_stats":null,"previous_names":["sivakov512/esp-idf-project-template"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/sivakov512/esp-idf-project-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivakov512%2Fesp-idf-project-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivakov512%2Fesp-idf-project-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivakov512%2Fesp-idf-project-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivakov512%2Fesp-idf-project-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sivakov512","download_url":"https://codeload.github.com/sivakov512/esp-idf-project-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivakov512%2Fesp-idf-project-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33461090,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T02:24:28.008Z","status":"ssl_error","status_checked_at":"2026-05-25T02:23:23.339Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","cmake","cpp","ctest","embedded","esp-idf","esp32","espressif","firmware","template"],"created_at":"2025-12-27T01:51:39.484Z","updated_at":"2026-05-25T05:01:34.760Z","avatar_url":"https://github.com/sivakov512.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESP-IDF Project Template\n\nAn ESP-IDF project base with clang-tidy, clangd, and CI pre-configured, host-side unit tests ready to run, and optional ESP-Matter support. Start writing firmware, not tooling config.\n\n[![ESP Lint](https://github.com/sivakov512/esp-idf-project-template/actions/workflows/esp-lint.yml/badge.svg)](https://github.com/sivakov512/esp-idf-project-template/actions/workflows/esp-lint.yml)\n[![Formatting](https://github.com/sivakov512/esp-idf-project-template/actions/workflows/formatting.yml/badge.svg)](https://github.com/sivakov512/esp-idf-project-template/actions/workflows/formatting.yml)\n\n## What's included\n\n- **clang-format, clang-tidy, and clangd work out of the box** — [`sanitize_compile_db.py`](sanitize_compile_db.py) strips GCC-specific flags from ESP-IDF's `compile_commands.json` and injects the correct toolchain/sysroot; works on both Xtensa and RISC-V targets\n- **CI pre-configured** — GitHub Actions for static analysis and formatting; auto-selects the correct Docker image when Matter is enabled\n- **Host-side unit tests** — [Unity](https://github.com/ThrowTheSwitch/Unity) via CMake `FetchContent`; test business logic without hardware\n- **App structure** — `main/` entry point + `components/app/` business logic, ready to expand\n- **Optional ESP-Matter** — connectedhomeip integration with C++17 pinning for Matter components\n\n---\n\n## Requirements\n\n| Tool | Version | Notes |\n|------|---------|-------|\n| [ESP-IDF](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/) | v5.4+ | Required |\n| CMake | 3.16+ | For host tests |\n| clang-format / clang-tidy / clangd | 18+ | Recommended |\n| [ESP-Matter](https://docs.espressif.com/projects/esp-matter/en/latest/esp32/developing.html) | release_v1.5+ | Optional |\n\n---\n\n## Quick Start\n\nClick **\"Use this template\" → \"Create a new repository\"** on GitHub, then clone your new repo.\n\nRename the project in `CMakeLists.txt`:\n\n```cmake\nproject(your-project-name)\n```\n\nBuild and flash:\n\n```bash\nmake esp-build\nmake esp-flashm        # flash + open serial monitor\n```\n\n---\n\n## Project Structure\n\n```\n.\n├── .github/\n│   ├── workflows/\n│   │   ├── esp-lint.yml        # clang-tidy on ESP target (auto-picks Matter image if needed)\n│   │   └── formatting.yml      # clang-format check\n│   └── disabled_workflows/\n│       └── host-checks.yml     # host tests + lint (enable when you add testable components)\n├── components/\n│   └── app/                    # Main application component\n│       ├── include/app.h       # app_ctx_t, app_init(), app_run()\n│       ├── app.c\n│       └── CMakeLists.txt\n├── main/\n│   ├── main.c                  # app_main() — calls app_init() then app_run(), handles errors\n│   ├── idf_component.yml       # IDF component manager dependencies\n│   └── CMakeLists.txt\n├── tests/\n│   └── host/                   # Host-side unit tests (Unity, no hardware needed)\n│       ├── cmake/\n│       │   └── AddUnityTest.cmake\n│       └── CMakeLists.txt\n├── .clang-format               # LLVM-based style, 85 col limit, 4-space indent\n├── .clang-tidy                 # Static analysis rules, all warnings as errors\n├── .clangd                     # LSP config — strips GCC flags for IDE compatibility\n├── sanitize_compile_db.py      # Patches IDF's compile_commands.json for clang-tidy\n├── sdkconfig.defaults          # IDF defaults (partition table hints)\n├── CMakeLists.txt              # Top-level build\n└── Makefile                    # Convenience targets for all common workflows\n```\n\n`app_main()` calls `app_init()` then `app_run()` on `app_ctx_t` and handles errors uniformly. All business logic goes in `components/app/` or new components alongside it; `main.c` stays minimal.\n\nDependencies pulled via IDF component manager (`main/idf_component.yml`):\n\n| Library | Purpose |\n|---------|---------|\n| [`slog`](https://github.com/sivakov512/slog) | Structured tag-based logging (`SLOGI`, `SLOGE`, …) |\n| [`embedlibs`](https://github.com/sivakov512/embedlibs) | Embedded utilities (`EXTERN_C_BEGIN/END`, etc.) |\n\n---\n\n## Makefile Reference\n\n### ESP (on-device)\n\n| Target | Description |\n|--------|-------------|\n| `esp-build` | Build the project (`idf.py build`) |\n| `esp-flash` | Flash to device |\n| `esp-flashm` | Flash and open serial monitor |\n| `esp-monitor` | Open serial monitor only |\n| `esp-lint` | Run clang-tidy on ESP sources |\n| `esp-sanitize-db` | Patch `build/compile_commands.json` → `build/tidy/compile_commands.json` (called by `esp-lint`) |\n| `esp-menuconfig` | Open IDF menuconfig |\n| `esp-clean` | Full clean (build artifacts, managed components, cache) |\n\nOverride the default serial port: `make esp-flash PORT_ESP=/dev/ttyUSB0`\n\n### Host tests\n\n| Target | Description |\n|--------|-------------|\n| `host-build` | Build host test suite (CMake + Unity) |\n| `host-test` | Run tests on the host machine |\n| `host-lint` | Run clang-tidy on host-compatible components |\n| `host-fullcheck` | `host-test` + `host-lint` |\n| `host-clean` | Remove host build artifacts |\n\n### Code quality\n\n| Target | Description |\n|--------|-------------|\n| `check-format` | Verify formatting with clang-format (dry-run) |\n| `lint` | `esp-lint` + `host-lint` + `check-format` |\n| `fullcheck` | `lint` + `host-test` |\n| `clean` | Clean all (ESP + host) |\n\n### IDE helpers\n\n| Target | Description |\n|--------|-------------|\n| `use-esp` | Symlink `compile_commands.json` → ESP build DB |\n| `use-host` | Symlink `compile_commands.json` → host test build DB |\n\n---\n\n## clangd / IDE Integration\n\nThe `.clangd` config strips ESP-IDF's GCC-specific flags (`-mlongcalls`, `-mcpu=*`, `-march=*`, etc.) so that clangd works correctly in VS Code, CLion, Neovim, and any other LSP-capable editor.\n\nSwitch `compile_commands.json` between build targets:\n\n```bash\nmake use-esp    # point clangd at the ESP build DB\nmake use-host   # point clangd at the host test build DB\n```\n\n---\n\n## Host-Side Testing\n\nThe `tests/host/` directory uses [Unity](https://github.com/ThrowTheSwitch/Unity) fetched automatically via CMake `FetchContent`. Tests run natively — no hardware required.\n\n```bash\nmake host-test\n```\n\nTo add a component to the host test suite:\n\n1. Add the component name to `LIBS2TEST` in `tests/host/CMakeLists.txt`.\n2. Create a `tests/` directory inside the component.\n3. Add a `CMakeLists.txt` using the `add_unity_test()` helper:\n\n```cmake\nadd_unity_test(my_component_tests\n    SRCS test_my_component.c\n    LIBS my_component\n)\n```\n\nEnable the `host-checks.yml` workflow once you have tests to run.\n\n---\n\n## Enabling ESP-Matter\n\n1. Set the environment variable:\n   ```bash\n   export ESP_MATTER_PATH=/path/to/esp-matter\n   ```\n\n2. Enable in `CMakeLists.txt`:\n   ```cmake\n   set(ESP_MATTER_ENABLED true)\n   ```\n\n3. Clean and rebuild:\n   ```bash\n   make esp-clean\n   make esp-build\n   ```\n\n**C++ standard:** ESP-IDF defaults to GNU C++23 (`-std=gnu++2b`). When Matter is enabled, Matter/CHIP components are compiled with `-std=gnu++17 -w` to avoid C++23 incompatibilities in upstream connectedhomeip; your code stays on C++23.\n\n**CI:** The `esp-lint` workflow auto-detects `ESP_MATTER_ENABLED` and selects the correct Docker image — `ghcr.io/sivakov512/esp-idf` for plain builds or `ghcr.io/sivakov512/esp-matter` when Matter is active.\n\n---\n\n## Code Style\n\n### clang-format\n\nBased on **LLVM style** with project tweaks:\n\n- 4-space indentation, 85-column limit\n- Tabs → spaces\n- Braces: `Attach`\n- Sorted includes, blocks preserved\n\n### clang-tidy\n\nChecks enabled: `clang-diagnostic-*`, `clang-analyzer-*`, `bugprone-*`, `performance-*`, `portability-*`, `modernize-*`, `readability-*`, `misc-*`, plus select `google-*` rules. **All warnings are treated as errors.**\n\n**Naming conventions:**\n\n| Context | Convention | Example |\n|---------|-----------|---------|\n| C functions | `snake_case` | `app_init` |\n| C structs / typedefs | `snake_case_t` | `app_ctx_t` |\n| C++ classes / enums | `CamelCase` | `WifiManager` |\n| C++ methods | `snake_case` | `connect` |\n| C++ members | `snake_case_` | `retry_count_` |\n| Class constants | `kCamelCase` | `kMaxRetries` |\n| Enum values | `UPPER_CASE` | `STATE_IDLE` |\n| Macros \u0026 global constants | `UPPER_CASE` | `TAG` |\n| Global variables | `g_` prefix | `g_event_loop` |\n| Namespaces | `lower_case` | `wifi` |\n\nSee [`.clang-tidy`](.clang-tidy) for the complete configuration.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsivakov512%2Fesp-idf-project-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsivakov512%2Fesp-idf-project-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsivakov512%2Fesp-idf-project-template/lists"}