@protoboardai/ext-esp-idf 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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.

package/NOTICE

@@ -0,0 +1,13 @@
+Protoboard Stack: @protoboardai/ext-esp-idf
+Copyright 2026 Delta Robotics, Inc.
+
+This product includes software developed at Delta Robotics, Inc.
+(https://deltaroboticsinc.com).
+
+Licensed under the Apache License, Version 2.0 (the "License").
+See the LICENSE file in this package for full terms.
+
+"Protoboard", the Protoboard logo and the "0" mark are trademarks of
+Delta Robotics, Inc. The License grants no rights to them (section 6);
+see TRADEMARKS.md in the Protoboard Stack repository
+(https://github.com/Delta-Robotics-Inc/protoboard-stack).

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# @protoboardai/ext-esp-idf
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A provider of the `firmware` capability
+([tool integrations](../../docs/specs/tool-integrations.md)). It turns
+a UHD board whose controller is an ESP32-C3 module into an
+[ESP-IDF](https://docs.espressif.com/projects/esp-idf/) pins and peripherals
+header and `sdkconfig.defaults`. Every setting line cites the UHD facts it
+comes from, in a comment for people and in `firmware.manifest.json` for
+tools. Checked against ESP-IDF **v5.3.5** (Kconfig symbols at the `v5.3.5`
+tag).
+
+ESP-IDF configures pins in code (`i2c_new_master_bus`, `gpio_config`,
+`esp_deep_sleep_enable_gpio_wakeup`), not in a devicetree, so the header
+carries the board and `sdkconfig.defaults` only what Kconfig owns.
+
+A project selects it for one board, in the config next to the board module:
+
+```ts
+// src/boards/mainboard/firmware.config.ts
+import { defineCapabilityConfig } from "@protoboardai/core";
+
+export default defineCapabilityConfig({
+  provider: "@protoboardai/ext-esp-idf",
+  constraints: {
+    wake: ["sw2", "u4"], // the wake button and the fuel gauge's alert wake it from Deep-sleep
+  },
+});
+```
+
+```sh
+protoboard run firmware:generate --module mainboard   # src/boards/mainboard/esp-idf/
+protoboard run firmware:export   --module mainboard   # out/config/ + out/firmware.manifest.json
+protoboard check                                      # includes firmware:check for the board
+```
+
+`test/fixtures/bottle-core` is a complete example: an ESP32-C3-MINI-1-H4X with
+an LED driver, a time-of-flight sensor and a fuel gauge on I2C, a DS18B20
+probe on 1-Wire, a BOOT button on GPIO9 and a wake button on GPIO5, a
+32.768 kHz crystal on GPIO0/1, a GNSS on GPIO20/21 and USB Serial/JTAG on
+GPIO18/19. Its generated files are the golden files in `test/golden/`.
+
+## What it writes
+
+```
+esp-idf/
+  board_pins.h            buses (port, pins, clock, pull-ups), device addresses and controls,
+                          1-Wire, buttons, status lines, Deep-sleep wake masks
+  sdkconfig.defaults      CONFIG_IDF_TARGET, flash size, console, RTC clock source
+  protoboard.lines.json   digest and cites of every file (what export turns into the manifest)
+```
+
+Put `board_pins.h` where the application includes it (`main/` or a `board`
+component) and list `sdkconfig.defaults` first in `SDKCONFIG_DEFAULTS`, with
+the project's own defaults after it. Do not edit the generated files: export
+refuses an edited file and check reports it.
+
+```c
+#include "board_pins.h"
+
+i2c_master_bus_config_t bus = {
+  .i2c_port = BOARD_I2C0_PORT, .sda_io_num = BOARD_I2C0_SDA, .scl_io_num = BOARD_I2C0_SCL,
+  .clk_source = I2C_CLK_SRC_DEFAULT, .flags.enable_internal_pullup = BOARD_I2C0_INTERNAL_PULLUPS,
+};
+esp_deep_sleep_enable_gpio_wakeup(BOARD_DEEP_SLEEP_WAKE_LOW_MASK, ESP_GPIO_WAKEUP_GPIO_LOW);
+```
+
+## How the board maps to ESP-IDF
+
+1. **Firmware map** (tool-neutral, in `@protoboardai/core`: `boardFirmware`),
+   as for every firmware provider: buses from the peripherals' composites,
+   controls from the peripheral pins' capabilities, buttons from switches
+   between a controller net and ground, external pull resistors from the
+   nets.
+2. **SoC table** (`lib/soc.ts`). The controller's SoC fact
+   ("ESP32-C3FH4X, …") selects the ESP32-C3: one I2C controller, SPI2 as the
+   general-purpose SPI host, UART0 and UART1. A module pin's GPIO number is
+   its `gpio<n>` capability.
+3. **Console.** USB Serial/JTAG (`CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG`) when
+   GPIO18/19 are wired to a connector, else UART0; with the console on UART0,
+   a UART device gets UART1.
+4. **Clocks and flash.** A 32.768 kHz crystal on GPIO0/1 (XTAL_32K_P/N)
+   selects `CONFIG_RTC_CLK_SRC_EXT_CRYS`; the module's `memory.flash_MB` fact
+   sets `CONFIG_ESPTOOLPY_FLASHSIZE_<n>MB`.
+5. **Strapping and wake.** The part marks GPIO2, GPIO8 and GPIO9 as strapping
+   pins and GPIO0-5 as able to wake it from Deep-sleep (`deep_sleep_wakeup`,
+   the RTC IO). A peripheral output on a strapping pin is an error; a button
+   on GPIO9 is the BOOT button and only noted. Each wake source must arrive
+   on an RTC GPIO; the header gives one mask per wake level.
+
+## Constraints
+
+| Key | Meaning |
+| --- | --- |
+| `controller` | instance path of the controller, when the board has more than one microcontroller |
+| `console` | `usb` (USB Serial/JTAG; the default when GPIO18/19 are wired) or `uart0` |
+| `i2c_frequency_hz` | I2C clock (default: the slowest device's limit, 400 kHz at most) |
+| `uart_baud` | `{ <instance>: baud }` for UART devices that state no `baud_rate` |
+| `wake` | inputs that wake the chip from Deep-sleep: button or device instances, or nets |
+
+## Checks
+
+`firmware:check` runs the shared rules from `@protoboardai/core` (codes in the
+[provider guide](../../docs/guides/writing-a-capability-provider.md#diagnostic-codes),
+including `FW_STRAPPING_DRIVEN` and `FW_WAKE_INVALID`) and these:
+
+| Code | Severity | Meaning |
+| --- | --- | --- |
+| `FW_SOC_UNSUPPORTED` | error | The controller's SoC fact names no SoC this provider knows. |
+| `FW_BUS_INSTANCES` | error | More I2C, SPI or UART buses than the ESP32-C3 has (one I2C controller; UART0 is taken when it is the console). |
+| `FW_UART_BAUD_UNKNOWN`, `FW_CONSOLE_UNKNOWN` | error | No baud rate for a UART device; a console the board cannot carry. |
+
+The tests compile `board_pins.h` with the system C compiler against a stub
+`driver/gpio.h` when one is installed, and check the values it yields.
+
+## What the output does not establish
+
+The header and defaults agree with the model and the checked ESP-IDF
+release. They have not been built into an application or flashed. The bench
+proves them: an I2C scan finds the addresses in the header, the BOOT button
+enters download mode, each wake source wakes the chip from Deep-sleep.
+
+## Tests
+
+```sh
+npx vitest run packages/ext-esp-idf                    # contract, golden files, cites, C compile, seeded faults
+UPDATE_GOLDEN=1 npx vitest run packages/ext-esp-idf    # after a deliberate change to the output
+```
+
+The test parts in `test/fixtures/parts/` are copies of researched parts; the
+README there says where they came from.

package/evals/wake-on-fuel-gauge/case.json

@@ -0,0 +1,56 @@
+{
+  "schema": "protoboard.eval-case/v0",
+  "title": "Configure ESP-IDF for the bottle cap after a wake source was asked for on a pin that cannot wake the chip",
+  "skills": ["firmware-config-esp-idf"],
+  "tags": ["firmware", "esp-idf", "judgement"],
+  "fixture": {
+    "from": "../../../../examples/smart-bottle",
+    "exclude": ["release"],
+    "steps": [
+      { "note": "the request: the fuel gauge's ALRT (u6, on IO6) as a Deep-sleep wake source", "write": { "file": "src/boards/bottle-cap/firmware.config.ts", "from": "seed-firmware.config.ts.txt" } },
+      { "note": "the firmware configuration has not been generated in this copy", "remove": "src/boards/bottle-cap/esp-idf" },
+      { "remove": "src/boards/bottle-cap/out/config" },
+      { "remove": "src/boards/bottle-cap/out/firmware.manifest.json" }
+    ]
+  },
+  "instruction": "The smart bottle's cap board (module bottle-cap-board, src/boards/bottle-cap) needs its ESP-IDF firmware configuration generated and exported; the copy you have has none yet. The firmware owner has just added the fuel gauge's alert as a Deep-sleep wake source in firmware.config.ts, so the cap can warn about a low battery. Produce fresh firmware outputs so that `npx protoboard check` reports no errors and no firmware finding left open. The board is already fabricated: do not change the board module, its circuit config or its circuit outputs. Tell me what you generated and what the firmware owner needs to know about their wake request.",
+  "tools": { "read": true, "edit": true, "commands": ["npx protoboard *"] },
+  "budget": { "turns": 30, "seconds": 900, "usd": 4 },
+  "graders": [
+    {
+      "id": "wake-fault-resolved-and-explained",
+      "kind": "fault",
+      "code": "FW_WAKE_INVALID",
+      "caught": "(gpio ?6|io ?6|pin_20)[\\s\\S]*(rtc|gpio ?0[\\s\\S]{0,12}5|cannot|can't|not able)|(rtc|gpio ?0[\\s\\S]{0,12}5)[\\s\\S]*(gpio ?6|io ?6|pin_20)",
+      "description": "the invalid wake source is gone and the answer says why (IO6 is not an RTC GPIO, only GPIO0-5 wake the chip)"
+    },
+    {
+      "id": "check-clean",
+      "kind": "check",
+      "maxErrors": 0,
+      "absent": ["FW_NOT_GENERATED", "FW_NATIVE_STALE", "FW_NATIVE_EDITED", "FW_PIN_DRIFT", "PB_OUTPUT_NOT_EXPORTED"],
+      "ran": ["ext:@protoboardai/ext-esp-idf/firmware:check", "protoboard/standard-outputs"]
+    },
+    { "id": "outputs-valid", "kind": "outputs", "module": "bottle-cap-board" },
+    { "id": "manifest", "kind": "facts", "file": "src/boards/bottle-cap/out/firmware.manifest.json", "facts": [{ "path": "schema", "equals": "protoboard.firmware/v0" }, { "path": "module", "equals": "bottle-cap-board" }, { "path": "provider", "equals": "@protoboardai/ext-esp-idf" }, { "path": "files[path=config/board_pins.h].digest", "matches": "^sha256:" }] },
+    {
+      "id": "wake-mask",
+      "kind": "text",
+      "file": "src/boards/bottle-cap/out/config/board_pins.h",
+      "matches": ["BOARD_DEEP_SLEEP_WAKE_LOW_MASK \\(\\(1ULL << GPIO_NUM_3\\)\\)", "BOARD_U6_ALRT_GPIO GPIO_NUM_6"],
+      "notMatches": ["WAKE[^\\n]*GPIO_NUM_6"],
+      "description": "the button wakes the chip; the alert is still configured as an input on IO6, not as a wake source"
+    },
+    { "id": "board-untouched", "kind": "digest", "file": "src/boards/bottle-cap/bottle-cap.uhd.ts", "changed": false },
+    { "id": "circuit-config-untouched", "kind": "digest", "file": "src/boards/bottle-cap/circuit.config.ts", "changed": false },
+    { "id": "circuit-outputs-untouched", "kind": "digest", "file": "src/boards/bottle-cap/out/netlist.json", "changed": false }
+  ],
+  "solution": [
+    { "protoboard": ["check"], "expect": { "exit": 1 } },
+    { "write": { "file": "src/boards/bottle-cap/firmware.config.ts", "from": "solution-firmware.config.ts.txt" } },
+    { "protoboard": ["run", "firmware:generate", "--module", "bottle-cap-board"], "expect": { "status": "succeeded" } },
+    { "protoboard": ["run", "firmware:export", "--module", "bottle-cap-board"], "expect": { "status": "succeeded" } },
+    { "protoboard": ["check"] },
+    { "say": "The fuel gauge's ALRT reaches the ESP32-C3 on IO6 (u1:pin_20), and only the RTC GPIOs GPIO0-5 can wake the chip from Deep-sleep, so firmware:check refused it (FW_WAKE_INVALID). GPIO0-5 are all in use and the board is fabricated, so I removed u6 from the wake sources (the button sw1 on GPIO3 stays), generated and exported: out/config/board_pins.h and sdkconfig.defaults with the manifest. The alert is still configured as an input (BOARD_U6_ALRT_GPIO, IO6, active low) for when the chip is awake; a low-battery wake needs the next board revision to route ALRT to an RTC GPIO, or the firmware can poll the gauge on each timer wake." }
+  ]
+}

package/evals/wake-on-fuel-gauge/seed-firmware.config.ts.txt

@@ -0,0 +1,16 @@
+import { defineCapabilityConfig } from "@protoboardai/core";
+
+/**
+ * The cap board's firmware configuration provider: ESP-IDF 5.3 for the
+ * ESP32-C3-MINI-1 (board_pins.h and sdkconfig.defaults in esp-idf/, standard
+ * outputs in out/config/ and out/firmware.manifest.json).
+ *
+ * Wake from Deep-sleep: the button (sw1), and the fuel gauge's ALRT (u6) so
+ * the cap can flash a low-battery warning without waiting for the next timer
+ * wake. The console is USB Serial/JTAG (the default: GPIO18/19 reach the
+ * USB-C receptacle).
+ */
+export default defineCapabilityConfig({
+  provider: "@protoboardai/ext-esp-idf",
+  constraints: { wake: ["sw1", "u6"] },
+});

package/evals/wake-on-fuel-gauge/solution-firmware.config.ts.txt

@@ -0,0 +1,18 @@
+import { defineCapabilityConfig } from "@protoboardai/core";
+
+/**
+ * The cap board's firmware configuration provider: ESP-IDF 5.3 for the
+ * ESP32-C3-MINI-1 (board_pins.h and sdkconfig.defaults in esp-idf/, standard
+ * outputs in out/config/ and out/firmware.manifest.json).
+ *
+ * Wake from Deep-sleep: the button (sw1, GPIO3, an RTC pad [B2]). The
+ * timer wakes the cap for each sample (docs/power-budget.md); the ToF sensor
+ * is in hardware standby while the chip sleeps (XSHUT held low) and the fuel
+ * gauge's alert is on GPIO6, which cannot wake the chip, so neither is a
+ * wake source. The console is USB Serial/JTAG (the default: GPIO18/19 reach
+ * the USB-C receptacle).
+ */
+export default defineCapabilityConfig({
+  provider: "@protoboardai/ext-esp-idf",
+  constraints: { wake: ["sw1"] },
+});

package/lib/design.ts

@@ -0,0 +1,227 @@
+/**
+ * ESP-IDF configuration for a UHD board whose controller is an ESP32-C3
+ * module, from the board's firmware map (`boardFirmware` in
+ * @protoboardai/core). Checked against ESP-IDF v5.3.5.
+ *
+ *   board_pins.h         every pin, bus, address, button and wake source as a
+ *                        #define, for the application's driver setup code
+ *   sdkconfig.defaults   target, flash size, console, RTC clock source
+ *
+ * ESP-IDF configures pins in code (i2c_new_master_bus, gpio_config,
+ * esp_deep_sleep_enable_gpio_wakeup), not in Kconfig, so the header carries
+ * the board and sdkconfig.defaults only what Kconfig owns. Every setting
+ * line cites the UHD facts it comes from.
+ */
+import type { InterfaceDef, ModuleDef } from "@deltarobotics/uhd";
+import type { BoardFirmware, CapabilityContext, CitedLine, FirmwareBus, FirmwareCite, FirmwareDesign, FirmwareFinding, FirmwareGpio } from "@protoboardai/core";
+import { wakeSources } from "@protoboardai/core";
+import { ESP32C3, IDF_VERSION, gpioNumber, socFact, socOf } from "./soc.ts";
+
+type Ctx = Pick<CapabilityContext, "constraints" | "module" | "project">;
+
+const macro = (s: string) => s.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+const hex = (n: number) => `0x${n.toString(16).padStart(2, "0")}`;
+
+export function designEspIdf(fw: BoardFirmware, board: ModuleDef, controller: ModuleDef, ctx: Ctx): FirmwareDesign {
+  const findings: FirmwareFinding[] = [];
+  const warnings: string[] = [];
+  const c = ctx.constraints;
+  const soc = socOf(controller);
+  const fact = socFact(controller);
+  const ctl = fw.controller!.instance;
+  if (!soc) {
+    findings.push({ code: "FW_SOC_UNSUPPORTED", severity: "error", instance: ctl, message: `${controller.id} states SoC "${fact ?? "nothing"}"; this provider knows ${ESP32C3.target} (domains[electrical].metadata.soc)` });
+    return { files: [], warnings, findings };
+  }
+  const socCite: FirmwareCite = `part:${controller.id}:domains.electrical.metadata.soc`;
+  const periphCite: FirmwareCite = `part:${controller.id}:domains.electrical.metadata.peripherals`;
+  const leaf = (pin: string) => controller.interfaces.find((i: InterfaceDef) => i.id === pin);
+  const num = (pin: string) => gpioNumber(leaf(pin))!;
+  const where = (pin: string) => `${ctl}:${pin} ${leaf(pin)?.name ?? pin}`;
+  const gpioDefine = (name: string, pin: string, cites: FirmwareCite[], why: string): CitedLine => ({ text: `#define ${name} GPIO_NUM_${num(pin)}`, cites, why });
+
+  for (const pin of Object.keys(fw.uses)) {
+    if (leaf(pin) && gpioNumber(leaf(pin)) === undefined && !fw.usb?.pins.includes(pin)) {
+      findings.push({ code: "FW_PIN_UNKNOWN", severity: "error", instance: ctl, message: `${where(pin)} has no GPIO number (capability gpio<n>), so it cannot be configured`, cites: [`pin:${ctl}:${pin}`] });
+    }
+  }
+  if (findings.length) return { files: [], warnings, findings };
+
+  // ---- console and controllers
+  const console = typeof c.console === "string" ? c.console : fw.usb ? "usb" : "uart0";
+  if (console !== "usb" && console !== "uart0") findings.push({ code: "FW_CONSOLE_UNKNOWN", severity: "error", message: `console ${console}: use "usb" (USB Serial/JTAG) or "uart0"`, cites: ["constraint:console"] });
+  if (console === "usb" && !fw.usb) findings.push({ code: "FW_CONSOLE_UNKNOWN", severity: "error", message: "console usb: the board does not wire the USB Serial/JTAG pins (GPIO18/19) to anything", cites: ["constraint:console"] });
+  const pools: Record<string, number[]> = { i2c: [...soc.i2c], spi: [...soc.spi], uart: console === "uart0" ? soc.uart.filter((n) => n !== 0) : [...soc.uart] };
+  const port = new Map<FirmwareBus, number>();
+  for (const bus of fw.buses.filter((b) => b.protocol !== "onewire")) {
+    const n = pools[bus.protocol].shift();
+    if (n === undefined) {
+      findings.push({
+        code: "FW_BUS_INSTANCES",
+        severity: "error",
+        instance: ctl,
+        message: `${bus.id}: the ${soc.target} has ${soc[bus.protocol as "i2c" | "spi" | "uart"].length} ${bus.protocol.toUpperCase()} controller(s)${bus.protocol === "uart" && console === "uart0" ? " and UART0 is the console" : ""}; put the devices on one bus`,
+        cites: [periphCite, ...bus.signals.flatMap((s) => s.cites)],
+      });
+      continue;
+    }
+    port.set(bus, n);
+  }
+  if (findings.some((f) => f.severity === "error")) return { files: [], warnings, findings };
+
+  // ---- board_pins.h
+  const h: CitedLine[] = [{ text: "#pragma once" }, { text: "" }, { text: '#include "driver/gpio.h"', cites: [socCite], why: "GPIO_NUM_x" }];
+  const section = (title: string) => h.push({ text: "" }, { text: `/* ${title} */` });
+  const levelOf = (g: FirmwareGpio) => (g.activeLow ? 0 : 1);
+  const pullOf = (g: FirmwareGpio) => (g.pull === "up" ? "GPIO_PULLUP_ONLY" : g.pull === "down" ? "GPIO_PULLDOWN_ONLY" : "GPIO_FLOATING");
+  const control = (prefix: string, g: FirmwareGpio) => {
+    const why = `${g.label}: ${where(g.pin)}${g.externalPull ? `, pulled ${g.externalPull.to} by ${g.externalPull.instance}` : ""}`;
+    h.push(gpioDefine(`${prefix}_GPIO`, g.pin, g.cites, why));
+    h.push({ text: `#define ${prefix}_ACTIVE_LEVEL ${levelOf(g)}`, cites: g.cites, why: g.activeLow ? "active low" : "active high" });
+    if (g.direction === "input") h.push({ text: `#define ${prefix}_PULL ${pullOf(g)}`, cites: g.cites, why: g.externalPull ? "the board has its own pull resistor" : g.pull ? `internal pull-${g.pull}` : "driven both ways" });
+  };
+
+  section("Controller");
+  h.push({ text: `#define BOARD_TARGET "${soc.target}"`, cites: [socCite], why: `${controller.id}: ${fact}` });
+
+  for (const [bus, n] of port) {
+    const sig = (role: string) => bus.signals.find((s) => s.role === role);
+    const B = `BOARD_${bus.protocol.toUpperCase()}${n}`;
+    if (bus.protocol === "i2c") {
+      section(`I2C${n}: ${bus.devices.map((d) => d.instance).join(", ")}`);
+      h.push({ text: `#define ${B}_PORT ${n}`, cites: [periphCite, ...bus.signals.flatMap((s) => s.cites)], why: `I2C controller ${n} (the ${soc.target} has ${soc.i2c.length})` });
+      for (const role of ["sda", "scl"]) {
+        const s = sig(role);
+        if (s) h.push(gpioDefine(`${B}_${role.toUpperCase()}`, s.pin, s.cites, `net ${s.net}: ${where(s.pin)}`));
+      }
+      const asked = c.i2c_frequency_hz;
+      const slowest = Math.min(...bus.devices.map((d) => d.maxClockHz ?? 400_000), 400_000);
+      const hz = typeof asked === "number" ? asked : slowest;
+      h.push({
+        text: `#define ${B}_FREQ_HZ ${hz}`,
+        // the controller's I2C (fast mode at most) always bounds it, so the line is cited even when no device states a clock
+        cites: [...(typeof asked === "number" ? ["constraint:i2c_frequency_hz" as const] : []), periphCite, ...bus.devices.flatMap((d) => d.cites.filter((x) => x.endsWith(".clock_freq")))],
+        why: typeof asked === "number" ? "set in firmware.config.ts" : "the slowest device's limit (400 kHz at most)",
+      });
+      const pulled = bus.signals.every((s) => fw.netlist.nets.find((x) => x.id === s.net)?.pins.some((p) => fw.netlist.components.find((k) => k.instance === p.split(":")[0])?.kind === "resistor"));
+      h.push({ text: `#define ${B}_INTERNAL_PULLUPS ${pulled ? 0 : 1}`, cites: bus.signals.map((s) => s.cites[0]), why: pulled ? "pull-up resistors on the board" : "no pull-up resistors on the board: enable the internal ones (weak, ~45 kOhm)" });
+      if (!pulled) warnings.push(`${bus.id}: no pull-up resistors on SDA/SCL; the internal ~45 kOhm pull-ups are too weak for 400 kHz on most boards`);
+      for (const d of bus.devices) {
+        if (d.address !== undefined) h.push({ text: `#define BOARD_${macro(d.instance)}_I2C_ADDR ${hex(d.address)}`, cites: d.cites, why: `${d.name} (${d.part})` });
+        for (const g of d.controls) control(`BOARD_${macro(d.instance)}_${macro(pinName(g))}`, g);
+      }
+    }
+    if (bus.protocol === "spi") {
+      section(`SPI${n}: ${bus.devices.map((d) => d.instance).join(", ")}`);
+      h.push({ text: `#define ${B}_HOST SPI${n}_HOST`, cites: [periphCite, ...bus.signals.flatMap((s) => s.cites)], why: "general-purpose SPI host" });
+      for (const role of ["sck", "mosi", "miso"]) {
+        const s = sig(role);
+        if (s) h.push(gpioDefine(`${B}_${role.toUpperCase()}`, s.pin, s.cites, `net ${s.net}: ${where(s.pin)}`));
+      }
+      for (const d of bus.devices) {
+        if (d.cs) h.push(gpioDefine(`BOARD_${macro(d.instance)}_CS`, d.cs.pin, d.cs.cites, `${d.name} chip select: ${where(d.cs.pin)}`));
+        if (d.maxClockHz) h.push({ text: `#define BOARD_${macro(d.instance)}_SPI_HZ ${Math.min(d.maxClockHz, soc.spiMaxHz)}`, cites: [...d.cites, periphCite], why: `the slower of ${d.part} and SPI${n}` });
+        for (const g of d.controls) control(`BOARD_${macro(d.instance)}_${macro(pinName(g))}`, g);
+      }
+    }
+    if (bus.protocol === "uart") {
+      const d = bus.devices[0];
+      section(`UART${n}: ${d?.instance}`);
+      h.push({ text: `#define ${B}_PORT ${n}`, cites: [periphCite, ...bus.signals.flatMap((s) => s.cites)], why: console === "uart0" ? "UART0 is the console" : `UART ${n}` });
+      for (const role of ["tx", "rx", "rts", "cts"]) {
+        const s = sig(role);
+        if (s) h.push(gpioDefine(`${B}_${role.toUpperCase()}`, s.pin, s.cites, `net ${s.net}: ${where(s.pin)}`));
+      }
+      const asked = (c.uart_baud as Record<string, unknown> | undefined)?.[d?.instance ?? ""];
+      const baud = typeof asked === "number" ? asked : d?.baud;
+      if (baud) h.push({ text: `#define ${B}_BAUD ${baud}`, cites: typeof asked === "number" ? ["constraint:uart_baud"] : [`part:${d.part}:${d.interface}.baud_rate`], why: `${d.instance} (${d.name})` });
+      else findings.push({ code: "FW_UART_BAUD_UNKNOWN", severity: "error", instance: d?.instance, message: `${d?.instance} states no baud_rate; set uart_baud: { ${d?.instance}: <baud> } in firmware.config.ts`, cites: d?.cites });
+      for (const g of d?.controls ?? []) control(`BOARD_${macro(d.instance)}_${macro(pinName(g))}`, g);
+    }
+  }
+
+  fw.buses
+    .filter((b) => b.protocol === "onewire")
+    .forEach((bus, i) => {
+      const s = bus.signals[0];
+      const B = `BOARD_ONEWIRE${i}`;
+      section(`1-Wire ${i}: ${bus.devices.map((d) => d.instance).join(", ")}`);
+      h.push(gpioDefine(`${B}_GPIO`, s.pin, s.cites, `DQ on net ${s.net}: ${where(s.pin)}`));
+      const pulled = fw.netlist.nets.find((x) => x.id === s.net)?.pins.some((p) => fw.netlist.components.find((k) => k.instance === p.split(":")[0])?.kind === "resistor");
+      h.push({ text: `#define ${B}_INTERNAL_PULLUP ${pulled ? 0 : 1}`, cites: s.cites, why: pulled ? "pull-up resistor on the board" : "no pull-up resistor on the board" });
+      if (!pulled) warnings.push(`${bus.id}: no pull-up resistor on DQ; 1-Wire needs about 4.7 kOhm, the internal pull-up is too weak for a cable`);
+      for (const d of bus.devices) {
+        const part = ctx.project.lookup(d.part);
+        const res = part?.traits?.find((t) => t.type === "performance" && (t.params as Record<string, unknown> | undefined)?.default_resolution_bits !== undefined);
+        if (res) h.push({ text: `#define BOARD_${macro(d.instance)}_RESOLUTION_BITS ${(res.params as Record<string, unknown>).default_resolution_bits}`, cites: [`part:${d.part}:traits.performance.default_resolution_bits`], why: `${d.name}: power-on resolution` });
+      }
+    });
+
+  const buttons = fw.gpios.filter((g) => g.use === "button");
+  if (buttons.length) {
+    section("Buttons");
+    for (const g of buttons) control(`BOARD_${macro(g.instance)}`, g);
+  }
+  const others = fw.gpios.filter((g) => g.use !== "button");
+  if (others.length) {
+    section("Status and control lines");
+    for (const g of others) control(`BOARD_${macro(g.instance)}_${macro(pinName(g))}`, g);
+  }
+
+  const { sources } = wakeSources(fw, c.wake);
+  if (sources.length) {
+    section("Deep-sleep wake (esp_deep_sleep_enable_gpio_wakeup: RTC GPIOs only)");
+    for (const [name, low] of [["LOW", true], ["HIGH", false]] as const) {
+      const set = sources.filter((w) => w.activeLow === low);
+      if (!set.length) continue;
+      h.push({
+        text: `#define BOARD_DEEP_SLEEP_WAKE_${name}_MASK (${set.map((w) => `(1ULL << GPIO_NUM_${num(w.pin)})`).join(" | ")})`,
+        cites: set.flatMap((w) => [...w.cites, `pin:${ctl}:${w.pin}`]),
+        why: `${set.map((w) => w.source).join(", ")}: wake when ${name.toLowerCase()} (ESP_GPIO_WAKEUP_GPIO_${name})`,
+      });
+    }
+  }
+
+  // ---- sdkconfig.defaults
+  const flash = memory(controller)?.flash_MB;
+  const sdk: CitedLine[] = [{ text: `CONFIG_IDF_TARGET="${soc.target}"`, cites: [socCite], why: `${controller.id}: ${fact}` }];
+  if (typeof flash === "number" && soc.flashSizes.includes(flash)) sdk.push({ text: `CONFIG_ESPTOOLPY_FLASHSIZE_${flash}MB=y`, cites: [`part:${controller.id}:domains.electrical.metadata.memory.flash_MB`], why: `${flash} MB flash in the package` });
+  else warnings.push(`${controller.id}: no flash size in the part (domains[electrical].metadata.memory.flash_MB); ESP-IDF keeps its 2 MB default`);
+  if (console === "usb" && fw.usb) sdk.push({ text: "CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y", cites: [...fw.usb.cites, ...(typeof c.console === "string" ? ["constraint:console" as const] : [])], why: `console on USB Serial/JTAG: D+/D- wired to ${fw.usb.peers.join(", ")}` });
+  else if (console === "uart0") sdk.push({ text: "CONFIG_ESP_CONSOLE_UART_DEFAULT=y", cites: [`pin:${ctl}:uart0`, ...(typeof c.console === "string" ? ["constraint:console" as const] : [])], why: "console on UART0 (GPIO20/21)" });
+  const xtal = fw.crystals.find((x) => x.pins.some((p) => (leaf(p)?.capabilities ?? []).some((k) => k.startsWith("xtal_32k"))));
+  if (xtal) sdk.push({ text: "CONFIG_RTC_CLK_SRC_EXT_CRYS=y", cites: xtal.cites, why: `32.768 kHz crystal ${xtal.instance} (${xtal.part}) on ${xtal.pins.map((p) => leaf(p)?.name).join(", ")} (XTAL_32K_P/N)` });
+
+  const files = [
+    {
+      path: "board_pins.h",
+      role: "pins and peripherals header",
+      style: "c-block" as const,
+      warnings: true,
+      header: [`${board.name}: pins and peripherals for ESP-IDF ${IDF_VERSION}, generated from the UHD model by @protoboardai/ext-esp-idf. Do not edit.`],
+      lines: h,
+    },
+    {
+      path: "sdkconfig.defaults",
+      role: "sdkconfig defaults",
+      style: "conf" as const,
+      warnings: true,
+      header: [`${board.name}: ESP-IDF ${IDF_VERSION} defaults, generated from the UHD model by @protoboardai/ext-esp-idf. Do not edit;`, "list your own defaults file after this one in SDKCONFIG_DEFAULTS."],
+      lines: sdk,
+    },
+  ];
+  return { files, warnings, findings };
+
+  function pinName(g: FirmwareGpio): string {
+    const part = ctx.project.lookup(g.part);
+    return part?.interfaces.find((i: InterfaceDef) => i.id === g.peripheralPin)?.name ?? g.use;
+  }
+}
+
+function memory(def: ModuleDef): Record<string, unknown> | undefined {
+  for (const d of def.domains ?? []) {
+    const m = (d as { metadata?: Record<string, unknown> }).metadata?.memory;
+    if (m && typeof m === "object") return m as Record<string, unknown>;
+  }
+  return undefined;
+}

package/lib/pins.ts

@@ -0,0 +1,19 @@
+/** Pins named in generated ESP-IDF files: `GPIO_NUM_<n>`. */
+import type { ModuleDef } from "@deltarobotics/uhd";
+import type { PinRef } from "@protoboardai/core";
+import { leafForGpio } from "./soc.ts";
+
+export function readEspIdfPins(files: Record<string, string>, controller: ModuleDef): PinRef[] {
+  const refs: PinRef[] = [];
+  for (const [file, text] of Object.entries(files)) {
+    if (!/\.h$/.test(file)) continue;
+    text.split("\n").forEach((line, i) => {
+      const code = line.replace(/\/\*.*?\*\//g, "").replace(/\/\/.*$/, "");
+      for (const m of code.matchAll(/GPIO_NUM_(\d+)\b/g)) {
+        const n = Number(m[1]);
+        refs.push({ file, line: i + 1, ref: `GPIO${n}`, pin: leafForGpio(controller, n)?.id });
+      }
+    });
+  }
+  return refs;
+}

package/lib/soc.ts

@@ -0,0 +1,61 @@
+/**
+ * ESP32-C3 facts the ESP-IDF provider needs, checked against ESP-IDF v5.3.5
+ * (components/esp_system/Kconfig ESP_CONSOLE_*, components/esp_hw_support/
+ * port/esp32c3/Kconfig.rtc RTC_CLK_SRC_*, components/esptool_py/
+ * Kconfig.projbuild ESPTOOLPY_FLASHSIZE_*). The provider's own table: a part
+ * is matched by its stated SoC fact (`domains[electrical].metadata.soc`).
+ */
+import type { InterfaceDef, ModuleDef } from "@deltarobotics/uhd";
+
+export const IDF_VERSION = "5.3.5";
+
+export interface IdfSoc {
+  /** CONFIG_IDF_TARGET. */
+  target: string;
+  match: RegExp;
+  /** Controller numbers per peripheral. */
+  i2c: number[];
+  spi: number[];
+  uart: number[];
+  /** SPI2 master clock limit (Hz). */
+  spiMaxHz: number;
+  /** ESPTOOLPY_FLASHSIZE_<n>MB choices. */
+  flashSizes: number[];
+}
+
+// One I2C controller, SPI2 as the only general-purpose SPI host, UART0 and UART1
+// (the module's peripheral list: "2 x UART", "SPI2 (master 80 MHz …)", "I2C").
+export const ESP32C3: IdfSoc = {
+  target: "esp32c3",
+  match: /ESP32-C3/i,
+  i2c: [0],
+  spi: [2],
+  uart: [1, 0],
+  spiMaxHz: 80_000_000,
+  flashSizes: [1, 2, 4, 8, 16, 32, 64, 128],
+};
+
+const SOCS = [ESP32C3];
+
+export function socFact(def: ModuleDef): string | undefined {
+  for (const d of def.domains ?? []) {
+    const soc = (d as { metadata?: Record<string, unknown> }).metadata?.soc;
+    if (typeof soc === "string") return soc;
+  }
+  return undefined;
+}
+
+export function socOf(def: ModuleDef): IdfSoc | undefined {
+  const fact = socFact(def);
+  return fact ? SOCS.find((s) => s.match.test(fact)) : undefined;
+}
+
+/** The GPIO number a module pin carries (its `gpio<n>` capability). */
+export function gpioNumber(leaf: InterfaceDef | undefined): number | undefined {
+  const c = (leaf?.capabilities ?? []).find((x) => /^gpio\d+$/.test(x));
+  return c ? Number(c.slice(4)) : undefined;
+}
+
+export function leafForGpio(def: ModuleDef, n: number): InterfaceDef | undefined {
+  return def.interfaces.find((i) => gpioNumber(i) === n);
+}

package/ops/firmware.ts

@@ -0,0 +1,26 @@
+/**
+ * The firmware capability for ESP-IDF on ESP32-C3 modules: the shared
+ * operations from @protoboardai/core with this provider's design, pin reader
+ * and wake rule (Deep-sleep wake only from RTC GPIOs).
+ */
+import type { CapabilityOperationFn } from "@protoboardai/core";
+import { firmwareOperations, type FirmwareProviderSpec } from "@protoboardai/core";
+import { designEspIdf } from "../lib/design.ts";
+import { readEspIdfPins } from "../lib/pins.ts";
+import { IDF_VERSION } from "../lib/soc.ts";
+
+export const SPEC: FirmwareProviderSpec = {
+  provider: "@protoboardai/ext-esp-idf",
+  framework: "esp-idf",
+  frameworkVersion: IDF_VERSION,
+  design: designEspIdf,
+  readPins: readEspIdfPins,
+  // only RTC IO (GPIO0-5 on the ESP32-C3) wake it from Deep-sleep: the part marks them deep_sleep_wakeup
+  rules: () => ({ sleepName: "Deep-sleep", canWake: (leaf) => (leaf.capabilities ?? []).includes("deep_sleep_wakeup") }),
+};
+
+const ops = firmwareOperations(SPEC);
+export const generate: CapabilityOperationFn = ops.generate;
+export const exportOutputs: CapabilityOperationFn = ops.exportOutputs;
+export const extract: CapabilityOperationFn = ops.extract;
+export const check: CapabilityOperationFn = ops.check;

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@protoboardai/ext-esp-idf",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "Protoboard extension: ESP-IDF firmware configuration for ESP32-C3 boards.",
+  "license": "Apache-2.0",
+  "author": "Delta Robotics, Inc.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Delta-Robotics-Inc/protoboard-stack.git",
+    "directory": "packages/ext-esp-idf"
+  },
+  "type": "module",
+  "files": [
+    "protoboard-extension.json",
+    "ops",
+    "lib",
+    "skills",
+    "evals",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@protoboardai/core": "^0.2.0",
+    "@deltarobotics/uhd": ">=0.3.0"
+  },
+  "keywords": [
+    "protoboard",
+    "hardware",
+    "firmware",
+    "esp32",
+    "esp-idf"
+  ],
+  "homepage": "https://protoboard.ai",
+  "bugs": {
+    "url": "https://github.com/Delta-Robotics-Inc/protoboard-stack/issues"
+  }
+}

package/protoboard-extension.json

@@ -0,0 +1,59 @@
+{
+  "schema": "protoboard.extension/v0",
+  "id": "@protoboardai/ext-esp-idf",
+  "version": "0.2.1",
+  "description": "firmware provider: ESP-IDF pin and peripheral header and sdkconfig.defaults for ESP32-C3 modules, every setting citing the UHD facts it comes from.",
+  "compatibility": {
+    "protoboard": "^0.2.0",
+    "uhd": ">=0.3.0"
+  },
+  "skills": [
+    {
+      "id": "firmware-config-esp-idf",
+      "summary": "SOP: configure ESP-IDF for a UHD board with an ESP32-C3 module (firmware capability): config, generate, check, export, hand-off; strapping pins and Deep-sleep wake checked",
+      "path": "skills/firmware-config-esp-idf/SKILL.md"
+    }
+  ],
+  "capabilities": [
+    {
+      "id": "firmware",
+      "summary": "ESP-IDF 5.3 board_pins.h (buses, addresses, buttons, controls, wake mask) and sdkconfig.defaults (target, flash, console, RTC clock) for an ESP32-C3 board",
+      "native": "esp-idf",
+      "operations": {
+        "generate": {
+          "entry": "./ops/firmware.ts#generate",
+          "summary": "Read the board into a firmware map, apply the rules, write board_pins.h and sdkconfig.defaults under esp-idf/ with the line index"
+        },
+        "export": {
+          "entry": "./ops/firmware.ts#exportOutputs",
+          "summary": "Copy the generated files to out/config/ and write out/firmware.manifest.json (refuses files edited since generate)"
+        },
+        "extract": {
+          "entry": "./ops/firmware.ts#extract",
+          "summary": "Artifact references and the GPIOs the header names"
+        },
+        "check": {
+          "entry": "./ops/firmware.ts#check",
+          "summary": "Pin table, single use, bus functions, I2C addresses, strapping pins, Deep-sleep wake sources, controller counts, and drift between the files and the board"
+        }
+      },
+      "constraints": {
+        "controller": {
+          "description": "instance path of the controller, when the board has more than one microcontroller"
+        },
+        "console": {
+          "description": "usb (USB Serial/JTAG; default when GPIO18/19 are wired) or uart0"
+        },
+        "i2c_frequency_hz": {
+          "description": "I2C bus clock (default: the slowest device's limit, 400 kHz at most)"
+        },
+        "uart_baud": {
+          "description": "{ <instance>: baud } for UART devices that state no baud_rate"
+        },
+        "wake": {
+          "description": "[<button or device instance | net>] inputs that wake the chip from Deep-sleep; each must be on an RTC GPIO (GPIO0-5)"
+        }
+      }
+    }
+  ]
+}

package/skills/firmware-config-esp-idf/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: firmware-config-esp-idf
+description: Configure ESP-IDF for a UHD board whose controller is an ESP32-C3 module, with the @protoboardai/ext-esp-idf firmware provider. Writes board_pins.h and sdkconfig.defaults from the board's nets and part facts, every setting citing its facts, and fixes what firmware:check finds (strapping pins, Deep-sleep wake sources, pins, buses, addresses, drift). Use after the board's circuit is modelled, whenever its nets change, and before the release's firmware configuration is frozen.
+---
+
+# Firmware configuration: ESP-IDF (ESP32-C3)
+
+Standard operating procedure (release-package-and-evals.md §4). The
+configuration is a view of the model: which GPIO is SDA is a net, a sensor's
+address is a part fact, which pins are strapping pins is a fact of the
+module. Nothing is typed from memory or edited by hand. Reference: the
+package README.
+
+## Purpose
+
+Produce the ESP-IDF 5.3 pins header and sdkconfig defaults for one custom
+board, and the standard firmware outputs (`out/config/`,
+`out/firmware.manifest.json`) that the release packages. Use it when a board
+module's controller is an ESP32-C3 module (the part's SoC fact says
+ESP32-C3), after its nets are modelled, and again whenever they change.
+
+## Inputs
+
+- The board module: `src/boards/<module>/<module>.uhd.ts`, with every
+  peripheral pin the firmware drives or reads on a net that reaches a
+  controller pin. Peripherals with a bus state it as a composite with
+  `i2c_address` and `clock_freq`; a 1-Wire device's data pin carries
+  `onewire_dq`.
+- The parts, with pin tables: the module's `gpio<n>`, `strapping` and
+  `deep_sleep_wakeup` capabilities are what the rules read.
+- Which inputs wake the device from Deep-sleep, decided with the person who
+  owns the firmware.
+
+## Steps
+
+### 1. Write the config
+
+Next to the board:
+
+```ts
+// src/boards/<module>/firmware.config.ts
+import { defineCapabilityConfig } from "@protoboardai/core";
+export default defineCapabilityConfig({ provider: "@protoboardai/ext-esp-idf", constraints: { wake: ["sw2", "u4"] } });
+```
+
+Then `npx protoboard capabilities`: the board is listed under `firmware`
+with `✓`.
+
+### 2. Check before generating
+
+`npx protoboard check`. Read every
+`ext:@protoboardai/ext-esp-idf/firmware:check` finding. Errors stop
+generate; `FW_STRAPPING_BUTTON` (info) on GPIO9 is the BOOT button.
+
+### 3. Generate
+
+`npx protoboard run firmware:generate --module <module>`.
+Read the summary and its warnings (`--format json | jq .data`).
+
+### 4. Read `src/boards/<module>/esp-idf/board_pins.h`
+
+Each `#define`
+names its net and pin in a comment. Compare with the schematic intent:
+pins, addresses, active levels, pulls, the wake masks.
+
+### 5. Export
+
+`npx protoboard run firmware:export --module <module>`, then
+`npx protoboard check`: `protoboard/standard-outputs` and the provider's
+check clean.
+
+### 6. Hand off
+
+Where the header and defaults go (README), the warnings,
+and the bench items in "Verification".
+
+## Decision points
+
+| Question | Rule |
+| --- | --- |
+| Which GPIO for a new signal | Wake inputs on GPIO0-5 (RTC IO). No peripheral output on GPIO2, GPIO8 or GPIO9 (strapping). GPIO18/19 are USB Serial/JTAG; GPIO20/21 are the UART0 download port. Change the board's nets, never the header. |
+| Two I2C buses wanted | The ESP32-C3 has one I2C controller: put every device on one bus, or choose part variants with distinct addresses. |
+| Console | USB Serial/JTAG when GPIO18/19 reach a connector (the default); `console: "uart0"` when a USB-serial bridge is on GPIO20/21. |
+| No pull-up resistors on I2C or 1-Wire (warning) | Add them to the board (4.7 kOhm is common); the internal ~45 kOhm pull-ups are too weak at 400 kHz or on a cable. |
+| Something must differ from the generated files | Put it in the application's own code or a later `SDKCONFIG_DEFAULTS` file. Never edit `esp-idf/`. |
+
+## Outputs
+
+- `src/boards/<module>/esp-idf/`: `board_pins.h`, `sdkconfig.defaults`,
+  `protoboard.lines.json` (native, provider-owned).
+- `src/boards/<module>/out/config/` and `out/firmware.manifest.json`:
+  standard outputs, the only files the release and other tools read.
+- The operation records in `operations/` (commit them with the outputs).
+
+## Verification
+
+- `npx protoboard check`: no error from `protoboard/standard-outputs` or the
+  firmware check; no `FW_NATIVE_STALE`.
+- `out/firmware.manifest.json`: every file listed, each setting line with at
+  least one cite.
+- First build: `idf.py set-target esp32c3 && idf.py build` with the header
+  included and the defaults listed. A compile error from the header is a
+  provider defect: record it with the ESP-IDF version.
+- On the bench (the release's test plan): BOOT held at reset enters download
+  mode; an I2C scan finds the header's addresses; the 1-Wire search finds the
+  probe; each wake source wakes the chip from Deep-sleep; the console appears
+  on USB. Record results with **test-and-measure**.
+
+## Failure handling
+
+| Diagnostic | Meaning | Action |
+| --- | --- | --- |
+| `FW_STRAPPING_DRIVEN` | A peripheral output (interrupt, a device's TX) on GPIO2/8/9 can select the wrong boot mode | Move it to another GPIO. |
+| `FW_STRAPPING_PIN` (warning) | A bus line or controller output on a strapping pin | Check the level it holds at reset against the module's strapping table; move it if in doubt. |
+| `FW_WAKE_INVALID` | A wake source on GPIO6 or above | Move it to GPIO0-5, or drop it from `wake`. |
+| `FW_WAKE_UNKNOWN` | A wake source that is no input of the board | Name a button, or a device whose interrupt reaches the controller. |
+| `FW_PIN_NOT_GPIO` | A signal on an NC, EN or supply pin | Fix the net. |
+| `FW_BUS_INSTANCES` | A second I2C bus, or a UART too many | Share the bus; move the console to USB. |
+| `FW_PIN_REUSED`, `FW_BUS_CROSSED`, `FW_BUS_INCOMPLETE` | One pin with two jobs; swapped or missing bus lines | Fix the nets. |
+| `FW_I2C_ADDRESS_CONFLICT` | Two devices at one address | Another part variant or address strap. |
+| `FW_NATIVE_EDITED` | Someone edited `esp-idf/` | Regenerate; move the change to the application. |
+| `FW_NATIVE_STALE`, `FW_PIN_DRIFT` | The board changed since generate | Regenerate and export. |
+| `FW_PIN_UNKNOWN` | The header names a GPIO the module does not have (GPIO11-17 are not on its pins; GPIO12-17 drive the in-package flash) | Regenerate; if it persists, it is a provider defect. |
+| `FW_LINE_UNCITED` | Provider defect | Report it with the board. |