Merge pull request #68 from baba-dev/codex/add-reproducible-dev-environment-setup

Add dev tooling scaffolding and test harnesses

Author: baba-dev

.devcontainer/devcontainer.json

@@ -1,11 +1,15 @@
 {
-  "name": "M5Tab5 - ESP-IDF v5.5",
-  "build": { "dockerfile": "Dockerfile" },
-  "containerEnv": { "BASH_ENV": "/etc/profile" },
-  "postStartCommand": "bash -lc 'idf.py --version || true'",
+  "name": "M5Tab5 Dev",
+  "image": "espressif/idf:release-v5.5",
+  "features": { "ghcr.io/devcontainers/features/git:1": {} },
+  "containerEnv": { "CCACHE_DIR": "/workspaces/.ccache" },
+  "mounts": [
+    "source=${localWorkspaceFolder}/.ccache,target=/workspaces/.ccache,type=bind"
+  ],
+  "postCreateCommand": "python -m pip install -U pip && pip install -r requirements.txt || true",
   "customizations": {
     "vscode": {
-      "extensions": ["espressif.esp-idf-extension", "ms-vscode.cpptools"]
+      "extensions": ["ms-vscode.cmake-tools", "ms-vscode.cpptools", "twxs.cmake"]
     }
   }
 }

.env.example

@@ -0,0 +1,8 @@
+# Example environment overrides for local tooling
+# Copy to .env and adjust as needed.
+
+# Uncomment to force the asset pipeline to refresh goldens.
+# UPDATE_GOLDEN=1
+
+# Serial port used for flashing/monitoring.
+# ESPPORT=/dev/ttyUSB0

.github/CODEOWNERS

