Referencia

Contrato de la placa BBC micro:bit V2 (Fase 9)

La nRF52833 sobre nuestro núcleo Cortex-M4, con GPIO, GPIOTE, los TIMER, RTC0, UARTE0 y la matriz de LEDs.

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 La BBC micro:bit V2 y la página de la placa.

El quinto microcontrolador, y el segundo en el motor Cortex-M4. Un componente del kernel (microbit en crates/parts) envuelve un modelo del SoC nRF52833 (crates/nrf52833) construido sobre el núcleo Cortex-M (crates/cortexm-core, Profile::V7M). El firmware es un ELF Thumb que se comunica con los periféricos de abajo en sus direcciones reales de nRF52833, así que un programa compilado para Mokxi corre en una micro:bit V2 real.

El tipo de catálogo es microbit (BBC micro:bit V2, nRF52833). Todo lo que dice docs/esp32c3.md sobre cómo se comporta un componente de placa (slices, canal del host, reset, línea de crash) aplica aquí salvo que este archivo diga lo contrario, y todo lo que dice docs/stm32f411.md sobre el núcleo Cortex-M4 aplica a este núcleo.

Running MakeCode or MicroPython .hex images is not a goal: both are built against the vendor stack and expect the soft device, the radio and a file system, none of which are modeled. What is modeled is the set of peripherals pinMode, digitalWrite, digitalRead, millis, micros, delay, Serial, attachInterrupt, showLeds, showText and tone need, at their real addresses, so the same source built against firmware/microbit/ produces an image that also runs on the hardware.

Esta placa se diferencia de las demás de aquí en dos cosas, y ambas vienen del hardware. No tiene pines para insertar en una protoboard: el conector de borde es un peine dorado a lo largo del borde inferior, y solo sus cinco anillos grandes aceptan un cocodrilo o un jumper, así que la placa va junto a la protoboard y no dentro de ella. Y no tiene un solo LED que parpadear: la pantalla son 25 LEDs en diez pads, barridos por el firmware, así que una imagen es algo que el simulador tiene que reconstruir a partir del barrido y no leer de un registro.

1. Pines de la placa (orden del catálogo)

Cinco pines, los cinco anillos grandes del conector de borde, de izquierda a derecha con la placa sostenida con su conector USB hacia arriba:

0, 1, 2, 3V, GND.

Las tiras pequeñas entre los anillos son GPIO reales del componente y accesibles desde el firmware, pero no son pines del catálogo: nada en una protoboard alcanza una tira de 0.06 pulgadas de ancho, y un pin que el usuario no puede cablear es un pin que miente sobre qué es el circuito.

Eléctrica:

  • 3V entrega 3.3 V con R_SUPPLY y GND entrega 0 V con R_SUPPLY, siempre, porque la placa se alimenta por USB. La placa es una fuente para el resto del circuito.
  • 0, 1 and 2 are inout GPIO on P0.02, P0.03 and P0.04. Output (DIR bit set): push-pull at 3.3 V or 0 V through R_STRONG. Input: high-Z, plus a 13 k pull-up to 3.3 V when PIN_CNF[n].PULL is Pullup, a 13 k pull-down when it is Pulldown. 13 k is the figure in the product specification. Input reads the net voltage against 1.65 V, half the supply; Unknown reads 0, and a floating input reads noise, as on the Uno (docs/uno.md section 1). PIN_CNF[n].INPUT set to Disconnect makes the input read 0.
  • Un pad al que ningún anillo lleva (los pines I2C 19 y 20, P0.26 y P1.00, la matriz, las tiras de borde de repuesto) no tiene nada encima más que el chip, así que lee lo que el chip ponga ahí: 1 con su propia pull-up o su propia salida alta, 0 en caso contrario. Por eso Wire, que suelta sus líneas sobre las pull-ups, no encuentra ningún dispositivo en ninguna dirección, como en la placa real.

2. Mapa de memoria (direcciones reales de nRF52833)

