LinuxCNC gRPC Documentation on LinuxCNC gRPC

Server Setup

Mon, 01 Jan 0001 00:00:00 +0000

How to install and run the linuxcnc-grpc server on your LinuxCNC machine.

Prerequisites#

A Linux machine with LinuxCNC installed (physical or simulation)
Python 3.9+ (included with most LinuxCNC installations)
Network access if you want to connect from a remote machine

Install#

SSH into your LinuxCNC machine (or open a terminal on it) and install:

pip install linuxcnc-grpc

Or with uv:

uv pip install linuxcnc-grpc

This installs both the gRPC server and the Python client library.

Client Quickstart

Mon, 01 Jan 0001 00:00:00 +0000

Install a client library and make your first API calls. This guide assumes you already have a running gRPC server.

Client Installation#

Python

pip install linuxcnc-grpc

go get github.com/dougcalobrisi/linuxcnc-grpc

Node.js / TypeScript

npm install linuxcnc-grpc

Rust

Add to Cargo.toml:

[dependencies]
linuxcnc-grpc = "1.0"
tokio = { version = "1", features = ["full"] }
tonic = "0.12"

Quick Start Examples#

Python

import grpc
from linuxcnc_pb import linuxcnc_pb2, linuxcnc_pb2_grpc

# Connect to server
channel = grpc.insecure_channel("localhost:50051")
stub = linuxcnc_pb2_grpc.LinuxCNCServiceStub(channel)

# Get status
status = stub.GetStatus(linuxcnc_pb2.GetStatusRequest())

# Print position
pos = status.position.actual_position
print(f"Position: X={pos.x:.3f} Y={pos.y:.3f} Z={pos.z:.3f}")

# Print machine state
print(f"Mode: {linuxcnc_pb2.TaskMode.Name(status.task.task_mode)}")
print(f"State: {linuxcnc_pb2.TaskState.Name(status.task.task_state)}")

channel.close()

package main

import (
 "context"
 "fmt"
 "log"

 pb "github.com/dougcalobrisi/linuxcnc-grpc/packages/go"
 "google.golang.org/grpc"
 "google.golang.org/grpc/credentials/insecure"
)

func main() {
 // Connect to server
 conn, err := grpc.NewClient("localhost:50051",
 grpc.WithTransportCredentials(insecure.NewCredentials()))
 if err != nil {
 log.Fatalf("Failed to connect: %v", err)
 }
 defer conn.Close()

 client := pb.NewLinuxCNCServiceClient(conn)

 // Get status
 status, err := client.GetStatus(context.Background(), &pb.GetStatusRequest{})
 if err != nil {
 log.Fatalf("GetStatus failed: %v", err)
 }

 // Print position
 pos := status.Position.ActualPosition
 fmt.Printf("Position: X=%.3f Y=%.3f Z=%.3f\n", pos.X, pos.Y, pos.Z)
}

Node.js / TypeScript

import * as grpc from "@grpc/grpc-js";
import { LinuxCNCServiceClient, GetStatusRequest, TaskMode, TaskState } from "linuxcnc-grpc";

// Connect to server
const client = new LinuxCNCServiceClient(
 "localhost:50051",
 grpc.credentials.createInsecure()
);

// Get status
client.getStatus(GetStatusRequest.create(), (err, status) => {
 if (err) {
 console.error("Error:", err);
 return;
 }

 // Print position
 const pos = status!.position!.actualPosition!;
 console.log(`Position: X=${pos.x.toFixed(3)} Y=${pos.y.toFixed(3)} Z=${pos.z.toFixed(3)}`);

 // Print machine state
 console.log(`Mode: ${TaskMode[status!.task!.taskMode]}`);
 console.log(`State: ${TaskState[status!.task!.taskState]}`);
});

Rust

use linuxcnc_grpc::linuxcnc::linux_cnc_service_client::LinuxCncServiceClient;
use linuxcnc_grpc::linuxcnc::GetStatusRequest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
 // Connect to server
 let mut client = LinuxCncServiceClient::connect("http://localhost:50051").await?;

 // Get status
 let response = client.get_status(GetStatusRequest {}).await?;
 let status = response.into_inner();

 // Print position
 if let Some(position) = &status.position {
 if let Some(pos) = &position.actual_position {
 println!("Position: X={:.3} Y={:.3} Z={:.3}", pos.x, pos.y, pos.z);
 }
 }

 Ok(())
}

Sending Commands#

Commands follow a consistent pattern across all languages:

Step-by-Step Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

A hands-on guide to connecting to a remote LinuxCNC machine from your development box using any of the supported client languages.

Prerequisites#

LinuxCNC running on a machine (physical or simulation)
Network access between your dev machine and the LinuxCNC machine
The LinuxCNC machine’s IP address (referred to as LINUXCNC_IP below)

Step 1: Install and Start the gRPC Server#

SSH into your LinuxCNC machine and install the server:

pip install linuxcnc-grpc

Start the server (LinuxCNC must already be running):

Server Configuration

Mon, 01 Jan 0001 00:00:00 +0000

The linuxcnc-grpc server runs on your LinuxCNC machine and exposes both LinuxCNCService and HalService over gRPC.

Requirements#

Linux with LinuxCNC installed and running
Python 3.9+
Network access to the machine (for remote clients)

Installation#

pip install linuxcnc-grpc
# or with uv
uv pip install linuxcnc-grpc

