pulsemaker-simulator 1.0.0__py3-none-any.whl

pulsemaker/__init__.py

@@ -0,0 +1,47 @@
+"""
+PulseMaker Simulator - Python & MicroPython Runtime
+DBE CAPS Coding & Robotics Platform
+"""
+import sys
+import time
+import builtins
+
+from .display import display, Display
+from .icons import Icon, IconImage
+from .music import music, Music
+from .pins import pin0, pin1, pin2, Pin
+from .buttons import button_a, button_b, Button
+from .sensors import sensors, Sensors
+from .rover import Rover
+
+# 1. MicroPython Compatibility Shim:
+# MicroPython provides time.sleep_ms(ms), whereas standard CPython only provides time.sleep(seconds).
+# We dynamically attach sleep_ms to the time module so standard Python scripts run without error.
+if not hasattr(time, "sleep_ms"):
+    time.sleep_ms = lambda ms: time.sleep(ms / 1000.0)  # type: ignore
+
+# 2. Inject Icon into Python builtins as a safety fallback
+# so transpiled code using Icon.SUN works even if 'Icon' was omitted from the import line.
+if not hasattr(builtins, "Icon"):
+    setattr(builtins, "Icon", Icon)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "display",
+    "Display",
+    "Icon",
+    "IconImage",
+    "music",
+    "Music",
+    "pin0",
+    "pin1",
+    "pin2",
+    "Pin",
+    "button_a",
+    "button_b",
+    "Button",
+    "sensors",
+    "Sensors",
+    "Rover",
+]

pulsemaker/buttons.py

@@ -0,0 +1,31 @@
+"""
+PulseMaker Push Buttons A & B
+"""
+import os
+
+class Button:
+    def __init__(self, name: str):
+        self.name = name
+        self._pressed = False
+
+    def is_pressed(self) -> bool:
+        """
+        Check if the button is currently pressed.
+        Can be influenced by environment variables PULSEMAKER_BUTTON_A=1 / PULSEMAKER_BUTTON_B=1.
+        """
+        env_val = os.environ.get(f"PULSEMAKER_BUTTON_{self.name.upper()}", "")
+        if env_val in ("1", "true", "True"):
+            return True
+        return self._pressed
+
+    def set_pressed(self, pressed: bool = True) -> None:
+        """
+        Simulate pressing or releasing this button.
+        """
+        self._pressed = bool(pressed)
+
+    def __repr__(self) -> str:
+        return f"<Button {self.name}: {'PRESSED' if self.is_pressed() else 'RELEASED'}>"
+
+button_a = Button("A")
+button_b = Button("B")

pulsemaker/cli.py

@@ -0,0 +1,35 @@
+"""
+PulseMaker CLI Utility
+"""
+import sys
+import runpy
+from pulsemaker import __version__, display, Icon, music
+
+def main():
+    if len(sys.argv) > 1:
+        cmd = sys.argv[1]
+        if cmd in ("-v", "--version"):
+            print(f"pulsemaker version {__version__}")
+            return
+        elif cmd in ("-h", "--help"):
+            print("PulseMaker Python Simulator CLI")
+            print("Usage:")
+            print("  pulsemaker run <script.py>   Run a PulseMaker script")
+            print("  pulsemaker demo              Run a built-in hardware demo")
+            return
+        elif cmd == "run" and len(sys.argv) > 2:
+            filepath = sys.argv[2]
+            print(f"Running PulseMaker script: {filepath}")
+            runpy.run_path(filepath, run_name="__main__")
+            return
+        elif cmd == "demo":
+            print("=== PulseMaker Demo ===")
+            display.show(Icon.SUN)
+            music.pitch(880, 250)
+            return
+
+    print(f"PulseMaker Python Runtime v{__version__} is ready.")
+    print("Run with '--help' for options.")
+
+if __name__ == "__main__":
+    main()

pulsemaker/display.py

