Referência

Contrato da placa ESP8266 NodeMCU (Onda C de placas)

O LX106 na ABI call0, o GPIO16 que não é um GPIO, PWM por software e o único bloco cujos registradores são inventados.

Esta é a referência de engenharia do modelo: o que ele implementa, registrador por registrador, para quem escreve firmware para ele. Para usar a placa no editor, comece por A ESP8266 NodeMCU e página da placa.

A NodeMCU V1.0 é a placa de trinta pinos em torno de um módulo ESP-12E: um Xtensa LX106 a 80 MHz, o menor e mais antigo componente aqui e ainda aquele que foi a primeira placa WiFi da maioria das pessoas. Um componente do kernel (esp8266 em crates/parts) envolve um modelo de SoC ESP8266 (crates/esp8266) no mesmo interpretador Xtensa do ESP32 (crates/xtensa-core), numa configuração diferente. Este documento é o contrato, e ele prevalece sobre qualquer comentário no código.

O tipo do catálogo é esp8266. A string de program do catálogo é elf32 xtensa lx106 esp8266.

Leia a seção 6 primeiro se você leva uma compilação daqui para silício real. A maior parte desta placa está no endereço real; o ADC não está, e isso está dito na seção 3.5, na página da placa e no artigo de ajuda, além de aqui, porque a Espressif nunca publicou a interface de registradores do conversor TOUT.

A sketch for this board compiles in the browser with clang-v3, the wasm build of Espressif's LLVM fork (-mcpu=esp8266), published 2026-09-28 and checked on this simulator (docs/compile.md). An untouched example still runs its prebuilt ELF from web/public/firmware/esp8266/, which Espressif's GCC builds. Section 7 has the details.

1. Pinos da placa (ordem do catálogo)

Vista de cima, o conector micro-USB embaixo, o módulo ESP-12E e sua antena de PCB no topo. A placa tem 48,3 x 25,6 mm e seus dois conectores de 15 pinos ficam a 22,86 mm (0,9 polegada) de distância, então ela encaixa numa protoboard deixando uma fileira de furos livre de cada lado. O visual a desenha nesse tamanho.

Essa é a V1.0 Amica, a placa que este componente modela. A V3 "LoLin", que as pessoas também chamam de NodeMCU, é mais larga, com uma polegada inteira entre as fileiras de conectores: numa protoboard, ela não deixa nenhuma fileira livre, e é daí que vem a fama dessa placa de precisar de duas protoboards.

Conector esquerdo, de cima para baixo (15 furos): A0, RSV, RSVb, SD3, SD2, SD1, CMD, SD0, CLK, GND, 3V3, EN, RST, GNDb, VIN.

Conector direito, de cima para baixo (15 furos): D0, D1, D2, D3, D4, 3V3b, GNDc, D5, D6, D7, D8, RX, TX, GNDd, 3V3c.

30 pinos. Nomes duplicados recebem uma letra porque os nomes de pino do catálogo são únicos.

Os nomes na serigrafia não são números de GPIO

Essa é a única coisa em que essa placa pega as pessoas de surpresa, então está escrito aqui, no artigo de ajuda e na página da placa:

serigrafia D0 D1 D2 D3 D4 D5 D6 D7 D8 RX TX
GPIO 16 5 4 0 2 14 12 13 15 3 1

digitalWrite(2, HIGH) é D4, e não D2. O runtime define D0 para D8 então um sketch pode usar qualquer um dos dois, e crates/parts/src/parts/esp8266.rs tem um teste que cobre a tabela inteira.

Oito pinos do conector que não estão ligados a nada

SD0, SD1, SD2, SD3, CMD e CLK são os GPIO 7, 8, 9, 10, 11 e 6: os seis fios do chip de flash, dos quais o programa está em execução. Eles estão no conector de um NodeMCU de verdade, então estão neste componente; aqui eles não acionam nem são lidos. Os dois pinos RSV são iguais. Um sketch que funcionou num simulador por usar SD1 travaria o flash numa bancada real, e é justamente isso que este componente existe para evitar.

A0 fica atrás do divisor de tensão da placa

O pino TOUT do chip converte 0 a 1.0 V. Um NodeMCU coloca um divisor de 220k/100k na frente dele, então o A0 do conector vai de 0 a cerca de 3.2 V, e um potenciômetro ligado ao trilho de 3.3 V praticamente cobre toda a faixa. O divisor pertence à placa, não ao chip, então ele vive no componente da placa: o pino carrega seu nó com 320 k e o SoC recebe um terço da tensão que chega ao pino do chip. A0 não é um GPIO e não pode ser escrito.

Os dois LEDs, ambos ativos em nível baixo

  • GPIO 2, que é D4, tem o LED azul do módulo ESP-12. Ele também é o TX da UART1 num componente real, e é por isso que um sketch que usa Serial1 o perde.
  • GPIO 16, que é D0, tem o LED da placa de suporte do NodeMCU.

Ambos são ligados de 3V3 ao pino, então LOW os acende. Inverter essa lógica é o erro que essa placa mais provoca, então probe informa cada lâmpada como acesa quando seu pad está em nível baixo (seção 5).

GPIO 16 não é um pino comum

D0 é o pino do RTC. Ele não está em nenhum registrador do bloco de GPIO (tem seus próprios registradores de saída, habilitação e entrada no bloco RTC, seção 3.2); tem pull-down enquanto todos os outros pads do componente têm pull-up, e não pode gerar interrupção. Num NodeMCU, é o pino que você liga ao RST para acordar do deep-sleep, e ele é D0, então não é uma peculiaridade que um sketch possa ignorar.

