Improve open-source docs and ESP-IDF examples

.editorconfig

@@ -0,0 +1,22 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{md,yml,yaml,json,js,ts,vue,html,css,scss}]
+indent_size = 2
+
+[*.{bat,cmd,ps1}]
+end_of_line = crlf
+
+[*.csv]
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+

.gitattributes

@@ -0,0 +1,20 @@
+* text=auto eol=lf
+
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.bin binary
+*.elf binary
+*.uf2 binary
+*.pcm binary
+*.gz binary
+*.zip binary
+*.tar binary
+*.tar.gz binary
+

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,66 @@
+name: Bug report
+description: Report a build, flash, runtime, or documentation issue
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: input
+    id: board
+    attributes:
+      label: Board
+      description: Include the exact Waveshare board name and revision if known.
+      placeholder: ESP32-P4-NANO
+    validations:
+      required: true
+  - type: input
+    id: example
+    attributes:
+      label: Example path
+      placeholder: examples/esp-idf/02_HelloWorld
+    validations:
+      required: true
+  - type: dropdown
+    id: framework
+    attributes:
+      label: Framework
+      options:
+        - ESP-IDF
+        - Arduino
+        - Other
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Framework version
+      placeholder: ESP-IDF v5.4.0 or Arduino-ESP32 v3.2.0
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What happened? What did you expect to happen?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Run ...
+        2. Configure ...
+        3. Build or flash ...
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: Paste build errors, serial output, or relevant command output.
+      render: text
+  - type: textarea
+    id: hardware
+    attributes:
+      label: Hardware setup
+      description: Include wiring, modules, display/camera model, power supply, or photos when relevant.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Waveshare support
+    url: https://www.waveshare.com/contact-us
+    about: Contact Waveshare for order-specific support.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,35 @@
+name: Feature request
+description: Suggest a new example, board note, or improvement
+title: "[Feature]: "
+labels:
+  - enhancement
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What would you like to add or improve?
+    validations:
+      required: true
+  - type: input
+    id: board
+    attributes:
+      label: Target board
+      placeholder: ESP32-P4-WIFI6-DEV-KIT
+  - type: input
+    id: area
+    attributes:
+      label: Area
+      placeholder: display, camera, Ethernet, LVGL, Arduino, documentation
+  - type: textarea
+    id: value
+    attributes:
+      label: Why this is useful
+      description: Explain the user problem or hardware workflow this would help.
+    validations:
+      required: true
+  - type: textarea
+    id: details
+    attributes:
+      label: Additional details
+      description: Add links, logs, screenshots, or implementation ideas.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,29 @@
+## Summary
+
+- 
+
+## Type of Change
+
+- [ ] Documentation
+- [ ] Bug fix
+- [ ] New example
+- [ ] Existing example improvement
+- [ ] Board support or configuration
+
+## Tested
+
+- [ ] Built with ESP-IDF
+- [ ] Flashed and tested on hardware
+- [ ] Tested with Arduino IDE or arduino-cli
+- [ ] Documentation-only change
+
+## Environment
+
+- Board:
+- ESP-IDF version or Arduino-ESP32 version:
+- Host OS:
+- Example path:
+
+## Notes
+
+Add logs, screenshots, wiring notes, or known limitations here.

.github/scripts/discover_esp_idf_examples.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""Discover ESP-IDF examples that should be built by CI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+EXAMPLES_ROOT = Path("examples/esp-idf")
+
+
+def run_git(args: list[str]) -> list[str]:
+    result = subprocess.run(
+        ["git", *args],
+        check=True,
+        text=True,
+        stdout=subprocess.PIPE,
+    )
+    return [line.strip() for line in result.stdout.splitlines() if line.strip()]
+
+
+def list_examples() -> list[str]:
+    if not EXAMPLES_ROOT.exists():
+        return []
+
+    examples = []
+    for path in EXAMPLES_ROOT.iterdir():
+        if (path / "CMakeLists.txt").is_file() and (path / "main").is_dir():
+            examples.append(path.as_posix())
+    return sorted(examples)
+
+
+def normalize_example(value: str) -> str:
+    value = value.strip().strip("/")
+    if not value:
+        return value
+    if value == "all":
+        return value
+    if value.startswith(EXAMPLES_ROOT.as_posix() + "/"):
+        return value
+    return (EXAMPLES_ROOT / value).as_posix()
+
+
+def discover_from_paths(paths: list[str], known_examples: set[str]) -> list[str]:
+    selected = set()
+    root_prefix = EXAMPLES_ROOT.as_posix() + "/"
+
+    for changed_path in paths:
+        changed_path = changed_path.strip().strip("/")
+        if not changed_path.startswith(root_prefix):
+            continue
+
+        parts = Path(changed_path).parts
+        if len(parts) < 3:
+            selected.update(known_examples)
+            continue
+
+        example = Path(*parts[:3]).as_posix()
+        if example in known_examples:
+            selected.add(example)
+
+    return sorted(selected)
+
+
+def discover_changed_examples(base_ref: str | None, head_ref: str, known_examples: set[str]) -> list[str]:
+    if base_ref:
+        diff_args = ["diff", "--name-only", f"{base_ref}...{head_ref}"]
+    else:
+        diff_args = ["diff-tree", "--no-commit-id", "--name-only", "-r", head_ref]
+
+    return discover_from_paths(run_git(diff_args), known_examples)
+
+
+def github_output(name: str, value: str) -> None:
+    output_path = os.environ.get("GITHUB_OUTPUT")
+    if output_path:
+        with open(output_path, "a", encoding="utf-8") as output:
+            output.write(f"{name}={value}\n")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--base-ref")
+    parser.add_argument("--head-ref", default="HEAD")
+    parser.add_argument("--example", default="")
+    parser.add_argument(
+        "--fallback-all",
+        action="store_true",
+        help="Build all examples when no changed example is detected.",
+    )
+    args = parser.parse_args()
+
+    known_examples = set(list_examples())
+    requested_example = normalize_example(args.example)
+
+    if requested_example == "all":
+        selected = sorted(known_examples)
+    elif requested_example:
+        if requested_example not in known_examples:
+            print(f"Unknown ESP-IDF example: {args.example}", file=sys.stderr)
+            print("Known examples:", file=sys.stderr)
+            for example in sorted(known_examples):
+                print(f"  {example}", file=sys.stderr)
+            return 1
+        selected = [requested_example]
+    else:
+        selected = discover_changed_examples(args.base_ref, args.head_ref, known_examples)
+        if args.fallback_all and not selected:
+            selected = sorted(known_examples)
+
+    matrix = {"example": selected}
+    matrix_json = json.dumps(matrix, separators=(",", ":"))
+    has_examples = "true" if selected else "false"
+
+    github_output("matrix", matrix_json)
+    github_output("has_examples", has_examples)
+    github_output("examples", ",".join(selected))
+
+    print(matrix_json)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())