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.
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 # add [daemon] for mDNS announce
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).
Defaults are GRBL at 115200 baud; for other firmware use
raydriver daemon add PORT --protocol smoothie --baudrate 115200
(protocols: grbl, grbl_simple, smoothie, marlin).
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
- Rayforge: follow the first-time setup guide on the Rayforge website.
- Any other raydriver consumer: connect through the client API — see docs/daemon.md.
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:
- Configure a PyPI trusted publisher for this repository once
(owner
barebaric, reporaydriver, workflowrelease.yml, environmentpypi). 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.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| raydriver-1.3.0.tar.gz | 210.5 kB | With provenance | Details for raydriver-1.3.0.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| raydriver-1.3.0-cp311-abi3-win_amd64.whl | CPython 3.11 | abi3 | Windows x86-64 | Details for raydriver-1.3.0-cp311-abi3-win_amd64.whl |
| raydriver-1.3.0-cp311-abi3-manylinux_2_34_x86_64.whl | CPython 3.11 | abi3 | Linux glibc 2.34+ x86-64 | Details for raydriver-1.3.0-cp311-abi3-manylinux_2_34_x86_64.whl |
| raydriver-1.3.0-cp311-abi3-manylinux_2_34_aarch64.whl | CPython 3.11 | abi3 | Linux glibc 2.34+ ARM64 | Details for raydriver-1.3.0-cp311-abi3-manylinux_2_34_aarch64.whl |
| raydriver-1.3.0-cp311-abi3-macosx_11_0_arm64.whl | CPython 3.11 | abi3 | macOS 11.0+ ARM64 | Details for raydriver-1.3.0-cp311-abi3-macosx_11_0_arm64.whl |
| raydriver-1.3.0-cp311-abi3-macosx_10_12_x86_64.whl | CPython 3.11 | abi3 | macOS 10.12+ x86-64 | Details for raydriver-1.3.0-cp311-abi3-macosx_10_12_x86_64.whl |
Total release size: 11.1 MB
Release files / raydriver-1.3.0.tar.gz
| Download URL | raydriver-1.3.0.tar.gz |
|---|---|
| Size | 210.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6b9fa9f04b9080d122c5d48c345e959da9a0d60985a061434e4a13af5668e8cf
|
|
BLAKE2b-256 checksum How to use checksums |
01dd534ea11cc6c097a61b578f1986aa3b2c712f6a9f33bd0a26e8aa573cef60
|
| 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 13, 2026.
Transparency logRelease files / raydriver-1.3.0-cp311-abi3-win_amd64.whl
| Download URL | raydriver-1.3.0-cp311-abi3-win_amd64.whl |
|---|---|
| Size | 2.1 MB |
| Tags | CPython 3.11 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
2b1a370bba6f0d5c605bac8cdc27cc8729110b598398f87b9a2992c1d18732b6
|
|
BLAKE2b-256 checksum How to use checksums |
f3d8d069728f2b0be27a9d89a13bfdea0cb6e09f57d96656e878c71348b5dec0
|
| 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 13, 2026.
Transparency logRelease files / raydriver-1.3.0-cp311-abi3-manylinux_2_34_x86_64.whl
| Download URL | raydriver-1.3.0-cp311-abi3-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 2.3 MB |
| Tags | CPython 3.11 Linux glibc 2.34+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
99655c14c7421a74a105cbb3ff13fcdb45a1b90716db2762206b9158a286c127
|
|
BLAKE2b-256 checksum How to use checksums |
c99b361618ff082712b360581399c9db3df7c05c8dd0eb8330407c24c1ae4650
|
| 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 13, 2026.
Transparency logRelease files / raydriver-1.3.0-cp311-abi3-manylinux_2_34_aarch64.whl
| Download URL | raydriver-1.3.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 |
765e8195728c8904d7102afc1b95ff5ebc3e89790d7338709481af57486630cd
|
|
BLAKE2b-256 checksum How to use checksums |
1c2315750f93613863dc9cbf0b5c82fd8adfa531676581031267e0fed88ba69e
|
| 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 13, 2026.
Transparency logRelease files / raydriver-1.3.0-cp311-abi3-macosx_11_0_arm64.whl
| Download URL | raydriver-1.3.0-cp311-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 2.1 MB |
| Tags | CPython 3.11 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
0212c6fac5d826384b2728dc432e129dcf2b7336e507165d91e9e89ea7466dc4
|
|
BLAKE2b-256 checksum How to use checksums |
21679a27aecbbd74e149698cb4d0aab3a98aa581df3c97c985a2dd5b864f2acb
|
| 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 13, 2026.
Transparency logRelease files / raydriver-1.3.0-cp311-abi3-macosx_10_12_x86_64.whl
| Download URL | raydriver-1.3.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 |
73a3d6eea147c5e0fe987a0709b9d910545ee675951a6508ed77fad7b7bc5ea3
|
|
BLAKE2b-256 checksum How to use checksums |
188bea5fe17716af4d33b2fddda949230450ca53649e9d104405ca8f5d682b03
|
| 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 13, 2026.
Transparency logSecurity for raydriver 1.3.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.
Attestation for raydriver-1.3.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 13, 2026.
Transparency logA 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.