O editor

O depurador

Pare uma placa numa linha do seu próprio código, veja o que ela estava fazendo e avance passo a passo enquanto o circuito fica exatamente onde a parada o encontrou.

Para que serve

Um LED piscando mostra que a placa está viva. Mas não mostra qual era o valor de count quando a luz apagou, nem se o branch que você acabou de escrever foi executado. O depurador mostra: aperte Rodar, pare a placa em uma linha e leia os registradores e suas próprias variáveis naquele instante.

Enquanto a placa está parada, todo o resto também está. O LED mantém o brilho que tinha, o servo fica no ângulo em que estava, os timers do chip param onde estavam. Assim, quando você aperta Continuar, millis() segue da instrução que você estava olhando, em vez de pular para frente pelo tempo que você passou lendo.

Definindo um breakpoint

Clique na faixa estreita à esquerda dos números de linha. Um ponto vermelho aparece, e a placa vai parar antes de essa linha rodar: o que você vê na tela ainda não aconteceu.

Aperte Rodar. Uma placa com um breakpoint é sempre compilada a partir dos arquivos à sua frente, mesmo que a seção Firmware da placa indique um programa pronto. Um breakpoint está em uma linha deste código, e os programas prontos vêm sem a informação que diz a qual instrução cada linha corresponde.

Clique no ponto de novo para removê-lo. Limpar todos na aba Depurar remove de uma vez todos os breakpoints dessa placa.

Uma aba de assembly tem a mesma faixa e funciona do mesmo jeito. Um breakpoint em uma linha de um arquivo .S para naquela linha, porque os números de linha que a compilação registra são os da própria aba, e não os da cópia pré-processada.

Um ponto vazado

Um ponto vazado significa que o breakpoint está onde você o colocou e não está fazendo nada: o compilador não gerou instrução para aquela linha. Linhas em branco, comentários, declarações sem código e linhas que o otimizador eliminou ficam todas assim. Mova para a próxima linha que faz algo.

A barra ao lado de Rodar

Pausar para a placa onde ela estiver. Vira Continuar, que deixa ela seguir.

Passo por cima roda uma linha de código-fonte, chamadas incluídas: uma linha que chama delay(500) leva 500 ms de tempo simulado e o resto do circuito vive tudo isso, porque é isso que acontece de verdade.

Passo para dentro roda até a próxima linha que a placa alcança, que é a primeira linha de uma função chamada pela linha atual.

Um passo pode ser interrompido por um breakpoint mais adiante, e ele para lá e avisa. O único breakpoint que nunca interrompe um passo é aquele de onde o passo começou: uma interrupção naquele instante (um timer, um pino, o tique que millis() conta) roda seu tratador e devolve a placa exatamente para a linha em que você estava, e parar ali significaria que o aperto não fez nada.

Passo para fora está esmaecido, e a dica diz por quê: seria preciso descobrir para onde a função atual retorna, e o depurador não lê a pilha de chamadas. Coloque um breakpoint na linha seguinte à chamada.

Passo de instrução, na seção Disassembly da aba Depurar, roda exatamente uma instrução de máquina em vez de uma linha inteira.

No celular a barra vai para a aba Depurar, onde há espaço para ela.

A aba Depurar

Ao lado do monitor serial na parte de baixo da janela (uma aba própria na folha no celular), com cinco coisas dentro.

Onde parou, em uma linha: o arquivo e a linha, o endereço e por que parou: um breakpoint, um passo ou Pausar. Quando a tabela de linhas não cobre o endereço, ele mostra o endereço e avisa, em vez de citar uma linha sobre a qual não tem certeza. "Dentro de sketch.ino:14" significa que a placa está no meio daquela linha, não no começo dela, e o destaque no painel de código é desenhado mais suave para combinar.

Registradores, com os nomes que o próprio core usa: a0 e sp num ESP32-C3, r24 e sreg num Uno. Eles são lidos do core na parada, então são o que ele guarda agora e não o que guardava da última vez. O pc vem primeiro, e é a instrução que vai rodar em seguida.

Um registrador de status também é escrito por extenso ao lado do número, porque oito bits não são um valor só. Num AVR, sreg mostra seus flags como ITHSVNZC, com um ponto no lugar de cada flag zerado, então uma parada logo após um cp mostra de relance se o branch será executado. Numa placa ARM, xpsr mostra N Z C V Q do mesmo jeito.

Disassembly é o código de máquina ao redor da parada. Cada linha é uma instrução: seu endereço, seus bytes, a própria instrução na grafia que o llvm-objdump usa, e a linha de código-fonte onde ela começa, que é um botão que leva você a essa linha no painel de código. A instrução prestes a rodar fica marcada. Passo de instrução, no topo da seção, roda aquela instrução e redesenha a lista.

Esta é a visão para abrir numa aba .S: a linha que você escreveu está ao lado dos bytes que ela montou. Funciona igualmente bem num sketch, onde mostra o que o compilador fez de uma linha de C++. Uma placa que não foi compilada a partir de seus arquivos avisa, porque não há programa para ler até você apertar Rodar.

Observar recebe o nome de uma variável global. Comece a digitar e ele oferece as que seu programa tem. Cada linha mostra o tipo como o compilador registrou e quantos bytes esse tipo ocupa, depois o valor, lido da memória da placa a cada parada. Um nome que o programa não tem avisa, em vez de mostrar um zero. Um struct ou um array mostra seus bytes, endereço baixo primeiro, porque são bytes e não um número só.

Breakpoints lista todos os desta placa com o endereço ao qual cada um resolveu. Clique em um para ir até ele no código.

O que o monitor serial faz enquanto isso

Nada muda. Tudo que a placa imprimiu antes da parada continua lá, e o que ela imprimir depois que você continuar aparece logo abaixo. Parar uma placa não é parar a execução.

Duas placas

Cada placa tem seus próprios breakpoints, sua própria lista de observação e sua própria parada. O depurador age sobre a placa que o painel de código está mostrando, que é a indicada pelo seletor acima das abas.

Em quais placas ele funciona

Em todas. Toda placa que o Mokxi tem responde ao depurador: a ESP32-C3 e a ESP32-C6, a ESP32 e a ESP8266, a Arduino Uno, Nano, Mega, Leonardo e Uno R4 Minima, a ATtiny85, a Raspberry Pi Pico e Pico W, a STM32 Black Pill e Blue Pill, a BBC micro:bit e a Seeed XIAO SAMD21.

Os registradores são os que o core da própria placa tem, com os nomes que a documentação dele usa: a0 e sp numa ESP32-C3, r24 e sreg num AVR, r0, lr e xpsr em qualquer placa com um ARM dentro, a0 a a15 nas placas Xtensa (a ESP32, a ESP32-S3 e a ESP8266). Então o que você lê no painel é o que leria no componente real.

Sair fica cinza em todas as placas, pelo motivo que a dica dele dá.

A barra ainda pode ficar cinza por um motivo que não tem nada a ver com a placa: nada está rodando ainda, ou o componente que o painel de código mostra não roda programa nenhum (um resistor não pode ser parado). Uma placa que o depurador realmente não alcançasse se identificaria ("O depurador ainda não dá suporte ao mega1."), e nenhuma placa faz mais isso. Uma placa que ele alcança nunca fica cinza por falta de breakpoint: o Pausar funciona assim que a placa está rodando, com breakpoint ou sem.