# Embedded Firmware From Hardware > Build and review maintainable embedded MCU firmware from schematic, PCB, netlist, pin-map, BOM, Keil/C51/MDK projects, vendor demo code, or hardware debug evidence. Use when Codex must convert hardware design knowledge into firmware architecture, BSP/HAL code, pin configuration, peripheral drivers, board diagnostics, touch-key/keypad/display/buzzer/WiFi bring-up, or investigate why firmware does not match schematic/PCB behavior. - Skill: `tansuo2021/embedded-firmware-from-hardware` (Agent Skill, multi-file: 9 files) - Install (CLI): `npx skillmds@latest add tansuo2021/embedded-firmware-from-hardware` - Raw SKILL.md: https://api.skillmd.com/api/skills/tansuo2021/embedded-firmware-from-hardware/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tansuo2021 (https://skillmd.com/u/tansuo2021) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tansuo2021/embedded-firmware-from-hardware --- # Embedded Firmware From Hardware ## Core Rule Treat the schematic/PCB as the source of truth for pins and nets, and treat vendor libraries as state machines with required setup, service, restart, and IO-bias contracts. Do not replace a vendor peripheral flow with intuition such as "this should be high impedance" unless the working reference, datasheet, or measured behavior supports it. ## Workflow 1. **Extract hardware evidence** - Build a pin map: MCU pin, alternate function, schematic net, series parts, destination component, PCB pad, and uncertainty. - Trace each user-visible function end-to-end: input electrode/switch -> resistor/filter -> MCU pin -> firmware symbol -> behavior. - Mark polarity, pull state, power domain, level shifting, reset/default state, and "needs measurement" items. - For MCU datasheets, app notes, and vendor PDFs, extract text first; if text is sparse or screenshots contain instructions, render pages as images and read the visual content before deciding the implementation. Prefer `scripts/pdf_evidence.py` for repeatable extraction/rendering. For Chinese filenames on Windows, enumerate PDFs with Python `Path.glob()` or use a Python launcher/environment that preserves Unicode paths. 2. **Choose firmware ownership** - Put product logic in `App/`. - Put board pins and MCU registers in `BSP/`. - Put external chips/protocols in `Drivers/`. - Keep vendor libraries under a clear folder inside the target firmware project, such as `Firmware/TKDriver/`, and wrap them with a BSP adapter. Do not leave a Keil project depending on a sibling `../TKDriver` path when the vendor manual says to copy/export the driver into the target project. - Keep `Config/board_config.h` as the board contract: clocks, pin/channel mappings, timings, display mapping, diagnostic flags. 3. **Bring up in layers** - First verify clock, power-safe GPIO defaults, and unused-pin handling. - Then bring up one visible output path such as display or buzzer. - Then bring up one input path with an on-board diagnostic display before integrating product behavior. - Only after each layer is observable should `App/` depend on it. 4. **Use board diagnostics** - Prefer diagnostics that work without a debugger: display status codes, beep patterns, LED patterns, or UART logs. - Distinguish "interrupt not firing", "scan not completing", "raw event present", and "mapped application event present". - Never diagnose "no input response" only from product behavior; add counters/status at the BSP boundary. 5. **Compare against known-good evidence** - When a known-good firmware exists, diff BSP pin setup, vendor library call order, restart/service calls, thresholds, project options, startup files, and linker output. - Favor the smallest transferable differences rather than wholesale copying generated output. 6. **Create the buildable project when requested** - If the user asks for embedded software development and a Keil/C51 toolchain is present, create or update a real `.uvproj`/`.uvprojx` project unless the user explicitly says not to. - Put vendor groups such as `TKDriver` visibly in the project tree, include headers/config files for review, include all required `.C` and `.LIB` files for build, then run UV4 build/rebuild to prove the HEX path. ## Implementation Standards Use [references/architecture.md](references/architecture.md) when designing or refactoring firmware structure. Use [references/hardware-to-firmware-checklist.md](references/hardware-to-firmware-checklist.md) when converting a schematic/PCB report into code tasks. Use [references/pdf-datasheet-workflow.md](references/pdf-datasheet-workflow.md) when a PDF datasheet or app note must be read with both text extraction and rendered page evidence. Use [references/vendor-touch-libraries.md](references/vendor-touch-libraries.md) when working with capacitive touch, spring touch keys, TK libraries, or scan/restart/threshold problems. Use [references/sinone-sc95f861xb.md](references/sinone-sc95f861xb.md) when working with SinOne/SOC SC95F861xB 8051 MCUs, especially GPIO, TK, UART0, USCI SPI/TWI/UART, clock options, interrupts, and Keil C51 register setup. Use [references/keil-c51-project-review.md](references/keil-c51-project-review.md) when a Keil C51/8051 project builds but hardware behavior is wrong, or when comparing a current project against a known-good Keil project. ## Debugging Heuristics - If a visible app keeps running but input has no effect, confirm the BSP input event before touching app logic. - If a capacitive touch channel never fires, inspect IO mode, pull/bias state, selected channel mask, threshold bytes, interrupt enable, status bit handling, and required restart call. - If changing thresholds does nothing, assume the scan flow or IO-bias contract may be wrong. - If a diagnostic build still shows old product behavior, suspect the wrong HEX was flashed or the flash operation did not take. - If a register comment says "input" but known-good code sets output/pull bits, trust measured/known-good behavior until the datasheet register semantics are confirmed. ## Deliverables When using this skill, finish with: - The hardware evidence used. - The firmware files changed or proposed. - The reason each pin/register/library call is needed. - Build result and artifact path. - A board-test procedure with observable expected results.