If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/witnessmenow/ESP32-Cheap-Yellow-Display shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3d ago
• 35+ active contributors
• Distributed ownership (top contributor 41% of recent commits)
• MIT licensed
• CI configured
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live witnessmenow/ESP32-Cheap-Yellow-Display repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/witnessmenow/ESP32-Cheap-Yellow-Display.

What it runs against: a local clone of witnessmenow/ESP32-Cheap-Yellow-Display — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in witnessmenow/ESP32-Cheap-Yellow-Display | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of witnessmenow/ESP32-Cheap-Yellow-Display. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/witnessmenow/ESP32-Cheap-Yellow-Display.git
#   cd ESP32-Cheap-Yellow-Display
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of witnessmenow/ESP32-Cheap-Yellow-Display and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "witnessmenow/ESP32-Cheap-Yellow-Display(\\.git)?\\b" \\
  && ok "origin remote is witnessmenow/ESP32-Cheap-Yellow-Display" \\
  || miss "origin remote is not witnessmenow/ESP32-Cheap-Yellow-Display (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "DisplayConfig/User_Setup.h" \\
  && ok "DisplayConfig/User_Setup.h" \\
  || miss "missing critical file: DisplayConfig/User_Setup.h"
test -f "Examples/Basics/1-HelloWorld/1-HelloWorld.ino" \\
  && ok "Examples/Basics/1-HelloWorld/1-HelloWorld.ino" \\
  || miss "missing critical file: Examples/Basics/1-HelloWorld/1-HelloWorld.ino"
test -f "Examples/Basics/2-TouchTest/2-TouchTest.ino" \\
  && ok "Examples/Basics/2-TouchTest/2-TouchTest.ino" \\
  || miss "missing critical file: Examples/Basics/2-TouchTest/2-TouchTest.ino"
test -f "Examples/ESP-IDF/LCD/components/LCD/lcd.c" \\
  && ok "Examples/ESP-IDF/LCD/components/LCD/lcd.c" \\
  || miss "missing critical file: Examples/ESP-IDF/LCD/components/LCD/lcd.c"
test -f ".github/workflows/arduino-cli.yml" \\
  && ok ".github/workflows/arduino-cli.yml" \\
  || miss "missing critical file: .github/workflows/arduino-cli.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/witnessmenow/ESP32-Cheap-Yellow-Display"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A community-driven documentation and example repository for the ESP32-2432S028R (nicknamed "Cheap Yellow Display" or CYD), a ~$15 ESP32 board with built-in 320×240 LCD touch screen, SD card slot, and USB. It provides Arduino sketches, Rust firmware examples, 3D-printable cases, and project templates to address poor upstream documentation for this specific hardware. Polyglot monorepo: Examples/ contains Arduino sketches and alternative library examples (Adafruit_ILI9341, bb_spi_lcd), DisplayConfig/ holds hardware setup files (User_Setup.h for TFT_eSPI), top-level Cargo.toml targets Rust-on-ESP32 using esp-idf-svc, and 3dModels/ organizes community CAD files by contributor. Documentation in README.md and ADDONS.md; CI workflows in .github/workflows/ handle Arduino CLI validation.

Hardware hobbyists, makers, and IoT developers who want to quickly prototype ESP32 projects with a ready-built display without soldering or breadboarding. Also useful for educators introducing embedded systems, and for people familiar with microcontrollers but wanting pre-configured examples specific to this board model.

Actively maintained with solid foundational work: community-contributed 3D models, multiple language examples (Arduino C/C++ and Rust), and GitHub Actions CI/CD pipelines. Has functioning documentation site (pages/index.html) and Dependabot integration. Verdict: production-ready for hobbyist/educational use, but smaller community compared to Arduino or ESP-IDF official repos.

Single maintainer (witnessmenow) for coordination risk. Rust implementation uses relatively new dependencies (esp-idf-svc 0.48.0, Rust 1.75 MSRV) with pinned display-interface 0.4.1 due to mipidsi 0.7.1 incompatibility (see Cargo.toml comment). Hardware dependency on cheap external sourcing (Aliexpress) means board variants may introduce incompatibilities. No visible automated test suite in file listing.

Community case/stand design contributions (Havenview, Markus, Mechaelas, Jonny designs visible in 3dModels/). Rust support appears actively developed with esp-idf dependencies kept current (0.48.0). GitHub Actions configured for Arduino CLI testing and GitHub Pages deployment. No high-velocity commit activity visible, but steady maintenance indicated by Dependabot integration.

