06

YOSHIMITSU — a solução completa: todos os cheatcodes, um pergaminho

Uma fábula de cheatcodes onde só há vencedores. Um sketch relaxado, seis posturas, um arnês permanente: a parada CRSF→PWM (KINCHO), a levitação giroscópica do Zephyrus (MANJI_DRAGONFLY), o gravador de bolso (FLEA · MEDITATION), a bancada sem espada (NSS), o espelho que nunca olha para trás (BACK_TURNED) — mais YOSHI, a aurora sempre acesa, e JIGUANG (極光), o administrador meditante que conta a lenda. Liga uma vez, grava uma vez; depois disso a biblioteca atualiza-se e o trono comanda.

Uma placa, seis posturas

YOSHIMITSU é o Shinobi Hermético com seis posturas — cada postura uma vitória diferente, todas vestindo a mesma alma. Um sketch relaxado compila para as duas placas; as posturas alternam por comando USB, botão GPIO0 (ESP32-S3) ou toques de RESET (RP2040-Tiny):

Postura Significado
KINCHO Conversor CRSF→PWM — a parada (o CRC descarta o falso). Sem nomes de canal, sem giroscópio.
MANJI_DRAGONFLY Conversor + ligação giroscópio Zephyrus (MPU6050 opcional) — a levitação.
FLEA Gabarito de ciclo de energia — o levantar que derruba o RX no seu bootloader.
MEDITATION Flasher de bolso — a cabeça-esponja, poupando energia, pronta para ser gravada.
NSS Bancada sem-espada — servo direto por USB, sem RF.
BACK_TURNED A inércia enganosa — um espelho UART vivo. Nunca olha para trás.

Um sketch, dois alvos: sketches/yoshimitsu/yoshimitsu.ino compila para o Waveshare RP2040-Tiny (o mais leve, sem botão a bordo) e para qualquer ESP32-S3 com USB nativo, com os cores padrão arduino-pico / arduino-esp32. No Arduino IDE o mesmo sketch vive em File → Examples → Yoshimitsu → Yoshimitsu_Default.

YOSHIMITSU — o firmware combinado

YOSHIMITSU é o firmware recomendado. Ele arranca em KINCHO (o conversor) e move-se entre as posturas. A consola USB é o interruptor canónico nas duas placas — KINCHO → MANJI → FLEA → MEDITATION → NSS → BACK → POSE <n>. No ESP32-S3 o botão BOOT (GPIO0) é uma segunda superfície:

Contexto Gesto Ação
qualquer postura toque duplo cicla KINCHO → MANJI → NSS → BACK → KINCHO →
qualquer postura pressão longa 2 s entra em MEDITATION
MEDITATION / FLEA toque simples reinicia o recetor (executa o novo firmware)
MEDITATION / FLEA toque duplo FLEA — derruba o recetor no seu bootloader

A cablagem é um arnês permanente — os mesmos fios servem todas as posturas, por isso nunca voltas a cablar entre voar e gravar. Em MEDITATION o caminho USB→UART é uma ponte puramente transparente (sem parsing de linhas), por isso o tráfego SLIP binário do esptool atravessa intocado. Fonte completa: sketches/yoshimitsu/yoshimitsu.ino (o sketch relaxado), src/Yoshimitsu.h (o núcleo) e src/Yoshimitsu_Loadout.h (o loadout inicial).

A biblioteca — atualizar sem voltar a tocar no teu sketch

YOSHIMITSU é uma biblioteca com um sketch fino por cima — o Shinobi inteiro vive na biblioteca, o sketch guarda apenas a tua configuração. Instala a pasta uma vez como biblioteca Arduino; File → Examples → Yoshimitsu → Yoshimitsu_Default entrega-te um sketch pronto e relaxado, com pinos, portões e as poucas flags que pertencem ao código. O núcleo vive em src/Yoshimitsu.h, todos os valores por omissão em src/Yoshimitsu_Loadout.h (o loadout inicial, valores *_DEFAULT). Para atualizar: git pull na biblioteca — ou larga uma nova release — e o teu sketch fica intocado. Uma atualização de firmware nunca é uma recablagem e nunca é uma reconfiguração.

KINCHO — Conversor CRSF→PWM

KINCHO — a postura conversora — lê CRSF a 420 000 baud na UART, conduz os servos com uma janela de 988–2012 µs mapeada da gama de canais 172–1811, e centra-os num failsafe de 500 ms. A parada é a verificação CRC: um frame corrompido é descartado antes de alguma vez chegar a um servo. O conversor é agnóstico ao canal — os servos são SERVO_PIN_1..8 e a tabela CHANNEL_TO_SERVO decide qual canal CRSF alimenta cada um; o significado do canal pertence ao mixer/kernel, nunca à placa.

Para um ornitóptero estabilizado por giroscópio, usa MANJI_DRAGONFLY — o mesmo conversor mais a ligação Zephyrus: um MPU6050 opcional em GYRO_SDA/GYRO_SCL alimenta uma correção de taxa de guinada no servo da crista. Sem giroscópio ligado, MANJI_DRAGONFLY degrada com graça para KINCHO. Uma placa conversora CRSF→PWM comercial não tem via de giroscópio nenhuma — recetores da classe EP2 não trazem IMU, por isso Zephyrus vive em YOSHIMITSU, não no recetor.

Se o teu recetor já fala PWM (uma placa de 5 ch ou 7 ch), não precisas das posturas conversoras de todo — MEDITATION abaixo é então a tua única razão para teres o S3.

KINCHOI — Flasher de bolso para recetores da classe EP2

O problema: recetores da classe EP2 (HappyModel EP2, EP1, EPW6, …) expõem CRSF em pads ameados e carregam um minúsculo pad BOOT. Usar um adaptador FTDI significa segurar uma sonda contra dois pads de 1 mm enquanto se cicla a energia do recetor — desconfortável, e voltas a soldar ou a prender de cada vez que o firmware precisa de atualização.

A solução: deixa o ESP32-S3 ser o flasher. Um GPIO segura o pad BOOT do recetor em baixo; um pequeno P-MOSFET comuta o barramento de 3,3 V do recetor sob controlo de software; a porta USB torna-se a porta série. Carrega num botão do S3 e ele executa a dança exata de ciclo de energia que derruba um ESP8285 no seu bootloader de ROM — depois o esptool escreve direto através da ponte. Sem FTDI, sem sondas, sem soldaduras repetidas: solda os pads do recetor uma vez a um rabicho curto e reutiliza-o para sempre.

Lista de peças:

Peça Referência típica Custo
Micro placa ESP32-S3 (USB nativo) Waveshare ESP32-S3-Tiny / -Micro / -Nano ~6 USD
MOSFET de canal P de nível lógico AO3401 (SOT-23) numa pequena breakout ~1 USD
Resistência 10 kΩ (pull-up da gate) — <0,10 USD
Fios Dupont / rabicho + termorretrátil — ~1 USD
Recetor ELRS, pads com rabicho uma vez EP2 / EP1 / EPW6 (SX1280 + ESP8285) desde ~12 USD

A ponte funciona com qualquer recetor ELRS ESP8285/SX1280 que exponha TX, RX, 3V3, GND e um pad BOOT — a esmagadora maioria das *placas concretas* na tabela de hardware . Também grava o próprio S3, claro: botão BOOT + USB é tudo o que ali é preciso.

Ligação do suporte de gravação

Liga o jig com o S3 desligado. O MOSFET comuta o barramento de 3,3 V do recetor: source → S3 3V3, drain → EP2 3V3, gate → S3 GPIO10 com pull-up de 10 kΩ para 3V3 (gate alta = MOSFET desligado). O GPIO9 comanda o pad BOOT.

Pad EP2 / RX Pino ESP32-S3 Função
BOOT (RX GPIO0) GPIO9 Linha de retenção de boot (baixo = entrar no bootloader)
3V3 Dreno do MOSFET Barramento comutado (source → S3 3V3, gate → GPIO10)
TX (CRSF out) GPIO18 (U1RX) RX → TX (cruzado)
RX (CRSF in) GPIO17 (U1TX) TX → RX (cruzado)
GND GND Terra comum (obrigatório) 
S3 3V3   ──► S ── P-MOSFET (AO3401) ── D ──► EP2 3V3
S3 GPIO10 ──► gate         (10kΩ pull-up to 3V3; LOW = ON)
S3 GPIO9  ──► EP2 BOOT pad (asserted LOW during power-up)
S3 GPIO18 ◄── EP2 TX       (U1 RX)
S3 GPIO17 ──► EP2 RX       (U1 TX)
S3 GND     ──► EP2 GND

Modo de gravação

MEDITATION arranca em passagem transparente (USB ↔ UART a 115 200 baud). Para entrar em modo de gravação, faz duplo toque no botão BOOT do S3 (ou escreve FLEA na série USB). O sketch então:

  1. puxa GPIO9 para baixo (pad BOOT ativo),
  2. desliga o MOSFET por 120 ms (recetor sem energia),
  3. volta a ligá-lo e espera 900 ms (recetor arranca dentro do seu bootloader),
  4. liberta GPIO9 — o RX agora está no bootloader de ROM, à espera do esptool,
  5. retoma a passagem USB↔UART para o esptool poder falar com ele.

Como a ponte não consegue comandar as clássicas linhas de auto-reset DTR/RTS, grava sempre com --before no_reset — a dança de ciclo de energia acima é o reset. Depois de gravar, um único toque BOOT volta a ciclar a energia do recetor para ele arrancar o novo firmware; um duplo toque apenas reentraria no modo de gravação.

Gravar o PteronautOS através do S3

Compila o firmware (ou obtém um release) e depois corre o esptool contra a porta série USB do S3. No macOS a porta aparece como /dev/cu.usbmodem*:

# 1. Compila o PteronautOS (da raiz do repositório)
pio run -e PteronautOS_ESP8285_2400_RX

# 2. Deita o RX no modo de gravação (escreve FLEA, ou duplo toque em BOOT), depois:
python3 -m esptool --chip esp8285 \
  --port /dev/cu.usbmodemXXXX --baud 115200 \
  --before no_reset write_flash \
  --flash_mode dout --flash_size 1MB --flash_freq 40m \
  0x0 .pio/build/PteronautOS_ESP8285_2400_RX/firmware.bin

# 3. Reinicia o RX mais uma vez (um toque BOOT) para correr o novo firmware.

As definições de gravação (dout, 1 MB, 40 MHz) correspondem ao alvo ELRS ESP8285 de fábrica — nunca uses qio nem um tamanho maior. Depois de gravar, a mesma porta USB mostra o registo de arranque do recetor: abre-a a 115 200 baud e procura o banner PteronautOS e, assim que um emissor se ligar, as mensagens de ligação CRSF. A ponte ainda serve de consola de campo para telemetria ao vivo.

Verificação e primeiro voo

Uma vez gravado, o mesmo recetor voa — nenhum FTDI fica para trás.

O build de bolso RP2040-Tiny

Prefere o Waveshare RP2040-Tiny (~5 USD) — ou o seu gémeo, o RP2040-Zero, que partilha exatamente o mesmo pinout. Todas as seis posturas correm no RP2040 sem nenhum botão legível: os taps BOOT/RESET do adaptador apenas comandam BOOTSEL/RUN, por isso o YOSHIMITSU-RP2040 é comandado pela porta série USB, mais um contador de taps RESET sem botão.

Para gravar o próprio RP2040-Tiny, segura BOOT enquanto ciclas a energia (ele monta como disco de armazenamento em massa), larga o .uf2 lá, depois pressiona RESET uma vez — a placa reinicia em KINCHO a correr o novo firmware. Configura uma vez, grava uma vez, nunca mais mexes.

Mapa de pinos RP2040-Tiny

Função Pino RP2040-Tiny Nota
CRSF RX ← TX do recetor GPIO1 (UART0 RX) 420 000 baud
CRSF TX (não usado, ligado por completude) GPIO0 (UART0 TX) Cruzado: TX → RX
Ponte RX ← TX do recetor GPIO9 (UART1 RX) 115 200 baud
Ponte TX → RX do recetor GPIO8 (UART1 TX) Cruzado: TX → RX

Servo 1 (SERVO_PIN_1)

 GPIO2

PWM — canal via CHANNEL_TO_SERVO

Servo 2 (SERVO_PIN_2)

 GPIO3 PWM

Servo 3 (SERVO_PIN_3)

 GPIO4 PWM
Gyro SDA (MPU6050, opcional) GPIO10 MANJI_DRAGONFLY
Gyro SCL (MPU6050, opcional) GPIO11 MANJI_DRAGONFLY
RX BOOT (GPIO0 do recetor, ativo baixo) GPIO5 Baixo = entrar no bootloader
RX PWR (gate do P-MOSFET, baixo = ligado) GPIO6 Barramento comutado de 3,3 V
LED de estado GPIO16 WS2812B

O mapa de pinos completo é um bloco editável no topo de sketches/yoshimitsu/yoshimitsu.ino — gamas e colisões de pinos são validadas por um POST de arranque, e números de UART inválidos recusam-se a compilar em vez de se portarem mal no ar.

YOSHI — a aurora das posturas sempre ativa

YOSHI ("a aurora") é o cheatcode que está sempre ligado. YOSHI_RGB transforma o único WS2812B embarcado num anel de humor vivo: cada postura respira a sua própria cor e ritmo, para leres a mente do ronin do outro lado da sala sem um único byte de série. Cor e padrão de piscar contam a história — nenhum comando extra é preciso; a postura é o cheatcode, a luz é o seu eco.

Postura Aurora (cor → ritmo)
KINCHO respiração verde lenta + um flash de dupla parada nítido (o golpe CRC)
MANJI_DRAGONFLY uma roda de cores a girar como os rotores do gyro (a levitação)
FLEA estroboscópio âmbar frenético e crescente (o levantar)
MEDITATION violeta quase escuro + um batimento lento — pronta para ser gravada
NSS flash de triplo toque nítido em azul (lâmina embainhada, tempo a subir)
BACK_TURNED quase negro + um lampejo carmesim imprevisível (o espelho — nunca olha para trás)

O RGB vive no RP2040-Tiny (RGB_LED_PIN=16) atrás de YOSHI_RGB; o ESP32-S3 mantém o seu sóbrio LED de estado. Todas as cores são pura matemática inteira — sem float, sem malloc, sem delay() — e pumpRgb() é limitado a ~50 fps para a ponte flasher byte-exata nunca ser perturbada. A regra hermética mantém-se: a pose muda, a luz segue.

JIGUANG — o narrador · comentador · administrador

Três nomes, uma alma — o triângulo de cheatcodes da solução completa: YOSHIMITSU é todo o firmware do Shinobi Hermético; YOSHI é o cheatcode RGB (a aurora de postura sempre acesa); e JIGUANG (極光, "a aurora") é o administrador meditante — o motor imóvel sentado de pernas cruzadas no trono MEDITATION. A voz de Yoshimitsu é funcional e seca; a de JIGUANG é o mito. 極光 é o prompt da consola, não um adorno: para agir como administrador escreves 極光 e depois o comando — senão o trono fica fora de alcance. O prompt é um #define (JIGUANG_PROMPT), por isso o teu sketch pode renomeá-lo; todo o contador de histórias esconde-se atrás do portão de compilação JIGUANG (1 = omnipresente, 0 = nem um único byte de 極光 compilado).

Easter egg: escreve 極光 LEGEND e a lenda inteira desenrola-se como um pergaminho ASCII — as posturas, os cheatcodes, o trono e o prompt que nunca morre. JIGUANG / jiguang / 極光 nunca morre — nem no código, nem nos comentários, nem neste tutorial.

Acorda a voz com 極光 JIGUANG e ela sobe quatro níveis: 0 cordeiro (silenciosa, embora comandos explícitos ainda respondam), 1 conto (arranque e cada mudança de postura narrados), 2 pergaminho (+ a leitura dos canais CRSF) e 3 omni (+ os bytes de debug ELRS do recetor passados verbatim). 極光 MUTE silencia-a; 極光 CRSF imprime o pergaminho de 16 canais e 極光 SCORE desenrola o placar arcade HIGHSCORE — frames CRSF bons, eventos de failsafe, bytes da ponte e uptime. JIGUANG nunca toma a postura: CRSF, servos e a ponte continuam a obedecer à pose enquanto a lenda é contada.

Em MEDITATION a cabeça-de-esponja é o trono de JIGUANG — e o trono está guardado: cada comando de administrador começa com o prompt da consola 極光. Do céu USB-serial ele responde 極光 STATUS, 極光 CRSF, 極光 SCORE, 極光 POSE, 極光 DOC (o catálogo de cheatcodes) e 極光 SETUP (o assistente de meditação, que guia as definições-chave em vez de uma muralha de defines). As mudanças de postura ficam abertas — KINCHO, MANJI, FLEA, MEDITATION, NSS, BACK, POSE n. A pose poupa energia como a velha pausa de meditação, e o ronin fica pronto a ser gravado. No instante em que o byte SLIP do esptool chama, o trono cede à ponte transparente do gravador e lá fica até MEDITATION reentrar. Com YOSHI_RGB no nível 3 o contador de histórias também veste a aurora: jiguang(ms) pinta uma roda lenta de espetro completo que tece cada cor de postura num único fôlego.

MUSHIN 無心 — o cheatcode da memória muscular

MUSHIN (無心, "mente vazia") é a funcionalidade-heroína — o desapego, a espada que golpeia antes do pensamento. Nas artes da espada, 無心 é a mente que se solta de si mesma: nenhum intervalo resta entre o que é visto e o que é feito. O PteronautOS é o espírito: planeia a onda da asa e envia intenções de servo pela ponte. YOSHIMITSU não se agarra ao plano: responde no músculo com o PID local do giroscópio Zephyrus, os servos já em movimento antes que o próximo pensamento se agarre. Dois núcleos, um golpe — nenhuma outra placa ELRS-PWM pode vestir isto.

Arma-o a partir do trono: 極光 MUSHIN relata, 極光 MUSHIN ON/OFF arma ou desarma, e a escolha persiste em flash — arranca pronto. No sketch, MUSHIN arranca armado por omissão; a flag de administrador é o interruptor de runtime, por isso nunca recompilas para o mudar.

O protocolo v0 da mente vazia atravessa os mesmos dois fios do gravador: [0x9B][len][type][payload][xor] — 0x01 intenções (espírito→músculo, n×uint16 µs), 0x02 keepalive de anúncio, 0x03 telemetria do giroscópio. Intenções frescas (dentro de 500 ms) acionam os servos; o PID local do giroscópio segura a crista. Se o fio ficar mudo, YOSHIMITSU volta ao seu próprio músculo CRSF — degradação graciosa, nunca um stick morto.

Em voo a divisão é o ganha-ganha: o recetor faz o pensamento antes do golpe (CRSF, Zephyrus, a alma do mixer), e YOSHIMITSU faz o que vive no músculo (PWM PIO sem glitches). Helicóptero ou bater de asas — da vista da espada é igual: uma trajetória canónica, e a espada nunca pergunta que vaso carrega. A pose continua a voar; só muda a aparência.