Electrical: every GPIO drives push-pull at 3.3 V through R_STRONG, sits high-Z, or pulls through 45 k. An input reads high at 1.65 V; a contended (Unknown) net reads 0, and a floating one reads noise, as on the Uno (docs/uno.md section 1); the board's boot straps hold GPIO0 and GPIO2 high and GPIO15 low when nothing else does. 3V3 drives 3.3 V at R_SUPPLY, VIN drives 5 V, the four grounds drive 0 V. RST and EN are tied to the same node here, as a NodeMCU ties them, with a 10 k pull-up to 3.3 V; pulling either below 1.65 V holds the core in reset. The capacitor beside that resistor is the board's power-on reset and is not modeled.

A ordem exata da serigrafia dos dois conectores é a leitura que este modelo faz do pinout do NodeMCU V1.0 (Amica). Os números de GPIO são os do chip e são dos quais o firmware depende; a posição deles no conector é aquela de que um diagrama depende. Uma V3 LoLin move dois deles além de ser mais larga, e um circuito desenhado aqui precisaria ser religado para uma delas.

2. Mapa de memória

IRAM (instruções) 32 KB em 0x4010_0000 a 0x4010_7FFF
IROM (flash code and constants) 0x4020_0000, read-only, up to 1,044,464 bytes
DRAM (dados) 80 KB em 0x3FFE_8000 a 0x3FFF_BFFF
topo da pilha 0x3FFF_C000
UART0 0x6000_0000, seção 3.4
GPIO 0x6000_0300, seção 3.1
RTC (GPIO16) 0x6000_0700, seção 3.2
IO_MUX 0x6000_0800, seção 3.3
SAR (TOUT) 0x6000_0D00, seção 3.5, exclusivo deste modelo

Cada bloco de periférico ocupa 0x100 aqui, porque neste componente eles realmente estão assim próximos uns dos outros.

Three windows, as on the real part: the vectors, the exception entry and the startup code in iram1_0_seg (the 32 KB of instruction RAM), the rest of the code and every constant in irom0_0_seg, which a real ESP8266 reads from flash through the cache at 0x4020_0000, and the data in dram0_0_seg. Every ESP8266 linker script uses these names and these addresses.

The Arduino IDE gives a NodeMCU sketch 1,044,464 bytes of flash by default ("4MB (FS:2MB OTA:~1019KB)"), and that is the room here: code, literals, constants, startup code and the initial values of the variables, which is what the IDE adds up and the editor prints after a build. The flash window is a read-only view of the loaded image, not a cache: there are no misses and no timing, so a fetch from flash costs what a fetch from IRAM costs here. A store to it faults. Global variables are limited by the 80 KB of data RAM and a program over it is refused with "no room for the stack". Literal pools sit in front of their own functions (L32R reaches 256 KB backwards) and calls out of the startup code go through a register (CALL0 reaches 128 KB).

Every PT_LOAD segment must land inside one of those three ranges; anything else is refused with the offending address in the message, and the chip is left with no program.

The core resets with pc at the ELF entry point and every address register zero. There is no boot ROM: the real part's ROM loader, the flash reads, the cache set-up and the SDK's own initialization are absent, and firmware/esp8266/crt0.S makes the state it wants explicit.

3. Registradores de periféricos

Apenas o subconjunto abaixo está implementado. Qualquer outra coisa dentro de um bloco mapeado lê 0 e conta como acesso perdido; qualquer coisa fora de todos os blocos é uma falha de acesso.

3.1 GPIO (0x6000_0300)

Dezessete pinos, mas apenas dezesseis estão aqui: GPIO 0 a 15 são comuns e GPIO 16 está no bloco RTC (seção 3.2).

offset registrador
0x00 GPIO_OUT
0x04 GPIO_OUT_W1TS
0x08 GPIO_OUT_W1TC
0x0C GPIO_ENABLE
0x10 GPIO_ENABLE_W1TS
0x14 GPIO_ENABLE_W1TC
0x18 GPIO_IN
0x1C GPIO_STATUS
0x20 GPIO_STATUS_W1TS
0x24 GPIO_STATUS_W1TC
0x28 + 4n GPIO_PINn, para n em 0..16

Verificado no sentido que este componente permite: a base e cada offset aqui são os que todo cabeçalho de ESP8266, script de linkedor e descrição aberta de registradores usa há uma década, e são o que o ESP8266 Technical Reference Manual da Espressif dá para o bloco de GPIO. Não são números que este modelo escolheu.

O bit 2 PAD_DRIVER de GPIO_PINn torna o pad open drain; os bits 7..9, INT_TYPE, escolhem o que gera a interrupção do pino: 0 desligado, 1 borda de subida, 2 borda de descida, 3 qualquer borda, 4 nível baixo, 5 nível alto. Não há matriz de GPIO neste componente: um pad é GPIO ou é de um periférico, e a escolha é feita no IO_MUX.

Não há bit de habilitação de interrupção por pino além de INT_TYPE, nem segunda metade de nenhum registrador, porque dezesseis bits é tudo de que o bloco precisa.

3.2 Os registradores RTC por trás do GPIO16 (0x6000_0700)

offset registrador bits
0x68 RTC_GPIO_OUT o bit 0 é o nível de saída do GPIO16
0x74 RTC_GPIO_ENABLE o bit 0 é o driver de saída do GPIO16
0x8C RTC_GPIO_IN_DATA o bit 0 é o que o pad do GPIO16 está vendo
0x90 RTC_GPIO_CONF bit 0 clear puts the pad under RTC_GPIO_ENABLE
0xA0 PAD_XPD_DCDC_CONF os bits 0..1 selecionam o GPIO16 em vez do pino do DCDC

Acreditado em vez de verificado. Estes cinco são os registradores que toda sequência de GPIO16 do ESP8266 usa desde 2015 e os que o pinMode(16, ...) do core do Arduino escreve, mas não são uma página de manual citada de volta. O pull deste pad é um pull-down, diferente de todos os outros pads do componente.

Nada mais no bloco RTC é modelado: sem contador RTC, sem memória RTC, sem deep sleep, sem fonte de wake.

3.3 IO_MUX (0x6000_0800)

PERIPHS_IO_MUX_CONF_U em 0x00, depois um registrador por pad. O bit 7 é o pull-up interno.

Não há bit de habilitação de entrada em lugar nenhum, nem pull-down interno nos GPIO 0 a 15. O buffer de entrada de um ESP8266 está sempre ligado, e INPUT_PULLDOWN não existe neste componente; só o GPIO16 tem um pull-down, e ele fica no bloco RTC. Um sketch que precise de um pull-down precisa de um resistor.

Como no ESP32, os registradores estão em ordem de pad, não de GPIO:

GPIO offset GPIO offset
0 0x34 8 0x24
1 0x18 9 0x28
2 0x38 10 0x2C
3 0x14 11 0x30
4 0x3C 12 0x04
5 0x40 13 0x08
6 0x1C 14 0x0C
7 0x20 15 0x10

Acreditado em vez de verificado. O GPIO16 não tem nenhum registrador de IO_MUX.

3.4 UART0 (0x6000_0000)

offset registrador
0x00 UART_FIFO
0x04 UART_INT_RAW
0x08 UART_INT_ST
0x0C UART_INT_ENA
0x10 UART_INT_CLR
0x14 UART_CLKDIV
0x1C UART_STATUS
0x20 UART_CONF0
0x24 UART_CONF1

Verified: the base and every offset, and the bits below, against the ESP8266 Technical Reference v1.7, appendix 3 "UART Registers". The offsets are the ESP32's and the ESP32-C3's, but this part's fields are narrower, so crates/esp8266/src/uart.rs is no longer crates/esp32/src/uart.rs twice.

Duas FIFOs de 128 bytes. Os bits 0..7 de UART_STATUS são RXFIFO_CNT e os bits 16..23 são TXFIFO_CNT, e o modelo e o runtime leem campos de oito bits ali, como o apêndice 3 os apresenta. O runtime chegou a ler dez, o que dava os mesmos números porque os bits acima de cada campo são reservados e leem 0; o cabeçalho agora corresponde ao manual, como no ESP32, onde os bits acima não são reservados. UART_CONF0 bit 17 RXFIFO_RST e bit 18 TXFIFO_RST. UART_CONF1 bits 0..6 RXFIFO_FULL_THRHD e bits 8..14 TXFIFO_EMPTY_THRHD, ambos 96 no reset. Os bits 0..19 de UART_CLKDIV são o divisor, que divide o clock APB de 80 MHz e reseta para 694 (o 0x2B6 do apêndice), o que dá 115 274 baud.

Três desses estavam errados aqui antes dessa verificação, e nenhum mudou uma imagem compilada: os dois bits de reset de FIFO estavam trocados (o Serial.begin do runtime define e limpa os dois juntos, então o valor escrito era o mesmo); CONF1 tinha os campos de nove bits do ESP32-C3 em 0 e 9 (o runtime nunca escreve CONF1); e o ritmo de transmissão lia só doze bits do divisor, então Serial.begin(9600), cujo divisor é 8333, enviava bytes cerca de 59 vezes rápido demais. O ritmo agora usa os vinte bits.

Os bytes saem da FIFO de transmissão na taxa de baud, não instantaneamente, pelo motivo que a seção 3.3 de docs/esp32.md dá. crates/esp8266/tests/runtime.rs mede o intervalo entre dois bytes do exemplo serial contra os 86.8 us que um byte leva a 115200.

A UART1 não é modelada. Num ESP8266 real o TX da UART1 é o GPIO 2, que também é o LED do módulo, e é por isso que Serial1 e o LED azul não podem ser obtidos ao mesmo tempo.

3.5 The TOUT converter (0x6000_0D00): the one block that is not the chip's

Leia isto antes de acreditar num endereço. Todo outro periférico neste modelo está no seu endereço real com seus offsets reais, então o firmware compilado aqui roda num NodeMCU real. O ADC é a exceção, e não é uma pequena. A Espressif nunca publicou os registradores SAR do ESP8266: system_adc_read() vive dentro do blob binário do SDK, o core do Arduino o chama, e não há página de manual para citar. Em vez de inventar um endereço e deixar o leitor assumir que é do chip, este modelo põe três registradores próprios em SAR_BASE:

offset registrador bits
0x00 SAR_CFG bit 0 START inicia uma conversão; o bit 1 é armazenado e não faz nada
0x04 SAR_STATUS bit 31 DONE; bits 0..9 o resultado de dez bits

Não verificado, e não apenas não verificado: inventado. analogRead é a única chamada nesta placa que precisaria mudar para hardware real. Lá é system_adc_read() do SDK. Nada mais precisaria.

O que é modelado é a parte que um circuito pode ver: um canal, dez bits, round(1023 x Vin / 1.0 V), limitado, da tensão no pino do chip. O divisor de 220k/100k do NodeMCU é do componente da placa (seção 1), então a escala cheia do header é cerca de 3.2 V. Um A0 desconectado vagueia, como faz uma entrada flutuante (docs/uno.md, seção 1).

Uma conversão leva 80 us fixos de tempo simulado. O valor real depende do laço de amostragem do SDK e fica mais perto de cem microssegundos; este é o único número deste bloco que é escolha do modelo em vez de medição, e a seção 6 o lista.

3.6 The clock: CCOUNT, and no timer peripheral

FRC1 e FRC2 não são modelados. O ESP8266 tem dois timers de hardware e nenhum deles está aqui. O clock que o runtime desta placa lê é o do próprio core CCOUNT, e seu tick de milissegundo e seu PWM por software ambos vêm de CCOMPARE0. Ambos são registradores do core em todo Xtensa, então nenhum endereço de periférico presumido sustenta millis().

The cost is written down rather than hidden. CCOUNT is thirty-two bits at 80 MHz, so it wraps every 53.7 seconds. The sixty-four-bit count the runtime hands out is kept by sampling CCOUNT and adding the difference, which is exact as long as no more than one wrap happens between two samples. Every millis(), micros() and delay() samples it, and the scheduler never lets the next interrupt be more than 2^30 cycles (13.4 seconds) away. So only a sketch that turns interrupts off for a minute and asks the time for nothing in that minute can lose a wrap. Section 6 says so again.

crates/esp8266/tests/runtime.rs mede millis() contra o próprio clock do kernel ao longo de cinco segundos.

3.7 PWM, que é por software neste componente

O ESP8266 não tem nenhum hardware de PWM: nada de LEDC. O core Arduino ESP8266 gera suas formas de onda num handler de timer, e este runtime também: oito slots, cada um com um pino, um tempo em alta e um tempo em baixa em ciclos de CPU, e o deadline compartilhado de CCOMPARE0 armado para a borda que vier a seguir.

Essa é a diferença honesta entre as duas placas Xtensa aqui. Num ESP32 um LED com fade não custa nada ao core, porque o LEDC é hardware e o simulador acorda a placa só para a borda. Num ESP8266 o core acorda duas vezes por período para mover o próprio pino, que é exatamente o custo do componente real, e isso aparece na contagem de instruções. A página da placa também diz isso.

Oito pinos ao mesmo tempo. A frequência padrão é 1 kHz e analogWriteFreq aceita de 40 Hz a 60 kHz. crates/esp8266/tests/runtime.rs mantém o período do exemplo fade em 1 kHz dentro de um jitter de handler, em vez dos cinco microssegundos do ESP32, porque um jitter de handler é o que PWM por software tem.

A faixa é 1023, não 255; veja a seção 7.

3.8 O que não tem registradores aqui

SPI e HSPI, I2C (este componente não tem um periférico I2C de verdade; o core do Arduino emula por software), I2S, a UART1 de hardware, o contador e a memória do RTC, deep sleep, os eFuses e todo o MAC e PHY do WiFi.

3.9 Caixa de correio de rede do Mokxi (0x6FFF_E000)

Este bloco não é do ESP8266. Todo o resto deste documento é do componente ou está marcado como invenção própria deste modelo com a razão ao lado (seção 3.5, o conversor TOUT). Este não é nenhum dos dois: é a rede simulada do Mokxi de crates/net, no topo de uma janela de periféricos cujos blocos reais estão todos nos primeiros poucos kilobytes, para que uma imagem que o use falhe no silício em vez de ler o registrador de outro periférico. Essa falha é a resposta honesta, porque a coisa por trás deste bloco não existe no chip. Nada aqui foi tirado do SDK da Espressif nem do core do Arduino para ESP8266.

Este é o componente com um rádio e nenhuma documentação para ele. O WiFi do ESP8266 é um blob binário no SDK; a Espressif nunca publicou seus registradores, e este modelo não tenta adivinhá-los. O que ele oferece no lugar é uma caixa de correio que é honestamente do Mokxi, num endereço que honestamente não é do componente.

O bloco não gera nenhuma interrupção. Os números de interrupção que este modelo usa são aqueles com que todos os cabeçalhos de ESP8266 concordam, e não existe um número assim para um periférico que o chip não tem, então a caixa de correio não recebe nenhum. O firmware faz polling, e um núcleo estacionado em waiti ainda é acordado quando a rede tem algo a dizer.

Aqui não há rádio, nem 802.11, nem internet real. Nada no modelo transmite, escaneia, associa, criptografa ou abre um socket: uma senha é comparada como string, um nome que não está sob .mokxi não resolve, e as três origens que a rede serve são funções em crates/net/src/http.rs. A caixa de correio tem a forma da costura real em vez de uma ficção sobre um MAC: num ESP32 real o hardware de WiFi é um blob binário fechado com uma interface de comandos, e o WiFi.h do Arduino acaba do outro lado de um destes. docs/wifi.md é o contrato do que está por trás dele; esta seção é apenas os registradores.

Um registrador de comando, um registrador de status, um anel de 4096 bytes em cada sentido e um bit de interrupção. Escrever em NET_CMD_REG executa o comando; um comando que leva tempo simulado levanta BUSY e o limpa, com DONE em NET_INT_RAW_REG, quando termina.

offset nome bits
0x00 NET_ID_REG lê 0x494B4F4D, e nada mais o faz. Um sketch que quer saber se está no Mokxi lê isto; no silício o acesso falha
0x04 NET_CMD_REG escreva um código de comando (tabela abaixo); a escrita o executa
0x08 NET_ARG_REG uma palavra de argumento, lida de volta: a porta para LISTEN, o status para REPLY
0x0C NET_STATUS_REG bit 0 BUSY, bit 1 ERR, bit 2 RX_READY, bit 3 LINK, bit 4 SERVE, bits 8..11 STATE
0x10 NET_RESULT_REG o que o último comando respondeu
0x14 NET_INT_RAW_REG bit 0 DONE, bit 1 EVENT
0x18 NET_INT_ENA_REG os mesmos dois bits
0x1C NET_INT_CLR_REG escreva 1 para limpar, os mesmos dois bits
0x20 NET_TX_LEN_REG bytes preparados no anel de saída
0x24 NET_TX_DATA_REG escrita: empurra um byte (bits 0..7) para o anel de saída
0x28 NET_RX_LEN_REG bytes aguardando no anel de entrada
0x2C NET_RX_DATA_REG leitura: retira um byte do anel de entrada, 0 quando está vazio
0x30 NET_RING_LEN_REG capacidade de cada anel em bytes, para o firmware não precisar fixar 4096
0x40 NET_BT_CMD_REG Bluetooth: escreva um código de comando Bluetooth (docs/bluetooth.md); a escrita o executa
0x44 NET_BT_ARG_REG Bluetooth: uma palavra de argumento, lida de volta; um evento deixa seu número aqui
0x48 NET_BT_RESULT_REG Bluetooth: o que o último comando Bluetooth respondeu
0x4C NET_BT_STATUS_REG bit 0 CLASSIC_ON, bit 1 CLASSIC_LINK, bit 2 EVENT, bit 3 BLE_ADV, bit 4 BLE_LINK, bit 5 BT_ERR, bit 8 HAS_CLASSIC, bit 9 HAS_BLE
0x50 NET_BT_TX_LEN_REG Bluetooth: bytes preparados no seu próprio anel de saída
0x54 NET_BT_TX_DATA_REG Bluetooth: escrita: empurra um byte para esse anel
0x58 NET_BT_RX_LEN_REG Bluetooth: bytes aguardando no seu próprio anel de entrada
0x5C NET_BT_RX_DATA_REG Bluetooth: leitura: retira um byte, 0 quando está vazio

Os oito registradores NET_BT_ leem 0 e ignoram escritas nesta placa: o ESP8266 não tem Bluetooth (docs/bluetooth.md).

STATE é onde está a estação: 0 ociosa, 1 iniciando, 2 conectando, 3 conectada, 4 falhou, 5 rede inexistente. NET_CMD_STATUS transforma a mesma coisa no código wl_status_t do Arduino que um sketch lê de WiFi.status().

NET_CMD_REG nome o que faz
0 NOP nada
1 RESET desconecta, zera ambos os anéis, descarta qualquer requisição
2 CONNECT o anel de saída contém ssid\0password; levanta BUSY por um a três segundos
3 DISCONNECT descarta a associação e o endereço
4 STATUS NET_RESULT_REG = o código wl_status_t
5 IP NET_RESULT_REG = o endereço obtido, primeiro octeto no byte menos significativo
6 RSSI NET_RESULT_REG = o sinal em dBm, com sinal estendido
7 SSID o anel de entrada recebe o nome do ponto de acesso
8 MAC o anel de entrada recebe os seis bytes de MAC da placa
9 REQUEST o anel de saída contém method\0url\0headers\0body; levanta BUSY
10 POLL NET_RESULT_REG = 0 em andamento, depois o status HTTP, ou um erro negativo com ERR ativo; o corpo chega no anel de entrada
11 LISTEN escuta na porta em NET_ARG_REG
12 ACCEPT NET_RESULT_REG = 1 e o anel de entrada contém method\0path\0query\0body, ou 0 quando nada está aguardando
13 REPLY responde à requisição aceita com o status em NET_ARG_REG; o anel de saída contém content-type\0body
14 STOP para de escutar
15 WL_GPIO_SET controla os próprios GPIOs do componente sem fio a partir de NET_ARG_REG. Não nesta placa: o rádio deste componente não tem esse pino, então ele define ERR e não controla nada. É o caminho que o LED embutido de um Pico W percorre (docs/picow.md seção 3.8)
16 WL_GPIO_GET lê de volta, e o mesmo ERR aqui
17 BLYNK uma operação no servidor Blynk simulado, a operação em NET_ARG_REG e seus campos no anel de saída; respondida de imediato em NET_RESULT_REG, com ERR ativo, sem passar pela rede (docs/wifi.md, "Blynk")
20 SOFTAP o soft AP (crates/net/src/softap.rs, docs/wifi.md), a operação em NET_ARG_REG: 1 o levanta (o anel de saída ssid\0password\0 e o byte de canal; NET_RESULT_REG 1, ou 0 com ERR para um nome vazio ou uma senha de um a sete caracteres), 2 o derruba, 3 o configura (endereço, gateway e máscara de rede, quatro bytes cada), 4 seu endereço (0 enquanto estiver derrubado), 5 as estações conectadas, 6 as entradas, saídas e o bit de ativo que o runtime transforma em eventos, 7 e 8 um servidor DNS de portal cativo iniciando (o nome, um byte zero, o endereço) e parando, 9 seu nome no anel de entrada, 10 o endereço do telefone, 11 o Host da requisição sendo servida no anel de entrada. A única estação é o telefone do painel Web

Os códigos negativos de POLL: -1 o nome não resolve, -2 a estação não está associada, -3 https:// e o TLS não são simulados, -4 um corpo maior que o anel, -5 uma URL que esta rede não consegue interpretar, -6 já há uma requisição em andamento. firmware/include/HTTPClient.h os transforma nos códigos no formato Arduino que um sketch compara, e docs/wifi.md lista o mapeamento.

