embedded-firmware-from-hardware

name

embedded-firmware-from-hardware

description

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.

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 when designing or refactoring firmware structure.

Use references/hardware-to-firmware-checklist.md when converting a schematic/PCB report into code tasks.

Use 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 when working with capacitive touch, spring touch keys, TK libraries, or scan/restart/threshold problems.

Use 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 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.