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. ESP3D/FluidNC controllers use the same GRBL session over an HTTP command endpoint and WebSocket response channel, with upload-and-execute jobs. 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.

API reference

The Python API reference under docs/api is generated from the .pyi type stubs. Regenerate it after changing the Rust bindings:

make docs

Daemon (remote sessions)

The daemon runs the driver next to the hardware — e.g. on a Raspberry Pi in the workshop — while Rayforge runs on your desk. Jobs run daemon-side and survive client disconnects. Works on Linux, macOS and Windows; full reference in docs/daemon.md.

1. Add your machine

pip install raydriver          # includes network discovery
raydriver scan                 # find your machine's serial port
raydriver daemon add /dev/ttyUSB0

add creates the config file on first use and generates a token — the password clients use to connect. It prints the token; raydriver daemon status shows it again later. The config lives in ~/.config/raydriver/daemon.json (Linux), ~/Library/Application Support/raydriver/daemon.json (macOS) or %APPDATA%\raydriver\daemon.json (Windows).

The daemon announces itself over mDNS, so Rayforge's machine wizard discovers it automatically — no manual network setup.

Defaults are GRBL at 115200 baud; for other firmware use raydriver daemon add PORT --protocol smoothie --baudrate 115200 (protocols: grbl, grbl_simple, smoothie, marlin; ESP3D and FluidNC sessions are configured in daemon.json with their host and HTTP/WebSocket ports). raydriver daemon remove PORT unconfigures a device.

2. Run the daemon

raydriver daemon               # foreground
raydriver daemon install       # or as a service

install uses a systemd user unit on Linux, a launchd LaunchAgent on macOS and a logon scheduled task on Windows. raydriver daemon status shows the service state and probes the daemon; raydriver daemon uninstall stops and removes it.

3. Check it

raydriver list                 # configured devices + connection state
raydriver connection           # connected clients + control lease
raydriver info 127.0.0.1:8765  # sessions, devices and cameras

Connecting clients

Exposing the daemon to the LAN

On loopback the token never leaves the machine, so no TLS is needed. Reaching the daemon from another computer requires a certificate and a non-loopback bind — an exposed listener refuses to start without both a token and TLS. See docs/daemon.md for the setup.

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.config import GrblSerialConfig
from raydriver.core import SessionEvent
from raydriver.grbl import GrblSession

session = GrblSession(
    config=GrblSerialConfig(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())

xTool M2

M2Session connects to the M2's WS-V2 service for state monitoring, homing, motion and control of a job already staged on the machine. It does not upload or stream G-code jobs; use xTool Studio to stage those. M2 support uses a reverse-engineered local protocol and has not yet been validated against physical hardware.

The device commonly presents a self-signed TLS certificate. Certificate validation remains enabled by default. Set tls_allow_invalid_certs only on a trusted private network if the device certificate is not trusted by the host:

import asyncio
from raydriver.core import SessionEvent
from raydriver.xtool.m2 import M2Session

async def main():
    connected = asyncio.Event()

    def on_event(event):
        if (
            isinstance(event, SessionEvent.ConnectionStatusChanged)
            and event.status == "CONNECTED"
        ):
            connected.set()

    session = M2Session(
        config={
            "host": "192.168.1.50",
            "tls_allow_invalid_certs": True,
        },
        event_callback=on_event,
    )
    await session.connect()
    await asyncio.wait_for(connected.wait(), timeout=15)
    await session.disconnect()

asyncio.run(main())

The session also exposes home, move_to, jog, start, set_hold and cancel for supported machine-control operations. connect starts the connection loop; wait for the CONNECTED connection-status event before issuing machine commands.

Metadata

Release files for raydriver 1.11.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.11.0
File Size Uploaded Provenance Actions
raydriver-1.11.0.tar.gz 346.1 kB With provenance Details for raydriver-1.11.0.tar.gz

Built distributions (wheels)

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

Total release size: 21.9 MB

Release files / raydriver-1.11.0.tar.gz

Download URL raydriver-1.11.0.tar.gz
Size 346.1 kB
Tags Source
SHA-256 checksum
How to use checksums
5425a748aff5ea5a888808c2c69d92e4886c403a7a9b9a44c0c34e85a5486996
BLAKE2b-256 checksum
How to use checksums
6278c0ad134f74f3d78a0cc558cba59d2770a8c9866804d125fd341f8d30911d
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 18, 2026.

Transparency log

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

Download URL raydriver-1.11.0-cp311-abi3-win_amd64.whl
Size 4.2 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
3cabe7db7a8c554b2c5d60d635196ff734b7350cc89cbae80cf809549ae4b0a2
BLAKE2b-256 checksum
How to use checksums
cca47e9ff08c02ffb3066a166a4d6447221750135569c9f243fa4ac65ade992b
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 18, 2026.

Transparency log

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

Download URL raydriver-1.11.0-cp311-abi3-manylinux_2_34_x86_64.whl
Size 4.5 MB
Tags CPython 3.11 Linux glibc 2.34+ x86-64 abi3
SHA-256 checksum
How to use checksums
2846b018ce73595a30b2e48ead195c737623341526772f6ddb228effef3cf651
BLAKE2b-256 checksum
How to use checksums
4aef6c1db99c7260038358c0d9059bc6c5df4ce17530c8463b30b2bce9bf67da
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 18, 2026.

Transparency log

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

Download URL raydriver-1.11.0-cp311-abi3-manylinux_2_34_aarch64.whl
Size 4.6 MB
Tags CPython 3.11 Linux glibc 2.34+ ARM64 abi3
SHA-256 checksum
How to use checksums
a86a99aee6bb649768c9e845f618f8e237209defd941dc3b23a8391ce2c45cd6
BLAKE2b-256 checksum
How to use checksums
5828e58e7e85a7a981f8f18b4e4016a5355c266571671fbe377726a3ab6cbd44
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 18, 2026.

Transparency log

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

Download URL raydriver-1.11.0-cp311-abi3-macosx_11_0_arm64.whl
Size 4.1 MB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
8c1aabac8099c9657765db61f7c8a7c181ad086cd00d3147a50cdd054f0eed65
BLAKE2b-256 checksum
How to use checksums
aafda9d55fd4780c3c4f7e62bf1b7dc04975ccc0bc3557d780f6040a54e6eed0
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 18, 2026.

Transparency log

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

Download URL raydriver-1.11.0-cp311-abi3-macosx_10_12_x86_64.whl
Size 4.3 MB
Tags CPython 3.11 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
553de94c08320554e6474760d4de14e02ffa0a4b8a41fe3bef00ebde5ee0f30c
BLAKE2b-256 checksum
How to use checksums
fc102bbd067d801be399d518b3cb74f6cb8931946ae649e7bac1e598f3d9b33a
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 18, 2026.

Transparency log

Security for raydriver 1.11.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.11.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 18, 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.11.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