linuxcnc-grpc 0.5.0__tar.gz

linuxcnc_grpc-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Doug Calobrisi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

linuxcnc_grpc-0.5.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: linuxcnc-grpc
+Version: 0.5.0
+Summary: gRPC server exposing LinuxCNC machine control and HAL functionality
+License-Expression: MIT
+Project-URL: Repository, https://github.com/dougcalobrisi/linuxcnc-grpc
+Keywords: linuxcnc,cnc,grpc,machine-control,hal
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: grpcio>=1.60.0
+Requires-Dist: grpcio-health-checking>=1.60.0
+Requires-Dist: protobuf>=4.25.0
+Provides-Extra: dev
+Requires-Dist: grpcio-tools>=1.60.0; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Provides-Extra: build
+Requires-Dist: build>=1.0.0; extra == "build"
+Requires-Dist: twine>=5.0.0; extra == "build"
+Dynamic: license-file
+
+# 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
+
+## Running the Server
+
+The server runs on your LinuxCNC machine and exposes the gRPC interface.
+
+### Basic Usage
+
+```bash
+pip install linuxcnc-grpc
+# or with uv
+uv pip install linuxcnc-grpc
+```
+
+```bash
+linuxcnc-grpc --host 0.0.0.0 --port 50051
+```
+
+LinuxCNC must already be running before starting the server.
+
+### Auto-start with LinuxCNC
+
+To start the gRPC server automatically when LinuxCNC launches, add to your machine's HAL file:
+
+```hal
+# Start gRPC server (runs until LinuxCNC exits)
+loadusr -W linuxcnc-grpc --host 0.0.0.0 --port 50051
+```
+
+Or use a dedicated HAL file via your INI:
+
+```ini
+[HAL]
+POSTGUI_HALFILE = grpc-server.hal
+```
+
+The `-W` flag tells LinuxCNC to wait for the server to become ready before continuing.
+
+## Quick Start
+
+### Python
+
+```bash
+pip install linuxcnc-grpc
+```
+
+```python
+import grpc
+from linuxcnc_pb import linuxcnc_pb2, linuxcnc_pb2_grpc
+
+channel = grpc.insecure_channel("localhost:50051")
+stub = linuxcnc_pb2_grpc.LinuxCNCServiceStub(channel)
+
+status = stub.GetStatus(linuxcnc_pb2.GetStatusRequest())
+print(f"Position: X={status.position.x:.3f} Y={status.position.y:.3f} Z={status.position.z:.3f}")
+```
+
+### Go
+
+```bash
+go get github.com/dougcalobrisi/linuxcnc-grpc
+```
+
+```go
+import (
+    pb "github.com/dougcalobrisi/linuxcnc-grpc/packages/go"
+    "google.golang.org/grpc"
+    "google.golang.org/grpc/credentials/insecure"
+)
+
+conn, _ := grpc.NewClient("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
+client := pb.NewLinuxCNCServiceClient(conn)
+
+status, _ := client.GetStatus(context.Background(), &pb.GetStatusRequest{})
+fmt.Printf("Position: X=%.3f Y=%.3f Z=%.3f\n", status.Position.X, status.Position.Y, status.Position.Z)
+```
+
+### Node.js / TypeScript
+
+```bash
+npm install linuxcnc-grpc
+```
+
+```typescript
+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)}`);
+});
+```
+
+### Rust
+
+```toml
+[dependencies]
+linuxcnc-grpc = "0.5"
+tokio = { version = "1", features = ["full"] }
+tonic = "0.12"
+```
+
+```rust
+use linuxcnc_grpc::linuxcnc::linux_cnc_service_client::LinuxCncServiceClient;
+use linuxcnc_grpc::linuxcnc::GetStatusRequest;
+
+let mut client = LinuxCncServiceClient::connect("http://localhost:50051").await?;
+let status = client.get_status(GetStatusRequest {}).await?.into_inner();
+println!("Position: X={:.3} Y={:.3}", status.position.unwrap().x, status.position.unwrap().y);
+```
+
+## Examples
+
+Complete examples for all supported languages:
+
+| Example | Description | Python | Go | Node.js | Rust |
+|---------|-------------|--------|-----|---------|------|
+| `get_status` | Poll machine status | [view](examples/python/get_status.py) | [view](examples/go/cmd/get_status/main.go) | [view](examples/node/get_status.ts) | [view](examples/rust/src/bin/get_status.rs) |
+| `stream_status` | Real-time status streaming | [view](examples/python/stream_status.py) | [view](examples/go/cmd/stream_status/main.go) | [view](examples/node/stream_status.ts) | [view](examples/rust/src/bin/stream_status.rs) |
+| `jog_axis` | Jog axes with keyboard | [view](examples/python/jog_axis.py) | [view](examples/go/cmd/jog_axis/main.go) | [view](examples/node/jog_axis.ts) | [view](examples/rust/src/bin/jog_axis.rs) |
+| `mdi_command` | Execute G-code via MDI | [view](examples/python/mdi_command.py) | [view](examples/go/cmd/mdi_command/main.go) | [view](examples/node/mdi_command.ts) | [view](examples/rust/src/bin/mdi_command.rs) |
+| `hal_query` | Query HAL pins/signals | [view](examples/python/hal_query.py) | [view](examples/go/cmd/hal_query/main.go) | [view](examples/node/hal_query.ts) | [view](examples/rust/src/bin/hal_query.rs) |
+| `upload_file` | Upload, list, delete G-code files | [view](examples/python/upload_file.py) | [view](examples/go/cmd/upload_file/main.go) | [view](examples/node/upload_file.ts) | [view](examples/rust/src/bin/upload_file.rs) |
+
+See [examples/README.md](examples/README.md) for setup instructions.
+
+## Services
+
+- **LinuxCNCService** - Machine control: status, jogging, MDI, program execution, file management
+- **HalService** - HAL introspection: query pins, signals, parameters (read-only)
+
+### File Management
+
+The server provides `UploadFile`, `ListFiles`, and `DeleteFile` RPCs for remote G-code file management. Files are stored in the NC files directory (default: `/home/linuxcnc/linuxcnc/nc_files`).
+
+Configure the directory with `--nc-files` or the `LINUXCNC_NC_FILES` environment variable:
+
+```bash
+linuxcnc-grpc --host 0.0.0.0 --nc-files /path/to/nc_files
+```
+
+## Safety Warning
+
+This server provides remote control of 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
+
+## Production Deployment
+
+For production use, enable TLS authentication:
+
+```python
+# Server with TLS
+credentials = grpc.ssl_server_credentials([(private_key, certificate)])
+server.add_secure_port('[::]:50051', credentials)
+```
+
+```python
+# Client with TLS
+credentials = grpc.ssl_channel_credentials(root_certificates)
+channel = grpc.secure_channel('your-machine:50051', credentials)
+```
+
+See [Server Configuration](docs/server.md#security-considerations) for complete TLS setup instructions.
+
+## Development
+
+Requires [uv](https://docs.astral.sh/uv/) for Python dependency management:
+
+```bash
+# Install dev dependencies
+make setup
+
+# Run tests
+make test          # Python tests
+make test-all      # All languages
+
+# Generate proto code
+make proto-all     # Regenerate for all languages
+```
+
+See [CLAUDE.md](CLAUDE.md) for detailed development documentation.
+
+## License
+
+[MIT](LICENSE)

linuxcnc_grpc-0.5.0/README.md

@@ -0,0 +1,201 @@
+# 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
+
+## Running the Server
+
+The server runs on your LinuxCNC machine and exposes the gRPC interface.
+
+### Basic Usage
+
+```bash
+pip install linuxcnc-grpc
+# or with uv
+uv pip install linuxcnc-grpc
+```
+
+```bash
+linuxcnc-grpc --host 0.0.0.0 --port 50051
+```
+
+LinuxCNC must already be running before starting the server.
+
+### Auto-start with LinuxCNC
+
+To start the gRPC server automatically when LinuxCNC launches, add to your machine's HAL file:
+
+```hal
+# Start gRPC server (runs until LinuxCNC exits)
+loadusr -W linuxcnc-grpc --host 0.0.0.0 --port 50051
+```
+
+Or use a dedicated HAL file via your INI:
+
+```ini
+[HAL]
+POSTGUI_HALFILE = grpc-server.hal
+```
+
+The `-W` flag tells LinuxCNC to wait for the server to become ready before continuing.
+
+## Quick Start
+
+### Python
+
+```bash
+pip install linuxcnc-grpc
+```
+
+```python
+import grpc
+from linuxcnc_pb import linuxcnc_pb2, linuxcnc_pb2_grpc
+
+channel = grpc.insecure_channel("localhost:50051")
+stub = linuxcnc_pb2_grpc.LinuxCNCServiceStub(channel)
+
+status = stub.GetStatus(linuxcnc_pb2.GetStatusRequest())
+print(f"Position: X={status.position.x:.3f} Y={status.position.y:.3f} Z={status.position.z:.3f}")
+```
+
+### Go
+
+```bash
+go get github.com/dougcalobrisi/linuxcnc-grpc
+```
+
+```go
+import (
+    pb "github.com/dougcalobrisi/linuxcnc-grpc/packages/go"
+    "google.golang.org/grpc"
+    "google.golang.org/grpc/credentials/insecure"
+)
+
+conn, _ := grpc.NewClient("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
+client := pb.NewLinuxCNCServiceClient(conn)
+
+status, _ := client.GetStatus(context.Background(), &pb.GetStatusRequest{})
+fmt.Printf("Position: X=%.3f Y=%.3f Z=%.3f\n", status.Position.X, status.Position.Y, status.Position.Z)
+```
+
+### Node.js / TypeScript
+
+```bash
+npm install linuxcnc-grpc
+```
+
+```typescript
+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)}`);
+});
+```
+
+### Rust
+
+```toml
+[dependencies]
+linuxcnc-grpc = "0.5"
+tokio = { version = "1", features = ["full"] }
+tonic = "0.12"
+```
+
+```rust
+use linuxcnc_grpc::linuxcnc::linux_cnc_service_client::LinuxCncServiceClient;
+use linuxcnc_grpc::linuxcnc::GetStatusRequest;
+
+let mut client = LinuxCncServiceClient::connect("http://localhost:50051").await?;
+let status = client.get_status(GetStatusRequest {}).await?.into_inner();
+println!("Position: X={:.3} Y={:.3}", status.position.unwrap().x, status.position.unwrap().y);
+```
+
+## Examples
+
+Complete examples for all supported languages:
+
+| Example | Description | Python | Go | Node.js | Rust |
+|---------|-------------|--------|-----|---------|------|
+| `get_status` | Poll machine status | [view](examples/python/get_status.py) | [view](examples/go/cmd/get_status/main.go) | [view](examples/node/get_status.ts) | [view](examples/rust/src/bin/get_status.rs) |
+| `stream_status` | Real-time status streaming | [view](examples/python/stream_status.py) | [view](examples/go/cmd/stream_status/main.go) | [view](examples/node/stream_status.ts) | [view](examples/rust/src/bin/stream_status.rs) |
+| `jog_axis` | Jog axes with keyboard | [view](examples/python/jog_axis.py) | [view](examples/go/cmd/jog_axis/main.go) | [view](examples/node/jog_axis.ts) | [view](examples/rust/src/bin/jog_axis.rs) |
+| `mdi_command` | Execute G-code via MDI | [view](examples/python/mdi_command.py) | [view](examples/go/cmd/mdi_command/main.go) | [view](examples/node/mdi_command.ts) | [view](examples/rust/src/bin/mdi_command.rs) |
+| `hal_query` | Query HAL pins/signals | [view](examples/python/hal_query.py) | [view](examples/go/cmd/hal_query/main.go) | [view](examples/node/hal_query.ts) | [view](examples/rust/src/bin/hal_query.rs) |
+| `upload_file` | Upload, list, delete G-code files | [view](examples/python/upload_file.py) | [view](examples/go/cmd/upload_file/main.go) | [view](examples/node/upload_file.ts) | [view](examples/rust/src/bin/upload_file.rs) |
+
+See [examples/README.md](examples/README.md) for setup instructions.
+
+## Services
+
+- **LinuxCNCService** - Machine control: status, jogging, MDI, program execution, file management
+- **HalService** - HAL introspection: query pins, signals, parameters (read-only)
+
+### File Management
+
+The server provides `UploadFile`, `ListFiles`, and `DeleteFile` RPCs for remote G-code file management. Files are stored in the NC files directory (default: `/home/linuxcnc/linuxcnc/nc_files`).
+
+Configure the directory with `--nc-files` or the `LINUXCNC_NC_FILES` environment variable:
+
+```bash
+linuxcnc-grpc --host 0.0.0.0 --nc-files /path/to/nc_files
+```
+
+## Safety Warning
+
+This server provides remote control of 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
+
+## Production Deployment
+
+For production use, enable TLS authentication:
+
+```python
+# Server with TLS
+credentials = grpc.ssl_server_credentials([(private_key, certificate)])
+server.add_secure_port('[::]:50051', credentials)
+```
+
+```python
+# Client with TLS
+credentials = grpc.ssl_channel_credentials(root_certificates)
+channel = grpc.secure_channel('your-machine:50051', credentials)
+```
+
+See [Server Configuration](docs/server.md#security-considerations) for complete TLS setup instructions.
+
+## Development
+
+Requires [uv](https://docs.astral.sh/uv/) for Python dependency management:
+
+```bash
+# Install dev dependencies
+make setup
+
+# Run tests
+make test          # Python tests
+make test-all      # All languages
+
+# Generate proto code
+make proto-all     # Regenerate for all languages
+```
+
+See [CLAUDE.md](CLAUDE.md) for detailed development documentation.
+
+## License
+
+[MIT](LICENSE)

linuxcnc_grpc-0.5.0/linuxcnc_grpc.egg-info/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: linuxcnc-grpc
+Version: 0.5.0
+Summary: gRPC server exposing LinuxCNC machine control and HAL functionality
+License-Expression: MIT
+Project-URL: Repository, https://github.com/dougcalobrisi/linuxcnc-grpc
+Keywords: linuxcnc,cnc,grpc,machine-control,hal
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: grpcio>=1.60.0
+Requires-Dist: grpcio-health-checking>=1.60.0
+Requires-Dist: protobuf>=4.25.0
+Provides-Extra: dev
+Requires-Dist: grpcio-tools>=1.60.0; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Provides-Extra: build
+Requires-Dist: build>=1.0.0; extra == "build"
+Requires-Dist: twine>=5.0.0; extra == "build"
+Dynamic: license-file
+
+# 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
+
+## Running the Server
+
+The server runs on your LinuxCNC machine and exposes the gRPC interface.
+
+### Basic Usage
+
+```bash
+pip install linuxcnc-grpc
+# or with uv
+uv pip install linuxcnc-grpc
+```
+
+```bash
+linuxcnc-grpc --host 0.0.0.0 --port 50051
+```
+
+LinuxCNC must already be running before starting the server.
+
+### Auto-start with LinuxCNC
+
+To start the gRPC server automatically when LinuxCNC launches, add to your machine's HAL file:
+
+```hal
+# Start gRPC server (runs until LinuxCNC exits)
+loadusr -W linuxcnc-grpc --host 0.0.0.0 --port 50051
+```
+
+Or use a dedicated HAL file via your INI:
+
+```ini
+[HAL]
+POSTGUI_HALFILE = grpc-server.hal
+```
+
+The `-W` flag tells LinuxCNC to wait for the server to become ready before continuing.
+
+## Quick Start
+
+### Python
+
+```bash
+pip install linuxcnc-grpc
+```
+
+```python
+import grpc
+from linuxcnc_pb import linuxcnc_pb2, linuxcnc_pb2_grpc
+
+channel = grpc.insecure_channel("localhost:50051")
+stub = linuxcnc_pb2_grpc.LinuxCNCServiceStub(channel)
+
+status = stub.GetStatus(linuxcnc_pb2.GetStatusRequest())
+print(f"Position: X={status.position.x:.3f} Y={status.position.y:.3f} Z={status.position.z:.3f}")
+```
+
+### Go
+
+```bash
+go get github.com/dougcalobrisi/linuxcnc-grpc
+```
+
+```go
+import (
+    pb "github.com/dougcalobrisi/linuxcnc-grpc/packages/go"
+    "google.golang.org/grpc"
+    "google.golang.org/grpc/credentials/insecure"
+)
+
+conn, _ := grpc.NewClient("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
+client := pb.NewLinuxCNCServiceClient(conn)
+
+status, _ := client.GetStatus(context.Background(), &pb.GetStatusRequest{})
+fmt.Printf("Position: X=%.3f Y=%.3f Z=%.3f\n", status.Position.X, status.Position.Y, status.Position.Z)
+```
+
+### Node.js / TypeScript
+
+```bash
+npm install linuxcnc-grpc
+```
+
+```typescript
+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)}`);
+});
+```
+
+### Rust
+
+```toml
+[dependencies]
+linuxcnc-grpc = "0.5"
+tokio = { version = "1", features = ["full"] }
+tonic = "0.12"
+```
+
+```rust
+use linuxcnc_grpc::linuxcnc::linux_cnc_service_client::LinuxCncServiceClient;
+use linuxcnc_grpc::linuxcnc::GetStatusRequest;
+
+let mut client = LinuxCncServiceClient::connect("http://localhost:50051").await?;
+let status = client.get_status(GetStatusRequest {}).await?.into_inner();
+println!("Position: X={:.3} Y={:.3}", status.position.unwrap().x, status.position.unwrap().y);
+```
+
+## Examples
+
+Complete examples for all supported languages:
+
+| Example | Description | Python | Go | Node.js | Rust |
+|---------|-------------|--------|-----|---------|------|
+| `get_status` | Poll machine status | [view](examples/python/get_status.py) | [view](examples/go/cmd/get_status/main.go) | [view](examples/node/get_status.ts) | [view](examples/rust/src/bin/get_status.rs) |
+| `stream_status` | Real-time status streaming | [view](examples/python/stream_status.py) | [view](examples/go/cmd/stream_status/main.go) | [view](examples/node/stream_status.ts) | [view](examples/rust/src/bin/stream_status.rs) |
+| `jog_axis` | Jog axes with keyboard | [view](examples/python/jog_axis.py) | [view](examples/go/cmd/jog_axis/main.go) | [view](examples/node/jog_axis.ts) | [view](examples/rust/src/bin/jog_axis.rs) |
+| `mdi_command` | Execute G-code via MDI | [view](examples/python/mdi_command.py) | [view](examples/go/cmd/mdi_command/main.go) | [view](examples/node/mdi_command.ts) | [view](examples/rust/src/bin/mdi_command.rs) |
+| `hal_query` | Query HAL pins/signals | [view](examples/python/hal_query.py) | [view](examples/go/cmd/hal_query/main.go) | [view](examples/node/hal_query.ts) | [view](examples/rust/src/bin/hal_query.rs) |
+| `upload_file` | Upload, list, delete G-code files | [view](examples/python/upload_file.py) | [view](examples/go/cmd/upload_file/main.go) | [view](examples/node/upload_file.ts) | [view](examples/rust/src/bin/upload_file.rs) |
+
+See [examples/README.md](examples/README.md) for setup instructions.
+
+## Services
+
+- **LinuxCNCService** - Machine control: status, jogging, MDI, program execution, file management
+- **HalService** - HAL introspection: query pins, signals, parameters (read-only)
+
+### File Management
+
+The server provides `UploadFile`, `ListFiles`, and `DeleteFile` RPCs for remote G-code file management. Files are stored in the NC files directory (default: `/home/linuxcnc/linuxcnc/nc_files`).
+
+Configure the directory with `--nc-files` or the `LINUXCNC_NC_FILES` environment variable:
+
+```bash
+linuxcnc-grpc --host 0.0.0.0 --nc-files /path/to/nc_files
+```
+
+## Safety Warning
+
+This server provides remote control of 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
+
+## Production Deployment
+
+For production use, enable TLS authentication:
+
+```python
+# Server with TLS
+credentials = grpc.ssl_server_credentials([(private_key, certificate)])
+server.add_secure_port('[::]:50051', credentials)
+```
+
+```python
+# Client with TLS
+credentials = grpc.ssl_channel_credentials(root_certificates)
+channel = grpc.secure_channel('your-machine:50051', credentials)
+```
+
+See [Server Configuration](docs/server.md#security-considerations) for complete TLS setup instructions.
+
+## Development
+
+Requires [uv](https://docs.astral.sh/uv/) for Python dependency management:
+
+```bash
+# Install dev dependencies
+make setup
+
+# Run tests
+make test          # Python tests
+make test-all      # All languages
+
+# Generate proto code
+make proto-all     # Regenerate for all languages
+```
+
+See [CLAUDE.md](CLAUDE.md) for detailed development documentation.
+
+## License
+
+[MIT](LICENSE)