región dirección tamaño notas
flash 0x0000_0000 512 KB the part boots from zero; VTOR points here out of reset
RAM, bus de código 0x0080_0000 128 KB los mismos bytes que abajo, a través del bus de código
RAM, bus de datos 0x2000_0000 128 KB .data, .bss y la pila
FICR 0x1000_0000 4 KB información de fábrica, solo lectura
UICR 0x1000_1000 4 KB borrado, nunca programado aquí
periféricos APB 0x4000_0000 48 x 4 KB periférico con id en 0x4000_0000 + id * 0x1000, que genera la IRQ id
GPIO P0 0x5000_0000 P0.00 a P0.31
GPIO P1 0x5000_0300 P1.00 a P1.09, en los mismos offsets más 0x300
SCS 0xE000_E000 SysTick, NVIC y el SCB, de cortexm-core

La pila crece hacia abajo desde la parte alta de la RAM. firmware/microbit/link.ld falla el enlazado si los datos estáticos dejan menos de 4 KB.

3. Registros de periféricos (offsets reales, posiciones de bit reales)

Cada offset y posición de bit aquí es de la especificación de producto de la nRF52833. Los periféricos de Nordic comparten una forma: tareas en 0x000, eventos en 0x100, SHORTS en 0x200, INTEN / INTENSET / INTENCLR en 0x300, y los registros de configuración desde 0x500. Escribir 1 en un registro de tarea lo dispara; un registro de evento se lee como 1 hasta que el firmware le escribe 0.

Un periférico que el modelo no implementa no aparece en el mapa en absoluto, así que un sketch que intente usar la radio recibe una falla de bus y se detiene con una línea en el monitor serie en lugar de seguir ejecutándose en silencio. Dentro de un periférico que sí está implementado, un registro que este modelo no utiliza lee 0 y se cuenta.

3.1 CLOCK y POWER (0x4000_0000, IRQ 0)

offset registro
0x000 TASKS_HFCLKSTART
0x004 TASKS_HFCLKSTOP
0x008 TASKS_LFCLKSTART
0x00C TASKS_LFCLKSTOP
0x100 EVENTS_HFCLKSTARTED
0x104 EVENTS_LFCLKSTARTED
0x304 / 0x308 INTENSET / INTENCLR
0x408 / 0x40C HFCLKRUN / HFCLKSTAT
0x414 / 0x418 LFCLKRUN / LFCLKSTAT
0x518 LFCLKSRC
0x400 POWER.RESETREAS
0x500 POWER.SYSTEMOFF
0x51C / 0x520 POWER.GPREGRET / GPREGRET2

HFCLKSTAT y LFCLKSTAT llevan STATE en el bit 16 y la fuente en el bit 0. El HFXO se modela como si ya estuviera funcionando, así que una tarea de inicio se completa en el mismo segmento de tiempo en que se escribió y el evento de iniciado se genera de inmediato.

3.2 GPIO (0x5000_0000 y 0x5000_0300)

offset registro
0x504 OUT
0x508 / 0x50C OUTSET / OUTCLR
0x510 IN
0x514 DIR
0x518 / 0x51C DIRSET / DIRCLR
0x520 LATCH
0x524 DETECTMODE
0x700 + 4n PIN_CNF[n]

Campos de PIN_CNF[n]: DIR bit 0, INPUT bit 1 (1 desconecta el búfer), PULL bits 3:2 (0 deshabilitado, 1 pull-down, 3 pull-up), DRIVE bits 10:8 y SENSE bits 17:16. Valor de reinicio 0x0000_0002: entrada, búfer desconectado, sin pull. El campo de fuerza de salida se decodifica y se conserva, pero el modelo tiene una sola impedancia de salida, así que H0H1 y S0S1 manejan igual; una terminal configurada como D0S1 o S0D1 es de drenaje abierto en la mitad desconectada y esa mitad está en alta impedancia.

3.3 GPIOTE (0x4000_6000, IRQ 6)

offset registro
0x000 + 4n TASKS_OUT[n]
0x030 + 4n TASKS_SET[n]
0x060 + 4n TASKS_CLR[n]
0x100 + 4n EVENTS_IN[n]
0x17C EVENTS_PORT
0x300 / 0x304 / 0x308 INTEN / INTENSET / INTENCLR
0x510 + 4n CONFIG[n]

