diff --git a/.github/workflows/kibot.yml b/.github/workflows/kibot.yml deleted file mode 100644 index b2255b9..0000000 --- a/.github/workflows/kibot.yml +++ /dev/null @@ -1,32 +0,0 @@ -name: K1 Fab Pack - -on: - push: { branches: ["**"] } - pull_request: {} - workflow_dispatch: {} - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - name: Install KiCad & Dependencies - run: | - sudo apt-get update - sudo apt-get install -y kicad - - name: Install KiBot - run: | - pipx install kibot - - name: Generate Fab Artifacts from Committed Netlist - working-directory: hardware/k1-lightwave - run: | - mkdir -p _artifacts - # Use pre-generated netlist (k1_motherboard_revA.net) with KiBot - # KiBot will generate Gerbers, STEP, iBOM from the design - kibot -c kibot.yaml -d _artifacts -e kicad/K1_Lightwave.kicad_sch -b kicad/K1_Lightwave.kicad_pcb -v - echo "✅ Fab artifacts generated successfully" - - name: Upload Artifacts - uses: actions/upload-artifact@v4 - with: - name: fab-artifacts - path: hardware/k1-lightwave/_artifacts/ diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..8d968b6 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md index 96c21ca..9931204 100644 --- a/README.md +++ b/README.md @@ -1,395 +1,64 @@ -# K1 Lightwave: PCB Design & Manufacturing Platform +# K1.hardware -**Status:** ✅ **FULLY FUNCTIONAL** — Ready for hardware design kickoff +Agent-driven KiCad and PCB automation for K1-Lightwave hardware. ---- +This repository contains public tooling, MCP servers, reference material, and prototype automation used around the K1-Lightwave hardware workflow. Product PCB files, fabrication outputs, BOMs, and private design documents are not published in the public HEAD of this repository. -## What This Is +> [!NOTE] +> This public surface is being cleaned up for transfer into the SpectraSynq organisation. Some legacy prototype tooling is preserved for reference, but it should not be treated as a stable package API until it is extracted into a dedicated tool repository. -A **code-driven PCB design pipeline** built into Claude Code. Automates the entire hardware design workflow: +## Quickstart -``` -Design Intent → Spec → Schematic → Parts → Layout → Routing → Verification → Fab Package -``` - -**All steps are:** -- ✅ Automated via specialist agents -- ✅ Tracked in Git (reproducible) -- ✅ Validated with ERC/DRC (no surprises) -- ✅ Optimized for JLCPCB manufacturing - -**Time to manufacturing:** 4-6 hours for first design - ---- - -## Quick Start (5 Minutes) - -### 1. Prerequisites -```bash -# Install KiCad 8/9 -brew install kicad # macOS -# or download from kicad.org - -# Verify installation -kicad-cli --version -``` - -### 2. Setup MCP Servers -```bash -cd /Users/spectrasynq/Workspace_Management/Software/K1.hardware -python3 mcp/configure_claude.py - -# When prompted for credentials: -# - Leave blank if you don't have API keys -# - Paste credentials if you do (see SETUP_CREDENTIALS.md) -``` - -### 3. Reload Claude Code -- Close all Claude Code windows -- Reopen Claude Code -- MCP servers now available - -### 4. Start Designing -Ask in Claude Code: - -> "Design K1 Lightwave PCB: dual ESP32-S3, I2S microphone, WS2812B LEDs, 100×80mm form factor, JLCPCB standard class. Full design workflow." - -**That's it. The agent handles the rest.** - ---- - -## What You Get - -### 7 PCB Design Skills -| Skill | Purpose | -|-------|---------| -| **kicad-spec-extractor** | Design intent → YAML spec | -| **kicad-schematic-synthesizer** | SKiDL → KiCad schematic + ERC | -| **kicad-part-picker** | Symbol → footprint + BOM + sourcing | -| **kicad-pcb-synthesizer** | Netlist → board layout + stackup | -| **kicad-router-orchestrator** | FreeRouting autoroute + DSN/SES | -| **kicad-verification-drf** | DRC + DFM validation + thermal | -| **kicad-publisher-fabpack** | Gerbers + IPC-2581 + STEP + iBOM | - -### 3 Specialist Agents -| Agent | Triggers | Skills | -|-------|----------|--------| -| **PCB Hardware Designer** | `schematic`, `circuit`, `design`, `spec` | Spec + Schematic + Parts | -| **PCB Layout Specialist** | `layout`, `routing`, `placement`, `PCB` | Synthesis + Routing | -| **Hardware Validator** | `verify`, `manufacturing`, `DFM`, `DRC` | Verification + Publisher | - -### 7 MCP Servers -- **mcp-kicad-cli** — ERC/DRC/exports -- **mcp-nexar** — Component search + datasheets -- **mcp-lcsc** — JLC Assembly pricing -- **mcp-freerouting** — PCB autorouting -- **mcp-kikit** — Panelization + V-cuts -- **mcp-fabops** — Manufacturing pack generation -- **mcp-rag** — Knowledge retrieval (309 indexed chunks) - -### Knowledge Base (RAG) -- ESP32-S3 datasheets + hardware design guidelines -- JLCPCB manufacturing rules + DFM guidelines -- Power delivery + impedance + thermal design patterns -- Component selection + sourcing strategies - ---- - -## Project Structure - -``` -K1.hardware/ -├── README.md ← You are here -├── QUICKSTART.md ← 5-min setup + example workflow -├── SETUP_CREDENTIALS.md ← API credential setup -├── .claude/ -│ ├── K1_PCB_PIPELINE_ARCHITECTURE.md ← Complete architecture docs -│ └── skills/ -│ ├── kicad-spec-extractor/ -│ ├── kicad-schematic-synthesizer/ -│ ├── kicad-part-picker/ -│ ├── kicad-pcb-synthesizer/ -│ ├── kicad-router-orchestrator/ -│ ├── kicad-verification-drf/ -│ ├── kicad-publisher-fabpack/ -│ └── [10 reference skills: ESP-IDF, FastLED, FreeRTOS, etc.] -├── mcp/ -│ ├── configure_claude.py ← Run this to setup MCP -│ ├── verify-servers.py ← Check if everything works -│ ├── mcp-kicad-cli/ ← KiCad automation -│ ├── mcp-nexar/ ← Component search -│ ├── mcp-lcsc/ ← JLC pricing -│ ├── mcp-freerouting/ ← PCB routing -│ ├── mcp-kikit/ ← Panelization -│ ├── mcp-fabops/ ← Manufacturing -│ ├── mcp-rag/ ← Knowledge base -│ └── test_rag.py ← Test RAG system -├── docs/ -│ ├── prd/ ← Product requirements -│ ├── knowledge/ ← Design guidelines (RAG indexed) -│ │ ├── vendors/ ← Espressif, JLCPCB, etc. -│ │ └── tooling/ ← KiCad, KiKit, LCSC, etc. -│ └── datasheets/ ← PDF reference docs -├── hardware/ -│ └── k1-lightwave/ ← Design output (will be created) -│ ├── design-spec.yaml ← Generated design spec -│ ├── kicad/ -│ │ ├── k1_schematic.py ← SKiDL source -│ │ ├── k1_lightwave.kicad_sch ← Generated schematic -│ │ └── k1_lightwave.kicad_pcb ← Generated PCB layout -│ └── fab/ -│ ├── gerbers/ ← Manufacturing files -│ ├── k1_lightwave.ipc2581 ← Machine-readable spec -│ ├── k1_lightwave.step ← 3D model -│ └── k1_lightwave_bom.html ← Assembly reference -└── firmware/ ← (Future: firmware development) -``` - ---- - -## Workflow Overview - -### Phase 1: Specification (30 min) -**Agent:** PCB Hardware Designer -**Input:** Your design intent (high-level description) -**Output:** `design-spec.yaml` (structured, reviewable, Git-tracked) - -``` -User: "Dual ESP32-S3, I2S audio, WS2812B LEDs, compact form factor" -↓ -Agent: Extract spec, validate against manufacturing constraints -↓ -Output: design-spec.yaml ✅ -``` - -### Phase 2: Schematic Synthesis (2-4 hours) -**Agent:** PCB Hardware Designer -**Input:** `design-spec.yaml` -**Output:** `k1_lightwave.kicad_sch` (schematic), `k1_lightwave_bom.csv` (parts) - -``` -Spec Extractor: Convert to YAML ✅ -↓ -Schematic Synthesizer: Generate SKiDL + run ERC ✅ -↓ -Part Picker: Select parts + source + cost ✅ -``` - -### Phase 3: PCB Layout & Routing (3-6 hours) -**Agent:** PCB Layout Specialist -**Input:** Schematic + BOM -**Output:** `k1_lightwave.kicad_pcb` (routed design) - -``` -PCB Synthesizer: Create board file + stackup + placement ✅ -↓ -Router Orchestrator: FreeRouting autoroute ✅ -``` - -### Phase 4: Verification & Manufacturing (1-2 hours) -**Agent:** Hardware Validator -**Input:** Routed PCB -**Output:** Manufacturing package (Gerbers, IPC-2581, STEP, iBOM) - -``` -Verifier: DRC + DFM + thermal checks ✅ -↓ -Publisher: Generate Gerbers + fab package ✅ -``` - -### Phase 5: Manufacturing (2-4 weeks) -**You:** Order from JLCPCB - -``` -1. Go to jlcpcb.com -2. Upload fab/k1_lightwave_fab_package.zip -3. JLC auto-detects specs + component availability -4. Review BOM (pre-populated) -5. Place order -``` - ---- - -## Verification - -### Test Setup ```bash +git clone https://github.com/synqing/K1.hardware.git +cd K1.hardware python3 mcp/verify-servers.py -``` - -Expected output: -``` -✅ kicad-cli: found -✅ Python libraries: installed -✅ Java: available -✅ Claude config: exists -✅ RAG system: 309 chunks indexed - -🎉 All systems ready! -``` - -### Test RAG System -```bash python3 mcp/test_rag.py ``` -### Test in Claude Code -> "Search RAG for antenna design guidelines" - -Expected: Returns 3+ relevant results ✅ - ---- - -## Troubleshooting - -| Issue | Fix | -|-------|-----| -| `kicad-cli not found` | Install KiCad 8/9: `brew install kicad` | -| `ModuleNotFoundError` | Install libs: `pip install skidl pcbnew rank-bm25 beautifulsoup4 pypdf` | -| `MCP servers not available` | Run `configure_claude.py`, then reload Claude Code | -| `RAG system empty` | Run `python3 mcp/ingest_new_sources.py` | -| Agent doesn't activate | Use correct keywords; see `.claude/K1_PCB_PIPELINE_ARCHITECTURE.md` | - -See **SETUP_CREDENTIALS.md** for API credential issues. - ---- - -## Documentation - -| File | Purpose | -|------|---------| -| **QUICKSTART.md** | 5-minute setup + example workflow | -| **SETUP_CREDENTIALS.md** | Credential setup (Nexar, LCSC) | -| **`.claude/K1_PCB_PIPELINE_ARCHITECTURE.md`** | Complete architecture + design patterns | -| **`.claude/skills/*/SKILL.md`** | Individual skill documentation | -| **`docs/prd/`** | Product requirements + specifications | -| **`docs/knowledge/`** | Design guidelines (indexed by RAG) | - ---- - -## Key Technologies - -- **KiCad CLI** — ERC/DRC/exports (headless automation) -- **SKiDL** — Programmatic schematic generation -- **FreeRouting** — Automated PCB routing -- **BM25** — Semantic search over documentation -- **MCP** — Model Context Protocol (LLM ↔ tools) -- **Git** — Version control + audit trail +For Claude Code MCP setup, run: ---- - -## What's Next - -### Immediate (Now) -1. ✅ Run `python3 mcp/configure_claude.py` -2. ✅ Reload Claude Code -3. ✅ Verify with `python3 mcp/verify-servers.py` - -### Short-term (This Week) -1. Ask PCB Hardware Designer to design the board -2. Review generated files (Git history shows changes) -3. Ask Layout Specialist to route the PCB -4. Ask Validator to generate manufacturing package - -### Medium-term (Weeks 2-3) -1. Order PCBs from JLCPCB -2. Start firmware development (parallel) -3. Prepare assembly workflow - -### Long-term (Weeks 4-8) -1. PCBs arrive + assembly -2. Integration testing -3. Performance optimization -4. Enclosure design - ---- - -## Support - -### If Something Breaks -1. Check `mcp/DEPLOYMENT.md` (MCP troubleshooting) -2. Run `python3 mcp/verify-servers.py` (diagnostics) -3. Check Git history (`git log`) to see what changed -4. Review agent output (Claude Code shows all tool calls) - -### If You Get Stuck -1. Re-read `.claude/K1_PCB_PIPELINE_ARCHITECTURE.md` (complete reference) -2. Check QUICKSTART.md (example workflow) -3. Ask the agent directly for help - ---- - -## System Status - -``` -✅ Specification Framework: READY -✅ Schematic Synthesis: READY -✅ Part Selection & Sourcing: READY -✅ PCB Layout Engine: READY -✅ Automated Routing: READY -✅ Design Validation: READY -✅ Manufacturing Export: READY -✅ Knowledge Base (RAG): READY (309 chunks) -✅ MCP Infrastructure: READY (7 servers) -✅ Specialist Agents: READY (3 agents) -✅ Git Version Control: READY -✅ Documentation: READY - -🎉 SYSTEM FULLY FUNCTIONAL - Ready to design K1 Lightwave hardware +```bash +python3 mcp/configure_claude.py ``` ---- - -## Developer Guide - -This section provides instructions for setting up a development environment, running tests, and understanding the project's internal structure. +Some integrations need your own API credentials. See [SETUP_CREDENTIALS.md](docs/internal/legacy-root/SETUP_CREDENTIALS.md) for provider setup notes. -### Development Environment Setup +## What is here -1. **Clone the repository:** - ```bash - git clone https://github.com/your-repo/K1_Lightwave.git - cd K1_Lightwave - ``` +- **MCP servers** in [mcp/](mcp/) for KiCad CLI automation, KiKit, KiBot, SKiDL, FreeRouting, component sourcing, fab operations, and local RAG. +- **Agent modules** in [agent/](agent/) for DFM checks, KiCad helpers, routing, impedance, thermal modelling, and orchestration. +- **Tool prototypes** in [tools/](tools/), including the KiCad footprint hunter and the preserved Elite PCB Designer prototype. +- **Reference docs** in [docs/](docs/) for public tooling notes, vendor references, datasheets, and legacy implementation notes. -2. **Create a virtual environment:** - ```bash - python3 -m venv .venv - source .venv/bin/activate - ``` +## Repository layout -3. **Install dependencies:** - ```bash - pip install -r requirements.txt - ``` - -### Running Tests - -To run the test suite, use the following command: -```bash -python3 -m unittest discover -s tests +```text +K1.hardware/ +|-- agent/ Python modules for PCB automation workflows +|-- docs/ Public references and legacy notes +|-- mcp/ MCP servers used by agent-driven EDA workflows +|-- plugins/ KiCad plugin experiments +|-- tools/ +| |-- elite-pcb-designer/ Prototype routing, placement, and validation tooling +| `-- kicad-footprint-hunter/ Footprint discovery and board update utilities +|-- .github/ Workflow definitions retained for review +|-- .gitignore +|-- LICENSE +`-- README.md ``` -### Project Structure Overview - -- `elite_pcb_designer.py`: The main entry point and orchestrator for the PCB design process. -- `design_preparation.py`: Handles the initial loading and preparation of the design files. -- `component_placement.py`: Manages the intelligent placement of components. -- `automated_routing.py`: Orchestrates the automated routing process. -- `design_validation.py`: Performs final validation and generates manufacturing files. -- `tests/`: Contains the unit tests for the project. - ---- +## Working with the tools -## License & Credits +Use [mcp/verify-servers.py](mcp/verify-servers.py) to check local dependencies and MCP server availability. Use [mcp/test_rag.py](mcp/test_rag.py) to confirm the local RAG index can answer tooling queries. -K1 Lightwave design pipeline. Built with KiCad, Python, Claude AI, and open-source EDA tools. +The legacy Elite PCB Designer prototype now lives under [tools/elite-pcb-designer/legacy-pipeline/](tools/elite-pcb-designer/legacy-pipeline/). Run those scripts from that directory, and expect to provide your own KiCad input files. ---- +## Community and support -**Start designing now.** Ask the PCB Hardware Designer agent: +- [Issues](../../issues) for bugs, cleanup findings, and extraction candidates. +- [Discord](https://discord.gg/8y8rXegU8j) for SpectraSynq build discussion. -> "Design K1 Lightwave: dual ESP32-S3, I2S audio, WS2812B LEDs, 100×80mm form factor, JLCPCB standard." +## Licence -**Go.** 🚀 +Code is licensed under Apache-2.0; see [LICENSE](LICENSE). Documentation is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) unless a source document states otherwise. diff --git a/agent/__pycache__/__init__.cpython-312.pyc b/agent/__pycache__/__init__.cpython-312.pyc deleted file mode 100644 index b80dc39..0000000 Binary files a/agent/__pycache__/__init__.cpython-312.pyc and /dev/null differ diff --git a/agent/configs/__pycache__/__init__.cpython-312.pyc b/agent/configs/__pycache__/__init__.cpython-312.pyc deleted file mode 100644 index 0ca4cde..0000000 Binary files a/agent/configs/__pycache__/__init__.cpython-312.pyc and /dev/null differ diff --git a/agent/dfm/__pycache__/__init__.cpython-312.pyc b/agent/dfm/__pycache__/__init__.cpython-312.pyc deleted file mode 100644 index 0459a0f..0000000 Binary files a/agent/dfm/__pycache__/__init__.cpython-312.pyc and /dev/null differ diff --git a/agent/drivers/__pycache__/__init__.cpython-312.pyc b/agent/drivers/__pycache__/__init__.cpython-312.pyc deleted file mode 100644 index f124ce0..0000000 Binary files a/agent/drivers/__pycache__/__init__.cpython-312.pyc and /dev/null differ diff --git a/agent/impedance/__pycache__/__init__.cpython-312.pyc b/agent/impedance/__pycache__/__init__.cpython-312.pyc deleted file mode 100644 index 0c81051..0000000 Binary files a/agent/impedance/__pycache__/__init__.cpython-312.pyc and /dev/null differ diff --git a/agent/kicad/__pycache__/__init__.cpython-312.pyc b/agent/kicad/__pycache__/__init__.cpython-312.pyc deleted file mode 100644 index 31e6c90..0000000 Binary files a/agent/kicad/__pycache__/__init__.cpython-312.pyc and /dev/null differ diff --git a/agent/orchestrator/__pycache__/__init__.cpython-312.pyc b/agent/orchestrator/__pycache__/__init__.cpython-312.pyc deleted file mode 100644 index 2985a6c..0000000 Binary files a/agent/orchestrator/__pycache__/__init__.cpython-312.pyc and /dev/null differ diff --git a/agent/routing/__pycache__/__init__.cpython-312.pyc b/agent/routing/__pycache__/__init__.cpython-312.pyc deleted file mode 100644 index b3d6231..0000000 Binary files a/agent/routing/__pycache__/__init__.cpython-312.pyc and /dev/null differ diff --git a/agent/thermal/__pycache__/__init__.cpython-312.pyc b/agent/thermal/__pycache__/__init__.cpython-312.pyc deleted file mode 100644 index 2fa259e..0000000 Binary files a/agent/thermal/__pycache__/__init__.cpython-312.pyc and /dev/null differ diff --git a/docs/DESIGN_VALIDATION_SUMMARY.md b/docs/DESIGN_VALIDATION_SUMMARY.md deleted file mode 100644 index ba322ae..0000000 --- a/docs/DESIGN_VALIDATION_SUMMARY.md +++ /dev/null @@ -1,321 +0,0 @@ -# K1 Lightwave Rev-A — Design Validation & Manufacturing Readiness Summary - -**Status:** CLEARED FOR MANUFACTURING ✅ -**Date:** 2025-10-24 -**Validation Grade:** A- (93/100 architecture, 95% manufacturing readiness) -**Critical Issues Found & Fixed:** 3 (all resolved) - ---- - -## Executive Summary - -The K1 Lightwave dual-MCU LED controller design has completed comprehensive validation and is ready for manufacturing. Three critical bugs were identified in the initial SKiDL netlist and corrected before layout: - -1. **TPS62133 (BOOST) → TPS62160 (BUCK)** — Wrong converter type would have prevented 3.3V generation -2. **Si2301 (N-channel) → BSS84 (P-channel)** — Wrong FET topology broke ideal diode reverse-blocking -3. **INA226 Shunt Wiring** — Corrected to measure in series with high-side monitor - -All fixes have been applied, committed, and CI/CD pipeline is generating manufacturing artifacts. - ---- - -## Critical Design Fixes Applied - -### Fix #1: DC-DC Converter (TPS62133 → TPS62160) - -**Problem:** -- Initial design specified TPS62133 (synchronous step-up/BOOST converter) -- Board requires 5V USB input → 3.3V logic output -- BOOST converter would attempt to step up 5V input, creating invalid voltage - -**Impact:** -- 3.3V rail would never power up -- ESP32-S3 devices non-functional -- **Showstopper issue** - -**Fix Applied:** -```python -# File: hardware/k1-lightwave/skidl/k1_motherboard_revA.py (Line 104) -- u_buck = Part("Regulator_Switching", "TPS62133", ref="U2") -+ u_buck = Part("Regulator_Switching", "TPS62160", ref="U2") -``` - -**Specifications:** -- **Part:** TPS62160 (Texas Instruments) -- **Topology:** Synchronous step-down (BUCK) -- **Input:** 4.5–17V -- **Output:** Adjustable 0.6–13.2V (configured for 3.3V via feedback divider) -- **Output Current:** 1.5A max (sufficient for both MCUs + I2S + INA226) -- **Efficiency:** 92% typical @ 1A - ---- - -### Fix #2: Ideal Diode P-FET (Si2301 → BSS84) - -**Problem:** -- Initial design used Si2301 (N-channel MOSFET) -- LTC4412 ideal diode controller drives GATE low to TURN ON forward conduction -- N-channel FET gate-source topology: - - When gate pulled LOW: substrate body diode conducts instead (reverse current flows) - - **Protection fails: LED_5V can back-feed into VBUS_USB_5V** - -**Impact:** -- Power domain isolation broken -- USB host power contamination -- Potential current limiting circuit failure -- **Critical issue: risk of USB charger damage** - -**Fix Applied:** -```python -# File: hardware/k1-lightwave/skidl/k1_motherboard_revA.py (Lines 125-128) -- p_fet = Part("Transistor_FET", "Si2301", ref="Q1") -+ p_fet = Part("Transistor_FET", "BSS84", ref="Q1") - -# Drain/Source corrected for P-channel: -- p_fet["S"] += led_in_raw # Wrong: source on input side -- p_fet["D"] += led_5v # Wrong: drain on output side -+ p_fet["S"] += led_5v # Correct: source on output (LED_5V) -+ p_fet["D"] += led_in_raw # Correct: drain on input (raw input) -``` - -**P-Channel Ideal Diode Logic:** -- **Forward (Allow LED Power In):** - - External LED power present (LED_5V_RAW > VBUS_USB_5V) - - LTC4412 GATE pulled LOW - - P-FET turns ON (S-G voltage < threshold) - - Forward current flows: LED_5V_RAW → LED_5V_OUT -- **Reverse (Block USB Back-Feed):** - - Only USB power (VBUS_USB_5V) available - - LED_5V_RAW voltage drops to near-ground - - LTC4412 GATE releases HIGH (via pull-up) - - P-FET turns OFF (S-G voltage > threshold) - - **Substrate body diode CANNOT conduct** (cathode at gate, anode at source—no forward bias) - -**Specifications:** -- **Part:** BSS84 (Vishay Siliconix) -- **Type:** P-channel enhancement-mode MOSFET -- **Gate Threshold:** ±0.8V (typ) -- **Max Drain Current:** 1.6A @ 25°C -- **On-Resistance:** 3Ω @ VGS = -5V, ID = 1A -- **Package:** SOT-23-3 - ---- - -### Fix #3: INA226 Shunt Wiring (Series Measurement) - -**Problem:** -- Initial design connected 0.05Ω shunt to INA226 VIN- (after measurement point) -- VIN+ measured directly to LED_5V rail (no voltage drop across shunt) -- **Current monitoring fundamentally broken** — INA226 always measures 0A - -**Impact:** -- Firmware cannot measure LED current draw -- Thermal derate logic non-functional -- Power budget validation impossible -- Supply overcurrent condition undetected - -**Fix Applied:** -```python -# File: hardware/k1-lightwave/skidl/k1_motherboard_revA.py (Lines 140-142) -# Before (broken): -r_shunt[1] += u_ina226["VIN-"] # Shunt after measurement (wrong!) -r_shunt[2] += gnd -u_ina226["VIN+"] += led_5v # Direct measurement, no shunt voltage - -# After (correct - series measurement): -r_shunt[1] += led_5v # Input to shunt -r_shunt[2] += u_ina226["VIN+"] # VIN+ measures across shunt -u_ina226["VIN-"] += gnd -``` - -**INA226 High-Side Measurement Circuit:** -``` -LED_5V ─→ [Rshunt 0.05Ω] ─→ INA226[VIN+] - │ ↑ (voltage drop) - └─ INA226[VIN-] ─→ GND -``` - -**Measurement Characteristics:** -- **Shunt Value:** 0.05Ω ±1% (Yageo RL2512FK-0.05) -- **Full-Scale Voltage Drop:** 100mV @ 2A (within INA226 max range: 0–320mV) -- **Current Resolution:** 100mV / 0.05Ω = 2A / LSB = **1.22mA per digit** (12-bit) -- **Max Measurable Current:** 3.2A (before saturation) - ---- - -## Validation Results - -### Power Domain Isolation: A+ ✅ -- **Topology:** LTC4412 ideal diode controller + BSS84 P-FET -- **Isolation Method:** Passive reverse-blocking via P-FET body diode structure -- **Forward Drop:** <150mV @ 2A (within LTC4412 gate drive range) -- **Reverse Leakage:** <1 nA @ 5V (intrinsic P-FET leakage) -- **Test:** PASS — USB 5V isolated from external LED 5V -- **Status:** Ready for EVT - -### 3.3V Rail Power Quality: A ✅ -- **Converter:** TPS62160 synchronous buck -- **Load:** ESP32-S3 core (~500mA peak) + COM-A module (~400mA sustained) -- **Output Voltage Regulation:** ±2% @ 500mA (3.23–3.37V) -- **Transient Response:** <100mV overshoot @ 1A step load -- **EMI Filtering:** 10µF MLCC bulk capacitance on VCCB rail -- **Status:** Excellent — no power sequencing issues expected - -### SPI Inter-MCU Link (20–40 MHz): A ✅ -- **Data Rate:** 20–40 MHz SPI clock -- **GPIO Pins:** GPIO10 (SCK), GPIO11 (MOSI), GPIO12 (MISO), GPIO13 (CS) -- **Damping Resistors:** 33Ω series on A-side, 0Ω directly connected on B-side -- **Trace Routing:** <5mm total matched length (high school project specs, but sufficient) -- **CRC Validation:** 16-bit CRC on every payload (software error detection) -- **Handshake:** SYNC (A→B trigger) + READY (B→A ACK) status pins -- **Timing Margin:** 3× safety margin (40 MHz clock vs 120 MHz I/O capable) -- **Status:** Robust — no signal integrity issues anticipated - -### Microphone Path Validation: A ✅ - -**Default Build (3.3V SPH0645 I²S):** -- **Microphone:** PDM to I²S converter (onboard digital filtering, ~50dB SNR achievable) -- **Frequency Response:** 50 Hz–20 kHz (flat to ±3dB per spec) -- **Connectivity:** I²S directly from SoC GPIO (I²S0 data + clock on GPIO35/43) -- **No Level Shifting:** Direct 3.3V connection (SPH0645 native voltage) -- **Status:** ✅ Optimal configuration (lowest noise, no latency overhead) - -**Alternative Build (1.8V IM69D130 PDM):** -- **Microphone:** 1.8V direct PDM output -- **PDM Frequency:** 3.072 MHz (48 kHz × 64) or 6.144 MHz (48 kHz × 128) -- **Level Shifting:** SN74AXC2T245 (1.8V↔3.3V translator, 380 Mb/s capable) -- **Expected SNR:** ~63 dB(A) with TPS7A2018 LDO noise floor -- **Caveat:** Requires matched-length PDM clock + data traces (includes 22Ω + 10µF RC filter if using) -- **Status:** ⚠️ DNP by default (requires deliberate BOM selection for 1.8V variant) - -### LED Output Protection: A- ✅ -- **Topology:** TVS diode (5.5V clamp) + 330Ω series damping per port -- **TVS Diode:** SMAJ5.0A (Littelfuse, <1 pF parasitic capacitance) -- **Clamp Voltage:** 5.5–6.0V @ 10A (protects WS2812B: max 5.5V absolute) -- **Data Line Impedance:** 330Ω + ~150Ω transmission line = ~480Ω character (0.6–0.7V differential) -- **Polyfuse Protection:** 0.75A slow-blow per port (4× ports = 3A aggregate max) -- **Status:** Conservative design — exceeds WS2812B electrical requirements - -### ESD Compliance: A+ ✅ -- **USB Type-C Protection:** TPD4E05U06 (TechPublic) - - Configuration: 4-channel ESD diode array - - Parasitic Capacitance: <0.5pF (USB2.0 HS compliant) - - Clamp Voltage: 5.5V (compliant with USB Power Delivery spec) - - Human Body Model (HBM): ±8 kV minimum -- **I2C/I2S Pull-Ups:** 10kΩ (limited surge current on open-drain lines) -- **Status:** ✅ Meets USB Type-C ESD class 3B spec - -### Manufacturing Readiness: B+ ✅ -- **LCSC Availability:** 100% of 39 components in stock (as of 2025-10-24) -- **Lead Time:** 5–10 business days (JLCPCB standard SMD assembly) -- **Assembly Complexity:** Low (largest pitch: 0.4mm UQFN-10 for SN74AXC2T245) -- **Cost per Unit:** ~$95 (5-unit batch), ~$40 (50+ units) -- **DFM Issues:** 0 (design meets JLCPCB 4-layer specs) -- **V-Cut Panelization:** Clearance verified ≥0.4mm from copper edges -- **Status:** ✅ Ready for immediate PCB order - ---- - -## Component Risk Assessment - -### Moderate Risks (Mitigable) - -**1. LTC4412 Current Headroom** -- Specified max: 2.6A -- Peak design requirement: 3.0A (300 LEDs @ 100% white, worst case) -- Mitigation: - - Polyfuses limit to ~2.2A aggregate (4× 0.75A ports) - - Thermal validation will characterize actual losses - - Firmware brightness capping to 180/255 recommended - -**2. Microphone SNR @ 1.8V** -- Spec: 65 dB(A) minimum -- 1.8V IM69D130 achieves: ~63 dB(A) with TPS7A2018 LDO noise floor -- Mitigation: - - Default to 3.3V SPH0645 (guaranteed 65+ dB(A)) - - If 1.8V needed: add RC low-pass filter (22Ω + 10µF) on LDO output - -**3. LED Polyfuse vs Throughput** -- Polyfuse rated: 0.75A per port -- Design supports: 300 LEDs × 4 ports @ 60 FPS -- Reality: Polyfuse is protection device, not throughput bottleneck - - 300 LEDs @ 100% white = ~500mA per port - - 300 LEDs @ 60% white = ~300mA per port (well within fuse spec) -- Mitigation: - - Firmware brightness cap to 180/255 per channel (safe margin) - - Thermal validation will confirm power budget - -### Low Risks (Standard Practice) -- UQFN-10 0.4mm pitch: Standard SMD assembly (no hand-soldering needed) -- VSSOP-10 0.5mm pitch: Standard for analog ICs (good yield) -- SOT-23-5 packages: High-volume commodity (>99% first-pass) - ---- - -## Pre-Manufacturing Checklist - -- [x] SKiDL netlist generated and validated -- [x] KiCad schematic symbols defined (custom lib with LCSC properties) -- [x] PCB board outline and layer stackup confirmed (100×70mm, 1.6mm FR-4) -- [x] Net classes defined per design (LED_POWER, VBUS, LED_DATA, I2C, USB) -- [x] Design Rule Check (DRC) configured for JLCPCB spec -- [x] BOM finalized with LCSC C-numbers (39 components, 100% available) -- [x] Alternative components identified for EOL risk mitigation -- [x] CI/CD pipeline configured for automated Gerber/STEP/iBOM generation -- [x] Design validation report completed (A- grade) -- [x] Manufacturing package documentation prepared - ---- - -## Next Steps - -### Before Ordering PCB (Immediate) -1. **Confirm Microphone Build:** 3.3V SPH0645 (default) or 1.8V IM69D130 (DNP) -2. **Confirm LED Throughput:** 300 LEDs confirmed @ 60 FPS sufficient? -3. **Download Gerber Files:** Wait for CI/CD artifacts, validate with JLCPCB online viewer -4. **Generate iBOM:** Verify all LCSC C-numbers match latest stock - -### During PCB Order (JLCPCB) -1. Upload Gerber ZIP file -2. Enable ENIG finish + V-cut panelization -3. Select component assembly (standard SMD) -4. Review iBOM for missing/DNP components -5. Approve First Article Inspection (recommended, +$50) - -### During Bring-Up (First Board) -1. **Priority 1:** Smoke test (power rails, no shorts) -2. **Priority 2:** I2C/SPI verification (clock frequencies match spec) -3. **Priority 3:** Thermal validation (FLIR scan @ 300 LEDs, 100% white) -4. **Issue Resolution:** Any failures → design revision analysis - ---- - -## Design Grade Breakdown - -| Category | Score | Notes | -|----------|-------|-------| -| **Power Distribution** | A+ | LTC4412 ideal diode + TPS62160 buck — excellent isolation & regulation | -| **Signal Integrity** | A | SPI @ 40 MHz with 3× timing margin — robust inter-MCU link | -| **Protection & Safety** | A+ | TVS + polyfuse + ESD comply with spec; reverse-blocking verified | -| **Component Selection** | A | All parts in stock; minimal EOL risk; proven volume suppliers | -| **Thermal Design** | B+ | Pending EVT validation; conservative headroom predicted | -| **Manufacturing DFM** | B+ | JLCPCB compliant; V-cut verified; 0 DRC violations | -| **Documentation** | A | Complete BOM, symbols, errata, bring-up plan prepared | -| **Overall Grade** | **A-** | **93/100 — Cleared for manufacturing** | - ---- - -## References - -- **SKiDL Netlist:** `hardware/k1-lightwave/skidl/k1_motherboard_revA.py` -- **KiCad Symbols:** `hardware/k1-lightwave/kicad/k1_custom_ic.kicad_sym` -- **BOM with LCSC:** `docs/bom/K1_Lightwave_RevA_LCSC_Default.csv` -- **Design DRC Rules:** `hardware/k1-lightwave/kicad/design_rules.kicad_dru` -- **Errata & Fixes:** `docs/ERRATA_REV-A_VALIDATED.md` -- **Manufacturing Package:** `docs/MANUFACTURING_PACKAGE.md` - ---- - -**Status:** ✅ **CLEARED FOR MANUFACTURING** -**Validation Date:** 2025-10-24 -**Next Milestone:** PCB Order (within 1 week for EVT) diff --git a/docs/ERRATA_REV-A_VALIDATED.md b/docs/ERRATA_REV-A_VALIDATED.md deleted file mode 100644 index 6439297..0000000 --- a/docs/ERRATA_REV-A_VALIDATED.md +++ /dev/null @@ -1,199 +0,0 @@ -# K1 Lightwave Rev-A — Design Verification Errata & Fixes - -**Status:** VALIDATED (95% manufacturing readiness, A- architecture grade) -**Date:** 2025-10-24 -**Source:** Deep-technical-analyst + Architect-review specialist agents - ---- - -## Critical Errata Found & Fixed - -### 1. **Board Dimensions Conflict** (CRITICAL) - -**Issue:** PRD states "100×70mm baseline" (Section §152 mentions 100×70mm working area) but original KiCad files may reference different dimensions. - -**Fix Applied:** -- KiCad board outline: **100×70mm confirmed** -- Working area (excluding fiducials/rails): **100×60mm** -- Panel minimum (JLCPCB V-cut rule): **70×70mm** met ✅ - -**Action:** All documentation updated to reflect 100×70mm. No layout changes required. - ---- - -### 2. **DRC Edge Clearance Rule Missing** (MODERATE) - -**Issue:** V-cut clearance rule (0.4mm copper from Edge.Cuts) not enforced in `design_rules.kicad_dru`. - -**Fix Applied:** -Added to `hardware/k1-lightwave/kicad/design_rules.kicad_dru`: -```python -# Edge clearance: 0.5mm best-practice (JLCPCB minimum 0.4mm) -[edge_clearance] -value = 0.50mm # Conservative margin -``` - -**Action:** Apply DRC before panelization to catch near-edge traces. - ---- - -### 3. **FabOps iBOM Generation Bug** (MODERATE) - -**Issue:** Line 345 in `mcp/mcp-fabops/server.py` generates iBOM from **panel** instead of **single board**, resulting in incorrect component density counts. - -**Original (Line 345):** -```python -ibom_res = ibom_from_kicad(panel_pcb, ...) # WRONG: uses panel netlist -``` - -**Fix Applied:** -```python -ibom_res = ibom_from_kicad(board_kicad_pcb, ...) # CORRECT: uses single board -``` - -**Action:** Commit fix to fabops server immediately. - ---- - -### 4. **Thermal Validation Plan Missing** (MODERATE) - -**Issue:** Bring-up plan lacks thermal validation under load (300 LEDs @ 100% white = ~7.5W continuous). - -**Fix Applied:** Added to bring-up sequence: - -**Priority 3B: Thermal Validation (30 min)** -- Populate 300× WS2812B test strip -- Set to 100% white (255,255,255) all channels -- Soak for 15 minutes -- FLIR scan: measure junction temps - - Acceptance: **<70°C** (safe headroom for INA226 shunt 0.05Ω @ 3A) - - Warning: **60–70°C** (firmware brightness capping recommended) - - Reject: **>70°C** (LTC4412 overheat risk, redesign) - ---- - -### 5. **I2S/PDM Clock Frequency Verification Missing** (MINOR) - -**Issue:** Bring-up plan doesn't explicitly verify clock frequencies match ESP-IDF spec. - -**Fix Applied:** Added validation step: - -**Priority 2B: PDM/I2S Clock Verification (10 min)** -- PDM (if 1.8V mic): Measure clock frequency on GPIO12 - - Expected: **3.072 MHz** (48 kHz × 64) or **6.144 MHz** (48 kHz × 128) - - Tolerance: ±5% (2.92–3.22 MHz or 5.84–6.45 MHz) -- I2S (if 3.3V SPH0645): Measure BCLK on GPIO43 (from COM-A) - - Expected: **1.536 MHz** (mono) or **3.072 MHz** (stereo) @ 48 kHz - - Use logic analyzer to verify phase alignment with LRCK - ---- - -## Verification Summary - -| Criterion | Grade | Status | Notes | -|-----------|-------|--------|-------| -| **Power Domain Isolation** | A+ | ✅ PASS | LTC4412 + Si2301 topology verified | -| **SPI Inter-MCU (20–40 MHz)** | A | ✅ PASS | GPIO10/11/12/13 IO_MUX native, 3× margin | -| **Microphone Path (3.3V/1.8V)** | A | ✅ PASS | SN74AXC2T245 @ 380 Mb/s (63× headroom) | -| **LED Protection Chain** | A- | ✅ PASS | TVS clamp 5.5–6.0V within spec | -| **ESD Compliance** | A+ | ✅ PASS | TPD4E05U06 <0.5pF USB2.0 compliant | -| **Manufacturing Readiness** | B+ | ✅ PASS | 95% (LCSC 100%, assembly 95%, thermal 90%) | -| **Panelization & DFM** | B+ | ⚠️ FIX | 0.4mm V-cut clearance OK; edge DRC added | -| **FabOps CI/CD** | A- | ⚠️ FIX | iBOM bug fixed (panel→board) | -| **Bring-Up Plan** | B+ | ⚠️ UPDATED | Thermal + clock validation added | - ---- - -## Component Risk Assessment - -### Moderate Risks (Mitigable) - -**1. LTC4412 Current Headroom (2.6A vs 3.0A peak)** -- Polyfuses (0.75A per port × 4) limit peak to ~2.2A aggregate -- Thermal validation will confirm margins -- Mitigation: Firmware brightness capping if 60–70°C - -**2. Microphone SNR @ 1.8V (~63 dB(A) vs 65 dB(A) spec)** -- Default to 3.3V SPH0645 (guaranteed 65 dB(A)) -- If 1.8V required: add RC filter (22Ω + 10µF) on TPS7A2018 output -- Mitigation: Recommend 3.3V build; test SNR in EVT if 1.8V needed - -**3. LED Polyfuse vs Throughput Spec (0.75A fuse for 555 LED spec)** -- Polyfuse is protection, not throughput limit -- Real test: 300×WS2812B @ 60 FPS requires ~500 mA -- Mitigation: Firmware brightness cap to 180/255 per channel (safe margin) - -### Low Risks (Standard Practice) - -- UQFN-10 0.4mm pitch: automated SMD assembly recommended -- VSSOP-10 0.5mm pitch: standard for ICs -- SOT-23-5 footprint: high-volume standard - ---- - -## Alternative Components (If EOL) - -| Component | Selected | Alternative | LCSC | Notes | -|-----------|----------|-------------|------|-------| -| LTC4412 | LTC4412ES6 | LTC4411 | (check) | Monolithic, 2.6A (drop-in) | -| TPD4E05U06 | C2827646 | DOWO C22390021 | C22390021 | Tech Public equivalent | -| TPS7A2018 | C963430 | TPS7A2018PDQNR | C2878130 | X2-SON alt package | -| W25Q128JV | C106277 | GD25Q128C | C4245 | GigaDevice QSPI compat | -| SN74AHCT125 | C2860479 | CD74HC125E | C15413 | Slower alt (FYI) | - ---- - -## Recommended Next Steps - -### Immediate (Before PCB Layout) - -1. ✅ **Confirm microphone build preference** - - Recommendation: **3.3V SPH0645** (no translator, 65 dB(A) guaranteed) - - Alternative: 1.8V IM69D130 (requires SN74AXC2T245, ~63 dB(A) with LDO noise) - -2. ✅ **Confirm LED throughput requirement** - - Design supports 300 LEDs × 4 ports @ 60 FPS - - If >555 total: firmware brightness cap needed - -3. ✅ **Confirm manufacturing volume** - - <500 units: simplify BOM, single 3.3V mic path - - 500–5000: keep dual-path, leverage modular assembly - -### During PCB Layout - -4. ✅ **Use net classes per design spec** - - LED_POWER: 2.00mm trace, 1.60mm via - - VBUS: 0.80mm trace, 1.20mm via - - LED_DATA: 0.30mm trace, 0.80mm via - -5. ✅ **Enforce DRC rules** - - Copper ≥0.5mm from Edge.Cuts - - SPI traces <5mm total length - - I2S matched-length (±5mm skew) - -6. ✅ **Verify V-cut panelization** - - Use KiKit for automated v-cut + rails + fiducials - - Minimum panel: 70×70mm (K1 is 100×70mm, supports 2×2 grid minimum) - -### Before Ordering PCB - -7. ✅ **Final validation** - - ERC: 0 violations - - DRC: 0 violations - - Export Gerbers, preview with JLCPCB online viewer - - Confirm BOM via KiKit JLC assembly check - ---- - -## References - -- **Deep-Technical-Analysis Report:** `/docs/K1_ANALYSIS_TECHNICAL_REPORT.md` (1,141 lines) -- **Architecture Review Report:** `/docs/K1_LIGHTWAVE_REV-A_ARCHITECTURE_REVIEW.md` (22 pages) -- **BOM with LCSC Numbers:** `/docs/bom/K1_Lightwave_RevA_LCSC_Default.csv` -- **Custom Symbol Library:** `/hardware/k1-lightwave/kicad/k1_custom_ic.kicad_sym` - ---- - -**Version:** 1.0 VALIDATED -**Grade:** A- (93/100 architecture, 95% mfg readiness) -**Status:** ✅ **CLEARED FOR LAYOUT** diff --git a/docs/MANUFACTURING_PACKAGE.md b/docs/MANUFACTURING_PACKAGE.md deleted file mode 100644 index c3ff545..0000000 --- a/docs/MANUFACTURING_PACKAGE.md +++ /dev/null @@ -1,193 +0,0 @@ -# K1 Lightwave Rev-A — Manufacturing Package for JLCPCB - -**Status:** Ready for submission -**Board:** K1 Lightwave (Dual-MCU LED Controller) -**Dimensions:** 100×70mm (4-layer FR-4) -**PCB Finish:** ENIG -**Assembly:** Full JLCPCB standard + $5 panelization (V-cut rails) - ---- - -## 📋 Manufacturing Files - -### Gerber Files (`fab/gerbers/`) -- `K1_Lightwave_revA-F.Cu.gbr` — Front copper -- `K1_Lightwave_revA-B.Cu.gbr` — Back copper -- `K1_Lightwave_revA-F.Paste.gbr` — Front solder paste -- `K1_Lightwave_revA-B.Paste.gbr` — Back solder paste -- `K1_Lightwave_revA-F.Mask.gbr` — Front solder mask -- `K1_Lightwave_revA-B.Mask.gbr` — Back solder mask -- `K1_Lightwave_revA-Edge.Cuts.gbr` — Board outline + V-cut -- `K1_Lightwave_revA-Dwgs.User.gbr` — Assembly drawings (fiducial, test points) - -### Drill Files (`fab/drill/`) -- `K1_Lightwave_revA.drl` — Standard drill file -- `K1_Lightwave_revA.xln` — Excellon format (auto-generated) - -### Assembly Documentation -- **iBOM:** `docs/ibom/K1_Lightwave_revA_iBOM.html` — Interactive BOM (LCSC C-numbers, MPN, qty, refs) -- **BOM CSV:** `docs/bom/K1_Lightwave_RevA_LCSC_Default.csv` — Machine-readable (39 components) - -### 3D Models -- `mechanical/K1_Lightwave_revA.step` — STEP model (mechanical integration) -- `mechanical/K1_Lightwave_revA.glb` — GLB mesh (web preview) - ---- - -## 🎯 JLCPCB Submission Checklist - -### Step 1: PCB Order -1. Upload Gerber ZIP to JLCPCB online viewer -2. **Settings:** - - Layers: 4 - - Dimensions: 100×70mm - - Material: FR-4 (TG170-200) - - Thickness: 1.6mm - - Copper Weight: 1 oz (35 µm) - - Surface Finish: **ENIG** (Gold: 0.05 µm min) - - Mask Color: Black (for aesthetics; green acceptable) - - Silk Color: White - - Via Tenting: No - - Fiducials: Pre-populated (3 marks included in Dwgs.User) - - V-cut: **Enable** (clearance already verified: ≥0.4mm from copper) - -3. **DFM Check:** - - JLCPCB online viewer will validate all clearance rules - - Expected: 0 violations (design uses 0.127mm minimum trace-to-trace per JLCPCB 4-layer spec) - - **Proceed if:** All green checks pass - -4. Order quantity: **Recommend 5-10 units for EVT** (low-cost, high-volume pricing ~$50-100 total) - ---- - -### Step 2: Assembly Order (JLCPCB Standard) - -1. Upload iBOM to JLCPCB assembly portal -2. **Material Sourcing:** - - JLCPCB stock: **100% (all 39 components in stock as of 2025-10-24)** - - Verify against `docs/bom/K1_Lightwave_RevA_LCSC_Default.csv` - - Alternates provided for EOL risk mitigation (see ERRATA_REV-A_VALIDATED.md) - -3. **Assembly Service:** - - Standard SMD assembly (no selective soldering needed) - - **Estimated cost:** ~$50–$80/unit labor (5-unit batch) - - Component cost: ~$25–$35/unit (C-count: 39 SMD + 0 THT) - -4. **Panelization (Optional but Recommended):** - - JLCPCB can apply V-cut rails automatically - - Cost: +$5 for full panel - - Board count: 2×2 minimum (4 units from single panel) - - Use KiKit output (`panelized_revA.kicad_pcb`) if available - -5. **Quality Assurance:** - - AOI: Automated Optical Inspection (included) - - X-ray: Optional ($0.50/unit, useful for BGAs—not needed here) - - Functional test: Optional ($2/unit, good for production runs) - ---- - -### Step 3: Bring-Up & Validation - -**Priority 1: Smoke Test (5 min)** -- Bare board inspection: Check solder bridges, shorts -- Power-on (USB 5V, no load): Measure VBUS_USB_5V and LED_5V rails - - VBUS_USB_5V: 4.8–5.2V ✓ - - LED_5V (via ideal diode): Only present when external power connected ✓ -- 3.3V rail (via TPS62160): 3.15–3.45V ✓ - -**Priority 2A: I2C & Microphone Path (15 min)** -- SDA/SCL pull-ups: Verify with logic analyzer @ 400 kHz (standard I2C) -- INA226 I2C scan: Should respond at address 0x40 (A0/A1 pins = GND) -- PDM/I2S clock (if microphone installed): See ERRATA_REV-A_VALIDATED.md lines 81–87 - -**Priority 2B: SPI Inter-MCU Link (10 min)** -- Program both MCUs with test firmware (available in firmware/ directory) -- SPI SCK frequency: 20–40 MHz (measure with scope on GPIO10) -- CRC-16 validation: Ensure packets exchange cleanly - -**Priority 3A: LED Output (15 min)** -- Populate 1× test LED strip (4× strips × 10 LEDs = 40 total for low-power test) -- Set to 100% white (255,255,255) on one port -- Verify data line clock @ ~800 kHz (WS2812B bitrate) -- Power consumption: ~0.6W for 40 LEDs @ 100% white - -**Priority 3B: Thermal Validation (30 min) — HIGH IMPORTANCE** -- Populate full 300× LED test strip (or use current-limited load) -- Set to 100% white on all 4 ports simultaneously -- Soak for 15 minutes -- FLIR thermal scan: - - **Target:** <70°C junction temp (LTC4412 safe headroom) - - **Acceptable:** 60–70°C (firmware brightness cap may be needed) - - **Reject:** >70°C (redesign required) - ---- - -## 📊 Design Validation Grade - -| Criterion | Grade | Status | Notes | -|-----------|-------|--------|-------| -| **Power Domain Isolation** | A+ | ✅ PASS | LTC4412 + BSS84 ideal diode verified | -| **SPI Inter-MCU (20–40 MHz)** | A | ✅ PASS | GPIO10/11/12/13 IO_MUX native, 3× margin | -| **Microphone Path (3.3V/1.8V)** | A | ✅ PASS | SN74AXC2T245 @ 380 Mb/s (63× headroom) | -| **LED Protection** | A- | ✅ PASS | TVS clamp 5.5–6.0V within spec | -| **ESD Compliance** | A+ | ✅ PASS | TPD4E05U06 <0.5pF USB2.0 compliant | -| **Manufacturing Readiness** | B+ | ✅ PASS | 95% (LCSC 100%, assembly 95%, thermal 90%) | -| **DFM Clearance** | B+ | ✅ PASS | V-cut verified, edge DRC 0.5mm margin | - -**Overall Grade:** A- (93/100 architecture, 95% mfg readiness) -**Status:** ✅ **CLEARED FOR MANUFACTURING** - ---- - -## 💰 Cost Estimate (5-Unit Order) - -| Item | Unit Cost | Qty | Total | -|------|-----------|-----|-------| -| PCB (JLCPCB, 4-layer ENIG) | $2.50 | 5 | $12.50 | -| Component Assembly | $60.00 | 5 | $300.00 | -| BOM (39 components @ ~$6.50/unit) | $32.50 | 5 | $162.50 | -| **Subtotal** | | | **$475** | -| **Per-Unit Cost** | | | **$95** | - -*Note: Bulk pricing (50+ units) reduces per-unit cost to ~$40–$50.* - ---- - -## 🚨 Critical Notes for Manufacturing - -1. **Microphone Configuration:** Design supports two builds: - - **Default (Recommended):** 3.3V SPH0645 I²S (no level shifter) - - **Alt:** 1.8V IM69D130 PDM (requires SN74AXC2T245 translator, DNP by default) - - **Action:** Confirm build before assembly - -2. **LED Current Limiting:** Polyfuses (0.75A per port) are protective, not throughput limits - - Design supports 300 LEDs @ 60 FPS - - Firmware brightness capping at 180/255 recommended for thermal margin - -3. **Thermal Validation is Mandatory** (see Priority 3B above) - - Board behavior at 7.5W continuous (300 LEDs @ 100% white) not yet characterized - - Could reveal need for: - - Larger heat sink on LTC4412 - - Firmware thermal derate - - PCB routing changes - -4. **First Article Inspection (FAI):** Recommended - - X-ray void check on LTC4412 solder - - 100% electrical test (all nets, shorts, opens) - - Estimated cost: +$50 (one-time) - ---- - -## 📑 References - -- **PCB Design Files:** `hardware/k1-lightwave/kicad/` -- **BOM with LCSC:** `docs/bom/K1_Lightwave_RevA_LCSC_Default.csv` -- **Validation Report:** `docs/ERRATA_REV-A_VALIDATED.md` -- **Custom Symbols:** `hardware/k1-lightwave/kicad/k1_custom_ic.kicad_sym` -- **Bring-Up Plan:** `docs/K1_BRING_UP_PLAN.md` (if available) - ---- - -**Prepared by:** Claude Code -**Date:** 2025-10-24 -**Status:** Ready for submission ✅ diff --git a/docs/bom/K1_Lightwave_RevA_LCSC_Default.csv b/docs/bom/K1_Lightwave_RevA_LCSC_Default.csv deleted file mode 100644 index f93f463..0000000 --- a/docs/bom/K1_Lightwave_RevA_LCSC_Default.csv +++ /dev/null @@ -1,44 +0,0 @@ -Reference,Value,Footprint,LCSC,Manufacturer,MPN,Description,Qty,Notes -U1,TPD4E05U06,Package_DFN_QFN:DFN-10_3x3mm_P0.5mm,C2827646,TechPublic,C2827646,USB Type-C ESD protection 4-ch <0.5pF,1,Alt: DOWO C22390021 -U2,TPS62133,Package_BGA:BGA-21_3.5x3.5mm_P0.5mm,C3100,Texas Instruments,TPS62133RSMR,5V→3.3V buck ≥2A,1,VQFN-20 -U3,SN74AHCT125,Package_SO:SOIC-14_3.9x8.7mm_P1.27mm,C2860479,Texas Instruments,SN74AHCT125D,Quad TTL buffer 5V,1,LED output level shifter -U5,LTC4412ES6#TRMPBF,Package_TO_SOT_SMD:TSOT-23-6,C459883,Analog Devices,LTC4412ES6#TRMPBF,Ideal diode controller (monolithic),1,Prevents LED_5V back-feed -U7,INA226AIDGSR,Package_SO:VSSOP-10_3x3mm_P0.5mm,C49851,Texas Instruments,INA226AIDGSR,I2C current monitor 36V,1,LED_5V shunt: 0.05Ω -U8,SN74AXC2T245RSW,Package_DFN_QFN:UQFN-10_1.8x1.4mm_P0.40mm,C1882550,Texas Instruments,SN74AXC2T245RSW,Dual-bit 1.8↔3.3V translator,1,DNP if using 3.3V SPH0645 -U9,TPS7A2018PDBVR,Package_TO_SOT_SMD:SOT-23-5,C963430,Texas Instruments,TPS7A2018PDBVR,Fixed 1.8V LDO low-noise,1,"DNP unless 1.8V mic build; Alt: C2878130 (X2-SON)" -Q1,Si2301,Package_TO_SOT_SMD:SOT-23-3,C2852439,Vishay Siliconix,Si2301DS,P-FET 20V 1.6A (ideal diode gate),1,Pair with LTC4412 -R1,5.1k,Resistor_SMD:R_0603_1608Metric,C21196,Yageo,RC0603FR-075K1L,USB CC1 pull-down,1, -R2,5.1k,Resistor_SMD:R_0603_1608Metric,C21196,Yageo,RC0603FR-075K1L,USB CC2 pull-down,1, -R3,10k,Resistor_SMD:R_0603_1608Metric,C25804,Yageo,RC0603JR-1010KL,EN pull-up,1, -R4,10k,Resistor_SMD:R_0603_1608Metric,C25804,Yageo,RC0603JR-1010KL,BOOT pull-up,1, -R5,10k,Resistor_SMD:R_0603_1608Metric,C25804,Yageo,RC0603JR-1010KL,FLASH I/O2 pull-up,1, -R6,10k,Resistor_SMD:R_0603_1608Metric,C25804,Yageo,RC0603JR-1010KL,FLASH I/O3 pull-up,1, -R7,0.05,Resistor_SMD:R_2512_6332Metric,C21090,Yageo,RL2512FK-0.05,INA226 shunt (3A range),1,"High-power 2512; 100mV @ 3A" -RLED1,330,Resistor_SMD:R_0603_1608Metric,C25089,Yageo,RC0603JR-07330RL,LED1 data series damping,1, -RLED2,330,Resistor_SMD:R_0603_1608Metric,C25089,Yageo,RC0603JR-07330RL,LED2 data series damping,1, -RLED3,330,Resistor_SMD:R_0603_1608Metric,C25089,Yageo,RC0603JR-07330RL,LED3 data series damping,1, -RLED4,330,Resistor_SMD:R_0603_1608Metric,C25089,Yageo,RC0603JR-07330RL,LED4 data series damping,1, -R_PDM_CLK_SER,33,Resistor_SMD:R_0603_1608Metric,C23304,Yageo,RC0603FR-0733RL,PDM clock series damping,1,Minimize ringing @ multi-MHz -R_BYPASS_CLK,0,Resistor_SMD:R_0603_1608Metric,C319524,Unbranded,0603-0Ω,Direct PDM CLK (3.3V build),1,"DNP for 1.8V; stuff for 3.3V SPH0645" -R_BYPASS_DATA,0,Resistor_SMD:R_0603_1608Metric,C319524,Unbranded,0603-0Ω,Direct PDM DATA (3.3V build),1,"DNP for 1.8V; stuff for 3.3V SPH0645" -R_LVT_CLK_IN,0,Resistor_SMD:R_0603_1608Metric,C319524,Unbranded,0603-0Ω,Translator path CLK input,1,"Stuff for 1.8V IM69D130; DNP for 3.3V" -R_LVT_CLK_OUT,0,Resistor_SMD:R_0603_1608Metric,C319524,Unbranded,0603-0Ω,Translator path CLK output,1,"Stuff for 1.8V IM69D130; DNP for 3.3V" -R_LVT_DATA_IN,0,Resistor_SMD:R_0603_1608Metric,C319524,Unbranded,0603-0Ω,Translator path DATA input,1,"Stuff for 1.8V IM69D130; DNP for 3.3V" -R_LVT_DATA_OUT,0,Resistor_SMD:R_0603_1608Metric,C319524,Unbranded,0603-0Ω,Translator path DATA output,1,"Stuff for 1.8V IM69D130; DNP for 3.3V" -C1,1µ,Capacitor_SMD:C_0603_1608Metric,C15849,Samsung,CL10A105KA8NNNC,EN/BOOT RC cap,2,"10µF ceramic for bypass" -C2,10µ,Capacitor_SMD:C_0603_1608Metric,C19666,Samsung,CL10A106MQ8NRNC,VCCB bulk,1,"Bare S3 power bulk cap" -C3,100n,Capacitor_SMD:C_0603_1608Metric,C14663,Samsung,CL10B104KB8NNNC,PDM clock bypass,1, -C4,12p,Capacitor_SMD:C_0603_1608Metric,C23052,Yageo,CC0603JRNPO9BN120,Crystal load cap,1,40MHz XIN -C5,12p,Capacitor_SMD:C_0603_1608Metric,C23052,Yageo,CC0603JRNPO9BN120,Crystal load cap,1,40MHz XOUT -F1,0.75A,Fuse_SMD:Fuse_1206_3216Metric_Pad1.42x3.35mm_HandSolder,C382143,Littelfuse,1206L075/24-R,LED port 1 polyfuse,1,Slow-blow -F2,0.75A,Fuse_SMD:Fuse_1206_3216Metric_Pad1.42x3.35mm_HandSolder,C382143,Littelfuse,1206L075/24-R,LED port 2 polyfuse,1,Slow-blow -F3,0.75A,Fuse_SMD:Fuse_1206_3216Metric_Pad1.42x3.35mm_HandSolder,C382143,Littelfuse,1206L075/24-R,LED port 3 polyfuse,1,Slow-blow -F4,0.75A,Fuse_SMD:Fuse_1206_3216Metric_Pad1.42x3.35mm_HandSolder,C382143,Littelfuse,1206L075/24-R,LED port 4 polyfuse,1,Slow-blow -D1,SMAJ5.0A,Package_DFN_QFN:DFN-2_3x3mm_P0.5mm,C99900,Littelfuse,SMAJ5.0A,LED1 TVS 5V,1,≤1pF parasitic -D2,SMAJ5.0A,Package_DFN_QFN:DFN-2_3x3mm_P0.5mm,C99900,Littelfuse,SMAJ5.0A,LED2 TVS 5V,1,≤1pF parasitic -D3,SMAJ5.0A,Package_DFN_QFN:DFN-2_3x3mm_P0.5mm,C99900,Littelfuse,SMAJ5.0A,LED3 TVS 5V,1,≤1pF parasitic -D4,SMAJ5.0A,Package_DFN_QFN:DFN-2_3x3mm_P0.5mm,C99900,Littelfuse,SMAJ5.0A,LED4 TVS 5V,1,≤1pF parasitic -SW1,Push,Button_Switch_SMD:SW_Push_1P1T_NO_6x6mm_H9.5mm,C393090,Panasonic,EVP-EAJC7A02,BOOT pushbutton,1,Optional download mode -Y1,40MHz,Crystal_SMD:Crystal_3225_3.2x2.5mm_GND2,C13738,JYJE,HC-49S,40MHz MCU clock,1,12pF load caps -U4,24LC02,Package_DIP:DIP-8_W7.62mm_Socket,C15492,Microchip,24LC02T-I/P,FRU EEPROM,1,I2C board identification -U6,W25Q128JV,Package_SO:SOIC-16_3.9x9.87mm_P1.27mm,C106277,Winbond,W25Q128JVPM,QSPI flash 16MB,1,COM-B program storage diff --git a/docs/prd/01-product-brief.md b/docs/prd/01-product-brief.md deleted file mode 100644 index 10f83f2..0000000 --- a/docs/prd/01-product-brief.md +++ /dev/null @@ -1,137 +0,0 @@ -# K1 Lightwave — Product Brief - -## Mission - -Create a dual-ESP32-S3 real-time music visualizer that prioritizes **responsiveness and delight**—low-latency audio capture, synchronous LED output, and robust wireless connectivity. - -**Target users:** Stage/installation creators; living-room ambient users seeking a professional-grade, hackable music display. - ---- - -## Core Value Proposition - -1. **Real-time responsiveness** — Sub-100ms audio→LED latency for rhythm synchronization -2. **Dual-processor architecture** — One MCU captures audio; one handles LED orchestration (lower contention) -3. **Professional aesthetics** — Clean industrial design; modular audio/LED connectors -4. **Open & hackable** — All firmware, hardware, and design files available for customization -5. **Scalable LED support** — From single strand to full-room installations (TBD max LED count) - ---- - -## High-Level Requirements - -### **Audio Capture** -- **Digital microphones:** SPH0645 + IM69D130 (I2S, 16-bit, 16kHz–48kHz sampling) -- **Input:** Either analog preamp (codec: ES8388/SGTL5000) *or* digital mic direct; TBD during design -- **Processing:** Real-time FFT (16–2048 bins); BPM detection (Goertzel); energy per frequency band - -### **LED Output** -- **Addressable LEDs:** WS2812B or SK6812 (RGB/RGBW, 5V logic) -- **Level shifter:** SN74AHCT125 (5V tolerant, 3.3V→5V translation) -- **Scalability:** Currently 1–300 LEDs/strand; design for future expansion to multi-strand -- **FPS target:** ≥30 Hz refresh rate (12ms frame time) -- **Color profiles:** Spectrum, heatmap, amplitude-mapped, beat-sync animations (firmware TBD) - -### **Connectivity** -- **Wi-Fi + BLE:** Via ESP32-S3 built-in (no external module) -- **OTA updates:** Firmware push without USB re-programming -- **Network profile:** Local network only (no cloud dependency) + optional BLE app - -### **Power & Thermal** -- **Input:** 5V DC, USB-C or barrel jack (2A budget baseline; scale with LED load) -- **Logic rails:** 3.3V regulated from 5V supply (LDO or buck) -- **LED power:** Direct from 5V input (current budget per design) -- **Thermal:** Passive cooling preferred; active cooling if dissipation >5W - -### **Physical Form Factor** -- **Enclosure:** Compact (TBD: ~100mm L × 80mm W × 40mm H as placeholder) -- **Connectors:** JST-XH for LEDs (3-pin: GND, 5V, DATA); JST-PH for microphone (4-pin: VCC, GND, I2S×2) -- **Mounting:** Holes for DIN rail or wall mounting (TBD) - ---- - -## Non-Goals (v1) - -- Battery operation (wall/USB powered only) -- Analog audio input (digital I2S only) -- Ethernet connectivity -- Commercial FCC/CE certification (hobbyist/maker product) -- Support for >300 LEDs per strand (future version) - ---- - -## Key Constraints - -### **Electrical** -- 4-layer PCB; JLC/PCBWay manufacturing (cost & lead time optimized) -- Single-side assembly preferred (simplifies production) -- Component sourcing: LCSC/JLC C-numbers prioritized (fast delivery, cheap) - -### **Timing & Latency** -- Audio→LED latency budget: <100ms (to feel responsive) -- I2S clock: 64 kHz (4 × 16 kHz) or higher -- LED refresh: ≥30 Hz (12ms frame time) -- Contention: Dual MCU avoids audio processing blocking LED output - -### **EMI & Signal Integrity** -- 1-wire LED output is prone to noise (SN74AHCT125 level shifter helps) -- Audio lines must be separated from LED switching (ground guard traces) -- Ground plane on both internal layers; star grounding at power entry - -### **Manufacturability** -- No specialized components; all parts on LCSC/Digi-Key -- Panelization target: 4×8 grid for cost-per-unit optimization (later version) - ---- - -## Success Criteria - -1. ✅ Hardware prototype boots and runs basic firmware -2. ✅ Audio captures cleanly at 16 kHz, 16-bit, stereo via I2S -3. ✅ LEDs respond to audio in real-time (<100ms latency) -4. ✅ Wi-Fi / BLE connectivity stable (no frequent dropouts) -5. ✅ Thermal: <50°C at full LED load, 25°C ambient -6. ✅ ERC/DRC clean; all components ≥95% available on LCSC -7. ✅ Open-source design & firmware released (GitHub) - ---- - -## Timeline & Phases - -| Phase | Deliverable | Timeline | -|-------|-------------|----------| -| **Alpha** | Schematic + PCB layout (design-complete) | Week 1–2 | -| **Beta** | Prototype received; power-up & firmware bringup | Week 3–4 | -| **Release** | Full validation (thermal, EMI, assembly docs) + GitHub release | Week 5–6 | - ---- - -## Stakeholders & Roles - -- **Hardware Designer:** PCB schematic, layout, DFM -- **Firmware Engineer(s):** Audio DSP, LED animation, wireless stack -- **Validation Engineer:** Bringup, DVT, EMI pre-scan (TBD) - ---- - -## Scope (Out of v1) - -- Cloud dashboard / web interface -- Multi-color synchronized effects (single static/animated profile per session) -- Microphone auto-leveling / AGC -- Battery operation or ultra-low-power mode - ---- - -## References - -- **Hardware PRD:** `/docs/prd/02-hardware-prd.md` -- **Validation Plan:** `/docs/prd/03-validation-plan.md` -- **Governance:** `/claude/GOVERNANCE.md` -- **Datasheets:** `/docs/datasheets/` - ---- - -**Version:** 0.1 (Alpha) -**Last updated:** Oct 23, 2025 -**Status:** Project scaffold complete; design work to begin diff --git a/docs/prd/02-hardware-prd.md b/docs/prd/02-hardware-prd.md deleted file mode 100644 index 6ade589..0000000 --- a/docs/prd/02-hardware-prd.md +++ /dev/null @@ -1,316 +0,0 @@ -# K1 Lightwave — Hardware PRD (Rev-A Frozen) - -**Status:** LOCKED for schematic design. All GPIO, power domains, and compute architecture final. - ---- - -## Power - -- **USB-C 5V, up to 3A** (Type-C current mode; no PD). Powers **controller logic only**. -- **LED power:** **external 5V** via locking connector; **no back-feed** to USB-C (ideal-diode/OR-FET). -- 5V→3.3V buck (≥2A), input fuse/e-fuse, inrush, ESD on CC/D+/D−. - -| Rail | Voltage | Source | Usage | Notes | -|------|---------|--------|-------|-------| -| VBUS_USB_5V | 5V ±0.25V | USB-C | Logic only | Fused @ 1A; feeds buck | -| LED_5V | 5V ±0.1V | External connector | LED domain (high current) | Isolated via ideal diode | -| +3V3 | 3.3V ±0.1V | TPS62133 buck | MCU, codec, I2C, mics, LS drivers | ≥2A; 100µF bulk + 10µF per MCU | - ---- - -## LED Outputs - -- **Populate:** **4× one-wire** ports (WS2812B/SK6812) with **SN74AHCT125** (quad shifter) + 330Ω series resistor, polyfuse (0.75A), TVS diode, 3-pin locking headers (Molex KK-254). -- **Reserve (DNP):** **+4× one-wire** and **2× SPI (APA102/DotStar)** headers. -- **Throughput:** 1-wire @800 kHz ≈ 30 µs/LED → **60 FPS ~ 555 LEDs/port**, **120 FPS ~ 277 LEDs/port**. -- **Power protection:** Polyfuse per port; TVS across 5V-to-GND at connector; no back-feed to USB domain. - ---- - -## Compute - -### COM-A (Audio/DSP) — ESP32-S3-WROOM-1 Module - -- **Form factor:** K1-M2B slot (M.2 B-key 2230; custom electrical mapping, not PC-M.2 standard). -- **USB-C connects here** (for flashing, CDC debug). -- **Consumes:** I²S from mic headers, SPI master to COM-B, UART debug, I²C mgmt. -- **Produces:** I²S_BCLK/LRCK/SD (sampled audio), SPI_MOSI/MISO/CS/SCK (high-rate), SYNC pulse (frame timing). - -### COM-B (LED Renderer) — Bare ESP32-S3 QFN - -- **Flash:** **QSPI 8–16 MB** (W25Q128JV or equivalent). **Dedicated SPI0/1 pins (26–32)** per Espressif; **do not repurpose for GPIO**. -- **Clock:** **40 MHz crystal** with 12pF load caps (tied to XIN/XOUT pins). -- **Boot:** EN/BOOT RC network (10k/1µ); BOOT strap to GND via pushbutton for download mode. -- **Consumes:** SPI slave from COM-A (20–40 MHz, CRC-16 frames), SYNC pulse for alignment. -- **Produces:** 4× GPIO to level shifter (LED_DATA1..4_IN), READY/ERR GPIO back to COM-A. - ---- - -## Inter-MCU Link - -- **Protocol:** SPI-DMA, **20–40 MHz**, CRC-16, sequence number, **200–400 Hz frame rate** (~400 B/frame typical). -- **Pins (COM-B):** - - **GPIO12** = SPI_SCK_A2B (input from COM-A) - - **GPIO11** = SPI_MOSI_A2B (input) - - **GPIO13** = SPI_MISO_B2A (output) - - **GPIO10** = SPI_CS_A2B (input) - - **GPIO38** = SYNC_A2B (frame pulse from COM-A) - - **GPIO39** = READY_B2A (back-pressure from COM-B) -- **All pins selected for clean IO_MUX mapping and no strap/memory conflicts.** ([Espressif Docs](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/)) - ---- - -## Audio (Microphone & I²S) - -### Microphone Options & Voltage Domains - -**SPH0645 (I²S, Recommended @ 3.3V)** -- Voltage: **1.62–3.6V** (spec'd optimally at 3.3V supply). -- Interface: **I²S** (standard 4-wire + SEL). -- SNR: **65 dB(A)** nominal; THD ≈ 2%. -- Connect **SEL to GND** for mono; leave open for stereo on some variants. -- **No translator needed** if using 3.3V rail directly. -- Reference: [ATCKIT SPH0645](https://datasheets.com/en/datasheets/ATCKIT-SPH0645) - -**IM69D130 (PDM, 1.8V Optimized)** -- Voltage: **1.8V nominal** (can run 1.2–2.4V, but SNR degrades below 1.8V). -- Interface: **PDM** (clock + data serial stream @ Fpdm = Fs × 64 or Fs × 128; e.g., 3.072 MHz for 48 kHz). -- SNR: **65 dB(A)** @ 1.8V; drops ~1.5 dB per 100 mV below 1.8V. -- Requires **1.8V LDO** (separate from 3.3V rail) and **SN74AXC2T245 level translator** on clock/data. -- **Population options in SKiDL:** - - **3.3V SPH0645 build:** DNP `U8`, `R_LVT_*` (translator); populate `R_BYPASS_CLK/DATA` (0Ω direct paths). - - **1.8V IM69D130 build:** Populate `U8` (SN74AXC2T245), `R_LVT_*`; DNP bypass resistors. -- Reference: [Infineon IM69D130 Datasheet](https://www.infineon.com/en/products/sensors/im69d130) - -### ESP-IDF Implementation - -**PDM RX (for 1.8V IM69D130):** -- PDM available on **I2S0 only** (COM-B); outputs **16-bit PCM**. -- Clock frequency: **Fpdm = Fs × 64** or **Fs × 128** (e.g., 48 kHz → **3.072 MHz** @ ×64, **6.144 MHz** @ ×128). -- Initialize with `I2S_PDM_RX_DEFAULT_CONFIG()` (ESP-IDF > 4.4). -- COM-B GPIO: **GPIO12 (PDM_CLK_MCUSIDE)**, **GPIO13 (PDM_DATA_MCUSIDE)** → nets map to mic via translator or bypass. -- Latency: ~1 ms capture buffer; ideal for real-time effects. -- Reference: [Espressif I2S PDM RX](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/i2s.html) - -**I²S Standard (for 3.3V SPH0645 or external codec):** -- **BCLK:** bit clock (1.536 MHz mono @ 24-bit/48 kHz, 3.072 MHz stereo). -- **LRCK (WS):** frame sync (48 kHz). -- **SD:** serial data (MSB first, 32-bit slots with 24-bit fill). -- Master clock (MCLK) optional; leave floating if not on baseboard (codec/mic generates internally). -- Reference: [Espressif I2S Standard](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/i2s.html) - -### Headers & Wiring - -- **Two 6-pin JST-GH headers** (`3V3, GND, BCLK, LRCK, SD, SEL`). -- **BCLK/LRCK series damping:** 22–47 Ω near clock driver to minimize ringing @ multi-MHz edges. -- **Connector placement:** Near COM-A to minimize loop area on fast edges. -- **Cable:** Shielded pairs recommended for runs >10 cm; shield to GND at one end. - -### Bring-Up - -1. Verify clock/data outputs from COM-A on logic analyzer. -2. If PDM: confirm Fpdm matches Fs × 64 or Fs × 128. -3. FFT capture on COM-A confirms frequency response @ 48 kHz / 24-bit stereo. - ---- - -## Accessory I²C - -- **Qwiic-compatible pin order:** `GND, VCC, SDA, SCL` (standard Qwiic footprint). -- **Dual footprints per port:** JST-SH (default) + JST-GH (alternate, placed in PCB as parallel pads). -- **4 ports:** - - **I2C_PORT_1, I2C_PORT_2:** powered by **3.3V** (logic accessories, sensors, etc.). - - **I2C_PORT_3, I2C_PORT_4:** powered by **5V** (supply only; data lines **level-shifted** on motherboard to 3.3V safe levels). -- **FRU EEPROM:** 24LC02 on I²C (slot/base identification). - ---- - -## GPIO Summary (COM-B, Final) - -| Function | GPIO | Rationale | -|----------|------|-----------| -| SPI_SCK_A2B (in) | **12** | IO_MUX SCLK for SPI2; robust 20–40 MHz. | -| SPI_MOSI_A2B (in) | **11** | IO_MUX MOSI for SPI2. | -| SPI_MISO_B2A (out) | **13** | IO_MUX MISO for SPI2. | -| SPI_CS_A2B (in) | **10** | IO_MUX CS0 for SPI2. | -| SYNC_A2B (in) | **38** | Clean, non-strap. | -| READY_B2A (out) | **39** | Clean, non-strap. | -| LED_DATA1_IN (out) | **8** | Free; goes to LS A1. | -| LED_DATA2_IN (out) | **18** | Free; goes to LS A2. | -| LED_DATA3_IN (out) | **21** | Free; goes to LS A3. | -| LED_DATA4_IN (out) | **47** | Free; goes to LS A4. | -| UART_TX_B | **14** | Optional debug (not a strap). | -| UART_RX_B | **15** | Optional debug. | -| EN (CHIP_PU) | **EN pin** | RC 10k/1µF; standard bring-up. | -| GPIO0 (BOOT) | **GPIO0** | 10k pullup + pushbutton to GND. | - -**Avoided:** Strap pins (0, 3, 45, 46), memory/flash pins (26–32), and reserved Octal I/O (33–37). - ---- - -## Panelization & DFM - -### V-Cut Panel Requirements (JLCPCB Standard) - -**Minimum panel size:** **70 × 70 mm** (KiKit enforces this; smaller panels use mouse-bites instead). -- Quoted from JLCPCB documentation: panels must be ≥ 70 × 70 mm for V-cut scoring. - -**V-cut line rules:** -- **Full-length straight cuts** (no partial or curved lines); both horizontal and vertical lines must span the entire panel dimension. -- **Clearance from copper:** ≥ **0.4 mm** clearance on all copper traces (pads, vias, fills) to the V-cut score line. -- **Material thickness:** 1.6 mm (standard FR-4); JLC uses pneumatic V-scoring (60° or 90° angle, ~0.6 mm groove depth). -- **Breakability:** Post-scoring, boards separate with **hand pressure or light mechanical nudge** (no edge stress concentration). - -### Rails & Tooling - -- **Top/bottom rails:** **5 mm minimum** (2.54 mm typical) for handling and fixturing. -- **Left/right rails:** **3–5 mm** (same as top/bottom; full panel margin). -- **Fiducials:** 3× standard (Ø1.5 mm, no copper ring) placed at **panel corners + center** for vision alignment during depanel. -- **Test points:** Optional; route GND, +3V3 test pads to opposite corner from fiducials if automated. - -### Copper & Soldermask Clearance - -- **Edge clearance:** ≥ **0.3 mm** from board edge (Edge.Cuts) to nearest copper pad. -- **V-cut clearance:** ≥ **0.4 mm** (manufacturer minimum; Adafruit/SparkFun best practices use 0.5 mm for headroom). -- **Vias near V-cut:** Stagger vias in the 0.4–0.5 mm exclusion zone; never place via pad on the V-cut line itself. - -### Post-Depanelization - -- Boards separate cleanly when sawn or V-scored; no additional rework (shearing, sanding, or trimming) required in small volumes. -- Larger panels (100+ boards) benefit from **KiKit panelization script** which auto-assigns cuts, rails, and fiducials. -- JLC surcharge for V-cut: ≈ **$3–5 USD per order** (not per board); negligible for small runs. - -### Layer Stack & Finish - -- **4-layer FR-4** (standard): F.Cu / prepreg / GND / prepreg / PWR / prepreg / B.Cu (thickness 1.6 mm). -- **Copper weight:** 1 oz (1.4 mil / 35 µm) standard; 2 oz available for high-current rails (LED_5V busses). -- **Surface finish:** **ENIG** (electroless nickel immersion gold) ≥ 0.05 µm Ni, ≥ 0.025 µm Au; required for reliability on fine-pitch connectors and castellated edges. -- **Soldermask:** Green (standard); thickness ≥ 25 µm; clearance from solder bridges ≥ 0.1 mm. -- **Silkscreen:** White on black/green; min. text height 0.5 mm (readable by hand); auto-placement of reference designators on F.Fab layer. - -**References:** -- JLCPCB V-cut specifications: https://jlcpcb.com/capabilities/pcb-assembly -- KiKit panelization tool: https://github.com/yaqwsx/KiKit -- Adafruit PCB design guide: https://learn.adafruit.com/faq-all-about-pcbs (v-cut section) - ---- - -## Bring-Up Plan - -### Power-Only Smoke - -1. USB-C 5V in → 3.3V buck OK; no current on LED_5V. -2. Check **no continuity** between `VBUS_USB_5V` and `LED_5V`. -3. Fabops power-domain guard validates isolation in schematic. - -### COM-B Minimal Life - -1. Strap RC, EN high, BOOT pulled up; flash programming via UART. -2. QSPI flash wired; first blinky on **GPIO8** (LED_DATA1_IN) confirms IO. - -### COM-A ↔ COM-B Link - -1. SPI loop at 20–40 MHz on pins (12/11/13/10); toggle SYNC; ISR on COM-B. -2. MISO loopback; CRC-16 validation. - -### Priority 2B: PDM/I2S Clock Verification (10 min) - -1. **PDM Clock (if 1.8V IM69D130 build)** - - Measure clock frequency on GPIO12 - - Expected: **3.072 MHz** (48 kHz × 64) or **6.144 MHz** (48 kHz × 128) - - Tolerance: ±5% (2.92–3.22 MHz or 5.84–6.45 MHz) - -2. **I2S Clock (if 3.3V SPH0645 build)** - - Measure BCLK on GPIO43 (from COM-A) - - Expected: **1.536 MHz** (mono) or **3.072 MHz** (stereo) @ 48 kHz - - Use logic analyzer to verify phase alignment with LRCK - -### I²S Mics - -1. Feed tone; 48 kHz/24-bit capture on COM-A. -2. FFT shows line at input frequency. - -### LED Ports - -1. External 5V in; per-port fuse OK. -2. iBOM shows AHCT125 + 330Ω + TVS per port. - -### Priority 3B: Thermal Validation (30 min) - -1. **Setup** - - Populate 300× WS2812B test strip on LED1_OUT - - Set all pixels to 100% white (255, 255, 255) all channels - - Soak for 15 minutes continuous operation - -2. **Measurement** - - FLIR thermal scan of power components (LTC4412, TPS7A2018, shunt resistors) - - Measure junction temps at multiple points - -3. **Acceptance Criteria** - - **PASS**: <70°C (safe headroom for INA226 shunt 0.05Ω @ 3A) - - **WARNING**: 60–70°C (firmware brightness capping recommended) - - **FAIL**: >70°C (LTC4412 overheat risk, redesign required) - -4. **Alternative (No FLIR)** - - Touch-test: skin contact on U2 (LTC4412) and U5 (TPS7A2018) should be warm but safe (<60°C hand tolerance) - - Record ambient temperature for baseline correction - ---- - -## References & Technical Sources - -### Architecture & Design - -- **SKiDL netlist generator:** `hardware/k1-lightwave/skidl/k1_motherboard_revA.py` (complete BOM & net routing) -- **KiCad schematic:** `hardware/k1-lightwave/kicad/K1_Lightwave.kicad_sch` (all symbols, nets, ERC-validated) -- **KiCad PCB:** `hardware/k1-lightwave/kicad/K1_Lightwave.kicad_pcb` (layout rules, net classes, DRC-ready) - -### ESP32-S3 Hardware - -- **Espressif ESP32-S3 Hardware Design Guidelines:** https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/hw-reference/esp32s3-devkitc-1/user-guide.html -- **Espressif I2S (PDM & Standard):** https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/i2s.html -- **Espressif SPI Master:** https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/spi_master.html -- **GPIO & Pinmux Reference:** https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/gpio.html - -### USB Type-C & Power - -- **USB Type-C Spec (5V Sink):** Beyond Logic USB-C article on Rd = 5.1 kΩ current advertisement -- **ESD Protection:** Texas Instruments TPD4E05U06 datasheet (< 0.5 pF for USB2.0 compliance) -- **Ideal Diode (OR-FET):** Analog Devices LTC4412 datasheet (monolithic; LTC4411 ≤ 2.6 A variant) -- **Current Monitoring:** Texas Instruments INA226 datasheet (I2C high-side monitor, up to 36 V, ±16 addresses) - -### Audio & Microphones - -- **SPH0645 (I²S, 3.3V):** ATCKIT SPH0645 datasheet; 65 dB(A) SNR @ 3.3 V -- **IM69D130 (PDM, 1.8V optimized):** Infineon IM69D130 datasheet; SNR = 65 dB(A) @ 1.8V, ~1.5 dB/100mV below -- **SN74AXC2T245 (Voltage Translator):** Texas Instruments; dual-channel, push-pull, up to 380 Mb/s -- **Adafruit NeoPixel Best Practices:** https://learn.adafruit.com/adafruit-neopixel-uberguide (series resistor, TVS, bulk cap recommendations) - -### LED Outputs & Drivers - -- **SN74AHCT125 (Quad Buffer):** Texas Instruments; 5 V TTL-compatible, fast rise/fall for 1-wire data -- **300–500 Ω Series Damping:** Standard practice for WS2812B/SK6812 clock/data lines per Adafruit & NeoPixel specs -- **TVS Diodes (5V Lines):** Texas Instruments SMAJ series or Littelfuse 1.5KE series (≥ 5 V clamp, ≤ 1 pF) -- **Polyfuses (0.75A):** Littelfuse or Bourns (1206 SMD size, slow-blow for LED current transients) - -### Manufacturing & Panelization - -- **JLCPCB V-Cut Specifications:** https://jlcpcb.com/capabilities/pcb-assembly (≥ 70×70 mm panel, full-length cuts, 0.4 mm copper clearance) -- **KiKit Panelization Tool:** https://github.com/yaqwsx/KiKit (automated v-cut, rails, fiducials, test points) -- **Adafruit PCB Design Guide:** https://learn.adafruit.com/faq-all-about-pcbs (manufacturing best practices, v-cut, depanel) -- **ENIG Surface Finish:** IPC-A-610 standard for nickel/gold thickness and reliability on fine-pitch connectors - -### FabOps & Validation - -- **Fabops Power-Domain Guard:** `mcp/mcp-fabops/server.py` (prevents VBUS_USB_5V ↔ LED_5V shorts at netlist level) -- **KiBot CI Pipeline:** `.github/workflows/kibot.yml` (automated Gerber, STEP, GLB, iBOM generation per commit) - -### Full Datasheets Archive - -- Location: `docs/datasheets/` (indexed by part number) - ---- - -**Version:** 1.0 (FROZEN for Rev-A schematic) -**Date:** October 23, 2025 -**Status:** Ready for KiCad import & layout diff --git a/docs/prd/03-validation-plan.md b/docs/prd/03-validation-plan.md deleted file mode 100644 index 66f078f..0000000 --- a/docs/prd/03-validation-plan.md +++ /dev/null @@ -1,318 +0,0 @@ -# K1 Lightwave — Validation Plan - -## Overview - -This document outlines the testing and validation strategy for K1 Lightwave hardware, from initial prototype bringup through Design Verification Testing (DVT) and production readiness. - -**Target:** Confirm all requirements in `/docs/prd/01-product-brief.md` and `/docs/prd/02-hardware-prd.md` are met. - ---- - -## Test Phases - -### **Phase 1: EVT (Engineering Validation Test)** - -**Objective:** Confirm design intent; identify critical issues before DVT - -**Timeline:** Week 1–2 post-prototype - -#### **1.1 Power-Up & Electrical** - -| Test | Acceptance Criteria | Method | Owner | -|------|-------------------|--------|-------| -| No shorts on power rails | No smoke; no >100mA short-circuit draw | Bench PSU, measure VCC, GND continuity | HW Lead | -| VCC_5V rail stable | 5V ±0.2V under no-load | Multimeter; 10s observation | HW Lead | -| VCC_3V3 regulation | 3.3V ±0.1V under 0–2A load | Variable load bank (resistor); oscilloscope | HW Lead | -| No thermal issues (idle) | Ambient +5°C measured @ LDO, MCU | IR thermometer; 5min soak | HW Lead | - -**Deliverable:** Power-up report (pass/fail + photos) - ---- - -#### **1.2 MCU & UART Console** - -| Test | Acceptance Criteria | Method | Owner | -|------|-------------------|--------|--------| -| MCU boots (flash readable) | UART console responds to MCU reset | Connect FTDI USB→UART; monitor output | FW Lead | -| Clock accuracy | System clock within ±1% of 240 MHz | Oscilloscope on GPIO square wave | FW Lead | -| GPIO toggle works | LED on GPIO11 blinks @ 1 Hz | Connect test LED; visual confirmation | FW Lead | -| Wi-Fi radio responds | Wi-Fi chip enumerated; no JTAG errors | `espefuse.py summary` over USB-JTAG | FW Lead | - -**Deliverable:** Bringup log with timestamps; UART capture - ---- - -#### **1.3 Audio Input (I2S Microphone)** - -| Test | Acceptance Criteria | Method | Owner | -|------|-------------------|--------|--------| -| I2S clock present | BCLK 64 kHz ±1%, stable | Oscilloscope BCLK pin; 1s waveform | HW/FW | -| LRCLK framing | 16 kHz ±1%, ~50% duty | Oscilloscope LRCLK pin | HW/FW | -| Mic data output | 16-bit stereo capture, no all-zeros | MCU I2S DMA capture to SRAM; dump via UART | FW Lead | -| Audio quality | No excessive noise (SNR >60 dB baseline) | FFT of silence + 1kHz tone; spectrum analyzer | FW Lead | - -**Deliverable:** I2S timing diagram; audio capture waveform (WAV file); SNR measurement - ---- - -#### **1.4 LED Output (WS2812B)** - -| Test | Acceptance Criteria | Method | Owner | -|------|-------------------|--------|--------| -| Data line toggles | GPIO11 output pulse train visible | Oscilloscope GPIO11; frequency ≈800 kHz | HW Lead | -| LED color response | RGB test pattern visible (Red→Green→Blue) | Power LED strip; observe color changes | FW Lead | -| LED brightness | Full range 0–255 addressable | Firmware command; visual inspection | FW Lead | -| Max LED count | 300 LEDs operational @ 30 Hz refresh | Connect 300-LED strip; no frame loss | FW Lead | - -**Deliverable:** LED timing diagram; color test video; FPS measurement - ---- - -### **Phase 2: DVT (Design Verification Test)** - -**Objective:** Confirm production-level performance; quantify margins - -**Timeline:** Week 3–4 post-prototype (if EVT passes) - -#### **2.1 Thermal Analysis** - -| Test | Acceptance Criteria | Method | Owner | -|------|-------------------|--------|--------| -| Idle temperature | <30°C @ 25°C ambient (no load) | IR thermometer + internal temp sensor (if firmware supports) | HW Lead | -| Full LED load (300 LEDs @ 100%) | <50°C @ 25°C ambient | 15 min soak @ max brightness white; measure TDK sensor | HW Lead | -| Thermal hysteresis | No oscillation around set-point | 30 min observation; log temps every 10s | HW Lead | -| LDO dissipation | <1W nominal (calculated I × V_dropout) | Measure VCC_5V drop & 3.3V current draw | HW Lead | - -**Deliverable:** Thermal curve (time vs. temp); max junction temp estimate - ---- - -#### **2.2 Power Consumption** - -| Test | Acceptance Criteria | Method | Owner | -|------|-------------------|--------|--------| -| Idle (no LEDs) | <500 mA @ 5V | Current meter on VCC_5V | HW Lead | -| Audio capture only | <800 mA @ 5V | I2S capture + DSP running | FW Lead | -| LEDs @ 50% avg brightness | <4A @ 5V (acceptable; ≤5A budget) | LED load bank simulation or real strip | HW Lead | -| Peak burst (LEDs @ 100% + audio) | ≤5A for <100ms (burst acceptable) | Oscilloscope current sense (shunt resistor) | HW Lead | - -**Deliverable:** Current profile graph (time vs. current); surge events logged - ---- - -#### **2.3 Electromagnetic Interference (EMI)** - -| Test | Acceptance Criteria | Method | Owner | -|------|-------------------|--------|--------| -| LED switching noise on audio | <3% THD on 1 kHz audio capture during LED activity | FFT of captured audio; simultaneous LED PWM | HW/FW | -| Wi-Fi range | ≥10 m indoor (line-of-sight) from AP | Walk-around test; signal strength measurement | FW Lead | -| Antenna detuning (PCB impact) | No >3 dB gain loss vs. module alone | Measure S11 (return loss) if lab available; otherwise skip | HW Lead | - -**Deliverable:** EMI/audio cross-talk report; Wi-Fi link budget confirmation - ---- - -#### **2.4 Reliability & Stress** - -| Test | Acceptance Criteria | Method | Owner | -|------|-------------------|--------|--------| -| Power cycling (10× cycles) | No failures; consistent boot | Off→5s→On→10s soak; repeat 10×; check logs | HW Lead | -| Thermal stress (hot/cold) | Functionality across 0–50°C (industrial baseline) | If environmental chamber available; otherwise skip for v1 | HW Lead | -| Long-run stability (24h) | No crashes; audio/LED stable | 24h continuous operation @ typical load | FW Lead | -| Connector durability | ≥10 plug/unplug cycles | JST-XH/PH insertion tests; no contact issues | HW Lead | - -**Deliverable:** Stress test log; pass/fail summary - ---- - -### **Phase 3: DFM (Design For Manufacturability) Review** - -**Objective:** Confirm producibility; identify potential assembly/test gaps - -**Timeline:** Concurrent with DVT or after prototype receives approval - -#### **3.1 Gerber & Drill Review** - -| Item | Check | Method | Owner | -|------|-------|--------|-------| -| Gerber layers complete | All 10 layers (L1, L2, L3, L4 + solder mask, silk, drill) | Verify file count & naming in output | HW Lead | -| Drill file accuracy | All via sizes ≥0.3 mm; correct plating codes | Inspect .drill/.drl file; fab quotes | HW Lead | -| Solder mask detail | No isolation issues; pins accessible for rework | 2× magnification visual inspection or Gerber viewer | HW Lead | -| Silkscreen contrast | Legible reference designators; no clipping | 100% inspection of output | HW Lead | - -**Deliverable:** Gerber checklist (pass); fab clearance confirmation - ---- - -#### **3.2 BOM & Assembly** - -| Item | Check | Method | Owner | -|------|-------|--------|-------| -| Part availability | All parts ≥95% stock on LCSC/Digi-Key | Run BOM check via Nexar / LCSC API; confirm C-numbers | HW Lead | -| Lead times | All parts <8 weeks (fast-track criteria) | Record supplier lead times | Procurement | -| Assembly compatibility | All footprints compatible with pick-and-place | Verify IPC-636 footprint compliance | HW Lead | -| Panelization (if applicable) | Tab/breakaway design robust; <1 min manual separation | Prototype panel breakaway test | HW Lead | - -**Deliverable:** BOM with LCSC C-numbers + availability; assembly procedure - ---- - -#### **3.3 Test Coverage** - -| Test Point | Function | Method | Owner | -|------------|----------|--------|-------| -| TP_VCC_5V | 5V rail continuity | Continuity probe; voltage measurement | Assembly | -| TP_VCC_3V3 | 3.3V output check | Voltage check during power-on; functional trim | Assembly | -| TP_GND | Ground integrity | Continuity check; star-point verification | Assembly | -| TP_I2S_* | Audio clock/data present | Logic analyzer capture (if available); optional | Assembly | -| TP_LED_DATA | LED signal integrity | Oscilloscope waveform check (pulse train) | Assembly | - -**Deliverable:** In-circuit test (ICT) procedure / checklist - ---- - -## Acceptance Gates - -### **Gate 1: Electrical (EVT 1.1–1.2)** - -✅ **Pass if:** -- Power rails stable (no shorts, correct voltage) -- MCU responsive on UART -- Clock accuracy within ±1% - -❌ **Fail → Stop:** Investigate electrical schematic or layout error; debug traces - ---- - -### **Gate 2: Functional (EVT 1.3–1.4)** - -✅ **Pass if:** -- Audio captures cleanly (SNR >60 dB) -- LEDs respond to firmware commands -- No data loss @ 30 Hz refresh - -❌ **Fail → Conditional:** If audio/LED issues are firmware-only, proceed with caveats; hardware-level issues block progression - ---- - -### **Gate 3: Thermal & Reliability (DVT 2.1–2.4)** - -✅ **Pass if:** -- Idle <30°C, full load <50°C -- Power consumption <5A @ max load -- 24h uptime without crashes -- EMI within acceptable limits - -❌ **Fail → Conditional:** If thermal >60°C, investigate layout/component selection; minor EMI issues may warrant re-layout but don't block production - ---- - -### **Gate 4: Manufacturability (DFM 3.1–3.3)** - -✅ **Pass if:** -- All components ≥90% available on LCSC -- BOM cost within budget (TBD) -- Assembly procedure documented -- Test coverage defined - -❌ **Fail → Escalation:** Component substitution required; design may need iteration - ---- - -## Rework & Issue Tracking - -### **Minor Issues** (Doesn't block release) - -- Silkscreen text slightly faint (remedied with brighter ink) -- Single non-critical component substitution (same footprint, equivalent spec) -- Documentation typos or clarifications - -**Action:** Log in GitHub Issues; resolve in v1.1 respin - ---- - -### **Major Issues** (Blocks release, may require layout change) - -- Thermal runaway (>60°C full load) -- Audio noise >10% THD during LED activity -- Component unavailability (>30 day lead time, no substitute) -- Layout error affecting high-speed signals - -**Action:** Root cause analysis; schematic/PCB revision; new prototype - ---- - -### **Critical Issues** (Halt production; deep investigation) - -- Functional failure @ room temperature (MCU won't boot, no I2S output) -- Power rail instability (brown-out, ripple >200 mV) -- Connector/mechanical failure preventing assembly - -**Action:** Escalate to hardware designer; re-spin if necessary - ---- - -## Approval & Sign-Off - -| Role | Approval | Criteria | -|------|----------|----------| -| **Hardware Lead** | PCB & electrical | EVT power-up + DVT thermal/EMI pass; DFM checklist complete | -| **Firmware Lead** | Software stack | EVT audio/LED functional; 24h uptime pass; no unresolved faults | -| **Project Manager** | Production readiness | BOM sourced, lead times confirmed, assembly procedure documented | - -**Sign-off required for:** Gerber release to fab; GitHub public release announcement - ---- - -## Documentation Deliverables - -### **For Internal Use** - -- EVT power-up report (photos, voltage measurements, UART output) -- DVT thermal/power curves (plots, CSV data) -- EMI test report (audio FFT, Wi-Fi range measurements) -- 24h uptime log (firmware diagnostics) - -### **For Production / Assembly** - -- Final BOM (LCSC C-numbers, quantities, substitutes) -- Schematic PDF (with revision) -- PCB layout (top/bottom assembly diagrams) -- Gerber + drill + IPC-2581 (manufacturing data) -- Assembly procedure (step-by-step with photos) -- Test procedure (in-circuit checks; functional validation) - -### **For End-Users / Makers** - -- Quick-start guide (power-on, firmware install, Wi-Fi setup) -- Schematic (for reference/hacking) -- Hardware pinout diagram -- LED & mic connector pinout -- Firmware GitHub repo link - ---- - -## Timeline & Responsibilities - -| Phase | Week | Owner | Deliverable | -|-------|------|-------|-------------| -| EVT | 1–2 | HW + FW Lead | Power-up report, audio/LED validation | -| DVT | 3–4 | HW Lead | Thermal, EMI, reliability curves | -| DFM | Concurrent | HW Lead | Gerber review, BOM check, test plan | -| Approval | 4–5 | PM + HW + FW | Sign-off memo; GitHub release ready | - ---- - -## References - -- **Hardware PRD:** `/docs/prd/02-hardware-prd.md` -- **Product Brief:** `/docs/prd/01-product-brief.md` -- **Datasheets:** `/docs/datasheets/` -- **MCP Tools:** `/hardware/k1-lightwave/README.md#mcp-tool-commands` -- **Governance:** `/claude/GOVERNANCE.md` - ---- - -**Version:** 0.1 (Alpha Validation Plan) -**Last updated:** Oct 23, 2025 -**Status:** Template ready for prototype; adjustments based on actual hardware TBD diff --git a/esp-hardware-design-guidelines-en-master-esp32s3.pdf b/esp-hardware-design-guidelines-en-master-esp32s3.pdf deleted file mode 100644 index a69f72a..0000000 Binary files a/esp-hardware-design-guidelines-en-master-esp32s3.pdf and /dev/null differ diff --git a/esp32-s3_datasheet_en.pdf b/esp32-s3_datasheet_en.pdf deleted file mode 100644 index 752be01..0000000 Binary files a/esp32-s3_datasheet_en.pdf and /dev/null differ diff --git a/mcp/mcp-rag/__pycache__/server.cpython-312.pyc b/mcp/mcp-rag/__pycache__/server.cpython-312.pyc deleted file mode 100644 index 020f6da..0000000 Binary files a/mcp/mcp-rag/__pycache__/server.cpython-312.pyc and /dev/null differ diff --git a/automated_routing.py b/tools/elite-pcb-designer/legacy-pipeline/automated_routing.py similarity index 100% rename from automated_routing.py rename to tools/elite-pcb-designer/legacy-pipeline/automated_routing.py diff --git a/component_placement.py b/tools/elite-pcb-designer/legacy-pipeline/component_placement.py similarity index 100% rename from component_placement.py rename to tools/elite-pcb-designer/legacy-pipeline/component_placement.py diff --git a/demo_elite_pcb_designer.py b/tools/elite-pcb-designer/legacy-pipeline/demo_elite_pcb_designer.py similarity index 100% rename from demo_elite_pcb_designer.py rename to tools/elite-pcb-designer/legacy-pipeline/demo_elite_pcb_designer.py diff --git a/demo_placement.py b/tools/elite-pcb-designer/legacy-pipeline/demo_placement.py similarity index 100% rename from demo_placement.py rename to tools/elite-pcb-designer/legacy-pipeline/demo_placement.py diff --git a/design_preparation.py b/tools/elite-pcb-designer/legacy-pipeline/design_preparation.py similarity index 100% rename from design_preparation.py rename to tools/elite-pcb-designer/legacy-pipeline/design_preparation.py diff --git a/design_validation.py b/tools/elite-pcb-designer/legacy-pipeline/design_validation.py similarity index 100% rename from design_validation.py rename to tools/elite-pcb-designer/legacy-pipeline/design_validation.py diff --git a/elite_pcb_designer.py b/tools/elite-pcb-designer/legacy-pipeline/elite_pcb_designer.py similarity index 100% rename from elite_pcb_designer.py rename to tools/elite-pcb-designer/legacy-pipeline/elite_pcb_designer.py diff --git a/elite_pcb_designer_cli.py b/tools/elite-pcb-designer/legacy-pipeline/elite_pcb_designer_cli.py similarity index 100% rename from elite_pcb_designer_cli.py rename to tools/elite-pcb-designer/legacy-pipeline/elite_pcb_designer_cli.py diff --git a/example_k1_full_design.py b/tools/elite-pcb-designer/legacy-pipeline/example_k1_full_design.py similarity index 100% rename from example_k1_full_design.py rename to tools/elite-pcb-designer/legacy-pipeline/example_k1_full_design.py diff --git a/example_k1_routing.py b/tools/elite-pcb-designer/legacy-pipeline/example_k1_routing.py similarity index 100% rename from example_k1_routing.py rename to tools/elite-pcb-designer/legacy-pipeline/example_k1_routing.py diff --git a/freerouting_config.py b/tools/elite-pcb-designer/legacy-pipeline/freerouting_config.py similarity index 100% rename from freerouting_config.py rename to tools/elite-pcb-designer/legacy-pipeline/freerouting_config.py diff --git a/ipc_standards_library.py b/tools/elite-pcb-designer/legacy-pipeline/ipc_standards_library.py similarity index 100% rename from ipc_standards_library.py rename to tools/elite-pcb-designer/legacy-pipeline/ipc_standards_library.py diff --git a/k1_board_automation_template.py b/tools/elite-pcb-designer/legacy-pipeline/k1_board_automation_template.py similarity index 100% rename from k1_board_automation_template.py rename to tools/elite-pcb-designer/legacy-pipeline/k1_board_automation_template.py diff --git a/populate_board_from_netlist.py b/tools/elite-pcb-designer/legacy-pipeline/populate_board_from_netlist.py similarity index 100% rename from populate_board_from_netlist.py rename to tools/elite-pcb-designer/legacy-pipeline/populate_board_from_netlist.py diff --git a/populate_board_manual.py b/tools/elite-pcb-designer/legacy-pipeline/populate_board_manual.py similarity index 100% rename from populate_board_manual.py rename to tools/elite-pcb-designer/legacy-pipeline/populate_board_manual.py diff --git a/run_elite_designer.py b/tools/elite-pcb-designer/legacy-pipeline/run_elite_designer.py similarity index 100% rename from run_elite_designer.py rename to tools/elite-pcb-designer/legacy-pipeline/run_elite_designer.py diff --git a/run_placement_demo.sh b/tools/elite-pcb-designer/legacy-pipeline/run_placement_demo.sh similarity index 78% rename from run_placement_demo.sh rename to tools/elite-pcb-designer/legacy-pipeline/run_placement_demo.sh index 62fcac0..dbb4f12 100755 --- a/run_placement_demo.sh +++ b/tools/elite-pcb-designer/legacy-pipeline/run_placement_demo.sh @@ -1,6 +1,8 @@ #!/bin/bash # Run K1 Lightwave component placement demo with KiCad's Python +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + # KiCad Python path KICAD_PYTHON="/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/3.9/bin/python3" @@ -14,4 +16,4 @@ fi echo "Using KiCad Python: $KICAD_PYTHON" echo "" -exec "$KICAD_PYTHON" demo_placement.py "$@" +exec "$KICAD_PYTHON" "$SCRIPT_DIR/demo_placement.py" "$@" diff --git a/run_placement_test.sh b/tools/elite-pcb-designer/legacy-pipeline/run_placement_test.sh similarity index 77% rename from run_placement_test.sh rename to tools/elite-pcb-designer/legacy-pipeline/run_placement_test.sh index c7defa0..c14418a 100755 --- a/run_placement_test.sh +++ b/tools/elite-pcb-designer/legacy-pipeline/run_placement_test.sh @@ -1,6 +1,8 @@ #!/bin/bash # Wrapper script to run component placement tests with KiCad's Python +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + # KiCad Python path KICAD_PYTHON="/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/3.9/bin/python3" @@ -14,4 +16,4 @@ fi echo "Using KiCad Python: $KICAD_PYTHON" echo "" -exec "$KICAD_PYTHON" test_component_placement.py "$@" +exec "$KICAD_PYTHON" "$SCRIPT_DIR/test_component_placement.py" "$@" diff --git a/test_automated_routing.py b/tools/elite-pcb-designer/legacy-pipeline/test_automated_routing.py similarity index 100% rename from test_automated_routing.py rename to tools/elite-pcb-designer/legacy-pipeline/test_automated_routing.py diff --git a/test_component_placement.py b/tools/elite-pcb-designer/legacy-pipeline/test_component_placement.py similarity index 100% rename from test_component_placement.py rename to tools/elite-pcb-designer/legacy-pipeline/test_component_placement.py diff --git a/test_design_preparation.py b/tools/elite-pcb-designer/legacy-pipeline/test_design_preparation.py similarity index 100% rename from test_design_preparation.py rename to tools/elite-pcb-designer/legacy-pipeline/test_design_preparation.py diff --git a/test_design_validation.py b/tools/elite-pcb-designer/legacy-pipeline/test_design_validation.py similarity index 100% rename from test_design_validation.py rename to tools/elite-pcb-designer/legacy-pipeline/test_design_validation.py diff --git a/test_elite_pcb_designer.py b/tools/elite-pcb-designer/legacy-pipeline/test_elite_pcb_designer.py similarity index 100% rename from test_elite_pcb_designer.py rename to tools/elite-pcb-designer/legacy-pipeline/test_elite_pcb_designer.py diff --git a/test_ipc_standards.py b/tools/elite-pcb-designer/legacy-pipeline/test_ipc_standards.py similarity index 100% rename from test_ipc_standards.py rename to tools/elite-pcb-designer/legacy-pipeline/test_ipc_standards.py diff --git a/validate_k1_lightwave.py b/tools/elite-pcb-designer/legacy-pipeline/validate_k1_lightwave.py similarity index 100% rename from validate_k1_lightwave.py rename to tools/elite-pcb-designer/legacy-pipeline/validate_k1_lightwave.py diff --git a/validation_report_template.py b/tools/elite-pcb-designer/legacy-pipeline/validation_report_template.py similarity index 100% rename from validation_report_template.py rename to tools/elite-pcb-designer/legacy-pipeline/validation_report_template.py