@mikrojs/firmware 0.21.0 → 0.21.1-next.20260927212749

package/MikroFirmwareConfig.cmake

@@ -0,0 +1,15 @@
+# find_package(MikroFirmware COMPONENTS esp32 NO_DEFAULT_PATH); `mikro idf` sets MikroFirmware_DIR.
+# Without a component the package is only found (esp32/test uses its files itself).
+
+foreach(_mik_family IN LISTS MikroFirmware_FIND_COMPONENTS)
+    if(NOT _mik_family STREQUAL "esp32")
+        set(MikroFirmware_FOUND FALSE)
+        set(MikroFirmware_NOT_FOUND_MESSAGE
+            "@mikrojs/firmware has no component \"${_mik_family}\". It builds for: esp32")
+        return()
+    endif()
+endforeach()
+
+if("esp32" IN_LIST MikroFirmware_FIND_COMPONENTS)
+    include("${CMAKE_CURRENT_LIST_DIR}/project.cmake")
+endif()

package/README.md

@@ -4,18 +4,18 @@ ESP32 firmware package for Mikro.js. Provides the ESP-IDF integration, build sys
 
 ## What's included
 
-- **`project.cmake`** - CMake module that integrates with ESP-IDF. Handles component discovery, SDK config merging, and partition table defaults.
+- **`MikroFirmwareConfig.cmake`** and **`project.cmake`** - the CMake package that integrates with ESP-IDF. Turns the native modules that the project lists into ESP-IDF components, merges SDK config, and applies partition table defaults.
 - **`components/mikrojs/`** - ESP-IDF component that compiles the Mikro.js runtime, QuickJS engine, and platform-specific C modules.
 - **Default configs** - `sdkconfig.defaults` and `partitions.csv` for common setups.
 
 ## Usage
 
-A custom firmware project depends on this package and includes `project.cmake` (resolved via `resolve.js`, see the docs below for the CMakeLists boilerplate):
+A custom firmware project depends on this package and finds it with `find_package(MikroFirmware REQUIRED COMPONENTS esp32 NO_DEFAULT_PATH)`. `mikro idf` resolves the package from the project through its `cmake` export condition and passes its folder to CMake (see the docs below for the CMakeLists boilerplate):
 
 ```
 my-firmware/
-├── package.json          # depends on @mikrojs/firmware
-├── CMakeLists.txt        # resolves and includes project.cmake via resolve.js
+├── package.json          # depends on @mikrojs/firmware and mikro
+├── CMakeLists.txt        # find_package(MikroFirmware ...)
 └── main/                 # optional: omit it and the package's default main
     ├── CMakeLists.txt    # (which calls MIK_Main()) is used automatically
     └── main.cpp
@@ -28,4 +28,4 @@ See the [Custom Firmware](https://mikrojs.dev/develop/custom-firmware) docs for
 - Node.js >= 24
 - ESP-IDF >= 6.1 (installed via [EIM](https://docs.espressif.com/projects/idf-im-ui/en/latest/))
 
-To build, activate ESP-IDF in your shell first: run `eim select` and source the activation script it prints, then use `idf.py` as usual.
+To build, run `pn mikro idf build` in the project. `mikro idf` passes its arguments to `idf.py`, through EIM when ESP-IDF is not active in the shell, and tells CMake where this package is. Plain `idf.py` does not.

package/bin/mikro-fw.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// In the Mikro.js repository, run the TypeScript source, so a firmware build
+// never runs a stale dist/. A published package has only dist/.
+import {existsSync} from 'node:fs'
+
+const src = new URL('../src/cli.ts', import.meta.url)
+await import(existsSync(src) ? src.href : '../dist/cli.js')

package/components/mikrojs/CMakeLists.txt

@@ -1,4 +1,4 @@
-# ── Resolve package paths via Node.js ────────────────────────────────
+# ── Package paths ────────────────────────────────────────────────────
 # MIKROJS_PROJECT_DIR is the directory containing package.json and node_modules.
 # Defaults to CMAKE_SOURCE_DIR which works for both:
 #   - Monorepo: CMAKE_SOURCE_DIR is esp32/ (has package.json with workspace deps)
@@ -7,28 +7,18 @@ if(NOT DEFINED MIKROJS_PROJECT_DIR)
     set(MIKROJS_PROJECT_DIR "${CMAKE_SOURCE_DIR}")
 endif()
 
-# resolve.js lives in the firmware package root, two levels up from this component
-set(_MIK_RESOLVE "${CMAKE_CURRENT_LIST_DIR}/../../resolve.js")
-
-execute_process(
-    COMMAND node ${_MIK_RESOLVE} quickjs
-    OUTPUT_VARIABLE QUICKJS_CMAKE_PATH
-    OUTPUT_STRIP_TRAILING_WHITESPACE
-)
-execute_process(
-    COMMAND node ${_MIK_RESOLVE} native
-    OUTPUT_VARIABLE _NATIVE_JSON
-    OUTPUT_STRIP_TRAILING_WHITESPACE
-)
-# Parse JSON output
-string(JSON MIK_INCLUDE_DIR GET "${_NATIVE_JSON}" "include")
-string(JSON MIK_SRC_DIR GET "${_NATIVE_JSON}" "src")
-string(JSON MIK_RUNTIME_DIR GET "${_NATIVE_JSON}" "runtime")
-string(JSON MIK_SCRIPTS_DIR GET "${_NATIVE_JSON}" "scripts")
-string(JSON MIK_BYTECODE_CMAKE GET "${_NATIVE_JSON}" "bytecodeCmake")
-
-# Include quickjs.cmake for QUICKJS_SOURCES, QUICKJS_INCLUDE_DIR, etc.
-include("${QUICKJS_CMAKE_PATH}")
+# The MIK_* paths come from resolve.cmake, which project.cmake includes.
+# ESP-IDF first runs this file in a separate script-mode pass that only
+# collects REQUIRES, where they are unset. That pass reads no SRCS, so only
+# the include below needs a guard; REQUIRES must never depend on them.
+if(MIK_SRC_DIR)
+    # Include quickjs.cmake for QUICKJS_SOURCES, QUICKJS_INCLUDE_DIR, etc.
+    include("${MIK_QUICKJS_CMAKE}")
+elseif(NOT CMAKE_BUILD_EARLY_EXPANSION)
+    message(FATAL_ERROR
+        "mikrojs: the @mikrojs/native paths are not set. Include @mikrojs/firmware's "
+        "project.cmake in the project's CMakeLists.txt, before project().")
+endif()
 
 # nanocbor lives inside the native package
 set(MIK_NANOCBOR_DIR "${MIK_SRC_DIR}/../deps/nanocbor")
@@ -155,15 +145,15 @@ set_source_files_properties(${QUICKJS_SOURCES} PROPERTIES
     COMPILE_OPTIONS "-Wno-unused-but-set-variable")
 
 # ── Board and version metadata ──────────────────────────────────────
-execute_process(
-    COMMAND node ${_MIK_RESOLVE} version
-    OUTPUT_VARIABLE _MIK_VERSION
-    OUTPUT_STRIP_TRAILING_WHITESPACE
-)
-target_compile_definitions(${COMPONENT_LIB} PRIVATE "MIK_FW_VERSION=\"${_MIK_VERSION}\"")
+file(READ "${CMAKE_CURRENT_LIST_DIR}/../../package.json" _MIK_PACKAGE)
+string(JSON _MIK_VERSION GET "${_MIK_PACKAGE}" version)
+# The version and the build date change between builds, so only the files that
+# read them get them: the rest of the component neither recompiles nor misses ccache.
+set_property(SOURCE "${MIK_SRC_DIR}/mik_repl.cpp" "${MIK_SRC_DIR}/mik_sys.cpp" "mik_main.cpp"
+    "mik_ota_env.cpp" APPEND PROPERTY COMPILE_DEFINITIONS "MIK_FW_VERSION=\"${_MIK_VERSION}\"")
 # Core runtime owns the bare `native:mikro/*` namespace. MIK_PACKAGE_NAME makes
 # MIK_REGISTER_MODULE enforce that every native module here is named
-# "native:mikro/<module>"; driver/board packages set their own package name.
+# "native:mikro/<module>"; a package's native module sets its package name.
 target_compile_definitions(${COMPONENT_LIB} PRIVATE "MIK_PACKAGE_NAME=\"mikro\"")
 # The version is read at configure time, so configure must re-run when the
 # firmware package version changes — otherwise an incremental idf.py build
@@ -171,24 +161,53 @@ target_compile_definitions(${COMPONENT_LIB} PRIVATE "MIK_PACKAGE_NAME=\"mikro\""
 set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS
     "${CMAKE_CURRENT_LIST_DIR}/../../package.json")
 
-# Firmware identity: the consuming project's package.json name, reported in
-# MSG_READY as `fw`. The CLI only auto-flashes its bundled prebuilt over a
-# device whose identity matches the prebuilt's own recorded name, so custom
-# firmware is protected from the auto-reflash without any project marker.
-# Absent (no package.json, e.g. on-device test apps) the field is omitted.
-execute_process(
-    COMMAND node ${_MIK_RESOLVE} projectName ${CMAKE_SOURCE_DIR}
-    OUTPUT_VARIABLE _MIK_FW_NAME
-    OUTPUT_STRIP_TRAILING_WHITESPACE
-)
-# STREQUAL, not if(_MIK_FW_NAME): a project named "0", "off", or "false"
-# would read as a false constant and silently lose its identity.
-if(NOT _MIK_FW_NAME STREQUAL "")
-    target_compile_definitions(${COMPONENT_LIB} PRIVATE "MIK_FW_NAME=\"${_MIK_FW_NAME}\"")
-endif()
-if(EXISTS "${CMAKE_SOURCE_DIR}/package.json")
+# Board name and description: MIKROJS_BOARD_NAME and MIKROJS_BOARD_DESCRIPTION
+# (resolved by project.cmake), else the name and description in the nearest
+# package.json at or above the project (the app's, for a firmware folder inside
+# an app). The name is compiled in and reported as sys.board.name, and as
+# `board` and `fw` in MSG_READY. The CLI only auto-flashes its bundled image over
+# a device whose `fw` matches that image's name, so other firmware is never
+# replaced by accident. Without a name, `fw` is omitted and the board is
+# <chip>-generic.
+set(_MIK_NAME "${_MIK_BOARD_NAME}")
+set(_MIK_DESCRIPTION "${_MIK_BOARD_DESCRIPTION}")
+set(_MIK_FW_DIR "${CMAKE_SOURCE_DIR}")
+while(NOT EXISTS "${_MIK_FW_DIR}/package.json")
+    get_filename_component(_MIK_FW_PARENT "${_MIK_FW_DIR}" DIRECTORY)
+    if(_MIK_FW_PARENT STREQUAL _MIK_FW_DIR)
+        break()
+    endif()
+    set(_MIK_FW_DIR "${_MIK_FW_PARENT}")
+endwhile()
+if(EXISTS "${_MIK_FW_DIR}/package.json")
+    file(READ "${_MIK_FW_DIR}/package.json" _MIK_PROJECT_PACKAGE)
+    foreach(_field IN ITEMS name description)
+        string(TOUPPER "${_field}" _FIELD)
+        if(_MIK_${_FIELD} STREQUAL "")
+            string(JSON _MIK_${_FIELD} ERROR_VARIABLE _MIK_FIELD_ERROR
+                GET "${_MIK_PROJECT_PACKAGE}" ${_field})
+            if(_MIK_FIELD_ERROR)
+                set(_MIK_${_FIELD} "")
+            endif()
+        endif()
+    endforeach()
     set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS
-        "${CMAKE_SOURCE_DIR}/package.json")
+        "${_MIK_FW_DIR}/package.json")
+endif()
+# STREQUAL, not if(_MIK_NAME): a project named "0", "off", or "false" would read
+# as a false constant and silently lose its name.
+if(NOT _MIK_NAME STREQUAL "")
+    # The device keeps the name in a 64-byte buffer, and a registry rejects a
+    # check-in whose board name has another form.
+    string(LENGTH "${_MIK_NAME}" _MIK_NAME_LENGTH)
+    if(_MIK_NAME_LENGTH GREATER 63 OR NOT _MIK_NAME MATCHES
+       "^(@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*(/[a-z0-9]([a-z0-9.-]*[a-z0-9])?)?$")
+        message(FATAL_ERROR
+            "mikrojs: the board name is \"${_MIK_NAME}\". A board name has at most 63 "
+            "characters and the form of a package name, optionally followed by /<board> "
+            "(lowercase letters, digits, '.' and '-'). Set MIKROJS_BOARD_NAME.")
+    endif()
+    target_compile_definitions(${COMPONENT_LIB} PRIVATE "MIK_BOARD_NAME=\"${_MIK_NAME}\"")
 endif()
 
 # UTC build timestamp. `string(TIMESTAMP ... UTC)` honors SOURCE_DATE_EPOCH
@@ -196,21 +215,24 @@ endif()
 # build via its own reconfigure step, so in practice it's close to
 # build-fresh on ESP-IDF).
 string(TIMESTAMP _MIK_BUILD_DATE_UTC "%Y-%m-%dT%H:%M:%SZ" UTC)
-target_compile_definitions(${COMPONENT_LIB} PRIVATE "MIK_BUILD_DATE_UTC=\"${_MIK_BUILD_DATE_UTC}\"")
+set_property(SOURCE "${MIK_SRC_DIR}/mik_sys.cpp" APPEND PROPERTY COMPILE_DEFINITIONS
+    "MIK_BUILD_DATE_UTC=\"${_MIK_BUILD_DATE_UTC}\"")
 
-# Board name from MIKROJS_BOARD env var (set by CI or developer)
-if(DEFINED ENV{MIKROJS_BOARD})
-    # The registry rejects a check-in whose board name has another shape, and
-    # the device keeps it in a 48-byte buffer: a bad name means no OTA updates.
-    string(LENGTH "$ENV{MIKROJS_BOARD}" _MIK_BOARD_NAME_LEN)
-    if(NOT "$ENV{MIKROJS_BOARD}" MATCHES "^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$" OR _MIK_BOARD_NAME_LEN GREATER 47)
-        message(FATAL_ERROR
-            "mikrojs: MIKROJS_BOARD is \"$ENV{MIKROJS_BOARD}\". A board name has at most 47 "
-            "characters: lowercase letters, digits, '.' and '-', and it starts and ends with a "
-            "letter or digit.")
-    endif()
-    target_compile_definitions(${COMPONENT_LIB} PRIVATE "MIK_BOARD_NAME=\"$ENV{MIKROJS_BOARD}\"")
+# firmware.json next to flasher_args.json: what the image is, for the tools
+# that read it without a device (mikro flash, mikro fw pack and build).
+# Written below, once the feature list is known.
+set(_MIK_FW_JSON "{")
+if(NOT _MIK_NAME STREQUAL "")
+    string(APPEND _MIK_FW_JSON "\"name\": \"${_MIK_NAME}\", ")
 endif()
+if(NOT _MIK_DESCRIPTION STREQUAL "")
+    # Free text: escape it for JSON, on one line.
+    string(REPLACE "\\" "\\\\" _MIK_DESCRIPTION "${_MIK_DESCRIPTION}")
+    string(REPLACE "\"" "\\\"" _MIK_DESCRIPTION "${_MIK_DESCRIPTION}")
+    string(REGEX REPLACE "[\r\n\t]+" " " _MIK_DESCRIPTION "${_MIK_DESCRIPTION}")
+    string(APPEND _MIK_FW_JSON "\"description\": \"${_MIK_DESCRIPTION}\", ")
+endif()
+string(APPEND _MIK_FW_JSON "\"chip\": \"${IDF_TARGET}\", \"version\": \"${_MIK_VERSION}\", ")
 
 # ── Module lists derived from runtime/modules.json ───────────────────
 # Feature gating for the derived lists: ble-gated modules compile only when
@@ -227,37 +249,40 @@ else()
     set(_MIK_WIFI_FLAG "--wifi=off")
 endif()
 
-# Firmware feature list (e.g. "wifi,i2s,ble"), reported in MSG_READY so the
-# host knows which feature-gated builtins this firmware carries.
 execute_process(
-    COMMAND node "${MIK_SCRIPTS_DIR}/modules-list.js" features ${_MIK_BLE_FLAG} ${_MIK_WIFI_FLAG}
-    OUTPUT_VARIABLE _MIK_FEATURES
+    COMMAND node "${MIK_SCRIPTS_DIR}/modules-list.js" ${_MIK_BLE_FLAG} ${_MIK_WIFI_FLAG}
+    OUTPUT_VARIABLE _MIK_LISTS
     OUTPUT_STRIP_TRAILING_WHITESPACE
-    RESULT_VARIABLE _MIK_FEATURES_RESULT
+    RESULT_VARIABLE _MIK_LISTS_RESULT
 )
-if(NOT _MIK_FEATURES_RESULT EQUAL 0)
-    message(FATAL_ERROR "modules-list.js features failed")
+if(NOT _MIK_LISTS_RESULT EQUAL 0)
+    message(FATAL_ERROR "modules-list.js failed")
 endif()
+string(JSON _MIK_FEATURES GET "${_MIK_LISTS}" features)
+string(JSON _MIK_MODULES GET "${_MIK_LISTS}" native)
+string(JSON _MIK_BYTECODE_MODULES GET "${_MIK_LISTS}" bytecode)
+
+# The features in firmware.json too, so the tools can tell a board's images
+# apart and match the one a device runs.
+set(_MIK_FEATURES_JSON "")
+foreach(_mik_feature IN LISTS _MIK_FEATURES)
+    if(NOT _MIK_FEATURES_JSON STREQUAL "")
+        string(APPEND _MIK_FEATURES_JSON ", ")
+    endif()
+    string(APPEND _MIK_FEATURES_JSON "\"${_mik_feature}\"")
+endforeach()
+string(APPEND _MIK_FW_JSON "\"features\": [${_MIK_FEATURES_JSON}]}\n")
+file(WRITE "${CMAKE_BINARY_DIR}/firmware.json" "${_MIK_FW_JSON}")
+
+# Firmware feature list (e.g. "wifi,i2s,ble"), reported in MSG_READY so the
+# host knows which feature-gated builtins this firmware carries.
 string(REPLACE ";" "," _MIK_FEATURES "${_MIK_FEATURES}")
 target_compile_definitions(${COMPONENT_LIB} PRIVATE "MIK_FW_FEATURES=\"${_MIK_FEATURES}\"")
-
-execute_process(
-    COMMAND node "${MIK_SCRIPTS_DIR}/modules-list.js" native ${_MIK_BLE_FLAG} ${_MIK_WIFI_FLAG}
-    OUTPUT_VARIABLE _MIK_MODULES
-    OUTPUT_STRIP_TRAILING_WHITESPACE
-    RESULT_VARIABLE _MIK_MODULES_RESULT
-)
-if(NOT _MIK_MODULES_RESULT EQUAL 0)
-    message(FATAL_ERROR "modules-list.js native failed")
-endif()
-execute_process(
-    COMMAND node "${MIK_SCRIPTS_DIR}/modules-list.js" bytecode ${_MIK_BLE_FLAG} ${_MIK_WIFI_FLAG}
-    OUTPUT_VARIABLE _MIK_BYTECODE_MODULES
-    OUTPUT_STRIP_TRAILING_WHITESPACE
-    RESULT_VARIABLE _MIK_BYTECODE_RESULT
-)
-if(NOT _MIK_BYTECODE_RESULT EQUAL 0)
-    message(FATAL_ERROR "modules-list.js bytecode failed")
+# Without radios there is no WiFi, lwIP or TLS demand to hold heap back for, so
+# the default memReserved drops from 64 KB to 16 KB (mik_app_config.cpp). The
+# CLI's defaultMemReserved follows the same rule.
+if(NOT CONFIG_BT_ENABLED AND NOT CONFIG_MIKROJS_WIFI)
+    target_compile_definitions(${COMPONENT_LIB} PRIVATE "MIK_DEFAULT_MEM_RESERVED=16384")
 endif()
 # The lists are read at configure time, so configure must re-run when the
 # table or the script changes.
@@ -273,8 +298,6 @@ mikrojs_force_include_modules(${_MIK_MODULES})
 mikrojs_generate_bytecode(
     RUNTIME_DIR "${MIK_RUNTIME_DIR}"
     MODULES ${_MIK_BYTECODE_MODULES}
-    MODULE_PREFIX "mikro"
-    SYMBOL_PREFIX "mikro"
     TARGET gen_bytecode
     WORKING_DIRECTORY "${MIKROJS_PROJECT_DIR}"
 )

package/components/mikrojs/mik_gpio.cpp

@@ -93,7 +93,7 @@ static MIKGpioState* mik__gpio_get(JSContext* ctx, JSValueConst this_val, JSClas
 
 /* Claims `gpio` for the handle kind, or returns the GpioInUse Result. */
 static JSValue mik__gpio_claim(JSContext* ctx, int gpio, MIKGpioKind kind) {
-    return mik__claim_gpios(ctx, &gpio, 1, s_owner_names[kind]);
+    return MIK_ClaimGpios(ctx, &gpio, 1, s_owner_names[kind]);
 }
 
 /* Converts a JS value to a pin level. Returns false unless it is the number 0 or 1. */

package/components/mikrojs/mik_i2c.cpp

@@ -60,7 +60,7 @@ static void mik__i2c_release(MIKI2CState* s) {
     i2c_del_master_bus(s->bus);
     s->bus = nullptr;
     const int gpios[] = {s->sda, s->scl};
-    mik__release_gpios(gpios, countof(gpios), "I2c");
+    MIK_ReleaseGpios(gpios, countof(gpios), "I2c");
     s->active = false;
 }
 
@@ -129,7 +129,7 @@ static JSValue js_i2c(JSContext* ctx, JSValue this_val, int argc, JSValue* argv)
     JSValue invalid = mik__gpio_check(ctx, checks, countof(checks));
     if (!JS_IsUndefined(invalid)) return invalid;
     const int gpios[] = {sda, scl};
-    JSValue claim_failed = mik__claim_gpios(ctx, gpios, countof(gpios), "I2c");
+    JSValue claim_failed = MIK_ClaimGpios(ctx, gpios, countof(gpios), "I2c");
     if (!JS_IsUndefined(claim_failed)) return claim_failed;
 
     i2c_master_bus_config_t bus_cfg = {};
@@ -143,7 +143,7 @@ static JSValue js_i2c(JSContext* ctx, JSValue this_val, int argc, JSValue* argv)
     i2c_master_bus_handle_t bus = nullptr;
     esp_err_t err = i2c_new_master_bus(&bus_cfg, &bus);
     if (err != ESP_OK) {
-        mik__release_gpios(gpios, countof(gpios), "I2c");
+        MIK_ReleaseGpios(gpios, countof(gpios), "I2c");
         return mik__result_err_named(ctx, "BusInitFailed", "failed to initialize I2C bus %d: %s",
                                      (int)port, esp_err_to_name(err));
     }
