跳轉至

MCU命令

該文件介紹了Klipper上位機軟體發送到微控制器的,並由微處理器負責執行的底層命令。該文件不是這些命令的權威文件,也並未包含所有命令。

若想深入瞭解底層微處理器命令,該文件是不錯的入門材料。

關於命令的格式和傳輸的更多資訊,見protocol檔案。這裡的命令是使用其 "printf "風格的語法描述的--對於那些不熟悉這種格式的人來說,只需注意在看到'%...'序列時,應該用一個實際的整數來代替。例如,"count=%c "的描述可以被替換為 "count=10"。請注意,那些被認為是 "enumerations "的參數(見上述協議檔案)採取的是一個字串值,對於微控制器來說,它被自動轉換為一個整數值。這在名為 "pin"(或後綴為"_pin")的參數中很常見。

啟動命令

可能需要採取某些一次性的命令來配置微控制器及其片上外備。本節列出了可用於該目的的常用命令。與大多數微控制器的命令不同,這些命令在收到后立即執行,它們不需要任何特殊的設定。

常見的啟動命令:

  • set_digital_out pin=%u value=%c:該命令立即將指定的引腳配置為數字輸出GPIO,並將其設定為低電平(value=0)或高電平(value=1)。這條命令對於配置LED的初始值和配置步進驅動器微步進引腳的初始值很有用。
  • set_pwm_out pin=%u cycle_ticks=%u value=%hu:該命令將立即配置指定的引腳,使其使用硬體的脈寬調製(PWM)和給定的cycle_ticks。「cycle_ticks」是指每個通電和斷電週期應該持續的MCU時鐘數。cycle_ticks的值為1表示使用最短的週期時間。「value」參數在0-255之間,0表示完全關閉狀態,255表示完全開啟狀態。該命令對啟用CPU和噴嘴冷卻風扇很有用。

底層微控制器配置

微控制器中的大多數命令在成功呼叫之前需要進行初始設定。本節提供了一個配置過程的概述。本節和下面的章節適用於對Klipper的內部細節感興趣的開發者。

當主機第一次連線到微控制器時,它總是從獲得一個數據字典開始(更多資訊見protocol)。獲得數據字典后,主機將檢查微控制器是否處於 "已配置 "狀態,如果不是,就進行配置。配置包括以下幾個階段:

  • get_config:主機首先檢查微控制器是否已經被配置。微控制器用一個 "config "的響應資訊來回應這個命令。微控制器軟體在上電時總是以未配置的狀態啟動。在主機完成配置過程之前(通過發出finalize_config命令),它一直處於這種狀態。如果微控制器已經在前一個會話中進行了配置(並且配置了所需的設定),那麼主機就不需要進一步的操作,配置過程成功結束。
  • allocate_oids count=%c:這條命令是用來通知微控制器主機所需的對象標識(oid)的最大數量。這條命令只有效一次。oid是分配給每個步進電機、每個限位開關和每個可排程的gpio引腳的一個整數標識。主機事先確定操作硬體所需的oid數量,並將其傳遞給微控制器,以便它可以分配足夠的記憶體來儲存從oid到內部對象的對映。
  • config_XXX oid=%c ...:按照慣例,任何以 "config_"開頭的命令都會建立一個新的微控制器對象,並將給定的oid賦予它。例如,config_digital_out命令將把指定的引腳配置為數字輸出GPIO,並建立一個內部對象,主機可以用它來安排改變指定的GPIO的輸出。傳入config命令的oid參數由主機選擇,必須介於0和allocate_oids命令中提供的最大計數之間。config命令只能在微控制器不處於已配置狀態時(即在主機發送finalize_config之前)和allocate_oids命令被髮送之後執行。
  • finalize_config crc=%u:finalize_config命令將微控制器從未配置狀態轉換為已配置狀態。傳遞給微控制器的crc參數被儲存起來,並在 "config "響應資訊中反饋給主機。按照慣例,主機對它所要求的配置採取32位的CRC,並在隨後的通訊會話開始時,檢查儲存在微控制器中的CRC是否與它所希望的CRC正確匹配。如果CRC不匹配,那麼主機就知道微控制器還沒有被配置到主機所希望的狀態。

常見的微控制器對像

