plotdeck 1.0.0__py3-none-any.whl

plotdeck/utils/logging_setup.py

@@ -0,0 +1,42 @@
+"""Logging configuration: rotating file plus console."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+
+def log_directory() -> Path:
+    path = Path.home() / "Library" / "Logs" / "PlotDeck"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def setup_logging(level: int = logging.INFO) -> logging.Logger:
+    logger = logging.getLogger("plotdeck")
+    if logger.handlers:
+        return logger
+    logger.setLevel(level)
+    formatter = logging.Formatter(
+        "%(asctime)s %(levelname)-7s %(name)s: %(message)s", "%Y-%m-%d %H:%M:%S"
+    )
+
+    handler: logging.Handler
+    try:
+        handler = RotatingFileHandler(
+            log_directory() / "plotdeck.log", maxBytes=1_000_000, backupCount=3
+        )
+    except OSError:
+        handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+
+    if sys.stderr is not None:
+        console = logging.StreamHandler(sys.stderr)
+        console.setFormatter(formatter)
+        console.setLevel(logging.WARNING)
+        logger.addHandler(console)
+
+    return logger

plotdeck/utils/settings.py

@@ -0,0 +1,86 @@
+"""Persistent application settings backed by QSettings."""
+
+from __future__ import annotations
+
+from PySide6.QtCore import QByteArray, QSettings
+
+
+class AppSettings:
+    def __init__(self, path: str | None = None) -> None:
+        if path:
+            self._settings = QSettings(path, QSettings.Format.IniFormat)
+        else:
+            self._settings = QSettings("PlotDeck", "PlotDeck")
+
+    def value(self, key: str, default=None, kind=None):  # noqa: ANN001, ANN201
+        if kind is not None:
+            return self._settings.value(key, default, type=kind)
+        return self._settings.value(key, default)
+
+    def set_value(self, key: str, value) -> None:  # noqa: ANN001
+        self._settings.setValue(key, value)
+
+    def sync(self) -> None:
+        self._settings.sync()
+
+    # -- recent files --------------------------------------------------- #
+    def recent_files(self) -> list[str]:
+        value: object = self._settings.value("files/recent", [])
+        if isinstance(value, str):
+            value = [value]
+        if not isinstance(value, (list, tuple)):
+            return []
+        return [str(item) for item in value if item]
+
+    def add_recent_file(self, path: str) -> None:
+        files = [item for item in self.recent_files() if item != path]
+        files.insert(0, path)
+        self._settings.setValue("files/recent", files[:8])
+
+    def clear_recent_files(self) -> None:
+        self._settings.setValue("files/recent", [])
+
+    # -- window --------------------------------------------------------- #
+    def geometry(self) -> QByteArray | None:
+        value = self._settings.value("window/geometry")
+        return value if isinstance(value, QByteArray) else None
+
+    def save_geometry(self, geometry: QByteArray) -> None:
+        self._settings.setValue("window/geometry", geometry)
+
+    def window_state(self) -> QByteArray | None:
+        value = self._settings.value("window/state")
+        return value if isinstance(value, QByteArray) else None
+
+    def save_window_state(self, state: QByteArray) -> None:
+        self._settings.setValue("window/state", state)
+
+    # -- preferences ---------------------------------------------------- #
+    def dark_theme(self, fallback: bool = True) -> bool:
+        value = self._settings.value("ui/dark", fallback)
+        return str(value).lower() in ("1", "true", "yes")
+
+    def set_dark_theme(self, dark: bool) -> None:
+        self._settings.setValue("ui/dark", dark)
+
+    def last_port(self) -> str:
+        return str(self._settings.value("machine/port", ""))
+
+    def set_last_port(self, port: str) -> None:
+        self._settings.setValue("machine/port", port)
+
+    def last_baud(self) -> int:
+        try:
+            return int(str(self._settings.value("machine/baud", 115200)))
+        except (TypeError, ValueError):
+            return 115200
+
+    def set_last_baud(self, baud: int) -> None:
+        self._settings.setValue("machine/baud", baud)
+
+    def auto_reconnect(self) -> bool:
+        return str(self._settings.value("machine/auto_reconnect", False)).lower() in (
+            "1",
+            "true",
+            "yes",
+        )

plotdeck-1.0.0.dist-info/METADATA

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: plotdeck
+Version: 1.0.0
+Summary: G-code sender and editor for GRBL-based CNC routers
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PySide6>=6.6
+Requires-Dist: pyserial>=3.5
+Requires-Dist: pyqtgraph>=0.13
+Requires-Dist: numpy>=1.24
+Provides-Extra: 3d
+Requires-Dist: PyOpenGL>=3.1; extra == "3d"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-qt>=4.4; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: black>=24; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pyinstaller>=6; extra == "dev"
+
+# PlotDeck
+
+A G-code sender and editor for small CNC routers running **GRBL 1.1** on an
+Arduino Uno. macOS desktop app, Python + PySide6.
+
+PlotDeck connects over USB serial, lets you edit and preview a G-code file,
+streams it with GRBL's character-counting flow control, and gives you manual
+control (jog, home, zero, overrides) with live position and toolpath feedback.
+
+**New here? Read [USER_MANUAL.md](USER_MANUAL.md), or open it inside the app
+from the Manual toolbar button or Help → User Manual (F1).**
+
+![PlotDeck screenshot](images/PlotDeck.png)
+
+## Features
+
+- **Connection** — USB port discovery, 115200 baud default, GRBL banner
+  detection (the Uno resets when the port opens), 5 Hz status polling, and a
+  **Demo** mode that runs a simulated machine with no hardware.
+- **Streaming** — 127-byte character-counting sender, pause/resume, safe stop
+  (feed hold + soft reset), start from a line, and GRBL check mode (`$C`) dry
+  runs.
+- **Editor** — line numbers, G/M/axis/feed syntax colours, current-line and
+  executed-line markers, error markers, find/replace, go-to-line, toggle
+  comment, strip comments, renumber, and offset/scale/rotate transforms.
+- **Visualizer** — 2D toolpath with executed (green) and remaining (dashed)
+  paths, live tool position, scroll/button zoom, pan, fit-to-view, bounding
+  box and time estimate. Optional 3D view with orbit and zoom when PyOpenGL
+  is installed.
+- **Machine control** — jog pad with step chips and keyboard control, work
+  zeroing per axis, G54–G59 selection, homing, unlock, jog cancel, feed /
+  rapid / spindle overrides, spindle on/off, and a Z-probe wizard.
+- **Safety workflows** — pre-flight summary (time, bounds, depth, tools,
+  warnings), `M6` interception with a tool-change pause, `error:N` pauses the
+  job instead of blindly continuing, alarm dialog with unlock/home recovery,
+  and automatic job-interrupted reporting on disconnect.
+- **Settings** — editable `$$` table with descriptions, plus persistence of
+  recent files, port, theme and window layout via QSettings.
+- **Help** — the full user manual is bundled and rendered in-app from the
+  **Manual** toolbar button or **Help → User Manual** (F1), with search and links.
+
+## Requirements
+
+- macOS (only platform tested), Python 3.10 or newer
+- Arduino Uno with GRBL 1.1 and a CNC shield (for real hardware)
+- Python packages: PySide6, pyserial, pyqtgraph, numpy
+- Optional: PyOpenGL (3D view), PyInstaller (packaging)
+
+## Setup
+
+```bash
+bash scripts/setup_env.sh      # creates .venv and installs .[dev,3d]
+source .venv/bin/activate
+```
+
+Or manually:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev,3d]"
+```
+
+## Run
+
+```bash
+python -m plotdeck
+```
+
+Pick a `/dev/cu.usbmodem*` port (or `/dev/cu.usbserial*` for CH340 boards) and
+press **Connect**. Click **Demo** to explore the interface without hardware.
+
+## Typical workflow
+
+1. Connect and wait for the state badge to read **IDLE**.
+2. Home the machine, jog to the workpiece origin, and zero X/Y (and Z, or use
+   **Machine → Probe Z…** with a touch plate).
+3. Open a G-code file (⌘O or drag and drop). Check the toolpath preview.
+4. Press **Run**. The pre-flight dialog shows the time estimate, bounding box,
+   tools and warnings; **Dry run** uses GRBL check mode.
+5. Watch progress in the Job panel; the editor follows the executing line.
+   **Pause** sends feed hold, **Stop** (⌘.) sends feed hold then soft reset.
+6. If GRBL returns `error:N`, the job pauses and asks whether to skip the line
+   or abort. Insert tool changes when the M6 dialog appears.
+
+> **Tool changes:** PlotDeck pauses and prompts for `M6`, but it does not
+> automatically stop a manually switched spindle or retract Z. Turn the spindle
+> off and raise Z before reaching in, then re-probe Z if the tool length
+> changed. Only an automatic spindle relay wired to GRBL can be stopped by
+> GRBL itself.
+
+## Keyboard shortcuts
+
+| Action | Shortcut |
+| --- | --- |
+| Open / Save | ⌘O / ⌘S |
+| Find / Go to line | ⌘F / ⌘L |
+| Run / Run from cursor | ⌘R / ⌘⇧R |
+| Pause / Resume | toolbar (feed hold / cycle start) |
+| Stop | ⌘. |
+| Soft reset | ⌘⇧. |
+| Toggle comment | ⌘/ |
+| Connect / Disconnect | ⌘K |
+| Fit toolpath | ⌘0 (or `F` with the preview focused) |
+| Jog | arrows (X/Y), PgUp/PgDn (Z), `[` `]` step, Space cancel |
+
+Jog keys only act while the jog panel has focus. The console accepts commands
+when idle; during a job line commands are refused (real-time commands such as
+`?` or `!` still work from a serial terminal, but the app controls them).
+
+## Tests
+
+```bash
+source .venv/bin/activate
+QT_QPA_PLATFORM=offscreen pytest -q
+ruff check src tests
+black --check src tests
+mypy
+```
+
+The suite drives the core against an in-process GRBL simulator
+(`tests/fake_grbl.py`) that enforces the 127-byte buffer, and includes headless
+UI smoke tests (`pytest-qt`). CI runs the same checks on macOS.
+
+## Packaging
+
+```bash
+bash packaging/build_app.sh
+```
+
+The built `dist/PlotDeck.app` was launched headlessly during development to
+confirm the bundle starts (PySide6, pyqtgraph and the Qt platform plugins are
+collected; PyOpenGL is included when installed).
+
+This produces `dist/PlotDeck.app` via `packaging/plotdeck.spec`, and a `.dmg`
+when `create-dmg` is installed. For distribution outside your own Mac, sign and
+notarize with your Apple Developer identity:
+
+```bash
+codesign --deep --options runtime --sign "Developer ID Application: …" dist/PlotDeck.app
+xcrun notarytool submit … --wait
+xcrun stapler staple dist/PlotDeck.app
+```
+
+## Architecture
+
+```
+src/plotdeck/
+├── core/            # no Qt imports; unit-testable headless
+│   ├── transport.py     # Transport ABC, SerialTransport thread, MockTransport
+│   ├── grbl_protocol.py # real-time bytes, response classifier, error tables
+│   ├── status.py        # <...> status reports → MachineStatus
+│   ├── gcode_parser.py  # cleaning, tokenizing, toolpath + time estimate
+│   ├── streamer.py      # character-counting job state machine
+│   └── controller.py    # MachineController orchestration
+├── ui/              # PySide6 widgets
+│   ├── main_window.py   # layout, menus, shortcuts, state-driven enablement
+│   ├── editor.py        # editor, gutter, highlighter, find bar
+│   ├── console.py       # colour-coded console + history
+│   ├── status_panel.py  # DRO, state badge, override sliders
+│   ├── jog_panel.py     # jog pad, zeroing, WCS
+│   ├── visualizer.py    # 2D/3D toolpath preview
+│   ├── job_panel.py     # progress and timing
+│   ├── dialogs.py       # pre-flight, tool change, probe, settings
+│   └── theme.py         # colour tokens and QSS
+└── utils/           # settings (QSettings) and logging
+```
+
+The UI never touches the serial port. Controller callbacks are marshalled to
+the main thread through a small `QObject` signal bridge. The controller and
+streamer are plain Python, so tests and CLI use do not need a Qt event loop.
+
+## GRBL notes
+
+- Buffer size is 127 usable bytes; lines are counted as `len(line) + 1`.
+- Real-time bytes (`?`, `!`, `~`, `0x18`, `0x85`, override bytes) bypass the
+  queue and never produce `ok`.
+- Manual commands are acknowledged separately from the job stream, so a `$C`
+  or `$H` ok cannot corrupt buffer accounting.
+- `M6` is never forwarded (GRBL would return `error:20`); the streamer pauses,
+  the UI prompts, then the job resumes after the tool change.
+- On soft reset the streamer clears its queue and pending bytes and the app
+  re-syncs from the next status report.
+
+## Limitations / not implemented
+
+- Only GRBL 1.1 is supported; Marlin/FluidNC are out of scope.
+- No CAM: PlotDeck sends G-code produced elsewhere.
+- No auto-reconnect, macros editor, tool/material library, or height-map
+  leveling (post-1.0 in the plan).
+- The 3D view requires `PyOpenGL` (`pip install -e ".[3d]"`); without it the
+  3D button reports that the view is unavailable.
+- Clicking a toolpath segment does not jump to its line yet.
+- Find/replace is literal text, not regular expressions; hover documentation
+  and G/M-code autocomplete are not implemented.
+- Continuous (hold-to-jog) motion and saved macros are not implemented.
+- The app icon is optional; drop `packaging/icon.icns` in place before building
+  if you want one.
+
+## Safety
+
+This software controls a machine that can injure you. Wear eye protection,
+secure the workpiece, know where the power switch is, and keep a hand near it
+for the first cut. A software stop is **not** an emergency stop — wire a
+hardware e-stop that cuts motor and spindle power. Test with the tool
+disconnected or raised before cutting material.

plotdeck-1.0.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+plotdeck/__init__.py,sha256=AZ-Q2t-x-RS3PbS-Xg0I9lltIBwjjonU2F-zNxp5R3I,122
+plotdeck/__main__.py,sha256=vJbhcKnmxY8kShIvxgFrx0qJmthcuRrWhXVxnnyDeLQ,116
+plotdeck/app.py,sha256=VXMg-yy6qprG8-yknp4svMrhOs6FvGCbIRa-gTfqkhU,1685
+plotdeck/core/__init__.py,sha256=xgj92ejegspz_ak7ly5D5CjudKkKD2zS-eboaM3Fpyw,139
+plotdeck/core/controller.py,sha256=NQqcbUW_wuWjTzkUymMiqgpyX5EkMZ_iBqBlKKo4k-o,19975
+plotdeck/core/gcode_parser.py,sha256=H53FF2OOzdcORM64ixUA3klYwvuZ0aKrFvNRXcDVUJs,13171
+plotdeck/core/grbl_protocol.py,sha256=wXDfZ81n8MemskZB1JMKfoajSLKIAX1sqaAa0XmtvtY,9914
+plotdeck/core/status.py,sha256=IaUjegCEnM__MS8by-U-yV26DwsJOfCqMI0NXvVORdo,4669
+plotdeck/core/streamer.py,sha256=dZICcJrmV91tqQn06nDO14-eMdNdPwsrbnU_UOU5qbw,11400
+plotdeck/core/transport.py,sha256=SWyrpvGKWyd02xXaujrkz85VfB9z3d04GYh_aTpnN9Q,12009
+plotdeck/ui/__init__.py,sha256=yO2gsCHcUqbaMZd8ErO_eQyGcCaGwkOIAGH8NID7zFY,43
+plotdeck/ui/connection_panel.py,sha256=AhZn7aUaz5PMxU5TeKIo2F6S23k9q0pISrhY4aDf2ag,4575
+plotdeck/ui/console.py,sha256=4Uk4YjAqq5C_fSb3275krMhc9K5Uy_o7KoXJViS_AWI,6180
+plotdeck/ui/dialogs.py,sha256=nN0ejrBB7Nqpj5RLXDx8p4uxebvmX6mNem083B7EyMU,11295
+plotdeck/ui/editor.py,sha256=mNbqYsOX2xlqP2FACUiMB2KmeyjKb2HA8zgNxU8jifE,20710
+plotdeck/ui/job_panel.py,sha256=dSJI9sAYNWP9rIRq8QtrMN_Cb_YYaqX767Hbhl8Vnck,4261
+plotdeck/ui/jog_panel.py,sha256=jrTHZdwt2NsE1B90umct0rctGG92g27eByS3k980nzU,8294
+plotdeck/ui/main_window.py,sha256=I33ZB63hqmHUt-_UnJSioLNyv4kM7MwjyVGIT0DE4b8,45979
+plotdeck/ui/manual.py,sha256=Dwx06j0V4ak_jzS9qp6-luyIqPFu6zsIAAGxcZDfkLA,5376
+plotdeck/ui/status_panel.py,sha256=Fz4VIJUPFMhwkWrlCWan6iCRHt5cVAITOfpi3chTWK8,9237
+plotdeck/ui/theme.py,sha256=QQ0CwZivMQ9p6NSac80QfnHy1mpuduxl7oB_A3myr1o,8859
+plotdeck/ui/visualizer.py,sha256=1PVOncOiGdpenCKylO_E6mOBKzKlhSGnnhdgOiwvpYk,15158
+plotdeck/utils/__init__.py,sha256=_OATcBYijAEZ6ERdNUd5mWTBF7r00LYaiiaYNM_ePgg,50
+plotdeck/utils/logging_setup.py,sha256=CO82UzKy7Ed7voWil3Ys1LNCJWqu1mf_cozCViHXUaM,1173
+plotdeck/utils/settings.py,sha256=UgdOd1--rdlRCa7tMDBDdI_Mr6z3SBl0fX_CvnogOkk,3135
+plotdeck-1.0.0.dist-info/METADATA,sha256=RlzTNDbYeqixaXupj-VqM2s6QEkURlyQZ5pnDJEFgZc,9435
+plotdeck-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+plotdeck-1.0.0.dist-info/entry_points.txt,sha256=ZXkaRP720CiCm1PCMd7Dat6nsf9F5Q4WCvKUvN2Hyyw,95
+plotdeck-1.0.0.dist-info/top_level.txt,sha256=EEd8ps6Xn96Ix0_-hZ9wip-iWuqdn018E1X7iUWLWPQ,9
+plotdeck-1.0.0.dist-info/RECORD,,

plotdeck-1.0.0.dist-info/WHEEL

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

plotdeck-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+plotdeck = plotdeck.app:main
+
+[gui_scripts]
+plotdeck-gui = plotdeck.app:main

plotdeck-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+plotdeck