Vai al contenuto

# Comandi MCU

Questo documento fornisce informazioni sui comandi di basso livello del microcontrollore che sono inviati dal software "host" Klipper e processati dal software del microcontrollore Klipper. Questo documento non è un riferimento autorevole per questi comandi, né una lista esclusiva di tutti i comandi disponibili.

Questo documento può essere utile per gli sviluppatori interessati a comprendere i comandi di basso livello del microcontrollore.

Vedere il documento protocol per ulteriori informazioni sul formato dei comandi e sulla loro trasmissione. I comandi qui sono descritti usando la loro sintassi di stile "printf" - per chi non ha familiarità con quel formato, basta notare che dove si vede una sequenza '%...' dovrebbe essere sostituita con un intero reale. Ad esempio, una descrizione con "count=%c" potrebbe essere sostituita con il testo "count=10". Si noti che i parametri considerati "enumerazioni" (vedere il documento di protocollo sopra) assumono un valore stringa che viene automaticamente convertito in un valore intero per il microcontrollore. Questo è comune con i parametri denominati "pin" (o che hanno il suffisso "_pin").

## Comandi di avvio

Potrebbe essere necessario eseguire determinate azioni una tantum per configurare il microcontrollore e le sue periferiche. Questa sezione elenca i comandi comuni disponibili a tale scopo. A differenza della maggior parte dei comandi del microcontrollore, questi comandi vengono eseguiti non appena vengono ricevuti e non richiedono alcuna configurazione particolare.

Comandi di avvio comuni:

- `set_digital_out pin=%u value=%c` : Questo comando configura immediatamente il pin dato come un GPIO di uscita digitale e lo imposta su un livello basso (valore=0) o alto (valore=1). Questo comando può essere utile per configurare il valore iniziale dei LED e per configurare il valore iniziale dei pin micro-stepping del driver stepper.
- `set_pwm_out pin=%u cycle_ticks=%u value=%hu` : Questo comando configurerà immediatamente il pin dato per utilizzare la modulazione di larghezza di impulso (PWM) basata sull'hardware con il numero specificato di cycle_tick. Il "cycle_ticks" è il numero di tick di clock dell'MCU per cui ogni ciclo di accensione e spegnimento dovrebbe durare. È possibile utilizzare un valore cycle_ticks pari a 1 per richiedere il tempo di ciclo più rapido possibile. Il parametro "value" è compreso tra 0 e 255 con 0 che indica uno stato completamente spento e 255 indica uno stato completamente acceso. Questo comando può essere utile per abilitare le ventole di raffreddamento della CPU e degli ugelli.

## Configurazione di basso livello del microcontrollore

La maggior parte dei comandi nel microcontrollore richiede una configurazione iniziale prima di poter essere richiamati correttamente. Questa sezione fornisce una panoramica del processo di configurazione. Questa sezione e le sezioni seguenti sono probabilmente di interesse solo per gli sviluppatori interessati ai dettagli interni di Klipper.

Quando l'host si connette per la prima volta al microcontrollore, inizia sempre ottenendo un dizionario di dati (vedi protocol per ulteriori informazioni). Dopo aver ottenuto il dizionario dei dati, l'host verificherà se il microcontrollore è in uno stato "configurato" e in caso contrario lo configurerà. La configurazione prevede le seguenti fasi:

- `get_config` : L'host si avvia controllando se il microcontrollore è già configurato. Il microcontrollore risponde a questo comando con un messaggio di risposta "config". Il software del microcontrollore si avvia sempre in uno stato non configurato all'accensione. Rimane in questo stato fino a quando l'host non completa i processi di configurazione (emettendo un comando finalize_config). Se il microcontrollore è già configurato da una sessione precedente (ed è configurato con le impostazioni desiderate), non sono necessarie ulteriori azioni da parte dell'host e il processo di configurazione termina correttamente.
- `allocate_oids count=%c` : Questo comando viene emesso per informare il microcontrollore del numero massimo di ID oggetto (oid) che l'host richiede. È valido solo per emettere questo comando una volta. Un oid è un identificatore intero allocato a ogni stepper, ogni endstop e ogni pin gpio schedulabile. L'host determina in anticipo il numero di oid necessari per far funzionare l'hardware e lo passa al microcontrollore in modo che possa allocare memoria sufficiente per memorizzare una mappatura dall'oid all'oggetto interno.
- `config_XXX oid=%c ...` : Per convenzione qualsiasi comando che inizia con il prefisso "config_" crea un nuovo oggetto microcontrollore e gli assegna l'oid dato. Ad esempio, il comando config_digital_out configurerà il pin specificato come GPIO di output digitale e creerà un oggetto interno che l'host può utilizzare per pianificare le modifiche al GPIO specificato. Il parametro oid passato al comando config viene selezionato dall'host e deve essere compreso tra zero e il conteggio massimo fornito nel comando allocate_oids. I comandi di configurazione possono essere eseguiti solo quando il microcontrollore non è in uno stato configurato (cioè prima dell'invio da parte dell'host di finalize_config) e dopo che è stato inviato il comando allocate_oids.
- `finalize_config crc=%u` : Il comando finalize_config trasferisce il microcontrollore da uno stato non configurato a uno stato configurato. Il parametro crc passato al microcontrollore viene archiviato e restituito all'host nei messaggi di risposta "config". Per convenzione, l'host prende un CRC a 32bit della configurazione che richiederà e all'avvio delle successive sessioni di comunicazione verifica che il CRC memorizzato nel microcontrollore corrisponda esattamente al CRC desiderato. Se il CRC non corrisponde, l'host sa che il microcontrollore non è stato configurato nello stato desiderato dall'host.

### Oggetti comuni del microcontrollore

Questa sezione elenca alcuni comandi di configurazione comunemente usati.

- `config_digital_out oid=%c pin=%u value=%c default_value=%c max_duration=%u` : Questo comando crea un oggetto microcontrollore interno per il dato 'pin' GPIO. Il pin verrà configurato in modalità di uscita digitale e impostato su un valore iniziale come specificato da 'value' (0 per basso, 1 per alto). La creazione di un oggetto digital_out consente all'host di pianificare gli aggiornamenti GPIO per il pin specificato a orari specificati (consultare il comando queue_digital_out descritto di seguito). Se il software del microcontrollore entra in modalità di spegnimento, tutti gli oggetti digital_out configurati verranno impostati su 'default_value'. Il parametro 'max_duration' viene utilizzato per implementare un controllo di sicurezza: se è diverso da zero, è il numero massimo di tick di clock che l'host può impostare il GPIO specificato su un valore non predefinito senza ulteriori aggiornamenti. Ad esempio, se default_value è zero e max_duration è 16000, se l'host imposta gpio su un valore di uno, deve pianificare un altro aggiornamento del pin gpio (su zero o su uno) entro 16000 tick di clock. Questa funzione di sicurezza può essere utilizzata con i pin del riscaldatore per garantire che l'host non abiliti il riscaldatore e quindi vada offline.
- `config_pwm_out oid=%c pin=%u cycle_ticks=%u value=%hu default_value=%hu max_duration=%u` : Questo comando crea un oggetto interno per i pin PWM hardware per i quali l'host può pianificare gli aggiornamenti. Il suo utilizzo è analogo a config_digital_out - vedere la descrizione dei comandi 'set_pwm_out' e 'config_digital_out' per la descrizione dei parametri.
- `config_analog_in oid=%c pin=%u` : Questo comando viene utilizzato per configurare un pin nella modalità di campionamento analogico. Una volta configurato, il pin può essere campionato a intervalli regolari utilizzando il comando query_analog_in (vedi sotto).
- `config_stepper oid=%c step_pin=%c dir_pin=%c invert_step=%c step_pulse_ticks=%u` : Questo comando crea un oggetto stepper interno. I parametri 'step_pin' e 'dir_pin' specificano rispettivamente i pin del passo e della direzione; questo comando li configurerà in modalità uscita digitale. Il parametro 'invert_step' specifica se un passo si verifica su un fronte di salita (invert_step=0) o discendente (invert_step=1). Il parametro 'step_pulse_ticks' specifica la durata minima dell'impulso di passo. Se l'mcu esporta la costante 'STEPPER_BOTH_EDGE=1', l'impostazione di step_pulse_ticks=0 e invert_step=-1 imposterà il passaggio su entrambi i fronti di salita e di discesa dello step pin.
- `config_endstop oid=%c pin=%c pull_up=%c stepper_count=%c` : Questo comando crea un oggetto "finecorsa" interno. Viene utilizzato per specificare i relativi pin e per abilitare le operazioni di "homing" (vedere il comando endstop_home di seguito). Il comando configurerà il pin specificato nella modalità di input digitale. Il parametro 'pull_up' determina se i resistori pullup forniti dall'hardware per il pin (se disponibili) saranno abilitati. Il parametro 'stepper_count' specifica il numero massimo di stepper che potrebbe essere necessario arrestare questo endstop durante un'operazione di homing (vedere endstop_home di seguito).
- `config_spi oid=%c bus=%u pin=%u mode=%u rate=%u shutdown_msg=%*s` : Questo comando crea un oggetto SPI interno. Viene utilizzato con i comandi spi_transfer e spi_send (vedi sotto). Il "bus" identifica il bus SPI da utilizzare (se il microcontrollore ha più di un bus SPI disponibile). Il "pin" specifica il pin di selezione del chip (CS) per il dispositivo. La "modalità" è la modalità SPI (dovrebbe essere compresa tra 0 e 3). Il parametro "rate" specifica la velocità del bus SPI (in cicli al secondo). Infine, "shutdown_msg" è un comando SPI da inviare al dispositivo specificato se il microcontrollore entra in uno stato di spegnimento.
- `config_spi_without_cs oid=%c bus=%u mode=%u rate=%u shutdown_msg=%*s` : Questo comando è simile a config_spi, ma senza una definizione di pin CS. È utile per i dispositivi SPI che non dispongono di una linea di selezione del chip.

