Elk

A low footprint JavaScript engine for embedded systems

RuntimeIoT
cesanta/elk

README

Elk: a tiny JS engine for embedded systems

Build Status License: AGPL/Commercial Code Coverage


Elk is a tiny embeddable JavaScript engine that implements a small but usable
subset of ES6. It is designed for microcontroller development. Instead of
writing firmware code entirely in C/C++, Elk allows to add JavaScript
customisations to the firmware developed in C - which is a great way to let
customers to extend/customise device functionality.

Elk features include:

- Cross platform. Works anywhere from 8-bit microcontrollers to 64-bit servers
- Zero dependencies. Builds cleanly by ISO C or ISO C++ compilers
- Easy to embed: just copy elk.c and elk.h to your source tree
- Small and simple embedding API
- Does not use malloc. Operates with a given memory buffer only
- Small footprint: about 20KB on flash/disk, about 100 bytes RAM for core VM
- No bytecode. Interprets JS code directly

Elk approach is different from other scripting environments like micropython,
which provide a complete JS API for everything.  Elk is completely bare, it
does not even have a standard library. All required functionality is supposed
to be imported from C/C++ firmware, and JS code simply orchestrates things.
That leaves Elk very minimal and tunable.

Below is a blinky demonstration on a classic Arduino Nano board which has
2K RAM and 30K flash (see full sketch):

Elk on Arduino Nano


JavaScript on ESP32


The Esp32JS Arduino sketch is an example of Elk integration
with ESP32. Flash this sketch on your ESP32 board, go to http://elk-js.com,
and get a JavaScript development environment instantly! All components,
including ESP32 firmware and Web editor, are open.  Here how it looks like:

undefined

The example JS firmware implements a classic blinky that uses timers imported
from C.


Call JavaScript from C

  1. ```c
  2. #include <stdio.h>
  3. #include "elk.h"

  5. int main(void) {
  6.   char mem[200];
  7.   struct js *js = js_create(mem, sizeof(mem));  // Create JS instance
  8.   jsval_t v = js_eval(js, "1 + 2 * 3", ~0);     // Execute JS code
  9.   printf("result: %s\n", js_str(js, v));        // result: 7
  10.   return 0;
  11. }
  12. ```

Call C from JavaScript


This demonstrates how JS code can import and call existing C functions:

  1. ```c
  2. #include <stdio.h>
  3. #include "elk.h"

  5. // C function that adds two numbers. Will be called from JS
  6. jsval_t sum(struct js *js, jsval_t *args, int nargs) {
  7.   if (nargs != 2) return js_err(js, "2 args expected");
  8.   double a = js_getnum(args[0]);  // Fetch 1st arg
  9.   double b = js_getnum(args[1]);  // Fetch 2nd arg
  10.   return js_mknum(a + b);
  11. }

  13. int main(void) {
  14.   char mem[200];
  15.   struct js *js = js_create(mem, sizeof(mem));      // Create JS instance
  16.   js_set(js, js_glob(js), "sum", js_mkfun(sum)));   // Import sum()
  17.   jsval_t result = js_eval(js, "sum(3, 4);", ~0);   // Call sum
  18.   printf("result: %s\n", js_str(js, result));       // result: 7
  19.   return 0;
  20. }
  21. ```

Supported features


- Operations: all standard JS operations except:
   - !=, ==. Use strict comparison !==, ===
   - No computed member access a[b]
   - No exponentiation operation `a b`
- Typeof: typeof('a') === 'string'
- For loop: for (...;...;...)  ...
- Conditional: if (...) ... else ...
- Ternary operator a ? b : c
- Simple types: let a, b, c = 12.3, d = 'a', e = null, f = true, g = false;
- Functions: let f = function(x, y) { return x + y; };
- Objects: let obj = {f: function(x) { return x * 2}}; obj.f(3);
- Every statement must end with a semicolon ;
- Strings are binary data chunks, not Unicode strings: 'Київ'.length === 8

Not supported features


- No var, no const. Use let (strict mode only)
- No do, switch, while. Use for
- No => functions. Use let f = function(...) {...};
- No arrays, closures, prototypes, this, new, delete
- No standard library: no Date, Regexp, Function, String, Number

Performance


Since Elk parses and interprets JS code on the fly, it is not meant to be
used in a performance-critical scenarios. For example, below are the numbers
for a simple loop code on a different architectures.

  1. ``` js
  2. for (let i = 0; i < 100; i++) true;
  3. // 97 milliseconds on a 16Mhz 8-bit Atmega328P (Arduino Uno and alike)
  4. // 16 milliseconds on a 48Mhz SAMD21
  5. //  5 milliseconds on a 133Mhz Raspberry RP2040
  6. //  2 milliseconds on a 240Mhz ESP32
  7. ```

Build options


Available preprocessor definitions:

NameDefaultDescription
--------------------------------
|`JS_EXPR_MAX`20Maximum
|`JS_DUMP`undefinedDefine

