Como definir a frequência PWM no Klipper?

TL;DR: No Klipper a frequência PWM é definida indiretamente através de um parâmetro de cycle time (tempo de ciclo). A frequência é 1 / cycle_time. A opção de configuração exata depende do que você está controlando.

Qual parâmetro de configuração usar

O Klipper não tem uma única opção pwm_frequency. Em vez disso você configura o período de um ciclo PWM, e o Klipper deriva a frequência disso.

Ventoinhas e pinos de saída: cycle_time

Para ventoinhas, pinos de saída genéricos, canais LED e similares, use cycle_time:

[fan]
pin: PA8
cycle_time: 0.010
hardware_pwm: False

• Padrão para [fan]: 0.010 s → 100 Hz.
• Padrão para [output_pin]: 0.100 s → 10 Hz.
• Padrão para canais LED [neopixel] / [dotstar]: 0.010 s → 100 Hz.

O parâmetro está documentado em docs/Config_Reference.md para [fan] (linhas 3239-3242) e [output_pin] (linhas 3678-3681).

Aquecedores: pwm_cycle_time

Para aquecedores (extrusora, mesa aquecida, etc.) o parâmetro se chama pwm_cycle_time:

[extruder]
heater_pin: PA2
pwm_cycle_time: 0.100

• Padrão: 0.100 s → 10 Hz.
• A documentação observa que “não é recomendado definir isso a menos que haja um requisito elétrico para comutar o aquecedor mais de 10 vezes por segundo” (Config_Reference.md).

Cycle time configurável em tempo de execução: [pwm_cycle_time]

Se você precisa mudar o cycle time do PWM em tempo de execução via G-code, use a seção [pwm_cycle_time]:

[pwm_cycle_time my_pin]
pin: PB0

Depois em tempo de execução:

SET_PIN PIN=my_pin VALUE=0.5 CYCLE_TIME=0.001

Isso está documentado em docs/Config_Reference.md e implementado em klippy/extras/pwm_cycle_time.py.

Como o valor é usado internamente

Em klippy/mcu.py, a classe MCU_pwm converte o cycle time em ticks de relógio do MCU:

cycle_ticks = self._mcu.seconds_to_clock(self._cycle_time)

Para PWM por software isso se torna o argumento cycle_ticks de set_digital_out_pwm_cycle (linha 488), e o tempo ligado dentro de cada ciclo é agendado nas mesmas unidades de tick. Para PWM por hardware o mesmo valor cycle_ticks é passado para a função gpio_pwm_setup() específica da plataforma, que então escolhe um prescaler e período do temporizador que melhor se ajustem.

Aviso sobre PWM por hardware: a frequência real pode diferir

Quando hardware_pwm: True é definido, a frequência que você solicita é apenas um alvo. O periférico de temporizador do MCU deve escolher um prescaler e um período do contador que se encaixem nos seus limites de hardware, então a frequência real pode ser ligeiramente diferente.

Por exemplo, a implementação STM32 em src/stm32/hard_pwm.c calcula os valores hwpwm_ticks e prescaler mais próximos alcançáveis (linhas 328-348). A frequência final no STM32 é aproximadamente:

frequency = CLOCK_FREQ / (prescaler * hwpwm_ticks * pclock_div)

Se dois pinos PWM por hardware compartilharem o mesmo temporizador, eles também devem usar a mesma frequência; caso contrário o Klipper encerra com “PWM already programmed at different speed” (linha 356).

Exemplos práticos

Ventoinha de 25 kHz para controle PWM de 4 fios

[fan]
pin: PA8
cycle_time: 0.00004
hardware_pwm: True

1 / 0.00004 = 25.000 Hz. Como isso está fora da faixa confiável do PWM por software, hardware_pwm: True é necessário.

Ventoinha de resfriamento de peças padrão de 100 Hz

[fan]
pin: PA8
cycle_time: 0.010

Este é o padrão e funciona bem com PWM por software.

Aquecedor de 10 Hz

[extruder]
heater_pin: PA2
pwm_cycle_time: 0.100

Novamente o padrão; não é necessário mudá-lo a menos que seu MOSFET/driver precise de comutação mais rápida.

Resumo

• A frequência PWM no Klipper é sempre 1 / cycle_time.
• Use cycle_time para ventoinhas, pinos de saída e LEDs.
• Use pwm_cycle_time para aquecedores.
• O PWM por software respeita o cycle time exatamente.
• O PWM por hardware pode arredondar o cycle time devido a restrições do temporizador do MCU.