## Comandi comuni

Questa sezione elenca alcuni comandi comunemente usati durante il run-time. È probabilmente di interesse solo per gli sviluppatori che cercano di ottenere informazioni su Klipper.

- `set_digital_out_pwm_cycle oid=%c cycle_ticks=%u` : Questo comando configura un pin come uscita digitale (come creato da config_digital_out) per usare "software PWM". 'cycle_ticks' è il numero di tick di clock per il ciclo PWM. Poiché la commutazione dell'uscita è implementata nel software del microcontrollore, si consiglia che 'cycle_ticks' corrisponda a un tempo di 10 ms o superiore.
- `queue_digital_out oid=%c clock=%u on_ticks=%u` : Questo comando pianificherà una modifica a un pin GPIO dell'uscita digitale per un orario specifico. Per utilizzare questo comando è necessario che durante la configurazione del microcontrollore sia stato emesso un comando 'config_digital_out' con lo stesso parametro 'oid'. Se è stato chiamato 'set_digital_out_pwm_cycle', allora 'on_ticks' è la durata di attivazione (in tick di clock) per il ciclo pwm. Altrimenti, 'on_ticks' dovrebbe essere 0 (per bassa tensione) o 1 (per alta tensione).
- `queue_pwm_out oid=%c clock=%u value=%hu` : Pianifica una modifica a un pin di uscita PWM hardware. Per ulteriori informazioni, vedere i comandi 'queue_digital_out' e '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` : Questo comando imposta una pianificazione ricorrente di campionamenti di un ingresso analogico. Per utilizzare questo comando è necessario che durante la configurazione del microcontrollore sia stato emesso un comando 'config_analog_in' con lo stesso parametro 'oid'. I campioni inizieranno a partire dall'ora 'clock', riporterà sul valore ottenuto ogni tick di clock 'rest_ticks', sovracampionerà il numero di 'sample_count' e metterà in pausa il numero di tick di clock 'sample_ticks' tra i sovacampionamenti. I parametri 'min_value' e 'max_value' implementano una funzione di sicurezza: il software del microcontrollore verificherà che il valore campionato (dopo qualsiasi sovracampionamento) sia sempre compreso nell'intervallo fornito. Questo è destinato all'uso con pin collegati a termistori che controllano i riscaldatori: può essere utilizzato per verificare che un riscaldatore rientri in un intervallo di temperatura.
- `get_clock` : Questo comando fa sì che il microcontrollore generi un messaggio di risposta "clock". L'host invia questo comando una volta al secondo per ottenere il valore dell'orologio del microcontrollore e per stimare la deriva tra gli orologi dell'host e del microcontrollore. Consente all'host di stimare con precisione l'orologio del microcontrollore.

