Referencia

Contrato de la placa ESP8266 NodeMCU (Boards Wave C)

El LX106 con el ABI call0, el GPIO16 que no es un GPIO, PWM por software, y el único bloque cuyos registros son inventados.

Esta es la referencia de ingeniería del modelo: qué implementa, registro por registro, para quienes escriben firmware sobre él. Para usar la placa en el editor, empieza por El ESP8266 NodeMCU y la página de la placa.

La NodeMCU V1.0 es la placa de treinta pines construida alrededor de un módulo ESP-12E: un Xtensa LX106 a 80 MHz, el componente más pequeño y antiguo de esta lista y aun así el que fue la primera placa WiFi de mucha gente. Un componente del kernel (esp8266 en crates/parts) envuelve un modelo del SoC ESP8266 (crates/esp8266) sobre el mismo intérprete Xtensa que el ESP32 (crates/xtensa-core), con una configuración distinta. Este documento es el contrato, y prevalece sobre cualquier comentario en el código.

El tipo de catálogo es esp8266. La cadena de program del catálogo es elf32 xtensa lx106 esp8266.

Lee primero la sección 6 si vas a llevar una compilación de aquí a silicio real. La mayor parte de esta placa está en su dirección real; el ADC no, y eso se dice en la sección 3.5, en la página de la placa y en el artículo de ayuda, además de aquí, porque Espressif nunca ha publicado la interfaz de registros del 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. Pines de la placa (orden del catálogo)

Vista superior, con el conector micro-USB abajo y el módulo ESP-12E con su antena PCB arriba. La placa mide 48.3 x 25.6 mm y sus dos headers de 15 pines están a 22.86 mm (0.9 pulgadas) de distancia, así que cabalga una protoboard dejando libre una fila de orificios a cada lado. El dibujo la representa a ese tamaño.

Esa es la V1.0 Amica, que es la placa que modela este componente. La V3 "LoLin" que la gente también llama NodeMCU es más ancha, con una pulgada completa entre sus filas de pines: en una protoboard no deja ni una fila libre, y de ahí viene la fama de esta placa de necesitar dos protoboards.

Fila de pines izquierda, de arriba abajo (15 agujeros): A0, RSV, RSVb, SD3, SD2, SD1, CMD, SD0, CLK, GND, 3V3, EN, RST, GNDb, VIN.

Fila de pines derecha, de arriba abajo (15 agujeros): D0, D1, D2, D3, D4, 3V3b, GNDc, D5, D6, D7, D8, RX, TX, GNDd, 3V3c.

30 pines. Los nombres duplicados llevan una letra porque los nombres de pines del catálogo son únicos.

Los nombres de la serigrafía no son números de GPIO

Esta es la única cosa con la que esta placa confunde a la gente, así que está escrito aquí, en el artículo de ayuda y en la página de la placa:

. El entorno de ejecución define 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) es D4, no D2así que un sketch puede usar cualquiera de los dos, y D0 a D8 así que un sketch puede usar cualquiera de los dos, y crates/parts/src/parts/esp8266.rs tiene una prueba que cubre toda la tabla.

Ocho pines del header que no están conectados a nada

SD0, SD1, SD2, SD3, CMD y CLK son los GPIO 7, 8, 9, 10, 11 y 6: los seis cables del chip de flash, a través de los cuales se ejecuta el programa. Sí están en el header de un NodeMCU real, así que están en este componente; aquí ni manejan señal ni se leen. Los dos pines RSV son igual. Un sketch que funcionó en un simulador porque usaba SD1 detendría el flash en un escritorio, y eso es justamente lo que este componente existe para prevenir.

A0 está detrás del divisor de la placa

El pin TOUT del chip convierte 0 a 1.0 V. Un NodeMCU pone un divisor de 220k/100k delante, así que el A0 del header es 0 a aproximadamente 3.2 V y un potenciómetro conectado al riel de 3.3 V cubre casi todo el rango. El divisor pertenece a la placa, no al chip, así que vive en el componente de la placa: el pin carga su red con 320 k y al SoC le llega el tercio del voltaje que alcanza el pin del chip. A0 no es un GPIO y no se puede escribir.

Los dos LEDs, y ambos son activos en bajo

  • GPIO 2, que es D4, tiene el LED azul del módulo ESP-12. También es el TX del UART1 en un componente real, por eso un sketch que usa Serial1 lo pierde.
  • GPIO 16, que es D0, tiene el LED de la placa portadora del NodeMCU.

Ambos están cableados de 3V3 al pin, así que LOW los enciende. Confundir este sentido es el error en el que esta placa hace caer con más facilidad, así que probe reporta cada lámpara como encendida cuando su pad está en bajo (sección 5).

GPIO 16 no es un pin común y corriente