Ocho canales. CONFIG[n]: MODE bits 1:0 (0 deshabilitado, 1 evento, 3 tarea), PSEL bits 12:8, PORT bit 13, POLARITY bits 17:16 (1 de bajo a alto, 2 de alto a bajo, 3 alternación) y OUTINIT bit 20. El bit 31 de INTEN es el evento PORT, que es lo que alimenta PIN_CNF[n].SENSE. attachInterrupt en el runtime usa canales de evento; el evento PORT está ahí para el firmware que quiere despertar con un grupo de pines a la vez.

3.4 TIMER0, TIMER1, TIMER2 (0x4000_8000, 0x4000_9000, 0x4000_A000; IRQ 8, 9, 10)

offset registro
0x000 / 0x004 TASKS_START / TASKS_STOP
0x008 / 0x00C TASKS_COUNT / TASKS_CLEAR
0x010 TASKS_SHUTDOWN
0x040 + 4n TASKS_CAPTURE[n]
0x140 + 4n EVENTS_COMPARE[n]
0x200 SHORTS
0x304 / 0x308 INTENSET / INTENCLR
0x504 MODE
0x508 BITMODE
0x510 PRESCALER
0x540 + 4n CC[n]

El modo temporizador cuenta PCLK16M dividido entre 2^PRESCALER; el prescaler de reinicio es 4, es decir 1 MHz. El modo contador cuenta TASKS_COUNT en su lugar. BITMODE es 16, 8, 24 o 32 bits (0, 1, 2, 3). El bit n de SHORTS es COMPARE[n]_CLEAR y el bit 8 + n es COMPARE[n]_STOP; el bit 16 + n de INTEN es COMPARE[n]. Los tres temporizadores tienen cuatro canales de comparación.

3.5 RTC0 (0x4000_B000, IRQ 11)

offset registro
0x000 / 0x004 / 0x008 TASKS_START / TASKS_STOP / TASKS_CLEAR
0x00C TASKS_TRIGOVRFLW
0x100 / 0x104 EVENTS_TICK / EVENTS_OVRFLW
0x140 + 4n EVENTS_COMPARE[n]
0x304 / 0x308 INTENSET / INTENCLR
0x340 / 0x344 / 0x348 EVTEN / EVTENSET / EVTENCLR
0x504 COUNTER
0x508 PRESCALER
0x540 + 4n CC[n]

El contador es de 24 bits y funciona desde LFCLK a 32,768 Hz a través de un prescaler de 12 bits, con tres canales de comparación. INTEN y EVTEN: TICK bit 0, OVRFLW bit 1, COMPARE[n] bit 16 + n. PRESCALER solo puede escribirse mientras el RTC esté detenido, igual que en el componente real.

3.6 UARTE0 (0x4000_2000, IRQ 2)

offset registro
0x000 / 0x004 TASKS_STARTRX / TASKS_STOPRX
0x008 / 0x00C TASKS_STARTTX / TASKS_STOPTX
0x02C TASKS_FLUSHRX
0x108 EVENTS_RXDRDY
0x110 EVENTS_ENDRX
0x11C EVENTS_TXDRDY
0x120 EVENTS_ENDTX
0x124 EVENTS_ERROR
0x144 / 0x14C / 0x150 EVENTS_RXTO / EVENTS_RXSTARTED / EVENTS_TXSTARTED
0x200 SHORTS
0x300 / 0x304 / 0x308 INTEN / INTENSET / INTENCLR
0x500 ENABLE (4 el UART heredado, 8 el UARTE)
0x508 .. 0x514 PSEL.RTS, PSEL.TXD, PSEL.CTS, PSEL.RXD
0x518 / 0x51C RXD / TXD (los registros heredados de un byte)
0x524 BAUDRATE
0x534 / 0x538 / 0x53C RXD.PTR / RXD.MAXCNT / RXD.AMOUNT
0x544 / 0x548 / 0x54C TXD.PTR / TXD.MAXCNT / TXD.AMOUNT
0x56C CONFIG