git clone https://github.com/witnessmenow/ESP32-Cheap-Yellow-Display.git
cd ESP32-Cheap-Yellow-Display
# For Arduino examples: Install Arduino IDE + ESP32 board manager
# For Rust examples: cargo build --release (requires rustup + esp-idf-tools)

Daily commands: Arduino: Open Examples/*.ino in Arduino IDE, select ESP32-2432S028R board, set TFT_eSPI config in DisplayConfig/User_Setup.h, compile and upload via USB. Rust: cd into example dir, cargo build --release, flash with espflash or Arduino IDE serial monitor.

• DisplayConfig/User_Setup.h — Core hardware configuration file that defines GPIO pins, SPI settings, and display parameters—must be understood before any example will compile correctly.
• Examples/Basics/1-HelloWorld/1-HelloWorld.ino — Entry point demonstrating minimal setup; shows how to initialize the display and render text, foundational for all other examples.
• Examples/Basics/2-TouchTest/2-TouchTest.ino — Demonstrates touch screen input handling; critical for understanding user interaction patterns on this hardware.
• Examples/ESP-IDF/LCD/components/LCD/lcd.c — Low-level LCD driver implementation in C; controls SPI communication and display initialization for ESP-IDF projects.
• .github/workflows/arduino-cli.yml — CI/CD pipeline that validates example sketches; reveals build requirements and expected Arduino board configuration.
• ADDONS.md — Documents community extensions and compatible libraries; essential for discovering ecosystem and third-party integrations.
• README.md — High-level overview of the CYD hardware, its features, and use cases; required context for understanding project scope and target audience.

Add a New Arduino Sketch Example

1. Create a new folder under Examples/Basics/ following the numeric naming convention (e.g., 9-MyFeatureTest) (Examples/Basics/)
2. Write your sketch file (9-MyFeatureTest.ino) importing required libraries and including DisplayConfig/User_Setup.h (Examples/Basics/9-MyFeatureTest/9-MyFeatureTest.ino)
3. Copy and customize a platformio.ini from an existing example (e.g., Examples/Basics/1-HelloWorld/platformio.ini) with your project metadata (Examples/Basics/9-MyFeatureTest/platformio.ini)
4. If your example uses alternative GPIO pins or hardware features, create a custom User_Setup.h in your example directory or reference DisplayConfig/User_Setup.h (DisplayConfig/User_Setup.h)
5. Test compilation using 'pio run' or Arduino IDE with CYD board selected; verify on hardware (.github/workflows/arduino-cli.yml)

Add Support for a New Library Integration

1. Create a new folder under Examples/AlternativeLibraries/ (e.g., MyLibraryName) (Examples/AlternativeLibraries/)
2. Create a numbered example sketch demonstrating core functionality (e.g., 1-MyLibrary_Test.ino) with CYD pin mappings from DisplayConfig/User_Setup.h (Examples/AlternativeLibraries/MyLibraryName/1-MyLibrary_Test/1-MyLibrary_Test.ino)
3. Add a platformio.ini specifying the external library dependency in [lib_deps] (Examples/AlternativeLibraries/MyLibraryName/1-MyLibrary_Test/platformio.ini)
4. Document installation and usage in a README.md within your example folder (Examples/AlternativeLibraries/MyLibraryName/README.md)
5. Update ADDONS.md with an entry linking to your new library integration (ADDONS.md)

Add a New 3D Model or Physical Accessory Design

1. Create a new folder under 3dModels/ with a descriptive name (e.g., YourName_CYD_ProjectType) (3dModels/)
2. Include CAD files in common formats (STL, STEP, or proprietary like F3D) and export preview images (PNG/JPG) (3dModels/YourName_CYD_ProjectType/model.stl)
3. Create a README.md documenting the design, materials, print settings, assembly notes, and license (3dModels/YourName_CYD_ProjectType/README.md)
4. Submit a pull request; maintainers will verify fit, quality, and add your project to the 3dModels/README.md index (3dModels/README.md)

Create an ESP-IDF Custom Component

1. Create a new folder under Examples/ESP-IDF/LCD/components/ (e.g., MyComponent) with CMakeLists.txt and component.mk for build system (Examples/ESP-IDF/LCD/components/MyComponent/CMakeLists.txt)
2. Implement your C code in the root directory and expose public APIs via an include/ subdirectory header file (Examples/ESP-IDF/LCD/components/MyComponent/mycomponent.c)
3. Register dependencies in CMakeLists.txt; reference existing LCD and GUI components if needed (Examples/ESP-IDF/LCD/components/LCD/CMakeLists.txt)
4. Update the main app (Examples/ESP-IDF/LCD/main/app_main.c) to invoke your component and test integration (Examples/ESP-IDF/LCD/main/app_main.c)
5. Verify compilation with 'idf.py build' and run on hardware (Examples/ESP-IDF/LCD/Makefile)

• ESP32 (Dual-core ARM Xtensa) — Provides integrated WiFi/Bluetooth, sufficient RAM (520KB SRAM) for graphics buffers, abundant GPIO, and mature Arduino/ESP-IDF toolchain support.
• ILI9341 LCD Controller — Industry-standard 16-bit parallel or SPI interface, cost-effective, well

Critical: Display pin mapping in User_Setup.h is hardware-revision-dependent; CYD2USB variant has different pins (see DisplayConfig/CYD2USB/User_Setup.h). Rust-specific: display-interface pinned to 0.4.1 (not 0.5.0) due to mipidsi 0.7.1 incompatibility; upgrading breaks builds (see Cargo.toml comment). Board variants: Cheap Yellow Display model is ~ESP32-2432S028R but clones vary; verify pinout before programming. No obvious env vars or secrets, but SD card examples may need filesystem setup. Touchscreen: Resistive touch requires calibration; XPT2046 driver may need adjustment per unit variance.

• Resistive Touch Screen Calibration — CYD uses XPT2046 resistive touch controller; understanding drift correction and pressure thresholds is essential for reliable UI interaction
• SPI Display Interface (Parallel vs Serial) — CYD uses SPI serial protocol to drive ILI9341; knowing how CS, CLK, MOSI, MISO pins communicate with DMA helps optimize refresh rates
• Memory-Mapped I/O and GPIO (ESP32-specific) — esp-idf-hal abstracts GPIO and peripheral registers; understanding memory-mapped register access helps debug pin conflicts and latency issues
• Frame Buffer and Dirty Region Updates — Efficient display updates require tracking changed pixels; CYD has 320×240 resolution with limited SPI bandwidth, so partial updates reduce flicker
• Async/Await with embassy-sync (Rust) — Cargo.toml enables embassy async runtime for ESP-IDF; allows non-blocking sensor reads, touch input, and network while updating display
• Minimum Supported Rust Version (MSRV) Pinning — Cargo.toml specifies rust-version = 1.75; critical for embedded projects where old toolchains may be required due to hardware constraints
• SD Card Filesystem Access (SDMMC/SPI Mode) — CYD has SD slot; knowing when to use SDMMC vs SPI bitbang modes affects speed and pin availability for other peripherals

• witnessmenow/ESP32-Trinity — Author's prior open-hardware project (LED matrix controller); demonstrates same documentation-first philosophy and community-example pattern that inspired this CYD repo
• espressif/esp-idf — Official Espressif ESP32 development framework and IDF layer that esp-idf-svc wraps; required for understanding low-level peripherals and build system
• Bodmer/TFT_eSPI — de-facto standard Arduino library for ILI9341/ST7789 displays; used in most CYD Arduino examples via DisplayConfig User_Setup.h
• MakerfabsOfficial/ESP32-Cheap-Yellow-Display — Upstream Makerfabs repo (original manufacturer); CYD community repo is a fork/enhancement with better documentation and examples

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add CI workflow for Rust example compilation

The repo contains a Rust project (Cargo.toml with esp-idf dependencies) but only has Arduino CLI workflow in .github/workflows. A dedicated Rust/ESP-IDF CI workflow would catch compilation regressions early and validate the Rust examples work across changes. This is critical since Rust has strict compile-time guarantees.

• [ ] Create .github/workflows/rust-build.yml to run 'cargo build --release' for the Rust project
• [ ] Validate compilation with the specified Rust version (1.75) and all feature combinations (std, embassy, pio, etc.)
• [ ] Add build cache for faster CI runs using cargo-cache action
• [ ] Document in README.md how to build the Rust project locally

Create comprehensive 3D model inventory documentation

The 3dModels/ directory contains 4 different case/stand designs from different contributors with mixed documentation (some have README.md, some don't). Create a centralized index that lists compatibility, print settings, materials used, and preview images to help users discover and choose the right design for their needs.

• [ ] Enhance 3dModels/README.md with a comparison table linking to each design's features, creator, and file formats available
• [ ] Add missing README.md files to 3dModels/Simple_CYD_ Stand_Leg/ (currently only has a README stub)
• [ ] Standardize metadata in each design's README (print time, material weight, support requirements, wall thickness)
• [ ] Add thumbnail images or links to preview images for designs lacking them (e.g., Simple_CYD_Stand_Leg)

Add display configuration guide and hardware variant detection

There are two User_Setup.h files (DisplayConfig/User_Setup.h and DisplayConfig/CYD2USB/User_Setup.h) suggesting hardware variants, but no documentation explaining when to use which. The Examples lack guidance on which header to use. Create an automated detection helper and documentation to handle different CYD hardware revisions.

• [ ] Document in DisplayConfig/README.md the differences between standard CYD and CYD2USB hardware variants with pin differences
• [ ] Create a helper utility function to auto-detect hardware variant at runtime and validate pin configuration
• [ ] Update Examples/Basics/1-HelloWorld/1-HelloWorld.ino and other core examples with comments explaining which User_Setup.h applies
• [ ] Add troubleshooting section to README.md addressing common pin/display configuration issues for different hardware revisions

• Add integration tests for Rust display driver examples: Cargo.toml indicates active Rust development but no automated test suite visible; adding tests in src/ with simulated SPI would catch regressions
• Create setup.md guide for ESP32-2432S028R clone detection: README has decision tree image but no text walkthrough; documenting how to identify your specific board variant (pin configs, screen model, touch IC) would reduce support questions
• Expand Examples/AlternativeLibraries with LVGL or squareline-generated UI example: Current examples use low-level graphics libraries; adding a high-level UI framework example (like LVGL) would make CYD accessible to non-embedded developers

The codebase demonstrates good foundational security practices for an embedded systems project (no obvious SQL injection, XSS, or hardcoded secrets detected). However, several maintenance and configuration issues present medium-term risks: outdated Rust version, dependency incompatibility constraints preventing security updates, and missing security disclosure policies. The project would benefit from establishing a formal security vulnerability reporting process and implementing automated security scanning in CI/CD pipelines. No critical vulnerabilities were identified in the provided file structure, but regular dependency audits and version updates should be prioritized.

• Medium · Outdated Rust Version Requirement — Cargo.toml. The Cargo.toml specifies rust-version = '1.75', which is several versions behind the current stable Rust release. This may miss important security patches and compiler improvements available in newer versions. Fix: Update rust-version to a more recent stable version (1.80+) and regularly maintain it as new releases become available.
• Medium · Aggressive Optimization for Size in Release Builds — Cargo.toml [profile.release]. The release profile uses opt-level = 's' (optimize for size), which can disable certain safety optimizations and make debugging difficult in production. Combined with security-critical embedded code, this may increase vulnerability surface. Fix: Consider using opt-level = '2' or '3' for better security and performance balance, or justify the size optimization with documented trade-offs.
• Medium · Incompatible Dependency Pinning — Cargo.toml [dependencies]. The code contains a commented warning about incompatibility: display-interface 0.5.0 is incompatible with mipidsi 0.7.1. Currently pinned to older versions (0.4.1) due to upstream issue. This indicates potential security patches cannot be applied. Fix: Monitor https://github.com/almindor/mipidsi/pull/104 for resolution. Once merged, update to compatible versions to receive security updates.
• Low · Missing Security-Relevant Configuration Documentation — Repository root. No SECURITY.md file is present in the repository to document security policies, vulnerability reporting procedures, or security best practices for contributors. Fix: Create a SECURITY.md file with vulnerability disclosure policy, security contact information, and guidance for reporting security issues privately.
• Low · Hardcoded Display Configuration — DisplayConfig/User_Setup.h, DisplayConfig/CYD2USB/User_Setup.h. Display configuration files (User_Setup.h) may contain device-specific settings that could be used for fingerprinting or reconnaissance if exposed in compiled artifacts or documentation. Fix: Review configuration files for any sensitive parameters (API keys, credentials, etc.). Consider documenting which settings are safe to commit and which should be user-provided.
• Low · No Dependency Audit Configuration — .github/dependabot.yml, .github/workflows/. The repository uses Dependabot for dependency management but no evidence of regular security audits or cargo-audit integration in CI/CD workflows. Fix: Add 'cargo audit' step to CI/CD pipeline to detect known vulnerabilities in dependencies automatically.
• Low · Missing Code Signing or Integrity Verification — .github/workflows/. No evidence of signed releases or checksums for distributed artifacts. Users downloading binaries cannot verify authenticity or integrity. Fix: Implement signed releases using GitHub's built-in signing features and provide checksums/signatures for all distributed binaries.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.