Como Nivelar Mesa com BLTouch no Klipper: Guia Passo a Passo

Como o BLTouch e o bed mesh do Klipper trabalham juntos

O BLTouch é um sensor de toque. Segundo a descrição da Antclabs, fabricante do sensor original, ele combina um solenoide com um sensor de efeito Hall. O pino é de plástico de engenharia, com um núcleo magnético. Como o sensor depende do toque físico, e não de indução, ele funciona sobre vidro, metal, madeira e outras superfícies. A fabricante informa ainda um desvio padrão de repetibilidade em torno de 0,005 mm.

O Klipper, por sua vez, usa as leituras do BLTouch para montar a malha da mesa, o chamado bed mesh. A documentação explica que o módulo intercepta os comandos de movimento do G-code e aplica uma correção na coordenada Z. Para acompanhar o formato da superfície, ele também divide os movimentos longos. Assim, uma mesa levemente empenada recebe uma primeira camada mais uniforme.

O que a malha não corrige

Vale entender o limite do recurso antes de começar. A própria documentação do Klipper avisa que a correção por software apenas aproxima o formato da mesa e não chega a um resultado perfeito. Além disso, o bed mesh não compensa problemas mecânicos ou elétricos. Se um eixo está torto ou o sensor não é preciso, as medições já saem erradas, e a malha só reproduz esse erro.

Por isso, a ordem do trabalho importa. Primeiro vêm a montagem e os testes do sensor, depois o nivelamento pelos parafusos, em seguida o Z-offset e, por último, a malha.

Instalação física e ligação do BLTouch

Altura de montagem

A documentação do Klipper indica que, com o pino recolhido, a ponta dele deve ficar cerca de 2 mm acima do bico. Depois da calibração, o Z-offset deve ficar perto de 1 mm. Se o valor sair muito diferente, o guia sugere subir ou descer o sensor no suporte. A lógica é dupla. O sensor precisa disparar bem antes de o bico tocar a mesa, mas o pino recolhido deve ficar o mais alto possível para não raspar nas peças.

O Klipper faz ainda um alerta importante. O pino do BLTouch é sensível à gordura dos dedos, então evite tocá-lo com a mão nua e, se precisar, faça isso com muita delicadeza.

Ligação elétrica

Na fiação original, segundo o Klipper, o fio amarelo do conector de três vias é o control_pin, e o fio branco do conector de duas vias é o sensor_pin. A maioria dos BLTouch precisa de pull-up no pino do sensor, o que se faz colocando o símbolo ^ antes do nome do pino. Faça qualquer mudança de fiação com a impressora desligada da tomada.

Já o modo de saída exige cuidado extra. O Klipper explica que as versões 3.0 e 3.1 trabalham por padrão em modo open-drain. O modo 5V só deve ser usado se a entrada da placa tolerar 5 V. Caso contrário, há risco de danificar o processador da placa.

Testes antes de deixar o BLTouch tocar a mesa

Ao ligar a impressora, o BLTouch faz um autoteste e sobe e desce o pino algumas vezes. Em seguida, o LED vermelho deve ficar aceso e o pino, recolhido. Se o LED piscar ou o pino ficar abaixado, a orientação do Klipper é desligar a impressora e revisar fiação e configuração.

Depois, o guia propõe uma sequência no terminal. Com BLTOUCH_DEBUG COMMAND=pin_down, o pino deve descer e o LED apagar. Com pin_up, o pino sobe e o LED volta a acender. Para testar o sinal, desça o pino, envie BLTOUCH_DEBUG COMMAND=touch_mode e rode QUERY_PROBE, que deve responder “probe: open”. Então empurre o pino de leve com a unha e repita o QUERY_PROBE, que agora deve mostrar “probe: TRIGGERED”.

Por fim, vem o teste mais importante para a segurança da máquina. Com o cabeçote longe da mesa, rode G28 e, quando ele começar a descer, toque o pino com a unha para interromper o movimento. Pode ser preciso repetir, porque a configuração padrão mede duas vezes. O Klipper recomenda estar pronto para desligar a impressora se ela não parar. Só depois disso o pino deve tocar a mesa de verdade.

Medindo os offsets X e Y