D0 es el pin del RTC. No está en ninguno de los registros del bloque de GPIO (tiene sus propios registros de salida, habilitación y entrada en el bloque del RTC, sección 3.2); tiene una resistencia pull-down cuando todos los demás pads del componente tienen pull-up, y no puede generar una interrupción. En un NodeMCU es el pin que conectas a RST para despertar del deep-sleep, y es D0, así que no es una rareza que un sketch pueda 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.

El orden exacto de la serigrafía de las dos filas de pines es la interpretación de este modelo del pinout del NodeMCU V1.0 (Amica). Los números de GPIO son los del chip y son de los que depende el firmware; su posición en el header es de la que depende un diagrama. Una V3 LoLin mueve dos de ellos además de ser más ancha, y un circuito dibujado aquí necesitaría recablearse para una.

2. Mapa de memoria

IRAM (instrucciones) 32 KB en 0x4010_0000 a 0x4010_7FFF
IROM (flash code and constants) 0x4020_0000, read-only, up to 1,044,464 bytes
DRAM (datos) 80 KB en 0x3FFE_8000 a 0x3FFF_BFFF
tope de la pila 0x3FFF_C000
UART0 0x6000_0000, sección 3.4
GPIO 0x6000_0300, sección 3.1
RTC (GPIO16) 0x6000_0700, sección 3.2
IO_MUX 0x6000_0800, sección 3.3
SAR (TOUT) 0x6000_0D00, sección 3.5, propio de este modelo

Cada bloque de periféricos ocupa 0x100 aquí, porque en este componente de verdad están tan cerca unos de otros.

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. Registros de periféricos

Solo está implementado el subconjunto de abajo. Cualquier otra cosa dentro de un bloque mapeado se lee como 0 y cuenta como acceso errante; cualquier cosa fuera de todo bloque es una falta de acceso.

3.1 GPIO (0x6000_0300)

Diecisiete pines, pero solo dieciséis están aquí: GPIO 0 a 15 son corrientes y GPIO 16 está en el bloque RTC en su lugar (sección 3.2).

offset registro
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 en 0..16

Verificado en el sentido que este componente permite: la base y cada desplazamiento aquí son los que todo header, script de enlazado y descripción abierta de registros del ESP8266 ha usado durante una década, y son los que el ESP8266 Technical Reference Manual de Espressif da para el bloque GPIO. No son un número que este modelo haya elegido.

El bit 2 PAD_DRIVER de GPIO_PINn pone el pad en drenaje abierto; los bits 7..9 INT_TYPE eligen qué dispara la interrupción del pin: 0 apagado, 1 flanco de subida, 2 flanco de bajada, 3 cualquier flanco, 4 nivel bajo, 5 nivel alto. No hay matriz de GPIO en este componente: un pad es GPIO o es de un periférico, y eso se elige en IO_MUX.

No hay ningún bit de habilitación de interrupción por pin aparte de INT_TYPE, ni segunda mitad de ningún registro, porque dieciséis bits es todo lo que el bloque necesita.

3.2 Los registros RTC detrás de GPIO16 (0x6000_0700)

offset registro bits
0x68 RTC_GPIO_OUT el bit 0 es el nivel de salida de GPIO16
0x74 RTC_GPIO_ENABLE el bit 0 es el controlador de salida de GPIO16
0x8C RTC_GPIO_IN_DATA el bit 0 es lo que ve el pad de GPIO16
0x90 RTC_GPIO_CONF bit 0 clear puts the pad under RTC_GPIO_ENABLE
0xA0 PAD_XPD_DCDC_CONF los bits 0..1 seleccionan GPIO16 en lugar del pin DCDC

Se cree más de lo que se ha verificado. Estos cinco son los registros que toda secuencia de GPIO16 de ESP8266 ha usado desde 2015 y los que el pinMode(16, ...) del núcleo de Arduino escribe, pero no son una página citada de un manual. El pull en este pad es un pull-down, a diferencia de todos los demás pads del componente.

Nada más del bloque RTC está modelado: sin contador de RTC, sin memoria de RTC, sin suspensión profunda, sin fuente de despertar.

3.3 IO_MUX (0x6000_0800)

PERIPHS_IO_MUX_CONF_U en 0x00, luego un registro por pad. El bit 7 es el pull-up interno.

No hay ningún bit de habilitación de entrada, ni pull-down interno en GPIO 0 a 15. El búfer de entrada de un ESP8266 siempre está activo, y INPUT_PULLDOWN no existe en este componente; solo GPIO16 tiene un pull-down, y ese está en el bloque RTC. Un sketch que quiera un pull-down necesita una resistencia.

Como en el ESP32, los registros están en orden de pad, no 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

Se cree más de lo que se ha verificado. GPIO16 no tiene ningún registro IO_MUX.