Temporização, toda ela própria deste modelo e toda declarada em docs/wifi.md: uma associação leva entre um e três segundos, decidida a partir do SSID para que uma aula leve o mesmo tempo nas duas vezes; uma senha errada vira WL_CONNECT_FAILED após cinco segundos; uma requisição a uma origem simulada volta 60 ms depois; uma requisição ao próprio servidor do sketch que o sketch nunca responde é fechada pela rede com um 504 após dez segundos.

3.10 Resets e os watchdogs (0x6000_0700, 0x6000_0900)

A Espressif não documenta estes registradores: o SDK e a ROM os acionam por meio de código fechado. Os nomes e offsets aqui são os que esp8266_peri.h e as funções rtc_get_reset_reason() e software_reset() da ROM usam, na medida em que são conhecidos, e o modelo os toma como acreditados e não verificados. O watchdog de hardware: o bit 0 de WDTCTL o ativa, escrever 0x73 em WDTFEED (0x14) o alimenta, e 2^23 µs (cerca de 8,4 s) sem alimentação resetam o chip. RTC: o bit 31 de 0x00 é o reset de software do sistema, 0x14 bits 3:0 a causa do reset da ROM (1 energização, 2 reset de software, 4 o watchdog), e 0x30..0x3C quatro registradores de armazenamento que sobrevivem a todo reset menos uma energização.

The runtime (firmware/esp8266/src/time.c) is the SDK's: the software watchdog counts the hardware one's 1.6 s first stage, feeding it when the sketch has yielded (loop() returned, delay(), yield(), ESP.wdtFeed()) and, on the second tick in a row that finds it has not (3.2 to 4.8 s after it last yielded), prints the Arduino core's "Soft WDT reset" postmortem (exception 4, the epc, the stack dump between the cut lines) and resets. ESP.wdtDisable() stops only the software watchdog, as on the board, which leaves the hardware one; ESP.getResetReason() and getResetInfo() say which it was.

4. O núcleo: qual ABI, e como uma interrupção chega

crates/xtensa-core é o mesmo interpretador que o ESP32 usa, na configuração LX106. Nada nele é derivado do QEMU, do SDK da Espressif, do core do Arduino para ESP8266 ou de qualquer outro emulador; xtensa-lx106-elf-as foi usado como instrumento de bancada e crates/xtensa-core/tests/encoding.rs guarda as codificações que voltaram.

A ABI call0, e não havia escolha. O LX106 tem dezesseis registradores de endereço e nenhuma janela de registradores, então xtensa-lx106-elf-gcc emite call0, ret e um addi sp, sp, -16 explícito. Não há ENTRY, não há RETW, não há ROTW, não há spilling e não há handlers de estouro ou subfluxo de janela para escrever. crt0.S aqui é bem mais curto que o do ESP32 por essa única razão, e sua tabela de vetores tem seis slots a menos. Os vetores de janela em VECBASE + 0x000 a +0x140 não podem ser alcançados num componente sem a opção windowed, então guardam um salto para o relator de falhas em vez do que quer que esteja na memória.

A outra consequência é que o handler de interrupção desta placa pode salvar registradores na pilha interrompida, o que o do ESP32 não pode: sem janela não há um quadro mais antigo ancorado no ponteiro de pilha desta janela.

O que a configuração LX106 não tem, e cada diferença foi testada no assembler em vez de assumida: divisão de hardware, a multiplicação alta de 32 bits, MIN/MAX, SEXT, CLAMPS, o loop sem overhead e as cargas atômicas. MUL16 e MULL estão presentes. Um programa compilado para o ESP32, portanto, falha neste núcleo em vez de se comportar mal silenciosamente, e é por isso que as strings program das duas placas diferem.

Vetores. VECBASE é um registrador especial; os dois que importam aqui são KernelException em +0x300 e UserException em +0x340. Every level-1 interrupt takes the user exception vector with EXCCAUSE 4, então crt0.S as manda todas para um só lugar, e o runtime descobre qual foi a origem.

Interrupts. INTENABLE masks and PS.INTLEVEL gates, and only level 1 is modeled. Every interrupt the ESP8266 brings out is level 1 except the NMI, which is not modeled, so the level-1 mask here is all ones. That is believed rather than verified.

Não há matriz de interrupção neste componente: cada origem tem um número de interrupção fixo da CPU, e é por isso que attachInterrupt aqui são duas escritas em vez das três do ESP32.

fonte interrupção de CPU
GPIO 4
UART0 5
CCOMPARE0 6

Acreditado, não verificado. 4 é o que todo cabeçalho de ESP8266 chama de ETS_GPIO_INUM e 5 é ETS_UART_INUM; não são números citados de um manual. O 6 de CCOMPARE0 é o da ISA Xtensa.

Ponto flutuante. O LX106 não tem FPU, então não há nada para deixar de fora aqui: toda codificação de ponto flutuante levanta EXCCAUSE 32, coprocessador desativado, e o runtime é soft float, que é o que um sketch de ESP8266 real também recebe.

As regras de CCOMPARE da seção 4 de docs/esp32.md (a comparação é "atingido ou ultrapassado", e um prazo que já está no passado não é armado) valem aqui, e esta placa foi a que encontrou a segunda delas.

5. Modelo de tempo, probe, poke e o canal do host

A CPU roda a 80 MHz, uma instrução por ciclo, então uma instrução dura exatamente 12,5 ns e uma fatia de 800 instruções dura exatamente 10 us. Diferente da do ESP32, este barramento multiplica em vez de dividir: a instrução k termina em slice_start + 12,5 ns * k.

O ESP8266 pode ser clockado a 160 MHz. Este modelo está sempre a 80, que é onde o componente liga e onde o core do Arduino o deixa; não há árvore de clock aqui com a qual mudar isso.