### Comandi motori passopasso

- `queue_step oid=%c interval=%u count=%hu add=%hi` : Questo comando pianifica il 'conteggio' del numero di passi per il dato stepper, con 'intervallo' il numero di tick di clock tra ogni passo. Il primo passo sarà il numero "intervallo" di tick di clock dall'ultimo passo programmato per il dato stepper. Se 'add' è diverso da zero, l'intervallo verrà regolato in base all'importo di 'add' dopo ogni passaggio. Questo comando aggiunge la sequenza intervallo/conteggio/aggiunta data a una coda per stepper. Potrebbero esserci centinaia di queste sequenze in coda durante il normale funzionamento. La nuova sequenza viene aggiunta alla fine della coda e quando ogni sequenza completa il suo numero di "conteggi" di passaggi viene estratta dalla parte anteriore della coda. Questo sistema consente al microcontrollore di mettere in coda potenzialmente centinaia di migliaia di passaggi, il tutto con tempi di pianificazione affidabili e prevedibili.
- `set_next_step_dir oid=%c dir=%c` : Questo comando specifica il valore del dir_pin che verrà utilizzato dal comando queue_step successivo.
- `reset_step_clock oid=%c clock=%u` : Normalmente, la temporizzazione del passo è relativo all'ultimo passo per un dato stepper. Questo comando azzera l'orologio in modo che il passo successivo sia relativo all'ora fornita. L'host di solito invia questo comando solo all'inizio di una stampa.
- `stepper_get_position oid=%c` : Questo comando fa sì che il microcontrollore generi un messaggio di risposta "stepper_position" con la posizione corrente dello stepper. La posizione è il numero totale di passi generati con dir=1 meno il numero totale di passi generati con dir=0.
- `endstop_home oid=%c clock=%u sample_ticks=%u sample_count=%c rest_ticks=%u pin_value=%c` : Questo comando viene utilizzato durante le operazioni di "homing" dello stepper. Per utilizzare questo comando è necessario che durante la configurazione del microcontrollore sia stato emesso un comando 'config_endstop' con lo stesso parametro 'oid'. Quando viene invocato questo comando, il microcontrollore campiona il pin finecorsa ogni tick di clock "rest_ticks" e controlla se ha un valore uguale a "pin_value". Se il valore corrisponde (e continua a corrispondere per 'sample_count' campioni aggiuntivi separati da 'sample_ticks'), la coda di movimento per lo stepper associato verrà cancellata e lo stepper si arresterà immediatamente. L'host utilizza questo comando per implementare l'homing: l'host indica al finecorsa di eseguire il campionamento per il trigger endstop e quindi emette una serie di comandi queue_step per spostare uno stepper verso il finecorsa. Una volta che lo stepper raggiunge il finecorsa, il trigger verrà rilevato, il movimento verrà interrotto e l'host verrà informato.

### Coda movimento

Ogni comando queue_step utilizza una voce nella "coda di movimento" del microcontrollore. Questa coda viene allocata quando riceve il comando "finalize_config" e segnala il numero di voci di coda disponibili nei messaggi di risposta "config".

È responsabilità dell'host assicurarsi che ci sia spazio disponibile nella coda prima di inviare un comando queue_step. L'host esegue questa operazione calcolando il completamento di ciascun comando queue_step e pianificando di conseguenza i nuovi comandi queue_step.

### Comandi SPI

- `spi_transfer oid=%c data=%*s` : questo comando fa sì che il microcontrollore invii dati 'data' al dispositivo spi specificato da 'oid' e genera un messaggio di risposta "spi_transfer_response" con i dati restituiti durante la trasmissione .
- `spi_send oid=%c data=%*s` : Questo comando è simile a "spi_transfer", ma non genera un messaggio "spi_transfer_response".

Torna su