Note: on ESP32 or ESP8266, compiled functions go into the .text ELF
section and subsequently into the IRAM MCU memory. It is possible to save
IRAM space by copying Elk code into the irom section before linking.
First, compile the object file, then rename .text section, e.g. for ESP32:

  1. ```sh
  2. $ xtensa-esp32-elf-gcc $CFLAGS elk.c -c elk.tmp
  3. $ xtensa-esp32-elf-objcopy --rename-section .text=.irom0.text elk.tmp elk.o
  4. ```

Note: Elk uses snprintf() standard function to format numbers (double).
On some architectures, for example AVR Arduino, that standard function does
not support float formatting - therefore printing numbers may output nothing
or ? symbols.

API reference


js\_create()


  1. ```c
  2. struct js *js_create(void *buf, size_t len);
  3. ```

Initialize JS engine in a given memory block. Elk will only use that memory
block to hold its runtime, and never use any extra memory.
Return: a non-NULL opaque pointer on success, or NULL when
len is too small. The minimum len is about 100 bytes.

The given memory buffer is laid out in the following way:
  1. ```
  2.   | <-------------------------------- len ------------------------------> |
  3.   | struct js, ~100 bytes  |   runtime vars    |    free memory           |
  4. ```

js\_eval()


  1. ```c
  2. jsval_t js_eval(struct js *, const char *buf, size_t len);
  3. ```

Evaluate JS code in buf, len and return result of the evaluation.  During
the evaluation, Elk stores variables in the "runtime" memory section. When
js_eval() returns, Elk does not keep any reference to the evaluated code: all
strings, functions, etc, are copied to the runtime.

Important note: the returned result is valid only before the next call to
js_eval(). The reason is that js_eval() triggers a garbage collection.
A garbage collection is mark-and-sweep, run before every top-level statement
gets executed.

The runtime footprint is as follows:
- An empty object is 8 bytes
- Each object property is 16 bytes
- A string is 4 bytes + string length, aligned to 4 byte boundary
- A C stack usage is ~200 bytes per nested expression evaluation


js\_str()


  1. ```c
  2. const char *js_str(struct js *, jsval_t val);
  3. ```

Stringify JS value val and return a pointer to a 0-terminated result.
The string is allocated in the "free" memory section. If there is no
enough space there, an empty string is returned. The returned pointer
is valid until the next js_eval() call.

js\_glob()


  1. ```c
  2. jsval_t js_glob(struct js *);
  3. ```

Return global JS object, i.e. a root namespace.


js\_mk\*()


  1. ```c
  2. jsval_t js_mkundef(void);  // Create undefined
  3. jsval_t js_mknull(void);   // Create null, null, true, false
  4. jsval_t js_mktrue(void);   // Create true
  5. jsval_t js_mkfalse(void);  // Create false
  6. jsval_t js_mkstr(struct js *, const void *, size_t);           // Create string
  7. jsval_t js_mknum(double);                                      // Create number
  8. jsval_t js_mkerr(struct js *js, const char *fmt, ...);         // Create error
  9. jsval_t js_mkfun(jsval_t (*fn)(struct js *, jsval_t *, int));  // Create func
  10. jsval_t js_mkobj(struct js *);                                 // Create object
  11. void js_set(struct js *, jsval_t, const char *, jsval_t);      // Set obj attr
  12. ```

Create JS values from C values

js\_get\*()


  1. ```c
  2. enum { JS_UNDEF, JS_NULL, JS_TRUE, JS_FALSE, JS_STR, JS_NUM, JS_ERR, JS_PRIV };
  3. int js_type(jsval_t val);       // Return JS value type
  4. double js_getnum(jsval_t val);  // Get number
  5. int js_getbool(jsval_t val);    // Get boolean, 0 or 1
  6. char *js_getstr(struct js *js, jsval_t val, size_t *len);  // Get string
  7. ```

Extract C values from JS values

js\_chkargs()


  1. ```c
  2. bool js_chkargs(jsval_t *args, int nargs, const char *spec);
  3. ```

A helper function that checks a validity of the arguments passed to a function.
A spec is a 0-terminated string where each character represents a type of
the expected argument: b for bool, d for number, s for string, j
for any other JS value.

Usage example - a C function that implements a JS function
greater_than(number1, number2):

  1. ```c
  2. static jsval_t js_gt(struct js *js, jsval_t *args, int nargs) {
  3.   if (!js_chkargs(args, nargs, "dd")) return js_mkerr(js, "bad args!");
  4.   return js_getnum(args[0]) > js_getnum(args[1]) ? js_mktrue() : js_mkfalse();
  5. }
  6. ```

js\_setmaxcss()


  1. ```c
  2. void js_setmaxcss(struct js *, size_t max);
  3. ```

Set maximum allowed C stack size usage

js\_stats()


  1. ```c
  2. void js_stats(struct js *, size_t *total, size_t *min, size_t *cstacksize);
  3. ```

Return resource usage statistics: total for total usable JS memory, min
for the lowest free JS memory observed (low watermark), and cstacksize for
the largest C stack usage observed.

js\_dump()


  1. ```c
  2. void js_dump(struct js *);
  3. ```

Print debug info about the current JS state to stdout. Requires -DJS_DUMP

LICENSE


Dual license: AGPLv3 or commercial. For commercial licensing, technical support
and integration help, please contact us at https://cesanta.com/contact.html