TypeScript on a microcontroller, from your desk.

From your desk to the board, one command at a time.

No ESP-IDF to set up, no serial monitor to open, no board to start with. zinc fetches its pinned tools (esptool, SWC, ESP-IDF when a plugin brings C) the first time it needs them, and the same program runs at every step.

1. Write it on the computer

   zinc run examples/esp32-widgets

   A window on your computer. LVGL gets a memory pool the size of the board's heap, so a screen too big for the board fails here too, with the same message.

2. Check it for the board

   zinc check examples/esp32-widgets --target esp32 --engine mquickjs

   Compiles the program for MicroQuickJS and runs it for 300 frames on the computer, inside the board's heap and with LVGL's C. A feature the board does not have fails here, at your file and line, before anything is sent.

3. Try it without a board

   zinc run examples/esp32-widgets --target esp32 --emulator --live

   esp32sim runs the real firmware, the same bytes the board gets, in a window. The mouse is the finger, and the UART prints in your terminal. zinc builds the emulator from its sources the first time.

4. Send it to the board

   zinc run examples/esp32-widgets --target esp32

   Over USB. zinc writes the firmware the program needs once, then only the program: a few dozen KB of bytecode, in about a second. The console comes back to your terminal, and an error points at your TypeScript line, not at the bundle.

5. Or over Wi-Fi

   zinc run examples/esp32-wifi --target esp32 --host zinc-e3d8.local

   Once a board running the network firmware is on your network: a 20 KB program in under a second, a 1 MB firmware in 5.8 s. A firmware that does not start is rolled back by the board.

6. Ship it

   zinc export examples/breakout --target esp32 --engine mquickjs

   dist/breakout-esp32 gets firmware.bin, the program's image (app.img) and a flash.sh, for people who do not have Zinc.

$ zinc run examples/esp32-widgets --target esp32 --emulator --run-ms 4500
  bundle     examples/esp32-widgets/src/main.ts for mquickjs
  plugin     lvgl: cached native library
  plugin     device: cached native library
  bytecode   89612 bytes, checked for 300 frames under mquickjs 1.1 s
mqjs: firmware zinc-mquickjs 839f67c0
mqjs: free heap 231576, largest block 118784
mqjs: the program was relocated into the flash in 38 ms (once per program and firmware)
mqjs: bytecode of 89612 bytes loaded in 42016 us, free heap 133220
esp32-widgets ready
  emulator   4500 ms of an ESP32 in esp32sim              6.0 s

MicroQuickJS: JavaScript in 96 KB of heap.

A plugin brings its own C: its native code is written once on Zinc's native ABI (native/x.abi.c). The same file is the plugin's library on the computer and part of the board's firmware, which zinc builds with ESP-IDF and caches. It can even be C++ on Arduino's core, with an Arduino sketch's setup() and loop() running beside the TypeScript program. Native code on the ESP32 →

LVGL, driven from TypeScript.

zinc:lvgl brings LVGL 9.6, the embedded UI library, to TypeScript. Widgets, flex layout, scrolling with inertia, themes, animations and drawing all stay in C. The program holds handles (plain integers), sets values and reads events.

import * as lv from 'zinc:lvgl';

lv.start(240, 320, true, 0x3b82f6);  // dark, accent
const page = lv.screen();
lv.flex(page, lv.FLEX_COLUMN, lv.FLEX_START, lv.FLEX_CENTER);

const volume = lv.slider(page, 0, 100, 60);
const play = lv.button(page, 'Play');
lv.on(volume, lv.EVENT_VALUE_CHANGED,
  () => console.log('volume ' + lv.value(volume)));
lv.on(play, lv.EVENT_CLICKED,
  () => lv.setText(lv.buttonLabel(play), 'Pause'));

// slides into place, moved by LVGL in C
lv.animate(play, lv.TRANSLATE_Y, 80, 0, 400, lv.OVERSHOOT);

lv.run((dt: number) => { /* your frame, before LVGL's */ });

The widgets tour, in the emulator

examples/esp32-widgets: six pages under a title bar with the frame rate. Each page is built when it is shown and deleted when it is left. Captured from esp32sim, which runs the board's firmware.

The numbers, and where they come from.

Two kinds of figures. Some were measured on the board. The LVGL ones come from esp32sim: it emulates the chip and counts its time, but not the time the panel's bus takes. A full-screen redraw on the board's 8-bit, 10 MHz bus is 15 ms of transfer, so those frame rates are what LVGL can render, not yet what the board shows.

Measured with the ESP32-2432S022

LVGL in esp32sim, per frame

Heap free after the program loads: 133.5 KB. With a page shown: Home 79.9 KB, Music 82.5 KB, Input 71.8 KB, Lottie 35.3 KB. The firmware with LVGL and ThorVG: 1.06 MB of its 1.5 MB slot.

What made it fast

Every number is logged with its date and method in docs/reports/zinc-next-perf.md.