Dentro de uma fatia a contagem de instruções é o relógio: uma leitura de CCOUNT, um byte de UART e uma mudança de pino acontecem todas na instrução que as causou. Um núcleo estacionado em WAITI não custa nada e é acordado no próximo prazo de CCOMPARE0 (o tique de milissegundo, um delay acordando ou a próxima borda de PWM por software) ou por uma mudança de pino ou um byte do host.

probe é uma máscara de bits:

bit significado
1 rodando
2 parado em waiti
4 o LED do módulo no GPIO 2 está aceso
8 o LED da placa de expansão no GPIO 16 está aceso

0 means no program, held in reset, or crashed. Both LEDs are active low, so each bit is set when its pad is low.

poke: 1 mantém o FLASH pressionado (GPIO 0 em nível baixo), 0 o solta; 2 mantém RST, 3 solta.

O canal do host. host_write coloca bytes no FIFO de recepção da UART0; host_read retira os bytes que saíram do seu FIFO de transmissão. Isso é o Serial em um sketch e o monitor serial na interface. Os bytes são UTF-8 do ponto de vista da interface e opacos para o modelo. O soquete micro-USB de um NodeMCU vai para um conversor CP2102 ou CH340 nesta porta; o conversor não é modelado, e a rotina de auto-reset por DTR/RTS também não.

Travamento. 1000 traps consecutivos sem progresso e o núcleo é declarado travado e parado, com o local onde morreu registrado.

6. Do que este modelo tem certeza, e do que não tem

O mais realista que este componente fica

O ESP8266 não tem um manual de referência técnica como o do ESP32 (o da Espressif é curto e omite blocos inteiros), então "verificado" aqui significa que o número é aquele que todo cabeçalho de ESP8266, script de linker e descrição de registradores aberta usa há uma década e é o que a listagem oficial de registradores dá. Nesse padrão:

UART0_BASE 0x6000_0000, GPIO_BASE 0x6000_0300, IOMUX_BASE 0x6000_0800 and RTC_BASE 0x6000_0700. Every register offset inside the GPIO block and inside UART0, and UART0's CONF0 FIFO resets, CONF1 thresholds, CLKDIV width and STATUS counts, each checked against appendix 3 of the ESP8266 Technical Reference v1.7 (section 3.4). The iram1_0_seg at 0x4010_0000 with 32 KB and the dram0_0_seg at 0x3FFE_8000 with 80 KB. The seventeen GPIOs, that 6 to 11 are the flash, and that 16 is the RTC's pin and is in no GPIO register. The D0 to D8 silkscreen table. The module's LED on GPIO 2 and the carrier board's on GPIO 16, both active low. The 220k/100k divider on A0. That there is no PWM hardware, no input-enable bit and no pull-down on GPIO 0 to 15. The Xtensa vector offsets and EXCCAUSE numbers, which are the ISA's.

Acreditado, não verificado

  • A tabela de ordem de pads do IO_MUX (seção 3.3).
  • Os cinco registradores de RTC por trás do GPIO16 (seção 3.2).
  • Os números de interrupção da CPU: GPIO 4, UART0 5 (seção 4). São ETS_GPIO_INUM e ETS_UART_INUM, não números fixos.
  • The level-1 interrupt mask, taken to be every interrupt the part brings out (section 4).

Todos estão em um só lugar que o firmware lê, firmware/esp8266/include/esp8266.h, então uma imagem levada ao silício real tem uma lista curta de #defines para conferir. crates/esp8266/tests/contract.rs mantém esse cabeçalho e crates/esp8266/src/map.rs nos mesmos números; isso não torna nenhum dos dois correto.

Inventado, e nomeado como inventado

  • Os três registradores SAR em 0x6000_0D00 (seção 3.5). SAR_CFG, SAR_STATUS e seus bits são deste modelo, porque os do chip não são públicos. analogRead é a única chamada nesta placa que precisaria mudar para um NodeMCU real.

Modelado, mas não com os números do componente

  • Uma conversão leva exatamente 80 us. O valor real depende do laço de amostragem do SDK e fica mais perto de cem.
  • O ADC é uma linha reta de 0 a 1.0 V no pino do chip, e o divisor é exatamente 100/320.
  • O clock é sempre 80 MHz. Sem 160 MHz, e nada com que trocar.
  • RST e EN são apenas um pull-up de 10 k; o capacitor de reset na energização não é modelado.
  • Não há boot ROM. POWER_ON aqui dura 1 us; um ESP8266 real passa bem mais tempo no seu loader de ROM e imprime a mensagem de boot a 74880 baud que esta placa nunca imprime.
  • micros64() pode perder um estouro se as interrupções ficarem bloqueadas por mais de 53,7 segundos e nada perguntar a hora nessa janela (seção 3.6).
  • O PWM por software treme na medida de um handler, porque é software (seção 3.7). O componente real faz o mesmo.
  • Todos os pads ligam iguais: GPIO comum, sem pull.

Ausente de propósito

  • WiFi, em todas as formas. Sem rádio, sem PHY, sem MAC, sem pilha, sem ESP8266WiFi.h, nem mesmo um stub que falhe com educação. Num componente cuja razão de existir é o WiFi, essa é a maior ausência, e a página da placa diz isso primeiro em vez de por último.
  • Flash and the cache that maps it. Code and constants are read from a fixed, read-only window (section 2): no cache to miss, no SPI flash device, no 32-bit-only access rule for it, and no SPIFFS, LittleFS or OTA.
  • FRC1 e FRC2, os dois timers de hardware (seção 3.6). Os watchdogs são da seção 3.10.
  • Deep sleep e o RTC, seu contador e sua memória, e o despertar do GPIO16 para RST.
  • SPI, HSPI, I2S e a UART1 de hardware (seção 3.8).
  • Os eFuses e o ID do chip.
  • Todo nível de interrupção acima de um, e a NMI.

