Barmaja-PyArduino 2.0.0__py3-none-any.whl

Barmaja_PyArduino/pack_builder.py

@@ -0,0 +1,544 @@
+"""Turn an Arduino library (ZIP or folder) into a BARMAJA device pack.
+
+Used by the Library Adder window (library_adder.py), the ``add-library`` command
+and tools/new_device_pack.py.  It only READS the library's files; nothing from the
+library is executed on the PC.
+"""
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import tempfile
+import zipfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+CPP_TYPES = {
+    "void": "Void", "bool": "Bool", "boolean": "Bool",
+    "float": "Float", "double": "Float",
+    "int": "Int", "long": "Int", "short": "Int", "char": "Int", "byte": "Int", "word": "Int",
+    "uint8_t": "Int", "int8_t": "Int", "uint16_t": "Int", "int16_t": "Int",
+    "uint32_t": "Int", "int32_t": "Int", "size_t": "Int", "unsigned": "Int", "signed": "Int",
+}
+ADAPTER_CTYPE = {"Int": "long", "Float": "float", "Bool": "bool", "Void": "void"}
+PIN_WORDS = ("pin", "dout", "sck", "clk", "sda", "scl", "rx", "tx", "trig", "echo", "rst", "din", "latch")
+PIN_EXACT = {"cs", "ss", "dc", "rs", "rw", "en", "enable", "data", "clock", "miso", "mosi", "reset"}
+
+
+def _looks_like_pin(name: str) -> bool:
+    n = name.lower()
+    return any(w in n for w in PIN_WORDS) or n in PIN_EXACT or bool(re.fullmatch(r"d[0-7]", n))
+
+
+@dataclass
+class Param:
+    name: str
+    type: str
+    ctype: str
+    default: float | int | None = None
+    is_pin: bool = False
+
+
+@dataclass
+class Method:
+    cpp_name: str
+    student_name: str
+    params: list[Param]
+    returns: str
+    selected: bool = True
+
+
+@dataclass
+class ClassScan:
+    name: str
+    header: str
+    constructors: list[list[Param]] = field(default_factory=list)
+    methods: list[Method] = field(default_factory=list)
+    skipped: list[str] = field(default_factory=list)
+    printable: bool = False     # derives from Print/Stream/Adafruit_GFX -> offer print()/println()
+    bases: list[str] = field(default_factory=list)
+    abstract: bool = False
+    unusable: str = ""          # why students cannot get this class automatically
+
+
+@dataclass
+class LibraryScan:
+    root: Path
+    folder_name: str
+    name: str
+    version: str
+    license: str
+    license_warning: str
+    url: str
+    classes: dict[str, ClassScan]
+    problems: list[str]
+    depends: list[str] = field(default_factory=list)   # other Arduino libraries this one needs (library.properties)
+
+
+# ---------------- opening ----------------
+def open_library(path: str | Path) -> Path:
+    """Return the folder that holds the library (extracting a ZIP to a temp folder)."""
+    p = Path(path)
+    if p.is_file() and p.suffix.lower() == ".zip":
+        dest = Path(tempfile.mkdtemp(prefix="barmaja_lib_"))
+        with zipfile.ZipFile(p) as z:
+            for info in z.infolist():
+                target = (dest / info.filename).resolve()
+                if not str(target).startswith(str(dest.resolve())):
+                    raise ValueError("Unsafe path inside ZIP; refused.")
+            z.extractall(dest)
+        p = dest
+    if not p.is_dir():
+        raise FileNotFoundError(f"Not a ZIP file or folder: {path}")
+    if (p / "library.properties").is_file():
+        return p
+    candidates = sorted(x.parent for x in p.rglob("library.properties") if ".git" not in x.parts)
+    if candidates:
+        return min(candidates, key=lambda c: len(c.parts))
+    headers = [h for h in p.rglob("*.h") if "examples" not in h.parts]
+    if headers:
+        return min({h.parent for h in headers}, key=lambda c: len(c.parts))
+    raise FileNotFoundError("No Arduino library (library.properties or .h files) found.")
+
+
+def guess_license(root: Path) -> tuple[str, str]:
+    text = ""
+    for name in ("LICENSE", "LICENSE.txt", "LICENSE.md", "license.txt", "COPYING", "COPYING.txt", "COPYING.LESSER", "README.md", "README.adoc"):
+        f = root / name
+        if f.is_file():
+            text += f.read_text(encoding="utf-8", errors="replace")[:6000] + "\n"
+    for h in list(root.glob("*.h"))[:2] + list((root / "src").glob("*.h"))[:2]:
+        text += h.read_text(encoding="utf-8", errors="replace")[:3000]
+    t = text.lower()
+    if "lesser general public" in t or "lgpl" in t:
+        return "LGPL", "LGPL: allowed, but the installer must include the licence and the library source."
+    if "gnu general public" in t or re.search(r"\bgpl", t):
+        return "GPL", "GPL: check with BARMAJA before distributing - may require releasing combined source."
+    if "mit license" in t or "permission is hereby granted, free of charge" in t:
+        return "MIT", ""
+    if "apache license" in t:
+        return "Apache-2.0", ""
+    if "bsd" in t or "redistribution and use in source and binary forms" in t:
+        return "BSD", ""
+    return "UNKNOWN", "Licence not found: check the library's website before distributing."
+
+
+# ---------------- C++ header scanning ----------------
+_ARCH_TRUE = {"avr": {"ARDUINO_ARCH_AVR", "__AVR__", "AVR", "__AVR_ATmega328P__", "ARDUINO_AVR_UNO", "ARDUINO_AVR_NANO", "ARDUINO"}}
+_ARCH_FALSE = {"ARDUINO_ARCH_ESP32", "ESP32", "ESP_PLATFORM", "ESP8266", "ARDUINO_ARCH_ESP8266", "ARDUINO_ARCH_SAMD", "ARDUINO_ARCH_SAM",
+               "ARDUINO_ARCH_STM32", "STM32", "ARDUINO_ARCH_RP2040", "ARDUINO_ARCH_MBED", "ARDUINO_ARCH_RENESAS", "ARDUINO_ARCH_NRF52",
+               "ARDUINO_ARCH_MEGAAVR", "__arm__", "__ARM_ARCH", "CORE_TEENSY", "TEENSYDUINO", "PARTICLE", "SPARK", "__IMXRT1062__",
+               "ARDUINO_ARCH_ARC32", "__SAM3X8E__", "__MK20DX256__", "ARDUINO_ARCH_STM32F1", "ARDUINO_ARCH_STM32F4", "__PIC32MX__"}
+_NUMERIC = {"ARDUINO": 10819}
+
+
+def _eval_condition(expr: str, arch: str) -> bool | None:
+    """Evaluate a #if expression for the target board; None when unknown."""
+    true = _ARCH_TRUE.get(arch, set())
+    unknown = False
+    def defined(m):
+        nonlocal unknown
+        name = m.group(1)
+        if name in true: return " True "
+        if name in _ARCH_FALSE: return " False "
+        unknown = True
+        return " False "
+    e = re.sub(r"defined\s*\(\s*(\w+)\s*\)", defined, expr)
+    e = re.sub(r"defined\s+(\w+)", defined, e)
+    def ident(m):
+        nonlocal unknown
+        name = m.group(0)
+        if name in ("True", "False"): return name
+        if name in _NUMERIC: return str(_NUMERIC[name])
+        if name in true: return "1"
+        if name in _ARCH_FALSE: return "0"
+        unknown = True
+        return "0"
+    e = re.sub(r"\b[A-Za-z_]\w*\b", ident, e)
+    if unknown:
+        return None
+    e = e.replace("&&", " and ").replace("||", " or ").replace("!=", " __NE__ ").replace("!", " not ").replace(" __NE__ ", "!=")
+    e = re.sub(r"(\d+)[uUlL]+", r"\1", e)
+    try:
+        return bool(eval(e, {"__builtins__": {}}, {}))   # only numbers/booleans/operators remain
+    except Exception:
+        return None
+
+
+def _preprocess(text: str, arch: str = "avr") -> str:
+    """Keep only the #if branches that apply to the target board (unknown conditions keep all branches)."""
+    out: list[str] = []
+    stack: list[list] = []   # [parent_active, taken(bool|None), active]
+    active = True
+    for line in text.splitlines():
+        s = line.strip()
+        m = re.match(r"#\s*(if|ifdef|ifndef|elif|else|endif)\b(.*)", s)
+        if not m:
+            if active:
+                out.append(line)
+            continue
+        kind, rest = m.group(1), m.group(2).strip()
+        if kind in ("if", "ifdef", "ifndef"):
+            cond = (_eval_condition(rest, arch) if kind == "if" else
+                    _eval_condition(f"defined({rest.split()[0]})" if rest else "", arch))
+            if kind == "ifndef" and cond is not None:
+                cond = not cond
+            stack.append([active, cond if cond is not None else None, None])
+            stack[-1][2] = active and (cond is None or cond)
+            active = stack[-1][2]
+        elif kind == "elif" and stack:
+            parent, taken, _ = stack[-1]
+            cond = _eval_condition(rest, arch)
+            if taken is True:
+                now = False
+            else:
+                now = parent and (cond is None or cond)
+                if cond is True: stack[-1][1] = True
+            stack[-1][2] = now; active = now
+        elif kind == "else" and stack:
+            parent, taken, _ = stack[-1]
+            now = parent and taken is not True
+            stack[-1][2] = now; active = now
+        elif kind == "endif" and stack:
+            active = stack.pop()[0]
+    return "\n".join(out)
+
+
+def _strip_comments(text: str) -> str:
+    text = re.sub(r"/\*.*?\*/", "", text, flags=re.S)
+    return re.sub(r"//[^\n]*", "", text)
+
+
+def _class_bodies(text: str):
+    for m in re.finditer(r"\bclass\s+(\w+)\s*(?:final\s*)?(:\s*[^{;]+)?\{", text):
+        if re.search(r"template\s*<[^>]*>\s*$", text[max(0, m.start() - 120):m.start()]):
+            continue
+        depth, i = 1, m.end()
+        while i < len(text) and depth:
+            depth += {"{": 1, "}": -1}.get(text[i], 0)
+            i += 1
+        yield m.group(1), (m.group(2) or ""), text[m.end(): i - 1]
+
+
+def _public(body: str) -> str:
+    out, public, depth = [], False, 0
+    # put every access specifier on its own line ("{ public: void a(); private: int b; }")
+    body = re.sub(r"\b(public|private|protected)\s*:(?!:)", r"\n\1:\n", body)
+    for line in body.splitlines():
+        s = line.strip()
+        if depth == 0:
+            if re.match(r"^public\s*:$", s):
+                public = True; continue
+            if re.match(r"^(private|protected)\s*:$", s):
+                public = False; continue
+        if public and depth == 0:
+            out.append(line)
+        depth += line.count("{") - line.count("}")
+        depth = max(depth, 0)
+    return "\n".join(out)
+
+
+def _norm_type(ctype: str) -> str | None:
+    if "&" in ctype and "const" not in ctype.split():
+        return None          # output (reference) parameter: cannot come from Python
+    t = ctype.replace("&", " ").strip()
+    if "*" in t or "[" in t or "<" in t or "::" in t:
+        return None
+    words = [w for w in t.split() if w not in ("const", "volatile", "inline", "static", "virtual", "explicit", "constexpr")]
+    if not words:
+        return None
+    if words[0] == "unsigned" or words[0] == "signed":
+        return "Int"
+    return CPP_TYPES.get(words[-1])
+
+
+def _num(text: str):
+    text = text.strip().rstrip("fFuUlL")
+    try:
+        return float(text) if re.search(r"[.eE]", text) and not text.lower().startswith("0x") else int(text, 0)
+    except ValueError:
+        if text in ("true", "false"):
+            return 1 if text == "true" else 0
+        return None
+
+
+def _params(raw: str) -> tuple[list[Param] | None, str]:
+    raw = raw.strip()
+    if not raw or raw == "void":
+        return [], ""
+    out: list[Param] = []
+    parts, depth, cur = [], 0, ""
+    for ch in raw:
+        if ch in "(<": depth += 1
+        if ch in ")>": depth -= 1
+        if ch == "," and depth == 0:
+            parts.append(cur); cur = ""
+        else:
+            cur += ch
+    parts.append(cur)
+    for i, part in enumerate(x.strip() for x in parts):
+        default = None
+        has_default = "=" in part
+        if has_default:
+            part, d = part.split("=", 1)
+            default = _num(d)
+            if default is None:
+                # non-numeric default (macro/enum): stop here and let the library use its default
+                return out, f"later parameters use library defaults ({d.strip()})"
+        part = part.strip()
+        m = re.match(r"^(.*?)([A-Za-z_]\w*)$", part)
+        ctype, name = (m.group(1).strip(), m.group(2)) if m and m.group(1).strip() else (part, f"arg{i}")
+        ptype = _norm_type(ctype)
+        if ptype is None or ptype == "Void":
+            return None, f"parameter '{part}' type is not supported"
+        name = re.sub(r"_([a-z0-9])", lambda mm: mm.group(1).upper(), name.lstrip("_")) or f"arg{i}"
+        name = name.lower() if name.isupper() else name[0].lower() + name[1:]
+        is_pin = ptype == "Int" and _looks_like_pin(name)
+        out.append(Param(name, ptype, ctype, default, is_pin))
+    return out, ""
+
+
+def _camel(name: str) -> str:
+    s = re.sub(r"_([a-zA-Z0-9])", lambda m: m.group(1).upper(), name.strip("_"))
+    return (s[0].lower() + s[1:]) if s else s
+
+
+def scan_library(root: Path, arch: str = "avr") -> LibraryScan:
+    props_file = root / "library.properties"
+    props = props_file.read_text(encoding="utf-8", errors="replace") if props_file.is_file() else ""
+    def prop(key: str, default: str = "") -> str:
+        m = re.search(rf"^{key}=(.*)$", props, re.M)
+        return m.group(1).strip() if m else default
+    lic, warn = guess_license(root)
+    headers = sorted(h for h in list(root.glob("*.h")) + list((root / "src").rglob("*.h")) + list((root / "src").rglob("*.hpp"))
+                     if "examples" not in h.parts and "test" not in h.parts)
+    classes: dict[str, ClassScan] = {}
+    problems: list[str] = []
+    for h in headers:
+        text = _preprocess(_strip_comments(h.read_text(encoding="utf-8", errors="replace")), arch)
+        for cls, bases, body in _class_bodies(text):
+            if cls in classes or cls.startswith("_"):
+                continue
+            scan = ClassScan(cls, h.relative_to(root / "src" if (root / "src") in h.parents else root).as_posix())
+            scan.printable = bool(re.search(r"\b(Print|Stream|Adafruit_GFX)\b", bases))
+            scan.bases = re.findall(r"(?:public\s+)(\w+)", bases)
+            pub = _public(body)
+            scan.abstract = bool(re.search(r"\)\s*(?:const\s*)?=\s*0\s*;", body))
+            ctor_declared = False
+            seen: set[str] = set()
+            for m in re.finditer(r"(?:^|(?<=[;{}\n]))\s*(?:virtual\s+|static\s+|inline\s+|explicit\s+)*(?P<ret>[A-Za-z_][\w\s\*&:<>]*?\s+[\*&]?)?(?P<name>~?\w+)\s*\((?P<params>[^()]*(?:\([^()]*\)[^()]*)*)\)\s*(?:const\s*)?(?:override\s*)?(?:=\s*0\s*)?[;{]", pub):
+                name, ret = m.group("name"), (m.group("ret") or "").strip()
+                if name in ("if", "for", "while", "switch", "return", "operator"):
+                    continue
+                params, note = _params(m.group("params"))
+                if name == cls:
+                    ctor_declared = True
+                    if params is not None:
+                        cut = next((i for i, p in enumerate(params) if p.type != "Int"), None)
+                        if cut is not None:
+                            if params[cut].default is None:
+                                scan.skipped.append(f"constructor {cls}({m.group('params').strip()}): needs a {params[cut].type} argument")
+                                continue
+                            params = params[:cut]
+                        scan.constructors.append(params)
+                    else:
+                        scan.skipped.append(f"constructor {cls}({m.group('params').strip()}): {note}")
+                    continue
+                if name.startswith("~") or name.startswith("_") or "operator" in ret or not ret:
+                    continue
+                if "static" in m.group(0).split(name)[0]:
+                    scan.skipped.append(f"{name}(): static function"); continue
+                rtype = _norm_type(ret)
+                if rtype is None:
+                    scan.skipped.append(f"{name}(): returns '{ret}' (not a number/bool)"); continue
+                if params is None:
+                    scan.skipped.append(f"{name}(): {note}"); continue
+                student = _camel(name)
+                if name in ("write", "print", "println") and scan.printable:
+                    continue
+                if student in seen or not re.match(r"^[a-z][A-Za-z0-9]{0,30}$", student):
+                    scan.skipped.append(f"{name}(): overloaded or invalid name (kept the first version)"); continue
+                seen.add(student)
+                scan.methods.append(Method(name, student, params, rtype))
+            if not scan.constructors:
+                if ctor_declared:
+                    scan.unusable = "its constructor needs arrays/pointers/special types (needs a hand-written adapter)"
+                else:
+                    scan.constructors.append([])
+            if scan.abstract:
+                scan.unusable = "it is an abstract base class (use one of the classes built on it)"
+            classes[cls] = scan
+    # public base classes defined in the same library: inherit their methods / Print ability
+    def inherit(c: ClassScan, depth: int = 0) -> None:
+        for b in c.bases:
+            base = classes.get(b)
+            if base is None or depth > 5:
+                continue
+            inherit(base, depth + 1)
+            have = {m.student_name for m in c.methods}
+            c.methods += [Method(m.cpp_name, m.student_name, m.params, m.returns) for m in base.methods if m.student_name not in have]
+            c.printable = c.printable or base.printable
+    for c in classes.values():
+        inherit(c)
+    unusable = {k: v.unusable for k, v in classes.items() if v.unusable and (v.methods or v.printable)}
+    classes = {k: v for k, v in classes.items() if (v.methods or v.printable) and not v.unusable}
+    for k, why in unusable.items():
+        problems.append(f"Class {k} skipped: {why}.")
+    for c in classes.values():
+        if any(s.startswith(("begin(", "init(")) for s in c.skipped) and not any(m.cpp_name in ("begin", "init") for m in c.methods):
+            problems.append(f"Class {c.name}: begin()/init() could not be converted (pointer/array parameters). "
+                            "The device may need a hand-written adapter.")
+    if not classes:
+        problems.append("No usable C++ class found. Libraries that only provide functions or a ready-made global "
+                        "object (for example Wire, EEPROM, IrReceiver) need a hand-written adapter.")
+    lib_name = prop("name", root.name)
+    folder = re.sub(r"[^A-Za-z0-9_.-]+", "_", lib_name).strip("_") or "ArduinoLibrary"
+    depends = [re.sub(r"\s*\(.*\)\s*$", "", d).strip() for d in prop("depends").split(",") if d.strip()]
+    return LibraryScan(root, folder, lib_name, prop("version", "SET_VERSION"), lic, warn,
+                       prop("url"), classes, problems, depends)
+
+
+# ---------------- pack generation ----------------
+def main_class(lib: LibraryScan) -> str | None:
+    """Best guess of the class students need (name like the library, has begin(), most methods)."""
+    if not lib.classes:
+        return None
+    key = re.sub(r"[^a-z0-9]", "", lib.name.lower())
+    def score(item):
+        name, c = item
+        n = re.sub(r"[^a-z0-9]", "", name.lower())
+        return ((n in key or key in n) * 3 + any(m.cpp_name in ("begin", "init") for m in c.methods) * 2
+                + c.printable + min(len(c.methods), 30) / 30)
+    return max(lib.classes.items(), key=score)[0]
+
+
+def default_constructor(scan: ClassScan) -> int:
+    """Empty constructor when the class has begin(); else all-pin constructor; else shortest."""
+    ctors = scan.constructors
+    has_begin = any(m.cpp_name in ("begin", "init") for m in scan.methods)
+    if has_begin and [] in ctors:
+        return ctors.index([])      # I2C/bus devices: empty constructor + begin()
+    pins_only = [i for i, c in enumerate(ctors) if c and all(p.is_pin and p.default is None for p in c)]
+    if pins_only:
+        return min(pins_only, key=lambda i: len(ctors[i]))
+    empty = [i for i, c in enumerate(ctors) if not [p for p in c if p.default is None]]
+    if empty:
+        return empty[0]
+    return min(range(len(ctors)), key=lambda i: len(ctors[i]))
+
+
+def default_student_name(cls: str) -> str:
+    base = re.sub(r"[^A-Za-z0-9]", "", cls)
+    base = base[0].upper() + base[1:] if base else "Device"
+    if len(base) < 3:
+        base += "Device"
+    return base + "Module" if base == cls else base
+
+
+def build_pack(lib: LibraryScan, cls: str, student: str, ctor_index: int = 0, title: str | None = None,
+               status: str = "prototype", add_print: bool | None = None) -> tuple[dict, str, str]:
+    if ctor_index < 0:
+        ctor_index = default_constructor(lib.classes[cls])
+    """Return (pack.json dict, adapter header text, example.py text) for the selected methods."""
+    scan = lib.classes[cls]
+    if not re.match(r"^[A-Z][A-Za-z0-9]{2,40}$", student):
+        raise ValueError("Student class name must be CamelCase letters/digits, e.g. WeightSensor")
+    if student == cls:
+        raise ValueError(f"Student class name must differ from the library class '{cls}' (C++ name clash).")
+    ctor = scan.constructors[ctor_index] if scan.constructors else []
+    methods = [m for m in scan.methods if m.selected]
+    printable = scan.printable if add_print is None else add_print
+    lname = f"Barmaja_{student}"
+    hdr_name = Path(scan.header).name
+    def cparams(ps):
+        return ", ".join(f"{ADAPTER_CTYPE[p.type]} {p.name}" + (f" = {p.default}" if p.default is not None else "") for p in ps)
+    ctor_args = ", ".join(p.name for p in ctor)
+    lines = ["#pragma once", "#include <Arduino.h>", f"#include <{hdr_name}>", "",
+             f"// Generated by BARMAJA Library Adder from {lib.name} {lib.version}.",
+             f"class {student}{' : public Print' if printable else ''} {{", "public:",
+             f"  {'explicit ' if len(ctor) == 1 else ''}{student}({cparams(ctor)}){(' : dev_(' + ctor_args + ')') if ctor else ''} {{}}"]
+    for m in methods:
+        call = f"dev_.{m.cpp_name}({', '.join(p.name for p in m.params)})"
+        lines.append(f"  {ADAPTER_CTYPE[m.returns]} {m.student_name}({cparams(m.params)}) {{ {'return ' if m.returns != 'Void' else ''}{call}; }}")
+    if printable:
+        lines += ["  size_t write(uint8_t c) override { return dev_.write(c); }", "  using Print::print;", "  using Print::println;"]
+    lines += ["private:", f"  {cls} dev_;", "};", ""]
+    starter = next((m.student_name for m in methods if m.cpp_name in ("begin", "init", "setup")), None)
+    def pjson(p: Param) -> dict:
+        d = {"name": p.name, "type": p.type}
+        if p.is_pin: d["rule"] = "digital_pin"
+        if p.default is not None: d["default"] = p.default
+        return d
+    mjson = {}
+    for m in methods:
+        entry = {"params": [pjson(p) for p in m.params], "returns": m.returns}
+        if m.student_name == starter: entry["starts"] = True
+        elif starter is None: entry["requires_begin"] = False
+        mjson[m.student_name] = entry
+    if printable:
+        mjson["print"] = {"params": [{"name": "value", "type": "Scalar"}], "returns": "Void", **({} if starter else {"requires_begin": False})}
+        mjson["println"] = {"params": [{"name": "value", "type": "Scalar", "default": 0}], "returns": "Void", **({} if starter else {"requires_begin": False})}
+    dep_id = re.sub(r"[^a-z0-9]+", "-", lib.name.lower()).strip("-") or lib.folder_name.lower()
+    spec = {
+        "schema": 1, "class": student, "title": title or f"{lib.name} ({cls})", "status": status, "boards": ["uno", "nano"],
+        "constructor": [pjson(p) for p in ctor], "methods": mjson, "resources": [], "warnings": [],
+        "adapter": {"library": lname, "header": f"{lname}.h"},
+        "dependencies": [{"id": dep_id, "name": lib.name, "version": lib.version, "header": hdr_name,
+                          "license": lib.license, "library_folder": lib.folder_name, **({"source": lib.url} if lib.url else {})}],
+        "liverun": False,
+    }
+    notes = []
+    if lib.depends:
+        notes.append("Also needs Arduino libraries: " + ", ".join(lib.depends))
+    if scan.skipped:
+        notes.append("Not converted: " + "; ".join(scan.skipped[:25]))
+    if notes:
+        spec["notes"] = " | ".join(notes)
+    # example program
+    def sample(ps):
+        vals, pin = [], 2
+        for p in ps:
+            if p.default is not None: break
+            if p.is_pin: vals.append(str(pin)); pin += 1
+            else: vals.append({"Float": "1.0", "Bool": "True"}.get(p.type, "1"))
+        return ", ".join(vals)
+    low = student.lower()
+    obj = ("screen" if any(w in low for w in ("display", "lcd", "oled", "screen", "matrix")) else
+           "motor" if any(w in low for w in ("motor", "servo", "stepper", "pwm")) else
+           "sensor" if any(w in low for w in ("sensor", "temp", "max", "bmp", "bme", "aht", "dht", "ina", "tcs", "apds", "mpu", "hx711", "vl53")) else
+           "device")
+    ex = ["from Barmaja_PyArduino import *", "upload()", "", f"{obj} = {student}({sample(ctor)})"]
+    if starter:
+        sm = next(m for m in methods if m.student_name == starter)
+        ex.append(f"{obj}.{starter}({sample(sm.params)})")
+    ex.append("while True:")
+    readers = [m for m in methods if not [p for p in m.params if p.default is None] and m.returns in ("Int", "Float", "Bool") and m.student_name != starter]
+    def useful(m):
+        n = m.student_name.lower()
+        return (("read" in n) * 4 + any(w in n for w in ("temp", "distance", "value", "unit", "weight", "pressure", "humid", "range", "position", "key", "lux", "current", "voltage")) * 3
+                + n.startswith("get") - any(w in n for w in ("status", "id", "error", "version", "address")) * 5 + (m.returns == "Float"))
+    reader = max(readers, key=useful) if readers else None
+    if reader:
+        ex.append(f"    print(\"{reader.student_name}:\", {obj}.{reader.student_name}())")
+    elif printable:
+        ex.append(f"    {obj}.print(\"Hello\")")
+    ex.append("    delay(500)")
+    spec["example"] = "\n".join(ex) + "\n"
+    return spec, "\n".join(lines), spec["example"]
+
+
+def write_pack(dest_root: Path, spec: dict, adapter: str) -> Path:
+    folder = Path(dest_root) / spec["class"]
+    lname = spec["adapter"]["library"]
+    if folder.exists():
+        shutil.rmtree(folder)
+    (folder / "arduino" / lname / "src").mkdir(parents=True)
+    (folder / "arduino" / lname / "src" / spec["adapter"]["header"]).write_text(adapter, encoding="utf-8")
+    (folder / "arduino" / lname / "library.properties").write_text(
+        f"name={lname}\nversion=1.0.0\nauthor=BARMAJA Library Adder\nmaintainer=BARMAJA\n"
+        f"sentence=BARMAJA adapter for {spec['dependencies'][0]['name'] if spec['dependencies'] else spec['class']}\n"
+        "paragraph=\ncategory=Device Control\nurl=\narchitectures=*\n", encoding="utf-8")
+    (folder / "pack.json").write_text(json.dumps(spec, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    (folder / "example.py").write_text(spec["example"], encoding="utf-8")
+    return folder