3.4 UART0 (0x6000_0000)

offset registro
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.

Dos FIFOs de 128 bytes. Los bits 0..7 de UART_STATUS son RXFIFO_CNT y los bits 16..23 son TXFIFO_CNT, y el modelo y el entorno de ejecución leen campos de ocho bits ahí, como los da el apéndice 3. El entorno una vez leyó diez, lo que daba los mismos números porque los bits por encima de cada campo están reservados y leen 0; el header ahora coincide con el manual, como en el ESP32, donde los bits de arriba no están reservados. UART_CONF0 bit 17 RXFIFO_RST y bit 18 TXFIFO_RST. UART_CONF1 bits 0..6 RXFIFO_FULL_THRHD y bits 8..14 TXFIFO_EMPTY_THRHD, ambos en 96 al reset. Los bits 0..19 de UART_CLKDIV son el divisor, que divide el reloj APB de 80 MHz y se resetea a 694 (el 0x2B6 del apéndice), que son 115 274 baudios.

Tres de estos estaban mal aquí antes de esa verificación, y ninguno cambió una imagen compilada: los dos bits de reset de FIFO estaban intercambiados (el Serial.begin del entorno fija y limpia ambos juntos, así que el valor escrito era el mismo); CONF1 tenía los campos de nueve bits del ESP32-C3 en 0 y 9 (el entorno nunca escribe CONF1); y el ritmo de transmisión leía solo doce bits del divisor, así que Serial.begin(9600), cuyo divisor es 8333, enviaba bytes unas 59 veces demasiado rápido. El ritmo ahora usa los veinte bits.

Los bytes salen del FIFO de transmisión a la velocidad de baudios, no al instante, por la razón que da la sección 3.3 de docs/esp32.md. crates/esp8266/tests/runtime.rs mide la separación entre dos bytes del ejemplo serial contra los 86.8 us que toma un byte a 115200.

UART1 no está modelado. En un ESP8266 real el TX del UART1 es el GPIO 2, que también es el LED del módulo, y esa es toda la razón por la que no se pueden tener Serial1 y el LED azul a la vez.

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

Lee esto antes de creer una dirección. Todos los demás periféricos de este modelo están en su dirección real con sus offsets reales, así que el firmware compilado aquí corre en un NodeMCU real. El ADC es la excepción, y no es menor. Espressif nunca ha publicado los registros SAR del ESP8266: system_adc_read() vive dentro del blob binario del SDK, el núcleo de Arduino lo llama, y no hay una página de manual que citar. En vez de inventar una dirección y dejar que el lector asuma que es la del chip, este modelo pone tres registros propios en SAR_BASE:

offset registro bits
0x00 SAR_CFG bit 0 START inicia una conversión; el bit 1 se guarda y no hace nada
0x04 SAR_STATUS bit 31 DONE; bits 0..9 el resultado de diez bits

Sin verificar, y no solo sin verificar: inventado. analogRead es la única llamada en esta placa que habría que cambiar para hardware real. Allá es system_adc_read() del SDK. Nada más habría que cambiar.

Lo que sí está modelado es la parte que un circuito puede ver: un canal, diez bits, round(1023 x Vin / 1.0 V), acotado, del voltaje en el pin del chip. El divisor de 220k/100k del NodeMCU es el de la parte de la placa (sección 1), así que la escala completa del header es de unos 3.2 V. Un A0 sin conectar vaga, como lo hace una entrada flotante (docs/uno.md sección 1).

Una conversión toma 80 us fijos de tiempo simulado. La cifra real depende del lazo de muestreo del SDK y está más cerca de cien microsegundos; este es el único número en este bloque que es una elección del modelo y no una medición, y la sección 6 lo lista.

3.6 The clock: CCOUNT, and no timer peripheral

FRC1 y FRC2 no están modelados. El ESP8266 tiene dos temporizadores de hardware y ninguno está aquí. El reloj que lee el entorno de esta placa es el del propio núcleo CCOUNT, y su tick de milisegundos y su PWM por software provienen ambos de CCOMPARE0. Ambos son registros del núcleo en todo Xtensa, así que detrás no hay ninguna dirección de periférico verificada detrás 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 mide millis() contra el reloj del propio kernel durante cinco segundos.

3.7 PWM, que en esta pieza es por software

El ESP8266 no tiene ningún tipo de hardware de PWM: no hay LEDC, nada. El núcleo de Arduino para ESP8266 genera sus formas de onda desde un gestor de temporizador y este runtime hace lo mismo: ocho espacios, cada uno con un pin, un tiempo en alto y un tiempo en bajo en ciclos de CPU, y el plazo compartido de CCOMPARE0 armado para el flanco que llegue después.

