Willkommen in der faszinierenden Welt des 3D-Drucks mit Klipper! Wenn Sie bereits Klipper nutzen, wissen Sie um dessen Leistungsfähigkeit und Präzision. Doch wussten Sie, dass Sie mit der Klipper API das volle Potenzial Ihres Druckers freisetzen können? Die API (Application Programming Interface) ermöglicht es Ihnen, mit Ihrem Drucker zu interagieren, Daten abzurufen und Befehle zu senden – alles programmatisch. Dies eröffnet Türen für erweiterte Überwachung, individuelle Benutzeroberflächen, Heimautomatisierung und vieles mehr.
Dieser umfassende Leitfaden führt Sie Schritt für Schritt durch die Konfiguration und Nutzung der Klipper API. Egal, ob Sie ein Entwickler, ein fortgeschrittener Anwender oder einfach nur neugierig sind, wie Sie Ihren 3D-Druck-Workflow noch effizienter gestalten können, hier sind Sie richtig. Wir konzentrieren uns dabei auf Moonraker, den API-Server von Klipper, der die Kommunikation ermöglicht.
Warum die Klipper API nutzen?
Bevor wir ins Detail gehen, fragen Sie sich vielleicht: Warum sollte ich mich überhaupt mit einer API beschäftigen? Hier sind einige überzeugende Gründe:
* Automatisierung: Starten Sie Drucke, steuern Sie die Temperatur oder führen Sie G-Code-Befehle aus – alles automatisch über Skripte oder externe Systeme.
* Fernüberwachung: Rufen Sie jederzeit den Status Ihres Druckers ab, ohne eine Weboberfläche öffnen zu müssen. Ideal für mobile Apps oder Smart-Home-Integrationen.
* Benutzerdefinierte Schnittstellen: Erstellen Sie Ihre eigene Benutzeroberfläche, die genau auf Ihre Bedürfnisse zugeschnitten ist, anstatt auf Standard-Webinterfaces angewiesen zu sein.
* Integration: Verbinden Sie Ihren 3D-Drucker mit anderen Systemen in Ihrem Haus oder Büro, wie z.B. Benachrichtigungsdiensten oder Produktions-Dashboards.
* Analyse: Sammeln Sie detaillierte Daten über Ihre Drucke für Leistungsanalysen und Optimierungen.
Kurz gesagt: Die Klipper API verwandelt Ihren 3D-Drucker von einem isolierten Gerät in einen integralen Bestandteil Ihrer vernetzten Umgebung.
Grundlagen der Klipper API und Moonraker
Bevor wir uns in die Konfiguration stürzen, lassen Sie uns kurz klären, was wir eigentlich tun. Eine API ist im Wesentlichen ein Satz von Regeln und Definitionen, die es verschiedenen Softwarekomponenten ermöglichen, miteinander zu kommunizieren. Im Kontext von Klipper ist der zentrale Vermittler Moonraker.
Moonraker ist ein unabhängiger Dienst, der auf Ihrem Raspberry Pi (oder einem anderen Host-Gerät) zusammen mit Klipper läuft. Er fungiert als HTTP- und WebSocket-Server und bietet die Schnittstelle, über die Web-Interfaces wie Mainsail oder Fluidd, aber auch Ihre eigenen Anwendungen, mit Klipper kommunizieren können. Moonraker übersetzt Ihre API-Anfragen in Befehle, die Klipper versteht, und liefert Ihnen die von Klipper bereitgestellten Daten zurück. Ohne Moonraker gäbe es keine direkte, einfache Möglichkeit, über ein Netzwerk mit Klipper zu interagieren. Es ist also das unverzichtbare Herzstück Ihrer Klipper API-Zugriffsmöglichkeiten.
Voraussetzungen für den Start
Um dieser Anleitung folgen zu können, benötigen Sie Folgendes:
1. **Ein laufendes Klipper-System:** Ihr 3D-Drucker sollte bereits mit Klipper konfiguriert und betriebsbereit sein, idealerweise mit einer Web-Oberfläche wie Mainsail oder Fluidd installiert.
2. **Zugriff auf die Kommandozeile (SSH):** Sie benötigen SSH-Zugriff auf das Host-Gerät (z.B. Raspberry Pi), auf dem Klipper und Moonraker laufen. Tools wie PuTTY (Windows) oder das Terminal (macOS/Linux) sind dafür geeignet.
3. **Grundkenntnisse im Umgang mit Texteditoren:** Wir werden Konfigurationsdateien bearbeiten. Ein grundlegendes Verständnis von `nano` oder `vi` ist hilfreich.
4. **Netzwerkkenntnisse:** Sie sollten die IP-Adresse Ihres Klipper-Host-Geräts kennen.
Schritt 1: Moonraker – Das Herzstück der Klipper API finden
Moonraker wird in der Regel automatisch installiert, wenn Sie Mainsail oder Fluidd einrichten. Es ist der Dienst, der im Hintergrund läuft und auf Anfragen wartet.
Zuerst sollten wir sicherstellen, dass Moonraker läuft und wo sich seine Konfigurationsdatei befindet:
1. **Verbinden Sie sich per SSH mit Ihrem Klipper-Host-Gerät.**
Geben Sie im Terminal ein:
`ssh pi@
(Ersetzen Sie `
2. **Überprüfen Sie den Status des Moonraker-Dienstes:**
`sudo systemctl status moonraker`
Sie sollten „active (running)” sehen, was bestätigt, dass Moonraker läuft.
3. **Finden Sie die Moonraker-Konfigurationsdatei:**
Die Hauptkonfigurationsdatei für Moonraker ist `moonraker.conf`. Sie befindet sich normalerweise im Ordner `~/printer_data/config/`.
Navigieren Sie dorthin:
`cd ~/printer_data/config/`
Listen Sie den Inhalt auf:
`ls`
Sie sollten `moonraker.conf` in der Liste sehen.
Schritt 2: Konfiguration der Moonraker API-Zugriffsberechtigungen
Jetzt wird es spannend! Wir werden die `moonraker.conf`-Datei bearbeiten, um den API-Zugriff zu konfigurieren. Dies ist entscheidend für Sicherheit und Erreichbarkeit.
Öffnen Sie die Datei mit einem Texteditor (z.B. `nano`):
`nano moonraker.conf`
Suchen Sie nach den Abschnitten `[server]` und `[authorization]`. Wenn sie nicht vorhanden sind, können Sie sie am Ende der Datei hinzufügen.
Der `[server]`-Abschnitt
Hier definieren Sie, auf welchen Adressen und Ports Moonraker lauscht. Standardmäßig ist dies oft schon korrekt konfiguriert:
„`ini
[server]
host: 0.0.0.0
port: 7125
# enable_ssl: False # Nur aktivieren, wenn Sie SSL/HTTPS verwenden möchten
„`
* `host: 0.0.0.0` bedeutet, dass Moonraker auf allen verfügbaren Netzwerkschnittstellen lauscht. Das ist gut für den Zugriff aus dem lokalen Netzwerk.
* `port: 7125` ist der Standard-API-Port für Moonraker. Sie können diesen ändern, wenn Sie möchten, aber stellen Sie sicher, dass keine anderen Dienste diesen Port verwenden.
Der `[authorization]`-Abschnitt – Sicherheit geht vor!
Dies ist der wichtigste Teil für den API-Zugriff. Hier legen Sie fest, wer oder was auf Ihre Klipper-API zugreifen darf.
„`ini
[authorization]
trusted_clients:
127.0.0.1
192.168.1.0/24 # Beispiel: Ihr lokales Netzwerk
10.0.0.0/8 # Ein weiteres Beispiel für ein privates Netzwerk
cors_domains:
* # Erlaubt allen Domains, auf die API zuzugreifen. ACHTUNG: Nur für lokale/Testumgebungen empfohlen!
# http://localhost:8080 # Besser: Spezifische Domains angeben, z.B. Ihre lokale Entwicklungsumgebung
api_key:
„`
Erklärung der Parameter:
* `trusted_clients:` Dies ist eine Whitelist von IP-Adressen oder IP-Bereichen, die ohne API-Schlüssel auf Moonraker zugreifen dürfen.
* `127.0.0.1`: Dies ist die Loopback-Adresse, die den Zugriff vom Host selbst ermöglicht (wichtig für Mainsail/Fluidd).
* `192.168.1.0/24`: Dies ist ein CIDR-Block, der allen Geräten im Subnetz 192.168.1.x Zugriff gewährt. Ersetzen Sie dies durch den IP-Bereich Ihres eigenen Netzwerks. Wenn Ihr Router z.B. 192.168.0.1 verwendet, wäre es `192.168.0.0/24`. Finden Sie Ihren Netzwerkbereich heraus!
* Fügen Sie hier KEINE öffentlichen IP-Adressen hinzu, es sei denn, Sie wissen genau, was Sie tun!
* `cors_domains:` Dies steuert, welche Webseiten (Domains) Cross-Origin-Anfragen an Moonraker senden dürfen.
* `*`: Erlaubt Anfragen von JEDER Domain. Dies ist **aus Sicherheitsgründen nur für lokale oder Testumgebungen zu empfehlen!** Im Produktivbetrieb oder wenn Sie Moonraker über das Internet erreichbar machen, sollten Sie stattdessen spezifische Domains angeben, z.B. `http://mycustomapp.com` oder `http://localhost:8080` für eine lokale Entwicklungsumgebung.
* `api_key:` (Optional, aber empfohlen für externe Dienste): Mit einem API-Schlüssel können Sie den Zugriff für Anwendungen regeln, die nicht in Ihren `trusted_clients` enthalten sind. Dies ist besonders nützlich, wenn Sie Moonraker über einen Reverse Proxy öffentlich zugänglich machen oder wenn Sie eine Drittanbieteranwendung verwenden möchten.
* Um einen API-Schlüssel zu generieren, können Sie einfach einen langen, zufälligen String verwenden (z.B. mit einem Online-Passwortgenerator oder `openssl rand -hex 32` auf Linux). Tragen Sie den generierten Schlüssel hier ein.
* Wenn ein `api_key` definiert ist und die anfragende IP nicht in `trusted_clients` ist, muss der API-Schlüssel in jeder Anfrage im HTTP-Header `X-Api-Key` gesendet werden.
Nachdem Sie die Änderungen vorgenommen haben, speichern Sie die Datei (Strg+O, Enter, Strg+X bei nano).
**WICHTIG:** Damit die Änderungen wirksam werden, müssen Sie den Moonraker-Dienst neu starten:
`sudo systemctl restart moonraker`
Überprüfen Sie den Status erneut, um sicherzustellen, dass er aktiv ist:
`sudo systemctl status moonraker`
Schritt 3: Testen der Klipper API – Der erste Kontakt
Nun ist es Zeit, Ihre Konfiguration zu testen! Wir werden einfache GET-Anfragen senden, um Informationen vom Drucker abzurufen.
Methode 1: Über den Webbrowser
Dies ist der einfachste Weg für schnelle Tests. Öffnen Sie Ihren Webbrowser und geben Sie die folgende URL ein:
`http://
Ersetzen Sie `
Wenn alles richtig konfiguriert ist, sollten Sie eine JSON-Antwort sehen, die Informationen über Ihren Moonraker-Server enthält. Dies ist ein Zeichen dafür, dass die grundlegende Verbindung zur Klipper API funktioniert.
Probieren Sie auch diese Endpunkte aus:
* `http://
* `http://
Methode 2: Über die Kommandozeile mit `curl`
`curl` ist ein leistungsstarkes Tool für HTTP-Anfragen. Es ist oft bereits auf Linux-Systemen installiert.
Verbinden Sie sich erneut per SSH mit Ihrem Klipper-Host oder verwenden Sie ein lokales Terminal, wenn `curl` dort verfügbar ist.
Beispiel für eine GET-Anfrage:
`curl http://
Wenn Sie einen API-Schlüssel konfiguriert haben und von einer nicht-vertrauenswürdigen IP-Adresse zugreifen, müssen Sie diesen im Header mitsenden:
`curl -H „X-Api-Key:
Die Ausgabe sollte die JSON-Antwort des Servers sein.
Methode 3: Mit einem API-Client (Postman/Insomnia)
Für detailliertere Tests und die Vorbereitung von POST-Anfragen (Befehle senden) sind Tools wie Postman oder Insomnia ideal. Diese bieten eine grafische Oberfläche, um Header, Body und Methoden einfach zu konfigurieren. Dies ist besonders nützlich, wenn Sie mit verschiedenen Klipper API-Endpunkten experimentieren möchten.
Schritt 4: Interaktion mit der Klipper API – Praktische Beispiele
Sobald Sie die Verbindung hergestellt haben, können Sie beginnen, mit der API zu interagieren. Moonraker verwendet hauptsächlich JSON-RPC 2.0 für Befehle, aber auch einfache HTTP-GET/POST-Anfragen für Statusabfragen und Dateiverwaltung.
A. Statusabfrage (GET-Anfragen)
Das Abrufen des aktuellen Druckerstatus ist eine der häufigsten Anwendungen der API.
Endpunkt: `/printer/objects/query`
Beispiel: Aktuelle Temperaturen von Extruder und Heizbett abrufen
`http://
Die JSON-Antwort würde in etwa so aussehen:
„`json
{
„jsonrpc”: „2.0”,
„result”: {
„status”: {
„toolhead”: {
„x”: 0.0,
„y”: 0.0,
„z”: 0.0,
„current_position”: [0.0, 0.0, 0.0, 0.0],
„homed_axes”: „xyz”,
„extruder”: „extruder”
},
„extruder”: {
„pressure_advance”: 0.0,
„smooth_time”: 0.0,
„target”: 200.0,
„temperature”: 198.5,
„power”: 0.5,
„can_extrude”: true
},
„heater_bed”: {
„target”: 60.0,
„temperature”: 59.8,
„power”: 0.8
}
}
}
}
„`
Sie können die gewünschten Objekte als kommaseparierte Liste nach dem `?` angeben. Eine vollständige Liste der verfügbaren Objekte erhalten Sie unter `/printer/objects/list`.
B. Befehle senden (POST-Anfragen)
Dies ermöglicht die Steuerung des Druckers, z.B. das Senden von G-Code-Befehlen.
Endpunkt: `/printer/gcode/script`
Diese Anfragen erfordern eine HTTP POST-Methode und einen JSON-Body.
Beispiel: Drucker homing (G28)
Methode: `POST`
URL: `http://
Body (JSON):
„`json
{
„script”: „G28”
}
„`
Beispiel: Extruder auf 200°C stellen
Methode: `POST`
URL: `http://
Body (JSON):
„`json
{
„script”: „M104 S200”
}
„`
Wenn Sie einen API-Schlüssel verwenden, müssen Sie diesen im `X-Api-Key`-Header jeder POST-Anfrage mitsenden.
C. Dateiverwaltung
Moonraker bietet auch Endpunkte für die Dateiverwaltung:
* Auflisten von Dateien: `GET /server/files/list`
* Hochladen von Dateien: `POST /server/files/upload` (erfordert `multipart/form-data`)
* Löschen von Dateien: `DELETE /server/files/gcodes/
Diese fortgeschrittenen Themen sind oft komplexer zu implementieren und erfordern ein tieferes Verständnis von HTTP-Anfragen, insbesondere beim Dateiupload.
Schritt 5: Fortgeschrittene Nutzung & Sicherheitshinweise
Nachdem Sie die Grundlagen beherrschen, sind hier einige weiterführende Konzepte und wichtige Sicherheitstipps.
Python-Beispiel für API-Interaktion
Für die Entwicklung eigener Anwendungen ist Python mit der `requests`-Bibliothek sehr beliebt. Hier ein einfaches Beispiel:
„`python
import requests
import json
KLIPPER_IP = „192.168.1.100” # Ersetzen Sie dies durch Ihre Klipper IP
MOONRAKER_PORT = 7125
API_KEY = „IHR_API_SCHLÜSSEL” # Nur, wenn Sie einen API-Schlüssel verwenden
# Beispiel 1: Druckerstatus abfragen
def get_printer_status():
url = f”http://{KLIPPER_IP}:{MOONRAKER_PORT}/printer/objects/query?toolhead&extruder”
headers = {}
if API_KEY:
headers[„X-Api-Key”] = API_KEY
try:
response = requests.get(url, headers=headers)
response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx)
data = response.json()
extruder_temp = data[‘result’][‘status’][‘extruder’][‘temperature’]
extruder_target = data[‘result’][‘status’][‘extruder’][‘target’]
print(f”Extruder Temperatur: {extruder_temp}°C (Ziel: {extruder_target}°C)”)
except requests.exceptions.RequestException as e:
print(f”Fehler beim Abrufen des Druckerstatus: {e}”)
# Beispiel 2: G-Code senden (Druckbett heizen)
def send_gcode_command(command):
url = f”http://{KLIPPER_IP}:{MOONRAKER_PORT}/printer/gcode/script”
headers = {„Content-Type”: „application/json”}
if API_KEY:
headers[„X-Api-Key”] = API_KEY
payload = {„script”: command}
try:
response = requests.post(url, headers=headers, data=json.dumps(payload))
response.raise_for_status()
print(f”Befehl ‘{command}’ erfolgreich gesendet.”)
except requests.exceptions.RequestException as e:
print(f”Fehler beim Senden des G-Codes: {e}”)
if __name__ == „__main__”:
get_printer_status()
# send_gcode_command(„M140 S60”) # Heizt das Bett auf 60 Grad auf
# send_gcode_command(„G28”) # Home the printer
„`
Installieren Sie die `requests`-Bibliothek mit `pip install requests`, falls noch nicht geschehen.
Webhooks und Ereignisse
Moonraker unterstützt auch Webhooks, die es Ihnen ermöglichen, Benachrichtigungen zu erhalten, wenn bestimmte Ereignisse auf dem Drucker auftreten (z.B. Druck gestartet, Fehler aufgetreten, Druck beendet). Dies ist eine fortschrittlichere Form der Klipper API-Nutzung und erfordert einen Server, der die Webhook-Anfragen empfängt. Informationen dazu finden Sie in der Moonraker-Dokumentation.
Sicherheitshinweise (sehr wichtig!)
* **Niemals Moonraker direkt ins Internet stellen!** Der Moonraker-Port (standardmäßig 7125) sollte niemals direkt über das Internet zugänglich sein, ohne zusätzliche Sicherheitsebene. Dies würde Ihr gesamtes Netzwerk potenziell offenlegen.
* **Verwenden Sie einen Reverse Proxy:** Wenn Sie über das Internet auf die API zugreifen müssen, verwenden Sie einen Reverse Proxy (z.B. Nginx oder Caddy) mit starker Authentifizierung (z.B. Benutzername/Passwort oder Client-Zertifikaten).
* **VPN ist die sicherste Option:** Die sicherste Methode für den Fernzugriff ist die Verwendung eines VPN (Virtual Private Network), um sich zuerst mit Ihrem Heimnetzwerk zu verbinden und dann wie gewohnt auf Moonraker zuzugreifen.
* **Starke API-Schlüssel:** Wenn Sie API-Schlüssel verwenden, stellen Sie sicher, dass diese lang, zufällig und komplex sind. Behandeln Sie sie wie Passwörter.
* **Regelmäßige Updates:** Halten Sie Klipper, Moonraker und Ihr Betriebssystem stets auf dem neuesten Stand. Updates enthalten oft wichtige Sicherheitsfixes.
* **Minimale Berechtigungen:** Erlauben Sie nur den notwendigen IP-Adressen den Zugriff über `trusted_clients`. Je spezifischer, desto besser. Vermeiden Sie `*` oder große IP-Bereiche, es sei denn, es ist absolut notwendig für die Funktion in einer kontrollierten Umgebung.
Fehlerbehebung – Was tun, wenn es hakt?
Manchmal läuft nicht alles reibungslos. Hier sind einige häufige Probleme und Lösungen:
* **”Connection Refused” oder Timeout:**
* Überprüfen Sie, ob Moonraker läuft: `sudo systemctl status moonraker`.
* Stimmt die IP-Adresse und der Port?
* Ist die Firewall auf dem Klipper-Host aktiv und blockiert den Port (z.B. UFW)? Möglicherweise müssen Sie den Port 7125 freigeben: `sudo ufw allow 7125`.
* **”401 Unauthorized”:**
* Haben Sie einen API-Schlüssel in der `moonraker.conf` konfiguriert, aber nicht in Ihrer Anfrage gesendet oder einen falschen gesendet?
* Ist die IP-Adresse, von der Sie zugreifen, nicht in der `trusted_clients`-Liste in `moonraker.conf` enthalten?
* Haben Sie Moonraker nach den Änderungen in `moonraker.conf` neu gestartet?
* **”404 Not Found”:**
* Sie haben den falschen Endpunkt verwendet. Überprüfen Sie die URL auf Tippfehler.
* Das angeforderte Objekt (z.B. `toolhead`) existiert nicht oder ist falsch geschrieben.
* **Leere oder unerwartete JSON-Antwort:**
* Überprüfen Sie die Moonraker-Logs auf Fehler: `journalctl -u moonraker -f` (zeigt die neuesten Logs an). Dies ist oft der beste Weg, um Probleme zu diagnostizieren.
* Stimmt Ihre JSON-Anfrage (bei POST-Requests)? Syntaxfehler sind häufig.
Fazit
Die Konfiguration der Klipper API über Moonraker mag auf den ersten Blick einschüchternd wirken, aber wie Sie gesehen haben, ist es mit den richtigen Schritten ein überschaubarer Prozess. Durch das Verständnis der `moonraker.conf`-Parameter und die Praxis mit API-Anfragen eröffnen sich Ihnen unzählige Möglichkeiten, Ihren 3D-Druck-Workflow zu automatisieren, zu überwachen und zu personalisieren.
Erinnern Sie sich immer an die Sicherheitsaspekte, insbesondere wenn Sie planen, über das lokale Netzwerk hinaus auf Ihre API zuzugreifen. Mit der leistungsstarken Kombination aus Klipper und der Moonraker API sind Sie bestens gerüstet, um die nächste Stufe der 3D-Druck-Steuerung zu erreichen. Experimentieren Sie, bauen Sie und genießen Sie die neue Freiheit, die Ihnen die Klipper Automatisierung bietet! Viel Erfolg beim Tüfteln!