Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

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.0b5

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.0b5
File Size Uploaded Provenance Actions
raydriver-1.0.0b5.tar.gz 157.6 kB With provenance Details for raydriver-1.0.0b5.tar.gz

Built distributions (wheels)

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

Total release size: 10.7 MB

Release files / raydriver-1.0.0b5.tar.gz

Download URL raydriver-1.0.0b5.tar.gz
Size 157.6 kB
Tags Source
SHA-256 checksum
How to use checksums
77065fd7305321d4208ddd2bb9a94d35fdb8981caa46fbede29af0f59f4ae63a
BLAKE2b-256 checksum
How to use checksums
43bceaaed425be3f0d78c7556804ba0076798a433f8d0bd1604da32560ace216
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 Oct 31, 2026.

Transparency log

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

Download URL raydriver-1.0.0b5-cp311-abi3-win_amd64.whl
Size 2.0 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
ab553918a27ccefee7eb9f9cc009007fa0d09fbc9a9c436625a24812bec223e1
BLAKE2b-256 checksum
How to use checksums
cf252ea02eb69d45ecbb312bd482c794d9f789b8c0e6095816a55c7af367c620
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 Oct 31, 2026.

Transparency log

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

Download URL raydriver-1.0.0b5-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
a1d41b35955c1afb92d72ff76b983b5843deefbd9c01109ca790101d7ae7232c
BLAKE2b-256 checksum
How to use checksums
abd73f7ccbd1665226a91211aedfdd69bc64eddd1f08a66304af9962a4a11997
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 Oct 31, 2026.

Transparency log

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

Download URL raydriver-1.0.0b5-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
03989ce5bcf0b61f89139c0e2c15732812191f4b537fd6103fda9326d326b5c1
BLAKE2b-256 checksum
How to use checksums
f4ff5089089d325794ac25415dbdc7b933eb58ef91cc2a2bdfec1291dc58770d
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 Oct 31, 2026.

Transparency log

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

Download URL raydriver-1.0.0b5-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
9ca128f31cdce0afb02b06c9c083550756978173aa697aed0e8c89d463442cbf
BLAKE2b-256 checksum
How to use checksums
2f97974489eb7d6188cb20471d8ef48c7112375a9a22fcde1986a309c1f0e667
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 Oct 31, 2026.

Transparency log

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

Download URL raydriver-1.0.0b5-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
eef5791ebadd5e9aa8530900d09bc7dd2646bad45287d0e3640e6fd87387b7c6
BLAKE2b-256 checksum
How to use checksums
ee6438eb0ab7a316d76f2dc2042c0488d0f9d2a5cdf0d6e45b5ac7aecfef1756
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 Oct 31, 2026.

Transparency log

Security for raydriver 1.0.0b5

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.0b5.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 Oct 31, 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
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