Esa es la diferencia honesta entre las dos placas Xtensa que hay aquí. En un ESP32 un LED que se desvanece no le cuesta nada al núcleo, porque LEDC es hardware y el simulador despierta la placa solo para el flanco. En un ESP8266 el núcleo despierta dos veces por periodo para mover el pin él mismo, que es exactamente lo que cuesta la pieza real, y se nota en el conteo de instrucciones. La página de la placa también lo dice.

Ocho pines a la vez. La frecuencia predeterminada es 1 kHz y analogWriteFreq acepta de 40 Hz a 60 kHz. crates/esp8266/tests/runtime.rs mantiene el periodo del ejemplo fade en 1 kHz dentro de un jitter del tamaño de un gestor, en lugar de los cinco microsegundos del ESP32, porque un jitter del tamaño de un gestor es lo que tiene el PWM por software.

El rango es 1023, no 255; véase la sección 7.

3.8 Qué no tiene registros aquí en absoluto

SPI y HSPI, I2C (esta pieza no tiene periférico de I2C en primer lugar; el núcleo de Arduino lo implementa por bit-banging), I2S, el UART1 de hardware, el contador y la memoria del RTC, el sueño profundo, los eFuses, y todo el MAC y PHY de WiFi.

3.9 Buzón de red de Mokxi (0x6FFF_E000)

Este bloque no es del ESP8266. Todo lo demás en este documento es de la pieza o está marcado como invención propia de este modelo con la razón al lado (sección 3.5, el convertidor TOUT). Esto no es ni lo uno ni lo otro: es la red simulada de Mokxi de crates/net, en la parte alta de una ventana de periféricos cuyos bloques reales están todos en sus primeros kilobytes, de modo que una imagen que lo use falle en el silicio en lugar de leer el registro de otro periférico. Esa falla es la respuesta honesta, porque la cosa detrás de este bloque no existe en el chip. Nada de aquí se toma del SDK de Espressif ni del núcleo de Arduino para ESP8266.

Esta es la pieza con una radio y sin documentación para ella en absoluto. El WiFi del ESP8266 es un blob binario en el SDK; Espressif nunca ha publicado sus registros, y este modelo no los inventa. Lo que ofrece en su lugar es un buzón que es honestamente de Mokxi, en una dirección que honestamente no es de la pieza.

El bloque no genera ninguna interrupción. Los números de interrupción que usa este modelo son los que todos los headers de ESP8266 aceptan, y no existe un número así para un periférico que el chip no tiene, así que el buzón no recibe ninguno. El firmware hace sondeo, y un núcleo estacionado en waiti igual se despierta cuando la red tiene algo que decir.

Aquí no hay radio, ni 802.11, ni internet real. Nada en el modelo transmite, escanea, asocia, cifra o abre un socket: una contraseña se compara como cadena, un nombre que no esté bajo .mokxi no se resuelve, y los tres orígenes que la red sirve son funciones en crates/net/src/http.rs. El buzón tiene la forma de la costura real en vez de una ficción sobre una MAC: en un ESP32 real el hardware de WiFi es un blob binario cerrado con una interfaz de comandos, y el WiFi.h de Arduino termina al otro lado de uno de estos. docs/wifi.md es el contrato de lo que hay detrás; esta sección son solo los registros.

Un registro de comandos, un registro de estado, un anillo de 4096 bytes en cada sentido y un bit de interrupción. Escribir NET_CMD_REG ejecuta el comando; un comando que tarda tiempo simulado activa BUSY y lo limpia, con DONE en NET_INT_RAW_REG, cuando termina.

offset nombre bits
0x00 NET_ID_REG lee 0x494B4F4D, y nada más lo hace. Un sketch que quiera saber si está en Mokxi lee esto; en silicio el acceso falla
0x04 NET_CMD_REG escribe un código de comando (tabla abajo); la escritura lo ejecuta
0x08 NET_ARG_REG una palabra de argumento, leída de vuelta: el puerto para LISTEN, el estado 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 lo que respondió el último comando
0x14 NET_INT_RAW_REG bit 0 DONE, bit 1 EVENT
0x18 NET_INT_ENA_REG los mismos dos bits
0x1C NET_INT_CLR_REG escribe 1 para limpiar, los mismos dos bits
0x20 NET_TX_LEN_REG bytes preparados en el anillo de salida
0x24 NET_TX_DATA_REG escritura: empuja un byte (bits 0..7) al anillo de salida
0x28 NET_RX_LEN_REG bytes en espera en el anillo de entrada
0x2C NET_RX_DATA_REG lectura: saca un byte del anillo de entrada, 0 cuando está vacío
0x30 NET_RING_LEN_REG capacidad de cada anillo en bytes, para que el firmware no tenga que fijar 4096 a mano
0x40 NET_BT_CMD_REG Bluetooth: escribe un código de comando de Bluetooth (docs/bluetooth.md); la escritura lo ejecuta
0x44 NET_BT_ARG_REG Bluetooth: una palabra de argumento, leída de vuelta; un evento deja aquí su número
0x48 NET_BT_RESULT_REG Bluetooth: lo que respondió el último comando de Bluetooth
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 en su propio anillo de salida
0x54 NET_BT_TX_DATA_REG Bluetooth: escritura: empuja un byte a ese anillo
0x58 NET_BT_RX_LEN_REG Bluetooth: bytes en espera en su propio anillo de entrada
0x5C NET_BT_RX_DATA_REG Bluetooth: lectura: saca un byte, 0 cuando está vacío