@@ -0,0 +1,3 @@
+# Critical hardware components require explicit review
+components/hal/* @you
+custom/platform/* @you

.github/workflows/codeql.yml

@@ -0,0 +1,16 @@
+name: CodeQL
+on:
+  push: { branches: [main] }
+  pull_request:
+  schedule: [{cron: '0 3 * * 1'}]
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    permissions: { security-events: write, contents: read }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: github/codeql-action/init@v3
+        with: { languages: 'cpp' }
+      - uses: github/codeql-action/autobuild@v3
+      - uses: github/codeql-action/analyze@v3

.github/workflows/host-tests.yml

@@ -13,12 +13,12 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      # Use system GTest (fast) and tools
+      # Install build tools and GTest
       - name: Install deps
         run: |
           sudo apt-get update
           sudo apt-get install -y ninja-build cmake ccache libgtest-dev
-          # Build GTest if headers/libs not prebuilt on the runner image
+          # Build GTest libs (headers are already present)
           sudo cmake -S /usr/src/googletest -B /usr/src/googletest/build
           sudo cmake --build /usr/src/googletest/build -j
           sudo cp -a /usr/src/googletest/build/lib/* /usr/local/lib/
@@ -47,3 +47,6 @@ jobs:
 
       - name: Run tests
         run: ctest --test-dir tests/build --output-on-failure --timeout 60
+
+      - name: Secret scan
+        run: ./tools/check_secrets.sh

CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing guide
+
+Thanks for helping improve the Tab5 firmware! This document outlines the
+minimum steps required to get a change merged.
+
+## Prerequisites
+
+1. Install the ESP-IDF toolchain (v5.5) or use the provided devcontainer.
+2. Install Python dependencies:
+   ```bash
+   make setup
+   ```
+3. Configure Git LFS so binary blobs (fonts, PNGs) stay lightweight:
+   ```bash
+   git lfs install
+   ```
+
+## Workflow
+
+1. Create a feature branch and make focused commits. Follow Conventional Commit
+   prefixes (e.g. `feat(core): add foo`).
+2. Run the full validation suite before pushing:
+   ```bash
+   make fmt
+   make build
+   make test
+   ./tools/check_secrets.sh
+   ```
+3. If you touch firmware components or enable new compiler warnings, also run:
+   ```bash
+   make tidy
+   ```
+4. Document user-visible behaviour in `CHANGELOG.md` and update any relevant
+   docs in `docs/` or `DOCS/`.
+5. For UI tweaks provide screenshots or LVGL snapshot updates.
+
+## Pull requests
+
+- Fill out the PR template, ticking the boxes you exercised locally.
+- Reference issues in the footer (`Refs #123`).
+- Keep diffs reviewable (prefer < 500 lines changed).
+- Ensure CI workflows (`IDF Build`, `Host Tests`, `CodeQL`) are green before
+  requesting review.

DOCS/FLASH_LAYOUT.md

@@ -0,0 +1,15 @@
+# Flash layout
+
+The Tab5 firmware uses the partition table at `platforms/tab5/partitions.csv`:
+
+| Partition | Type | Offset  | Size | Notes |
+| --------- | ---- | ------- | ---- | ----- |
+| `nvs`     | data | 0x9000  | 24KB | Non-volatile key/value storage. |
+| `phy_init`| data | 0xF000  | 4KB  | Wi-Fi PHY calibration data. |
+| `factory` | app  | 0x10000 | 10MB | Main application image. |
+| `human_face_det` | data | auto | 400KB | SPIFFS partition reserved for demo assets. |
+| `storage` | data | auto | 2MB | SPIFFS partition that carries generated assets (`custom/assets` + `out/assets`). |
+
+`make assets` produces the runtime blobs in `out/assets/`; the ESP-IDF build
+copies them into the `storage` partition via the staging step in
+`platforms/tab5/main/CMakeLists.txt`.

DOCS/REPO_MAP.md

@@ -0,0 +1,17 @@
+# Repository map
+
+- `platforms/tab5/` – ESP-IDF application for the Tab5 hardware. Contains the
+  board-specific `main/` component, sdkconfig defaults, partition table, and
+  audio assets that ship with the firmware image.
+- `components/core/` – device-agnostic logic (ring buffer, settings store,
+  future shared services) that is built both for firmware and host tests.
+- `custom/` – application-specific UI, integration layers, and runtime asset
+  loaders. Files here are shared across hardware and desktop targets.
+- `tests/` – host-side unit tests, LVGL snapshot tests, and future firmware
+  smoke tests. Invoked with `make test`.
+- `tools/` – development utilities such as format/lint wrappers and the asset
+  conversion pipeline.
+- `DOCS/` – developer-facing documentation including this map and flash layout
+  notes.
+- `ai/tasks/` – repeatable briefs for automated agents. Copy the template and
+  fill in the context, goal, and acceptance criteria when scoping new work.

Makefile

@@ -0,0 +1,37 @@
+.PHONY: help setup build test flash monitor fmt tidy assets qemu
+IDF_PATH?=/opt/esp/idf
+APP_DIR?=platforms/tab5
+BUILD_DIR?=$(APP_DIR)/build
+
+help:
+	@grep -E '^[a-zA-Z_-]+:.*?## ' Makefile | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2}'
+
+setup: ## Install git hooks / Python deps
+	python -m pip install -U pip && pip install -r requirements.txt || true
+
+build: ## Build firmware (esp-idf)
+	cmake -S $(APP_DIR) -B $(BUILD_DIR) -DIDF_TARGET=esp32p4 -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+	cmake --build $(BUILD_DIR) -j
+
+test: ## Host/unit tests
+	cmake -S tests -B tests/build
+	cmake --build tests/build -j
+	ctest --test-dir tests/build --output-on-failure
+
+fmt: ## Format source
+	./tools/run_clang_format.sh
+
+tidy: build ## Static analysis
+	./tools/run_clang_tidy.sh
+
+assets: ## Convert PNG/JPG → runtime-friendly assets + manifest
+	python tools/gen_assets.py custom/assets out/assets
+
+flash: build ## Flash device (adjust port)
+	python $(IDF_PATH)/components/esptool_py/esptool/esptool.py --chip esp32p4 write_flash 0x0 $(BUILD_DIR)/M5Tab5.bin
+
+monitor: ## Serial monitor
+	miniterm.py /dev/ttyUSB0 115200
+
+qemu: ## QEMU smoke tests placeholder
+	@echo "QEMU smoke tests are not yet implemented for this project."

TRACEPOINTS.md

@@ -0,0 +1,13 @@
+# Tracepoints
+
+Use the macros in `components/core/include/app_trace.h` to annotate important
+runtime events. Common sections/events:
+
+| Section  | Event          | Purpose                                  |
+| -------- | -------------- | ---------------------------------------- |
+| `boot`   | `init`         | Firmware entry, board bring-up sequence. |
+| `ui`     | `page_show`    | User navigates to a page.                |
+| `ui`     | `asset_fallback` | File-system asset missing, using fallback. |
+| `audio`  | `play`         | Playback triggered (song, chime).        |
+
+Add new entries when introducing features so logs remain searchable.