@mikrojs/firmware 0.0.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Bjørge Næss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# @mikrojs/firmware
+
+ESP32 firmware package for Mikro.js. Provides the ESP-IDF integration, build system, and platform-specific modules (GPIO, WiFi, HTTP, etc.) needed to run Mikro.js on ESP32 chips.
+
+## What's included
+
+- **`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`:
+
+```
+my-firmware/
+├── package.json          # depends on @mikrojs/firmware
+├── CMakeLists.txt        # include($ENV{MIKROJS_PROJECT_CMAKE})
+└── main/
+    ├── CMakeLists.txt
+    └── main.cpp          # calls MIK_Main()
+```
+
+See the [Custom Firmware](https://mikrojs.dev/develop/custom-firmware) docs for details.
+
+## Requirements
+
+- Node.js >= 24
+- ESP-IDF >= 6.0 (installed via [EIM](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/index.html))

package/bin/idf.py

@@ -0,0 +1,7 @@
+#!/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 $*"

package/chips.json

@@ -0,0 +1,3 @@
+{
+  "chips": ["esp32", "esp32c3", "esp32c6", "esp32s3"]
+}

package/cmake.js

@@ -0,0 +1,9 @@
+import {dirname, join} from 'node:path'
+import {fileURLToPath} from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+// EXTRA_COMPONENT_DIRS expects directories containing component subdirectories.
+// ESP-IDF scans this and finds the mikrojs/ subdirectory as a component.
+export const componentDir = join(__dirname, 'components')
+export const projectCmakePath = join(__dirname, 'project.cmake')

package/components/mikrojs/CMakeLists.txt

@@ -0,0 +1,187 @@
+# ── Resolve package paths via Node.js ────────────────────────────────
+# 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)
+#   - External: CMAKE_SOURCE_DIR is the user's project root
+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}")
+
+# nanocbor lives inside the native package
+set(MIK_NANOCBOR_DIR "${MIK_SRC_DIR}/../deps/nanocbor")
+
+# BLE sources and the `ble` native module only compile when NimBLE is
+# available. Test builds disable Bluetooth via `CONFIG_BT_ENABLED=n` in
+# their sdkconfig.defaults, so this component has to skip BLE there.
+set(_MIK_BLE_SRCS "")
+if(CONFIG_BT_ENABLED)
+    list(APPEND _MIK_BLE_SRCS "mik_ble.cpp" "mik_ble_c_shim.c")
+endif()
+
+idf_component_register(
+    INCLUDE_DIRS "include" "${MIK_INCLUDE_DIR}"
+    REQUIRES bt littlefs esp_adc esp_app_format esp_driver_gpio esp_driver_i2c esp_driver_ledc esp_driver_rmt esp_driver_spi esp_psram esp_timer esp_http_client esp-tls esp_netif esp_event esp_wifi nvs_flash esp_driver_uart esp_driver_usb_serial_jtag spi_flash
+    SRCS
+    # QuickJS engine
+    ${QUICKJS_SOURCES}
+    # Standalone library portable sources
+    "${MIK_SRC_DIR}/cutils_compat.c"
+    "${MIK_SRC_DIR}/builtins.cpp"
+    "${MIK_SRC_DIR}/eval_bytecode.cpp"
+    "${MIK_SRC_DIR}/mik_abort.cpp"
+    "${MIK_SRC_DIR}/fs.cpp"
+    "${MIK_SRC_DIR}/mem.cpp"
+    "${MIK_SRC_DIR}/mik_app_config.cpp"
+    "${MIK_SRC_DIR}/mik_color.cpp"
+    "${MIK_SRC_DIR}/mik_console.cpp"
+    "${MIK_SRC_DIR}/mik_inspect.cpp"
+    "${MIK_SRC_DIR}/mik_repl.cpp"
+    "${MIK_SRC_DIR}/mik_stdio.cpp"
+    "${MIK_SRC_DIR}/mik_sys.cpp"
+    "${MIK_SRC_DIR}/mik_text_encoding.cpp"
+    "${MIK_SRC_DIR}/mik_cbor.cpp"
+    "${MIK_SRC_DIR}/mik_result.cpp"
+    "${MIK_SRC_DIR}/mikrojs.cpp"
+    # nanocbor CBOR codec
+    "${MIK_NANOCBOR_DIR}/src/encoder.c"
+    "${MIK_NANOCBOR_DIR}/src/decoder.c"
+    "${MIK_SRC_DIR}/modules.cpp"
+    "${MIK_SRC_DIR}/timers.cpp"
+    "${MIK_SRC_DIR}/utils.cpp"
+    # ESP32 platform implementation (replaces platform_posix.cpp)
+    "platform_esp32.cpp"
+    # Default firmware entry point
+    "mik_main.cpp"
+    # ESP32-specific modules and protocols
+    ${_MIK_BLE_SRCS}
+    "mik_config.cpp"
+    "mik_deploy.cpp"
+    "mik_http.cpp"
+    "mik_i2c.cpp"
+    "mik_neopixel.cpp"
+    "mik_pin.cpp"
+    "mik_pwm.cpp"
+    "mik_nvs_kv.cpp"
+    "mik_recovery.cpp"
+    "mik_rtc.cpp"
+    "mik_serial_io.cpp"
+    "mik_sleep.cpp"
+    "mik_spi.cpp"
+    "mik_sntp.cpp"
+    "mik_uart.cpp"
+    "mik_wifi.cpp"
+)
+
+# QuickJS headers as SYSTEM includes (suppresses warnings)
+target_include_directories(${COMPONENT_LIB} SYSTEM PUBLIC "${QUICKJS_INCLUDE_DIR}")
+# nanocbor headers
+target_include_directories(${COMPONENT_LIB} PRIVATE "${MIK_NANOCBOR_DIR}/include")
+target_compile_options(${COMPONENT_LIB} PUBLIC $<$<COMPILE_LANGUAGE:CXX>:-fpermissive>)
+# -fno-strict-aliasing: see comment in quickjs.cmake. Applied component-wide
+# (same posture as the Linux kernel) so neither QuickJS sources nor our
+# own C/C++ can be bitten by aliasing UB during optimization.
+target_compile_options(${COMPONENT_LIB} PRIVATE -Wno-implicit-fallthrough -Wno-maybe-uninitialized -Wno-missing-field-initializers -fno-strict-aliasing)
+
+# ── 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}\"")
+
+# UTC build timestamp. `string(TIMESTAMP ... UTC)` honors SOURCE_DATE_EPOCH
+# when set. Refreshes on re-configure only (idf.py triggers this on each
+# 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}\"")
+
+# Board name from MIKROJS_BOARD env var (set by CI or developer)
+if(DEFINED ENV{MIKROJS_BOARD})
+    target_compile_definitions(${COMPONENT_LIB} PRIVATE "MIK_BOARD_NAME=\"$ENV{MIKROJS_BOARD}\"")
+endif()
+
+# ── Bytecode generation ──────────────────────────────────────────────
+include("${MIK_BYTECODE_CMAKE}")
+
+# Force linker to include self-registering native modules
+set(_MIK_MODULES cbor pin i2c spi http wifi rtc nvs_kv sntp sleep neopixel pwm uart)
+set(_MIK_BYTECODE_MODULES cbor env result schema fs http/helpers http/request i2c kv/nvs kv/rtc kv/shared neopixel pin pwm reader sleep spi sntp stdio stream sys test uart wifi)
+if(CONFIG_BT_ENABLED)
+    list(APPEND _MIK_MODULES ble)
+    list(APPEND _MIK_BYTECODE_MODULES ble)
+endif()
+mikrojs_force_include_modules(${_MIK_MODULES})
+mikrojs_generate_bytecode(
+    RUNTIME_DIR "${MIK_RUNTIME_DIR}"
+    MODULES ${_MIK_BYTECODE_MODULES}
+    MODULE_PREFIX "mikrojs"
+    SYMBOL_PREFIX "mikrojs"
+    TARGET gen_bytecode
+    WORKING_DIRECTORY "${MIKROJS_PROJECT_DIR}"
+)
+add_dependencies(${COMPONENT_LIB} gen_bytecode)
+target_include_directories(${COMPONENT_LIB} PRIVATE "${gen_bytecode_INCLUDE_DIR}")
+
+# ── Symbol map for offline panic-trace decoding ──────────────────────
+# Runs after the ELF is linked. Toolchain prefix derived from the C
+# compiler path so this works for any binutils target (xtensa, riscv,
+# arm — anything a future port might add).
+get_filename_component(_MIK_TC_DIR "${CMAKE_C_COMPILER}" DIRECTORY)
+get_filename_component(_MIK_TC_NAME "${CMAKE_C_COMPILER}" NAME)
+string(REGEX REPLACE "gcc(\\.exe)?$" "" _MIK_TC_NAME_PREFIX "${_MIK_TC_NAME}")
+set(_MIK_TC_PREFIX "${_MIK_TC_DIR}/${_MIK_TC_NAME_PREFIX}")
+
+# The ${project}.elf target is created by ESP-IDF inside `project()`, in the
+# source-root CMake scope. Component CMakeLists run before that target
+# exists, so defer to end-of-source-dir processing. cmake_language(DEFER)
+# expands ${...} args in the *target* directory's scope at fire time, so
+# component-local variables won't survive — stash them as GLOBAL properties
+# and read them back inside the deferred function.
+set_property(GLOBAL PROPERTY MIKROJS_TOOLCHAIN_PREFIX "${_MIK_TC_PREFIX}")
+set_property(GLOBAL PROPERTY MIKROJS_SCRIPTS_DIR "${MIK_SCRIPTS_DIR}")
+
+function(_mik_install_symbol_map_hook)
+    get_property(tc_prefix GLOBAL PROPERTY MIKROJS_TOOLCHAIN_PREFIX)
+    get_property(scripts_dir GLOBAL PROPERTY MIKROJS_SCRIPTS_DIR)
+    idf_build_get_property(project_name PROJECT_NAME)
+    idf_build_get_property(target IDF_TARGET)
+    add_custom_command(
+        TARGET "${project_name}.elf" POST_BUILD
+        COMMAND node "${scripts_dir}/generate-symbol-map.js"
+            "$<TARGET_FILE:${project_name}.elf>"
+            "${CMAKE_BINARY_DIR}/${project_name}.symbols.json"
+            "${tc_prefix}"
+            "${target}"
+        BYPRODUCTS "${CMAKE_BINARY_DIR}/${project_name}.symbols.json"
+        COMMENT "Generating symbol map for panic-trace decoding"
+        VERBATIM
+    )
+endfunction()
+
+cmake_language(DEFER DIRECTORY "${CMAKE_SOURCE_DIR}"
+    CALL _mik_install_symbol_map_hook)

package/components/mikrojs/Kconfig

@@ -0,0 +1,55 @@
+menu "mikrojs console"
+
+    config MIKROJS_CONSOLE_FALLBACK_UART
+        bool "Install UART0 as fallback console on chips with USB-Serial/JTAG"
+        default n
+        depends on SOC_USB_SERIAL_JTAG_SUPPORTED
+        help
+            When enabled, mikrojs brings up both USB-Serial/JTAG and UART0
+            at boot and latches to whichever receives the first byte.
+            Convenient for dev: plug in either cable type and it just
+            works. Costs ~4 KB DRAM (UART RX ring buffer), a UART ISR
+            in IRAM, and keeps UART0 clocks powered — meaningful on
+            RAM-constrained apps (e.g. ones that push large SPI DMA
+            frames and already run the system heap close to full).
+
+            Defaults off to keep RAM available for the application.
+            Enable if you want the auto-detect dev experience on a board
+            where you sometimes connect a USB-TTL adapter instead of
+            (or in addition to) the native USB port. On chips without
+            USB-Serial/JTAG hardware (plain ESP32), UART0 is always
+            installed regardless of this option.
+
+endmenu
+
+menu "mikrojs Test Configuration"
+
+    config MIKROJS_TEST_GPIO_PIN
+        int "GPIO pin for output/input tests"
+        default 15 if IDF_TARGET_ESP32C6
+        default 8 if IDF_TARGET_ESP32C3
+        default 2
+        help
+            GPIO pin used by the hardware test suite for digital write/read tests.
+            Should be a safe, general-purpose pin on the target board (ideally an LED).
+
+    config MIKROJS_TEST_PWM_PIN
+        int "GPIO pin for PWM/LEDC tests"
+        default 15 if IDF_TARGET_ESP32C6
+        default 8 if IDF_TARGET_ESP32C3
+        default 2
+        help
+            GPIO pin used by the hardware test suite for PWM (LEDC) tests.
+            Should be a safe, general-purpose pin on the target board (ideally an LED).
+
+    config MIKROJS_TEST_ADC_PIN
+        int "GPIO pin for ADC tests"
+        default 0 if IDF_TARGET_ESP32C6
+        default 0 if IDF_TARGET_ESP32C3
+        default 1 if IDF_TARGET_ESP32S3
+        default 34
+        help
+            GPIO pin used by the hardware test suite for ADC read tests.
+            Must be connected to an ADC1 channel on the target chip.
+
+endmenu

package/components/mikrojs/idf_component.yml

@@ -0,0 +1,6 @@
+## IDF Component Manager Manifest File
+dependencies:
+  ## Required IDF version
+  idf:
+    version: '>=5.5.3'
+  joltwallet/littlefs: '>=1.19.1'

package/components/mikrojs/include/mem.h

@@ -0,0 +1,3 @@
+/* Backward-compatible header — forwards to standalone library */
+#pragma once
+#include <mikrojs/mem.h>

package/components/mikrojs/include/mik_color.h

@@ -0,0 +1,3 @@
+/* Backward-compatible header — forwards to standalone library */
+#pragma once
+#include <mikrojs/mik_color.h>

package/components/mikrojs/include/mik_http_internal.h

@@ -0,0 +1,77 @@
+/* Internal HTTP module layout shared with on-device tests.
+ * Included by mik_http.cpp and test/http_test.cpp so struct changes can't
+ * drift silently between the implementation and its mirror. */
+#pragma once
+
+#include <atomic>
+#include <cstdint>
+#include <cstdlib>
+
+#include "freertos/FreeRTOS.h"
+#include "freertos/queue.h"
+#include "freertos/semphr.h"
+#include "utils.h"
+
+struct MIKHttpHeader {
+    char* key;
+    char* value;
+};
+
+enum MIKHttpMsgKind : uint8_t {
+    MIK_HTTP_MSG_HEADERS,
+    MIK_HTTP_MSG_CHUNK,
+    MIK_HTTP_MSG_END,
+    MIK_HTTP_MSG_ERROR,
+};
+
+struct MIKHttpMsg {
+    uint32_t id;
+    MIKHttpMsgKind kind;
+    /* HEADERS */
+    int status;
+    MIKHttpHeader* headers;
+    size_t header_count;
+    /* CHUNK */
+    uint8_t* chunk_data;
+    size_t chunk_len;
+    /* ERROR */
+    bool is_cancelled;
+    char* error_message;
+};
+
+struct MIKHttpQueuedMsg {
+    MIKHttpMsgKind kind;
+    uint8_t* chunk_data;
+    size_t chunk_len;
+    bool is_cancelled;
+    char* error_message;
+    MIKHttpQueuedMsg* next;
+};
+
+struct MIKHttpPending {
+    uint32_t id;
+    std::atomic<bool>* cancelled;
+    bool js_cancelled;
+
+    MIKPromise headers_promise;
+    bool headers_resolved;
+
+    MIKPromise next_promise;
+    bool next_promise_active;
+
+    MIKHttpQueuedMsg* queue_head;
+    MIKHttpQueuedMsg* queue_tail;
+};
+
+/* Ceilings shared with the test harness. Must match the #defines in
+ * mik_http.cpp. */
+#define MIK_HTTP_MAX_PENDING 4
+#define MIK_HTTP_MAX_CHUNKS_INFLIGHT 8
+
+struct MIKHttpState {
+    QueueHandle_t result_queue;
+    SemaphoreHandle_t inflight;
+    MIKHttpPending pending[MIK_HTTP_MAX_PENDING];
+    size_t pending_count = 0;
+    uint32_t next_id = 1;
+};