Los ocho registros NET_BT_ leen 0 e ignoran las escrituras en esta placa: el ESP8266 no tiene Bluetooth (docs/bluetooth.md).

STATE es dónde está la estación: 0 inactiva, 1 iniciando, 2 conectando, 3 conectada, 4 falló, 5 no existe esa red. NET_CMD_STATUS convierte lo mismo en el código wl_status_t de Arduino que un sketch lee de WiFi.status().

NET_CMD_REG nombre qué hace
0 NOP nada
1 RESET desconecta, descarta ambos anillos, descarta cualquier solicitud
2 CONNECT el anillo de salida contiene ssid\0password; activa BUSY de uno a tres segundos
3 DISCONNECT descarta la asociación y la dirección
4 STATUS NET_RESULT_REG = el código wl_status_t
5 IP NET_RESULT_REG = la dirección asignada, primer octeto en el byte bajo
6 RSSI NET_RESULT_REG = la señal en dBm, con signo extendido
7 SSID el anillo de entrada recibe el nombre del punto de acceso
8 MAC el anillo de entrada recibe los seis bytes MAC de la placa
9 REQUEST el anillo de salida contiene method\0url\0headers\0body; activa BUSY
10 POLL NET_RESULT_REG = 0 mientras está en curso, luego el estado HTTP, o un error negativo con ERR arriba; el cuerpo llega al anillo de entrada
11 LISTEN escucha en el puerto de NET_ARG_REG
12 ACCEPT NET_RESULT_REG = 1 y el anillo de entrada contiene method\0path\0query\0body, o 0 cuando no hay nada en espera
13 REPLY responde la solicitud aceptada con el estado en NET_ARG_REG; el anillo de salida contiene content-type\0body
14 STOP deja de escuchar
15 WL_GPIO_SET maneja los GPIO propios del componente inalámbrico desde NET_ARG_REG. No esta placa: la radio de este componente no tiene tal pin, así que pone ERR y no maneja nada. Es la ruta que sigue el LED integrado de una Pico W (docs/picow.md sección 3.8)
16 WL_GPIO_GET se leen de vuelta, y el mismo ERR aquí
17 BLYNK una operación en el servidor Blynk simulado, la operación en NET_ARG_REG y sus campos en el anillo de salida; se responde de inmediato en NET_RESULT_REG, con ERR arriba sin pasar por la red (docs/wifi.md, "Blynk")
20 SOFTAP el AP por software (crates/net/src/softap.rs, docs/wifi.md), la operación en NET_ARG_REG: 1 lo levanta (el anillo de salida ssid\0password\0 y el byte de canal; NET_RESULT_REG 1, o 0 con ERR por un nombre vacío o una contraseña de uno a siete caracteres), 2 lo baja, 3 lo configura (dirección, puerta de enlace y máscara de red, cuatro bytes cada una), 4 su dirección (0 mientras está inactivo), 5 las estaciones conectadas, 6 las conexiones, desconexiones y el bit de actividad que el entorno de ejecución convierte en eventos, 7 y 8 el servidor DNS del portal cautivo iniciándose (el nombre, un byte cero, la dirección) y deteniéndose, 9 su nombre hacia el anillo de entrada, 10 la dirección del celular, 11 el Host de la petición que se atiende hacia el anillo de entrada. La única estación es el celular del panel Web

Los códigos negativos de POLL: -1 el nombre no se resuelve, -2 la estación no está asociada, -3 https:// y TLS no se simula, -4 un cuerpo más largo que el anillo, -5 una URL que esta red no puede analizar, -6 ya hay una petición en curso. firmware/include/HTTPClient.h los convierte en los códigos con forma de Arduino con los que un sketch se compara, y docs/wifi.md lista la correspondencia.

Tiempos, todos propios de este modelo y todos indicados en docs/wifi.md: una asociación tarda entre uno y tres segundos, decididos a partir del SSID para que una lección tarde lo mismo las dos veces; una contraseña errónea se convierte en WL_CONNECT_FAILED a los cinco segundos; una petición a un origen simulado regresa 60 ms después; una petición al propio servidor del sketch que el sketch nunca responde la cierra la red con un 504 a los diez segundos.