@@ -151,7 +151,7 @@ static JSValue js_i2c(JSContext* ctx, JSValue this_val, int argc, JSValue* argv)
     auto* s = static_cast<MIKI2CState*>(calloc(1, sizeof(MIKI2CState)));
     if (!s) {
         i2c_del_master_bus(bus);
-        mik__release_gpios(gpios, countof(gpios), "I2c");
+        MIK_ReleaseGpios(gpios, countof(gpios), "I2c");
         return JS_ThrowOutOfMemory(ctx);
     }
     s->bus = bus;

package/components/mikrojs/mik_i2s.cpp

@@ -193,7 +193,7 @@ static void mik__i2s_finalizer(JSRuntime* rt, JSValue val) {
             i2s_del_channel(s->rx_chan);
         }
         const int gpios[] = MIK__I2S_GPIOS(s);
-        mik__release_gpios(gpios, countof(gpios), "I2s");
+        MIK_ReleaseGpios(gpios, countof(gpios), "I2s");
     }
     for (int i = 0; i < s->tx_count; i++) {
         MIKI2sTxChunk* c = &s->tx_queue[(s->tx_head + i) % MIK_I2S_TX_QUEUE_DEPTH];
@@ -362,7 +362,7 @@ static JSValue js_i2s(JSContext* ctx, JSValue this_val, int argc, JSValue* argv)
     s->din = din;
 
     const int gpios[] = MIK__I2S_GPIOS(s);
-    JSValue claim_failed = mik__claim_gpios(ctx, gpios, countof(gpios), "I2s");
+    JSValue claim_failed = MIK_ClaimGpios(ctx, gpios, countof(gpios), "I2s");
     if (!JS_IsUndefined(claim_failed)) {
         free(s);
         return claim_failed;
@@ -374,7 +374,7 @@ static JSValue js_i2s(JSContext* ctx, JSValue this_val, int argc, JSValue* argv)
     if (err == ESP_OK && !mik__i2s_track(ctx, s)) err = ESP_ERR_NO_MEM;
     if (err != ESP_OK) {
         mik__i2s_del_channels(s);
-        mik__release_gpios(gpios, countof(gpios), "I2s");
+        MIK_ReleaseGpios(gpios, countof(gpios), "I2s");
         free(s);
         return mik__result_err_named(ctx, "ChannelInitFailed", "I2S init failed: %s",
                                      esp_err_to_name(err));
@@ -385,7 +385,7 @@ static JSValue js_i2s(JSContext* ctx, JSValue this_val, int argc, JSValue* argv)
     if (JS_IsException(obj)) {
         mik__i2s_untrack(ctx, s);
         mik__i2s_del_channels(s);
-        mik__release_gpios(gpios, countof(gpios), "I2s");
+        MIK_ReleaseGpios(gpios, countof(gpios), "I2s");
         free(s);
         return obj;
     }
@@ -421,7 +421,7 @@ static JSValue js_i2s_end(JSContext* ctx, JSValue this_val, int argc, JSValue* a
     mik__i2s_untrack(ctx, s);
     mik__i2s_del_channels(s);
     const int gpios[] = MIK__I2S_GPIOS(s);
-    mik__release_gpios(gpios, countof(gpios), "I2s");
+    MIK_ReleaseGpios(gpios, countof(gpios), "I2s");
     s->active = false;
     MIK_DropHandle(ctx, this_val);
     return JS_UNDEFINED;

package/components/mikrojs/mik_main.cpp

@@ -565,8 +565,7 @@ void MIK_Main(void) {
          * (USB-Serial/JTAG). `printf` goes to newlib stdio, which
          * ESP-IDF routes to UART0 and is invisible over USB. */
         const char* core_word = chip_info.cores == 1 ? "core" : "cores";
-        const MIKPlatform* plat = MIK_GetPlatform();
-        const char* dev_id = plat->get_device_id ? plat->get_device_id() : nullptr;
+        const char* dev_id = MIK_GetPlatform()->get_device_id();
         char banner[160];
         int off = 0;
 #ifdef MIK_FW_VERSION
@@ -577,9 +576,7 @@ void MIK_Main(void) {
                         JS_GetVersion(), CONFIG_IDF_TARGET);
 #endif
         /* Stable per-board device id (chip MAC as Crockford Base32). */
-        if (dev_id && dev_id[0]) {
-            off += snprintf(banner + off, sizeof(banner) - off, " (%s)", dev_id);
-        }
+        off += snprintf(banner + off, sizeof(banner) - off, " (%s)", dev_id);
         off += snprintf(banner + off, sizeof(banner) - off, ", %d %s", chip_info.cores, core_word);
         if (has_wifi || has_bt || has_ble) {
             off += snprintf(banner + off, sizeof(banner) - off, ", ");

package/components/mikrojs/mik_neopixel.cpp

@@ -213,7 +213,7 @@ static JSValue js_neopixel(JSContext* ctx, JSValue this_val, int argc, JSValue*
     JSValue invalid = mik__gpio_check(ctx, &check, 1);
     if (!JS_IsUndefined(invalid)) return invalid;
     const int gpios[] = {gpio};
-    JSValue claim_failed = mik__claim_gpios(ctx, gpios, 1, "NeoPixel");
+    JSValue claim_failed = MIK_ClaimGpios(ctx, gpios, 1, "NeoPixel");
     if (!JS_IsUndefined(claim_failed)) return claim_failed;
 
     int bytes_per_led = rgbw ? 4 : 3;

package/components/mikrojs/mik_nvs_kv.cpp

@@ -186,14 +186,14 @@ static JSValue mik__nvs_kv_remove(JSContext* ctx, JSValue this_val, int argc, JS
     esp_err_t err = nvs_erase_key(handle, key);
     JS_FreeCString(ctx, key);
 
-    if (err != ESP_OK) {
+    /* A missing key is already removed, not a failure. */
+    if (err == ESP_ERR_NVS_NOT_FOUND) {
         nvs_close(handle);
-        return JS_NewBool(ctx, false);
+        return JS_NewBool(ctx, true);
     }
-
-    nvs_commit(handle);
+    if (err == ESP_OK) err = nvs_commit(handle);
     nvs_close(handle);
-    return JS_NewBool(ctx, true);
+    return JS_NewBool(ctx, err == ESP_OK);
 }
 
 static JSValue mik__nvs_kv_clear(JSContext* ctx, JSValue this_val, int argc, JSValue* argv,

package/components/mikrojs/mik_ota_env.cpp

@@ -339,9 +339,8 @@ bool env_read_app_version(void* opaque, char* out, size_t out_len) {
 const MIKOtaEnv* mik__ota_env_for(MIKRuntime* rt, int bytecode_version) {
     g_state.rt = rt;
     g_state.bytecode_version = bytecode_version;
-    const MIKPlatform* platform = MIK_GetPlatform();
-    const char* id = platform->get_device_id ? platform->get_device_id() : nullptr;
-    snprintf(g_state.device_id, sizeof(g_state.device_id), "%s", id ? id : "");
+    snprintf(g_state.device_id, sizeof(g_state.device_id), "%s",
+             MIK_GetPlatform()->get_device_id());
 
     MIKOtaEnv& env = g_state.env;
     env = {};

package/components/mikrojs/mik_pwm.cpp

@@ -232,7 +232,7 @@ static JSValue js_pwm(JSContext* ctx, JSValue this_val, int argc, JSValue* argv)
     invalid = mik__gpio_check(ctx, &check, 1);
     if (!JS_IsUndefined(invalid)) return invalid;
     const int gpios[] = {gpio};
-    JSValue claim_failed = mik__claim_gpios(ctx, gpios, 1, "Pwm");
+    JSValue claim_failed = MIK_ClaimGpios(ctx, gpios, 1, "Pwm");
     if (!JS_IsUndefined(claim_failed)) return claim_failed;
 
     int ch = mik__pwm_alloc_channel();

package/components/mikrojs/mik_rtc.cpp

@@ -157,26 +157,29 @@ static JSValue mik__rtc_set(JSContext* ctx, JSValue this_val, int argc, JSValue*
     auto* hdr = reinterpret_cast<RtcHeader*>(s_rtc_store);
     uint8_t* data = mik__rtc_data();
 
-    /* Remove existing entry if present */
+    /* Check space before changing anything, counting the bytes an existing entry would free, so
+     * a failed set keeps the old value and a valid CRC */
     uint8_t* next = nullptr;
     uint8_t* found = mik__rtc_find(key, static_cast<uint8_t>(key_len), &next);
+    size_t old_size = (found && next) ? static_cast<size_t>(next - found) : 0;
+    size_t used = hdr->data_len - old_size;
+    size_t needed = mik__rtc_entry_size(static_cast<uint8_t>(key_len), static_cast<uint16_t>(val_len));
+    if (used + needed > MIK_RTC_DATA_CAPACITY) {
+        JS_FreeCString(ctx, key);
+        return mik__result_err(ctx, MIK_ERR_KV_STORAGE_FULL, 0,
+                               "RTC memory full (need %zu bytes, %zu available)", needed,
+                               MIK_RTC_DATA_CAPACITY - used);
+    }
+
+    /* Remove existing entry if present */
     if (found && next) {
         uint8_t* end = data + hdr->data_len;
         size_t tail = end - next;
         memmove(found, next, tail);
-        hdr->data_len -= static_cast<uint16_t>(next - found);
+        hdr->data_len -= static_cast<uint16_t>(old_size);
         hdr->entry_count--;
     }
 
-    /* Check space */
-    size_t needed = mik__rtc_entry_size(static_cast<uint8_t>(key_len), static_cast<uint16_t>(val_len));
-    if (hdr->data_len + needed > MIK_RTC_DATA_CAPACITY) {
-        JS_FreeCString(ctx, key);
-        return mik__result_err(ctx, MIK_ERR_KV_STORAGE_FULL, 0,
-                               "RTC memory full (need %zu bytes, %zu available)", needed,
-                               MIK_RTC_DATA_CAPACITY - hdr->data_len);
-    }
-
     /* Append new entry: encode CBOR directly into the RTC store */
     uint8_t* write_pos = data + hdr->data_len;
     write_pos[0] = static_cast<uint8_t>(key_len);
@@ -250,7 +253,8 @@ static JSValue mik__rtc_remove(JSContext* ctx, JSValue this_val, int argc, JSVal
     uint8_t* found = mik__rtc_find(key, static_cast<uint8_t>(key_len), &next);
     JS_FreeCString(ctx, key);
 
-    if (!found || !next) return JS_NewBool(ctx, false);
+    /* A missing key is already removed, not a failure. */
+    if (!found || !next) return JS_NewBool(ctx, true);
 
     uint8_t* end = data + hdr->data_len;
     size_t tail = end - next;

package/components/mikrojs/mik_spi.cpp

@@ -34,7 +34,7 @@ static void mik__spi_release(MIKSPIState* s) {
     s->device = nullptr;
     spi_bus_free(s->host);
     const int gpios[] = {s->clk, s->mosi, s->miso, s->cs};
-    mik__release_gpios(gpios, countof(gpios), "Spi");
+    MIK_ReleaseGpios(gpios, countof(gpios), "Spi");
     s->active = false;
 }
 
@@ -95,7 +95,7 @@ static JSValue js_spi(JSContext* ctx, JSValue this_val, int argc, JSValue* argv)
     JSValue invalid = mik__gpio_check(ctx, checks, countof(checks));
     if (!JS_IsUndefined(invalid)) return invalid;
     const int gpios[] = {clk, mosi, miso, cs};
-    JSValue claim_failed = mik__claim_gpios(ctx, gpios, countof(gpios), "Spi");
+    JSValue claim_failed = MIK_ClaimGpios(ctx, gpios, countof(gpios), "Spi");
     if (!JS_IsUndefined(claim_failed)) return claim_failed;
 
     /* SPI2_HOST is 1, SPI3_HOST is 2, etc. — host maps directly */
@@ -110,7 +110,7 @@ static JSValue js_spi(JSContext* ctx, JSValue this_val, int argc, JSValue* argv)
 
     esp_err_t err = spi_bus_initialize(host_id, &bus_cfg, SPI_DMA_CH_AUTO);
     if (err != ESP_OK) {
-        mik__release_gpios(gpios, countof(gpios), "Spi");
+        MIK_ReleaseGpios(gpios, countof(gpios), "Spi");
         return mik__result_err_named(ctx, "BusInitFailed", "SPI bus init failed: %s",
                                      esp_err_to_name(err));
     }
@@ -129,7 +129,7 @@ static JSValue js_spi(JSContext* ctx, JSValue this_val, int argc, JSValue* argv)
     err = spi_bus_add_device(host_id, &dev_cfg, &device);
     if (err != ESP_OK) {
         spi_bus_free(host_id);
-        mik__release_gpios(gpios, countof(gpios), "Spi");
+        MIK_ReleaseGpios(gpios, countof(gpios), "Spi");
         return mik__result_err_named(ctx, "AddDeviceFailed", "failed to add SPI device: %s",
                                      esp_err_to_name(err));
     }
@@ -138,7 +138,7 @@ static JSValue js_spi(JSContext* ctx, JSValue this_val, int argc, JSValue* argv)
     if (!s) {
         spi_bus_remove_device(device);
         spi_bus_free(host_id);
-        mik__release_gpios(gpios, countof(gpios), "Spi");
+        MIK_ReleaseGpios(gpios, countof(gpios), "Spi");
         return JS_ThrowOutOfMemory(ctx);
     }
     s->device = device;