DOCSEARCHbyAlgolia
Submit Docs

Kaluma JavaScript Runtime

repository·master·Indexed 21 days ago

https://github.com/kaluma-project/kaluma

A tiny, efficient JavaScript runtime for the RP2040 (Raspberry Pi Pico) microcontroller. Kaluma enables embedded development using ECMAScript 5/6+ standards and a Node.js-like asynchronous event loop. It features a small footprint (64KB RAM/300KB ROM), built-in modules for file systems (LittleFS, FAT), graphics, and networking, and supports RP2040 Programmable I/O (PIO) assembly directly within JavaScript. The runtime supports various targets including Raspberry Pi Pico, Adafruit KB2040, Waveshare RP2040 boards, and Kameleon Core (STM32).

Tokens
2.7K
Snippets
11
Records
23
Agent score
24%

What's inside Kaluma

  1. Overview of Kaluma JavaScript Runtime

    master

    Kaluma is a lightweight JavaScript runtime specifically designed for the RP2040 (Raspberry Pi Pico) microcontroller. It allows developers to write embedded applications using modern JavaScript (ECMAScript 5/6+) instead of C/C++.

    Key capabilities include:

    • Small Footprint: Optimized to run on microcontrollers with as little as 64KB RAM and 300KB ROM.
    • Asynchronous Programming: Features an internal event loop similar to Node.js.
    • Built-in Modules: Includes support for file systems (LittleFS, FAT), graphics, and networking.
    • PIO Support: Allows embedding RP2040 Programmable I/O (PIO) assembly directly within JavaScript code.
    • Familiar APIs: Provides APIs that resemble both Node.js and Arduino, making it easier for web and embedded developers to transition.

  3. Hardware Overview: Waveshare RP2040-Touch-LCD-1.28

    master

    The Waveshare RP2040-Touch-LCD-1.28 is an RP2040-based board featuring:

    • A round 1.28" SPI LCD.
    • Capacitive touch interface.
    • An IMU (Inertial Measurement Unit) connected via I2C/SPI.

    Note: The Kaluma board configuration only exposes generic MCU features and the filesystem. Peripherals like the LCD, touch, and IMU must be driven directly by your application code. There are currently no explicit LED or BUTTON pin constants defined in the board configuration.

  4. Flash partition layout for Raspberry Pi Pico

    master

    The Raspberry Pi Pico (RP2040) uses a 2MB flash memory divided into four distinct partitions. Understanding this layout is essential for managing firmware, user scripts, and data storage:

    • Partition A (1008K): Reserved for the Kaluma Binary (firmware).
    • Partition B (16K): Reserved for Storage (a key-value database).
    • Partition C (512K): Reserved for the User program (JavaScript files).
    • Partition D (512K): Reserved for the File system (LittleFS/lfs).

    The total flash capacity utilized is 2MB.

  5. Flash Partitioning on Adafruit KB2040

    master

    The KB2040 uses an 8 MB flash configuration with the following partition layout:

    PartitionPurposeSize / Details
    AFirmware1008 KB (KALUMA_BINARY_MAX=0xFC000)
    BStorage16 KB (KALUMA_STORAGE_SECTOR_BASE=0, COUNT=4)
    CUser Program512 KB (KALUMA_PROG_SECTOR_BASE=4, COUNT=128)
    DFilesystemRemainder of flash (auto-sized)

    On an 8 MB flash device, the filesystem (Partition D) is automatically sized to approximately 6.5 MiB (1664 sectors).

  6. Flash Partitioning for rp2040-pizero

    master

    The rp2040-pizero board uses a specific flash partitioning scheme designed for a 16 MB flash size (PICO_FLASH_SIZE_BYTES=16777216). The partitions are organized as follows:

    PartitionPurposeSize / Range
    AFirmware1008 KB (KALUMA_BINARY_MAX=0xFC000)
    BStorage16 KB (sectors 0–3)
    CUser Program512 KB (sectors 4–131)
    DFilesystemRemainder of flash (dynamically mounted)

    The filesystem (Partition D) is automatically sized to use the remaining flash space after partitions A, B, and C are allocated.

  7. Build for Waveshare RP2040-PiZero

    master

    You can build the Kaluma firmware for the Waveshare RP2040-PiZero using either CMake or the provided Node.js build script. The build process generates *.uf2 files which can be flashed to the board using the BOOTSEL method.

    # Using CMake
cmake -DTARGET=rp2 -DBOARD=rp2040-pizero

# Using Node.js build script
node build.js --target rp2 --board rp2040-pizero

  11. Structure a new target for Kaluma

    master

    To add support for a new hardware target, you must follow a specific directory structure within the targets/ directory. A target consists of source files, include headers, board definitions, and configuration files for both CMAKE and the Kaluma JavaScript environment.

    Required directory structure:

    • targets/<new-target>/include/: Contains header files.
    • targets/<new-target>/src/: Contains C implementation files. These must implement all headers found in include/port.
    • targets/<new-target>/boards/<new-board>/: Contains board-specific definitions.
    • targets/<new-target>/boards/<new-board>/board.h: The C header defining the board.
    • targets/<new-target>/target.cmake: The CMAKE configuration file for the target.
    • targets/<new-target>/board.js: The JavaScript configuration file for the board.
    targets/
  └─ <new-target>/
    ├─ include/
    │  └─ ...
    ├─ src/
    │  └─ ...
    ├─ boards/
    │  └─ <new-board>/
    │     └─ board.h
    ├─ target.cmake
    └─ board.js