simantic 0.2.0__tar.gz → 0.3.0__tar.gz

simantic-0.3.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.5
+Name: simantic
+Version: 0.3.0
+Summary: Python SDK and pytest plugin for the Simantic circuit and firmware simulators
+Project-URL: Homepage, https://simantic.dev
+Project-URL: Source, https://github.com/simantic-dev/simantic-py
+Project-URL: Issues, https://github.com/simantic-dev/simantic-py/issues
+Author: Simantic
+License-Expression: MIT
+License-File: LICENSE
+Keywords: circuit,eda,firmware,kicad,pytest,simulation,spice
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.11
+Requires-Dist: pythonnet>=3.0.5
+Requires-Dist: pyyaml>=6
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://simantic.dev/simantic_logo_4_full_transparent.png" alt="Simantic" width="340">
+</p>
+
+<h3 align="center">Test your firmware without a board.</h3>
+
+<p align="center">
+  <a href="https://pypi.org/project/simantic/"><img src="https://img.shields.io/pypi/v/simantic.svg" alt="PyPI"></a>
+  <img src="https://img.shields.io/pypi/pyversions/simantic.svg" alt="Python versions">
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT licence">
+</p>
+
+Nothing to plug in, nothing to flash. Simantic boots your real ELF on a
+simulated microcontroller and hands you the whole machine from Python. Watch it
+print, press a button, read a variable straight out of RAM.
+
+```bash
+pip install simantic
+```
+
+```python
+from simantic import Sim
+
+with Sim(elf="fw.elf", mcu="STM32F401RE", uart="usart2") as sim:
+    sim.expect("ready")
+    sim.inject_gpio("gpioc", 13, True)      # press the user button
+    sim.expect("button pressed")
+    assert sim.read_u32("press_count") == 1
+```
+
+That is a whole test. No probe, no breakpoint, no waiting on hardware.
+
+Three things you get that a bench cannot give you:
+
+* **See inside.** Read any variable, register, or RTOS thread while the
+  firmware runs, without halting it.
+* **Poke it.** Press buttons, send CAN frames, feed the radio, all from your
+  script.
+* **Repeat exactly.** Time moves only when you ask, so a run comes out the same
+  every time, on your laptop and in CI.
+
+The simulator lives inside your Python process, so there is no server to start
+and no port to talk to.
+
+> **Alpha, version 0.3.x.** We are still moving things around, so the API can
+> change without a deprecation period. Pin an exact version
+> (`simantic==0.3.0`) if you depend on it, and please hold off on production
+> pipelines for now. Tell us what breaks.
+
+## Setup
+
+`pip install` is the whole setup. The first `Sim(...)` downloads the engine it
+needs into `~/.simantic/` and checks it against the published checksum. The
+wheel on PyPI holds only Python code; the simulators are never inside it.
+
+Sign in once if you want to name MCUs by part number:
+
+```bash
+simantic auth
+```
+
+That opens a browser tab, much like `gh auth login`, and saves a token to
+`~/.sim_id`. In CI, pipe one in instead: `echo $TOKEN | simantic auth`. If you
+bring your own platform file (`repl="board.repl"`), you need no account at all.
+
+Already have the `sim` binary? Put it on PATH or point `$SIMANTIC_SIM` at it.
+`simantic status` shows what resolved.
+
+## Pick your engine
+
+The same script runs on either engine. You choose per simulation:
+
+```python
+Sim(elf="fw.elf", mcu="STM32F401RE", uart="usart2")                  # Renode engine, the default
+Sim(elf="fw.elf", mcu="STM32F401RE", uart="usart2", backend="rust")  # our Rust engine
+```
+
+The Rust engine is a small extension module, runs one machine, and is
+considerably faster. Anything it cannot do yet, such as multi machine scenarios
+or CAN and radio injection, raises `simantic.NotSupported` and names the gap
+instead of quietly doing nothing. You can follow what each engine covers in
+[simantic-core#183](https://github.com/simantic-dev/simantic-core/issues/183).
+
+## Testing with pytest
+
+Take the `sim` fixture and write ordinary tests:
+
+```python
+def test_timer_irq_fires(sim):
+    s = sim(elf="fw.elf", mcu="STM32F401RE", uart="usart2")
+    s.expect("fired=1", timeout=8)
+    assert s.read_u32("fired") == 1
+```
+
+The engine starts once per worker rather than once per test, and every machine
+is closed for you. When a test fails, its UART transcript is attached to the
+report, because that is usually the evidence you want.
+
+`--sim-backend=renode|rust|both` chooses the engine. With `both`, each test runs
+on each and the engine name appears in the test id. Anything an engine cannot do
+is reported as a skip with the reason, so one suite can target both and stay
+honest about what each covers.
+
+One tip worth real time: on the Renode engine, every hand off between Python and
+the simulation costs a few hundred microseconds. Reading is free, pausing and
+resuming is not. Prefer `expect()`, which crosses once, over a loop that polls
+every millisecond. On the Rust engine, polling is essentially free.
+
+If you keep `test.yaml` fixture manifests, installing the package also turns
+each one into its own pytest item, so you get `-k` filtering, `--junitxml`, and
+xdist for free. Multi machine manifests need the `--scenario` runner and report
+as skips for now.
+
+For a single run with no assertions in the middle, there is `run_firmware(...)`:
+
+```python
+run = simantic.run_firmware("build/zephyr.elf", mcu="STM32F401RE",
+                            expect=["RESULT: PASS"])
+assert run.passed, run.failure_report()
+```
+
+## Telemetry
+
+When you are signed in, we count the shape of a pytest session (how many tests
+ran, passed, failed, skipped) and which SDK calls you make, by name only. It is
+one request per pytest run, buffered in `~/.simantic/usage.jsonl`, and uploaded
+at most hourly, so nothing ever waits on the network.
+
+We do not send file paths, project names, test names, firmware, or simulation
+output. Those are yours. Turn it off whenever you like:
+
+```bash
+export SIMANTIC_TELEMETRY=0     # or DO_NOT_TRACK=1
+```
+
+## Questions
+
+We would genuinely like to hear how this goes for you, especially if something
+is confusing or broken. Write to **founder@simantic.dev**, or open an issue.
+
+## License
+
+MIT. The simulators it drives are separate software under their own terms.

simantic-0.3.0/README.md

@@ -0,0 +1,143 @@
+<p align="center">
+  <img src="https://simantic.dev/simantic_logo_4_full_transparent.png" alt="Simantic" width="340">
+</p>
+
+<h3 align="center">Test your firmware without a board.</h3>
+
+<p align="center">
+  <a href="https://pypi.org/project/simantic/"><img src="https://img.shields.io/pypi/v/simantic.svg" alt="PyPI"></a>
+  <img src="https://img.shields.io/pypi/pyversions/simantic.svg" alt="Python versions">
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT licence">
+</p>
+
+Nothing to plug in, nothing to flash. Simantic boots your real ELF on a
+simulated microcontroller and hands you the whole machine from Python. Watch it
+print, press a button, read a variable straight out of RAM.
+
+```bash
+pip install simantic
+```
+
+```python
+from simantic import Sim
+
+with Sim(elf="fw.elf", mcu="STM32F401RE", uart="usart2") as sim:
+    sim.expect("ready")
+    sim.inject_gpio("gpioc", 13, True)      # press the user button
+    sim.expect("button pressed")
+    assert sim.read_u32("press_count") == 1
+```
+
+That is a whole test. No probe, no breakpoint, no waiting on hardware.
+
+Three things you get that a bench cannot give you:
+
+* **See inside.** Read any variable, register, or RTOS thread while the
+  firmware runs, without halting it.
+* **Poke it.** Press buttons, send CAN frames, feed the radio, all from your
+  script.
+* **Repeat exactly.** Time moves only when you ask, so a run comes out the same
+  every time, on your laptop and in CI.
+
+The simulator lives inside your Python process, so there is no server to start
+and no port to talk to.
+
+> **Alpha, version 0.3.x.** We are still moving things around, so the API can
+> change without a deprecation period. Pin an exact version
+> (`simantic==0.3.0`) if you depend on it, and please hold off on production
+> pipelines for now. Tell us what breaks.
+
+## Setup
+
+`pip install` is the whole setup. The first `Sim(...)` downloads the engine it
+needs into `~/.simantic/` and checks it against the published checksum. The
+wheel on PyPI holds only Python code; the simulators are never inside it.
+
+Sign in once if you want to name MCUs by part number:
+
+```bash
+simantic auth
+```
+
+That opens a browser tab, much like `gh auth login`, and saves a token to
+`~/.sim_id`. In CI, pipe one in instead: `echo $TOKEN | simantic auth`. If you
+bring your own platform file (`repl="board.repl"`), you need no account at all.
+
+Already have the `sim` binary? Put it on PATH or point `$SIMANTIC_SIM` at it.
+`simantic status` shows what resolved.
+
+## Pick your engine
+
+The same script runs on either engine. You choose per simulation:
+
+```python
+Sim(elf="fw.elf", mcu="STM32F401RE", uart="usart2")                  # Renode engine, the default
+Sim(elf="fw.elf", mcu="STM32F401RE", uart="usart2", backend="rust")  # our Rust engine
+```
+
+The Rust engine is a small extension module, runs one machine, and is
+considerably faster. Anything it cannot do yet, such as multi machine scenarios
+or CAN and radio injection, raises `simantic.NotSupported` and names the gap
+instead of quietly doing nothing. You can follow what each engine covers in
+[simantic-core#183](https://github.com/simantic-dev/simantic-core/issues/183).
+
+## Testing with pytest
+
+Take the `sim` fixture and write ordinary tests:
+
+```python
+def test_timer_irq_fires(sim):
+    s = sim(elf="fw.elf", mcu="STM32F401RE", uart="usart2")
+    s.expect("fired=1", timeout=8)
+    assert s.read_u32("fired") == 1
+```
+
+The engine starts once per worker rather than once per test, and every machine
+is closed for you. When a test fails, its UART transcript is attached to the
+report, because that is usually the evidence you want.
+
+`--sim-backend=renode|rust|both` chooses the engine. With `both`, each test runs
+on each and the engine name appears in the test id. Anything an engine cannot do
+is reported as a skip with the reason, so one suite can target both and stay
+honest about what each covers.
+
+One tip worth real time: on the Renode engine, every hand off between Python and
+the simulation costs a few hundred microseconds. Reading is free, pausing and
+resuming is not. Prefer `expect()`, which crosses once, over a loop that polls
+every millisecond. On the Rust engine, polling is essentially free.
+
+If you keep `test.yaml` fixture manifests, installing the package also turns
+each one into its own pytest item, so you get `-k` filtering, `--junitxml`, and
+xdist for free. Multi machine manifests need the `--scenario` runner and report
+as skips for now.
+
+For a single run with no assertions in the middle, there is `run_firmware(...)`:
+
+```python
+run = simantic.run_firmware("build/zephyr.elf", mcu="STM32F401RE",
+                            expect=["RESULT: PASS"])
+assert run.passed, run.failure_report()
+```
+
+## Telemetry
+
+When you are signed in, we count the shape of a pytest session (how many tests
+ran, passed, failed, skipped) and which SDK calls you make, by name only. It is
+one request per pytest run, buffered in `~/.simantic/usage.jsonl`, and uploaded
+at most hourly, so nothing ever waits on the network.
+
+We do not send file paths, project names, test names, firmware, or simulation
+output. Those are yours. Turn it off whenever you like:
+
+```bash
+export SIMANTIC_TELEMETRY=0     # or DO_NOT_TRACK=1
+```
+
+## Questions
+
+We would genuinely like to hear how this goes for you, especially if something
+is confusing or broken. Write to **founder@simantic.dev**, or open an issue.
+
+## License
+
+MIT. The simulators it drives are separate software under their own terms.

{simantic-0.2.0 → simantic-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "simantic"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python SDK and pytest plugin for the Simantic circuit and firmware simulators"
 # PyYAML reads sim-fixtures test.yaml manifests; pythonnet hosts the
 # simulation engine (Simantic.Core, .NET) in-process for `simantic.Sim`.

simantic-0.3.0/src/simantic/__init__.py

@@ -0,0 +1,56 @@
+"""Python control of the Simantic simulators.
+
+The firmware engine, hosted in your process.
+
+    import simantic
+
+    with simantic.Sim(elf="fw.elf", repl="board.repl") as sim:   # live control
+        sim.expect("ready"); sim.run_for(0.5)
+    run = simantic.run_firmware("fw.elf", repl="board.repl",
+                                expect=["RESULT: PASS"])          # one-shot
+
+The engine is fetched on first use. The `sim` CLI is optional; point
+`$SIMANTIC_SIM` at one, or put it on PATH.
+
+Installing this package also registers a pytest plugin that turns `test.yaml`
+fixture manifests into individually addressable pytest items.
+"""
+
+from ._locate import BinaryNotFound
+from .fixtures import (
+    Manifest,
+    ModelLibraryUnavailable,
+    UnsupportedManifest,
+    load_manifest,
+)
+from .mcu import ServerNotConfigured, SimError, SimRun, sim_binary
+from .mcu import run as run_firmware
+from .engine import EngineNotFound, engine_dir, rust_engine_dir
+from .session import BACKENDS, ExpectTimeout, Match, Sim
+from ._rust import NotSupported
+
+__version__ = "0.3.0"
+
+__all__ = [
+    # firmware
+    "Manifest",
+    "ModelLibraryUnavailable",
+    "ServerNotConfigured",
+    "SimError",
+    "SimRun",
+    "UnsupportedManifest",
+    "load_manifest",
+    "run_firmware",
+    "sim_binary",
+    # scripted sessions
+    "Sim",
+    "Match",
+    "ExpectTimeout",
+    "EngineNotFound",
+    "NotSupported",
+    "BACKENDS",
+    "engine_dir",
+    "rust_engine_dir",
+    # shared
+    "BinaryNotFound",
+]

{simantic-0.2.0 → simantic-0.3.0}/src/simantic/_cli.py

@@ -15,16 +15,8 @@ from . import auth, install, telemetry
 from ._locate import BinaryNotFound, locate
 from .mcu import BINARY as SIM_BINARY
 from .mcu import ENV_VAR as SIM_ENV
-from ._locate import BINARY as ANALOG_BINARY
-from ._locate import ENV_VAR as ANALOG_ENV
-from .pyrite import BINARY as PYRITE_BINARY
-from .pyrite import ENV_VAR as PYRITE_ENV
 
-BINARIES = (
-    (ANALOG_BINARY, ANALOG_ENV),
-    (SIM_BINARY, SIM_ENV),
-    (PYRITE_BINARY, PYRITE_ENV),
-)
+BINARIES = ((SIM_BINARY, SIM_ENV),)
 
 
 def _auth(args) -> int:
@@ -47,20 +39,22 @@ def _auth(args) -> int:
 
 
 def _install(args) -> int:
-    names = args.binary or [name for name, _ in BINARIES] + [install.ENGINE_KEY]
+    names = args.binary or [name for name, _ in BINARIES] + [install.ENGINE_KEY, install.RUST_ENGINE_KEY]
     failures = 0
     for name in names:
         try:
             if name == install.ENGINE_KEY:
                 path = install.install_engine(force=args.force, channel=args.channel)
+            elif name == install.RUST_ENGINE_KEY:
+                path = install.install_rust_engine(force=args.force, channel=args.channel)
             else:
                 path = install.install(name, force=args.force, channel=args.channel)
             print(f"{name}: {path}")
         except install.InstallError as exc:
             print(f"{name}: {exc}", file=sys.stderr)
             failures += 1
-    # Partial success is still useful — one engine may be published and the
-    # other not — so report it without discarding what did install.
+    # Partial success is still useful, so report it without discarding what
+    # did install.
     return 1 if failures == len(names) else 0
 
 
@@ -80,6 +74,9 @@ def _status(args) -> int:
             print(f"  {name}: not found (run `simantic install {name}`)")
     engine = install.installed_engine()
     print(f"  engine: {engine if engine else 'not found (fetched on first use, or `simantic install engine`)'}")
+    rust = install.installed_rust_engine()
+    missing = 'not found (fetched on first use of backend="rust", or `simantic install engine-rust`)'
+    print(f"  engine-rust: {rust if rust else missing}")
     print(telemetry.describe())
     return 0
 
@@ -106,7 +103,7 @@ def main(argv: list[str] | None = None) -> int:
     p_auth.set_defaults(func=_auth)
 
     p_install = sub.add_parser("install", help="download simulator binaries")
-    p_install.add_argument("binary", nargs="*", help="defaults to all known binaries and the engine")
+    p_install.add_argument("binary", nargs="*", help="defaults to all known binaries and both engines")
     p_install.add_argument(
         "--force", action="store_true", help="re-download even if already present"
     )

simantic-0.3.0/src/simantic/_elf.py

@@ -0,0 +1,39 @@
+"""Symbol addresses from a 32-bit little-endian ELF, with the standard library.
+
+The Renode backend resolves symbols inside the engine. The Rust engine does
+not carry a symbol table, so `Sim.symbol()` on that backend reads `.symtab`
+here — the same answer, from the same file.
+"""
+
+from __future__ import annotations
+
+import struct
+
+SHT_SYMTAB = 2
+STT_FUNC = 2
+
+
+def symbols(elf: bytes) -> dict[str, int]:
+    if elf[:4] != b"\x7fELF" or elf[4] != 1 or elf[5] != 1:
+        raise ValueError("only 32-bit little-endian ELF images are supported")
+    (shoff,) = struct.unpack_from("<I", elf, 0x20)
+    shentsize, shnum = struct.unpack_from("<HH", elf, 0x2E)
+    sections = [struct.unpack_from("<IIIIIIIIII", elf, shoff + i * shentsize) for i in range(shnum)]
+
+    out: dict[str, int] = {}
+    for sh in sections:
+        _, sh_type, _, _, offset, size, link, _, _, entsize = sh
+        if sh_type != SHT_SYMTAB or entsize == 0:
+            continue
+        strtab_off, strtab_size = sections[link][4], sections[link][5]
+        strtab = elf[strtab_off : strtab_off + strtab_size]
+        for i in range(size // entsize):
+            name_idx, value, _, info = struct.unpack_from("<IIIB", elf, offset + i * entsize)
+            if name_idx == 0:
+                continue
+            end = strtab.index(b"\0", name_idx)
+            name = strtab[name_idx:end].decode("utf-8", "replace")
+            if info & 0xF == STT_FUNC:
+                value &= ~1  # Thumb bit is a call-site convention, not the address
+            out.setdefault(name, value)
+    return out

{simantic-0.2.0 → simantic-0.3.0}/src/simantic/_locate.py

@@ -66,11 +66,3 @@ def locate(
         f"PATH, or set ${env_var} to its location."
     )
 
-
-ENV_VAR = "SIMANTIC_ANALOG_CLI"
-BINARY = "analog-cli"
-
-
-def analog_cli(explicit: str | os.PathLike[str] | None = None) -> Path:
-    """Resolve the analog-cli binary, or raise BinaryNotFound."""
-    return locate(BINARY, ENV_VAR, explicit)

simantic-0.3.0/src/simantic/_replx.py

@@ -0,0 +1,108 @@
+"""Platform text for the Rust backend.
+
+The Renode backend hands `.replx` templates to Simantic.Core, which renders
+them. The Rust engine parses plain `.repl`, so the same rendering happens
+here: every `{{a:b:default}}` placeholder becomes its default, and a default
+that is an arithmetic expression (`84000000 / 1000000 * 1.25`) is evaluated.
+Model names resolve the way `sim --mcu` does — `~/.sim_cache`, else the
+backend with stored credentials, then cached — or from a local model library
+when $SIMANTIC_MCU_LIB is set.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import os
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+from . import auth
+from .fixtures import MCU_LIB_ENV, platform_path
+from .mcu import SimError
+
+MCU_DETAILS_URL = "https://drjdhqfvrttolueolzif.supabase.co/functions/v1/get-mcu-details"
+
+_PLACEHOLDER = re.compile(r"\{\{([^}]*)\}\}")
+_ARITHMETIC = re.compile(r"[0-9. */+()-]+")
+
+
+def _evaluate(expr: str) -> str:
+    """Fold a numeric expression; anything else passes through untouched."""
+    expr = expr.strip()
+    if not _ARITHMETIC.fullmatch(expr) or re.fullmatch(r"[0-9.]+", expr):
+        return expr
+    tree = ast.parse(expr, mode="eval")
+
+    def fold(node):
+        if isinstance(node, ast.Expression):
+            return fold(node.body)
+        if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
+            return node.value
+        if isinstance(node, ast.BinOp) and isinstance(node.op, (ast.Add, ast.Sub, ast.Mult, ast.Div)):
+            a, b = fold(node.left), fold(node.right)
+            return {ast.Add: a + b, ast.Sub: a - b, ast.Mult: a * b, ast.Div: a / b}[type(node.op)]
+        if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub):
+            return -fold(node.operand)
+        raise ValueError(f"unsupported expression in platform template: {expr!r}")
+
+    value = fold(tree)
+    return str(int(value)) if float(value).is_integer() else str(value)
+
+
+def render(text: str) -> str:
+    """`.replx` → `.repl`: placeholders take their defaults."""
+    return _PLACEHOLDER.sub(lambda m: _evaluate(m.group(1).split(":")[-1]), text)
+
+
+def cache_dir() -> Path:
+    return Path(os.environ.get("HOME", "")) / ".sim_cache"
+
+
+def model_replx(mcu: str, *, use_cache: bool = True) -> str:
+    """The `.replx` text for a model name, like `sim --mcu`."""
+    if os.environ.get(MCU_LIB_ENV):
+        return platform_path(mcu, None, Path.cwd()).read_text()
+    cached = cache_dir() / f"{mcu.lower()}.json"
+    if use_cache and cached.exists():
+        replx = json.loads(cached.read_text()).get("replx")
+        if replx:
+            return replx
+    try:
+        credentials = auth.load()
+    except auth.NotAuthenticated as exc:
+        raise SimError(f"mcu={mcu!r} needs credentials to fetch the model: {exc}") from None
+    request = urllib.request.Request(
+        f"{MCU_DETAILS_URL}?model={urllib.parse.quote(mcu)}",
+        headers={"Authorization": f"Bearer {credentials.api_key}"},
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            details = json.loads(response.read())
+    except urllib.error.HTTPError as exc:
+        raise SimError(f"mcu={mcu!r} is not a supported model (HTTP {exc.code})") from None
+    except urllib.error.URLError as exc:
+        raise SimError(f"cannot reach the model backend: {exc.reason}") from None
+    replx = details.get("replx")
+    if not replx:
+        raise SimError(f"the backend returned no platform for mcu={mcu!r}")
+    cached.parent.mkdir(parents=True, exist_ok=True)
+    cached.write_text(json.dumps({"model": mcu, "replx": replx, "deprecated": bool(details.get("deprecated"))}))
+    return replx
+
+
+def platform_text(*, repl: Path | None, mcu: str | None, overlay: Path | None) -> str:
+    """Rendered `.repl` text for one machine."""
+    if repl is not None:
+        text = repl.read_text()
+    else:
+        assert mcu is not None
+        text = model_replx(mcu)
+    if overlay is not None:
+        # The platform grammar has no comment syntax; strip note lines first.
+        body = "\n".join(l for l in overlay.read_text().splitlines() if not l.lstrip().startswith(("#", "//")))
+        text = text.rstrip() + "\n\n" + body.strip() + "\n"
+    return render(text)