circuitpython/ports/webassembly
Damien George 5987130afd webassembly/Makefile: Change compiler optimisation from O3 to Os.
Emscripten strongly advises the use of optimisation when compiling with
ASYNCIFY enabled.  Testing the difference betwen O3 and Os for various
configurations gives:

    flags                      firmware.wasm   micropython.js  perf
    -O3 -s ASYNCIFY            1342003          212845         0 (baseline)
    -O3 -s ASYNCIFY -s WASM=0        -         7064750         -30%
    -O3                         367131          196569         +140%
    -O3 -s WASM=0                    -         2818260         +30%
    -Os -s ASYNCIFY            1135450          213064         +40%
    -Os -s ASYNCIFY -s WASM=0        -         6239768         -30%
    -Os                         295028          196569         +180%
    -Os -s WASM=0                    -         2271358         +30%

The first row is prior to this commit.  The second and third columns show
firmware size (add them to get the total size).  The fourth column shows
the approximate change in performance compared to the baseline.  The
performance was measured using run-perfbench.py and the error was large, up
to 20%, although general trends in the change in performance could still be
seen.

In summary, using using Os instead of O3 makes it a little bit faster in
all cases, and smaller output (wasm/js) in all cases.

Signed-off-by: Damien George <damien@micropython.org>
2022-11-07 17:18:42 +11:00
..
Makefile webassembly/Makefile: Change compiler optimisation from O3 to Os. 2022-11-07 17:18:42 +11:00
README.md webassembly/README: Update README to describe new stdout behaviour. 2022-11-07 17:18:31 +11:00
library.h javascript: Rename this port to 'webassembly'. 2022-08-22 12:03:39 +01:00
library.js webassembly: Dispatch micropython-print via document not mp_js_stdout. 2022-11-07 15:09:56 +11:00
main.c webassembly: Add support for VFS and enable VFS_POSIX. 2022-11-01 13:53:06 +11:00
modutime.c javascript: Rename this port to 'webassembly'. 2022-08-22 12:03:39 +01:00
mpconfigport.h webassembly: Add support for VFS and enable VFS_POSIX. 2022-11-01 13:53:06 +11:00
mphalport.c javascript: Rename this port to 'webassembly'. 2022-08-22 12:03:39 +01:00
mphalport.h webassembly: Add support for VFS and enable VFS_POSIX. 2022-11-01 13:53:06 +11:00
node_run.sh javascript: Rename this port to 'webassembly'. 2022-08-22 12:03:39 +01:00
qstrdefsport.h javascript: Rename this port to 'webassembly'. 2022-08-22 12:03:39 +01:00
wrapper.js webassembly: Support piping in a program on stdin. 2022-11-03 23:35:22 +11:00

README.md

MicroPython WebAssembly

MicroPython for WebAssembly.

Dependencies

Building webassembly port bears the same requirements as the standard MicroPython ports with the addition of Emscripten (and uglify-js for the minified file).

The output includes micropython.js (a JavaScript wrapper for the MicroPython runtime) and firmware.wasm (actual MicroPython compiled to WASM).

Build instructions

In order to build micropython.js, run:

$ make

To generate the minified file micropython.min.js, run:

$ make min

Running with Node.js

Access the repl with:

$ node build/micropython.js

Stack size may be modified using:

$ node build/micropython.js -X stack=64K

Where stack size may be represented in Bytes, KiB or MiB.

MicroPython scripts may be executed using:

$ node build/micropython.js hello.py

Alternatively micropython.js may by accessed by other javascript programs in node using the require command and the general API outlined below. For example:

var mp_js = require('./build/micropython.js');

mp_js_init(64 * 1024);
mp_js_do_str("print('hello world')\n");

Running with HTML

The prerequisite for browser operation of micropython.js is to listen to the micropython-print event, which is passed data when MicroPython code prints something to stdout. The following code demonstrates basic functionality:

<!doctype html>
<html>
  <head>
    <script src="build/micropython.js"></script>
  </head>
  <body>
    <pre id="micropython-stdout"></pre>
    <script>
      document.addEventListener("micropython-print", function(e) {
        let output = document.getElementById("micropython-stdout");
        output.innerText += e.data;
      }, false);

      var mp_js_startup = Module["onRuntimeInitialized"];
      Module["onRuntimeInitialized"] = async function() {
        mp_js_startup();
        mp_js_init(64 * 1024);
        mp_js_do_str("print('hello world')");
      };
    </script>
  </body>
</html>

MicroPython code execution will suspend the browser so be sure to atomize usage within this environment. Unfortunately interrupts have not been implemented for the browser.

Testing

Run the test suite using:

$ make test

API

The following functions have been exposed to javascript.

mp_js_init(stack_size)

Initialize MicroPython with the given stack size in bytes. This must be called before attempting to interact with MicroPython.

mp_js_do_str(code)

Execute the input code. code must be a string.

mp_js_init_repl()

Initialize MicroPython repl. Must be called before entering characters into the repl.

mp_js_process_char(char)

Input character into MicroPython repl. char must be of type number. This will execute MicroPython code when necessary.