Se modelan ambas caras del periférico: el UARTE con EasyDMA que lee y escribe búferes en RAM, y los registros heredados de un byte RXD y TXD, que es lo primero que usa un runtime pequeño. BAUDRATE acepta los valores que lista la especificación del producto (0x01D7_E000 es 115,200), y cada byte cuesta en el tiempo simulado lo que costarían diez bits a esa velocidad, así que una línea larga tarda aquí lo mismo que en la placa. Las terminales indicadas por PSEL.TXD y PSEL.RXD siguen siendo GPIO; los bytes van al canal del host (sección 4), exactamente como lo hace docs/esp32c3.md.

3.7 NVMC (0x4001_E000) y FICR (0x1000_0000)

NVMC.READY en 0x400 lee 1 y NVMC.CONFIG en 0x504 acepta los modos de escritura y borrado; un borrado de página limpia 4 KB de la imagen de flash y una escritura de palabra se combina con AND sobre ella, como lo hace la flash. FICR contiene CODEPAGESIZE (0x010, 4096), CODESIZE (0x014, 128 páginas), DEVICEID0/1 (0x060, 0x064) y el bloque INFO desde 0x100: parte 0x52833, la variante, el paquete, 128 KB de RAM y 512 KB de flash.

3.8 El núcleo y las interrupciones

Cortex-M4 (ARMv7-M) a 64 MHz, sin FPU: CPUID lee 0x410F_C241 y toda instrucción VFP o DSP genera UNDEFINSTR, por eso firmware/microbit/build.sh compila con soft float y lo dice en serio. La NVIC implementa los tres bits de prioridad más altos de los ocho, como lo hace la familia nRF52. SysTick no tiene un reloj de referencia separado, así que SYST_CALIB lee 0xC000_0000.

Los números de interrupción son los ID de periféricos: POWER_CLOCK 0, UARTE0 2, GPIOTE 6, TIMER0 8, TIMER1 9, TIMER2 10, RTC0 11.

4. Canal del host

host_write le da a la placa los bytes escritos en el monitor serie; llegan por la ruta de recepción de UARTE0 y generan EVENTS_RXDRDY. host_read toma los bytes que el firmware ha transmitido. La cadena de formato en el catálogo es utf-8 bytes on UARTE0. En una placa real estos pads (P0.06 TX, P1.08 RX) van al chip de interfaz y salen por USB, así que el monitor serie sustituye al puerto serie USB y no a un segundo UART.

El formato de programa es elf32 arm nrf52833. load acepta un ELF Thumb para el mapa de memoria de la sección 2 y repite toda la secuencia de encendido.

5. Modelo de tiempo, la sonda y el poke

El componente ejecuta el SoC en porciones de 10 microsegundos, como lo hace el componente de STM32F411: 640 ciclos a 64 MHz, exactamente. Cada porción devuelve los cambios de pads que hizo con el desplazamiento dentro de la porción en que ocurrió cada uno, y el componente los convierte en llamadas a drive_after en sus propios desplazamientos, así que un pin que cambió en el ciclo 12 de una porción se mueve 187.5 nanosegundos dentro de ella y no al final. Un núcleo detenido en WFI no cuesta nada hasta lo que esté esperando, o hasta que el circuito o el host lo muevan; on_pin_change y on_poke lo despiertan un nanosegundo después y no en el mismo ciclo delta, así que un cambio de pin nunca puede iniciar un bucle que se realimente.

La matriz. Veinticinco LEDs en cinco pads de fila (P0.21, P0.22, P0.15, P0.24, P0.19) y cinco pads de columna (P0.28, P0.11, P0.31, P1.05, P0.30). Un LED se enciende mientras su fila maneja alto y su columna maneja bajo, que es lo que hace el escaneo del runtime, una fila a la vez. Cada LED se recuerda durante 40 milisegundos después de encenderse por última vez, así que un escaneo que muestra una fila por milisegundo se lee como la imagen estable que ve un ojo, y una pantalla que se limpia se apaga antes del siguiente parpadeo. Los diez pads de la matriz no salen a un anillo, así que nunca manejan una red.