@@ -0,0 +1,99 @@
+"""
+PulseMaker 5x5 LED Matrix Display Controller
+"""
+import sys
+from typing import Union, List
+from .icons import IconImage
+
+class Display:
+    def __init__(self):
+        self._matrix: List[List[int]] = [[0 for _ in range(5)] for _ in range(5)]
+        self._supports_color = hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+        encoding = getattr(sys.stdout, "encoding", "utf-8") or "utf-8"
+        self._is_utf8 = "utf" in encoding.lower()
+
+    def show(self, image: Union[IconImage, List[List[int]], str]) -> None:
+        """
+        Display an icon preset or a 5x5 brightness matrix (0-255).
+        """
+        if isinstance(image, IconImage):
+            self._matrix = [row[:] for row in image.matrix]
+            name = image.name
+        elif isinstance(image, list):
+            self._matrix = [row[:] for row in image]
+            name = "CUSTOM"
+        else:
+            name = str(image)
+
+        self._render(header=f"Icon.{name}")
+
+    def clear(self) -> None:
+        """
+        Turn off all 25 LEDs on the matrix.
+        """
+        self._matrix = [[0 for _ in range(5)] for _ in range(5)]
+        self._render(header="CLEARED")
+
+    def set_pixel(self, x: int, y: int, brightness: int = 255) -> None:
+        """
+        Set brightness of a single pixel (x: 0-4, y: 0-4, brightness: 0-255).
+        """
+        if 0 <= x < 5 and 0 <= y < 5:
+            self._matrix[y][x] = max(0, min(255, brightness))
+            self._render(header=f"pixel({x}, {y}) = {brightness}")
+
+    def _render(self, header: str = "") -> None:
+        """
+        Render 5x5 LED matrix in the terminal safely across Windows (cp1252/utf-8) and Linux/macOS.
+        """
+        use_unicode = self._is_utf8
+        
+        # Characters for ON, MEDIUM, OFF
+        if use_unicode:
+            on_char = "■ "
+            med_char = "▫ "
+            off_char = "· "
+            t_left, t_right = "┌", "┐"
+            b_left, b_right = "└", "┘"
+            h_bar, v_bar = "─", "│"
+        else:
+            # Safe ASCII fallback for Windows cp1252 / legacy CMD
+            on_char = "# "
+            med_char = "* "
+            off_char = ". "
+            t_left, t_right = "+", "+"
+            b_left, b_right = "+", "+"
+            h_bar, v_bar = "-", "|"
+
+        title = f"[ PulseBit 5x5: {header} ]"
+        total_width = 32
+        left_pad = (total_width - len(title) - 2) // 2
+        right_pad = total_width - len(title) - 2 - left_pad
+
+        border_top = t_left + (h_bar * max(1, left_pad)) + title + (h_bar * max(1, right_pad)) + t_right
+        border_bot = b_left + (h_bar * (len(border_top) - 2)) + b_right
+
+        lines = [border_top]
+        for y in range(5):
+            row_chars = []
+            for x in range(5):
+                b = self._matrix[y][x]
+                if b > 150:
+                    char = f"\033[91m{on_char}\033[0m" if self._supports_color else on_char
+                elif b > 0:
+                    char = f"\033[33m{med_char}\033[0m" if self._supports_color else med_char
+                else:
+                    char = f"\033[90m{off_char}\033[0m" if self._supports_color else off_char
+                row_chars.append(char)
+            lines.append(f"{v_bar}        {''.join(row_chars)}     {v_bar}")
+        lines.append(border_bot)
+
+        output = "\n" + "\n".join(lines) + "\n"
+        try:
+            print(output, flush=True)
+        except UnicodeEncodeError:
+            # Emergency ASCII fallback
+            safe_output = output.encode("ascii", "replace").decode("ascii")
+            print(safe_output, flush=True)
+
+display = Display()

pulsemaker/icons.py