3.10 Reinicios y perros guardianes (0x6000_0700, 0x6000_0900)

Espressif no documenta estos registros: el SDK y la ROM los manejan mediante código cerrado. Los nombres y offsets que aparecen aquí son los que usan esp8266_peri.h y las funciones rtc_get_reset_reason() y software_reset() de la ROM, hasta donde se conocen, y el modelo los toma como creíbles en lugar de verificados. El watchdog de hardware: el bit 0 de WDTCTL lo activa, escribir 0x73 en WDTFEED (0x14) lo alimenta, y 2^23 µs (unos 8.4 s) sin alimentarlo reinician el chip. RTC: el bit 31 de 0x00 es el reinicio de sistema por software, los bits 3:0 de 0x14 la causa de reinicio de la ROM (1 encendido, 2 un reinicio por software, 4 el watchdog), y 0x30..0x3C cuatro registros de almacenamiento que sobreviven a todo reinicio excepto un encendido.

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. El núcleo: qué ABI, y cómo llega una interrupción

crates/xtensa-core es el mismo intérprete que el ESP32 ejecuta, en la configuración LX106. Nada de él proviene de QEMU, del SDK de Espressif, del núcleo de Arduino ESP8266 ni de ningún otro emulador; xtensa-lx106-elf-as se usó como instrumento de banco de trabajo y crates/xtensa-core/tests/encoding.rs conserva las codificaciones que devolvió.

El ABI call0, y no había otra opción. El LX106 tiene dieciséis registros de direcciones y ninguna ventana de registros, así que xtensa-lx106-elf-gcc emite call0, ret y un addi sp, sp, -16 explícito. No hay ENTRY, ni RETW, ni ROTW, ni derrame de registros, ni controladores de desbordamiento o subdesbordamiento de ventana que escribir. crt0.S aquí es mucho más corto que el del ESP32 por esa única razón, y su tabla de vectores tiene seis espacios menos. Los vectores de ventana en VECBASE + 0x000 a +0x140 no se pueden alcanzar en un chip sin la opción de ventanas, así que contienen un salto al reportador de fallos en lugar de lo que sea que haya en memoria.

La otra consecuencia es que el controlador de interrupciones de esta placa sí puede guardar registros en la pila interrumpida, cosa que el del ESP32 no puede: sin ventana no hay un marco más antiguo anclado al puntero de pila de esta ventana.

Lo que la configuración del LX106 no tiene, y cada diferencia se verificó en el ensamblador en lugar de asumirse: división por hardware, la multiplicación alta de 32 bits, MIN/MAX, SEXT, CLAMPS, el bucle sin sobrecosto y las cargas atómicas. MUL16 y MULL sí están presentes. Un programa compilado para el ESP32 por lo tanto falla en este núcleo en lugar de comportarse mal silenciosamente, y por eso las cadenas de program de las dos placas son distintas.

Vectores. VECBASE es un registro especial; los dos que importan aquí son KernelException en +0x300 y UserException en +0x340. Every level-1 interrupt takes the user exception vector with EXCCAUSE 4, así que crt0.S los manda a todos a un mismo lugar y el runtime determina cuál fue la fuente.

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.

Aquí no hay matriz de interrupciones: cada fuente tiene un número de interrupción de CPU fijo, y por eso attachInterrupt aquí son dos escrituras en vez de las tres del ESP32.

fuente interrupción de CPU
GPIO 4
UART0 5
CCOMPARE0 6

Se supone, no se ha verificado. El 4 es lo que todo header del ESP8266 llama ETS_GPIO_INUM y el 5 es ETS_UART_INUM; no son números citados de un manual. El 6 de CCOMPARE0 es del ISA de Xtensa.

Punto flotante. El LX106 no tiene FPU, así que no hay nada que omitir aquí: toda codificación de punto flotante genera EXCCAUSE 32, coprocesador deshabilitado, y el runtime es de coma flotante por software, que es lo que también obtiene un sketch real de ESP8266.

Las reglas de CCOMPARE de la sección 4 de docs/esp32.md (la comparación es "alcanzado o superado", y un plazo ya en el pasado no se arma) se aplican aquí, y esta placa fue la que encontró la segunda de ellas.

5. Modelo de tiempo, sonda, poke y el canal del host

El CPU corre a 80 MHz, una instrucción por ciclo, así que una instrucción dura exactamente 12.5 ns y una porción de 800 instrucciones dura exactamente 10 us. A diferencia del bus del ESP32, este puede multiplicar en vez de dividir: la instrucción k termina en slice_start + 12.5 ns * k.