Basic Usage#

Start LinuxCNC first, then start the gRPC server:

linuxcnc-grpc --host 0.0.0.0 --port 50051

Or run as a Python module:

python -m linuxcnc_grpc.server --host 0.0.0.0 --port 50051

Command Line Options#

Option	Default	Description
`--host`	`0.0.0.0`	Address to bind to. Use `127.0.0.1` for local-only access
`--port`	`50051`	Port number to listen on
`--nc-files`	`/home/linuxcnc/linuxcnc/nc_files`	Directory for G-code file operations
`--debug`	off	Enable debug logging

Auto-Start with LinuxCNC#

Method 1: HAL File#

Add to your machine’s HAL file (e.g., your_machine.hal):

API Reference

Mon, 01 Jan 0001 00:00:00 +0000

Complete API documentation for LinuxCNC gRPC services.

LinuxCNCService#

Main service for machine control and status monitoring.

GetStatus#

Get the current machine status.

rpc GetStatus(GetStatusRequest) returns (LinuxCNCStatus)

Request: GetStatusRequest (empty message)

Response: LinuxCNCStatus containing:

Field	Type	Description
`timestamp`	int64	Unix timestamp in nanoseconds
`version`	string	LinuxCNC version
`task`	TaskStatus	Task/interpreter state
`trajectory`	TrajectoryStatus	Motion planning state
`position`	PositionStatus	All position information
`joints`	JointStatus[]	Per-joint status (up to 16)
`axes`	AxisStatus[]	Per-axis status (up to 9: XYZABCUVW)
`spindles`	SpindleStatus[]	Per-spindle status (up to 8)
`tool`	ToolStatus	Tool table and current tool
`io`	IOStatus	Digital/analog I/O state
`gcode`	GCodeStatus	Active G-codes and M-codes
`limits`	LimitStatus	Limit switch states
`errors`	ErrorMessage[]	Pending error messages

Example (Python):

Examples Guide

Mon, 01 Jan 0001 00:00:00 +0000

Walkthrough of the example code provided with linuxcnc-grpc.

Overview#

Examples are provided in four languages, each implementing the same functionality:

Example	Description
`get_status`	Poll and display machine status
`stream_status`	Real-time status streaming
`jog_axis`	Interactive jogging with keyboard
`mdi_command`	Execute G-code via MDI
`hal_query`	Query HAL pins, signals, parameters
`upload_file`	Upload, list, and delete G-code files

Directory Structure#

examples/
├── python/
│ ├── get_status.py
│ ├── stream_status.py
│ ├── jog_axis.py
│ ├── mdi_command.py
│ ├── hal_query.py
│ └── upload_file.py
├── go/
│ └── cmd/
│ ├── get_status/
│ ├── stream_status/
│ ├── jog_axis/
│ ├── mdi_command/
│ ├── hal_query/
│ └── upload_file/
├── node/
│ ├── get_status.ts
│ ├── stream_status.ts
│ ├── jog_axis.ts
│ ├── mdi_command.ts
│ ├── hal_query.ts
│ └── upload_file.ts
├── rust/
│ ├── Cargo.toml
│ └── src/bin/
│ ├── get_status.rs
│ ├── stream_status.rs
│ ├── jog_axis.rs
│ ├── mdi_command.rs
│ ├── hal_query.rs
│ └── upload_file.rs
└── README.md

Running Examples#

Prerequisites#

LinuxCNC running (or use a mock server for testing)
gRPC server running on the LinuxCNC machine
Language-specific dependencies installed

Python

cd examples/python

# Install dependencies (if using virtualenv)
pip install grpcio linuxcnc-grpc

# Run an example
python get_status.py --host localhost --port 50051

cd examples/go

# Download dependencies
go mod download

# Run an example
go run ./cmd/get_status --host localhost --port 50051

Node.js / TypeScript

cd examples/node

# Install dependencies
npm install

# Run an example
npx tsx get_status.ts --host localhost --port 50051

Rust

cd examples/rust

# Build all examples
cargo build --release

# Run an example
cargo run --bin get_status -- --host localhost --port 50051

# Or run the built binary directly
./target/release/get_status --host localhost --port 50051

get_status#

The simplest example - polls the machine once and displays status.

End-to-End Testing

Mon, 01 Jan 0001 00:00:00 +0000

The e2e test suite (tests/test_e2e.py) runs against a real LinuxCNC simulator instance, validating that the gRPC server works correctly with actual LinuxCNC state, commands, HAL data, and file management.

What E2E Tests Cover#

The suite has ~50 tests organized into these areas:

Status — version, joints, INI filename, positions, task state
State transitions — estop/recovery, on/off, mode changes
Commands — homing, MDI G-code, feedrate/spindle overrides
WaitComplete — blocking until commands finish, timeout behavior
G-code execution — upload/open/run, pause/resume, abort, single-step
Jogging — incremental and continuous jog with stop
Coolant — mist and flood on/off
Rapid rate & max velocity — override scales
Override config — feed/spindle override enable/disable
Program options — optional stop, block delete
Negative paths — empty MDI, wrong mode, invalid axis, path traversal, duplicate upload
Streaming — StreamStatus, StreamErrors
HAL — GetSystemStatus, QueryPins/Signals/Components/Params, GetValue, StreamStatus, SendCommand, WatchValues
File management — upload/list/delete cycle

These tests catch issues that mock-based tests cannot: