O editor

O editor de código e a compilação

Um projeto por placa, um clang de verdade rodando na aba, e diagnósticos clicáveis.

Um projeto por placa

O painel da direita é uma estação de trabalho, não uma caixa de texto. Cada placa do diagrama é programada separadamente e tem arquivos próprios: um sketch, mais os cabeçalhos e fontes extras que você adicionar, exatamente como um projeto de verdade. Um seletor de placas no topo escolhe qual placa você está vendo; uma faixa de arquivos abaixo dele tem abas e botões para adicionar, renomear e excluir um arquivo.

Os arquivos viajam com o diagrama. Eles são salvos junto com ele, pelo id da placa, exportados e importados com ele, e excluídos com a placa.

Um diagrama sem nenhuma placa ainda tem um sketch, então você pode escrever código antes de decidir o que vai rodá-lo. Os nomes de arquivo podem ter letras, números, _, . e -, e qualquer arquivo terminado em .ino, .c, .cpp, .cc, .h, .hpp ou .hh recebe realce de C++.

Escondendo o painel de código

Quando o canvas e o código ficam lado a lado, o botão na ponta direita do cabeçalho do painel de código recolhe o código e o canvas ocupa toda a largura. Uma barra fina de Código fica na borda direita do canvas: clique nela para trazer o código de volta na largura que ele tinha. Ctrl+\ (Cmd+\ num Mac) faz as duas coisas, esteja onde estiver o foco, inclusive no código.

Seu navegador lembra a escolha, então o código fica recolhido na próxima vez que você abrir o editor. Numa janela mais estreita, onde o canvas e o código ficam empilhados, e num celular, o painel de código fica onde está.

Abas de assembly

Uma aba terminada em .S ou .s é assembly, e é compilada e linkada com as abas .ino e .cpp da mesma placa, como a IDE do Arduino compila um arquivo ao lado de um sketch. Um .S passa pelo pré-processador de C primeiro, então #include <avr/io.h> e #define funcionam nele; um .s é montado como escrito. C e assembly chamam um ao outro através de extern "C", e as abas de assembly ganham destaque próprio e a mesma barra de breakpoints de um sketch.

Uma placa também pode ser um projeto inteiro em assembly, sem o core do Arduino: escolha um projeto inicial em Assembly (sem Arduino) na seção Firmware das propriedades da placa, no Uno, no Nano, no Pro Mini, no Pico ou no STM32F411 Black Pill. Escrevendo assembly cobre os dois casos, as convenções de chamada, avr/io.h num .S, asm volatile inline e o que os erros significam.

Writing code

O painel de código edita como um editor de código de desktop faz, o Sublime Text em particular, e as teclas são as que seus usuários já usam. Todas estão listadas em Atalhos de teclado.

  • Completion as you type. The list offers the Arduino calls of the board the files belong to (pinMode, digitalWrite, analogRead, millis, the pin names), the C and C++ keywords, and the names the project already uses. After a dot it offers the object's methods: Serial. lists print, println, available and the rest, and lcd. lists what a LiquidCrystal_I2C lcd(...) declared in the file can do. After #include < it lists the libraries the board can compile.
  • Somente nomes que compilam. A lista é lida dos cabeçalhos que o próprio compilador usa para aquela placa, então um ESP32 oferece ledcAttach e um Uno não, e as classes de uma biblioteca aparecem assim que o arquivo a inclui. Um teste compila cada sugestão em cada placa.
  • Snippets. setup writes both setup() and loop(); for, if, ifelse, else, switch, while and do write the whole block. Tab moves to the next blank to fill in.
  • Vários cursores. Ctrl/Cmd+D seleciona a palavra e depois a próxima ocorrência, Alt com um clique adiciona um cursor, e Alt com um arrasto seleciona uma coluna.
  • Buscar e substituir, com expressões regulares, ir para a linha, correspondência e fechamento de parênteses, dobra de código, alternar comentário, duplicar e mover linha, e um Enter que indenta a linha seguinte sem deixar espaços no fim.
  • Auto Formatar. Ctrl/Cmd+T, como na IDE do Arduino, ou Ctrl/Cmd+Shift+F indenta de novo o arquivo aberto, dois espaços por nível, e não mexe em strings nem comentários. Numa janela comum do navegador, Ctrl/Cmd+T abre uma nova aba, então Ctrl/Cmd+Shift+F é o que vale aprender. Atalhos de teclado tem os detalhes.
  • Linhas longas quebram na borda do painel, sob sua própria indentação, então um comentário longo nunca empurra o começo do código para fora da vista. Alt+Z desativa a quebra, e o editor lembra. No celular as linhas ficam inteiras e o código rola lateralmente no tamanho que cabe no arquivo.
  • Erros no código. Depois de uma compilação, cada erro e aviso que o compilador deu fica sublinhado na sua linha. Aponte para ele para ler a mensagem, aperte F8 para ir ao próximo, ou Ctrl/Cmd+Shift+M para a lista. A próxima compilação os apaga.

O que acontece quando você aperta Rodar

Cada placa recebe uma pergunta: isso precisa compilar? Há três respostas.

  • Rodar a imagem como está. Um ELF enviado não foi compilado a partir desses arquivos, e um exemplo pronto intocado já vem compilado.
  • Reaproveitar a última compilação. A decisão é um hash de cada nome de arquivo e de cada byte nele, então um toque de tecla e um desfazer deixam você exatamente onde estava.
  • Compilar. Compila e roda o resultado.

A compilação em si é um clang de verdade e um lld de verdade, compilados para WebAssembly e rodando num Web Worker, então uma primeira compilação de quatro segundos nunca custa um quadro ao canvas. Nada é enviado, e não há servidor de compilação, nem fila, nem minutos de build.

A primeira compilação, e todas as seguintes

O toolchain são cerca de setenta megabytes de clang, transmitidos uma única vez do nosso próprio armazenamento e guardados no cache do navegador. A primeira compilação num navegador novo leva alguns segundos; uma visita de volta leva cerca de um segundo e meio, e uma edição seguida de rodar leva mais ou menos dois décimos de segundo.

Junto vem o runtime: o nosso próprio C e C++ freestanding para aquela família de placas, com os mesmos cabeçalhos, código de inicialização, script de linker e flags que o script de compilação do próprio repositório usa. É por isso que um sketch que inclui um dos drivers compartilhados compila em qualquer placa que os tenha.

A linguagem Arduino, em todas as placas

O runtime é do Mokxi, mas ele fala a linguagem da referência do Arduino: um sketch copiado de um tutorial usa as mesmas chamadas aqui e numa placa de verdade.

  • Ponto flutuante. A aritmética de float e double funciona em todo lugar, por meio de uma biblioteca de ponto flutuante em software no runtime, como num Uno de verdade, em que o chip também não tem hardware de ponto flutuante. double tem 32 bits nas placas AVR (Uno, Nano, Mega, Leonardo, ATtiny85), exatamente como no core Arduino AVR, e 64 bits nas demais. Serial.print(x, 3) imprime três casas decimais.
  • The math library. sqrt, pow, sin, cos, tan, atan2, log, exp, floor, round and the rest of math.h, plus PI, radians(), degrees(), map() and constrain(). Include <math.h> or not; either works.
  • String. Arduino's String class: + and +=, indexOf, substring, toInt, toFloat, trim, replace and the rest. Its text lives on the heap, which on an Uno is whatever of its 2 KB the sketch leaves free, so building long Strings in a loop runs out here as it does on the bench.
  • Ler a Serial. parseInt, parseFloat, readString, readStringUntil, readBytes, find e setTimeout, e uma função serialEvent() é chamada entre os loop()s quando chega uma entrada.
  • Medir a duração de um pulso. pulseIn e pulseInLong retornam a duração de um pulso em microssegundos, 0 em caso de timeout, que é como um HC-SR04 é lido. shiftIn e shiftOut transferem um byte por clock, para dentro ou para fora.
  • Som. tone(pin, frequency) e tone(pin, frequency, duration) tocam uma onda quadrada a partir de uma interrupção de timer, sem parar o sketch, e noTone(pin) interrompe o som. Num Uno isso usa o timer 2, como o core do Arduino faz, então o PWM nos pinos 3 e 11 pausa enquanto a nota toca. Na XIAO e no Uno R4, a nota toca nos pinos PWM. #include "pitches.h" fornece os nomes NOTE_.
  • A biblioteca do C. sprintf, snprintf, atoi, atof, strtol, strcpy, strcmp, strtok, dtostrf, itoa, malloc e afins. Como num Uno de verdade, %f no sprintf imprime ? nas placas AVR; use dtostrf ali.
  • Caracteres. isDigit, isAlpha, isSpace, isUpperCase e o resto.
  • std::atomic. #include <atomic> funciona em toda placa cujo core Arduino de verdade o tem: as placas ESP32 e ESP8266, as placas RP2040, as placas STM32, a Uno R4, a XIAO SAMD21 e a micro:bit. load, store, fetch_add, compare_exchange, atomic_flag e as barreiras de memória rodam. O core das placas AVR não tem <atomic>, então numa Uno, Nano, Mega, Leonardo ou ATtiny85 a compilação para, como acontece no Arduino IDE, com uma linha que diz o que usar no lugar: uma variável volatile com noInterrupts() e interrupts() ao redor do código que a toca. ATOMIC_BLOCK de <util/atomic.h> funciona nas placas AVR também.

O ATtiny85 tem 8 KB de flash e suas chamadas só alcançam 4 KB, então um sketch que puxa a biblioteca de matemática ou muito ponto flutuante costuma ficar grande demais para ele, aqui como na bancada.

Arduino libraries that compile as they are

Cole um tutorial e os includes dele funcionam: o runtime traz as bibliotecas mais usadas, com os nomes de sempre. Cada uma é um header próprio do Mokxi, escrito sobre os drivers dos componentes da caixa; nada disso é o código da biblioteca original, e cada uma mantém as chamadas que os tutoriais usam.

A tabela mostra as mais usadas nos tutoriais, não a lista completa. Digite #include < no editor para ver todas as bibliotecas que a placa em que você está consegue compilar.

Header O que controla Placas
Servo.h, ESP32Servo.h um servo de hobby em qualquer pino toda placa que compila
Wire.h I2C como mestre, nos pinos I2C da própria placa ou em quaisquer dois toda placa que compila
SPI.h SPI nos pinos SPI da própria placa toda placa que compila
EEPROM.h read, write, update, get, put, EEPROM[i] toda placa que compila
LiquidCrystal_I2C.h the 16x2 LCD behind its I2C backpack toda placa que compila
Adafruit_GFX.h, Adafruit_SSD1306.h o OLED I2C de 128x64 todas menos a ATtiny85
Adafruit_NeoPixel.h WS2812 strips and panels placas AVR, família ESP32, Pico, Uno R4
DHT.h os DHT11 e DHT22 toda placa que compila
OneWire.h, DallasTemperature.h termômetros DS18B20, quantos quiser em um pino todas menos a ATtiny85
Adafruit_BME280.h, Adafruit_BMP280.h, SparkFunBME280.h os sensores de pressão da Bosch todas menos a ATtiny85
RTClib.h os relógios DS3231 e DS1307, DateTime e TimeSpan todas menos a ATtiny85
Adafruit_INA219.h o monitor de corrente INA219 todas menos a ATtiny85
Adafruit_ADS1X15.h o ADC de dezesseis bits ADS1115 todas menos a ATtiny85
Adafruit_MCP23X17.h o expansor de portas MCP23017 todas menos a ATtiny85
SoftwareSerial.h uma porta serial em dois pinos comuns, para um HC-05 ou um GPS Uno, Nano, Pro Mini, Mega, Leonardo, Pro Micro, ESP8266, ESP32, ESP32-S3
TinyGPS++.h NMEA do GPS NEO-6M testado no Uno, Mega e NodeMCU

Onde elas diferem das bibliotecas originais, o que a página de ajuda de cada componente detalha:

  • Servo envia um pulso por write() em vez de pulsar a partir de um timer. Suas larguras são as da biblioteca original: attach(pin) vai de 544 a 2400 microssegundos, write(90) é 1472, e attach(pin, min, max) define outra janela. Os padrões do componente de servo são os mesmos 544 a 2400.
  • EEPROM é a EEPROM do próprio chip no Uno, Nano, Mega, Leonardo e ATtiny85, e 4 KB de RAM em todas as outras placas, cujos modelos não têm nada gravável que sobreviva a um reset. Um novo Rodar começa apagado em qualquer caso.
  • A fonte do display dos displays Adafruit GFX é a fonte 5x8 própria do Mokxi, com minúsculas, na célula 6x8 da original. setFont() desenha exatamente uma fonte que o sketch carrega, e os cabeçalhos de Fonts/ são as letras do Mokxi no tamanho de cada fonte, não as fontes GNU FreeFont.
  • DHT devolve floats construídos a partir dos décimos inteiros do sensor. Eles funcionam com print, isnan e computeHeatIndex, e também com qualquer aritmética sua sobre eles.
  • Wire é só mestre, e bit-banged, como todo barramento aqui.
  • SoftwareSerial nas placas AVR funciona como a biblioteca do Arduino: uma interrupção de mudança de pino e loops contados, uma porta ouvindo por vez, half duplex, um buffer compartilhado de 64 bytes. Para receber é preciso um pino com interrupção de mudança de pino, que numa Mega é 10 a 15, 50 a 53 e A8 a A15. No ESP8266, ESP32 e ESP32-S3 é o jeito do EspSoftwareSerial: bordas cronometradas numa interrupção, então várias portas recebem ao mesmo tempo. Só 8N1. Qualquer outra placa avisa disso na compilação.
  • As bibliotecas de sensores devolvem floats do mesmo jeito que o DHT, construídos a partir das próprias contagens dos chips. DEVICE_DISCONNECTED_C compara com uma leitura como nos tutoriais, e o readPressure() / 100.0F dos tutoriais de pressão funciona como escrito; readPressureHPa() também está lá.

O artigo de ajuda de cada placa diz quais pinos o Wire.begin() usa nela.

Adicionando uma biblioteca

Três faixas sob o código cuidam das bibliotecas, e adicionar uma é grátis em todos os planos:

  • Bibliotecas lista as bibliotecas do próprio projeto, cada uma com um botão de remover. + Adicionar biblioteca aceita um .zip no layout do Arduino, ou arquivos .h e .cpp soltos, e diz quais arquivos manteve e quais pulou, como exemplos.
  • Gerenciador de Bibliotecas do Arduino: todas as bibliotecas, um toque. Aperte Buscar e digite um nome, um cabeçalho ou uma palavra sobre ela. Cada resultado tem Instalar, que a baixa junto com as bibliotecas das quais ela depende. Uma biblioteca que o Mokxi já inclui diz Incluída, uma no projeto diz Instalada, e uma que não lista a placa que você está editando instala com um aviso.
  • Bibliotecas incluídas. Aperte Navegar para buscar as bibliotecas que o Mokxi traz, com Somente esta placa para manter só o que compila na placa em que você está. Adicionar #include põe o cabeçalho da biblioteca no topo do arquivo aberto (ou avisa que ele já está lá), e Detalhes mostra seus cabeçalhos e Abrir exemplo.

Um sketch que inclui uma biblioteca que o projeto não tem para no file not found do clang. A aba Compilação então nomeia o cabeçalho do Mokxi que faz o mesmo trabalho, ou oferece Instalar para a biblioteca do Gerenciador de Bibliotecas do Arduino, que a coloca no projeto e compila de novo.

Python no Pico, no ESP32 e no Raspberry Pi

Essas placas podem rodar Python em vez de um sketch. A escolha é a lista de programa na seção Firmware das propriedades da placa:

  • Raspberry Pi Pico. Escolha MicroPython (main.py) e escreva main.py. Rodar inicia o firmware oficial do MicroPython no chip simulado e copia seus arquivos .py para ele, do jeito que o Thonny faz. print() aparece no monitor serial. O Pico W faz o mesmo com sua própria versão, com network.WLAN na rede simulada. Veja a Pico e a Pico W.
  • placas ESP32. A mesma escolha inicializa o firmware oficial do MicroPython para o chip, com network.WLAN na rede simulada, no ESP32 clássico (DevKit V1, DevKitC, LOLIN32 Lite), no ESP32-S3 (com a XIAO ESP32-S3 e a Nano ESP32), no ESP32-C3 (com a XIAO ESP32-C3 e a SuperMini) e no ESP32-C6 (com a XIAO ESP32-C6). O ESP8266 não tem MicroPython aqui. Veja MicroPython no ESP32.
  • CircuitPython na Pico, na Pico W, na Arduino Nano RP2040 Connect e no ESP32-S3. Escolha CircuitPython (code.py) e escreva code.py. Rodar inicializa o firmware oficial do CircuitPython e salva code.py na unidade CIRCUITPY da placa, junto com as bibliotecas da Adafruit que ele importa. Veja CircuitPython no Pico.
  • Raspberry Pi 4, Pi 5 e Zero 2 W. A placa recebe um main.py, e Rodar o inicia com gpiozero e RPi.GPIO controlando os pinos do cabeçote. Não há Linux por baixo. Veja o Raspberry Pi.

A aba Compilação

Abaixo da faixa de arquivos. Ela fica fora do caminho até ter algo a dizer, e então mostra três coisas: as etapas com seus tempos, de modo que uma primeira compilação lenta parece progresso em vez de travamento; os diagnósticos do compilador como linhas clicáveis que levam ao arquivo, à linha e à coluna reclamados; e uma frase simples no final, como Compilado esp1.elf, 1.5 KB, 0.21 s.

Todas as placas, um só toolchain

Todas as placas compilam no navegador no mesmo toolchain clang, cada uma para o seu próprio chip: os Arduinos AVR, como o Uno (avr -mmcu=atmega328p), as placas ESP32 RISC-V, como o ESP32-C3 (riscv32 -march=rv32imc), e as placas Arm, como a Pico (thumbv6m, Cortex-M0+) e a STM32F411 (thumbv7em, Cortex-M4, soft float). A página de placas lista todas.

O detalhe completo, até a lista de comandos e as chaves de cache, está em compilar no navegador.

Se uma compilação falhar, o sketch não compila percorre o que a aba Compilação está dizendo a você.