Building from Source

This page covers building firmware from the Mikro.js monorepo. You need this if you are contributing to the core runtime or working with native (C/C++) drivers.

For building custom firmware from npm packages without cloning the monorepo, see Custom Firmware.

One-time ESP-IDF setup

Install ESP-IDFEspressif IoT Development Framework >= 6.1 using EIMESP-IDF Installation Manager (ESP-IDFEspressif IoT Development Framework Installation Manager):

eim install -i v6.1 -t all -n true

The commands below use mikro idf, which runs ESP-IDFEspressif IoT Development Framework's idf.py through eim run when ESP-IDFEspressif IoT Development Framework is not active in the shell, so no manual activation is needed.

Building the firmware for development

esp32/ builds the core runtime without any board-specific configuration:

cd esp32
pn mikro idf set-target esp32c6    # or esp32, esp32s3
pn mikro idf build flash monitor

Replace esp32c6 with your chip. Press Ctrl+] to exit the serial monitor.

The build reports its name as @mikrojs/firmware-dev, so the CLICommand-Line Interface treats it as custom firmware: it doesn't replace it with the generic image on its own, and mikro flash --force puts the generic image back.

Building firmware for a board

A board package builds its firmware from its boards.config.ts, not in esp32/: the config holds each board's chip, settings and native modules. In the package:

pn mikro fw build

mikro fw build builds every board in the config and writes each image into the folder that the board's firmware export points at. An app that depends on the package flashes that image with mikro flash.

The generic images ship with mikro, which is a board package too, built the same way: pn mikro fw build --board esp32c6-generic in packages/mikro builds the C6's images, the full one and its leaner ones, into packages/mikro/dist-fw/. Add --image full to build only the full image, or --parallel 4 to build them at once. While you work on the firmware, pn fw esp32c6-generic at the root of the repository builds just the full image for one chip and flashes it (mikro fw build --flash --image full --board esp32c6-generic); without the board name it asks which.

Running on-device tests

From the esp32/ directory:

pnpm test

This builds the test firmware, flashes it, and runs the Unity test suite over serial. Tests are organized by category: [runtime], [modules], [timers], [fs], [gpio].

If tests fail to build, try a full clean first:

cd esp32/test
pn mikro idf -B build fullclean

Running host-side tests

The core runtime can also be built and tested on your development machine without any ESP32 hardware:

pnpm run build:lib
pnpm run test:lib

sdkconfig notes

sdkconfig.defaults is only read when sdkconfig does not exist. If you change sdkconfig.defaults (or switch boards), you must delete sdkconfig and re-run pn mikro idf set-target <chip> for the changes to take effect. The target chip is stored in sdkconfig, so it must be re-set each time.