Skip to main content

raydriver

Rust-native machine drivers for Rayforge, exposed to Python via PyO3.

Currently this provides a full port of Rayforge's advanced GRBL serial driver: character-counting flow control, handshake and status polling, interactive command queue, job streaming with stall detection and deadlock recovery, cancel/safety-shutdown semantics, settings and WCS access, and probe cycles. Dialects (command templates) remain data owned by Rayforge and are passed in resolved form.

CLI

The raydriver command runs G-code against a real device with live progress, or against the built-in firmware emulator for hardware-free dry runs:

raydriver run job.gcode --port /dev/ttyUSB0 --baudrate 115200
raydriver run job.gcode --emulator          # no hardware needed
raydriver status --port /dev/ttyUSB0 --seconds 5

While a job runs, raydriver run shows acknowledged lines, a progress bar, the device state, machine position, feed rate and ETA; Ctrl-C cancels the job and runs the safety shutdown.

Protocol analyzer

The analyzer captures device traffic, decodes it to a readable listing, and replays or proxies it — the workflow for developing protocols without hardware and for characterizing real controllers. Captures are editable JSONL (text lines or base64 for binary protocols), and decoders plug in per protocol (grbl ships first; raw and hex cover the rest).

# Record a session (or --emulator for a hardware-free dry run)
raydriver analyzer record --port /dev/ttyUSB0 --out cap.jsonl
raydriver analyzer tui --port /dev/ttyUSB0     # interactive monitor

# Print a capture as a decoded listing
raydriver analyzer decode cap.jsonl

# Replay captured frames at a device, at up to Nx speed
raydriver analyzer replay cap.jsonl --to 192.168.1.50:23 --speed 10

# Man-in-the-middle: point an application at the proxy in front of
# a TCP device and record both directions
raydriver analyzer proxy --upstream 192.168.1.50:23 --out mitm.jsonl

Golden tests pin wire behavior: deterministic scenarios run against the firmware emulators, and their decoded listings are diffed against fixtures under tests/golden/ (regenerate with RAYDRIVER_REGEN_GOLDEN=1). Captures from real hardware can be dropped in as fixtures the same way, so protocol changes that alter what goes over the wire fail loudly.

Security policy

Analyzer network endpoints are hardened before any socket opens:

  • listeners bind loopback (127.0.0.1) without authentication by default;
  • non-loopback or wildcard binds require both a token and TLS — there is no override;
  • explicitly configured authentication is never dropped.

Token checks and TLS handshakes are covered by tests that drive the real sockets and assert on the outcomes.

Releases

Releasing mirrors the Raygeo flow:

  1. Configure a PyPI trusted publisher for this repository once (owner barebaric, repo raydriver, workflow release.yml, environment pypi).
  2. gh release create v0.1.0 --title "v0.1.0" --generate-notes

The Build and Publish workflow then stamps the version from the tag, builds wheels (Linux/Windows/macOS) and an sdist, publishes to PyPI via OIDC, and attaches the artifacts to the GitHub release.

Development

make venv && source .venv/bin/activate
make dev     # build + install (do this before testing)
make test    # pytest suite (all tests are Python-based)
make check   # lint + test

Usage

import asyncio
from raydriver.grbl import GrblSession, SessionEvent

session = GrblSession(
    config={"port": "/dev/ttyUSB0", "baudrate": 115200},
    dialect={
        "home_all": "$H",
        "home_axis": "$H{axis_letter}",
        "clear_alarm": "$X",
        "laser_on": "M4 S{power:.0f}",
        "laser_off": "M5",
    },
    event_callback=on_event,
)

def on_event(event: SessionEvent):
    match event:
        case SessionEvent.StateChanged():
            print("device state:", event.state.status.name)
        case SessionEvent.ConnectionStatusChanged(status=status):
            print("connection:", status)
        case SessionEvent.RawRx(line=line):
            print("<<", line)
        case SessionEvent.RawTx(line=line):
            print(">>", line)

async def main():
    await session.connect()
    print(await session.execute_interactive_command("$I"))
    await session.disconnect()

asyncio.run(main())

Metadata

