Barmaja-PyArduino 2.0.0__py3-none-any.whl

Barmaja_PyArduino/device_packs_builtin/ShiftRegister595/pack.json

@@ -0,0 +1,83 @@
+{
+  "schema": 1,
+  "class": "ShiftRegister595",
+  "title": "74HC595 shift register (8 extra outputs from 3 pins)",
+  "status": "compile-verified",
+  "boards": [
+    "uno",
+    "nano"
+  ],
+  "constructor": [
+    {
+      "name": "data_pin",
+      "type": "Int",
+      "rule": "digital_pin"
+    },
+    {
+      "name": "clock_pin",
+      "type": "Int",
+      "rule": "digital_pin"
+    },
+    {
+      "name": "latch_pin",
+      "type": "Int",
+      "rule": "digital_pin"
+    }
+  ],
+  "methods": {
+    "write": {
+      "params": [
+        {
+          "name": "value",
+          "type": "Int",
+          "range": [
+            0,
+            255
+          ]
+        }
+      ],
+      "returns": "Void",
+      "requires_begin": false
+    },
+    "setPin": {
+      "params": [
+        {
+          "name": "output",
+          "type": "Int",
+          "range": [
+            0,
+            7
+          ]
+        },
+        {
+          "name": "on",
+          "type": "Bool"
+        }
+      ],
+      "returns": "Void",
+      "requires_begin": false
+    },
+    "clear": {
+      "params": [],
+      "returns": "Void",
+      "requires_begin": false
+    }
+  },
+  "resources": [],
+  "warnings": [],
+  "adapter": {
+    "library": "Barmaja_ShiftRegister595",
+    "header": "Barmaja_ShiftRegister595.h"
+  },
+  "dependencies": [],
+  "liverun": false,
+  "example": "from Barmaja_PyArduino import *\nupload()\n\nleds = ShiftRegister595(11, 12, 8)\nwhile True:\n    for k in range(8):\n        leds.clear()\n        leds.setPin(k, True)\n        delay(150)\n",
+  "pins": {
+    "forbid": [
+      0,
+      1
+    ],
+    "distinct": true
+  },
+  "notes": "No library needed."
+}

Barmaja_PyArduino/device_packs_builtin/TemperatureDS18B20/arduino/Barmaja_TemperatureDS18B20/library.properties

@@ -0,0 +1,9 @@
+name=Barmaja_TemperatureDS18B20
+version=1.1.0
+author=BARMAJA
+maintainer=BARMAJA
+sentence=BARMAJA PyArduino device-pack adapter: DS18B20 digital temperature sensor (one-wire)
+paragraph=
+category=Device Control
+url=
+architectures=avr

Barmaja_PyArduino/device_packs_builtin/TemperatureDS18B20/arduino/Barmaja_TemperatureDS18B20/src/Barmaja_TemperatureDS18B20.h

@@ -0,0 +1,16 @@
+#pragma once
+#include <Arduino.h>
+#include <OneWire.h>
+#include <DallasTemperature.h>
+// Data pin needs a 4.7k pull-up resistor to 5V. Reads the first sensor on the bus.
+// Returns -127.0 when no sensor answers.
+class TemperatureDS18B20 {
+public:
+  explicit TemperatureDS18B20(uint8_t pin): wire_(pin), sensors_(&wire_) {}
+  void begin() { sensors_.begin(); }
+  float readCelsius() { sensors_.requestTemperatures(); return sensors_.getTempCByIndex(0); }
+  float readFahrenheit() { sensors_.requestTemperatures(); return sensors_.getTempFByIndex(0); }
+private:
+  OneWire wire_;
+  DallasTemperature sensors_;
+};

Barmaja_PyArduino/device_packs_builtin/TemperatureDS18B20/example.py

@@ -0,0 +1,8 @@
+from Barmaja_PyArduino import *
+upload()
+
+temp = TemperatureDS18B20(4)
+temp.begin()
+while True:
+    print("Temperature =", temp.readCelsius(), "C")
+    delay(1000)

Barmaja_PyArduino/device_packs_builtin/TemperatureDS18B20/pack.json

