traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/tools/firmware_tools.py

@@ -0,0 +1,218 @@
+"""Firmware tools: pin map from the netlist, scaffolds, driver snippets, build and flash."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from traceforge.firmware.drivers import generate_driver, supported_parts
+from traceforge.firmware.netlist import NetlistError, load_netlist
+from traceforge.firmware.pinmap import HEADER_FILES, PinMap, build_pinmap, render_header
+from traceforge.firmware.scaffold import TARGETS, ScaffoldError, scaffold
+from traceforge.firmware.toolchain import (
+    INSTALL_GUIDANCE,
+    compile_project,
+    detect_tools,
+    flash_command,
+    flash_project,
+    size_project,
+)
+from traceforge.tools.base import Tool, ToolContext, ToolError, ToolKind
+from traceforge.tools.kicad_tools import _schematic_path
+
+
+def _design(args: dict[str, Any], ctx: ToolContext) -> Path:
+    if args.get("design"):
+        return ctx.resolve(args["design"], must_exist=True)
+    return _schematic_path(args, ctx)
+
+
+def _pinmap(args: dict[str, Any], ctx: ToolContext) -> tuple[PinMap, Path]:
+    design = _design(args, ctx)
+    try:
+        return build_pinmap(load_netlist(design), args.get("ref"), args.get("mcu")), design
+    except NetlistError as exc:
+        raise ToolError(str(exc)) from exc
+
+
+def firmware_pins(args: dict[str, Any], ctx: ToolContext) -> dict:
+    pm, design = _pinmap(args, ctx)
+    result = pm.as_dict()
+    style = args.get("style")
+    if style:
+        if style not in HEADER_FILES:
+            raise ToolError(f"style must be one of {', '.join(HEADER_FILES)}")
+        result["header"] = render_header(pm, style, ctx.display(design))
+    return result
+
+
+def firmware_scaffold(args: dict[str, Any], ctx: ToolContext) -> dict:
+    pm, design = _pinmap(args, ctx)
+    out = ctx.resolve(args.get("out") or "firmware", for_write=True)
+    try:
+        files = scaffold(
+            pm, out, args.get("target"), args.get("name"), args.get("drivers") or [],
+            ctx.display(design), bool(args.get("overwrite")),
+        )  # fmt: skip
+    except (ScaffoldError, KeyError) as exc:
+        raise ToolError(str(exc)) from exc
+    return {"written": [ctx.display(f) for f in files], "warnings": pm.warnings}
+
+
+def firmware_driver(args: dict[str, Any], ctx: ToolContext) -> dict:
+    if not args.get("part"):
+        return {"parts": supported_parts()}
+    try:
+        files = generate_driver(args["part"], args.get("address"))
+    except KeyError as exc:
+        raise ToolError(exc.args[0]) from exc
+    if args.get("out"):
+        out = ctx.resolve(args["out"], for_write=True)
+        out.mkdir(parents=True, exist_ok=True)
+        for name, text in files.items():
+            (out / name).write_text(text, encoding="utf-8")
+        return {"written": [ctx.display(out / n) for n in files]}
+    return {"files": files}
+
+
+def firmware_toolchain(args: dict[str, Any], ctx: ToolContext) -> dict:
+    return {
+        "tools": [
+            {"name": t.name, "found": t.found, "path": t.path, "version": t.version,
+             "install": t.guidance}
+            for t in detect_tools()
+        ]
+    }  # fmt: skip
+
+
+def firmware_build(args: dict[str, Any], ctx: ToolContext) -> dict:
+    project = ctx.resolve(args.get("project") or ".", must_exist=True)
+    action = args.get("action", "compile")
+    timeout = float(args.get("timeout", 1800))
+    try:
+        if action == "size":
+            result = size_project(project, timeout)
+        elif action == "compile":
+            result = compile_project(project, timeout)
+        else:
+            raise ToolError("action must be compile or size")
+    except ValueError as exc:
+        raise ToolError(str(exc)) from exc
+    data = result.as_dict()
+    data["output_tail"] = result.output[-3000:]
+    if result.returncode == 127:
+        data["install"] = INSTALL_GUIDANCE.get(result.tool, "")
+    return data
+
+
+def firmware_flash(args: dict[str, Any], ctx: ToolContext) -> dict:
+    """Runs only because the tool is SHELL kind: the host asks the user before it executes."""
+    project = ctx.resolve(args.get("project") or ".", must_exist=True)
+    try:
+        if args.get("dry_run", False):
+            return {"command": flash_command(project, args.get("port"))}
+        result = flash_project(project, args.get("port"), approved=True)
+    except ValueError as exc:
+        raise ToolError(str(exc)) from exc
+    data = result.as_dict()
+    data["output_tail"] = result.output[-2000:]
+    return data
+
+
+_DESIGN = {
+    "design": {"type": "string", "description": "design spec (.yaml), .kicad_sch or .net"},
+    "schematic": {"type": "string", "description": "schematic when 'design' is not given"},
+    "ref": {"type": "string", "description": "MCU reference, e.g. U1 (auto-detected)"},
+    "mcu": {"type": "string", "description": "attiny85 | esp32s3 | stm32f103 (auto-detected)"},
+}
+
+FIRMWARE_TOOLS = [
+    Tool(
+        "firmware_pins",
+        "Pin map from the netlist: every non-power net on the MCU mapped to its pin, GPIO "
+        "number and peripheral (UART/SPI/I2C/PWM/ADC) using the datasheet pin table; "
+        "warns on strapping/reserved pins and functions the pin cannot do. With 'style' "
+        "(c | cpp | rust) also returns the pins.h / pins.hpp / board_pins.rs text.",
+        {"type": "object", "properties": {**_DESIGN, "style": {"type": "string"}}},
+        firmware_pins,
+        ToolKind.READ,
+    ),
+    Tool(
+        "firmware_scaffold",
+        "Write a firmware project for the design: target arduino | platformio | esp-idf | "
+        "stm32 | avr, with the generated pin header, a small main, and optional drivers "
+        "(see firmware_driver).",
+        {
+            "type": "object",
+            "properties": {
+                **_DESIGN,
+                "target": {"type": "string", "enum": list(TARGETS)},
+                "out": {"type": "string", "description": "output folder (default firmware)"},
+                "name": {"type": "string"},
+                "drivers": {"type": "array", "items": {"type": "string"}},
+                "overwrite": {"type": "boolean"},
+            },
+        },
+        firmware_scaffold,
+        ToolKind.WRITE,
+        target_arg="out",
+    ),
+    Tool(
+        "firmware_driver",
+        "Generate init/read driver C code for an I2C/SPI/single-wire part from its register "
+        "table (BME280, SHT31, MCP23017, PCF85063A, DHT11, LM75, SSD1306). Without 'part' "
+        "lists the parts. Returns the text, or writes it to 'out'.",
+        {
+            "type": "object",
+            "properties": {
+                "part": {"type": "string"},
+                "address": {"type": "integer", "description": "7-bit address override"},
+                "out": {"type": "string"},
+            },
+        },
+        firmware_driver,
+        ToolKind.WRITE,
+        target_arg="out",
+    ),
+    Tool(
+        "firmware_toolchain",
+        "Which firmware tools are installed (arduino-cli, platformio, idf.py, avr-gcc, "
+        "arm-none-eabi-gcc), their versions, and install guidance for the missing ones.",
+        {"type": "object", "properties": {}},
+        firmware_toolchain,
+        ToolKind.READ,
+    ),
+    Tool(
+        "firmware_build",
+        "Compile (action compile) or report memory use (action size) of a firmware project "
+        "made by firmware_scaffold, with the real toolchain; returns parsed errors and "
+        "flash/RAM use.",
+        {
+            "type": "object",
+            "properties": {
+                "project": {"type": "string"},
+                "action": {"type": "string", "enum": ["compile", "size"]},
+                "timeout": {"type": "number"},
+            },
+        },
+        firmware_build,
+        ToolKind.SHELL,
+        target_arg="project",
+    ),
+    Tool(
+        "firmware_flash",
+        "Flash the board from a firmware project (asks the user first). With dry_run only "
+        "returns the command.",
+        {
+            "type": "object",
+            "properties": {
+                "project": {"type": "string"},
+                "port": {"type": "string", "description": "serial port, e.g. /dev/ttyUSB0"},
+                "dry_run": {"type": "boolean"},
+            },
+        },
+        firmware_flash,
+        ToolKind.SHELL,
+        target_arg="project",
+    ),
+]