Los botones. A en P0.14 y B en P0.23, detrás de las pull-ups de 10 k de la propia placa, así que un botón presionado lleva el pad a tierra. Llegan a través de poke, porque el lienzo no tiene noción de una región de un componente: 1 es A presionado, 2 es B presionado, 3 es ambos, 0 es ninguno.

El altavoz. En P0.00. El componente mide los flancos del pad como lo hace el componente piezo y considera que suena mientras sigan llegando entre 20 Hz y 20 kHz, quedándose en silencio 60 milisegundos después del último.

La sonda es un f32, y la placa tiene más que decir de lo que un entero en un float puede llevar con exactitud. Así que la sonda es una palabra de 32 bits en el patrón de bits del float, dispuesta de modo que siempre sea un número normal y nunca un NaN:

bit significado
0..24 la matriz de LEDs, en orden de lectura: de izquierda a derecha, de arriba abajo
25 en ejecución
26 botón A presionado
27 botón B presionado
28 actividad serie en los últimos 20 ms
29 always set: the tag that says this is a packed word
30 always clear, so the float is never a NaN
31 el altavoz sonando

Sin programa, o después de un fallo, la sonda es simplemente 0. El visual lee los bits de vuelta del mismo float (web/src/parts/microbit.ts, probeWord).

6. Lo que no está modelado

  • La radio. Nada de 2.4 GHz: sin Bluetooth, sin mensajes de micro:bit a micro:bit, y sin pretender lo contrario.
  • Los sensores. El acelerómetro y la brújula (un LSM303 por I2C en la V2 real), el micrófono y el logotipo táctil. Los pads existen; no hay nada detrás de ellos.
  • SAADC, PWM, PPI, I2S, SPIM, TWIM y el sensor de temperatura. Sus direcciones no están mapeadas, así que tocar una es una falta y no un cero silencioso. tone() es una onda cuadrada conmutada desde la interrupción de comparación de TIMER1; analogWrite y analogRead no tienen ningún periférico detrás.
  • El soft device, el chip de interfaz DAPLink y el sistema de archivos. Un .hex de MakeCode o MicroPython no funcionará aquí.
  • RTC1 y RTC2, TIMER3 y TIMER4. Solo se modelan RTC0 y TIMER0 a TIMER2.
  • La V1. Esa es una nRF51822, un chip distinto.

7. Runtime del firmware (firmware/microbit/)

Un runtime autónomo de C y C++ con una API con forma de Arduino, compilado con clang y ld.lld para thumbv7em-none-eabi con soft float. Sin newlib, sin CMSIS, sin el SDK de Nordic, sin libgcc y sin compiler-rt.

./firmware/microbit/build.sh          # every example into web/public/firmware/microbit/

Un sketch nombra un pin como lo hace la placa: 0 a 20 para el conector lateral, más BUTTON_A, BUTTON_B, SPEAKER, MIC, LOGO y los diez nombres LED_ROW* y LED_COL* para la matriz. firmware/microbit/include/pins.h contiene el mapa de esos números a los pads del nRF52833, y es el del esquema de la micro:bit V2.

Además del conjunto habitual de Arduino, el runtime ofrece la pantalla: showLeds(picture) toma cinco filas de cinco, # para un LED encendido y . para uno apagado; showChar(c) mantiene un carácter de la fuente de 5x5; showText(s) desplaza una cadena de derecha a izquierda y regresa cuando la última letra se ha ido; plot, unplot y point alcanzan un solo LED. El escaneo corre desde la interrupción de SysTick, una fila a la vez, así que un sketch que llama a showLeds y luego duerme conserva su imagen. buttonA() y buttonB() leen los dos botones de la placa, y tone(SPEAKER, hz, ms) es una onda cuadrada en P0.00.

Los cuatro ejemplos incluidos son blink (un corazón latiendo en la matriz), button (A y B cambian la cara, un botón en el anillo 1 enciende un LED en el anillo 0), serial (dice qué hacen los botones y repite lo que escribes) y scroll (una palabra cruzando la matriz). build.sh escribe web/public/firmware/microbit/index.json, que contiene el código fuente de cada sketch para el editor.

