velxio/test/autosearch/01_wokwi_research.md

Wokwi Custom Chips — investigación de referencia

Esto NO es código que copiemos. Es una descripción del sistema de Wokwi para entender el dominio del problema antes de diseñar el nuestro propio.

Consultado: 2026-04-27.

Qué es

Wokwi permite que el usuario escriba un chip en C, lo compile a WebAssembly, y lo agregue a su diagrama. El chip simula su comportamiento eléctrico/lógico cuando el sketch del Arduino interactúa con sus pines.

Fuentes:

• https://docs.wokwi.com/chips-api/getting-started
• https://docs.wokwi.com/chips-api/chip-json
• https://docs.wokwi.com/chips-api/i2c
• https://docs.wokwi.com/chips-api/uart
• https://docs.wokwi.com/chips-api/spi
• https://docs.wokwi.com/chips-api/tutorial-7seg
• https://github.com/alextrical/wokwi-24C01-custom-chip (ejemplo MIT real)

Anatomía de un chip Wokwi

Dos archivos:

1. chip.c — incluye wokwi-api.h. Define una función chip_init() que se llama una vez por cada instancia del chip al iniciar el simulador.
2. chip.json — declara nombre, autor, lista de pines, atributos editables, opciones de display.

Ejemplo chip.json (24C01 EEPROM):

{
  "version": 1,
  "name": "24C01",
  "author": "Alextrical",
  "license": "MIT",
  "pins": ["A0","A1","A2","GND","VCC","WP","SCL","SDA"]
}

API observada (resumen)

Pines

• pin_t pin_init(const char* name, pin_mode mode) — registra y devuelve handle.
• uint32_t pin_read(pin_t), void pin_write(pin_t, uint32_t).
• void pin_watch(pin_t, const pin_watch_config_t*) con callback en flanco.
• Modos: INPUT, OUTPUT, OUTPUT_HIGH, INPUT_PULLUP, INPUT_PULLDOWN, ANALOG.
• Edges: RISING, FALLING, BOTH.

I2C (slave)

• i2c_dev_t i2c_init(const i2c_config_t* cfg). Solo desde chip_init().
• Callbacks: connect(ud, addr, isRead)→bool ack, read(ud)→uint8, write(ud, byte)→bool ack, disconnect(ud).
• Bus es 7-bit slave; el chip "responde" a una dirección.

UART

• uart_dev_t uart_init(const uart_config_t* cfg). RX/TX, baud, callbacks rx_data y write_done.
• uart_write(uart, buffer, count) para emitir bytes.

SPI (slave)

• spi_dev_t spi_init(const spi_config_t* cfg). Pines sck/mosi/miso, modo (0..3), callback done.
• spi_start(spi, buffer, count), spi_stop(spi).

Atributos

• attr_t attr_init(const char* name, uint32_t default_val), attr_read(attr).
• Versiones attr_init_float / attr_float_read para reales.

Tiempo

• get_sim_nanos() reloj de la simulación.
• API de timers: timer_init, timer_start, etc. (no la documentamos exhaustivamente acá).

Misc

• printf funciona porque el chip se compila contra wasi-libc y la salida va a la "Chips Console".
• Estado por instancia: el chip hace malloc(sizeof(chip_state_t)) en chip_init().

ABI del WASM

Compilación:

clang --target=wasm32-unknown-wasi -nostartfiles \
      -Wl,--import-memory -Wl,--export-table -Wl,--no-entry \
      -I<sdk> chip.c -o chip.wasm

• --import-memory: el host provee la memoria, el WASM la importa.
• --export-table: la tabla de funciones se exporta para que el host pueda invocar callbacks por índice (los punteros a función en C son índices en la tabla).
• --no-entry: no hay main, solo exports.

El WASM importa todas las funciones de la API (pin_init, i2c_init, etc) y exporta chip_init + memory + __indirect_function_table.

Conclusión para Velxio

Replicamos el modelo (chip = WASM con imports + exports), no el API. Velxio escribe su propio header, sus propios nombres, su propio chip.json schema. El compilador (clang) y runtime (wasi-libc) se mantienen idénticos porque son OSS no-Wokwi.