Barmaja-PyArduino 2.0.0__tar.gz

barmaja_pyarduino-2.0.0/Barmaja_PyArduino/__init__.py

@@ -0,0 +1,528 @@
+"""Student-facing Barmaja PyArduino API.
+
+Two execution modes use the same Arduino-style student API:
+
+Standalone mode
+    ``upload()`` compiles the Python program to Arduino C++ and uploads it. The
+    Uno then runs independently from the PC.
+
+LiveRun mode
+    ``LiveRun()`` keeps Python running on the PC/PictoBlox and controls the Uno
+    live through the pinned Telemetrix firmware.
+"""
+
+__version__ = "2.0.0"
+# Internal same-version build marker used by the small DEV1 updater.  Earlier
+# DEV1 wheels share the public version but do not contain the final runtime
+# layout fix, so version metadata alone cannot identify the corrected build.
+__liverun_update__ = "1.1.0.dev8-library-adder-2026-10-31"
+
+HIGH = 1
+LOW = 0
+INPUT = 0
+OUTPUT = 1
+INPUT_PULLUP = 2
+A0, A1, A2, A3, A4, A5 = 14, 15, 16, 17, 18, 19
+DHT11 = 11
+DHT22 = 22
+CM = 28
+INC = 71
+
+
+class ArduinoOnlyError(RuntimeError):
+    """Raised when Arduino-only code is run on the PC without LiveRun."""
+
+
+def _not_desktop(*_args, **_kwargs):
+    raise ArduinoOnlyError(
+        "This is a Barmaja PyArduino program. Choose one mode near the top: "
+        "upload() for standalone Arduino execution, or LiveRun() for live PC/PictoBlox control."
+    )
+
+
+def _live_backend_or_none():
+    try:
+        from .live import is_live, backend
+        return backend() if is_live() else None
+    except Exception:
+        return None
+
+
+def _dispatch(method, *args):
+    live = _live_backend_or_none()
+    if live is None:
+        return _not_desktop(*args)
+    return getattr(live, method)(*args)
+
+
+def pinMode(pin, mode):
+    return _dispatch("pin_mode", pin, mode)
+
+
+def digitalWrite(pin, value):
+    return _dispatch("digital_write", pin, value)
+
+
+def digitalRead(pin):
+    return _dispatch("digital_read", pin)
+
+
+def analogRead(pin):
+    return _dispatch("analog_read", pin)
+
+
+def analogWrite(pin, value):
+    return _dispatch("analog_write", pin, value)
+
+
+def delay(milliseconds):
+    return _dispatch("delay", milliseconds)
+
+
+def millis():
+    return _dispatch("millis")
+
+
+def tone(pin, frequency, duration=None):
+    """Arduino square-wave output. Standalone only until tested LiveRun firmware exists."""
+    if _live_backend_or_none() is not None:
+        raise RuntimeError("tone() is available with upload(), but not with LiveRun() yet (Telemetrix firmware has no tone command).")
+    return _not_desktop(pin, frequency, duration)
+
+
+def noTone(pin):
+    if _live_backend_or_none() is not None:
+        raise RuntimeError("noTone() is available with upload(), but not with LiveRun() yet (Telemetrix firmware has no tone command).")
+    return _not_desktop(pin)
+
+
+def micros():
+    if _live_backend_or_none() is not None:
+        raise RuntimeError("micros() currently requires upload() mode; LiveRun timing is host-side, not Arduino microseconds.")
+    return _not_desktop()
+
+
+def delayMicroseconds(microseconds):
+    if _live_backend_or_none() is not None:
+        raise RuntimeError("delayMicroseconds() currently requires upload() mode; USB LiveRun timing cannot guarantee microseconds.")
+    return _not_desktop(microseconds)
+
+
+def map(value, in_min, in_max, out_min, out_max):
+    """Integer Arduino-style linear mapping (truncates division toward zero)."""
+    if in_min == in_max:
+        raise ValueError("map() input range cannot have equal minimum and maximum.")
+    # Small host-only convenience for LiveRun; always compiled to C++ for upload().
+    numerator = (value - in_min) * (out_max - out_min)
+    denominator = in_max - in_min
+    result = (abs(numerator) // abs(denominator)) * (1 if numerator * denominator >= 0 else -1) + out_min
+    return result
+
+
+def constrain(value, lower, upper):
+    if lower > upper:
+        raise ValueError("constrain() requires lower <= upper.")
+    return max(lower, min(value, upper))
+
+
+# Stage 2 hardware is compiled into the Uno sketch for upload() only.
+# Explicitly reject desktop/LiveRun usage rather than pretending it works.
+class _UploadOnlyModule:
+    _label = "Stage 2 device"
+    def _only_upload(self, *args):
+        if _live_backend_or_none() is not None:
+            raise RuntimeError(f"{self._label} is supported by upload() only, not LiveRun() yet.")
+        return _not_desktop(*args)
+
+# Stage 4: separate module-dependent standalone transports and motion sensors.
+class BluetoothSerial(_UploadOnlyModule):
+    _label = "BluetoothSerial (HC-05/HC-06 UART)"
+    def __init__(self, rx_pin, tx_pin): self.pins = (rx_pin, tx_pin)
+    def begin(self, baud): return self._only_upload(baud)
+    def listen(self): return self._only_upload()
+    def available(self): return self._only_upload()
+    def read(self): return self._only_upload()
+    def write(self, value): return self._only_upload(value)
+
+class MPU6050Sensor(_UploadOnlyModule):
+    _label = "MPU6050Sensor (GY-521 only)"
+    def begin(self): return self._only_upload()
+    def update(self): return self._only_upload()
+    def angleX(self): return self._only_upload()
+    def angleY(self): return self._only_upload()
+    def angleZ(self): return self._only_upload()
+    def accelX(self): return self._only_upload()
+    def accelY(self): return self._only_upload()
+    def accelZ(self): return self._only_upload()
+    def gyroX(self): return self._only_upload()
+    def gyroY(self): return self._only_upload()
+    def gyroZ(self): return self._only_upload()
+
+class GPSModule(_UploadOnlyModule):
+    _label = "GPSModule (NMEA UART)"
+    def __init__(self, rx_pin, tx_pin): self.pins = (rx_pin, tx_pin)
+    def begin(self, baud): return self._only_upload(baud)
+    def update(self): return self._only_upload()
+    def hasFix(self): return self._only_upload()
+    def latitude(self): return self._only_upload()
+    def longitude(self): return self._only_upload()
+    def satellites(self): return self._only_upload()
+
+class EthernetW5500(_UploadOnlyModule):
+    _label = "EthernetW5500 (W5500 shield/module)"
+    def __init__(self, cs_pin, mac0, mac1, mac2, mac3, mac4, mac5):
+        self.mac = (mac0,mac1,mac2,mac3,mac4,mac5); self.cs_pin = cs_pin
+    def beginIP(self, a,b,c,d): return self._only_upload(a,b,c,d)
+    def connect(self, a,b,c,d,port): return self._only_upload(a,b,c,d,port)
+    def connected(self): return self._only_upload()
+    def write(self, value): return self._only_upload(value)
+    def available(self): return self._only_upload()
+    def read(self): return self._only_upload()
+    def stop(self): return self._only_upload()
+
+class WiFiESPAT(_UploadOnlyModule):
+    _label = "WiFiESPAT (ESP8266/ESP32 with AT firmware)"
+    def __init__(self, rx_pin, tx_pin): self.pins = (rx_pin, tx_pin)
+    def begin(self, baud): return self._only_upload(baud)
+    def connect(self, ssid, password): return self._only_upload(ssid,password)
+    def connected(self): return self._only_upload()
+    def tcpConnect(self, a,b,c,d,port): return self._only_upload(a,b,c,d,port)
+    def write(self, value): return self._only_upload(value)
+    def available(self): return self._only_upload()
+    def read(self): return self._only_upload()
+    def stop(self): return self._only_upload()
+
+class RFID(_UploadOnlyModule):
+    _label = "RFID"
+    def __init__(self, ss_pin, reset_pin):
+        self.ss_pin = ss_pin
+        self.reset_pin = reset_pin
+    def begin(self): return self._only_upload()
+    def readUID(self): return self._only_upload()
+
+class IRRemote(_UploadOnlyModule):
+    _label = "IRRemote"
+    def __init__(self, receive_pin): self.receive_pin = receive_pin
+    def begin(self): return self._only_upload()
+    def readCommand(self): return self._only_upload()
+
+class Keypad4x4(_UploadOnlyModule):
+    _label = "Keypad4x4"
+    def __init__(self, r1, r2, r3, r4, c1, c2, c3, c4):
+        self.pins = (r1,r2,r3,r4,c1,c2,c3,c4)
+    def getKey(self): return self._only_upload()
+
+class StepperMotor(_UploadOnlyModule):
+    _label = "StepperMotor"
+    def __init__(self, p1,p2,p3,p4): self.pins = (p1,p2,p3,p4)
+    def setMaxSpeed(self, speed): return self._only_upload(speed)
+    def setAcceleration(self, value): return self._only_upload(value)
+    def moveTo(self, position): return self._only_upload(position)
+    def move(self, distance): return self._only_upload(distance)
+    def run(self): return self._only_upload()
+    def distanceToGo(self): return self._only_upload()
+    def currentPosition(self): return self._only_upload()
+    def setCurrentPosition(self, position): return self._only_upload(position)
+
+class OneWireBus(_UploadOnlyModule):
+    _label = "OneWireBus"
+    def __init__(self, pin): self.pin = pin
+    def reset(self): return self._only_upload()
+    def write(self, value): return self._only_upload(value)
+    def read(self): return self._only_upload()
+
+class LEDMatrixMAX7219(_UploadOnlyModule):
+    _label = "LEDMatrixMAX7219 (MAX7219/MAX7221 only)"
+    def __init__(self, data_pin, clk_pin, cs_pin): self.pins = (data_pin, clk_pin, cs_pin)
+    def begin(self): return self._only_upload()
+    def clear(self): return self._only_upload()
+    def setPixel(self, row, col, on): return self._only_upload(row,col,on)
+    def setRow(self, row, value): return self._only_upload(row,value)
+    def setBrightness(self, brightness): return self._only_upload(brightness)
+
+class FourDigitTM1637(_UploadOnlyModule):
+    _label = "FourDigitTM1637 (TM1637 only)"
+    def __init__(self, clk_pin, dio_pin): self.pins = (clk_pin,dio_pin)
+    def setBrightness(self, brightness): return self._only_upload(brightness)
+    def showNumber(self, number): return self._only_upload(number)
+    def clear(self): return self._only_upload()
+
+class _EEPROMAPI(_UploadOnlyModule):
+    _label = "EEPROM"
+    def read(self, address): return self._only_upload(address)
+    def write(self, address, value): return self._only_upload(address,value)
+    def update(self, address, value): return self._only_upload(address,value)
+    def length(self): return self._only_upload()
+EEPROM = _EEPROMAPI()
+
+class _SPIAPI(_UploadOnlyModule):
+    _label = "SPI"
+    def begin(self): return self._only_upload()
+    def transfer(self, value): return self._only_upload(value)
+    def end(self): return self._only_upload()
+SPI = _SPIAPI()
+
+class Servo:
+    def __init__(self):
+        self._pin = None
+        self._last_angle = None
+
+    def attach(self, pin, min_us=None, max_us=None):
+        if (min_us is None) != (max_us is None):
+            raise TypeError("Servo.attach() accepts attach(pin) or attach(pin, min, max).")
+        live = _live_backend_or_none()
+        if live is None:
+            return _not_desktop(pin, min_us, max_us)
+        live.servo_attach(pin, min_us, max_us)
+        self._pin = int(pin)
+
+    def _attached_pin(self):
+        if self._pin is None:
+            raise RuntimeError("Call Servo.attach(pin) before using this Servo.")
+        return self._pin
+
+    def write(self, angle):
+        live = _live_backend_or_none()
+        if live is None:
+            return _not_desktop(angle)
+        result = live.servo_write(self._attached_pin(), angle)
+        self._last_angle = int(angle)
+        return result
+
+    def writeMicroseconds(self, microseconds):
+        live = _live_backend_or_none()
+        if live is None:
+            return _not_desktop(microseconds)
+        return live.servo_write_microseconds(self._attached_pin(), microseconds)
+
+    def read(self):
+        live = _live_backend_or_none()
+        if live is None:
+            return _not_desktop()
+        if self._last_angle is None:
+            raise RuntimeError("Servo.read() has no value yet; call Servo.write(angle) first in LiveRun.")
+        return self._last_angle
+
+    def detach(self):
+        live = _live_backend_or_none()
+        if live is None:
+            return _not_desktop()
+        pin = self._attached_pin()
+        result = live.servo_detach(pin)
+        self._pin = None
+        return result
+
+    def attached(self):
+        live = _live_backend_or_none()
+        if live is None:
+            return _not_desktop()
+        return False if self._pin is None else bool(live.servo_attached(self._pin))
+
+
+class Ultrasonic:
+    def __init__(self, trigger_pin, echo_pin):
+        self._pins = (int(trigger_pin), int(echo_pin))
+
+    def read(self, unit=None):
+        if unit not in (None, CM):
+            raise ValueError("LiveRun ultrasonic currently supports centimetres (CM).")
+        live = _live_backend_or_none()
+        if live is None:
+            return _not_desktop(unit)
+        return live.ultrasonic_read(*self._pins)
+
+    def setTimeout(self, timeout):
+        # Existing Telemetrix wrapper manages its own bounded read timeout.
+        # Keep the call accepted in standalone compilation, but make unsupported
+        # live behavior explicit rather than silently ignoring it.
+        if _live_backend_or_none() is not None:
+            raise RuntimeError("Ultrasonic.setTimeout() is not configurable in LiveRun DEV1.")
+        return _not_desktop(timeout)
+
+
+class DHT:
+    def __init__(self, pin, sensor_type):
+        self._config = (int(pin), int(sensor_type))
+        self._begun = False
+
+    def begin(self):
+        live = _live_backend_or_none()
+        if live is None:
+            return _not_desktop()
+        live.dht_begin(*self._config)
+        self._begun = True
+
+    def _last(self):
+        live = _live_backend_or_none()
+        if live is None:
+            return _not_desktop()
+        if not self._begun:
+            live.dht_begin(*self._config)
+            self._begun = True
+        return live.dht_last(*self._config)
+
+    def readTemperature(self):
+        temperature, _humidity = self._last()
+        return temperature
+
+    def readHumidity(self):
+        _temperature, humidity = self._last()
+        return humidity
+
+
+class LiquidCrystal_I2C:
+    def __init__(self, address, columns, rows):
+        self._config = (int(address), int(columns), int(rows))
+        self._lcd = None
+
+    def _ensure_lcd(self):
+        live = _live_backend_or_none()
+        if live is None:
+            return _not_desktop()
+        if self._lcd is None:
+            self._lcd = live.lcd_create(*self._config)
+        return self._lcd
+
+    def init(self):
+        return self._ensure_lcd().begin()
+
+    def begin(self, columns, rows, charsize=None):
+        # Constructor dimensions remain authoritative in the Arduino-compatible
+        # API. Accept matching begin() dimensions used by many classroom examples.
+        if int(columns) != self._config[1] or int(rows) != self._config[2]:
+            self._config = (self._config[0], int(columns), int(rows))
+            self._lcd = None
+        return self._ensure_lcd().begin()
+
+    def clear(self): return self._ensure_lcd().clear()
+    def home(self): return self._ensure_lcd().home()
+    def setCursor(self, column, row): return self._ensure_lcd().set_cursor(column, row)
+    def print(self, value): return self._ensure_lcd().print(value)
+    def backlight(self): return self._ensure_lcd().backlight(True)
+    def noBacklight(self): return self._ensure_lcd().backlight(False)
+    def display(self): return self._ensure_lcd().display(True)
+    def noDisplay(self): return self._ensure_lcd().display(False)
+
+
+def _arduino_text(value, fmt=None) -> str:
+    """Format a value like Arduino's ``Serial.print`` (used by LiveRun only).
+
+    * int + base 2/8/10/16  -> that base (HEX uppercase, like Arduino);
+    * float                 -> 2 decimals by default, or ``fmt`` decimals;
+    * bool                  -> 1 / 0 (Arduino prints bool as an integer);
+    * str                   -> unchanged.
+    """
+    if isinstance(value, bool):
+        return "1" if value else "0"
+    if isinstance(value, int):
+        if fmt in (None, 10):
+            return str(value)
+        digits = {2: "01", 8: "01234567", 16: "0123456789ABCDEF"}
+        if fmt not in digits:
+            return str(value)
+        base = int(fmt)
+        number = value if value >= 0 else value & 0xFFFFFFFF  # Arduino prints negatives as unsigned
+        if number == 0:
+            return "0"
+        out = ""
+        while number:
+            number, rem = divmod(number, base)
+            out = digits[base][rem] + out
+        return out
+    if isinstance(value, float):
+        places = 2 if fmt is None else int(fmt)
+        return f"{value:.{places}f}"
+    return str(value)
+
+
+class _SerialAPI:
+    """``Serial`` for both modes.
+
+    ``upload()`` programs are compiled to real Arduino Serial calls; this object
+    is only used on the PC.  In LiveRun mode it is a *stdout compatibility layer*:
+    Telemetrix owns the USB port, so text goes to the host Python console and
+    nothing is ever written into the Telemetrix binary channel.
+    ``Serial.begin(baud)`` is a documented no-op in LiveRun (the Telemetrix
+    firmware baud is fixed).
+    """
+
+    def _live(self) -> bool:
+        return _live_backend_or_none() is not None
+
+    @staticmethod
+    def _emit(text: str) -> None:
+        import sys
+        try:
+            sys.stdout.write(text)
+        except UnicodeEncodeError:
+            enc = getattr(sys.stdout, "encoding", None) or "ascii"
+            sys.stdout.write(text.encode(enc, errors="replace").decode(enc, errors="replace"))
+        try:
+            sys.stdout.flush()
+        except Exception:
+            pass
+
+    def begin(self, baud=9600):
+        if self._live():
+            return None
+        return _not_desktop(baud)
+
+    def print(self, value="", fmt=None):
+        if self._live():
+            self._emit(_arduino_text(value, fmt))
+            return None
+        return _not_desktop(value, fmt)
+
+    def println(self, value=None, fmt=None):
+        if self._live():
+            self._emit(("" if value is None else _arduino_text(value, fmt)) + "\n")
+            return None
+        return _not_desktop(value, fmt)
+
+    def available(self):
+        if self._live():
+            raise RuntimeError("Serial.available() is unavailable in LiveRun because Telemetrix owns USB Serial.")
+        return _not_desktop()
+
+    def read(self):
+        if self._live():
+            raise RuntimeError("Serial.read() is unavailable in LiveRun because Telemetrix owns USB Serial.")
+        return _not_desktop()
+
+
+class _WireAPI:
+    def begin(self): return _dispatch("wire_begin")
+    def beginTransmission(self, address): return _dispatch("wire_begin_transmission", address)
+    def write(self, value): return _dispatch("wire_write", value)
+    def endTransmission(self): return _dispatch("wire_end_transmission")
+    def requestFrom(self, address, count): return _dispatch("wire_request_from", address, count)
+    def available(self): return _dispatch("wire_available")
+    def read(self): return _dispatch("wire_read")
+
+
+Serial = _SerialAPI()
+Wire = _WireAPI()
+
+# Device packs: one upload-only Python class per pack.json (same names the compiler uses).
+from . import device_packs as _device_packs
+from . import api_registry as _api_registry  # noqa: F401  (loads packs)
+def _install_device_pack_classes() -> None:
+    for name, pack in _device_packs.LOADED.items():
+        globals()[name] = _device_packs.make_python_class(pack, _UploadOnlyModule)
+
+
+_install_device_pack_classes()
+
+# PC-side workflows callable from PictoBlox and normal Python editors.
+from .workflow import show_code, upload, verify
+from .live import LiveRun, LiveStop
+
+# Diagnostic helper for PictoBlox/embedded Python hosts.
+from .doctor import doctor_pictoblox
+
+__all__ = [
+    "HIGH", "LOW", "INPUT", "OUTPUT", "INPUT_PULLUP", "A0", "A1", "A2", "A3", "A4", "A5",
+    "DHT11", "DHT22", "CM", "INC", "pinMode", "digitalWrite", "digitalRead", "analogRead", "analogWrite",
+    "delay", "millis", "tone", "noTone", "micros", "delayMicroseconds", "map", "constrain", "Servo", "Ultrasonic", "DHT", "LiquidCrystal_I2C", "RFID", "IRRemote", "Keypad4x4", "StepperMotor", "OneWireBus", "LEDMatrixMAX7219", "FourDigitTM1637", "BluetoothSerial", "MPU6050Sensor", "GPSModule", "EthernetW5500", "WiFiESPAT", "EEPROM", "SPI", "Serial", "Wire",
+    "upload", "verify", "show_code", "LiveRun", "LiveStop",
+] + list(_device_packs.LOADED)