मुख्य सामग्री पर जाएँ

raydriver.grbl

GRBL device drivers implemented in Rust.

The central type is GrblSession: it owns the connection lifecycle (handshake, status polling, reconnect), interactive commands, and job streaming with character-counting flow control, stall detection and deadlock recovery. GrblSimpleSession (raydriver.grbl.simple) is the minimal alternative: strict ping-pong, for hardware where the full driver misbehaves. Dialects remain data owned by Rayforge: resolved command templates are passed into the session.

GrblSession​

A GRBL device session: connection lifecycle, streaming and interactive commands, entirely in Rust.

All async methods return asyncio futures; a typed SessionEvent is delivered to event_callback(event) on the event loop thread.

buffer_count​

buffer_count: int

job_running​

job_running: bool

pending_commands​

pending_commands: list[str]

Commands awaiting their 'ok' acknowledgement.

resource_uri​

resource_uri: Optional[str]

rx_buffer_size​

rx_buffer_size: int

state​

state: types.DeviceState

Current snapshot of the device state.

cancel()​

cancel(emergency: bool = False) -> Any

Abort the running job: soft reset, queue cleanup and safety shutdown.

ParameterTypeDescription
emergencybool = False
ReturnsAny

connect()​

connect() -> Any

Open the connection and start the background tasks.

ParameterTypeDescription
ReturnsAny

detect_unit_system()​

detect_unit_system() -> Any

Infer the device's unit system ("metric"/"imperial") from the $13 setting.

ParameterTypeDescription
ReturnsAny

disconnect()​

disconnect() -> Any

Stop all background tasks and close the transport.

ParameterTypeDescription
ReturnsAny

execute_command()​

execute_command(command: str) -> Any

Queue a command for asynchronous processing and await its response.

ParameterTypeDescription
commandstr
ReturnsAny

execute_interactive_command()​

execute_interactive_command(command: str) -> Any

Send a command and synchronously await its full response, blocking any other command from interleaving.

ParameterTypeDescription
commandstr
ReturnsAny

home()​

home(axes: Optional[Sequence[str]] = None, active_wcs: str = 'G54') -> Any

Home all axes (axes is None) or the named axes (e.g. ["X"]), then re-activate the active WCS via the toggle workaround.

ParameterTypeDescription
axesOptional[Sequence[str]] = None
active_wcsstr = 'G54'
ReturnsAny

jog()​

jog(speed: float, deltas: Sequence[tuple[str, float]]) -> Any

Jog by relative deltas (mm) at speed (mm/min).

ParameterTypeDescription
speedfloat
deltasSequence[tuple[str, float]]
ReturnsAny

move_to()​

move_to(speed: float, x: float, y: float) -> Any

Move to an absolute position (mm) at speed (mm/min).

ParameterTypeDescription
speedfloat
xfloat
yfloat
ReturnsAny

read_parser_state()​

read_parser_state() -> Any

Read the $G parser state to determine the active WCS.

ParameterTypeDescription
ReturnsAny

read_settings()​

read_settings() -> Any

Read $$ into (key, raw_value) pairs.

ParameterTypeDescription
ReturnsAny

read_wcs_offsets()​

read_wcs_offsets() -> Any

Read $# WCS offsets, converted to mm when the device reports inches.

ParameterTypeDescription
ReturnsAny

run()​

run(
gcode: str,
op_line_map: Optional[Mapping[int, int]] = None,
op_estimates: Optional[Sequence[float]] = None,
progress_callback: Optional[Any] = None,
) -> Any

Stream a G-code program using the character-counting protocol.

op_line_map maps G-code line indices to op indices for progress reporting; op_estimates holds per-op estimated durations (seconds) used to scale per-line stall timeouts.

ParameterTypeDescription
gcodestr
op_line_mapOptional[Mapping[int, int]] = None
op_estimatesOptional[Sequence[float]] = None
progress_callbackOptional[Any] = None
ReturnsAny

run_probe_cycle()​

run_probe_cycle(axis_letter: str, max_travel: float, feed_rate: float) -> Any

Run a probe cycle (G38.2); returns the trigger position in mm or None on failure.

ParameterTypeDescription
axis_letterstr
max_travelfloat
feed_ratefloat
ReturnsAny

run_raw()​

run_raw(machine_code: str) -> Any

Execute a raw G-code string; GRBL realtime commands (?, ~, !) are sent via the control path instead of the stream.

ParameterTypeDescription
machine_codestr
ReturnsAny

select_tool()​

select_tool(tool_number: int) -> Any
ParameterTypeDescription
tool_numberint
ReturnsAny

set_focus_power()​

set_focus_power(power: Optional[float] = None) -> Any

Set laser power for focus mode; None waits for pending jogs to finish and turns the laser off.

ParameterTypeDescription
powerOptional[float] = None
ReturnsAny

set_hold()​

set_hold(hold: bool = True) -> Any

Pause (feed hold) or resume the device.

ParameterTypeDescription
holdbool = True
ReturnsAny

set_power()​

set_power(power: Optional[float] = None) -> Any

Set laser power. power is the absolute S value; None (or zero) turns the laser off.

ParameterTypeDescription
powerOptional[float] = None
ReturnsAny

set_wcs_offset()​

set_wcs_offset(wcs_slot: str, x: float, y: float, z: Optional[float]) -> Any
ParameterTypeDescription
wcs_slotstr
xfloat
yfloat
zOptional[float]
ReturnsAny

update_dialect()​

update_dialect(dialect: dict) -> None

Swap the dialect command templates at runtime.

ParameterTypeDescription
dialectdict
ReturnsNone

with_transport()​

with_transport(
transport: transport.MockTransport,
config: Optional[Union[dict, config.SessionConfig]] = None,
dialect: Optional[dict] = None,
event_callback: Optional[Callable[[core.SessionEvent], Any]] = None,
) -> GrblSession

Build a session around a [MockTransport] (for tests).

ParameterTypeDescription
transporttransport.MockTransport
configOptional[Union[dict, config.SessionConfig]] = None
dialectOptional[dict] = None
event_callbackOptional[Callable[[core.SessionEvent], Any]] = None
ReturnsGrblSession

write_setting()​

write_setting(key: str, value: str) -> Any
ParameterTypeDescription
keystr
valuestr
ReturnsAny