Um paquímetro dá uma boa estimativa, mas o Klipper descreve um método que usa o próprio sistema de movimento. Cole uma fita no centro da mesa, rode PROBE e marque o ponto sob o sensor. Em seguida, anote a posição com GET_POSITION, leve o bico exatamente sobre a marca e anote a nova posição. O x_offset é a posição X registrada com o bico sobre a marca menos a posição registrada com o sensor sobre ela, e o mesmo vale para o Y.

Na prática, um sensor montado à esquerda do bico gera x_offset negativo. Já um sensor montado atrás gera y_offset positivo, nas máquinas em que o Y cresce em direção ao fundo. Depois de editar o arquivo, envie RESTART para carregar os valores.

Configurando o BLTouch no printer.cfg

Seções [bltouch], [stepper_z] e [safe_z_home]

O ponto de partida é a seção [bltouch], com os pinos da sua placa e os offsets medidos. Se o BLTouch também for usado para o homing do eixo Z, a documentação do Klipper manda definir endstop_pin: probe:z_virtual_endstop em [stepper_z] e remover a linha position_endstop. Em seguida, entra a seção [safe_z_home]. Ela levanta o Z, faz o homing de X e Y e leva o cabeçote ao centro da mesa antes de medir o Z.

Um exemplo baseado na documentação, com os pinos e coordenadas que você precisa trocar pelos seus:

[bltouch]
sensor_pin: ^P1.24
control_pin: P1.26
x_offset: -40
y_offset: -10
z_offset: 0

[safe_z_home]

home_xy_position: 117.5, 117.5 speed: 50 z_hop: 10 z_hop_speed: 5

O Klipper destaca que o z_hop do [safe_z_home] precisa ser alto o bastante para o sensor não bater em nada. Isso vale mesmo que o pino esteja na posição mais baixa. Os valores de offset do exemplo são ilustrativos. O z_offset: 0 é só um valor provisório. Ele será substituído pelo número que o PROBE_CALIBRATE mede e grava, então não tente adivinhar esse valor.

Seção [bed_mesh]

Na seção [bed_mesh], os parâmetros obrigatórios são mesh_min e mesh_max. Segundo a documentação, essas coordenadas se referem à posição do sensor, e não à do bico. Ou seja, elas precisam ser pontos que o BLTouch consegue alcançar sem forçar o fim de curso dos eixos. Vale conferir o resultado com BED_MESH_OUTPUT PGP=1, que lista onde o bico e o sensor vão estar em cada ponto.

Já o probe_count define quantos pontos o sensor mede em cada eixo. O padrão é 3 por 3, e esse também é o mínimo aceito. Quanto ao algoritmo de interpolação, o padrão do Klipper é o lagrange, limitado a 6 pontos por eixo para evitar oscilações. O bicubic exige pelo menos 4 pontos por eixo, e com menos que isso o Klipper volta automaticamente ao lagrange.

[bed_mesh]
speed: 120
horizontal_move_z: 5
mesh_min: 15, 15
mesh_max: 190, 210
probe_count: 5, 5
algorithm: bicubic

Portanto, o bicúbico não é obrigatório nem sempre melhor. Ele faz sentido quando a malha tem 4 pontos ou mais por eixo. Além disso, a documentação alerta que valores altos de bicubic_tension podem gerar picos e vales que não existem na mesa.

Ordem do nivelamento: parafusos, Z-offset e malha

Nivelamento mecânico com SCREWS_TILT_CALCULATE

O primeiro passo é acertar a inclinação da mesa pelos parafusos. Na seção [screws_tilt_adjust], o Klipper pede as coordenadas do bico em que o sensor fica exatamente sobre cada parafuso. Esse detalhe é importante, porque não se trata da posição do parafuso, e sim da posição do cabeçote que coloca o BLTouch em cima dele. Também é preciso informar a rosca dos parafusos em screw_thread, como CW-M3.

Antes de rodar o comando, faça G28. Depois disso, SCREWS_TILT_CALCULATE mede cada ponto e informa o ajuste em “minutos de relógio”. Assim, 15 minutos equivalem a um quarto de volta, e 01:20 significa uma volta e 20 minutos. O primeiro parafuso é sempre a referência e não deve ser mexido. Segundo a documentação, o processo se repete até todos os ajustes ficarem abaixo de cerca de 6 minutos.