El ESP8266 puede correr a 160 MHz. Este modelo siempre está a 80, que es la frecuencia con la que arranca el componente y donde el núcleo de Arduino la deja; aquí no hay árbol de reloj para cambiarla.

Dentro de una porción el conteo de instrucciones es el reloj: una lectura de CCOUNT, un byte del UART y un cambio de pin ocurren todos en la instrucción que los causó. Un núcleo detenido en WAITI no cuesta nada y despierta en su siguiente vencimiento de CCOMPARE0 (el tick de milisegundo, un delay despertando, o el siguiente flanco de PWM por software) o por un cambio de pin o un byte del host.

sonda es una máscara de bits:

bit significado
1 en ejecución
2 estacionado en waiti
4 el LED del módulo en GPIO 2 está encendido
8 el LED de la placa portadora en GPIO 16 está encendido

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 mantiene FLASH (GPIO 0 en bajo), 0 lo libera; 2 mantiene RST, 3 lo libera.

El canal del host. host_write pone bytes en el FIFO de recepción del UART0; host_read toma los bytes que han salido de su FIFO de transmisión. Eso es Serial en un sketch y el monitor serie en la interfaz. Los bytes son UTF-8 en lo que a la interfaz respecta y opacos para el modelo. El conector micro USB de una NodeMCU va a un puente CP2102 o CH340 en este puerto; el puente no está modelado, y tampoco lo está la secuencia de auto reset por DTR/RTS.

Colapso. 1000 trampas consecutivas sin progreso y el núcleo se declara colapsado y se detiene, con registro del lugar donde murió.

6. De lo que este modelo está seguro, y de lo que no

Lo más real que llega este componente

El ESP8266 no tiene un manual de referencia técnica como el del ESP32 (el de Espressif es corto y deja bloques enteros fuera), así que "verificado" aquí significa que el número es el que todo header de ESP8266, todo script de enlazado y toda descripción abierta de registros ha usado durante una década, y es lo que da el listado oficial de registros. Con ese estándar:

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.

Se cree, pero no está verificado

  • La tabla de orden de pads del IO_MUX (sección 3.3).
  • Los cinco registros del RTC detrás del GPIO16 (sección 3.2).
  • Los números de interrupción de la CPU: GPIO 4, UART0 5 (sección 4). Son ETS_GPIO_INUM y ETS_UART_INUM, no números literales.
  • The level-1 interrupt mask, taken to be every interrupt the part brings out (section 4).

Todos están en un solo lugar que lee el firmware, firmware/esp8266/include/esp8266.h, así que una imagen que se lleve a silicio real tiene una lista corta de #define que revisar. crates/esp8266/tests/contract.rs obliga a ese header y a crates/esp8266/src/map.rs a coincidir en los mismos números; no hace que ninguno de los dos esté en lo correcto.

Inventados, y nombrados como inventados

  • Los tres registros SAR en 0x6000_0D00 (sección 3.5). SAR_CFG, SAR_STATUS y sus bits son de este modelo, porque los del chip no son públicos. analogRead es la única llamada en esta placa que habría que cambiar para una NodeMCU real.

Modelado, pero no con los números del componente

  • Una conversión tarda exactamente 80 us. La cifra real depende del ciclo de muestreo del SDK y ronda los cien.
  • El ADC es una línea recta de 0 a 1.0 V en el pin del chip, y el divisor es exactamente 100/320.
  • El reloj siempre está a 80 MHz. No hay 160 MHz, ni nada con qué cambiarlo.
  • RST y EN son solo un pull-up de 10 k; el capacitor de reset de encendido no está modelado.
  • No hay ROM de arranque. POWER_ON aquí dura 1 us; un ESP8266 real pasa mucho más tiempo en su cargador de ROM e imprime el mensaje de arranque a 74880 baudios que esta placa nunca imprime.
  • micros64() puede perder un desbordamiento si las interrupciones se retienen más de 53.7 segundos y nada pregunta la hora en esa ventana (sección 3.6).
  • El PWM por software tiembla lo que dura un manejador, porque es software (sección 3.7). Eso también es lo que hace el componente real.
  • Todos los pads encienden igual: GPIO simple, sin pull.

Ausentes a propósito

  • WiFi, en todas sus formas. Sin radio, sin PHY, sin MAC, sin pila, sin ESP8266WiFi.h, ni siquiera un stub que falle con cortesía. En un componente cuya razón de existir es el WiFi, esto es lo más grande que falta, y la página de la placa lo dice primero y no al final.
  • 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 y FRC2, los dos temporizadores de hardware (sección 3.6). Los watchdog son de la sección 3.10.
  • El sueño profundo y el RTC, su contador y su memoria, y el despertar de GPIO16 a RST.
  • SPI, HSPI, I2S y el UART1 de hardware (sección 3.8).
  • Los eFuses y el ID del chip.
  • Todos los niveles de interrupción por encima de uno, y el NMI.