@@ -0,0 +1,63 @@
+{
+  "schema": 1,
+  "class": "TemperatureDS18B20",
+  "title": "DS18B20 digital temperature sensor (one-wire)",
+  "status": "compile-verified",
+  "boards": [
+    "uno",
+    "nano"
+  ],
+  "constructor": [
+    {
+      "name": "pin",
+      "type": "Int",
+      "rule": "digital_pin"
+    }
+  ],
+  "methods": {
+    "begin": {
+      "params": [],
+      "returns": "Void",
+      "starts": true
+    },
+    "readCelsius": {
+      "params": [],
+      "returns": "Float"
+    },
+    "readFahrenheit": {
+      "params": [],
+      "returns": "Float"
+    }
+  },
+  "resources": [],
+  "warnings": [],
+  "adapter": {
+    "library": "Barmaja_TemperatureDS18B20",
+    "header": "Barmaja_TemperatureDS18B20.h"
+  },
+  "dependencies": [
+    {
+      "id": "paulstoffregen-onewire",
+      "name": "OneWire",
+      "version": "2.3.8",
+      "header": "OneWire.h",
+      "license": "MIT-style (PJRC)",
+      "source": "https://github.com/PaulStoffregen/OneWire",
+      "library_folder": "OneWire",
+      "bundled": true
+    },
+    {
+      "id": "milesburton-dallastemperature",
+      "name": "DallasTemperature",
+      "version": "4.0.6",
+      "header": "DallasTemperature.h",
+      "license": "MIT",
+      "source": "https://github.com/milesburton/Arduino-Temperature-Control-Library",
+      "tag": "v4.0.6",
+      "library_folder": "DallasTemperature"
+    }
+  ],
+  "liverun": false,
+  "example": "from Barmaja_PyArduino import *\nupload()\n\ntemp = TemperatureDS18B20(4)\ntemp.begin()\nwhile True:\n    print(\"Temperature =\", temp.readCelsius(), \"C\")\n    delay(1000)\n",
+  "notes": "Each read waits ~750 ms for the sensor conversion."
+}

Barmaja_PyArduino/doctor.py

