alpaca2-stubs 1.0.2__tar.gz

alpaca2_stubs-1.0.2/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: alpaca2-stubs
+Version: 1.0.2
+Summary: Stub files for ALPACA 2.0 for NB2420 Electronic Instrumentation course of TU Delft
+License-Expression: CC-BY-4.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+Stubs for # ALPACA 2.0
+
+> © Copyright Delft University of Technology, CC BY 4.0.
+
+**ALPACA (Advanced Learning Platform for Analog Circuits and Automation)** is a device built on RP2 and MicroPython and equipped with several digital tools to be a guide in introduction to digital systems and electronics for NB2420 Electronic Instrumentation course of TU Delft.
+
+ALPACA splits work across two Picos:
+
+- **Student Pico**: the board a student writes code on via Belay. It exposes a tiny RPC
+  client so student programs can ask the Helper to do things. Student Pico is equiiped with 
+  a double channel DAC.
+
+- **Helper**: a self-contained instrument. It drives an LCD and runs
+  a set of measurement screens (voltmeter, component/resistance tester) that
+  the user can cycles through. It also answers commands sent by the Student
+  over a UART link.
+
+A host-side CLI (`alpaca`) handles flashing your code onto the boards and
+opening a serial REPL, so you never have to manage USB ports by hand.
+
+
+The Student and Helper talk over UART0 with a crossover wiring and a shared
+ground:
+
+```
+  Student GP00 (TX) ──► Helper GP13 (RX)
+  Student GP01 (RX) ◄── Helper GP12 (TX)
+  GND ◄──────────────► GND
+```
+
+## Repository layout
+
+`📁 alpaca` folder contains the libraries for Picos.
+`📁 src/alpaca` contains the desktop-side library and the ALPACA CLI for
+managing the boards (`src/alpaca/cli`). It is published on PyPI as `alpaca2`,
+but the import name and the command stay `alpaca`, so installed users write
+`from alpaca import list_boards`.
+
+`alpaca/common` is copied alongside `alpaca/student` or `alpaca/helper` onto
+each board at sync time, which is why on-device imports are flat
+(`from command import ...`, `from link import ...`).
+
+Therefore if the folders are like this
+
+```
+📁 alpaca/
+  📁 common/
+    📄 A.py
+  📁 student/
+    📄 B.py
+  📁 helper/
+    📄 C.py
+```
+
+using `alpaca sync` will copy the files to the root as:
+
+```
+🍓 HelperPico
+  📄 A.py
+  📄 C.py
+
+🍓 StudentPico
+  📄 A.py
+  📄 B.py
+```
+
+## Setup
+
+```bash
+uv sync
+```
+
+This installs the project and exposes the `alpaca` command. Outside a
+checkout, install the published package instead:
+
+```bash
+pip install alpaca2   # or: uv tool install alpaca2
+```
+
+## Usage
+
+### Sync your code onto the boards
+
+```bash
+uv run alpaca sync
+```
+
+This discovers connected Picos, copies the `common` + `student`/`helper` code
+onto each, and soft-resets them. To drop into a REPL on one board right after
+syncing:
+
+```bash
+uv run alpaca sync --connect student
+```
+
+### Open a serial REPL
+
+```bash
+uv run alpaca connect student   # or: helper
+```
+
+### Picking a board
+
+The first time the CLI needs a board it lists the connected Picos in a terminal
+menu. Hovering an entry lights that board's onboard LED so you can tell
+which is which, and you can choose to remember the selection — it's cached per
+role under `.alpaca/` so later runs skip the prompt.
+
+## Building
+
+The repository workflow should build and publish stubs, and assemble firmware images on creation of a version tag.
+
+```sh
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+The MicroPython version for firmware is set inside the `build-firmware.yml` (currently 1.28.0).
+
+## MicroPython builtins
+
+These stubs cover ALPACA itself. For `machine`, `rp2` and the rest of
+the MicroPython standard library, install those stubs alongside:
+
+```bash
+conda install pip
+pip install micropython-rp2-stubs
+```
+
+They are not published on any conda channel, so they are not declared
+as a dependency here. Without them only the MicroPython builtins stay
+unresolved in your editor; the ALPACA stubs themselves work either way.

alpaca2_stubs-1.0.2/README.md

@@ -0,0 +1,132 @@
+Stubs for # ALPACA 2.0
+
+> © Copyright Delft University of Technology, CC BY 4.0.
+
+**ALPACA (Advanced Learning Platform for Analog Circuits and Automation)** is a device built on RP2 and MicroPython and equipped with several digital tools to be a guide in introduction to digital systems and electronics for NB2420 Electronic Instrumentation course of TU Delft.
+
+ALPACA splits work across two Picos:
+
+- **Student Pico**: the board a student writes code on via Belay. It exposes a tiny RPC
+  client so student programs can ask the Helper to do things. Student Pico is equiiped with 
+  a double channel DAC.
+
+- **Helper**: a self-contained instrument. It drives an LCD and runs
+  a set of measurement screens (voltmeter, component/resistance tester) that
+  the user can cycles through. It also answers commands sent by the Student
+  over a UART link.
+
+A host-side CLI (`alpaca`) handles flashing your code onto the boards and
+opening a serial REPL, so you never have to manage USB ports by hand.
+
+
+The Student and Helper talk over UART0 with a crossover wiring and a shared
+ground:
+
+```
+  Student GP00 (TX) ──► Helper GP13 (RX)
+  Student GP01 (RX) ◄── Helper GP12 (TX)
+  GND ◄──────────────► GND
+```
+
+## Repository layout
+
+`📁 alpaca` folder contains the libraries for Picos.
+`📁 src/alpaca` contains the desktop-side library and the ALPACA CLI for
+managing the boards (`src/alpaca/cli`). It is published on PyPI as `alpaca2`,
+but the import name and the command stay `alpaca`, so installed users write
+`from alpaca import list_boards`.
+
+`alpaca/common` is copied alongside `alpaca/student` or `alpaca/helper` onto
+each board at sync time, which is why on-device imports are flat
+(`from command import ...`, `from link import ...`).
+
+Therefore if the folders are like this
+
+```
+📁 alpaca/
+  📁 common/
+    📄 A.py
+  📁 student/
+    📄 B.py
+  📁 helper/
+    📄 C.py
+```
+
+using `alpaca sync` will copy the files to the root as:
+
+```
+🍓 HelperPico
+  📄 A.py
+  📄 C.py
+
+🍓 StudentPico
+  📄 A.py
+  📄 B.py
+```
+
+## Setup
+
+```bash
+uv sync
+```
+
+This installs the project and exposes the `alpaca` command. Outside a
+checkout, install the published package instead:
+
+```bash
+pip install alpaca2   # or: uv tool install alpaca2
+```
+
+## Usage
+
+### Sync your code onto the boards
+
+```bash
+uv run alpaca sync
+```
+
+This discovers connected Picos, copies the `common` + `student`/`helper` code
+onto each, and soft-resets them. To drop into a REPL on one board right after
+syncing:
+
+```bash
+uv run alpaca sync --connect student
+```
+
+### Open a serial REPL
+
+```bash
+uv run alpaca connect student   # or: helper
+```
+
+### Picking a board
+
+The first time the CLI needs a board it lists the connected Picos in a terminal
+menu. Hovering an entry lights that board's onboard LED so you can tell
+which is which, and you can choose to remember the selection — it's cached per
+role under `.alpaca/` so later runs skip the prompt.
+
+## Building
+
+The repository workflow should build and publish stubs, and assemble firmware images on creation of a version tag.
+
+```sh
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+The MicroPython version for firmware is set inside the `build-firmware.yml` (currently 1.28.0).
+
+## MicroPython builtins
+
+These stubs cover ALPACA itself. For `machine`, `rp2` and the rest of
+the MicroPython standard library, install those stubs alongside:
+
+```bash
+conda install pip
+pip install micropython-rp2-stubs
+```
+
+They are not published on any conda channel, so they are not declared
+as a dependency here. Without them only the MicroPython builtins stay
+unresolved in your editor; the ALPACA stubs themselves work either way.

