name: snapmaker-2 description: "Control and monitor Snapmaker 2.0 3D printers via their HTTP API. Status, job management, progress watching, and event monitoring." summary: "Snapmaker 2.0 3D printer control: status, jobs, monitoring." version: 1.2.2 homepage: https://github.com/odrobnik/snapmaker-skill metadata: { "openclaw": { "emoji": "🖨️", "requires": { "bins": ["python3"] }, }, }

Snapmaker 2.0 Skill

Control and monitor Snapmaker 2.0 3D printers via their HTTP API.

Features

Status monitoring - Real-time printer status (temperatures, progress, position)
Job management - Send, start, pause, resume, and stop print jobs
Safety features - Prevents interfering with active prints without confirmation
Progress watching - Live monitoring of print progress
Notification support - Detect print completion, filament issues, errors

Configuration

Create config.json in your workspace's snapmaker/ folder (e.g. ~/clawd/snapmaker/config.json). Start from config.json.example.

Config format:

{
  "ip": "192.168.0.32",
  "token": "your-token-here",
  "port": 8080
}

Finding your token: Open the Snapmaker Luban app, connect to your printer, and find the token in the connection settings. Copy it into your config.json.

Usage

Discovery

# Find Snapmaker printers on the local network (UDP broadcast, port 20054)
python3 scripts/snapmaker.py discover
 
# Probe a specific IP (useful across subnets)
python3 scripts/snapmaker.py discover --target 192.168.0.32
 
# JSON output
python3 scripts/snapmaker.py discover --json

Discovery uses the Snapmaker UDP broadcast protocol (no auth required). Falls back to HTTP probe using config if UDP gets no reply (e.g. different subnet).

Basic Commands

# Get current printer status
python3 scripts/snapmaker.py status
 
# Watch print progress (updates every 5 seconds)
python3 scripts/snapmaker.py watch
 
# Get status as JSON
python3 scripts/snapmaker.py status --json

Job Control

# Send a file (prepares but doesn't start)
python3 scripts/snapmaker.py send ~/prints/model.gcode
 
# Send and start immediately
python3 scripts/snapmaker.py send ~/prints/model.gcode --start --yes
 
# Pause current print
python3 scripts/snapmaker.py pause --yes
 
# Resume paused print
python3 scripts/snapmaker.py resume --yes
 
# Stop/cancel print (requires confirmation)
python3 scripts/snapmaker.py stop

Safety Flags

--yes - Skip confirmation prompts (use with caution!)
--force - Override safety checks (NOT RECOMMENDED)

All commands that modify state require confirmation unless --yes is provided.

API Endpoints

The skill uses these Snapmaker HTTP API v1 endpoints:

POST /api/v1/connect - Establish connection
GET /api/v1/status - Get printer status
POST /api/v1/prepare_print - Upload file
POST /api/v1/start_print - Start printing
POST /api/v1/pause - Pause print
POST /api/v1/resume - Resume print
POST /api/v1/stop - Stop/cancel print
GET /api/v1/print_file - Download last file

Status Fields

The status command returns:

status - Overall state (IDLE, RUNNING, PAUSED)
printStatus - Printing / Idle
progress - 0.0 to 1.0
fileName - Current/last file
currentLine / totalLines - G-code progress
elapsedTime / remainingTime - In seconds
nozzleTemperature1 / nozzleTargetTemperature1
heatedBedTemperature / heatedBedTargetTemperature
x / y / z - Current position
isFilamentOut - Filament runout detection
isEnclosureDoorOpen - Door state

Notifications

To detect events:

# Watch for completion
python3 scripts/snapmaker.py watch
 
# Or poll status in a loop
while true; do
  python3 scripts/snapmaker.py status --json | jq -r '.printStatus'
  sleep 10
done

Event detection:

Print complete - status == "IDLE" && progress >= 0.99
Filament out - isFilamentOut == true
Door opened - isEnclosureDoorOpen == true
Error - Check status field for errors

Safety Features

Active print protection - Cannot send files while printing
Confirmation prompts - All destructive actions require confirmation
State validation - Commands check printer state before executing
Clear warnings - Stop command shows prominent warning

Examples

Check if printer is busy

python3 scripts/snapmaker.py status | grep -q "RUNNING" && echo "Busy" || echo "Available"

Get remaining time

python3 scripts/snapmaker.py status --json | jq -r '.remainingTime'

Monitor temperatures

python3 scripts/snapmaker.py status --json | jq '{nozzle: .nozzleTemperature1, bed: .heatedBedTemperature}'

Troubleshooting

"Machine is not connected yet" (401 error):

The API requires calling /api/v1/connect first before any status queries
Example: curl -X POST "http://192.168.0.32:8080/api/v1/connect?token=YOUR_TOKEN"
The Python script handles this automatically on first request
Connection establishes a session that persists until the printer is powered off
If using raw curl commands, always call connect first

Connection refused:

Verify printer IP: ping 192.168.0.32
Check printer is powered on
Ensure you're on the same network

Invalid token:

Reconnect Luban to the printer (accept on touchscreen)
Copy the new token from Luban's connection settings
Update your config.json

Can't send file:

Check if printer is busy: python3 scripts/snapmaker.py status
Wait for current print to finish
Use --force only if absolutely necessary

References

Dependencies

Python 3.6+
requests library (install: pip3 install requests)

License

Part of OpenClaw skills collection.