8. De qué está seguro este modelo, y de qué no

Tres grupos, con el mismo orden que usa la sección 7 de docs/esp32c6.md. Existe porque un modelo de placa que adivina silenciosamente una dirección es peor que uno que dice que no lo sabía.

Tomado de la especificación del producto, y comprobado con firmware real. Cada dirección base, desplazamiento de registro y posición de bit en las secciones 2 y 3 proviene de la nRF52833 Product Specification: CLOCK y POWER en 0x4000_0000, UARTE0 en 0x4000_2000, GPIOTE en 0x4000_6000, TIMER0 a TIMER2 en 0x4000_8000/9000/A000, RTC0 en 0x4000_B000, NVMC en 0x4001_E000, FICR en 0x1000_0000 y GPIO P0/P1 en 0x5000_0000/0300, con sus números de IRQ. crates/nrf52833/tests/firmware.rs carga ELFs reales y maneja GPIO, GPIOTE, los temporizadores, RTC0 y UARTE0 a través de ellos. Los números propios de la micro:bit V2 (la matriz de 5x5 como cinco filas en P0.21/22/15/24/19 y cinco columnas, los botones A y B en P0.14 y P0.23, el altavoz en P0.00 y los tres anillos grandes del conector lateral) provienen del esquemático de la placa.

Modelado, pero sin ajustarse a los números de la especificación. Comportamientos en lugar de direcciones:

  • El reloj es de 64 MHz y el árbol de relojes es un stub. Las tareas HFCLKSTART y LFCLKSTART de CLOCK activan sus eventos de inmediato y el núcleo corre a 64 MHz sin importar lo que se pida; no hay tiempo de arranque de cristal, ni calibración de RC, ni dominio de reloj de bajo consumo.
  • El slice tiene dos velocidades, y la primera escritura tras un periodo de calma llega temprano. El núcleo corre en lotes grandes hasta que una escritura cae en un registro de GPIO, GPIOTE, TIMER o UARTE, y entonces avanza una instrucción a la vez durante un rato, la misma forma que describe la sección 7 de docs/stm32f411.md.
  • La matriz de LED es una sonda, no un barrido que puedas observar. El modelo reporta los veinticinco píxeles como una máscara de bits; el multiplexado fila por fila que una micro:bit real ejecuta sí ocurre en las escrituras de registros (y crates/nrf52833/tests/firmware.rs comprueba que solo una fila esté encendida a la vez), pero la imagen que se entrega al lienzo muestra los veinticinco a la vez, sin brillo por píxel y sin persistencia.
  • El altavoz es una onda cuadrada que el runtime cronometra por sí mismo, reportada como una frecuencia entre 20 Hz y 20 kHz con un mantenimiento de 40 ms y 60 ms de silencio al detenerse, no una forma de onda impulsada; no hay volumen ni un periférico PWM detrás.
  • Las almohadillas son tres estados y un umbral. Push-pull a 3.3 V, alta impedancia, o una resistencia interna de pull de 13 kΩ (el valor típico de la especificación), leídas contra la mitad del voltaje de alimentación, sin histéresis, sin ajuste de fuerza de manejo, sin tiempo de subida y sin límite de corriente. Solo los anillos 0, 1, 2, 3V y GND son pines aquí; el resto del conector de borde no lo es.
  • La placa es una fuente de alimentación ideal a 3.3 V; nada se cae por bajo voltaje, y ni el conector de batería ni la alimentación por USB se modelan. El arranque dura un microsegundo.

Deliberately absent, as section 6 lists: the radio, the accelerometer, compass, microphone and touch logo, SAADC, PWM, PPI, I2S, SPIM, TWIM, PDM, NFC, USB, the temperature sensor, the watchdog, RTC1 and RTC2, TIMER3 and TIMER4, the FPU, flash programming, the soft device, the DAPLink interface chip and the file system. Their addresses are unmapped, so touching one is a fault rather than a silent zero, which means analogRead and analogWrite have no peripheral behind them, and a MakeCode or MicroPython .hex will not run here.