@@ -0,0 +1,406 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from .environment import (
+    ensure_runtime_dirs, find_normal_arduino_cli, invalidate_cache, load_cache, make_fingerprint,
+    pictoblox_module_dirs, run_text, save_cache,
+)
+
+def _cli_cmd(cli: str, *args: str) -> list[str]:
+    cfg = os.environ.get("BARMAJA_ARDUINO_CONFIG")
+    prefix = [cli]
+    if cfg and Path(cfg).exists():
+        prefix += ["--config-file", cfg]
+    else:
+        bundled = ensure_runtime_dirs()["root"] / "runtime" / "arduino-cli.yaml"
+        try:
+            if bundled.exists() and Path(cli).resolve().parent == bundled.parent.resolve():
+                prefix += ["--config-file", str(bundled)]
+        except OSError:
+            pass
+    return [*prefix, *args]
+
+
+REQUIRED_LIBRARIES = {
+    "Servo": "1.3.0",
+    "Ultrasonic": "3.0.0",
+    "DHT sensor library": "1.4.7",
+    "Adafruit Unified Sensor": "1.1.15",
+    "LiquidCrystal I2C": "1.1.4",
+}
+
+@dataclass(frozen=True)
+class DoctorItem:
+    key: str
+    label: str
+    status: str  # OK/WARN/ERROR
+    detail: str
+
+@dataclass(frozen=True)
+class DoctorReport:
+    items: tuple[DoctorItem, ...]
+    source: str | None = None
+
+    @property
+    def ok(self) -> bool:
+        return not any(i.status == "ERROR" for i in self.items)
+
+    @property
+    def problems(self) -> tuple[DoctorItem, ...]:
+        return tuple(i for i in self.items if i.status != "OK")
+
+    def concise(self) -> str:
+        if self.ok and not self.problems:
+            return "ALL OK"
+        if self.ok:
+            return "\n".join(f"Warning: {i.label}: {i.detail}" for i in self.problems)
+        return "\n".join(f"- {i.label}: {i.detail}" for i in self.problems)
+
+    def detailed(self) -> str:
+        lines = []
+        for i in self.items:
+            lines.append(f"{i.label:<28} {i.status:<5} {i.detail}")
+        if self.source:
+            lines.append(f"Environment source             {self.source}")
+        return "\n".join(lines)
+
+
+def _cli_version(cli: str) -> tuple[str | None, DoctorItem]:
+    result = run_text(_cli_cmd(cli, "version", "--format", "json"), timeout=8)
+    if result.returncode != 0:
+        result = run_text(_cli_cmd(cli, "version"), timeout=8)
+    text = (result.stdout + "\n" + result.stderr).strip()
+    if result.returncode != 0:
+        return None, DoctorItem("arduino_cli", "Arduino CLI", "ERROR", "found but could not run")
+    m = re.search(r"(?:Version:|version\"\s*:\s*\")?v?(\d+\.\d+\.\d+)", text, re.I)
+    version = m.group(1) if m else "unknown"
+    return version, DoctorItem("arduino_cli", "Arduino CLI", "OK", version)
+
+
+def _board_core(cli: str) -> tuple[Path | None, DoctorItem]:
+    result = run_text(_cli_cmd(cli, "core", "list", "--format", "json"), timeout=12)
+    if result.returncode != 0:
+        return None, DoctorItem("avr_core", "Arduino Uno AVR Core", "ERROR", "not available")
+    try:
+        payload = json.loads(result.stdout or "[]")
+    except json.JSONDecodeError:
+        payload = []
+    rows = payload if isinstance(payload, list) else payload.get("platforms", []) if isinstance(payload, dict) else []
+    for row in rows:
+        ident = row.get("id") or row.get("ID") or row.get("platform")
+        ver = row.get("installed_version") or row.get("version") or row.get("Installed")
+        if not ver and isinstance(row.get("releases"), dict):
+            for rv, meta in row["releases"].items():
+                if isinstance(meta, dict) and meta.get("installed") is True:
+                    ver = rv; break
+        if ident == "arduino:avr":
+            status = "OK" if str(ver) == "1.8.8" else "WARN"
+            return None, DoctorItem("avr_core", "Arduino Uno AVR Core", status, str(ver or "unknown"))
+    return None, DoctorItem("avr_core", "Arduino Uno AVR Core", "ERROR", "missing")
+
+
+def _libraries(cli: str) -> tuple[list[Path], list[DoctorItem]]:
+    result = run_text(_cli_cmd(cli, "lib", "list", "--format", "json"), timeout=15)
+    items: list[DoctorItem] = []
+    markers: list[Path] = []
+    if result.returncode != 0:
+        return markers, [DoctorItem("libraries", "Arduino libraries", "ERROR", "could not query libraries")]
+    try:
+        payload = json.loads(result.stdout or "[]")
+    except json.JSONDecodeError:
+        payload = []
+    rows = payload if isinstance(payload, list) else payload.get("installed_libraries", []) if isinstance(payload, dict) else []
+    available = {}
+    aliases = {"liquidcrystal_i2c": "LiquidCrystal I2C", "liquidcrystal i2c": "LiquidCrystal I2C"}
+    for row in rows:
+        lib = row.get("library", row) if isinstance(row, dict) else {}
+        name = lib.get("name")
+        version = lib.get("version")
+        install_dir = lib.get("install_dir")
+        if name:
+            canonical = aliases.get(str(name).lower(), name)
+            available[canonical] = (str(version or "unknown"), Path(install_dir) if install_dir else None)
+            if install_dir:
+                markers.append(Path(install_dir) / "library.properties")
+    # Merge Barmaja-private Light/Full-pack libraries; these intentionally take precedence.
+    private = ensure_runtime_dirs()["root"] / "arduino-libraries"
+    if private.exists():
+        for props in private.glob("*/library.properties"):
+            data={}
+            for line in props.read_text(encoding="utf-8", errors="replace").splitlines():
+                if "=" in line:
+                    k,v=line.split("=",1); data[k.strip()]=v.strip()
+            n=data.get("name"); v=data.get("version","unknown")
+            if n:
+                canonical=aliases.get(n.lower(), n); available[canonical]=(v, props.parent); markers.append(props)
+    for name, expected in REQUIRED_LIBRARIES.items():
+        entry = available.get(name)
+        got = entry[0] if entry else None
+        if got is None:
+            items.append(DoctorItem(f"lib:{name}", name, "ERROR", f"missing (need {expected})"))
+        elif got == expected:
+            items.append(DoctorItem(f"lib:{name}", name, "OK", got))
+        else:
+            items.append(DoctorItem(f"lib:{name}", name, "WARN", f"{got}; tested version is {expected}"))
+    return markers, items
+
+
+def _compile_capability(cli: str, verbose: bool = False) -> DoctorItem:
+    """Real Uno test compile with the same library pinning as student builds.
+
+    The sketch lives under the ASCII-only Barmaja runtime root (not %TEMP%, which
+    contains the Windows user name) so non-ASCII user names do not break the test.
+    """
+    import tempfile
+    from .toolchain import _private_library_args
+    build_root = ensure_runtime_dirs()["build"]
+    with tempfile.TemporaryDirectory(prefix="doctor_", dir=str(build_root)) as td:
+        root = Path(td); sketch = root / "DoctorBlink"; sketch.mkdir()
+        (sketch / "DoctorBlink.ino").write_text(
+            "void setup(){pinMode(13,OUTPUT);}\nvoid loop(){digitalWrite(13,HIGH);delay(10);digitalWrite(13,LOW);delay(10);}\n",
+            encoding="utf-8",
+        )
+        args = _cli_cmd(cli, "compile", "--fqbn", "arduino:avr:uno", "--warnings", "all")
+        args += _private_library_args()
+        args += ["--build-path", str(root / "build"), str(sketch)]
+        result = run_text(args, timeout=180)
+        if result.returncode == 0:
+            return DoctorItem("compile_test", "Uno test compile", "OK", "PASS")
+        if verbose:
+            tail = " | ".join(line.strip() for line in ((result.stdout or "") + "\n" + (result.stderr or "")).strip().splitlines()[-6:])
+            return DoctorItem("compile_test", "Uno test compile", "ERROR", f"failed: {tail[:900]}")
+        return DoctorItem("compile_test", "Uno test compile", "ERROR", "failed; run 'pyarduino doctor --details' for the compiler output")
+
+
+def _running_in_pictoblox() -> bool:
+    exe = (sys.executable or "").lower().replace("\\", "/")
+    return "pictoblox" in exe
+
+
+def _pictoblox_python_support(version_info):
+    """Return (supported, detail) for the embedded PictoBlox interpreter."""
+    major, minor, micro = int(version_info[0]), int(version_info[1]), int(version_info[2])
+    normal_ok = (major, minor) >= (3, 10)   # 3.10 and every newer Python
+    pictoblox_compat_ok = (major, minor) == (3, 8)
+    ok = normal_ok or pictoblox_compat_ok
+    if pictoblox_compat_ok:
+        detail = f"{major}.{minor}.{micro} (PictoBlox compatibility host)"
+    elif normal_ok:
+        detail = f"{major}.{minor}.{micro}"
+    else:
+        detail = f"{major}.{minor}.{micro} (supported: PictoBlox 3.8.x or normal Python 3.10 or newer)"
+    return ok, detail
+
+
+def _pictoblox_frontend_self_test() -> DoctorItem:
+    """Compile a tiny list-index program through the real Python frontend.
+
+    This specifically protects the mandatory PictoBlox Python 3.8 host, whose
+    AST shape differs from Python 3.9+ for ``a[i]``.
+    """
+    from .compiler import Transpiler
+    source = """from Barmaja_PyArduino import *
+
+leds = [2, 3, 4]
+i = 0
+pinMode(leds[i], OUTPUT)
+
+while True:
+    digitalWrite(leds[i], HIGH)
+    i = (i + 1) % 3
+"""
+    try:
+        Transpiler().compile_text(source)
+    except Exception as exc:
+        return DoctorItem(
+            "pictoblox_frontend",
+            "PictoBlox Python frontend",
+            "ERROR",
+            f"list-index self-test failed: {exc}",
+        )
+    return DoctorItem("pictoblox_frontend", "PictoBlox Python frontend", "OK", "list indexing PASS")
+
+
+def _pictoblox_items() -> tuple[DoctorItem, ...]:
+    from . import __version__ as current
+    from .environment import installed_package_version
+    items: list[DoctorItem] = []
+    inside = _running_in_pictoblox()
+    if inside:
+        py = sys.version_info
+        # PictoBlox V1 embeds CPython 3.8.10 on current Windows releases.
+        # Normal Python is a 3.10-and-newer product target, but the mandatory
+        # PictoBlox host is a deliberate compatibility exception.
+        ok, detail = _pictoblox_python_support(py)
+        items.append(DoctorItem("pictoblox_python", "PictoBlox Python", "OK" if ok else "ERROR", detail))
+        here = Path(__file__).resolve().parent
+        items.append(DoctorItem("pictoblox_loaded", "Barmaja_PyArduino loaded from", "OK", f"{here} (version {current})"))
+        items.append(_pictoblox_frontend_self_test())
+        copies = []
+        for entry in sys.path:
+            try:
+                candidate = Path(entry or ".").resolve() / "Barmaja_PyArduino"
+                if (candidate / "__init__.py").exists() and candidate.resolve() != here:
+                    copies.append(f"{candidate} ({installed_package_version(candidate) or 'unknown'})")
+            except OSError:
+                continue
+        if copies:
+            items.append(DoctorItem("pictoblox_duplicates", "Other Barmaja_PyArduino copies", "WARN", "; ".join(copies)))
+    dirs = pictoblox_module_dirs()
+    if not dirs:
+        items.append(DoctorItem("pictoblox", "PictoBlox", "ERROR" if not inside else "WARN",
+                                "python_modules directory not detected (Documents\\PictoBlox\\python_modules)"))
+        return tuple(items)
+    if len(dirs) > 1:
+        items.append(DoctorItem(
+            "pictoblox_multiple_dirs", "Multiple PictoBlox module directories", "WARN",
+            "; ".join(str(p) for p in dirs),
+        ))
+    for p in dirs:
+        pkg = p / "Barmaja_PyArduino"
+        exists = p.is_dir()
+        writable = os.access(p, os.W_OK) if exists else os.access(p.parent, os.W_OK)
+        items.append(DoctorItem("pictoblox", "PictoBlox modules", "OK" if exists else "WARN",
+                                str(p) if exists else f"{p} (will be created by offline installer)"))
+        items.append(DoctorItem("pictoblox_write", "PictoBlox modules writable", "OK" if writable else "ERROR", "yes" if writable else "no"))
+        if not pkg.exists():
+            items.append(DoctorItem("pictoblox_import", "Barmaja_PyArduino in PictoBlox", "ERROR", "not installed; run the Barmaja offline installer"))
+            continue
+        installed = installed_package_version(pkg)
+        if installed != current:
+            items.append(DoctorItem("pictoblox_import", "Barmaja_PyArduino in PictoBlox", "ERROR",
+                                    f"version {installed or 'unknown'} installed, {current} expected; run the Barmaja offline installer again"))
+        else:
+            items.append(DoctorItem("pictoblox_import", "Barmaja_PyArduino in PictoBlox", "OK", f"installed ({installed})"))
+    return tuple(items)
+
+
+def _bundled_discovery_tools_item(cli: str) -> DoctorItem | None:
+    """Check the four Arduino CLI builtin helpers shipped by the Full Pack."""
+    try:
+        cli_path = Path(cli).resolve()
+        runtime = (ensure_runtime_dirs()["root"] / "runtime").resolve()
+        if cli_path.parent != runtime:
+            return None
+    except OSError:
+        return None
+
+    required = {
+        "serial-discovery": "serial-discovery.exe" if os.name == "nt" else "serial-discovery",
+        "mdns-discovery": "mdns-discovery.exe" if os.name == "nt" else "mdns-discovery",
+        "dfu-discovery": "dfu-discovery.exe" if os.name == "nt" else "dfu-discovery",
+        "serial-monitor": "serial-monitor.exe" if os.name == "nt" else "serial-monitor",
+    }
+    tools_root = runtime / "arduino-data" / "packages" / "builtin" / "tools"
+    missing = []
+    for family, exe_name in required.items():
+        family_root = tools_root / family
+        found = any((version_dir / exe_name).is_file() for version_dir in family_root.iterdir()) if family_root.is_dir() else False
+        if not found:
+            missing.append(family)
+    if missing:
+        return DoctorItem(
+            "discovery_tools",
+            "Arduino USB discovery tools",
+            "ERROR",
+            "missing: " + ", ".join(missing) + "; reinstall the Full Offline package",
+        )
+    return DoctorItem("discovery_tools", "Arduino USB discovery tools", "OK", "present")
+
+
+def run_doctor(*, details: bool = False, pictoblox: bool = False, use_cache: bool = True) -> DoctorReport:
+    if pictoblox:
+        return DoctorReport(_pictoblox_items(), source="PictoBlox")
+
+    try:
+        from .toolchain import find_arduino_cli
+        cli = find_arduino_cli()
+    except Exception:
+        cli = None
+    items: list[DoctorItem] = []
+    if not cli:
+        items.append(DoctorItem("arduino_cli", "Arduino environment", "ERROR", "Arduino CLI/toolchain not found"))
+        return DoctorReport(tuple(items), source=None)
+
+    _, cli_item = _cli_version(cli)
+    items.append(cli_item)
+    discovery_item = _bundled_discovery_tools_item(cli)
+    if discovery_item is not None:
+        items.append(discovery_item)
+    _, core_item = _board_core(cli)
+    items.append(core_item)
+    lib_markers, lib_items = _libraries(cli)
+    items.extend(lib_items)
+
+    quick_fp = make_fingerprint(cli, libraries=_pinned_library_markers())
+    full_fp = make_fingerprint(cli, libraries=lib_markers)
+    cached = load_cache() if use_cache else None
+    full_cache_match = bool(_cache_is_content_safe(full_fp) and cached and cached.get("fingerprint") == full_fp.digest() and cached.get("status") == "READY")
+
+    # A first/full/manual diagnosis proves that the Uno core/compiler can really compile.
+    # A matching deep cache may skip this expensive step; any real compile/upload failure
+    # invalidates the cache in toolchain.py.
+    if not full_cache_match or details:
+        if core_item.status != "ERROR":
+            items.append(_compile_capability(cli, verbose=details))
+
+    from .toolchain import bundled_arduino_cli
+    bundled = bundled_arduino_cli()
+    source = "Barmaja bundled runtime" if bundled and Path(bundled).resolve() == Path(cli).resolve() else f"Arduino environment ({cli})"
+    report = DoctorReport(tuple(items), source=source)
+    if report.ok:
+        save_cache(full_fp, quick_fingerprint=quick_fp, source=report.source)
+    else:
+        invalidate_cache()
+    return report
+
+def doctor_pictoblox(*, details: bool = False) -> str:
+    """In-Python doctor for PictoBlox: package install + the Arduino toolchain used by upload()."""
+    package = run_doctor(details=details, pictoblox=True, use_cache=False)
+    environment = run_doctor(details=details, pictoblox=False, use_cache=not details)
+    report = DoctorReport(package.items + environment.items, source=environment.source)
+    return report.detailed() if details else report.concise()
+
+
+def _pinned_library_markers() -> list[Path]:
+    private = ensure_runtime_dirs()["root"] / "arduino-libraries"
+    return sorted(private.glob("*/library.properties")) if private.exists() else []
+
+
+def _cache_is_content_safe(fp) -> bool:
+    # Only the Full Pack has a known immutable layout that we can fingerprint
+    # strongly enough to skip a real compile. Existing IDE/PictoBlox environments
+    # are still supported, but Doctor performs the compile instead of trusting cache.
+    return bool(getattr(fp, "integrity_markers", ()))
+
+
+def quick_environment_ok() -> bool:
+    """Safe fast path for an unchanged pinned Full-Pack environment."""
+    try:
+        from .toolchain import find_arduino_cli
+        cli = find_arduino_cli()
+    except Exception:
+        invalidate_cache(); return False
+    fp = make_fingerprint(cli, libraries=_pinned_library_markers())
+    if not _cache_is_content_safe(fp):
+        return False
+    cached = load_cache()
+    return bool(cached and cached.get("status") == "READY" and cached.get("quick_fingerprint", cached.get("fingerprint")) == fp.digest())
+
+
+def ensure_environment_ready() -> None:
+    """Silent normal-run check. Cache accelerates success but never masks failures."""
+    if quick_environment_ok():
+        return
+    report = run_doctor(details=False, pictoblox=False, use_cache=True)
+    if not report.ok:
+        from .errors import ToolchainError
+        problems = "; ".join(f"{i.label}: {i.detail}" for i in report.problems)
+        raise ToolchainError(problems or "Arduino environment is not ready.")