plotdeck 1.0.0__py3-none-any.whl

plotdeck/core/gcode_parser.py

@@ -0,0 +1,404 @@
+"""G-code tokenizer, cleaner and toolpath extractor.
+
+The parser is deliberately small: PlotDeck is a sender, not a CAM package, so
+it only needs enough modal understanding to draw an accurate preview and
+estimate job time.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass, field
+
+MAX_LINE_LENGTH = 80
+RAPID_RATE_MM_MIN = 3000.0
+ARC_SEGMENTS = 48
+
+WORD_RE = re.compile(r"([A-Z])\s*([-+]?(?:\d+(?:\.\d*)?|\.\d+))")
+M6_RE = re.compile(r"(?:^|\s)M0?6(?:\D|$)")
+TOOL_RE = re.compile(r"(?:^|\s)T(\d+)(?:\D|$)")
+
+
+@dataclass(frozen=True)
+class ProgramLine:
+    """A single executable line, with its original 1-based line number."""
+
+    text: str
+    source_line: int
+    length: int = 0
+
+    def __post_init__(self) -> None:
+        if not self.length:
+            object.__setattr__(self, "length", len(self.text))
+
+    @property
+    def too_long(self) -> bool:
+        return self.length > MAX_LINE_LENGTH
+
+    @property
+    def is_tool_change(self) -> bool:
+        if M6_RE.search(self.text):
+            return True
+        # A standalone tool-select line (T2 with no motion) is also a change.
+        if TOOL_RE.search(self.text):
+            words = WORD_RE.findall(self.text)
+            return bool(words) and all(letter in {"T", "N"} for letter, _ in words)
+        return False
+
+    @property
+    def tool_number(self) -> int | None:
+        match = TOOL_RE.search(self.text)
+        return int(match.group(1)) if match else None
+
+
+def strip_comments(line: str) -> str:
+    """Remove ``;`` and ``(...)`` comments, respecting commented semicolons."""
+    out: list[str] = []
+    depth = 0
+    for char in line:
+        if depth:
+            if char == ")":
+                depth -= 1
+            continue
+        if char == "(":
+            depth += 1
+            continue
+        if char == ";":
+            break
+        out.append(char)
+    return "".join(out)
+
+
+def clean_line(line: str) -> str:
+    """Clean a source line into something GRBL will accept."""
+    text = strip_comments(line).strip()
+    if not text or text.startswith("%"):
+        return ""
+    text = re.sub(r"\s+", " ", text.upper())
+    return text
+
+
+def tokenize(text: str) -> list[tuple[str, float]]:
+    """Split a cleaned line into ``(letter, value)`` words."""
+    return [(match.group(1), float(match.group(2))) for match in WORD_RE.finditer(text)]
+
+
+def parse_program(source: str) -> list[ProgramLine]:
+    """Clean *source* and return the executable lines with source numbers."""
+    program: list[ProgramLine] = []
+    for index, raw in enumerate(source.splitlines(), start=1):
+        text = clean_line(raw)
+        if text:
+            program.append(ProgramLine(text=text, source_line=index))
+    return program
+
+
+def line_count(source: str) -> int:
+    return len(source.splitlines())
+
+
+# --------------------------------------------------------------------------- #
+# Toolpath model
+# --------------------------------------------------------------------------- #
+Point = tuple[float, float, float]
+
+
+@dataclass
+class Segment:
+    kind: str  # "rapid" | "feed" | "arc_cw" | "arc_ccw"
+    start: Point
+    end: Point
+    source_line: int
+    points: list[Point] = field(default_factory=list)
+
+    @property
+    def length(self) -> float:
+        if len(self.points) > 1:
+            return sum(
+                math.dist(self.points[i], self.points[i + 1]) for i in range(len(self.points) - 1)
+            )
+        return math.dist(self.start, self.end)
+
+
+@dataclass
+class Toolpath:
+    segments: list[Segment] = field(default_factory=list)
+    bounds: tuple[Point, Point] | None = None
+    estimated_seconds: float = 0.0
+    tools: list[int] = field(default_factory=list)
+    min_z: float | None = None
+    max_z: float | None = None
+    warnings: list[str] = field(default_factory=list)
+    unsupported: set[str] = field(default_factory=set)
+
+    @property
+    def total_length(self) -> float:
+        return sum(segment.length for segment in self.segments)
+
+
+class _Modal:
+    def __init__(self) -> None:
+        self.units = 1.0  # multiplier to millimetres
+        self.absolute = True
+        self.motion = 0
+        self.plane = "XY"
+        self.position: Point = (0.0, 0.0, 0.0)
+        self.feed: float | None = None
+
+
+def _plane_axes(plane: str) -> tuple[int, int, int]:
+    if plane == "ZX":
+        return 2, 0, 1
+    if plane == "YZ":
+        return 1, 2, 0
+    return 0, 1, 2
+
+
+def _arc_points(
+    start: Point,
+    end: Point,
+    center: Point,
+    clockwise: bool,
+    plane: str,
+) -> list[Point]:
+    u, v, w = _plane_axes(plane)
+    su, sv = start[u], start[v]
+    eu, ev = end[u], end[v]
+    cu, cv = center[u], center[v]
+
+    radius = math.hypot(su - cu, sv - cv)
+    start_angle = math.atan2(sv - cv, su - cu)
+    end_angle = math.atan2(ev - cv, eu - cu)
+
+    if clockwise:
+        while end_angle >= start_angle:
+            end_angle -= 2 * math.pi
+    else:
+        while end_angle <= start_angle:
+            end_angle += 2 * math.pi
+
+    sweep = end_angle - start_angle
+    count = max(4, min(ARC_SEGMENTS, int(abs(sweep) / (math.pi / 24)) + 1))
+
+    points: list[Point] = []
+    for step in range(count + 1):
+        fraction = step / count
+        angle = start_angle + sweep * fraction
+        point = list(start)
+        point[u] = cu + radius * math.cos(angle)
+        point[v] = cv + radius * math.sin(angle)
+        point[w] = start[w] + (end[w] - start[w]) * fraction
+        points.append((point[0], point[1], point[2]))
+    points[-1] = end
+    return points
+
+
+def _arc_points_from_radius(
+    start: Point, end: Point, radius: float, clockwise: bool, plane: str
+) -> list[Point] | None:
+    u, v, _ = _plane_axes(plane)
+    chord = math.dist((start[u], start[v]), (end[u], end[v]))
+    if chord == 0 or chord > 2 * abs(radius):
+        return None
+    half = chord / 2
+    height = math.sqrt(max(0.0, radius * radius - half * half))
+    mx = (start[u] + end[u]) / 2
+    my = (start[v] + end[v]) / 2
+    dx = end[u] - start[u]
+    dy = end[v] - start[v]
+    length = math.hypot(dx, dy) or 1.0
+    nx, ny = -dy / length, dx / length
+
+    # Positive R selects the minor arc; negative selects the major arc.
+    minor = radius >= 0
+    candidates = [(mx + nx * height, my + ny * height), (mx - nx * height, my - ny * height)]
+    center = candidates[0]
+    for candidate in candidates:
+        cangle = math.atan2(start[v] - candidate[1], start[u] - candidate[0])
+        eangle = math.atan2(end[v] - candidate[1], end[u] - candidate[0])
+        sweep = eangle - cangle
+        sweep = -(sweep % (2 * math.pi)) if clockwise else sweep % (2 * math.pi)
+        if (abs(sweep) <= math.pi) == minor:
+            center = candidate
+            break
+    cx, cy = center
+    full_center = list(start)
+    full_center[u] = cx
+    full_center[v] = cy
+    return _arc_points(start, end, tuple(full_center), clockwise, plane)  # type: ignore[arg-type]
+
+
+def _segment_length(points: list[Point]) -> float:
+    return sum(math.dist(points[i], points[i + 1]) for i in range(len(points) - 1))
+
+
+def build_toolpath(program: list[ProgramLine], limits: Point | None = None) -> Toolpath:
+    """Extract drawable segments and job statistics from *program*."""
+    model = _Modal()
+    path = Toolpath()
+    tools: set[int] = set()
+    seen_z: list[float] = []
+
+    for line in program:
+        if line.is_tool_change:
+            tool = line.tool_number
+            if tool is not None:
+                tools.add(tool)
+            continue
+
+        if line.too_long:
+            path.warnings.append(f"Line {line.source_line} is longer than 80 characters.")
+
+        words = tokenize(line.text)
+        values: dict[str, float] = {}
+        for letter, value in words:
+            values[letter] = value
+
+        # Update modal state before motion. A block can carry several G words
+        # (for example "G20 G90"), so process all of them in order.
+        g_codes = [value for letter, value in words if letter == "G"]
+        for code in g_codes:
+            if code == 20:
+                model.units = 25.4
+            elif code == 21:
+                model.units = 1.0
+            elif code == 90:
+                model.absolute = True
+            elif code == 91:
+                model.absolute = False
+            elif code in (0, 1, 2, 3):
+                model.motion = int(code)
+            elif code == 17:
+                model.plane = "XY"
+            elif code == 18:
+                model.plane = "ZX"
+            elif code == 19:
+                model.plane = "YZ"
+        if "F" in values:
+            model.feed = values["F"] * model.units
+
+        if any(code in (4, 10, 28, 30, 53, 92) for code in g_codes) and not any(
+            code in (0, 1, 2, 3) for code in g_codes
+        ):
+            # Dwells and coordinate-setting commands do not produce a segment.
+            continue
+        if model.motion not in (0, 1, 2, 3):
+            continue
+        if not any(axis in values for axis in ("X", "Y", "Z", "I", "J")):
+            continue
+
+        target = list(model.position)
+        for index, axis in enumerate(("X", "Y", "Z")):
+            if axis in values:
+                value = values[axis] * model.units
+                target[index] = value if model.absolute else model.position[index] + value
+        end = (target[0], target[1], target[2])
+        start = model.position
+        points: list[Point] | None
+
+        if model.motion == 0:
+            kind = "rapid"
+            points = [start, end]
+        elif model.motion == 1:
+            kind = "feed"
+            points = [start, end]
+        else:
+            clockwise = model.motion == 2
+            kind = "arc_cw" if clockwise else "arc_ccw"
+            plane = model.plane
+            u, v, _ = _plane_axes(plane)
+            center = list(start)
+            center_letters = {"XY": ("I", "J"), "ZX": ("K", "I"), "YZ": ("J", "K")}[plane]
+            u_word, v_word = center_letters
+            if u_word in values or v_word in values:
+                center[u] = start[u] + values.get(u_word, 0.0) * model.units
+                center[v] = start[v] + values.get(v_word, 0.0) * model.units
+                points = _arc_points(start, end, tuple(center), clockwise, plane)  # type: ignore[arg-type]
+            elif "R" in values:
+                points = _arc_points_from_radius(
+                    start, end, values["R"] * model.units, clockwise, plane
+                )
+            else:
+                path.unsupported.add("arc without I/J/R")
+                points = None
+            if points is None:
+                kind = "feed"
+                points = [start, end]
+
+        segment = Segment(
+            kind=kind,
+            start=start,
+            end=end,
+            source_line=line.source_line,
+            points=points,
+        )
+        path.segments.append(segment)
+
+        rate = RAPID_RATE_MM_MIN if kind == "rapid" else (model.feed or 0.0)
+        if rate > 0:
+            path.estimated_seconds += segment.length / rate * 60.0
+
+        model.position = end
+        seen_z.extend((start[2], end[2]))
+
+    if path.segments:
+        starts = [segment.start for segment in path.segments]
+        ends = [segment.end for segment in path.segments]
+        all_points = starts + ends
+        low = tuple(min(point[i] for point in all_points) for i in range(3))
+        high = tuple(max(point[i] for point in all_points) for i in range(3))
+        path.bounds = (low, high)  # type: ignore[assignment]
+        if limits and any(high[i] > limits[i] for i in range(3)):
+            path.warnings.append("Toolpath extends beyond the configured machine travel.")
+    if seen_z:
+        path.min_z = min(seen_z)
+        path.max_z = max(seen_z)
+    path.tools = sorted(tools)
+    return path
+
+
+def transform_lines(
+    lines: list[ProgramLine],
+    dx: float = 0.0,
+    dy: float = 0.0,
+    dz: float = 0.0,
+    scale: float = 1.0,
+    rotate: float = 0.0,
+) -> list[str]:
+    """Offset/scale/rotate axis words, returning new text lines."""
+    if rotate:
+        cos_a = math.cos(math.radians(rotate))
+        sin_a = math.sin(math.radians(rotate))
+    result: list[str] = []
+    for line in lines:
+        words = tokenize(line.text)
+        values = {letter: value for letter, value in words}
+        if not any(axis in values for axis in ("X", "Y", "Z")):
+            result.append(line.text)
+            continue
+
+        x = values.get("X", 0.0) * scale
+        y = values.get("Y", 0.0) * scale
+        z = values.get("Z", 0.0) * scale
+        if rotate:
+            x, y = x * cos_a - y * sin_a, x * sin_a + y * cos_a
+        x += dx
+        y += dy
+        z += dz
+
+        def fmt(value: float) -> str:
+            text = f"{value:.4f}".rstrip("0").rstrip(".")
+            return "0" if text in ("-0", "") else text
+
+        out = line.text
+        for axis, value in (("X", x), ("Y", y), ("Z", z)):
+            if axis in values:
+                out = re.sub(
+                    rf"{axis}\s*[-+]?(?:\d+(?:\.\d*)?|\.\d+)",
+                    f"{axis}{fmt(value)}",
+                    out,
+                    count=1,
+                )
+        result.append(out)
+    return result

plotdeck/core/grbl_protocol.py

@@ -0,0 +1,278 @@
+"""GRBL 1.1 protocol constants, response classification and lookup tables.
+
+Pure Python; no Qt or serial imports. Everything the rest of the application
+needs to know about the wire protocol lives here.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+
+# --------------------------------------------------------------------------- #
+# Wire constants
+# --------------------------------------------------------------------------- #
+BAUD_RATE = 115200
+RX_BUFFER_SIZE = 127  # usable bytes, not 128
+MAX_LINE_LENGTH = 80
+
+STATUS_INTERVAL_MS = 200
+UNO_RESET_DELAY_S = 2.0
+
+
+class RealTime(bytes, Enum):
+    """Single-byte commands that bypass the line queue and never get an ``ok``."""
+
+    STATUS = b"?"
+    FEED_HOLD = b"!"
+    CYCLE_START = b"~"
+    SOFT_RESET = b"\x18"
+    SAFETY_DOOR = b"\x84"
+    JOG_CANCEL = b"\x85"
+
+    FEED_OVERRIDE_RESET = b"\x90"
+    FEED_OVERRIDE_PLUS_10 = b"\x91"
+    FEED_OVERRIDE_MINUS_10 = b"\x92"
+    FEED_OVERRIDE_PLUS_1 = b"\x93"
+    FEED_OVERRIDE_MINUS_1 = b"\x94"
+
+    RAPID_OVERRIDE_100 = b"\x95"
+    RAPID_OVERRIDE_50 = b"\x96"
+    RAPID_OVERRIDE_25 = b"\x97"
+
+    SPINDLE_OVERRIDE_RESET = b"\x99"
+    SPINDLE_OVERRIDE_PLUS_10 = b"\x9a"
+    SPINDLE_OVERRIDE_MINUS_10 = b"\x9b"
+    SPINDLE_OVERRIDE_PLUS_1 = b"\x9c"
+    SPINDLE_OVERRIDE_MINUS_1 = b"\x9d"
+    SPINDLE_STOP = b"\x9e"
+
+
+class ResponseKind(str, Enum):
+    OK = "ok"
+    ERROR = "error"
+    ALARM = "alarm"
+    STATUS = "status"
+    MESSAGE = "message"
+    BANNER = "banner"
+    SETTING = "setting"
+    OTHER = "other"
+
+
+@dataclass(frozen=True)
+class Response:
+    kind: ResponseKind
+    text: str
+    code: int | None = None
+    detail: str = ""
+
+    @property
+    def is_terminal(self) -> bool:
+        """True for responses that acknowledge exactly one queued line."""
+        return self.kind in (ResponseKind.OK, ResponseKind.ERROR)
+
+
+_BANNER_RE = re.compile(r"^Grbl\s+([0-9]+\.[0-9]+[a-zA-Z]?)\b")
+_ERROR_RE = re.compile(r"^error:(\d+)")
+_ALARM_RE = re.compile(r"^ALARM:(\d+)")
+_SETTING_RE = re.compile(r"^\$(\d+)=([-0-9.]+)")
+
+
+def classify(line: str) -> Response:
+    """Turn one raw line from GRBL into a :class:`Response`."""
+    text = line.strip()
+    if not text:
+        return Response(ResponseKind.OTHER, line)
+
+    if text == "ok":
+        return Response(ResponseKind.OK, text)
+
+    match = _ERROR_RE.match(text)
+    if match:
+        code = int(match.group(1))
+        return Response(ResponseKind.ERROR, text, code, error_text(code))
+
+    match = _ALARM_RE.match(text)
+    if match:
+        code = int(match.group(1))
+        return Response(ResponseKind.ALARM, text, code, alarm_text(code))
+
+    if text.startswith("<") and text.endswith(">"):
+        return Response(ResponseKind.STATUS, text)
+
+    if text.startswith("[") and text.endswith("]"):
+        return Response(ResponseKind.MESSAGE, text, detail=message_text(text))
+
+    match = _BANNER_RE.match(text)
+    if match:
+        return Response(ResponseKind.BANNER, text, detail=match.group(1))
+
+    match = _SETTING_RE.match(text)
+    if match:
+        return Response(ResponseKind.SETTING, text, int(match.group(1)), match.group(2))
+
+    return Response(ResponseKind.OTHER, text)
+
+
+def message_text(raw: str) -> str:
+    """Extract the human readable payload from a ``[TYPE:...]`` message."""
+    body = raw.strip()
+    if body.startswith("["):
+        body = body[1:]
+    if body.endswith("]"):
+        body = body[:-1]
+    if ":" in body:
+        tag, _, value = body.partition(":")
+        if tag in {"MSG", "GC", "PRB", "HLP", "OPT", "VER", "echo"}:
+            return value
+    return body
+
+
+def banner_version(raw: str) -> str | None:
+    """Return the firmware version from a welcome banner, if it is one."""
+    match = _BANNER_RE.match(raw.strip())
+    return match.group(1) if match else None
+
+
+# --------------------------------------------------------------------------- #
+# Error / alarm lookup tables (GRBL 1.1)
+# --------------------------------------------------------------------------- #
+ERROR_MESSAGES: dict[int, str] = {
+    1: "G-code word is missing its letter.",
+    2: "Numeric value is missing or malformed.",
+    3: "Unsupported or unknown '$' system command.",
+    4: "Negative value received where a positive value is required.",
+    5: "Homing cycle is not enabled in settings ($22).",
+    6: "Step pulse time must be greater than 3 microseconds.",
+    7: "EEPROM read failed; settings restored to defaults. Reset required.",
+    8: "'$' command can only be used while the machine is Idle.",
+    9: "G-code commands are locked out during an alarm or jog.",
+    10: "Soft limits require homing to be enabled ($22).",
+    11: "Maximum characters per line exceeded (80).",
+    12: "Value exceeds the maximum allowed (compile-time option).",
+    13: "Value exceeds the maximum allowed (compile-time option).",
+    14: "Value exceeds the maximum allowed (compile-time option).",
+    15: "Value exceeds the maximum allowed (compile-time option).",
+    16: "Value exceeds the maximum allowed (compile-time option).",
+    17: "Value exceeds the maximum allowed (compile-time option).",
+    18: "Value exceeds the maximum allowed (compile-time option).",
+    19: "Value exceeds the maximum allowed (compile-time option).",
+    20: "Unsupported or invalid G-code command in block.",
+    21: "More than one G-code command from the same modal group in block.",
+    22: "Feed rate has not been set or is undefined.",
+    23: "G-code command requires an integer value.",
+    24: "Two commands that require the same axis words were detected in block.",
+    25: "A G-code word was repeated in the block.",
+    26: "A G-code command is missing required axis or parameter words.",
+    27: "Numeric value is out of range.",
+    28: "Command value is not valid for the current state.",
+    29: "Unsupported coordinate system or axis word.",
+    30: "Command requires a valid value that was not supplied.",
+    31: "Command is not allowed in the current machine state.",
+    32: "Command is not allowed in the current machine state (laser mode).",
+    33: "Motion command target is invalid.",
+    34: "Arc radius value is invalid.",
+    35: "Arc endpoint is invalid for the defined radius.",
+    36: "Feed rate is required for this command.",
+    37: "Command is not allowed in the current machine state.",
+}
+
+ALARM_MESSAGES: dict[int, str] = {
+    1: "Hard limit triggered. Position is likely lost - re-home before continuing.",
+    2: "Soft limit exceeded. Target is outside machine travel; unlock to recover.",
+    3: "Reset while in motion. Position is likely lost - re-home before continuing.",
+    4: "Probe failed: probe is not in the expected initial state.",
+    5: "Probe failed: no contact with the workpiece within the travel distance.",
+    6: "Homing failed: pull-off failed to clear the limit switch.",
+    7: "Homing failed: limit switch not found within the search distance.",
+    8: "Homing failed: limit switch triggered during the search.",
+    9: "Homing failed: could not find the limit switch.",
+    10: "Homing failed: could not clear the limit switch.",
+}
+
+
+def error_text(code: int | None) -> str:
+    if code is None:
+        return "Unknown error."
+    return ERROR_MESSAGES.get(code, f"Unknown error {code}.")
+
+
+def alarm_text(code: int | None) -> str:
+    if code is None:
+        return "Unknown alarm."
+    return ALARM_MESSAGES.get(code, f"Unknown alarm {code}.")
+
+
+# --------------------------------------------------------------------------- #
+# Machine states
+# --------------------------------------------------------------------------- #
+IDLE_STATES = {"Idle"}
+RUN_STATES = {"Run", "Jog", "Home", "Check", "Sleep"}
+HOLD_STATES = {
+    "Hold",
+    "Hold:0",
+    "Hold:1",
+    "Door",
+    "Door:0",
+    "Door:1",
+    "Door:2",
+    "Door:3",
+}
+ALARM_STATES = {"Alarm"}
+
+
+def state_family(state: str) -> str:
+    """Collapse a GRBL state into one of: idle, run, hold, alarm, offline."""
+    if state in ALARM_STATES:
+        return "alarm"
+    if state in IDLE_STATES:
+        return "idle"
+    if state in HOLD_STATES:
+        return "hold"
+    if state in RUN_STATES:
+        return "run"
+    return "offline"
+
+
+# --------------------------------------------------------------------------- #
+# GRBL settings metadata (for the settings editor / limits)
+# --------------------------------------------------------------------------- #
+SETTING_INFO: dict[int, tuple[str, str]] = {
+    0: ("Step pulse, microseconds", "10"),
+    1: ("Step idle delay, milliseconds", "25"),
+    2: ("Step port invert, mask", "0"),
+    3: ("Direction port invert, mask", "0"),
+    4: ("Step enable invert, bool", "0"),
+    5: ("Limit pins invert, bool", "0"),
+    6: ("Probe pin invert, bool", "0"),
+    10: ("Status report, mask", "3"),
+    11: ("Junction deviation, mm", "0.010"),
+    12: ("Arc tolerance, mm", "0.002"),
+    13: ("Report inches, bool", "0"),
+    20: ("Soft limits, bool", "0"),
+    21: ("Hard limits, bool", "0"),
+    22: ("Homing cycle, bool", "1"),
+    23: ("Homing dir invert, mask", "0"),
+    24: ("Homing feed, mm/min", "25.000"),
+    25: ("Homing seek, mm/min", "500.000"),
+    26: ("Homing debounce, milliseconds", "250"),
+    27: ("Homing pull-off, mm", "1.000"),
+    30: ("Max spindle speed, RPM", "1000"),
+    31: ("Min spindle speed, RPM", "0"),
+    32: ("Laser mode, bool", "0"),
+    100: ("X steps/mm", "250.000"),
+    101: ("Y steps/mm", "250.000"),
+    102: ("Z steps/mm", "250.000"),
+    110: ("X max rate, mm/min", "500.000"),
+    111: ("Y max rate, mm/min", "500.000"),
+    112: ("Z max rate, mm/min", "500.000"),
+    120: ("X acceleration, mm/sec^2", "10.000"),
+    121: ("Y acceleration, mm/sec^2", "10.000"),
+    122: ("Z acceleration, mm/sec^2", "10.000"),
+    130: ("X max travel, mm", "200.000"),
+    131: ("Y max travel, mm", "200.000"),
+    132: ("Z max travel, mm", "200.000"),
+}
+
+LIMIT_SETTINGS = (130, 131, 132)