@mikrojs/firmware 0.12.0 → 0.14.0-pr-229.g0d8db1b

package/README.md

@@ -6,20 +6,19 @@ ESP32 firmware package for Mikro.js. Provides the ESP-IDF integration, build sys
 
 - **`project.cmake`** - CMake module that integrates with ESP-IDF. Handles component discovery, SDK config merging, and partition table defaults.
 - **`components/mikrojs/`** - ESP-IDF component that compiles the Mikro.js runtime, QuickJS engine, and platform-specific C modules.
-- **`idf.py` wrapper** - Runs `idf.py` through `eim run`, so you don't need to manually activate ESP-IDF.
 - **Default configs** - `sdkconfig.defaults` and `partitions.csv` for common setups.
 
 ## Usage
 
-A custom firmware project depends on this package and includes `project.cmake`:
+A custom firmware project depends on this package and includes `project.cmake` (resolved via `resolve.js`, see the docs below for the CMakeLists boilerplate):
 
 ```
 my-firmware/
 ├── package.json          # depends on @mikrojs/firmware
-├── CMakeLists.txt        # include($ENV{MIKROJS_PROJECT_CMAKE})
-└── main/
-    ├── CMakeLists.txt
-    └── main.cpp          # calls MIK_Main()
+├── CMakeLists.txt        # resolves and includes project.cmake via resolve.js
+└── main/                 # optional: omit it and the package's default main
+    ├── CMakeLists.txt    # (which calls MIK_Main()) is used automatically
+    └── main.cpp
 ```
 
 See the [Custom Firmware](https://mikrojs.dev/develop/custom-firmware) docs for details.
@@ -27,4 +26,6 @@ See the [Custom Firmware](https://mikrojs.dev/develop/custom-firmware) docs for
 ## Requirements
 
 - Node.js >= 24
-- ESP-IDF >= 6.0.1 (installed via [EIM](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/index.html))
+- ESP-IDF >= 6.0.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.

package/components/mikrojs/CMakeLists.txt

@@ -134,7 +134,7 @@ include("${MIK_BYTECODE_CMAKE}")
 
 # Force linker to include self-registering native modules
 set(_MIK_MODULES cbor pin i2c spi http http_server wifi rtc nvs_kv sntp sleep neopixel pwm uart)
-set(_MIK_BYTECODE_MODULES cbor env result schema fs http/helpers http/request http/server i2c kv/nvs kv/rtc kv/shared module neopixel observable observable/lazy observable/operators pin pwm reader sleep spi sntp stdio stream sys test uart udp wifi)
+set(_MIK_BYTECODE_MODULES abort cbor env result schema fs http/helpers http/request http/server i2c kv/nvs kv/rtc kv/shared module neopixel observable observable/lazy observable/operators pin pwm reader sleep spi sntp stdio stream sys test uart udp wifi)
 if(CONFIG_BT_ENABLED)
     list(APPEND _MIK_MODULES ble)
     list(APPEND _MIK_BYTECODE_MODULES ble)

package/components/mikrojs/include/mikrojs_esp32.h

@@ -60,6 +60,10 @@ void mik_logfile_flush(void);
  * when file logging is disabled. */
 void mik_logfile_suspend(void);
 void mik_logfile_resume(void);
+/* Clear the log files: close + unlink log.txt and log.txt.1, then reopen
+ * a fresh empty log.txt. Logging continues uninterrupted (no restart).
+ * No-op when file logging is disabled. */
+void mik_logfile_reset(void);
 
 /* Serial binary I/O (mik_serial_io.cpp) */
 void mik__serial_binary_begin_no_echo(void);

package/components/mikrojs/mik_http.cpp

@@ -218,9 +218,17 @@ static void mik__http_task(void* arg) {
             int tls_flags = 0;
             esp_err_t last_tls_err =
                 esp_http_client_get_and_clear_last_tls_error(client, &tls_code, &tls_flags);
+            /* Alloc-class failures surface as opaque transport codes: 0x008d
+             * is PSA's INSUFFICIENT_MEMORY (-141) leaking through the mbedtls
+             * slot untranslated, 0x7f00 is MBEDTLS_ERR_SSL_ALLOC_FAILED. Name
+             * the condition when a trustworthy code is present; otherwise
+             * keep the plain connect error (no heap-level guessing). */
+            bool out_of_memory = err == ESP_ERR_NO_MEM || last_tls_err == ESP_ERR_NO_MEM ||
+                                 tls_code == 0x008d || tls_code == 0x7f00;
             snprintf(error_buf, sizeof(error_buf),
-                     "fetch failed: could not connect to %s (%s, errno=%d, "
+                     "fetch failed: %s %s (%s, errno=%d, "
                      "esp_tls=%s, mbedtls=-0x%04x, flags=0x%x)",
+                     out_of_memory ? "out of memory connecting to" : "could not connect to",
                      args->req.url, esp_err_to_name(err), sock_errno,
                      esp_err_to_name(last_tls_err), tls_code, tls_flags);
             have_error = true;
@@ -573,6 +581,14 @@ static JSValue mik__http_request(JSContext* ctx, JSValue this_val, int argc, JSV
     MIKHttpPending pending = {};
     pending.id = mik__http_st(mik_rt)->next_id++;
     JSValue headers_promise = MIK_InitPromise(ctx, &pending.headers_promise);
+    if (JS_IsException(headers_promise)) {
+        /* OOM building the promise. Nothing is registered yet, so just free the
+         * request and propagate. Do NOT register this pending entry: its
+         * headers_promise.rfuncs are unwritten on failure, and a later
+         * consume/destroy would free dangling values (gc_decref underflow). */
+        mik__http_free_request(&req);
+        return JS_EXCEPTION;
+    }
 
     auto* cancelled = new std::atomic<bool>(false);
     pending.cancelled = cancelled;
@@ -664,6 +680,12 @@ static JSValue mik__http_next_message(JSContext* ctx, JSValue this_val, int argc
 
     /* Slow path: wait. Create a new promise stored on the pending entry. */
     JSValue promise = MIK_InitPromise(ctx, &p->next_promise);
+    if (JS_IsException(promise)) {
+        /* OOM building the promise. Do NOT mark next_promise_active: rfuncs are
+         * unwritten on failure, so a later resolve/destroy would free dangling
+         * values (gc_decref underflow). */
+        return JS_EXCEPTION;
+    }
     p->next_promise_active = true;
     return promise;
 }

package/components/mikrojs/mik_logfile.cpp

@@ -232,6 +232,28 @@ void mik_logfile_resume(void) {
     xSemaphoreGive(s_mtx);
 }
 
+void mik_logfile_reset(void) {
+    if (!s_mtx) return;
+    if (xSemaphoreTake(s_mtx, pdMS_TO_TICKS(100)) != pdTRUE) return;
+    if (s_file) {
+        fclose(s_file);
+        s_file = nullptr;
+    }
+    unlink(s_path_main);
+    unlink(s_path_rot);
+    /* Reopen the same path: unlinked, so this starts a fresh empty file. */
+    s_file = fopen(s_path_main, "a");
+    if (s_file) {
+        setvbuf(s_file, s_stdio_buf, _IOFBF, sizeof(s_stdio_buf));
+        s_file_size = 0;
+    }
+    /* Drop any half-assembled line so a stale prefix doesn't bleed into
+     * the fresh file. */
+    s_line_pos = 0;
+    s_line_has_ts = false;
+    xSemaphoreGive(s_mtx);
+}
+
 void mik_logfile_flush(void) {
     if (!s_mtx || !s_file) return;
     if (xSemaphoreTake(s_mtx, pdMS_TO_TICKS(50)) != pdTRUE) return;

package/components/mikrojs/mik_main.cpp

@@ -75,7 +75,11 @@ static void mik__apply_nvs_log_level(void) {
 #define MIK_SUP_PATH_MAX 384
 static char s_sup_dbg[MIK_SUP_PATH_MAX + 64];
 static char s_sup_esc[MIK_SUP_PATH_MAX * 2 + 8];
-static char s_sup_buf[MIK_SUP_PATH_MAX * 2 + 128];
+static char s_sup_buf[MIK_SUP_PATH_MAX * 2 + 512];
+/* Exception text captured by MIK_RunEntryErr when a test file fails to
+ * evaluate, and its JSON-escaped form for the synthesized test event. */
+static char s_sup_err[192];
+static char s_sup_err_esc[sizeof(s_sup_err) * 2 + 8];
 
 /* Minimal JSON string-escape into a bounded buffer. Handles `"`, `\`, and
  * control characters; everything else copies verbatim. Returns bytes
@@ -169,6 +173,14 @@ static bool platform_command_handler(MIKReplTransport* transport, uint8_t cmd_ty
         return mik__handle_fs_get(transport, payload_len);
     }
 
+    /* Log reset (0x2C): clear the on-device log files */
+    if (cmd_type == MIK_CMD_LOG_RESET) {
+        mik__proto_drain(transport, payload_len);
+        mik_logfile_reset();
+        mik__proto_send_ok(transport);
+        return true;
+    }
+
     /* Config commands (0x40-0x42) */
     if (cmd_type >= MIK_CMD_CONFIG_LIST && cmd_type <= MIK_CMD_CONFIG_DELETE) {
         return mik__handle_config_command(transport, cmd_type, payload_len);
@@ -476,7 +488,7 @@ void MIK_Main(void) {
             MIKRuntime* rt = create_runtime();
             MIK_EnableTestHelpers(rt);
             MIK_ProtocolAttach(rt);
-            int rc = MIK_RunEntry(rt, test_paths[i]);
+            int rc = MIK_RunEntryErr(rt, test_paths[i], s_sup_err, sizeof(s_sup_err));
             const char* fail_reason = nullptr;
             if (rc == -ENOENT) {
                 fail_reason = "Test file not found";
@@ -508,10 +520,26 @@ void MIK_Main(void) {
                         s_sup_esc[1] = '\0';
                     }
                 }
-                int n = snprintf(s_sup_buf, sizeof(s_sup_buf),
+                /* Append the captured exception text (escaped) so the CLI
+                 * shows the actual error, not just "Evaluation threw". */
+                s_sup_err_esc[0] = '\0';
+                if (rc == -EFAULT && s_sup_err[0] != '\0') {
+                    if (mik__json_escape(s_sup_err_esc, sizeof(s_sup_err_esc), s_sup_err) < 0) {
+                        s_sup_err_esc[0] = '\0';
+                    }
+                }
+                int n;
+                if (s_sup_err_esc[0] != '\0') {
+                    n = snprintf(s_sup_buf, sizeof(s_sup_buf),
+                                 "{\"e\":3,\"s\":\"<load>\",\"t\":\"%s\",\"d\":0,"
+                                 "\"m\":\"%s: %s\"}",
+                                 s_sup_esc, fail_reason, s_sup_err_esc);
+                } else {
+                    n = snprintf(s_sup_buf, sizeof(s_sup_buf),
                                  "{\"e\":3,\"s\":\"<load>\",\"t\":\"%s\",\"d\":0,"
                                  "\"m\":\"%s\"}",
                                  s_sup_esc, fail_reason);
+                }
                 if (n > 0 && n < (int)sizeof(s_sup_buf)) {
                     mik__proto_send(&transport, MIK_MSG_TEST, s_sup_buf, n);
                 }

package/components/mikrojs/mik_sntp.cpp

@@ -144,6 +144,15 @@ static JSValue mik__sntp_sync(JSContext* ctx, JSValue this_val, int argc, JSValu
 
     /* Create and return promise wrapped in result */
     JSValue promise = MIK_InitPromise(ctx, &state->sync_promise);
+    if (JS_IsException(promise)) {
+        /* OOM building the promise. Tear down so we don't leave a half-started
+         * sync, and crucially do NOT set sync_pending: MIK_InitPromise leaves
+         * sync_promise.rfuncs unwritten on failure, so a later consume/destroy
+         * would free dangling values (gc_decref refcount underflow). */
+        esp_netif_sntp_deinit();
+        state->running = false;
+        return JS_EXCEPTION;
+    }
     state->sync_pending = true;
 
     return mik__result_ok(ctx, promise);

package/components/mikrojs/mik_wifi.cpp

@@ -2,6 +2,7 @@
 #include <vector>
 
 #include "esp_event.h"
+#include "esp_heap_caps.h"
 #include "esp_log.h"
 #include "esp_mac.h"
 #include "esp_netif.h"
@@ -332,6 +333,17 @@ fail_after_init:
     return err;
 }
 
+/* Minimum free internal (DMA-capable) RAM required before bringing up the
+ * radio. esp_wifi_start() enables the PHY, which calloc()s its RF
+ * calibration data from internal RAM and calls abort() on failure
+ * (esp_phy/src/phy_init.c: "failed to allocate memory for RF calibration
+ * data"). That hard-abort reboots the device instead of surfacing a
+ * catchable error, so we pre-flight the heap here and refuse gracefully
+ * when it's too low. The figure covers the PHY cal buffers plus the WiFi
+ * driver's start-time internal allocations with margin; it is a heuristic,
+ * not an exact bound. Tune if a healthy device ever trips it. */
+static constexpr size_t MIK_WIFI_MIN_INTERNAL_HEAP = 40 * 1024;
+
 /* Start the WiFi radio.  Deferred from init so the radio is not active
  * until connect() or scan() is actually called. */
 static esp_err_t mik__wifi_ensure_started(JSContext* ctx) {
@@ -339,6 +351,13 @@ static esp_err_t mik__wifi_ensure_started(JSContext* ctx) {
     if (err != ESP_OK) return err;
     if (s_wifi_started) return ESP_OK;
 
+    /* Refuse to start under low internal RAM rather than let the PHY init
+     * abort() the whole device. The caller turns ESP_ERR_NO_MEM into a
+     * catchable StartFailed result. */
+    if (heap_caps_get_free_size(MALLOC_CAP_INTERNAL) < MIK_WIFI_MIN_INTERNAL_HEAP) {
+        return ESP_ERR_NO_MEM;
+    }
+
     err = esp_wifi_start();
     if (err != ESP_OK) return err;
 

package/components/mikrojs/platform_esp32.cpp

@@ -167,6 +167,43 @@ static const char* esp32_get_device_id(void) {
     return id;
 }
 
+static const char* esp32_get_reset_reason(void) {
+    switch (esp_reset_reason()) {
+        case ESP_RST_POWERON:
+            return "power-on";
+        case ESP_RST_EXT:
+            return "external";
+        case ESP_RST_SW:
+            return "software";
+        case ESP_RST_PANIC:
+            return "panic";
+        case ESP_RST_INT_WDT:
+            return "interrupt-watchdog";
+        case ESP_RST_TASK_WDT:
+            return "task-watchdog";
+        case ESP_RST_WDT:
+            return "watchdog";
+        case ESP_RST_DEEPSLEEP:
+            return "deep-sleep";
+        case ESP_RST_BROWNOUT:
+            return "brownout";
+        case ESP_RST_SDIO:
+            return "sdio";
+        case ESP_RST_USB:
+            return "usb";
+        case ESP_RST_JTAG:
+            return "jtag";
+        case ESP_RST_EFUSE:
+            return "efuse";
+        case ESP_RST_PWR_GLITCH:
+            return "power-glitch";
+        case ESP_RST_CPU_LOCKUP:
+            return "cpu-lockup";
+        default:
+            return "unknown";
+    }
+}
+
 static void esp32_log(int level, const char* tag, const char* fmt, ...) {
     /* Map MIK_LOG_xxx to ESP_LOG_xxx for the runtime filter check. */
     esp_log_level_t esp_level;
@@ -238,6 +275,7 @@ static const MIKPlatform esp32_platform = {
     .stderr_write = esp32_stderr_write,
     .stdin_read = esp32_stdin_read,
     .get_device_id = esp32_get_device_id,
+    .get_reset_reason = esp32_get_reset_reason,
 };
 
 /*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/firmware",
-  "version": "0.12.0",
+  "version": "0.14.0-pr-229.g0d8db1b",
   "description": "Mikro.js ESP32 firmware: ESP-IDF component, build tools, and project template",
   "keywords": [
     "esp-idf",
@@ -18,9 +18,6 @@
     "type": "git",
     "url": "git+https://github.com/mikrojs/mikro.git"
   },
-  "bin": {
-    "idf.py": "./bin/idf.py"
-  },
   "files": [
     "components",
     "default-app",
@@ -28,7 +25,6 @@
     "sdkconfig.defaults",
     "sdkconfig.defaults.*",
     "partitions.csv",
-    "bin",
     "chips.json",
     "cmake.js",
     "discover.js",
@@ -51,8 +47,8 @@
   },
   "dependencies": {
     "esbuild": "^0.28.0",
-    "@mikrojs/native": "0.12.0",
-    "@mikrojs/quickjs": "0.12.0"
+    "@mikrojs/native": "0.14.0-pr-229.g0d8db1b",
+    "@mikrojs/quickjs": "0.14.0-pr-229.g0d8db1b"
   },
   "engines": {
     "node": ">=24.0.0"

package/sdkconfig.defaults

@@ -21,11 +21,11 @@ CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
 # Use -Os to reduce code size (less IRAM pressure, smaller function frames)
 CONFIG_COMPILER_OPTIMIZATION_SIZE=y
 
-# Move system functions from IRAM to flash (IRAM and DRAM share the same
-# SRAM on single-core chips like C3/C6, so freeing IRAM also frees DRAM)
+# Move heap functions from IRAM to flash (IRAM and DRAM share the same
+# SRAM on single-core chips like C3/C6, so freeing IRAM also frees DRAM).
+# FreeRTOS and esp_ringbuf functions are placed in flash by default since
+# ESP-IDF 6.0; their *_PLACE_FUNCTIONS_INTO_FLASH options were removed.
 CONFIG_HEAP_PLACE_FUNCTION_INTO_FLASH=y
-CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH=y
-CONFIG_RINGBUF_PLACE_FUNCTIONS_INTO_FLASH=y
 
 # Trade WiFi throughput for ~15-20KB IRAM savings. Fine for mikrojs
 # workloads (HTTP requests, small payloads — not high-throughput streaming).

package/bin/idf.py

@@ -1,7 +0,0 @@
-#!/bin/sh
-# Thin wrapper: runs idf.py via eim in the activated ESP-IDF environment.
-# Usage: idf.py <args>
-#   idf.py build
-#   idf.py set-target esp32c6
-#   idf.py build flash monitor
-exec eim run "idf.py $*"