本節列出了一些常用的配置命令。

  • config_digital_out oid=%c pin=%u value=%c default_value=%c max_duration=%u:該命令為給定的GPIO'pin'建立一個內部微控制器對象。該引腳將被配置為數字輸出模式,並被設定為'value'指定的初始值(0為低,1為高)。建立一個digital_out對像允許主機在指定的時間內對指定引腳重新整理GPIO輸出狀態(見下面描述的queue_digital_out命令)。如果微控制器軟體進入關機模式,那麼所有配置的digital_out對像將被設定為'default_value'。max_duration "參數用於實現安全檢查--如果它是非零,那麼它代表主機可以將指定的GPIO設為非預設值而不需要重新整理的最大時鐘數。例如,如果default_value是0,max_duration是16000,那麼如果主機將gpio設定為1,它必須在16000個時鐘刻度內重新整理gpio引腳的輸出(為0或1)。這個安全功能可用於加熱器引腳,以確保主機不會啟用加熱器后離線。
  • config_pwm_out oid=%c pin=%u cycle_ticks=%u value=%hu default_value=%hu max_duration=%u:該命令為基於硬體的PWM引腳建立一個內部對象,主機可以定期重新整理。它的用法與config_digital_out類似--參數說明見'set_pwm_out'和'config_digital_out'命令的描述。
  • config_analog_in oid=%c pin=%u:該命令用於將一個引腳配置為模擬輸入採樣模式。一旦配置完成,就可以使用query_analog_in命令(見下文)以固定的時間間隔對該引腳進行採樣。
  • config_stepper oid=%c step_pin=%c dir_pin=%c invert_step=%c step_pulse_ticks=%u:該命令建立一個內部步進器對象。'step_pin'和'dir_pin'參數分別指定步進和方向引腳;該命令將把它們配置為數字輸出模式。'invert_step'參數指定步進是發生在上升沿(invert_step=0)還是下降沿(invert_step=1)。'step_pulse_ticks'參數指定了步進脈衝的最小持續時間。如果MCU輸出常數 "STEPPER_BOTH_EDGE=1",那麼設定step_pulse_ticks=0和invert_step=-1將設定在步進引腳的上升沿和下降沿都進行步進輸出。
  • config_endstop oid=%c pin=%c pull_up=%c stepper_count=%c : 該命令建立一個內部的 "endstop"對象。它用於指定限位開關的引腳,並啟用 "homing "操作(見下面的endstop_home命令)。該命令將把指定的引腳配置為數字輸入模式。『pull_up』參數決定是否啟用硬體為引腳提供的上拉電阻(如果有的話)。『stepper_count』參數規定了在歸零操作中,該限位開關觸發器可能需要的最大步進數(見下文endstop_home)。
  • config_spi oid=%c bus=%u pin=%u mode=%u rate=%u shutdown_msg=%*s:該命令建立了一個內部SPI對象。它與spi_transfer和spi_send命令一起使用(見下文)。"bus"標識了要使用的SPI匯流排(如果微控制器有一個以上的SPI匯流排可用)。"pin"指定了裝置的片選(CS)引腳。"mode"指定SPI模式(應該在0到3之間)。"rate "參數指定了SPI匯流排的速率(以每秒週期為單位)。最後,"shutdown_msg "是在微控制器進入關機狀態時向給定裝置發送的SPI命令。
  • config_spi_without_cs oid=%c bus=%u mode=%u rate=%u shutdown_msg=%*s : 這個命令類似於config_spi,但是沒有CS引腳的定義。它對沒有晶片選擇線的SPI裝置很有用。

常用命令

