Barmaja-PyArduino 2.0.0__py3-none-any.whl

Barmaja_PyArduino/console.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import os
+import sys
+
+
+# ANSI control sequences are used only for real ANSI-capable terminals.
+# PictoBlox is intentionally excluded: its Python terminal/log owns rendering.
+_ANSI = {
+    "success": "\x1b[32m",  # green
+    "error": "\x1b[31m",    # red
+}
+_RESET = "\x1b[0m"
+
+
+def _percent(used, total):
+    if used is None or not total:
+        return None
+    return int((used * 100) // total)
+
+
+def compilation_summary_lines(memory, board_name="Arduino Uno"):
+    """Return stable, ASCII-only Arduino-IDE-inspired compilation output."""
+    lines = [f"{board_name} compilation succeeded."]
+
+    if memory.flash_used is not None and memory.flash_total:
+        pct = _percent(memory.flash_used, memory.flash_total)
+        lines.extend([
+            "",
+            f"Sketch uses {memory.flash_used} bytes ({pct}%) of program storage space.",
+            f"Maximum is {memory.flash_total} bytes.",
+        ])
+
+    if memory.sram_used is not None and memory.sram_total:
+        pct = _percent(memory.sram_used, memory.sram_total)
+        leaving = max(0, memory.sram_total - memory.sram_used)
+        lines.extend([
+            "",
+            f"Global variables use {memory.sram_used} bytes ({pct}%) of dynamic memory,",
+            f"leaving {leaving} bytes for local variables.",
+            f"Maximum is {memory.sram_total} bytes.",
+        ])
+
+    return tuple(lines)
+
+
+def _color_mode():
+    """Return always / never / auto for ANSI-capable consoles."""
+    if os.environ.get("NO_COLOR") is not None:
+        return "never"
+    raw = os.environ.get("BARMAJA_COLOR", "auto").strip().lower()
+    if raw in {"1", "true", "yes", "on", "always"}:
+        return "always"
+    if raw in {"0", "false", "no", "off", "never"}:
+        return "never"
+    return "auto"
+
+
+def _stream_tag(stream) -> str:
+    cls = type(stream)
+    return f"{getattr(cls, '__module__', '')}.{getattr(cls, '__name__', '')}".lower()
+
+
+def _looks_like_idle(stream) -> bool:
+    tag = _stream_tag(stream)
+    return "idlelib" in tag or "pseudooutputfile" in tag
+
+
+def _looks_like_pictoblox_host() -> bool:
+    executable = str(getattr(sys, "executable", "") or "").lower()
+    prefix = str(getattr(sys, "prefix", "") or "").lower()
+    base_prefix = str(getattr(sys, "base_prefix", "") or "").lower()
+    return "pictoblox" in executable or "pictoblox" in prefix or "pictoblox" in base_prefix
+
+
+def _known_ansi_host() -> bool:
+    env = os.environ
+
+    # PictoBlox is NOT an ANSI terminal. Real physical testing in 0.6.8 proved
+    # that ANSI color is not rendered there, so let PictoBlox own stderr/log
+    # styling instead of injecting escape sequences.
+    if _looks_like_pictoblox_host():
+        return False
+
+    if env.get("PYCHARM_HOSTED") == "1":
+        return True
+    if env.get("VSCODE_PID") or env.get("TERM_PROGRAM", "").lower() == "vscode":
+        return True
+    if env.get("WT_SESSION") or env.get("ANSICON"):
+        return True
+    if env.get("ConEmuANSI", "").upper() == "ON":
+        return True
+    term = env.get("TERM", "")
+    if term and term.lower() != "dumb":
+        return True
+    return False
+
+
+def _enable_windows_vt(stream) -> bool:
+    """Best-effort enable ANSI colors in a real Windows console."""
+    if os.name != "nt":
+        return True
+    try:
+        if not stream.isatty():
+            return True
+    except Exception:
+        return True
+
+    try:
+        import ctypes
+        import msvcrt
+
+        kernel32 = ctypes.windll.kernel32
+        handle = msvcrt.get_osfhandle(stream.fileno())
+        mode = ctypes.c_uint()
+        if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+            return False
+        ENABLE_VIRTUAL_TERMINAL_PROCESSING = 0x0004
+        if mode.value & ENABLE_VIRTUAL_TERMINAL_PROCESSING:
+            return True
+        return bool(kernel32.SetConsoleMode(handle, mode.value | ENABLE_VIRTUAL_TERMINAL_PROCESSING))
+    except Exception:
+        return False
+
+
+def supports_color(stream=None) -> bool:
+    """Whether ANSI color is safe for this output stream."""
+    stream = stream or sys.stdout
+    mode = _color_mode()
+
+    # Mandatory GUI hosts must never receive ANSI garbage in auto mode.
+    if mode == "auto" and (_looks_like_idle(stream) or _looks_like_pictoblox_host()):
+        return False
+
+    if mode == "never":
+        return False
+    if mode == "always":
+        return True
+
+    # Do not inject escape sequences into StringIO/captured logs.
+    cls = type(stream)
+    if getattr(cls, "__module__", "") == "_io" and getattr(cls, "__name__", "") == "StringIO":
+        return False
+
+    try:
+        tty = bool(stream.isatty())
+    except Exception:
+        tty = False
+
+    if tty:
+        return _enable_windows_vt(stream)
+    return _known_ansi_host()
+
+
+def style_text(text: str, style: str | None = None, *, stream=None) -> str:
+    """Apply ANSI color only where the host supports it."""
+    if not text or style not in _ANSI or not supports_color(stream):
+        return text
+    return f"{_ANSI[style]}{text}{_RESET}"
+
+
+def _safe_write(stream, text: str) -> None:
+    """Write without crashing on restrictive Windows console encodings."""
+    try:
+        stream.write(text)
+    except UnicodeEncodeError:
+        encoding = getattr(stream, "encoding", None) or "utf-8"
+        safe = text.encode(encoding, errors="replace").decode(encoding, errors="replace")
+        stream.write(safe)
+
+
+def _idle_native_write(stream, text: str, style: str | None) -> bool:
+    """Best-effort IDLE-native highlighting.
+
+    IDLE exposes a PseudoOutputFile whose ``shell.write`` accepts semantic tags.
+    Using native tags avoids ANSI escapes in IDLE. The exact colors follow the
+    user's IDLE theme.
+    """
+    if not _looks_like_idle(stream):
+        return False
+
+    shell = getattr(stream, "shell", None)
+    writer = getattr(shell, "write", None)
+    if not callable(writer):
+        return False
+
+    # IDLE's own stderr tag is its error color. STRING is green in the default
+    # IDLE themes and serves as a readable success highlight; custom themes may
+    # choose a different shade.
+    tag = "stderr" if style == "error" else "STRING" if style == "success" else getattr(stream, "tags", None)
+    if isinstance(tag, (tuple, list)):
+        tag = tag[0] if tag else None
+    if not isinstance(tag, str) or not tag:
+        tag = "stdout"
+
+    try:
+        writer(text, tag)
+        return True
+    except Exception:
+        return False
+
+
+def write_styled(stream, text: str, *, style: str | None = None, end: str = "\n") -> None:
+    """Write one student-facing message using the host's safest color mechanism.
+
+    - IDLE: native semantic tags (theme-controlled)
+    - PictoBlox: plain stdout/stderr; PictoBlox owns terminal/log rendering
+    - ANSI terminals / PyCharm / VS Code: ANSI green/red where supported
+    - Other hosts: plain text
+    """
+    payload = text + end
+
+    if _idle_native_write(stream, payload, style):
+        return
+
+    rendered = style_text(text, style, stream=stream) + end
+    _safe_write(stream, rendered)

Barmaja_PyArduino/device_packs.py

@@ -0,0 +1,367 @@
+"""BARMAJA device packs: add Arduino libraries/sensors WITHOUT editing the compiler.
+
+A device pack is a folder::
+
+    <PackName>/
+        pack.json                       declarative student API + rules (no code runs)
+        arduino/Barmaja_<Class>/        tiny Arduino adapter library
+            library.properties
+            src/Barmaja_<Class>.h
+
+Built-in packs live in ``Barmaja_PyArduino/device_packs/``.  Teachers/developers can
+add more without rebuilding the wheel by pointing ``BARMAJA_DEVICE_PACKS`` at one or
+more folders (os.pathsep separated) or by copying packs into
+``<BARMAJA runtime root>/device-packs``.  Third-party Arduino libraries named in
+``dependencies`` must exist in the offline library folder (see the payload builder).
+
+pack.json is JSON only (never executed), validated strictly; an invalid pack is
+skipped with a clear message and never breaks the core compiler.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+SCHEMA_VERSION = 1
+TYPES = {"Int", "Float", "Bool", "String", "Scalar", "Void"}
+RETURN_TYPES = {"Int", "Float", "Bool", "String", "Void"}
+PIN_RULES = {"digital_pin", "analog_pin", "pwm_pin", "none"}
+RESOURCES = {"i2c", "spi", "softserial", "timer1", "timer2", "interrupts"}
+STATUSES = {"prototype", "compile-verified", "hardware-verified"}
+_NAME = re.compile(r"^[A-Z][A-Za-z0-9]{2,40}$")
+_PARAM = re.compile(r"^[a-z][A-Za-z0-9_]{0,30}$")
+_METHOD = re.compile(r"^[a-z][A-Za-z0-9]{0,30}$")
+_BOUND = re.compile(r"^([a-z][A-Za-z0-9_]*)\s*([+-]\s*\d+)?$")
+_RESERVED_METHODS = {"__init__", "pins", "_only_upload", "_label"}
+
+
+class PackError(ValueError):
+    """pack.json does not follow the device-pack schema."""
+
+
+@dataclass(frozen=True)
+class PackParam:
+    name: str
+    types: tuple[str, ...]
+    rule: str = "none"
+    range: tuple[Any, Any] | None = None   # ints or "ctorparam[+-N]"
+    default: Any = None                     # optional trailing parameter (C++ adapter must use the same default)
+
+
+@dataclass(frozen=True)
+class PackMethod:
+    name: str
+    params: tuple[PackParam, ...]
+    returns: str
+    starts: bool = False
+    requires_begin: bool = True
+
+
+@dataclass
+class DevicePack:
+    class_name: str
+    title: str
+    status: str
+    folder: Path
+    constructor: tuple[PackParam, ...]
+    methods: dict[str, PackMethod]
+    resources: tuple[str, ...]
+    warnings: tuple[str, ...]
+    forbid_pins: tuple[int, ...]
+    distinct_pins: bool
+    adapter_library: str
+    adapter_header: str
+    dependencies: tuple[dict, ...]
+    boards: tuple[str, ...] = ("uno",)
+    liverun: bool = False
+    example: str = ""
+    source: str = "built-in"
+    errors: list[str] = field(default_factory=list)
+
+    @property
+    def adapter_dir(self) -> Path:
+        return self.folder / "arduino" / self.adapter_library
+
+
+def _types(value: Any, where: str, allowed: set[str]) -> tuple[str, ...]:
+    items = value if isinstance(value, list) else [value]
+    if not items or any(not isinstance(t, str) or t not in allowed for t in items):
+        raise PackError(f"{where}: type must be one of {sorted(allowed)} (or a list of them)")
+    return tuple(items)
+
+
+def _range(value: Any, where: str, ctor_names: set[str]) -> tuple[Any, Any] | None:
+    if value is None:
+        return None
+    if not (isinstance(value, list) and len(value) == 2):
+        raise PackError(f"{where}: range must be [low, high]")
+    out = []
+    for bound in value:
+        if isinstance(bound, bool) or not isinstance(bound, (int, str)):
+            raise PackError(f"{where}: range bounds must be integers or 'constructorParam-1'")
+        if isinstance(bound, str):
+            m = _BOUND.match(bound.strip())
+            if not m or m.group(1) not in ctor_names:
+                raise PackError(f"{where}: bound '{bound}' must name a constructor parameter, e.g. 'count-1'")
+        out.append(bound)
+    return (out[0], out[1])
+
+
+def _param(raw: Any, where: str, ctor_names: set[str], *, ctor: bool) -> PackParam:
+    if not isinstance(raw, dict):
+        raise PackError(f"{where}: each parameter must be an object")
+    name = raw.get("name")
+    if not isinstance(name, str) or not _PARAM.match(name):
+        raise PackError(f"{where}: parameter name must be lower_snake/camel, e.g. 'pin'")
+    types = _types(raw.get("type", "Int"), f"{where}.{name}", TYPES - {"Void"})
+    rule = raw.get("rule", "none")
+    if rule not in PIN_RULES:
+        raise PackError(f"{where}.{name}: rule must be one of {sorted(PIN_RULES)}")
+    if rule != "none" and types != ("Int",):
+        raise PackError(f"{where}.{name}: pin parameters must have type Int")
+    if ctor and types != ("Int",):
+        raise PackError(f"{where}.{name}: constructor parameters must be Int (compile-time numbers)")
+    default = raw.get("default")
+    if default is not None and (isinstance(default, bool) or not isinstance(default, (int, float))):
+        raise PackError(f"{where}.{name}: default must be a number")
+    return PackParam(name, types, rule, _range(raw.get("range"), f"{where}.{name}", ctor_names), default)
+
+
+def _check_defaults(params: tuple[PackParam, ...], where: str) -> None:
+    seen_default = False
+    for p in params:
+        if p.default is not None:
+            seen_default = True
+        elif seen_default:
+            raise PackError(f"{where}: parameters with a default must come last")
+
+
+def required_count(params: tuple[PackParam, ...]) -> int:
+    return sum(1 for p in params if p.default is None)
+
+
+def parse_pack(folder: Path, *, source: str = "built-in") -> DevicePack:
+    path = folder / "pack.json"
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        raise PackError(f"{folder.name}: pack.json missing") from None
+    except (OSError, json.JSONDecodeError) as exc:
+        raise PackError(f"{folder.name}: pack.json is not valid JSON ({exc})") from None
+    if not isinstance(raw, dict) or raw.get("schema") != SCHEMA_VERSION:
+        raise PackError(f"{folder.name}: 'schema' must be {SCHEMA_VERSION}")
+    allowed_keys = {"schema", "class", "title", "status", "boards", "constructor", "methods", "resources",
+                    "warnings", "pins", "adapter", "dependencies", "liverun", "example", "notes"}
+    unknown = set(raw) - allowed_keys
+    if unknown:
+        raise PackError(f"{folder.name}: unknown keys {sorted(unknown)}")
+    cls = raw.get("class")
+    if not isinstance(cls, str) or not _NAME.match(cls):
+        raise PackError(f"{folder.name}: 'class' must be a CamelCase name like 'TemperatureDS18B20'")
+    status = raw.get("status", "prototype")
+    if status not in STATUSES:
+        raise PackError(f"{cls}: status must be one of {sorted(STATUSES)}")
+    ctor_raw = raw.get("constructor", [])
+    if not isinstance(ctor_raw, list) or len(ctor_raw) > 10:
+        raise PackError(f"{cls}: constructor must be a list (max 10 parameters)")
+    ctor_names = {p.get("name") for p in ctor_raw if isinstance(p, dict)}
+    ctor = tuple(_param(p, f"{cls}.constructor", ctor_names, ctor=True) for p in ctor_raw)
+    _check_defaults(ctor, f"{cls}.constructor")
+    if len({p.name for p in ctor}) != len(ctor):
+        raise PackError(f"{cls}: duplicate constructor parameter names")
+    methods_raw = raw.get("methods")
+    if not isinstance(methods_raw, dict) or not methods_raw:
+        raise PackError(f"{cls}: 'methods' must be a non-empty object")
+    methods: dict[str, PackMethod] = {}
+    for mname, mraw in methods_raw.items():
+        if not _METHOD.match(mname) or mname in _RESERVED_METHODS:
+            raise PackError(f"{cls}.{mname}: invalid method name")
+        if not isinstance(mraw, dict):
+            raise PackError(f"{cls}.{mname}: must be an object")
+        bad = set(mraw) - {"params", "returns", "starts", "requires_begin", "doc"}
+        if bad:
+            raise PackError(f"{cls}.{mname}: unknown keys {sorted(bad)}")
+        params = tuple(_param(p, f"{cls}.{mname}", ctor_names, ctor=False) for p in mraw.get("params", []))
+        _check_defaults(params, f"{cls}.{mname}")
+        returns = _types(mraw.get("returns", "Void"), f"{cls}.{mname}.returns", RETURN_TYPES)
+        if len(returns) != 1:
+            raise PackError(f"{cls}.{mname}: exactly one return type")
+        methods[mname] = PackMethod(mname, params, returns[0], bool(mraw.get("starts", False)),
+                                    bool(mraw.get("requires_begin", True)))
+    pins = raw.get("pins", {}) or {}
+    forbid = tuple(int(p) for p in pins.get("forbid", [0, 1]))
+    resources = tuple(raw.get("resources", []))
+    if any(r not in RESOURCES for r in resources):
+        raise PackError(f"{cls}: resources must be from {sorted(RESOURCES)}")
+    adapter = raw.get("adapter") or {}
+    lib = adapter.get("library", f"Barmaja_{cls}")
+    header = adapter.get("header", f"Barmaja_{cls}.h")
+    if not (folder / "arduino" / lib / "src" / header).is_file() and not (folder / "arduino" / lib / header).is_file():
+        raise PackError(f"{cls}: adapter header arduino/{lib}/src/{header} not found")
+    if not (folder / "arduino" / lib / "library.properties").is_file():
+        raise PackError(f"{cls}: arduino/{lib}/library.properties missing")
+    adapter_text = ""
+    for candidate in (folder / "arduino" / lib / "src" / header, folder / "arduino" / lib / header):
+        if candidate.is_file():
+            adapter_text = candidate.read_text(encoding="utf-8", errors="replace")
+    if not re.search(rf"\bclass\s+{cls}\b", adapter_text):
+        raise PackError(f"{cls}: adapter header must define 'class {cls}' (the generated C++ uses that name)")
+    deps = raw.get("dependencies", [])
+    if not isinstance(deps, list):
+        raise PackError(f"{cls}: dependencies must be a list")
+    for d in deps:
+        need = {"id", "name", "version", "header", "license"}
+        if not isinstance(d, dict) or not need <= set(d):
+            raise PackError(f"{cls}: each dependency needs {sorted(need)}")
+        if str(d["version"]).strip().lower() in {"", "latest", "pin_pending", "*"}:
+            raise PackError(f"{cls}: dependency {d['name']} must have an exact pinned version")
+    for m in methods.values():
+        try:
+            _signatures(m.params)
+        except PackError as exc:
+            raise PackError(f"{cls}.{m.name}: {exc}") from None
+    starters = [m for m in methods.values() if m.starts]
+    if len(starters) > 1:
+        raise PackError(f"{cls}: at most one method can have \"starts\": true")
+    return DevicePack(
+        class_name=cls, title=str(raw.get("title", cls)), status=status, folder=folder,
+        constructor=ctor, methods=methods, resources=resources,
+        warnings=tuple(str(w) for w in raw.get("warnings", [])), forbid_pins=forbid,
+        distinct_pins=bool(pins.get("distinct", True)), adapter_library=lib, adapter_header=header,
+        dependencies=tuple(deps), boards=tuple(raw.get("boards", ["uno"])), liverun=bool(raw.get("liverun", False)),
+        example=str(raw.get("example", "")), source=source,
+    )
+
+
+def pack_search_dirs() -> list[tuple[Path, str]]:
+    dirs: list[tuple[Path, str]] = [(Path(__file__).resolve().parent / "device_packs_builtin", "built-in")]
+    try:
+        from .environment import ensure_runtime_dirs
+        dirs.append((ensure_runtime_dirs()["root"] / "device-packs", "runtime"))
+    except Exception:
+        pass
+    for item in os.environ.get("BARMAJA_DEVICE_PACKS", "").split(os.pathsep):
+        if item.strip():
+            dirs.append((Path(item.strip()).expanduser(), "BARMAJA_DEVICE_PACKS"))
+    return dirs
+
+
+LOADED: dict[str, DevicePack] = {}
+LOAD_ERRORS: list[str] = []
+
+
+def load_packs(existing_names: set[str]) -> dict[str, DevicePack]:
+    LOADED.clear(); LOAD_ERRORS.clear()
+    for root, source in pack_search_dirs():
+        if not root.is_dir():
+            continue
+        for folder in sorted(p for p in root.iterdir() if p.is_dir() and not p.name.startswith((".", "_"))):
+            try:
+                pack = parse_pack(folder, source=source)
+            except PackError as exc:
+                LOAD_ERRORS.append(f"[{source}] {exc}")
+                continue
+            if source == "built-in" and pack.class_name in os.environ.get("BARMAJA_SKIP_BUILTIN_PACKS", "").split(","):
+                continue   # check_device_pack.py is testing an edited copy of this pack
+            if pack.class_name in existing_names or pack.class_name in LOADED:
+                LOAD_ERRORS.append(f"[{source}] {pack.class_name}: name already used; pack skipped")
+                continue
+            LOADED[pack.class_name] = pack
+    return LOADED
+
+
+# ---------------- registry integration ----------------
+def _signatures(params: tuple[PackParam, ...]) -> list[tuple[str, ...]]:
+    """All accepted argument-type tuples, including shorter calls that use defaults."""
+    out: list[tuple[str, ...]] = []
+    for length in range(required_count(params), len(params) + 1):
+        combos: list[tuple[str, ...]] = [()]
+        for p in params[:length]:
+            combos = [c + (t,) for c in combos for t in p.types]
+        out.extend(combos)
+        if len(out) > 24:
+            raise PackError("too many type combinations (max 24)")
+    return out
+
+
+def register_into(hardware_classes: dict, dependencies: dict, specs) -> None:
+    """Add LOADED packs to the compiler registry (called from api_registry)."""
+    SignatureSpec, MethodSpec, HardwareClassSpec, DependencySpec = specs
+    for pack in LOADED.values():
+        ctor_constraints = tuple(p.rule for p in pack.constructor if p.rule != "none")
+        ctor_sigs = tuple(SignatureSpec(combo, f"Hardware[{pack.class_name}]", ctor_constraints)
+                          for combo in _signatures(pack.constructor))
+        methods = {}
+        for m in pack.methods.values():
+            sigs = tuple(SignatureSpec(combo, m.returns) for combo in _signatures(m.params))
+            methods[m.name] = MethodSpec(m.name, sigs)
+        dep_ids = [f"pack-adapter-{pack.class_name.lower()}"]
+        dependencies[dep_ids[0]] = DependencySpec(dep_ids[0], f"{pack.title} adapter", "pack", pack.adapter_header,
+                                                  f"BARMAJA device pack ({pack.status})")
+        for d in pack.dependencies:
+            if d["id"] not in dependencies:
+                dependencies[d["id"]] = DependencySpec(d["id"], d["name"], str(d["version"]), d.get("header"),
+                                                       f"{d.get('source', '')} {d['license']}".strip())
+            dep_ids.append(d["id"])
+        hardware_classes[pack.class_name] = HardwareClassSpec(
+            pack.class_name, ctor_sigs, methods, includes=(pack.adapter_header,),
+            dependency_ids=tuple(dep_ids), resources=pack.resources,
+        )
+
+
+def adapter_library_dirs() -> list[Path]:
+    return [p.adapter_dir for p in LOADED.values() if p.adapter_dir.is_dir()]
+
+
+def resolve_bound(bound: Any, ctor_values: dict[str, int | None]) -> int | None:
+    if isinstance(bound, int):
+        return bound
+    m = _BOUND.match(str(bound).strip())
+    if not m:
+        return None
+    base = ctor_values.get(m.group(1))
+    if base is None:
+        return None
+    return base + (int(m.group(2).replace(" ", "")) if m.group(2) else 0)
+
+
+# ---------------- Python student classes + stubs ----------------
+_PY = {"Int": "int", "Float": "float", "Bool": "bool", "String": "str", "Scalar": "int | float | bool | str", "Void": "None"}
+
+
+def make_python_class(pack: DevicePack, base):
+    ctor_names = [p.name for p in pack.constructor]
+
+    low, high = required_count(pack.constructor), len(ctor_names)
+
+    def __init__(self, *args):
+        if not low <= len(args) <= high:
+            raise TypeError(f"{pack.class_name}() takes {low}..{high} argument(s): {', '.join(ctor_names)}")
+        self.pins = tuple(args)
+
+    ns = {"__init__": __init__, "_label": f"{pack.class_name} ({pack.title}) [device pack, {pack.status}]",
+          "__doc__": f"{pack.title}. Upload-only device pack ({pack.status})."}
+    for m in pack.methods.values():
+        def method(self, *args, _m=m):
+            return self._only_upload(*args)
+        method.__name__ = m.name
+        ns[m.name] = method
+    return type(pack.class_name, (base,), ns)
+
+
+def render_stubs(packs: dict[str, DevicePack] | None = None) -> str:
+    lines: list[str] = []
+    for pack in (packs or LOADED).values():
+        lines.append(f"class {pack.class_name}:")
+        lines.append(f'    """{pack.title} [device pack, {pack.status}]"""')
+        args = ", ".join(f"{p.name}: int" + (f" = {p.default}" if p.default is not None else "") for p in pack.constructor)
+        lines.append(f"    def __init__(self{', ' if args else ''}{args}) -> None: ...")
+        for m in pack.methods.values():
+            ps = ", ".join(f"{p.name}: {' | '.join(_PY[t] for t in p.types)}" + (f" = {p.default}" if p.default is not None else "") for p in m.params)
+            lines.append(f"    def {m.name}(self{', ' if ps else ''}{ps}) -> {_PY[m.returns]}: ...")
+        lines.append("")
+    return "\n".join(lines)

Barmaja_PyArduino/device_packs_builtin/Button/arduino/Barmaja_Button/library.properties

@@ -0,0 +1,9 @@
+name=Barmaja_Button
+version=1.1.0
+author=BARMAJA
+maintainer=BARMAJA
+sentence=BARMAJA PyArduino device-pack adapter: Push button with built-in pull-up and debounce (no resistor needed)
+paragraph=
+category=Device Control
+url=
+architectures=avr

Barmaja_PyArduino/device_packs_builtin/Button/arduino/Barmaja_Button/src/Barmaja_Button.h

@@ -0,0 +1,18 @@
+#pragma once
+#include <Arduino.h>
+// Wire the button between the pin and GND. Uses INPUT_PULLUP; 30 ms debounce.
+class Button {
+public:
+  explicit Button(uint8_t pin): pin_(pin) {}
+  bool isPressed() { setup(); return digitalRead(pin_) == LOW; }
+  bool wasPressed() {
+    setup();
+    bool now = digitalRead(pin_) == LOW;
+    unsigned long t = millis();
+    if (now != last_ && t - changed_ >= 30) { changed_ = t; last_ = now; if (now) return true; }
+    return false;
+  }
+private:
+  void setup() { if (!ready_) { pinMode(pin_, INPUT_PULLUP); ready_ = true; last_ = false; changed_ = millis(); } }
+  uint8_t pin_; bool ready_ = false; bool last_ = false; unsigned long changed_ = 0;
+};

Barmaja_PyArduino/device_packs_builtin/Button/example.py

@@ -0,0 +1,10 @@
+from Barmaja_PyArduino import *
+upload()
+
+button = Button(2)
+pinMode(13, OUTPUT)
+led = False
+while True:
+    if button.wasPressed():
+        led = not led
+        digitalWrite(13, HIGH if led else LOW)

Barmaja_PyArduino/device_packs_builtin/Button/pack.json

@@ -0,0 +1,40 @@
+{
+  "schema": 1,
+  "class": "Button",
+  "title": "Push button with built-in pull-up and debounce (no resistor needed)",
+  "status": "compile-verified",
+  "boards": [
+    "uno",
+    "nano"
+  ],
+  "constructor": [
+    {
+      "name": "pin",
+      "type": "Int",
+      "rule": "digital_pin"
+    }
+  ],
+  "methods": {
+    "isPressed": {
+      "params": [],
+      "returns": "Bool",
+      "requires_begin": false
+    },
+    "wasPressed": {
+      "params": [],
+      "returns": "Bool",
+      "requires_begin": false,
+      "doc": "True once per press"
+    }
+  },
+  "resources": [],
+  "warnings": [],
+  "adapter": {
+    "library": "Barmaja_Button",
+    "header": "Barmaja_Button.h"
+  },
+  "dependencies": [],
+  "liverun": false,
+  "example": "from Barmaja_PyArduino import *\nupload()\n\nbutton = Button(2)\npinMode(13, OUTPUT)\nled = False\nwhile True:\n    if button.wasPressed():\n        led = not led\n        digitalWrite(13, HIGH if led else LOW)\n",
+  "notes": "No library needed."
+}

Barmaja_PyArduino/device_packs_builtin/ClockDS3231/arduino/Barmaja_ClockDS3231/library.properties

@@ -0,0 +1,9 @@
+name=Barmaja_ClockDS3231
+version=1.1.0
+author=BARMAJA
+maintainer=BARMAJA
+sentence=BARMAJA PyArduino device-pack adapter: DS3231 real-time clock module (I2C)
+paragraph=
+category=Device Control
+url=
+architectures=avr