O comando ainda tem dois parâmetros úteis. Com MAX_DEVIATION, ele cancela a impressão se a mesa saiu do nível em relação à malha salva. Com DIRECTION=CW ou DIRECTION=CCW, o Klipper escolhe uma referência que permite nivelar girando os parafusos em um único sentido.

Z-offset do BLTouch com PROBE_CALIBRATE

Neste ponto, a documentação do Klipper contraria o hábito de calibrar com tudo quente. Ela diz, em destaque, que o teste do papel deve ser feito com o bico e a mesa em temperatura ambiente. O motivo é duplo. O bico quente deixa plástico derretido no papel, o que altera o atrito, e o calor aumenta muito o risco de queimadura. A dilatação térmica, que costuma ficar em torno de 0,1 mm, é estável. Se for preciso, o guia mostra como compensá-la depois com SET_GCODE_OFFSET, observando a primeira camada de uma peça de teste.

Antes de começar, verifique se não há plástico no bico nem na mesa. Se houver, o guia orienta aquecer o bico, retirar o material com uma pinça metálica e esperar esfriar completamente. Em seguida, faça o homing, leve o cabeçote ao centro e rode PROBE_CALIBRATE. O Klipper mede com o sensor, posiciona o bico no mesmo ponto e abre a ferramenta manual.

A partir daí, coloque uma folha de papel comum, de cerca de 0,1 mm, entre o bico e a mesa. Use TESTZ Z=-.1 para descer o bico e repita até sentir um leve atrito ao mover o papel. Também é possível usar TESTZ Z=+ ou TESTZ Z=- para dividir a distância entre as duas últimas posições. Quando chegar ao ponto, envie ACCEPT e depois SAVE_CONFIG, que grava o valor no arquivo e reinicia o Klipper.

A ordem com os parafusos tem um motivo técnico. Segundo a documentação, se o sensor tem offset em X ou Y, qualquer ajuste na inclinação da mesa invalida o PROBE_CALIBRATE. Portanto, ajuste os parafusos primeiro e calibre o Z-offset depois.

Conferindo a precisão do BLTouch

Antes de gerar a malha, vale rodar PROBE_ACCURACY, que mede o mesmo ponto dez vezes. A documentação considera normal uma diferença de até um passo do eixo Z ou 0,005 mm entre a maior e a menor leitura. Se essa faixa passar de 0,025 mm, o sensor não tem precisão suficiente para o nivelamento. Nesse caso, o guia sugere ajustar velocidade, altura inicial ou número de amostras.

A temperatura também pesa nesse resultado. O Klipper explica que muitos sensores têm um viés térmico. Por isso, recomenda usar as ferramentas de nivelamento sempre na mesma condição: com a impressora fria ou depois de ela atingir a temperatura de impressão. Em qualquer caso, a orientação é esperar alguns minutos para o conjunto estabilizar.

Gerando a malha com BED_MESH_CALIBRATE

Com tudo isso pronto, BED_MESH_CALIBRATE mede os pontos configurados e salva o resultado no perfil default. O Mainsail e o Fluidd mostram o mapa de alturas em gráfico. Para a documentação do Klipper, esses visualizadores bastam para a maioria dos usuários.

Um ponto mudou em versões mais novas do Klipper. Antes, o Klipper carregava o perfil default sozinho ao iniciar, mas esse comportamento foi removido. Agora, a recomendação é colocar BED_MESH_PROFILE LOAD=default na macro START_PRINT ou no G-code inicial do fatiador. Se a macro já roda BED_MESH_CALIBRATE a cada impressão, carregar o perfil salvo não é necessário.

Se você gerar a malha com a mesa aquecida, lembre que ela e o bico ficam quentes o bastante para queimar. Mantenha as mãos longe do cabeçote durante a medição e não encoste na superfície logo depois.

Erros comuns do BLTouch no Klipper

LED vermelho piscando

Segundo a documentação do Klipper, o LED pisca quando o BLTouch entra em um estado inconsistente. Isso pode acontecer, por exemplo, quando a calibração interna é interrompida porque algo impediu o pino de descer. O comando para sair desse estado é BLTOUCH_DEBUG COMMAND=reset. Alguns guias citam um comando “reset_state”, mas o parâmetro correto, na documentação, é apenas reset.

