linuxcnc-grpc

gRPC interface for LinuxCNC machine control and HAL (Hardware Abstraction Layer).

Why gRPC?

LinuxCNC's native Python API only works locally. This project exposes it over gRPC, enabling:

• Remote monitoring - Build web dashboards, mobile apps, or desktop GUIs
• Multi-machine management - Monitor a fleet of CNC machines from one place
• Any-language integration - Use Go, Node.js, Rust, or any gRPC-supported language
• Real-time streaming - Subscribe to status updates instead of polling

Installation

npm install linuxcnc-grpc

npm package

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

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

client.getStatus(GetStatusRequest.create(), (err, status) => {
  console.log(`Position: X=${status.position.x.toFixed(3)} Y=${status.position.y.toFixed(3)}`);
});

Examples

See the examples directory for complete Node.js/TypeScript examples:

• get_status — Poll machine status
• stream_status — Real-time status streaming
• jog_axis — Jog axes with keyboard
• mdi_command — Execute G-code via MDI
• hal_query — Query HAL pins/signals
• upload_file — Upload, list, delete G-code files

Services

• LinuxCNCService — Machine control: status, jogging, MDI, program execution, file management
• HalService — HAL introspection: query pins, signals, parameters (read-only)

Documentation

See the full documentation for server setup, API reference, and tutorials.

Safety Warning

This package communicates with a gRPC server that controls real CNC machinery. Ensure proper safety measures:

• Use only on trusted networks
• Implement authentication in production (gRPC supports TLS/mTLS)
• Never leave machines unattended during remote operation
• Verify E-stop and safety systems are functional

License

MIT