@@ -0,0 +1,65 @@
+"""
+PulseMaker 5x5 LED Matrix Icon Presets
+"""
+from typing import List
+
+class IconImage:
+    def __init__(self, name: str, matrix: List[List[int]]):
+        self.name = name
+        self.matrix = matrix
+
+    def __repr__(self) -> str:
+        return f"<Icon.{self.name}>"
+
+class _IconMeta(type):
+    def __getattr__(cls, name: str):
+        raise AttributeError(f"Icon '{name}' does not exist on PulseMaker Icon set.")
+
+class Icon(metaclass=_IconMeta):
+    HEART = IconImage("HEART", [
+        [0, 255, 0, 255, 0],
+        [255, 255, 255, 255, 255],
+        [255, 255, 255, 255, 255],
+        [0, 255, 255, 255, 0],
+        [0, 0, 255, 0, 0],
+    ])
+
+    SMILE = IconImage("SMILE", [
+        [0, 255, 0, 255, 0],
+        [0, 255, 0, 255, 0],
+        [0, 0, 0, 0, 0],
+        [255, 0, 0, 0, 255],
+        [0, 255, 255, 255, 0],
+    ])
+
+    SAD = IconImage("SAD", [
+        [0, 255, 0, 255, 0],
+        [0, 0, 0, 0, 0],
+        [0, 255, 255, 255, 0],
+        [255, 0, 0, 0, 255],
+        [0, 0, 0, 0, 0],
+    ])
+
+    SUN = IconImage("SUN", [
+        [255, 0, 255, 0, 255],
+        [0, 255, 255, 255, 0],
+        [255, 255, 255, 255, 255],
+        [0, 255, 255, 255, 0],
+        [255, 0, 255, 0, 255],
+    ])
+
+    ARROW_N = IconImage("ARROW_N", [
+        [0, 0, 255, 0, 0],
+        [0, 255, 255, 255, 0],
+        [255, 0, 255, 0, 255],
+        [0, 0, 255, 0, 0],
+        [0, 0, 255, 0, 0],
+    ])
+
+    CHECK = IconImage("CHECK", [
+        [0, 0, 0, 0, 255],
+        [0, 0, 0, 255, 0],
+        [255, 0, 255, 0, 0],
+        [0, 255, 0, 0, 0],
+        [0, 0, 0, 0, 0],
+    ])

pulsemaker/music.py

@@ -0,0 +1,38 @@
+"""
+PulseMaker Piezo Buzzer Sound Synthesizer
+"""
+import sys
+import time
+
+class Music:
+    def __init__(self):
+        self._winsound = None
+        if sys.platform == "win32":
+            try:
+                import winsound
+                self._winsound = winsound
+            except ImportError:
+                self._winsound = None
+
+    def pitch(self, frequency: int, duration: int = 300) -> None:
+        """
+        Play a musical frequency (Hz) for a duration (milliseconds).
+        """
+        freq = int(max(37, min(32767, frequency)))
+        dur_ms = int(max(10, duration))
+
+        played = False
+        if self._winsound:
+            try:
+                # Windows hardware/driver beep
+                self._winsound.Beep(freq, dur_ms)
+                played = True
+            except Exception:
+                played = False
+
+        if not played:
+            # Fallback for systems without hardware beep
+            print(f"[PulseMaker Buzzer ♫ {freq} Hz for {dur_ms} ms]", flush=True)
+            time.sleep(dur_ms / 1000.0)
+
+music = Music()

pulsemaker/pins.py

@@ -0,0 +1,29 @@
+"""
+PulseMaker GPIO Edge Connector Pins (P0, P1, P2)
+"""
+
+class Pin:
+    def __init__(self, name: str):
+        self.name = name
+        self.value = 0
+
+    def write_digital(self, value: int) -> None:
+        """
+        Write digital state (1 for HIGH, 0 for LOW).
+        """
+        self.value = 1 if value else 0
+        state_str = "HIGH (1)" if self.value else "LOW (0)"
+        print(f"[PulseMaker Pin {self.name} -> {state_str}]", flush=True)
+
+    def read_digital(self) -> int:
+        """
+        Read current digital state (0 or 1).
+        """
+        return self.value
+
+    def __repr__(self) -> str:
+        return f"<Pin {self.name}: {self.value}>"
+
+pin0 = Pin("P0")
+pin1 = Pin("P1")
+pin2 = Pin("P2")

pulsemaker/rover.py

