MCU Befehle¶
Dieses Dokument enthält Informationen zu den Low-Level-Mikrocontroller-Befehlen, die von der Klipper "Host"-Software gesendet und von der Klipper Mikrocontroller-Software verarbeitet werden. Dieses Dokument ist weder eine verbindliche Referenz für diese Befehle, noch ist es eine exklusive Liste aller verfügbaren Befehle.
Dieses Dokument kann für Entwickler nützlich sein, die daran interessiert sind, die Low-Level-Mikrocontroller-Befehle zu verstehen.
Siehe das Dokument protocol für weitere Informationen über das Format der Befehle und ihre Übertragung. Die Befehle werden hier in der „printf“-Syntax beschrieben - für diejenigen, die mit diesem Format nicht vertraut sind, sei darauf hingewiesen, dass eine „%...“-Sequenz durch eine Ganzzahl ersetzt werden sollte, wenn sie vorkommt. Zum Beispiel könnte eine Beschreibung mit „count=%c“ durch den Text „count=10“ ersetzt werden. Beachten Sie, dass Parameter, die als „Aufzählungen“ gelten (siehe das obige Protokolldokument), einen String-Wert annehmen, der für den Mikrocontroller automatisch in einen Integer-Wert umgewandelt wird. Dies ist bei Parametern mit dem Namen „pin“ (oder mit dem Suffix „_pin“) üblich.
Start Befehle¶
Unter Umständen sind bestimmte einmalige Aktionen erforderlich, um den Mikrocontroller und seine Peripherie zu konfigurieren. Dieser Abschnitt listet die dafür gebräuchlichen Befehle auf. Anders als die meisten Mikrocontroller-Befehle werden diese Befehle sofort nach Empfang ausgeführt und erfordern keine besondere Einrichtung.
Übliche Startbefehle:
set_digital_out pin=%u value=%c: Dieser Befehl konfiguriert den angegebenen Pin sofort als digitalen GPIO-Ausgang und setzt ihn entweder auf Low-Pegel (value=0) oder High-Pegel (value=1). Dieser Befehl kann nützlich sein, um den Anfangswert von LEDs sowie den Anfangswert der Microstepping-Pins von Schrittmotortreibern festzulegen.set_pwm_out pin=%u cycle_ticks=%u value=%hu: Dieser Befehl konfiguriert den angegebenen Pin sofort für hardwarebasierte Pulsweitenmodulation (PWM) mit der angegebenen Anzahl von cycle_ticks. "cycle_ticks" ist die Anzahl der MCU-Takte, die jeder Ein- und Ausschaltzyklus dauern soll. Ein cycle_ticks-Wert von 1 kann verwendet werden, um die kürzestmögliche Zykluszeit anzufordern. Der Parameter "value" liegt zwischen 0 und 255, wobei 0 den vollständig ausgeschalteten und 255 den vollständig eingeschalteten Zustand bedeutet. Dieser Befehl kann nützlich sein, um CPU- und Bauteilkühlungslüfter zu aktivieren.
Low-Level Mikrocontroller Konfiguration¶
Die meisten Befehle im Mikrocontroller erfordern eine anfängliche Einrichtung, bevor sie erfolgreich aufgerufen werden können. Dieser Abschnitt gibt einen Überblick über den Konfigurationsvorgang. Dieser und die folgenden Abschnitte sind vermutlich nur für Entwickler interessant, die sich für die internen Details von Klipper interessieren.
Wenn sich der Host erstmals mit dem Mikrocontroller verbindet, beginnt er stets damit, ein Datenwörterbuch abzurufen (weitere Informationen siehe Protokoll). Nach dem Abruf des Datenwörterbuchs prüft der Host, ob sich der Mikrocontroller im Zustand "konfiguriert" befindet, und konfiguriert ihn andernfalls. Die Konfiguration umfasst die folgenden Phasen:
get_config: Der Host beginnt mit der Prüfung, ob der Mikrocontroller bereits konfiguriert ist. Der Mikrocontroller antwortet auf diesen Befehl mit einer "config"-Antwortnachricht. Die Mikrocontroller-Software startet beim Einschalten immer in einem unkonfigurierten Zustand. Sie verbleibt in diesem Zustand, bis der Host den Konfigurationsvorgang abschließt (durch Absetzen eines finalize_config-Befehls). Ist der Mikrocontroller bereits aus einer vorherigen Sitzung konfiguriert (und zwar mit den gewünschten Einstellungen), sind keine weiteren Schritte des Hosts erforderlich und der Konfigurationsvorgang endet erfolgreich.allocate_oids count=%c: Dieser Befehl wird abgesetzt, um dem Mikrocontroller die maximale Anzahl an Objekt-IDs (oid) mitzuteilen, die der Host benötigt. Dieser Befehl darf nur einmal abgesetzt werden. Eine oid ist ein ganzzahliger Bezeichner, der jedem Schrittmotor, jedem Endschalter und jedem planbaren GPIO-Pin zugewiesen wird. Der Host bestimmt im Voraus die Anzahl der oids, die er zum Betrieb der Hardware benötigt, und übergibt sie dem Mikrocontroller, damit dieser ausreichend Speicher für eine Zuordnung von oid zu internem Objekt reservieren kann.config_XXX oid=%c ...: Per Konvention erzeugt jeder Befehl, der mit dem Präfix "config_" beginnt, ein neues Mikrocontroller-Objekt und weist ihm die angegebene oid zu. Der Befehl config_digital_out konfiguriert zum Beispiel den angegebenen Pin als digitalen GPIO-Ausgang und erzeugt ein internes Objekt, über das der Host Änderungen an diesem GPIO einplanen kann. Der an den config-Befehl übergebene oid-Parameter wird vom Host gewählt und muss zwischen null und der im Befehl allocate_oids angegebenen Höchstzahl liegen. Die config-Befehle dürfen nur ausgeführt werden, wenn sich der Mikrocontroller nicht im konfigurierten Zustand befindet (also bevor der Host finalize_config sendet) und nachdem der Befehl allocate_oids gesendet wurde.finalize_config crc=%u: Der Befehl finalize_config überführt den Mikrocontroller vom unkonfigurierten in den konfigurierten Zustand. Der an den Mikrocontroller übergebene crc-Parameter wird gespeichert und dem Host in "config"-Antwortnachrichten zurückgemeldet. Per Konvention bildet der Host eine 32-Bit-CRC über die von ihm angeforderte Konfiguration und prüft zu Beginn nachfolgender Kommunikationssitzungen, ob die im Mikrocontroller gespeicherte CRC exakt mit der gewünschten CRC übereinstimmt. Stimmt die CRC nicht überein, weiß der Host, dass der Mikrocontroller nicht in dem vom Host gewünschten Zustand konfiguriert wurde.
Übliche Mikrocontroller Objekte¶
Dieser Abschnitt listet einige häufig verwendete config-Befehle auf.
config_digital_out oid=%c pin=%u value=%c default_value=%c max_duration=%u: Dieser Befehl erzeugt ein internes Mikrocontroller-Objekt für den angegebenen GPIO-Pin 'pin'. Der Pin wird im digitalen Ausgangsmodus konfiguriert und auf den durch 'value' angegebenen Anfangswert gesetzt (0 für Low, 1 für High). Das Erzeugen eines digital_out-Objekts erlaubt es dem Host, GPIO-Aktualisierungen für diesen Pin zu bestimmten Zeiten einzuplanen (siehe den weiter unten beschriebenen Befehl queue_digital_out). Geht die Mikrocontroller-Software in den Abschaltmodus, werden alle konfigurierten digital_out-Objekte auf 'default_value' gesetzt. Der Parameter 'max_duration' dient der Umsetzung einer Sicherheitsprüfung - ist er ungleich null, gibt er die maximale Anzahl an Takten an, für die der Host den betreffenden GPIO ohne weitere Aktualisierung auf einen vom Standard abweichenden Wert setzen darf. Ist zum Beispiel default_value gleich null und max_duration gleich 16000, dann muss der Host, wenn er den GPIO auf eins setzt, innerhalb von 16000 Takten eine weitere Aktualisierung des GPIO-Pins (auf null oder eins) einplanen. Diese Sicherheitsfunktion kann bei Heizungs-Pins eingesetzt werden, um sicherzustellen, dass der Host nicht die Heizung einschaltet und anschließend offline geht.config_pwm_out oid=%c pin=%u cycle_ticks=%u value=%hu default_value=%hu max_duration=%u: Dieser Befehl erzeugt ein internes Objekt für hardwarebasierte PWM-Pins, für die der Host Aktualisierungen einplanen kann. Die Verwendung ist analog zu config_digital_out - eine Beschreibung der Parameter finden Sie bei den Befehlen 'set_pwm_out' und 'config_digital_out'.config_analog_in oid=%c pin=%u: Dieser Befehl dient dazu, einen Pin im Modus der analogen Eingangsabtastung zu konfigurieren. Nach der Konfiguration kann der Pin mit dem Befehl query_analog_in in regelmäßigen Abständen abgetastet werden (siehe unten).config_stepper oid=%c step_pin=%c dir_pin=%c invert_step=%c step_pulse_ticks=%u: Dieser Befehl erzeugt ein internes Schrittmotor-Objekt. Die Parameter 'step_pin' und 'dir_pin' geben den Schritt- bzw. den Richtungs-Pin an; dieser Befehl konfiguriert sie im digitalen Ausgangsmodus. Der Parameter 'invert_step' legt fest, ob ein Schritt bei steigender Flanke (invert_step=0) oder bei fallender Flanke (invert_step=1) erfolgt. Der Parameter 'step_pulse_ticks' gibt die Mindestdauer des Schrittimpulses an. Exportiert der MCU die Konstante 'STEPPER_BOTH_EDGE=1', so bewirkt das Setzen von step_pulse_ticks=0 und invert_step=-1 ein Schalten sowohl bei steigender als auch bei fallender Flanke des Step-Pins.config_endstop oid=%c pin=%c pull_up=%c stepper_count=%c: Dieser Befehl erzeugt ein internes "endstop"-Objekt. Er dient dazu, die Endschalter-Pins festzulegen und "Homing"-Vorgänge zu ermöglichen (siehe den Befehl endstop_home weiter unten). Der Befehl konfiguriert den angegebenen Pin im digitalen Eingangsmodus. Der Parameter 'pull_up' bestimmt, ob die hardwareseitig für den Pin vorhandenen Pull-up-Widerstände (falls verfügbar) aktiviert werden. Der Parameter 'stepper_count' gibt die maximale Anzahl an Schrittmotoren an, die dieser Endschalter während eines Homing-Vorgangs anhalten können muss (siehe endstop_home unten).config_spi oid=%c bus=%u pin=%u mode=%u rate=%u shutdown_msg=%*s: Dieser Befehl erzeugt ein internes SPI-Objekt. Er wird zusammen mit den Befehlen spi_transfer und spi_send verwendet (siehe unten). "bus" bezeichnet den zu verwendenden SPI-Bus (falls der Mikrocontroller über mehr als einen SPI-Bus verfügt). "pin" gibt den Chip-Select-Pin (CS) des Geräts an. "mode" ist der SPI-Modus (er sollte zwischen 0 und 3 liegen). Der Parameter "rate" gibt die Übertragungsrate des SPI-Busses an (in Zyklen pro Sekunde). "shutdown_msg" schließlich ist ein SPI-Befehl, der an das betreffende Gerät gesendet wird, falls der Mikrocontroller in den Abschaltzustand geht.config_spi_without_cs oid=%c bus=%u mode=%u rate=%u shutdown_msg=%*s: Dieser Befehl entspricht config_spi, jedoch ohne Definition eines CS-Pins. Er ist für SPI-Geräte nützlich, die keine Chip-Select-Leitung besitzen.
Allgemeine Befehle¶
Dieser Abschnitt listet einige häufig verwendete Laufzeitbefehle auf. Er ist vermutlich nur für Entwickler interessant, die Einblick in Klipper gewinnen möchten.
set_digital_out_pwm_cycle oid=%c cycle_ticks=%u: Dieser Befehl konfiguriert einen digitalen Ausgangspin (wie er mit config_digital_out erzeugt wurde) für die Verwendung von "Software-PWM". 'cycle_ticks' ist die Anzahl der Takte für den PWM-Zyklus. Da das Umschalten des Ausgangs in der Mikrocontroller-Software umgesetzt wird, wird empfohlen, für 'cycle_ticks' eine Zeit von 10 ms oder mehr zu wählen.queue_digital_out oid=%c clock=%u on_ticks=%u: Dieser Befehl plant eine Änderung an einem digitalen GPIO-Ausgangspin zum angegebenen Taktzeitpunkt ein. Um diesen Befehl zu verwenden, muss während der Mikrocontroller-Konfiguration ein Befehl 'config_digital_out' mit demselben Parameter 'oid' abgesetzt worden sein. Wurde 'set_digital_out_pwm_cycle' aufgerufen, ist 'on_ticks' die Einschaltdauer (in Takten) für den PWM-Zyklus. Andernfalls sollte 'on_ticks' entweder 0 (für niedrige Spannung) oder 1 (für hohe Spannung) sein.queue_pwm_out oid=%c clock=%u value=%hu: Plant eine Änderung an einem hardwarebasierten PWM-Ausgangspin ein. Weitere Informationen finden Sie bei den Befehlen 'queue_digital_out' und 'config_pwm_out'.query_analog_in oid=%c clock=%u sample_ticks=%u sample_count=%c rest_ticks=%u min_value=%hu max_value=%hu: Dieser Befehl richtet einen wiederkehrenden Zeitplan für analoge Eingangsabtastungen ein. Um diesen Befehl zu verwenden, muss während der Mikrocontroller-Konfiguration ein Befehl 'config_analog_in' mit demselben Parameter 'oid' abgesetzt worden sein. Die Abtastung beginnt zum Zeitpunkt 'clock', der ermittelte Wert wird alle 'rest_ticks' Takte gemeldet, es wird 'sample_count'-mal überabgetastet und zwischen den einzelnen Überabtastungen wird 'sample_ticks' Takte pausiert. Die Parameter 'min_value' und 'max_value' setzen eine Sicherheitsfunktion um - die Mikrocontroller-Software prüft, ob der abgetastete Wert (nach etwaiger Überabtastung) stets innerhalb des angegebenen Bereichs liegt. Das ist für Pins gedacht, an denen Thermistoren zur Heizungsregelung angeschlossen sind - damit lässt sich prüfen, ob sich eine Heizung innerhalb eines Temperaturbereichs befindet.get_clock: Dieser Befehl veranlasst den Mikrocontroller, eine "clock"-Antwortnachricht zu erzeugen. Der Host sendet diesen Befehl einmal pro Sekunde, um den Wert des Mikrocontroller-Takts zu ermitteln und die Drift zwischen Host- und Mikrocontroller-Takt abzuschätzen. Dadurch kann der Host den Mikrocontroller-Takt genau abschätzen.
Stepper Befehle¶
queue_step oid=%c interval=%u count=%hu add=%hi: Dieser Befehl plant 'count' Schritte für den angegebenen Schrittmotor ein, mit 'interval' Takten zwischen den einzelnen Schritten. Der erste Schritt erfolgt 'interval' Takte nach dem zuletzt eingeplanten Schritt dieses Schrittmotors. Ist 'add' ungleich null, wird das Intervall nach jedem Schritt um den Betrag 'add' angepasst. Dieser Befehl hängt die angegebene interval/count/add-Sequenz an eine Warteschlange je Schrittmotor an. Im Normalbetrieb können Hunderte solcher Sequenzen in der Warteschlange stehen. Neue Sequenzen werden am Ende der Warteschlange angehängt, und sobald eine Sequenz ihre 'count' Schritte abgeschlossen hat, wird sie vorne aus der Warteschlange entnommen. Dieses System erlaubt es dem Mikrocontroller, potenziell Hunderttausende von Schritten einzureihen - alle mit zuverlässigen und vorhersagbaren Ausführungszeiten.set_next_step_dir oid=%c dir=%c: Dieser Befehl legt den Wert des dir_pin fest, den der nächste queue_step-Befehl verwenden wird.reset_step_clock oid=%c clock=%u: Normalerweise ist das Schritt-Timing relativ zum letzten Schritt eines bestimmten Schrittmotors. Dieser Befehl setzt den Takt zurück, sodass der nächste Schritt relativ zur angegebenen Zeit 'clock' erfolgt. Der Host sendet diesen Befehl üblicherweise nur zu Beginn eines Drucks.stepper_get_position oid=%c: Dieser Befehl veranlasst den Mikrocontroller, eine "stepper_position"-Antwortnachricht mit der aktuellen Position des Schrittmotors zu erzeugen. Die Position ist die Gesamtzahl der mit dir=1 erzeugten Schritte abzüglich der Gesamtzahl der mit dir=0 erzeugten Schritte.endstop_home oid=%c clock=%u sample_ticks=%u sample_count=%c rest_ticks=%u pin_value=%c: Dieser Befehl wird bei "Homing"-Vorgängen der Schrittmotoren verwendet. Um diesen Befehl zu verwenden, muss während der Mikrocontroller-Konfiguration ein Befehl 'config_endstop' mit demselben Parameter 'oid' abgesetzt worden sein. Wird dieser Befehl aufgerufen, tastet der Mikrocontroller den Endschalter-Pin alle 'rest_ticks' Takte ab und prüft, ob er den Wert 'pin_value' hat. Stimmt der Wert überein (und bleibt er für 'sample_count' weitere, jeweils 'sample_ticks' auseinanderliegende Abtastungen übereinstimmend), wird die Bewegungswarteschlange des zugehörigen Schrittmotors geleert und der Schrittmotor kommt unmittelbar zum Stillstand. Der Host setzt damit das Homing um - er weist den Endschalter an, auf das Auslösen zu prüfen, und setzt anschließend eine Reihe von queue_step-Befehlen ab, um einen Schrittmotor in Richtung des Endschalters zu bewegen. Sobald der Schrittmotor den Endschalter erreicht, wird das Auslösen erkannt, die Bewegung angehalten und der Host benachrichtigt.
Bewegungswarteschlange¶
Jeder queue_step-Befehl belegt einen Eintrag in der "Bewegungswarteschlange" des Mikrocontrollers. Diese Warteschlange wird beim Empfang des Befehls "finalize_config" reserviert; die Anzahl der verfügbaren Warteschlangeneinträge wird in "config"-Antwortnachrichten gemeldet.
Es liegt in der Verantwortung des Hosts, vor dem Senden eines queue_step-Befehls sicherzustellen, dass in der Warteschlange Platz verfügbar ist. Dazu berechnet der Host, wann jeder queue_step-Befehl abgeschlossen ist, und plant neue queue_step-Befehle entsprechend ein.
SPI Befehle¶
spi_transfer oid=%c data=%*s: Dieser Befehl veranlasst den Mikrocontroller, 'data' an das durch 'oid' angegebene SPI-Gerät zu senden, und erzeugt eine "spi_transfer_response"-Antwortnachricht mit den während der Übertragung zurückgegebenen Daten.spi_send oid=%c data=%*s: Dieser Befehl entspricht "spi_transfer", erzeugt jedoch keine "spi_transfer_response"-Nachricht.