Release files for raydriver 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for raydriver 1.0.0
File Size Uploaded Provenance Actions
raydriver-1.0.0.tar.gz 158.1 kB With provenance Details for raydriver-1.0.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for raydriver 1.0.0
File Actions
raydriver-1.0.0-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for raydriver-1.0.0-cp311-abi3-win_amd64.whl
raydriver-1.0.0-cp311-abi3-manylinux_2_34_x86_64.whl CPython 3.11 abi3 Linux glibc 2.34+ x86-64 Details for raydriver-1.0.0-cp311-abi3-manylinux_2_34_x86_64.whl
raydriver-1.0.0-cp311-abi3-manylinux_2_34_aarch64.whl CPython 3.11 abi3 Linux glibc 2.34+ ARM64 Details for raydriver-1.0.0-cp311-abi3-manylinux_2_34_aarch64.whl
raydriver-1.0.0-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for raydriver-1.0.0-cp311-abi3-macosx_11_0_arm64.whl
raydriver-1.0.0-cp311-abi3-macosx_10_12_x86_64.whl CPython 3.11 abi3 macOS 10.12+ x86-64 Details for raydriver-1.0.0-cp311-abi3-macosx_10_12_x86_64.whl

Total release size: 10.7 MB

Release files / raydriver-1.0.0.tar.gz

Download URL raydriver-1.0.0.tar.gz
Size 158.1 kB
Tags Source
SHA-256 checksum
How to use checksums
2f9c9ad0b1bb7994cbcd183f3f0a4a5f07a8f1b5810cd0fc3c07dfd6f1907d74
BLAKE2b-256 checksum
How to use checksums
cd67c95a3acfbd1fbb3d5a4e8622a3cb57cb62d417e6621737235d49ffeed2b2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / raydriver-1.0.0-cp311-abi3-win_amd64.whl

Download URL raydriver-1.0.0-cp311-abi3-win_amd64.whl
Size 2.0 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
c2530bd5490a5d2c63879f8394c0ee8f3c923e70db8ddd4541d57da47c897ccf
BLAKE2b-256 checksum
How to use checksums
0b77c789fb71fc7d624d80e0560d85d85e7bee048b124715665ab752cd9d22e5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / raydriver-1.0.0-cp311-abi3-manylinux_2_34_x86_64.whl

Download URL raydriver-1.0.0-cp311-abi3-manylinux_2_34_x86_64.whl
Size 2.2 MB
Tags CPython 3.11 Linux glibc 2.34+ x86-64 abi3
SHA-256 checksum
How to use checksums
d7cf6dcbffa9e3f5dd9a297b82d528d943ea0f58ee4b9098f5c7ada13b6c6487
BLAKE2b-256 checksum
How to use checksums
c0b2ad645e3baea9c0bf3e7b82fbc73ed05909d240cce17eb231acbb67606905
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / raydriver-1.0.0-cp311-abi3-manylinux_2_34_aarch64.whl

Download URL raydriver-1.0.0-cp311-abi3-manylinux_2_34_aarch64.whl
Size 2.3 MB
Tags CPython 3.11 Linux glibc 2.34+ ARM64 abi3
SHA-256 checksum
How to use checksums
716f5379d5b9cd955d5f2df88f5a990a375a9ed4c42aa0a6ec62df79b95356bd
BLAKE2b-256 checksum
How to use checksums
beb675485739532cba174458aa4360bbad48e52ba179001db8e2eecd16e0a144
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / raydriver-1.0.0-cp311-abi3-macosx_11_0_arm64.whl

Download URL raydriver-1.0.0-cp311-abi3-macosx_11_0_arm64.whl
Size 2.0 MB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
d41b5b7c2270d94aa1ef05b4262d30246bd5f7243d40ce6e4dd1d45cd3490984
BLAKE2b-256 checksum
How to use checksums
16e8c322fe3a360cfc8dcfad599eb66411842de5c878baaa1d3119ad9b7e42aa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / raydriver-1.0.0-cp311-abi3-macosx_10_12_x86_64.whl

Download URL raydriver-1.0.0-cp311-abi3-macosx_10_12_x86_64.whl
Size 2.1 MB
Tags CPython 3.11 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
0227a675e21b0faaebdc4a58658c7126bd4d8f14760599206b3842088ef372a0
BLAKE2b-256 checksum
How to use checksums
7f3e092c58ad92b218524052c043cdc0bb898ccadef1718ac4b09ec2e890c944
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Security for raydriver 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 6 files in this release have been uploaded with provenance metadata.

Select from 6 files

Attestation for raydriver-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

6 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page