Por eso los binarios del SDK del fabricante y del núcleo de Arduino no corren aquí, y el firmware compilado para este documento sí.

Una imagen de ESP32 tampoco correrá aquí. La cadena program del catálogo es elf32 xtensa lx106 esp8266 contra el elf32 xtensa lx6 esp32 del DevKit, y esa es una diferencia real: el LX106 no tiene ventana de registros, así que la primera entry de una imagen con ventanas es una instrucción ilegal y no una respuesta sutilmente equivocada.

7. Entorno de ejecución del firmware (firmware/esp8266/)

Un entorno de ejecución con forma de Arduino: setup() y loop(), pinMode, digitalWrite, digitalRead, shiftOut, analogRead, analogWrite con sus controles de rango y frecuencia, millis, micros, micros64, delay, delayMicroseconds, attachInterrupt, Serial, map, random. Sin núcleo de Arduino, sin SDK de Espressif, sin libc.

Los constructores estáticos salen de .ctors aquí, no de .init_array. El GCC 8.4 de Espressif está configurado sin --enable-initfini-array y no tiene -fuse-init-array, así que el constructor de un objeto global termina en .ctors donde todas las demás cadenas de herramientas de este repositorio lo emiten en .init_array. link.ld reúne ambos en el único rango crt0.S recorre. Sin eso, un sketch con un objeto global (WebServer server(80) en wifilamp) enlazaría, se ejecutaría y encontraría sus miembros en cero. Los dos se recorren en una sola pasada y .ctors no se invierte, porque el orden en que corren los constructores entre unidades de traducción no está especificado en C++ y un sketch no debe depender de él.

LED_BUILTIN es 2: el LED del módulo, activo en bajo. FLASH_BUTTON es 0. D0 a D8, RX y TX están definidos según la tabla de la sección 1, y A0 es 17, un pseudo-pin: no es un GPIO, y analogRead de cualquier otra cosa devuelve 0 en lugar de un número que esta placa no podría haber producido.

analogWrite acepta de 0 a 1023, no de 0 a 255. Eso es lo que es el núcleo de Arduino para ESP8266: PWMRANGE y copiarlo fue la elección entre sorprenderte en el navegador o sorprenderte en el escritorio. analogWriteRange(255) hace que un sketch de Uno se comporte bien, y analogWriteResolution(8) es lo mismo dicho a la manera del ESP32. Es PWM por software (sección 3.7): ocho pines a la vez, 1 kHz por defecto, de 40 Hz a 60 kHz.

analogRead es de diez bits y analogReadResolution desplaza lo que devuelve en lugar de cambiar el convertidor, igual que el del núcleo de Arduino para ESP32.

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 son dos escrituras en lugar de tres, porque no hay matriz de interrupciones (sección 4). El GPIO16 no puede generar una.

Los ejemplos incluidos se compilan con el GCC de Espressif, y el sketch de un usuario con clang-v3 en el navegador, por las razones que da la sección 7 de docs/esp32.md. deploy/fetch-xtensa.sh coloca xtensa-lx106-elf-gcc 8.4.0 en tools/xtensa/, que está en el gitignore: GCC es GPL y nada de lo que compila aquí se enlaza contra libgcc, así que ningún código GPL llega a un ELF distribuido.

Tres de los archivos de este runtime son del ESP32, compilados de nuevo para esta placa en lugar de copiados: el formateo de números, los auxiliares matemáticos y el floor independiente, más Print y main. Los propios de esta placa son crt0.S, el header de registros, el script del enlazador y los controladores de GPIO, ADC, PWM, tiempo, UART e interrupciones. support32.c está aquí porque el LX106 no tiene división por hardware: los auxiliares de división y módulo de 32 bits que llama el compilador son nuestros, de modo que nada se enlaza contra 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 ejemplos, cada uno con un sketch que la interfaz muestra: blink (el LED del módulo en D4 y uno cableado en D1, siempre opuestos porque uno es activo bajo), button (un interruptor a tierra en D2 con la pull-up propia del pin), serial (un latido por segundo y un eco), fade (un LED en D1 con PWM por software, de 0 a 1023) y knob (el potenciómetro en A0, diez bits, directo al ciclo útil del PWM porque los dos rangos tienen el mismo número).

crates/esp8266/tests/runtime.rs arranca esos cinco ELFs y mide: el medio periodo de blink, el 1 kHz del PWM por software dentro del jitter de un manejador, millis() contra el reloj del kernel y el ritmo de bytes de UART0 a 115200 baudios. Cada prueba se omite a sí misma cuando las imágenes no están compiladas.