@@ -0,0 +1,57 @@
+"""
+PulseMaker 2D Autonomous Rover Controller (Grade 7 Senior Phase)
+"""
+import os
+import random
+
+class UltrasonicSensor:
+    def __init__(self, initial_dist: int = 120):
+        self._distance = initial_dist
+
+    def distance_cm(self) -> int:
+        """
+        Return simulated ultrasonic distance in cm.
+        Can be overridden via PULSEMAKER_ROVER_DISTANCE=45.
+        """
+        env_val = os.environ.get("PULSEMAKER_ROVER_DISTANCE")
+        if env_val:
+            try:
+                return int(env_val)
+            except ValueError:
+                pass
+        return self._distance
+
+    def set_distance(self, distance_cm: int) -> None:
+        self._distance = int(distance_cm)
+
+class Rover:
+    def __init__(self):
+        self.v_left = 0
+        self.v_right = 0
+        self.ultrasonic = UltrasonicSensor(initial_dist=45)
+        self._left_line = False
+        self._right_line = False
+
+    def motors(self, v_left: int, v_right: int) -> None:
+        """
+        Set left and right motor velocities (-100 to 100).
+        """
+        self.v_left = max(-100, min(100, int(v_left)))
+        self.v_right = max(-100, min(100, int(v_right)))
+        print(f"[Rover Motors: v_left={self.v_left}%, v_right={self.v_right}%]", flush=True)
+
+    def line_sensor_left(self) -> bool:
+        """
+        Return True if left optical sensor detects line.
+        """
+        return self._left_line
+
+    def line_sensor_right(self) -> bool:
+        """
+        Return True if right optical sensor detects line.
+        """
+        return self._right_line
+
+    def set_line_sensors(self, left: bool, right: bool) -> None:
+        self._left_line = bool(left)
+        self._right_line = bool(right)

pulsemaker/sensors.py

@@ -0,0 +1,49 @@
+"""
+PulseMaker Virtual Environment Sensors
+"""
+import os
+
+class Sensors:
+    def __init__(self):
+        self._temp = 32.0  # Default 32°C so heatwave alarms trigger predictably in tests
+        self._light = 180  # Default 180 (0-255)
+
+    def temperature(self) -> float:
+        """
+        Get live simulated ambient temperature in °C.
+        Can be overridden via environment variable PULSEMAKER_TEMP=35.
+        """
+        env_val = os.environ.get("PULSEMAKER_TEMP")
+        if env_val:
+            try:
+                return float(env_val)
+            except ValueError:
+                pass
+        return self._temp
+
+    def light_level(self) -> int:
+        """
+        Get live simulated light level (0-255).
+        Can be overridden via environment variable PULSEMAKER_LIGHT=200.
+        """
+        env_val = os.environ.get("PULSEMAKER_LIGHT")
+        if env_val:
+            try:
+                return int(env_val)
+            except ValueError:
+                pass
+        return self._light
+
+    def set_temperature(self, degrees_celsius: float) -> None:
+        """
+        Set simulated ambient temperature.
+        """
+        self._temp = float(degrees_celsius)
+
+    def set_light_level(self, level: int) -> None:
+        """
+        Set simulated light level (0 to 255).
+        """
+        self._light = max(0, min(255, int(level)))
+
+sensors = Sensors()

pulsemaker_rover/__init__.py

@@ -0,0 +1,6 @@
+"""
+PulseMaker Rover Module
+"""
+from pulsemaker.rover import Rover, UltrasonicSensor
+
+__all__ = ["Rover", "UltrasonicSensor"]