É por isso que binários do SDK do fabricante e do core do Arduino não rodam aqui, e firmware compilado para este documento roda.

Uma imagem de ESP32 também não roda aqui. A string program do catálogo é elf32 xtensa lx106 esp8266 contra a elf32 xtensa lx6 esp32 do DevKit, e essa é uma diferença real: o LX106 não tem janela de registradores, então a primeira entry de uma imagem com janela é uma instrução ilegal em vez de uma resposta sutilmente errada.

7. Runtime do firmware (firmware/esp8266/)

Um runtime no formato Arduino: setup() e loop(), pinMode, digitalWrite, digitalRead, shiftOut, analogRead, analogWrite com seus controles de faixa e frequência, millis, micros, micros64, delay, delayMicroseconds, attachInterrupt, Serial, map, random. Sem core do Arduino, sem SDK da Espressif, sem libc.

Os construtores estáticos saem de .ctors aqui, não de .init_array. O GCC 8.4 da Espressif é configurado sem --enable-initfini-array e não tem -fuse-init-array, então o construtor de um objeto global vai parar em .ctors onde todas as outras toolchains deste repositório emitem .init_array. link.ld coleta os dois no único intervalo que crt0.S percorre. Sem isso, um sketch com um objeto global (WebServer server(80) em wifilamp) compilaria, rodaria e encontraria seus membros zerados. Os dois são percorridos numa única passada e .ctors não é invertido, porque a ordem em que os construtores rodam entre unidades de tradução é indefinida em C++ e um sketch não deve depender disso.

LED_BUILTIN é 2: o LED do módulo, ativo em nível baixo. FLASH_BUTTON é 0. D0 a D8, RX e TX são definidos como a tabela da seção 1, e A0 é 17, um pseudo-pino: não é um GPIO, e analogRead de qualquer outro pino retorna 0 em vez de um número que esta placa não poderia ter produzido.

analogWrite aceita de 0 a 1023, não de 0 a 255. Isso é o que o core do Arduino para ESP8266 PWMRANGE faz, e copiá-lo foi a escolha entre surpreender você no navegador e surpreender você na bancada. analogWriteRange(255) faz um sketch de Uno funcionar, e analogWriteResolution(8) é a mesma coisa dita à moda do ESP32. É PWM por software (seção 3.7): oito pinos ao mesmo tempo, 1 kHz por padrão, de 40 Hz a 60 kHz.

analogRead tem dez bits e analogReadResolution desloca o que ele retorna em vez de mudar o conversor, como o do core do Arduino para ESP32 faz.

millis() and micros() come from CCOUNT extended to sixty-four bits by the tick handler (section 3.6). micros() wraps every 71.6 minutes and millis() every 49.7 days, like Arduino; micros64() does not wrap. delay() parks the core on CCOMPARE0 rather than spinning. One comparator has two customers (the next delay deadline and the next PWM edge), so the scheduler works out which comes first, arms that, and the handler services whatever was due and schedules again.

attachInterrupt são duas escritas em vez de três, porque não há matriz de interrupções (seção 4). O GPIO16 não consegue levantar uma.

Os exemplos enviados são compilados pelo GCC da Espressif, e o sketch do usuário pelo clang-v3 no navegador, pelos motivos que a seção 7 de docs/esp32.md dá. deploy/fetch-xtensa.sh coloca xtensa-lx106-elf-gcc 8.4.0 em tools/xtensa/, que é gitignored: o GCC é GPL e nada do que ele compila aqui faz link contra a libgcc, então nenhum código GPL chega a um ELF enviado.

Três arquivos deste runtime são do ESP32, compilados de novo para esta placa em vez de copiados: a formatação de números, os auxiliares de matemática e o floor freestanding, além de Print e main. Os próprios desta placa são crt0.S, o header de registradores, o script de linker e os drivers de GPIO, ADC, PWM, tempo, UART e interrupções. support32.c está aqui porque o LX106 não tem divisão em hardware: os auxiliares de divisão e módulo de 32 bits que o compilador chama são nossos, para que nada faça link contra a libgcc.

Linked against firmware/esp8266/link.ld: the vectors and startup code in the 32 KB of IRAM, code and constants in the flash window, .data, .bss and the stack in the 80 KB of DRAM. A NodeMCU has 4 MB of flash and an example should be a small part of it, so the build refuses an image over its budget; the real ceiling the linker script enforces is the 1,044,464 bytes of the IDE's default sketch partition. The upload build (firmware/esp8266/link-hw.ld) is loaded into RAM by the ROM and keeps the 32 KB.

Cinco exemplos, cada um com um sketch que a interface mostra: blink (o LED do módulo no D4 e um ligado no D1, sempre opostos porque um é ativo baixo), button (uma chave para o terra no D2 com o pull-up do próprio pad), serial (um tick por segundo, e um eco), fade (um LED no D1 no PWM por software, de 0 a 1023) e knob (o potenciômetro no A0, dez bits, indo direto para o duty do PWM porque as duas faixas têm o mesmo valor).

crates/esp8266/tests/runtime.rs inicializa esses cinco ELFs e mede: o meio período do blink, o 1 kHz do PWM por software dentro de um jitter da ordem de um handler, o millis() contra o relógio do kernel e o espaçamento de bytes da UART0 a 115200 baud. Cada teste se autoignora quando as imagens não estão compiladas.