本節列出了一些常用的執行時命令。對希望深入瞭解Klipper的開發者可能會感興趣。

  • set_digital_out_pwm_cycle oid=%c cycle_ticks=%u:該命令將數字輸出引腳(由config_digital_out建立)配置為使用 "軟體PWM"。'cycle_ticks' 是PWM週期的時鐘數。因為輸出切換是在微控制器軟體中實現的,建議把'cycle_ticks'對應的時間設為10ms或更大。
  • queue_digital_out oid=%c clock=%u on_ticks=%u : 這個命令將安排在設定的時鐘時間內改變數字輸出GPIO引腳。要使用這條命令,必須在微控制器配置過程中發出具有相同『oid』參數的'config_digital_out'命令。如果'set_digital_out_pwm_cycle'已經被呼叫,那麼'on_ticks'就是pwm週期的開啟時間(以時鐘數為單位)。否則,'on_ticks'應該是0(低電壓)或1(高電壓)。
  • queue_pwm_out oid=%c clock=%u value=%hu :安排改變一個硬體PWM輸出引腳。更多資訊請參考 'queue_digital_out' 和 '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:此命令設定了一個對模擬輸入的循環採樣。要使用這條命令,必須在微控制器配置時發出具有相同'oid'參數的 'config_analog_in '命令。採樣將從'clock'時間開始,它將每隔'rest_ticks'時鐘數報告獲得的值,'sample_count'是過量採樣次數,'sample_ticks'是在過量採樣之間暫停的時鐘數。"min_value "和 "max_value "參數實現了安全功能--微控制器軟體將驗證採樣值(在每次過採樣之後)總是在安全範圍內。這是為連線到控制加熱器的熱敏電阻的引腳而設計的--它可以用來檢查加熱器是否在一個溫度範圍內。
  • get_clock:該命令使微控制器產生一個 "clock"響應訊息。主機每秒發送一次這個命令,以獲得微控制器的時鐘值,並估計主機和微控制器時鐘之間的漂移。它使主機能夠準確估計微控制器的時鐘。

步進器命令

  • queue_step oid=%c interval=%u count=%hu add=%hi:該命令安排指定的步進電機輸出'count'個步數,'interval'是每步之間的時鐘數間隔。命令中的第一步與上一個步進輸出命令最後一步的時間間隔為'interval'個時鐘數。如果'add'不為零,那麼每步之後的間隔將以'add'的增量調整。該命令將給定的間隔/計數/增量序列附加到每個步進佇列中。在正常操作中,可能有數百個這樣的序列排隊。新的序列被新增到佇列的末尾,當每個序列完成了它的 'count'步數后它就從佇列的前面彈出去。這個系統允許微控制器將幾十萬步排入佇列--所有這些都有可靠且可預測的排程時序。
  • set_next_step_dir oid=%c dir=%c:該命令指定了下一個queue_step命令將使用的dir_pin的值。
  • reset_step_clock oid=%c clock=%u:通常情況下步進時序是相對於給定步進的上一步。這條命令重置了時鐘,使下一步是相對於提供的 'clock' 時間。通常主機只在列印開始時發送此命令。
  • stepper_get_position oid=%c:該命令使微控制器產生一個 "stepper_position "響應訊息,其中包含步進器的當前位置。該位置是dir=1時產生的總步數減去dir=0時的總步數。
  • endstop_home oid=%c clock=%u sample_ticks=%u sample_count=%c rest_ticks=%u pin_value=%c:該命令用於步進電機 "homing"操作。要使用這條命令,必須在微控制器配置過程中發出具有相同 'oid '參數的 'config_endstop '命令。當這個命令被呼叫時,微控制器將在每一個'rest_ticks'時鐘刻度上對限位開關引腳進行採樣,並檢查它的值是否等於'pin_value'。如果開關被觸發(並且以間隔'sample_ticks'為週期,額外持續'sample_count'次被觸發),那麼相關步進的運動佇列將被清除,步進將立即停止。主機使用該命令實現歸位–主機指示限位開關對限位開關的觸發進行採樣,然後發出一系列queue_step命令,使步進向限位移動。一旦步進電機撞到限位開關,檢測到觸發,運動就會停止並通知主機。

運動佇列

每個queue_step命令都利用了微控制器 "move queue "中的一個條目。這個佇列是在它收到 "finalize_config "命令時分配的,它在 "config "響應資訊中報告可用佇列條目的數量。

在發送queue_step命令之前,主機有責任確保佇列中有可用空間。這需要主機通過計算每個queue_step命令完成的時間並相應地安排新的queue_step命令來實現。

SPI 命令

  • spi_transfer oid=%c data=%*s:這條命令使微控制器向 'oid '指定的spi裝置發送 'data' ,並產生一個 "spi_transfer_response "的響應訊息,其中包括傳輸期間返回的數據。
  • spi_send oid=%c data=%*s:這個命令與 "spi_transfer "類似,但它不產生 "spi_transfer_response "訊息。
Back to top