mcuscope 0.1.0__tar.gz

mcuscope-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Packaging / lockfiles that should not be committed for a lib
+*.egg
+
+# C build artifacts
+*.o
+*.obj
+*.a
+*.elf
+*.bin
+*.hex
+*.map
+
+# Firmware host-test binary (no extension on POSIX, .exe on Windows)
+firmware/tests/test_monitor
+firmware/tests/test_monitor.exe
+firmware/tests/test_monitor_asan
+firmware/tests/test_monitor_asan.exe
+
+# Capture databases
+*.db
+*.db-wal
+*.db-shm
+
+# Editor / OS cruft
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# superpowers brainstorm visual companion (local only)
+.superpowers/

mcuscope-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Watman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcuscope-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: mcuscope
+Version: 0.1.0
+Summary: MCUscope: host daemon, CLI and web UI to debug, monitor and plot embedded targets over serial, for humans and AI agents.
+Project-URL: Homepage, https://github.com/dwatman/mcuscope
+Project-URL: Repository, https://github.com/dwatman/mcuscope
+Project-URL: Issues, https://github.com/dwatman/mcuscope/issues
+Author-email: Daniel Watman <dwatman@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: can,debug,embedded,i2c,mcu,microcontroller,oscilloscope,plotting,serial,spi,stm32,uart
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.11
+Requires-Dist: fastapi<1.0,>=0.110
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pyserial>=3.5
+Requires-Dist: regex>=2024.0
+Requires-Dist: tomlkit<1.0,>=0.12
+Requires-Dist: typer<1.0,>=0.12
+Requires-Dist: uvicorn<1.0,>=0.29
+Requires-Dist: websockets>=14.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MCUscope
+
+**MCUscope** is a hardware debug bridge for embedded targets. It lets both humans and AI
+agents (such as Claude Code) talk to an STM32 (or any) microcontroller over a serial link:
+send CAN/I2C/SPI/GPIO/ADC commands, stream and query timestamped debug output, and plot
+realtime data in the browser.
+
+A single daemon (`mcuscoped`) owns the serial port, timestamps every line into SQLite, and
+serves a local REST + WebSocket API and a web UI on `127.0.0.1:8765`. The `mcu` CLI is a
+thin client over that API and is the primary interface for both the human and the agent.
+
+This package (`mcuscope`) is the host side. The portable C firmware "monitor" module that
+runs on the target, a hardware-free simulator, and the full specification live in the
+[project repository](https://github.com/dwatman/mcuscope).
+
+<!-- Absolute URL on purpose: PyPI does not resolve repo-relative image paths, and it only
+     renders once the repository is public. -->
+![MCUscope web UI](https://raw.githubusercontent.com/dwatman/mcuscope/main/docs/img/webui.png)
+
+## Install
+
+Requires Python 3.11 or newer.
+
+```bash
+uv tool install mcuscope        # or: pipx install mcuscope
+```
+
+This exposes three console scripts on your PATH: `mcuscoped` (the daemon), `mcu` (the
+CLI), and `mcu-sim` (the hardware-free simulator).
+
+To reach a real serial port, one OS-specific step:
+
+- **Linux**: your user must be in the `dialout` group: `sudo usermod -aG dialout $USER`,
+  then log out and back in. Without it, opening `/dev/ttyACM0` fails with permission denied.
+- **Windows 10/11**: most USB-serial adapters and ST-Link VCPs work with the in-box
+  driver; some need the vendor driver (CP210x, CH340, FTDI).
+
+Neither is needed for the quickstart below, which runs with no hardware attached.
+
+## Quickstart
+
+No hardware needed to try it:
+
+```bash
+mcuscoped --sim --open            # daemon + built-in simulator; opens the web UI
+```
+
+The web UI at `http://127.0.0.1:8765/ui/` shows the live terminal, CAN table, and
+realtime plots. The Plots panel also renders a Digital/Enum view (logic-analyser bit
+traces and labelled enum/state bands) sharing the same time base and cursor as the
+analog charts.
+
+With real hardware, start the daemon first (it owns the port and captures everything),
+then attach the port - from the UI's **+ Attach** dialog, or the CLI:
+
+```bash
+mcuscoped                                              # serves the API + web UI on :8765
+# in another terminal (or use `mcu daemon start` to background the daemon):
+mcu devices                                            # find the port name
+mcu attach /dev/ttyACM0 --baud 115200 --alias board    # Linux
+mcu attach COM7 --baud 115200 --alias board            # Windows
+
+mcu status                        # daemon + port health
+mcu cmd ping                      # -> monitor 1 <project>  (port-layer name, not the alias)
+mcu cmd 'i2c scan'                # -> 48 50
+mcu tail -f                       # follow live capture
+```
+
+Every command takes `--json` for a single machine-readable object and returns meaningful
+exit codes (**0** success/match, **1** error or bad usage, **2** timeout, **3** daemon
+unreachable). Run `mcu ai-guide` for a compact, agent-oriented cheat sheet.
+
+The simulator also runs standalone (`mcu-sim`, prints e.g. `socket://127.0.0.1:9900`);
+attach it like any device: `mcu attach socket://127.0.0.1:9900 --alias sim`.
+
+## Documentation
+
+Full quickstart, configuration reference, protocol/API specification, and firmware
+integration guide are in the [project repository](https://github.com/dwatman/mcuscope).
+
+## License
+
+MIT

mcuscope-0.1.0/README.md

@@ -0,0 +1,83 @@
+# MCUscope
+
+**MCUscope** is a hardware debug bridge for embedded targets. It lets both humans and AI
+agents (such as Claude Code) talk to an STM32 (or any) microcontroller over a serial link:
+send CAN/I2C/SPI/GPIO/ADC commands, stream and query timestamped debug output, and plot
+realtime data in the browser.
+
+A single daemon (`mcuscoped`) owns the serial port, timestamps every line into SQLite, and
+serves a local REST + WebSocket API and a web UI on `127.0.0.1:8765`. The `mcu` CLI is a
+thin client over that API and is the primary interface for both the human and the agent.
+
+This package (`mcuscope`) is the host side. The portable C firmware "monitor" module that
+runs on the target, a hardware-free simulator, and the full specification live in the
+[project repository](https://github.com/dwatman/mcuscope).
+
+<!-- Absolute URL on purpose: PyPI does not resolve repo-relative image paths, and it only
+     renders once the repository is public. -->
+![MCUscope web UI](https://raw.githubusercontent.com/dwatman/mcuscope/main/docs/img/webui.png)
+
+## Install
+
+Requires Python 3.11 or newer.
+
+```bash
+uv tool install mcuscope        # or: pipx install mcuscope
+```
+
+This exposes three console scripts on your PATH: `mcuscoped` (the daemon), `mcu` (the
+CLI), and `mcu-sim` (the hardware-free simulator).
+
+To reach a real serial port, one OS-specific step:
+
+- **Linux**: your user must be in the `dialout` group: `sudo usermod -aG dialout $USER`,
+  then log out and back in. Without it, opening `/dev/ttyACM0` fails with permission denied.
+- **Windows 10/11**: most USB-serial adapters and ST-Link VCPs work with the in-box
+  driver; some need the vendor driver (CP210x, CH340, FTDI).
+
+Neither is needed for the quickstart below, which runs with no hardware attached.
+
+## Quickstart
+
+No hardware needed to try it:
+
+```bash
+mcuscoped --sim --open            # daemon + built-in simulator; opens the web UI
+```
+
+The web UI at `http://127.0.0.1:8765/ui/` shows the live terminal, CAN table, and
+realtime plots. The Plots panel also renders a Digital/Enum view (logic-analyser bit
+traces and labelled enum/state bands) sharing the same time base and cursor as the
+analog charts.
+
+With real hardware, start the daemon first (it owns the port and captures everything),
+then attach the port - from the UI's **+ Attach** dialog, or the CLI:
+
+```bash
+mcuscoped                                              # serves the API + web UI on :8765
+# in another terminal (or use `mcu daemon start` to background the daemon):
+mcu devices                                            # find the port name
+mcu attach /dev/ttyACM0 --baud 115200 --alias board    # Linux
+mcu attach COM7 --baud 115200 --alias board            # Windows
+
+mcu status                        # daemon + port health
+mcu cmd ping                      # -> monitor 1 <project>  (port-layer name, not the alias)
+mcu cmd 'i2c scan'                # -> 48 50
+mcu tail -f                       # follow live capture
+```
+
+Every command takes `--json` for a single machine-readable object and returns meaningful
+exit codes (**0** success/match, **1** error or bad usage, **2** timeout, **3** daemon
+unreachable). Run `mcu ai-guide` for a compact, agent-oriented cheat sheet.
+
+The simulator also runs standalone (`mcu-sim`, prints e.g. `socket://127.0.0.1:9900`);
+attach it like any device: `mcu attach socket://127.0.0.1:9900 --alias sim`.
+
+## Documentation
+
+Full quickstart, configuration reference, protocol/API specification, and firmware
+integration guide are in the [project repository](https://github.com/dwatman/mcuscope).
+
+## License
+
+MIT

mcuscope-0.1.0/contrib/config.example.toml

@@ -0,0 +1,48 @@
+# Example mcuscope daemon configuration (SPEC 3.3).
+# Copy to the platformdirs config location and edit:
+#   Linux:   ~/.config/mcuscope/config.toml
+#   Windows: %LOCALAPPDATA%\mcuscope\mcuscope\config.toml
+# All keys are optional; the file can also be edited from the web UI settings page.
+
+[server]
+host = "127.0.0.1"    # bind "0.0.0.0" to reach the daemon across the LAN
+port = 8765
+# Note: the access token is NOT a config key. Set it at runtime instead
+# (preferred: environment variable, so it is not visible in the process list):
+#   MCUSCOPED_TOKEN=long-random-string mcuscoped
+# Generate one with:  python -c "import secrets; print(secrets.token_urlsafe(24))"
+
+[storage]
+# Empty db_path uses the platformdirs data dir:
+#   Linux:   ~/.local/share/mcuscope/capture.db
+#   Windows: %LOCALAPPDATA%\mcuscope\mcuscope\capture.db
+db_path = ""
+retention_days = 10
+
+# The newest N sessions are never expired by age, however old they get. Age alone is a
+# poor measure of what is worth keeping: a board captured over a quiet fortnight would
+# otherwise lose its only recorded run to the calendar. 0 = pure age-based retention.
+min_sessions = 5
+
+# Open a session automatically for each daemon run, so the floor above has runs to protect
+# even when nobody types `mcu session start`. Normal use names no sessions at all, so with
+# this off the floor protects nothing and retention is age-based alone. An automatic run
+# that captured no device traffic is dropped when it closes.
+auto_session = true
+
+# Optional hard bound on disk use. 0 (the default) means no cap: the capture is bounded
+# by retention_days alone and nothing is ever dropped for size. When set, the daemon
+# trims the OLDEST lines once the capture exceeds it, so set it generously - the web UI
+# status bar shows the current capture size to size it against.
+# max_db_bytes = 2147483648   # 2 GiB
+
+# One [[ports]] block per serial port. Attach the simulator with a socket URL, or a
+# real board by device path / COM name, or by USB serial number (stable across replug
+# on both Linux and Windows).
+
+[[ports]]
+alias = "board"
+device = "socket://127.0.0.1:9900"   # sim; or /dev/ttyACM0, COM7, /dev/serial/by-id/...
+# serial_number = "066BFF3..."       # alternative to device: resolve via list_ports
+baud = 115200
+autoconnect = true

mcuscope-0.1.0/contrib/mcuscoped.service

@@ -0,0 +1,21 @@
+# systemd user unit for mcuscoped (Linux convenience only; SPEC 3.1).
+# Install:
+#   mkdir -p ~/.config/systemd/user
+#   cp mcuscoped.service ~/.config/systemd/user/
+#   systemctl --user daemon-reload
+#   systemctl --user start mcuscoped
+# Enabling it at login (OS-level autostart) is intentionally left to the user;
+# automated enable/disable is a P2 item.
+
+[Unit]
+Description=mcuscope hardware debug bridge daemon
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=%h/.local/bin/mcuscoped
+Restart=on-failure
+RestartSec=2
+
+[Install]
+WantedBy=default.target

mcuscope-0.1.0/mcuscope/__init__.py

@@ -0,0 +1,14 @@
+"""mcuscope: host daemon and CLI for MCUscope, a hardware debug and plotting bridge.
+
+See docs/SPEC.md for the authoritative protocol and API contract. The package is
+split into small modules:
+
+- protocol: pure encode/decode of the UART line protocol (no I/O).
+- store: SQLite capture storage.
+- serial_link: per-port serial handling, seq machinery, reconnect.
+- server: FastAPI REST + WebSocket app.
+- daemon: mcuscoped entry point (config load, wiring, lifecycle).
+- cli: the mcu command-line client.
+"""
+
+__version__ = "0.1.0"