package/components/mikrojs/include/mikrojs.h

@@ -0,0 +1,5 @@
+/* Backward-compatible header — includes both the standalone library API
+ * and ESP32-specific extensions. */
+#pragma once
+#include <mikrojs/mikrojs.h>
+#include "mikrojs_esp32.h"

package/components/mikrojs/include/mikrojs_esp32.h

@@ -0,0 +1,65 @@
+/* ESP32-specific extensions to the mikrojs public API.
+ * Include this alongside <mikrojs/mikrojs.h> for deploy, config, and serial I/O. */
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct MIKRuntime MIKRuntime;
+
+/* Default firmware entry point (mik_main.cpp).
+ * Sets up console, NVS, LittleFS, JS runtime, and enters the event loop
+ * with REPL, deploy, and config protocol support. */
+void MIK_Main(void);
+
+/* Deploy recovery (mik_deploy.cpp) */
+void MIK_DeployRecover(void);
+
+/* Safe-mode recovery window (mik_recovery.cpp).
+ * Opens a brief window (typ. 500ms) right after console init that watches
+ * for two triggers and returns true if either fires:
+ *   1) Double-reset: an RTC_NOINIT magic word survives a soft reset that
+ *      happens while the window is armed.
+ *   2) Sync bytes: the host sends "MIKSAFE\n" over the console transport
+ *      (mikro console --recover toggles RTS to reset and then floods this).
+ * When true, the firmware should skip user-app autorun and drop to REPL. */
+bool mik__check_recovery(int timeout_ms);
+
+/* Console auto-detection (mik_serial_io.cpp).
+ * On chips with USB Serial/JTAG, detects whether USB or UART is connected
+ * and sets up the active console accordingly. Must be called early in app_main(). */
+void mik__console_init(void);
+
+/* Read from the active console.  Returns bytes read, 0 if no data, or -1. */
+int mik__console_read(void* buf, size_t len);
+
+/* Write to the active console.  Returns bytes written. */
+int mik__console_write(const void* buf, size_t len);
+
+/* Serial binary I/O (mik_serial_io.cpp) */
+void mik__serial_binary_begin_no_echo(void);
+
+/* Shared NVS helpers (mik_serial_io.cpp) */
+extern const char* MIK__NVS_NS_ENV;  /* env var values */
+extern const char* MIK__NVS_NS_SEC;  /* secret-flag markers (u8) */
+/* ENV_FLAG_SECRET is defined in mikrojs/private.h as MIK_ENV_FLAG_SECRET */
+void mik__nvs_clear_namespace(const char* ns);
+bool mik__nvs_put_string(const char* ns, const char* key, const char* value);
+bool mik__nvs_put_string_if_diff(const char* ns, const char* key, const char* value,
+                                 bool* out_changed);
+bool mik__nvs_is_secret(const char* key);
+bool mik__nvs_set_secret_flag(const char* key, bool secret);
+bool mik__nvs_env_set(const char* key, const char* value, bool secret, bool* out_changed);
+bool mik__nvs_env_delete(const char* key);
+
+/* Read NVS env vars and register them with the runtime via MIK_SetEnvVar() */
+void MIK_LoadEnvFromNVS(MIKRuntime* mik_rt);
+
+#ifdef __cplusplus
+}
+#endif

package/components/mikrojs/include/private.h

@@ -0,0 +1,10 @@
+/* Backward-compatible header — forwards to standalone library
+ * and adds ESP32-specific declarations. */
+#pragma once
+#include <mikrojs/private.h>
+#include "mikrojs_esp32.h"
+
+/* Forward declarations for ESP32 module state types (needed by inline accessors
+ * that appear before the full struct definitions in their respective .cpp files). */
+struct MIKHttpState;
+struct MIKWifiState;

package/components/mikrojs/include/utils.h

@@ -0,0 +1,3 @@
+/* Backward-compatible header — forwards to standalone library */
+#pragma once
+#include <mikrojs/utils.h>