pulsemaker_simulator-1.0.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: pulsemaker-simulator
+Version: 1.0.0
+Summary: Python and MicroPython runtime library for PulseMaker Simulator (DBE CAPS Coding & Robotics)
+Author: PulseMaker Simulator Team
+License: MIT
+Keywords: robotics,simulator,micropython,education,stem,caps
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# PulseMaker Python Library
+
+The official Python / MicroPython companion library for the **PulseMaker Simulator** (DBE CAPS Coding & Robotics curriculum for South African schools, Grades R–7).
+
+This library allows code generated or written in the PulseMaker browser simulator to run on any computer or MicroPython microcontroller without modifications.
+
+---
+
+## Installation
+
+Install via pip:
+
+```bash
+pip install pulsemaker-simulator
+```
+
+Or install locally in editable mode:
+
+```bash
+# From the project root
+pip install -e ./python
+```
+
+---
+
+## Quick Example (Intermediate Phase 5x5 Board)
+
+```python
+from pulsemaker import display, music, pin0, pin1, pin2, button_a, button_b, sensors, Icon
+import time
+
+# Check simulated environment sensors
+if sensors.temperature() > 30:
+    display.show(Icon.SUN)
+    music.pitch(880, duration=300)
+    print("Heatwave Alert! Temp > 30C")
+else:
+    display.show(Icon.SMILE)
+    print("Temperature Normal")
+
+# Wait and clear
+time.sleep_ms(1000)
+display.clear()
+```
+
+---
+
+## Senior Phase Example (2D Autonomous Rover)
+
+```python
+from pulsemaker_rover import Rover
+import time
+
+rover = Rover()
+
+for _ in range(10):
+    dist = rover.ultrasonic.distance_cm()
+    print(f"Ultrasonic distance: {dist} cm")
+
+    if dist < 65:
+        # Avoid obstacle: spin right
+        rover.motors(v_left=65, v_right=-65)
+    else:
+        # Drive forward
+        rover.motors(v_left=70, v_right=70)
+
+    time.sleep_ms(200)
+```
+
+---
+
+## Features
+
+- **5x5 LED Matrix Display**: Visual terminal rendering with ANSI color highlighting (`display.show`, `display.set_pixel`, `display.clear`).
+- **Icons**: Pre-packaged icons including `Icon.HEART`, `Icon.SMILE`, `Icon.SAD`, `Icon.SUN`, `Icon.ARROW_N`, and `Icon.CHECK`.
+- **Piezo Sound Synthesizer**: Native audio via PC speaker / `winsound` on Windows and terminal fallbacks on macOS/Linux.
+- **Sensors & Pins**: Virtual inputs for Temperature, Light Level, Push Buttons A & B, and Edge Pins P0, P1, P2.
+- **MicroPython Compatibility**: Automatically injects `time.sleep_ms()` into Python's built-in `time` module so MicroPython scripts run unmodified in standard CPython.
+- **2D Rover Kinematics**: Complete differential drive robotics model with raycasting and line sensors (`pulsemaker_rover.Rover`).

pulsemaker_simulator-1.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+pulsemaker/__init__.py,sha256=deStSNhH0NGk5xUEqUEoYdtCctIhq4k4Xhdvz-zNLN8,1215
+pulsemaker/buttons.py,sha256=Q6xCsttxec1h3uA3bVd4yZ8eX2PgdCHOvCedW-EMSN8,877
+pulsemaker/cli.py,sha256=71AlRtojCGvRwGlbHxj9077swAQQ9N3xn4Er2wywQ7o,1116
+pulsemaker/display.py,sha256=wLZPtSe6QMTlTgKorGt9YUMVEQ1A_0ytQC4ESrY4eIY,3617
+pulsemaker/icons.py,sha256=CPR7FoyupvWChNM8PKuyT4_hQpQBV-64d6p4lpSocUE,1570
+pulsemaker/music.py,sha256=zHO_-8E54cy1KNl2_CGrKmc3h7wjE_YsdlGJ2k3TJz8,1067
+pulsemaker/pins.py,sha256=BGNgwLzwF5_ZNpjIq-Z9fKe5JvAvE48CwKFLHLTev4c,717
+pulsemaker/rover.py,sha256=0TVwMAMlA-sWin3MThLFYxHbLOD1BE33DZHO1C6sRIE,1703
+pulsemaker/sensors.py,sha256=PMkx1vtQlS58ACID2CT37hK7aaGQTFV57_Jh1w6v3Ng,1383
+pulsemaker_rover/__init__.py,sha256=WIO-7YcV2vEHV8kLv7BXlMeVHgwyjbGLndSfDDoUF7w,126
+pulsemaker_simulator-1.0.0.dist-info/METADATA,sha256=6wKAWGsujxa2d_vyaOGZ5WATVPjavxi2O2w4Ks_19ic,2829
+pulsemaker_simulator-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pulsemaker_simulator-1.0.0.dist-info/entry_points.txt,sha256=bjlgk01uUMQ32ahbEtZsNlHi4s2gwuFodM7GwZKVgmk,51
+pulsemaker_simulator-1.0.0.dist-info/top_level.txt,sha256=GCr7j4RP4GDrbmAgEJG9ZjQJEhkqrv9cLNgrzP0tF1s,28
+pulsemaker_simulator-1.0.0.dist-info/RECORD,,

pulsemaker_simulator-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pulsemaker_simulator-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pulsemaker = pulsemaker.cli:main

pulsemaker_simulator-1.0.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+pulsemaker
+pulsemaker_rover