alpaca2_stubs-1.0.2/alpaca2_stubs.egg-info/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: alpaca2-stubs
+Version: 1.0.2
+Summary: Stub files for ALPACA 2.0 for NB2420 Electronic Instrumentation course of TU Delft
+License-Expression: CC-BY-4.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+Stubs for # ALPACA 2.0
+
+> © Copyright Delft University of Technology, CC BY 4.0.
+
+**ALPACA (Advanced Learning Platform for Analog Circuits and Automation)** is a device built on RP2 and MicroPython and equipped with several digital tools to be a guide in introduction to digital systems and electronics for NB2420 Electronic Instrumentation course of TU Delft.
+
+ALPACA splits work across two Picos:
+
+- **Student Pico**: the board a student writes code on via Belay. It exposes a tiny RPC
+  client so student programs can ask the Helper to do things. Student Pico is equiiped with 
+  a double channel DAC.
+
+- **Helper**: a self-contained instrument. It drives an LCD and runs
+  a set of measurement screens (voltmeter, component/resistance tester) that
+  the user can cycles through. It also answers commands sent by the Student
+  over a UART link.
+
+A host-side CLI (`alpaca`) handles flashing your code onto the boards and
+opening a serial REPL, so you never have to manage USB ports by hand.
+
+
+The Student and Helper talk over UART0 with a crossover wiring and a shared
+ground:
+
+```
+  Student GP00 (TX) ──► Helper GP13 (RX)
+  Student GP01 (RX) ◄── Helper GP12 (TX)
+  GND ◄──────────────► GND
+```
+
+## Repository layout
+
+`📁 alpaca` folder contains the libraries for Picos.
+`📁 src/alpaca` contains the desktop-side library and the ALPACA CLI for
+managing the boards (`src/alpaca/cli`). It is published on PyPI as `alpaca2`,
+but the import name and the command stay `alpaca`, so installed users write
+`from alpaca import list_boards`.
+
+`alpaca/common` is copied alongside `alpaca/student` or `alpaca/helper` onto
+each board at sync time, which is why on-device imports are flat
+(`from command import ...`, `from link import ...`).
+
+Therefore if the folders are like this
+
+```
+📁 alpaca/
+  📁 common/
+    📄 A.py
+  📁 student/
+    📄 B.py
+  📁 helper/
+    📄 C.py
+```
+
+using `alpaca sync` will copy the files to the root as:
+
+```
+🍓 HelperPico
+  📄 A.py
+  📄 C.py
+
+🍓 StudentPico
+  📄 A.py
+  📄 B.py
+```
+
+## Setup
+
+```bash
+uv sync
+```
+
+This installs the project and exposes the `alpaca` command. Outside a
+checkout, install the published package instead:
+
+```bash
+pip install alpaca2   # or: uv tool install alpaca2
+```
+
+## Usage
+
+### Sync your code onto the boards
+
+```bash
+uv run alpaca sync
+```
+
+This discovers connected Picos, copies the `common` + `student`/`helper` code
+onto each, and soft-resets them. To drop into a REPL on one board right after
+syncing:
+
+```bash
+uv run alpaca sync --connect student
+```
+
+### Open a serial REPL
+
+```bash
+uv run alpaca connect student   # or: helper
+```
+
+### Picking a board
+
+The first time the CLI needs a board it lists the connected Picos in a terminal
+menu. Hovering an entry lights that board's onboard LED so you can tell
+which is which, and you can choose to remember the selection — it's cached per
+role under `.alpaca/` so later runs skip the prompt.
+
+## Building
+
+The repository workflow should build and publish stubs, and assemble firmware images on creation of a version tag.
+
+```sh
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+The MicroPython version for firmware is set inside the `build-firmware.yml` (currently 1.28.0).
+
+## MicroPython builtins
+
+These stubs cover ALPACA itself. For `machine`, `rp2` and the rest of
+the MicroPython standard library, install those stubs alongside:
+
+```bash
+conda install pip
+pip install micropython-rp2-stubs
+```
+
+They are not published on any conda channel, so they are not declared
+as a dependency here. Without them only the MicroPython builtins stay
+unresolved in your editor; the ALPACA stubs themselves work either way.

alpaca2_stubs-1.0.2/alpaca2_stubs.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+alpaca2_stubs.egg-info/PKG-INFO
+alpaca2_stubs.egg-info/SOURCES.txt
+alpaca2_stubs.egg-info/dependency_links.txt
+alpaca2_stubs.egg-info/top_level.txt
+command/__init__.pyi
+dac/__init__.pyi
+dac/driver.pyi
+helper/__init__.pyi
+link/__init__.pyi
+utime/__init__.pyi
+version/__init__.pyi

alpaca2_stubs-1.0.2/alpaca2_stubs.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

alpaca2_stubs-1.0.2/alpaca2_stubs.egg-info/top_level.txt

@@ -0,0 +1,6 @@
+command
+dac
+helper
+link
+utime
+version

alpaca2_stubs-1.0.2/command/__init__.pyi

@@ -0,0 +1,20 @@
+from _typeshed import Incomplete
+
+PING: Incomplete
+LCD_PUTSTR: Incomplete
+SET_PIN: Incomplete
+AWG_R2R_LOAD: Incomplete
+AWG_R2R_START: Incomplete
+AWG_R2R_STOP: Incomplete
+AWG_R2R_OFFSET: Incomplete
+AWG_R2R_GEN: Incomplete
+WAVE_SINE: Incomplete
+WAVE_BLOCK: Incomplete
+WAVE_TRIANGLE: Incomplete
+WAVE_SAWTOOTH: Incomplete
+COMMANDS: Incomplete
+
+def pack_args(fmt, values):
+    """Encode a tuple/list of values per a format string into bytes."""
+def unpack_args(fmt, buf):
+    """Decode bytes per a format string into a list of values."""

alpaca2_stubs-1.0.2/dac/__init__.pyi

@@ -0,0 +1,82 @@
+import _thread
+import micropython
+import types
+from _typeshed import Incomplete
+from collections.abc import Callable as Callable
+from dac.driver import MCP4922 as MCP4922
+from machine import Pin as Pin, SPI as SPI
+from typing import Literal
+from utime import sleep_us as sleep_us, ticks_ms as ticks_ms
+
+driver: Incomplete
+
+class DAC:
+    channel: Literal[0, 1]
+    gain: Literal[1, 2]
+    v_ref: Incomplete
+    def __init__(self, channel: Literal['A', 'B'], v_ref: Literal[3000, 2048] = 3000, gain: Literal[1, 2] = 1) -> None: ...
+    def write(self, val: float): ...
+    def generate(self, generator: Callable[[float], float], frequency_hz: int, N: int = 100): ...
+    @staticmethod
+    def sync(worker_1: DACWorker, worker_2: DACWorker, resample: bool = True) -> SyncedDACWorker:
+        """Drive two DAC channels simultaneously.
+
+    Takes two workers (as produced by ``DAC.generate``) that target
+    different channels and returns a single worker that interleaves both
+    signals over SPI, latching both outputs with one shared LDAC pulse so
+    the two channels update at exactly the same instant.
+
+    :param resample: when True (default), both AWG tables are regenerated
+      from their original functions at a shared sample count (the larger of
+      the two). When the two signals also share a sample period this lets the
+      worker drive both channels from a single index on one deadline, instead
+      of tracking each channel's deadline separately.
+
+    Usage::
+
+        worker_a = dac_a.generate(...)
+        worker_b = dac_b.generate(...)
+        with DAC.sync(worker_a, worker_b):
+          ...
+    """
+
+class DACWorker:
+    channel: Incomplete
+    dac: Incomplete
+    generator: Incomplete
+    frequency_hz: Incomplete
+    N: Incomplete
+    sample_period_us: Incomplete
+    awg_table: Incomplete
+    stop_flag_lock: Incomplete
+    def __init__(self, sample_period_us: int, awg_table: memoryview, channel: Literal[0, 1], dac: DAC, generator: Callable[[float], float], frequency_hz: int, N: int) -> None: ...
+    done: Incomplete
+    def __enter__(self): ...
+    def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: types.TracebackType | None) -> None: ...
+    @micropython.native
+    @staticmethod
+    def worker(sample_period_us: int, awg_table: memoryview, stop_flag_lock: _thread.LockType, done_lock: _thread.LockType, spi: SPI, cs: Pin, ldac: Pin): ...
+
+class SyncedDACWorker:
+    """Drives two channels from a single worker thread.
+
+  Both signals share one worker loop so their outputs are latched together
+  with one LDAC pulse. Each channel keeps its own sample period, so signals
+  of different frequencies stay phase-aligned while still updating in lockstep
+  whenever their deadlines coincide.
+  """
+    sample_period_1: Incomplete
+    awg_table_1: Incomplete
+    sample_period_2: Incomplete
+    awg_table_2: Incomplete
+    stop_flag_lock: Incomplete
+    def __init__(self, worker_1: DACWorker, worker_2: DACWorker) -> None: ...
+    done: Incomplete
+    def __enter__(self): ...
+    def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: types.TracebackType | None) -> None: ...
+    @micropython.native
+    @staticmethod
+    def worker_locked(period: int, awg_table_1: memoryview, awg_table_2: memoryview, stop_flag_lock: _thread.LockType, done_lock: _thread.LockType, spi: SPI, cs: Pin, ldac: Pin): ...
+    @micropython.native
+    @staticmethod
+    def worker(period_1: int, awg_table_1: memoryview, period_2: int, awg_table_2: memoryview, stop_flag_lock: _thread.LockType, done_lock: _thread.LockType, spi: SPI, cs: Pin, ldac: Pin): ...

alpaca2_stubs-1.0.2/dac/driver.pyi

@@ -0,0 +1,36 @@
+import micropython
+from _typeshed import Incomplete
+from typing import Literal
+
+DAC_12_BIT_LIMIT: Incomplete
+
+class MCP4922:
+    """
+    MCP4922 is a Digital to Analog Converter
+
+    It operates over SP and has two channels.
+
+    The 16-bit data is sent over TX (MOSI) Pin and 4-bit is reserved
+    for config (see MCP4922.write). The data for indiviual channels
+    is kept in the input register.
+
+    Setting LDAC to low moves inputs from input register to output
+    register, which allows both channels to be operated simeltanously.
+  """
+    spi: Incomplete
+    cs: Incomplete
+    ldac: Incomplete
+    def __init__(self) -> None: ...
+    @micropython.native
+    def write(self, value: int, channel: Literal[0, 1] = 0, buffered: bool = False, gain: Literal[1, 2] = 1) -> bool:
+        """Write a 12-bit value to DAC
+    :param channel: 0 for DAC A, 1 for DAC B.
+    :param value: Integer from 0 to 4095.
+    :param buffered: True to use VREF buffer, False for unbuffered.
+    :param gain: 1x or 2x output gain
+
+    :returns: whether the data was actually sent to DAC
+    """
+    @micropython.native
+    def push(self) -> None:
+        """Move input register to output"""

alpaca2_stubs-1.0.2/helper/__init__.pyi

@@ -0,0 +1,40 @@
+import types
+from _typeshed import Incomplete
+
+link: Incomplete
+
+def ping(): ...
+def set_screen_text(text_up: str = '', text_down: str = ''): ...
+def awg_r2r(samples, sample_rate_hz):
+    """Play a waveform on the Helper's R-2R ladder DAC (GPIO0-9).
+
+    samples: iterable of 10-bit codes (0-1023, values are masked), looped
+    forever. sample_rate_hz: requested playback rate; returns the actual
+    rate achieved, which is lower if the requested rate is too fast.
+    """
+def awg_r2r_stop():
+    """Stop the AWG and drive the ladder to 0."""
+def awg_r2r_offset(magnitude, negative: bool = False):
+    """Set the analog offset stage: magnitude 0.0-1.0 (PWM duty on
+    OFFSET_PWM), negative selects the sign via OFFSET_POL."""
+
+class _Waveform:
+    """A shortcut waveform the Helper synthesizes itself: playing it sends one
+    small payload instead of loading samples over the wire. Use it as a context
+    manager so the AWG stops on exit, or drive it with .start()/.stop()."""
+    frequency_hz: Incomplete
+    def __init__(self, waveform, frequency_hz, amplitude_vpp, duty_cycle) -> None: ...
+    def start(self): ...
+    def stop(self): ...
+    def __enter__(self): ...
+    def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: types.TracebackType | None): ...
+
+class FunctionGenerator:
+    """Shortcut waveforms on the Helper's R-2R ladder DAC (GPIO0-9). Amplitudes
+    are volts peak-to-peak around mid-rail, clipped to the ladder's 0-3.3V."""
+    def sine(self, frequency_hz, amplitude_vpp): ...
+    def block(self, frequency_hz, amplitude_vpp, duty_cycle: float = 0.5): ...
+    def triangle(self, frequency_hz, amplitude_vpp): ...
+    def sawtooth(self, frequency_hz, amplitude_vpp): ...
+
+function_generator: Incomplete

alpaca2_stubs-1.0.2/link/__init__.pyi

@@ -0,0 +1,21 @@
+import micropython
+from _typeshed import Incomplete
+
+OK: Incomplete
+ERR: Incomplete
+
+class Link:
+    uart: Incomplete
+    timeout_ms: Incomplete
+    handlers: Incomplete
+    event_loop: Incomplete
+    event_times: Incomplete
+    def __init__(self, uart, timeout_ms: int = 1000) -> None: ...
+    @micropython.native
+    def call(self, opcode, *args):
+        """Send a request and block for the reply. Returns the decoded
+        result or raises RuntimeError on an ERR reply."""
+    def register(self, opcode): ...
+    def event(self, func): ...
+    @micropython.native
+    def serve(self) -> None: ...

alpaca2_stubs-1.0.2/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "alpaca2-stubs"
+version = "1.0.2"
+description = "Stub files for ALPACA 2.0 for NB2420 Electronic Instrumentation course of TU Delft"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "CC-BY-4.0"
+
+[build-system]
+requires = [ "setuptools>=61",]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = [ "link", "helper", "version", "command", "dac", "utime",]
+
+[tool.conda-recipe]
+noarch = true
+build-channels = [ "conda-forge",]
+maintainers = [ "NB-TUDelft",]
+test-imports = []
+
+[tool.setuptools.package-data]
+link = [ "*.pyi",]
+helper = [ "*.pyi",]
+version = [ "*.pyi",]
+command = [ "*.pyi",]
+dac = [ "*.pyi",]
+utime = [ "*.pyi",]

alpaca2_stubs-1.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

alpaca2_stubs-1.0.2/utime/__init__.pyi

@@ -0,0 +1,11 @@
+from typing import Any
+
+def sleep(seconds: float) -> None: ...
+def sleep_ms(ms: int) -> None: ...
+def sleep_us(us: int) -> None: ...
+
+# Include any other native time elements you use so they don't break
+def ticks_ms() -> int: ...
+def ticks_diff(ticks1: int, ticks2: int) -> int: ...
+def ticks_add(ticks1: int, ticks2: int) -> int: ...
+def ticks_us() -> int: ...

alpaca2_stubs-1.0.2/version/__init__.pyi

@@ -0,0 +1 @@
+ALPACA_FW_VER: str