Se o reset não resolver, o problema pode estar no parafuso do topo do sensor ou no núcleo magnético dentro do pino. O guia descreve o procedimento: abrir o parafuso, empurrar o núcleo de volta com uma caneta esferográfica e recolocar o pino. Depois, o parafuso deve ser reajustado com cuidado até o pino subir e descer normalmente. Não é um ajuste de rotina, e sim uma correção para quando o sensor já não consegue se calibrar.

Clones e versão 3.1

O Klipper informa que muitos clones funcionam com a configuração padrão. Alguns, porém, não aceitam QUERY_PROBE ou precisam de pin_up_reports_not_triggered ou pin_up_touch_mode_reports_triggered em False. A documentação é enfática em dois pontos. Só altere essas opções depois de seguir o teste descrito no guia, e nunca as altere em um BLTouch original, porque isso pode aumentar o risco de danos à impressora.

O BLTouch 3.1, por sua vez, às vezes pisca por alguns segundos depois de uma medição bem-sucedida. O Klipper afirma que esse erro costuma ser limpo automaticamente e é inofensivo, mas que a opção probe_with_touch_mode evita o problema. Em clones e no BLTouch 2.0, essa mesma opção pode reduzir a precisão, então vale comparar o PROBE_ACCURACY antes e depois.

Tabela de comandos do BLTouch

Comando	O que faz
`BLTOUCH_DEBUG COMMAND=pin_down`	Desce o pino
`BLTOUCH_DEBUG COMMAND=pin_up`	Recolhe o pino
`BLTOUCH_DEBUG COMMAND=touch_mode`	Coloca o sensor em modo de toque para o teste com `QUERY_PROBE`
`BLTOUCH_DEBUG COMMAND=reset`	Tira o sensor do estado de alarme
`QUERY_PROBE`	Informa se o sensor está aberto ou acionado
`PROBE_ACCURACY`	Mede o mesmo ponto dez vezes para checar a repetibilidade
`SCREWS_TILT_CALCULATE`	Calcula o ajuste de cada parafuso da mesa
`PROBE_CALIBRATE`	Inicia a calibração do Z-offset pelo teste do papel
`BED_MESH_CALIBRATE`	Mede a mesa e gera a malha
`SAVE_CONFIG`	Grava os resultados no printer.cfg e reinicia o Klipper

Perguntas frequentes

O bico bateu na mesa durante o homing. O que fazer?

Desligue a impressora e refaça os testes iniciais do Klipper com pin_down, touch_mode e QUERY_PROBE. Confira também se o sensor_pin tem o ^ de pull-up, que a maioria dos BLTouch exige. Antes de deixar o pino tocar a mesa de novo, repita o teste da unha com o cabeçote longe da superfície.

Com que frequência devo refazer a malha?

Depende do que mudou. Segundo o Klipper, mudanças no sistema de movimento, no hotend, no sensor ou na inclinação da mesa invalidam o Z-offset. Por consequência, também invalidam a malha. Fora isso, uma malha salva pode ser reaproveitada, e o SCREWS_TILT_CALCULATE MAX_DEVIATION ajuda a detectar se a mesa saiu do nível.

Ainda vale usar o KAMP para malha adaptativa?

Para a parte da malha, o próprio Klipper já faz esse trabalho com BED_MESH_CALIBRATE ADAPTIVE=1. O recurso mede só a área ocupada pelos objetos definidos no G-code, com uma margem opcional. A documentação recomenda gerar uma nova malha a cada impressão nesse modo. Também avisa que ele funciona melhor em mesas cuja malha completa varia no máximo uma altura de camada.

BLTouch original ou clone?

O BLTouch original é fabricado pela Antclabs, que informa repetibilidade em torno de 0,005 mm. Muitos clones funcionam no Klipper com a configuração padrão, mas alguns exigem ajustes específicos. Em qualquer caso, o PROBE_ACCURACY mostra se o sensor que você tem é repetível o bastante.

Qual velocidade de medição usar?

O exemplo de PROBE_ACCURACY da documentação do Klipper usa 5 mm/s. Se a repetibilidade estiver ruim, o guia sugere testar outras velocidades e alturas iniciais com o próprio PROBE_ACCURACY. Depois, mantenha a combinação que der resultados mais consistentes.

Como configurar o BLTouch no Klipper e nivelar a mesa aquecida