[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-83973":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":12,"openIssues":13,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":14,"stars7d":15,"stars30d":15,"stars90d":13,"forks30d":13,"starsTrendScore":16,"compositeScore":17,"rankGlobal":8,"rankLanguage":8,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":8,"pushedAt":8,"updatedAt":23,"readmeContent":24,"aiSummary":8,"trendingCount":13,"starSnapshotCount":13,"syncStatus":14,"lastSyncTime":25,"discoverSource":26},83973,"ADtoKeil","Tansuo2021\u002FADtoKeil","Tansuo2021",null,"Python",78,6,63,0,2,7,11,47.74,"GNU General Public License v3.0",false,"main",true,[],"2026-06-12 04:01:42","# ADtoKeil · Hardware → Firmware Skill Suite\n\n> **Languages:** **English** · [简体中文](README.zh-CN.md)\n\n> An **embedded hardware development skill suite** for AI agents (Claude Code \u002F Codex): from reading Altium schematics, to evidence-led circuit analysis, hardware-driven firmware, Keil builds, serial debugging, and one-click workflow orchestration — enabling AI to understand and develop embedded systems from **verifiable circuit evidence** rather than guesswork.\n\n[![Skills](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fskills-6-2de2e6)](#skill-overview)\n[![Python](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.12%2B-3776ab)](#requirements)\n[![Platform](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatform-Windows-0a7bd6)](#requirements)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-AGPL--3.0-orange)](#license--compliance)\n\n---\n\n## Table of Contents\n\n- [What is this](#what-is-this)\n- [Core Principles](#core-principles)\n- [Skill Overview](#skill-overview)\n- [Architecture](#architecture)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Skills in Detail](#skills-in-detail)\n- [Typical Workflow](#typical-workflow)\n- [Configuration](#configuration)\n- [License & Compliance](#license--compliance)\n- [Contributing](#contributing)\n- [Star History](#star-history)\n- [Acknowledgements](#acknowledgements)\n\n---\n\n## What is this\n\n`ADtoKeil` is a collection of **skills** callable by AI coding assistants (Claude Code, Codex, etc.). Each skill consists of a `SKILL.md` (capability declaration + invocation contract) and a set of Python scripts, covering the key stages of embedded development:\n\n```\nSchematic Reading → Circuit Analysis → Firmware Generation → Keil Build → Serial Debug → Workflow Orchestration\n```\n\nThe core problem it solves: **stop the AI from \"guessing the circuit from filenames\u002Fscreenshots\", and instead reason from structured netlists, pin-level connectivity, PCB pads, and local annotations — all verifiable evidence.**\n\n## Core Principles\n\n- **Evidence-led** — Net names, part values, and symbol shapes are only clues. A conclusion must be proven by netlist endpoints, full symbol-pin coverage, PCB pads, local labels, or datasheets.\n- **Explicit uncertainty** — Conclusions are graded `Confirmed` \u002F `Likely` \u002F `Hypothesis` \u002F `Unknown`. Never present a hypothesis as fact.\n- **Hardware is the source of truth** — The schematic\u002FPCB defines pins and nets; vendor libraries are treated as state machines with init \u002F service \u002F restart \u002F IO-bias contracts.\n- **Layered, observable firmware** — Verify clock and safe GPIO defaults first, bring up output\u002Finput paths layer by layer, and only then let the application layer depend on them.\n- **Don't guess, list candidates** — When multiple projects \u002F targets \u002F ports \u002F backends exist, list candidates for the user to choose instead of deciding arbitrarily.\n\n---\n\n## Skill Overview\n\n| # | Skill | Purpose | When it triggers |\n|---|-------|---------|------------------|\n| 1 | **altium-schematic-reader** | Parse `.PrjPcb` \u002F `.SchDoc` → compact JSON slices | Understand, explain, review, or query an Altium design (components\u002Fnets\u002Fpins\u002FBOM\u002Fpower) |\n| 2 | **altium-circuit-investigator** | Evidence-led net tracing + full pin coverage + PCB cross-check | Prove circuit function, map MCU pins, define external ports before writing a report\u002Fdesign doc |\n| 3 | **embedded-firmware-from-hardware** | Build\u002Freview maintainable MCU firmware from hardware evidence | Turn hardware knowledge into BSP\u002FHAL code, pin config, peripheral drivers, board diagnostics |\n| 4 | **keil** | Drive Keil MDK\u002FuVision to scan · build · emit HEX | Anything involving Keil\u002FMDK\u002FUV4\u002FC51\u002F8051, compile, build\u002Frebuild\u002Fclean, artifact paths |\n| 5 | **serial** | UART\u002FCOM port scan · monitor · send\u002Freceive · log | Serial debugging, baud rate, AT commands, hex streams, capturing UART evidence |\n| 6 | **workflow** | Thin orchestrator: build → flash → debug → observe | Explicit requests for \"one-click build\u002Fflash \u002F auto-diagnosis\" |\n\n---\n\n## Architecture\n\n```\nPresentation \u002F Orchestration\n  └─ workflow            (select backends, chain skills, aggregate results)\n        │\n        ├─ keil          (build backend: scan project \u002F enumerate targets \u002F build·rebuild·clean \u002F parse log → HEX)\n        ├─ serial        (observe backend: scan \u002F monitor \u002F send-receive \u002F log)\n        └─ flash·debug   (placeholder: J-Link \u002F OpenOCD \u002F probe-rs — needs an extra backend skill)\n\nUnderstanding \u002F Design\n  ├─ altium-schematic-reader      (structured facts: netlist \u002F components \u002F nets \u002F connections \u002F BOM)\n  ├─ altium-circuit-investigator  (evidence reasoning: trace \u002F coverage \u002F port inventory \u002F region render)\n  └─ embedded-firmware-from-hardware (hardware → firmware: layered BSP \u002F Drivers \u002F App + board diagnostics)\n\nState Hub\n  └─ .embeddedskills\u002Fstate.json   (chains per-stage artifacts and context within a workspace)\n```\n\n**Dependency direction:** `workflow` calls lower-level skills; the understanding layer feeds facts to the firmware layer; skills collaborate via workspace config and state files under `.embeddedskills\u002F`.\n\n---\n\n## Requirements\n\n- **OS:** Windows (examples use PowerShell; Keil invocation depends on `UV4.exe`)\n- **Python:** 3.12+ (caches show 3.12 \u002F 3.14 both run)\n- **Optional dependencies:**\n  - `altium-monkey` (required by skills 1 & 2 to parse Altium files)\n  - `pyserial` (skill 5 serial I\u002FO)\n  - Keil MDK \u002F C51 (skill 4 `UV4.exe`)\n\n> On Windows, if the default `python` is too new or missing a dependency, try another launcher such as `py -3.12` before concluding the dependency is absent.\n\n---\n\n## Installation\n\n```powershell\n# 1) Get the suite (drop it into your AI assistant's skills directory, or clone locally)\ngit clone https:\u002F\u002Fgithub.com\u002FTansuo2021\u002FADtoKeil.git\n\n# 2) Required to parse Altium files (skills 1 \u002F 2)\npip install altium-monkey\n# When using an altium_monkey source checkout:\n$env:PYTHONPATH=\"path\\to\\altium_monkey\\src\\py\"\n\n# 3) Required for serial debugging (skill 5)\npip install pyserial\n\n# 4) Keil build (skill 4): install Keil MDK and point keil\u002Fconfig.json at UV4.exe\n```\n\nEvery skill's scripts run standalone. The unified command pattern is:\n\n```powershell\npython \u003Cskill_dir>\\scripts\\\u003Cscript>.py \u003Ccommand> [args] [--json]\n```\n\n> `\u003Cskill_dir>` is the absolute or relative path to that skill's folder in your environment.\n\n---\n\n## Quick Start\n\n```powershell\n# Read an Altium project: always start with summary\npython \u003Cskill_dir>\\scripts\\read_schematic.py summary path\\to\\Project.PrjPcb\n\n# Inspect all connections of an MCU\npython \u003Cskill_dir>\\scripts\\read_schematic.py connections path\\to\\Project.PrjPcb --designator U7\n\n# One-click build (when a Keil backend is configured)\npython \u003Cskill_dir>\\scripts\\workflow_run.py build --json\n\n# Scan serial ports and monitor the boot banner\npython \u003Cskill_dir>\\scripts\\serial_scan.py --json\npython \u003Cskill_dir>\\scripts\\serial_monitor.py --port COM3 --baudrate 115200 --timestamp --timeout 10\n```\n\n---\n\n## Skills in Detail\n\n### 1. altium-schematic-reader\nReads Altium files via `altium-monkey` and emits **compact JSON slices** for AI reasoning. All commands print JSON to stdout (errors to stderr).\n\n| Command | Purpose |\n|---------|---------|\n| `summary \u003Cprj>` | Project overview (preferred entry; includes power\u002Fground nets) |\n| `components \u003Cprj> [--brief\\|--sheet\\|--designator]` | Component list |\n| `nets \u003Cprj> [--contains\\|--name]` | Net list \u002F all terminals on a net |\n| `connections \u003Cprj> --designator U7 [--pin C9]` | Component \u002F single-pin connectivity |\n| `bom \u003Cprj> [--variant]` | BOM and variants |\n| `sheet \u003Cschdoc>` | Use only when a single `.SchDoc` is available |\n| `raw \u003Cprj> design\\|netlist` | Last-resort escape hatch (output can be large) |\n\n**Reasoning rules:** cite designators, pin numbers, net names, sheet filenames; prefer project-level over single-sheet; distinguish \"not in netlist\" from \"not on symbol\" (mark unconnected pins as `NC`).\n\n### 2. altium-circuit-investigator\nComplements skill 1: collect structured net\u002Fcomponent data first, then prove circuit meaning with topology, local labels, PCB evidence, and coverage checks.\n\n**Non-negotiable coverage gates (before a report):** port inventory → cover every MCU symbol pin (mark missing nets `NC`) → cover every connector pin → schematic vs PCB pad comparison → render local context for every \"unknown\" signal → deep-trace each firmware-relevant control\u002Ffeedback signal at least one active device beyond the MCU → list open questions explicitly.\n\n| Script | Purpose |\n|--------|---------|\n| `port_inventory.py` | Collect connectors, full symbol pins, MCU pins, suspicious nets, local labels, PCB pads |\n| `coverage_report.py` | Summarize completeness; highlight MCU pins \u002F PCB-only ports \u002F suspicious nets |\n| `trace_net_deep.py` | Multi-hop trace through passives, drivers, optocouplers, relays, switches, connectors |\n| `render_region.py` | Render schematic SVG around a net endpoint\u002Fcoordinate |\n| `schdoc_probe.py` | Single-sheet `.SchDoc` tracing\u002Frendering when project-level tools are unavailable |\n| `generate_firmware_design_report.py` | Generate a Chinese firmware-design document scaffold |\n\n### 3. embedded-firmware-from-hardware\nTurns hardware knowledge into a **maintainable firmware architecture**. Core rule: the schematic\u002FPCB is the source of truth for pins and nets; vendor libraries are state machines with init\u002Fservice\u002Frestart\u002FIO-bias contracts — do not replace their flow with intuition.\n\n**Firmware ownership (layered):** `App\u002F` (product logic) · `BSP\u002F` (board pins & MCU registers) · `Drivers\u002F` (external chips\u002Fprotocols) · vendor libs (e.g. `Firmware\u002FTKDriver\u002F`) inside the target project, wrapped by a BSP adapter · `Config\u002Fboard_config.h` as the board contract.\n\n**Bring up in layers:** clock\u002Fsafe GPIO\u002Funused pins → one output path (display\u002Fbuzzer) → one input path with on-board diagnostics → only then let `App\u002F` depend on it.\n\n### 4. keil\nDrives Keil\u002FuVision (8051\u002FC51 and MDK). Prefer the scripts over invoking `UV4.exe` by hand.\n\n| Script \u002F Command | Purpose |\n|------------------|---------|\n| `keil_project.py scan --root \u003Cws> --json` | Scan `.uvproj\u002F.uvprojx\u002F.uvmpw` projects |\n| `keil_project.py targets --project \u003Cp> --json` | Enumerate targets |\n| `keil_build.py build\\|rebuild\\|clean --project \u003Cp> --target \u003Ct> --workspace \u003Cws> --json` | Build and parse log; return HEX\u002FAXF paths & metrics |\n\nAfter success: report project, target, log file, errors\u002Fwarnings, HEX\u002FAXF paths; persist to `.embeddedskills\u002Fstate.json` for workflow reuse.\n\n> Parameter priority: CLI > workspace config > skill config > `state.json` > scan result.\n> Never edit `.uvproj\u002F.uvprojx\u002F.uvopt\u002F.uvoptx` unless the user explicitly asks.\n\n### 5. serial\nUART\u002FCOM observation and command exchange during bring-up.\n\n| Script | Purpose |\n|--------|---------|\n| `serial_scan.py --json` | Scan available ports |\n| `serial_monitor.py --port COM3 --baudrate 115200 --timestamp` | Text monitor (filters\u002Ftimestamps) |\n| `serial_send.py \"AT\" --crlf --wait-response --json` | Send text (optional response wait) |\n| `serial_send.py \"01 03 00 00 00 02\" --hex --json` | Send hex |\n| `serial_hex.py` | View binary stream as a hex dump |\n| `serial_log.py --duration 30 --timestamp --json` | Record logs (text\u002FCSV\u002FJSON) |\n\n**Bring-up pattern:** scan & confirm adapter → monitor reset banner → if no output, check baud \u002F TX-RX \u002F voltage domain \u002F firmware UART init \u002F whether the current HEX was flashed → log evidence before changing firmware → send one minimal request and wait.\n\n> Safety: never send data unless required; don't guess the port when several exist; don't guess baud rate; prefer passive monitoring.\n\n### 6. workflow\nA **thin coordinator** — it does not duplicate lower-level logic; it selects backends, calls lower-level scripts, and chains results via `.embeddedskills\u002Fstate.json`.\n\n```powershell\npython \u003Cskill_dir>\\scripts\\workflow_run.py plan|build|build-flash|build-debug|observe|diagnose --json\n```\n\nBackend selectors: `--build-backend auto|keil|gcc`, `--flash-backend`\u002F`--debug-backend`\u002F`--observe-backend auto|jlink|openocd|probe-rs`.\n\n> Current boundary: Keil build works when configured; flash\u002Fdebug\u002Fobserve are orchestration placeholders until a dedicated backend is configured. On any failure, report that stage first with the lower-level log path.\n\n---\n\n## Typical Workflow\n\n```text\nGoal: take an unfamiliar board and produce working firmware\n\n1. Read the circuit   altium-schematic-reader        summary → connections \u002F nets\n                            ↓ structured facts\n2. Analyze evidence   altium-circuit-investigator     port_inventory → coverage_report\n                            ↓ full pin coverage + deep net trace + PCB cross-check (Confirmed\u002FLikely\u002FHypothesis)\n3. Derive firmware    embedded-firmware-from-hardware layered BSP\u002FDrivers\u002FApp + board_config.h\n                            ↓\n4. Build artifact     keil                            scan → build → parse log → out\u002Ffirmware.hex\n                            ↓ writes .embeddedskills\u002Fstate.json\n5. Flash & observe    serial                          scan → monitor boot banner → log evidence\n                            ↓\n6. Orchestrate        workflow                        build → flash → debug → observe (aggregated)\n```\n\n---\n\n## Configuration\n\nWorkspace-level config lives in `.embeddedskills\u002Fconfig.json`:\n\n```json\n{\n  \"keil\": {\n    \"uv4_exe\": \"C:\u002FKeil_v5\u002FUV4\u002FUV4.exe\",\n    \"project\": \"path\u002Fto\u002Fproject.uvproj\",\n    \"target\": \"Target 1\",\n    \"log_dir\": \".embeddedskills\u002Fbuild\"\n  },\n  \"serial\": {\n    \"port\": \"COM3\",\n    \"baudrate\": 115200,\n    \"encoding\": \"utf-8\",\n    \"log_dir\": \".embeddedskills\u002Flogs\u002Fserial\"\n  },\n  \"workflow\": {\n    \"preferred_build\": \"keil\",\n    \"preferred_flash\": \"auto\",\n    \"preferred_debug\": \"auto\",\n    \"preferred_observe\": \"auto\"\n  }\n}\n```\n\n- See each skill's `config.example.json` for reference.\n- `keil` also supports an environment-level `keil\u002Fconfig.json` pointing at `UV4.exe`. **This file holds real machine paths and is git-ignored** — copy `config.example.json` to `config.json` locally.\n- Cross-stage state is maintained in `.embeddedskills\u002Fstate.json` (also git-ignored).\n\n---\n\n## License & Compliance\n\nThis project is released under the **GNU Affero General Public License v3.0 (AGPL-3.0)** — see [`LICENSE`](LICENSE).\n\n> **Why AGPL-3.0:** skills 1 & 2 depend on **`altium-monkey`**, which is licensed under **AGPL-3.0-or-later**. Adopting AGPL-3.0 for this project keeps it compatible with that dependency. Note that AGPL is \"viral\": if you **distribute** a modified version, or **expose its functionality through a network service**, you must make the corresponding source available under AGPL-3.0. Review the license before distributing or hosting.\n\nAlso note: the previous repo state contained hardcoded local paths and a personal username; these have been removed for public release. Keep machine-specific config (`keil\u002Fconfig.json`, `.embeddedskills\u002F`, `.env`) out of version control via [`.gitignore`](.gitignore).\n\n---\n\n## Contributing\n\nIssues \u002F PRs welcome:\n\n- **New skill:** include a `SKILL.md` (with `name` + `description` frontmatter) and standalone scripts; commands should support `--json`.\n- **Code style:** scripts emit structured JSON, errors to stderr; list candidates instead of guessing when ambiguous.\n- **Docs:** add domain knowledge under `references\u002F`; keep the \"evidence-first, explicit-uncertainty\" style.\n- **Tests:** cover the happy path and edges (null values, missing PCB, busy port, build failure, etc.).\n- **Compliance:** never commit personal paths, usernames, secrets, or machine-specific config.\n\n---\n\n## Star History\n\n[![Star History Chart](https:\u002F\u002Fapi.star-history.com\u002Fsvg?repos=Tansuo2021\u002FADtoKeil&type=Date)](https:\u002F\u002Fstar-history.com\u002F#Tansuo2021\u002FADtoKeil&Date)\n\nIf this project helps you, please consider giving it a ⭐ — it really helps!\n\n---\n\n## Acknowledgements\n\n- Thanks to the **[linux.do](https:\u002F\u002Flinux.do)** community — for the sharing, discussion, and inspiration that made this suite possible. 🙏\n- Built to be driven by AI coding agents such as Claude Code and Codex.\n- Altium parsing powered by the open-source [`altium-monkey`](https:\u002F\u002Fpypi.org\u002Fproject\u002Faltium-monkey\u002F) project.\n","2026-06-11 04:11:57","CREATED_QUERY"]