mirror
/
micropython
kopia lustrzana https://github.com/micropython/micropython
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

webassembly: Update README.md to describe latest changes. 

Signed-off-by: Damien George <damien@micropython.org>
pull/13583/head
Damien George 2024-03-06 10:27:54 +11:00
rodzic b9eb74e73b
commit 26d6969fef
1 zmienionych plików z 96 dodań i 51 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

147
ports/webassembly/README.md
Wyświetl plik

@ -6,22 +6,22 @@ MicroPython for [WebAssembly](https://webassembly.org/).
Dependencies Dependencies
------------ ------------
Building webassembly port bears the same requirements as the standard Building the webassembly port bears the same requirements as the standard
MicroPython ports with the addition of Emscripten (and uglify-js for the MicroPython ports with the addition of Emscripten, and optionally terser for
minified file). the minified file.
The output includes `micropython.js` (a JavaScript wrapper for the The output includes `micropython.mjs` (a JavaScript wrapper for the
MicroPython runtime) and `firmware.wasm` (actual MicroPython compiled to MicroPython runtime) and `micropython.wasm` (actual MicroPython compiled to
WASM). WASM).
Build instructions Build instructions
------------------ ------------------
In order to build micropython.js, run: In order to build `micropython.mjs`, run:
$ make $ make
To generate the minified file micropython.min.js, run: To generate the minified file `micropython.min.mjs`, run:
$ make min $ make min
@ -30,55 +30,90 @@ Running with Node.js
Access the repl with: Access the repl with:
$ node build/micropython.js $ make repl
Stack size may be modified using: This is the same as running:
$ node build/micropython.js -X stack=64K $ node build-standard/micropython.mjs
Where stack size may be represented in Bytes, KiB or MiB. The initial MicroPython GC heap size may be modified using:
$ node build-standard/micropython.mjs -X heapsize=64k
Where stack size may be represented in bytes, or have a `k` or `m` suffix.
MicroPython scripts may be executed using: MicroPython scripts may be executed using:
$ node build/micropython.js hello.py $ node build-standard/micropython.mjs hello.py
Alternatively micropython.js may by accessed by other javascript programs in node Alternatively `micropython.mjs` may by accessed by other JavaScript programs in node
using the require command and the general API outlined below. For example: using the require command and the general API outlined below. For example:
```javascript ```javascript
var mp_js = require('./build/micropython.js'); const mp_mjs = await import("micropython.mjs");
const mp = await mp_mjs.loadMicroPython();
mp_js_init(64 * 1024); mp.runPython("print('hello world')");
await mp_js_do_str("print('hello world')\n"); ```
Or without await notation:
```javascript
import("micropython.mjs").then((mp_mjs) => {
mp_mjs.loadMicroPython().then((mp) => {
mp.runPython("print('hello world')");
});
});
``` ```
Running with HTML Running with HTML
----------------- -----------------
The prerequisite for browser operation of micropython.js is to listen to the The following code demonstrates the simplest way to load `micropython.mjs` in a
`micropython-print` event, which is passed data when MicroPython code prints browser, create an interpreter context, and run some Python code:
something to stdout. The following code demonstrates basic functionality:
```html ```html
<!doctype html> <!doctype html>
<html> <html>
<head> <head>
<script src="build/micropython.js"></script> <script src="build-standard/micropython.mjs" type="module"></script>
</head>
<body>
<script type="module">
const mp = await loadMicroPython();
mp.runPython("print('hello world')");
</script>
</body>
</html>
```
The output in the above example will go to the JavaScript console. It's possible
to instead capture the output and print it somewhere else, for example in an
HTML element. The following example shows how to do this, and also demonstrates
the use of top-level await and the `js` module:
```html
<!doctype html>
<html>
<head>
<script src="build-standard/micropython.mjs" type="module"></script>
</head> </head>
<body> <body>
<pre id="micropython-stdout"></pre> <pre id="micropython-stdout"></pre>
<script> <script type="module">
document.addEventListener("micropython-print", function(e) { const stdoutWriter = (line) => {
let output = document.getElementById("micropython-stdout"); document.getElementById("micropython-stdout").innerText += line + "\n";
output.innerText += new TextDecoder().decode(e.detail);
}, false);
var mp_js_startup = Module["onRuntimeInitialized"];
Module["onRuntimeInitialized"] = async function() {
mp_js_startup();
mp_js_init(64 * 1024);
await mp_js_do_str("print('hello world')");
}; };
const mp = await loadMicroPython({stdout:stdoutWriter});
await mp.runPythonAsync(`
import js
url = "https://api.github.com/users/micropython"
print(f"fetching {url}...")
res = await js.fetch(url)
json = await res.json()
for i in dir(json):
print(f"{i}: {json[i]}")
`);
</script> </script>
</body> </body>
</html> </html>
@ -98,31 +133,41 @@ Run the test suite using:
API API
--- ---
The following functions have been exposed to javascript. The following functions have been exposed to JavaScript through the interpreter
context, created and returned by `loadMicroPython()`.
``` - `PyProxy`: the type of the object that proxies Python objects.
mp_js_init(stack_size)
```
Initialize MicroPython with the given stack size in bytes. This must be - `FS`: the Emscripten filesystem object.
called before attempting to interact with MicroPython.
``` - `globals`: an object exposing the globals from the Python `__main__` module,
await mp_js_do_str(code) with methods `get(key)`, `set(key, value)` and `delete(key)`.
```
Execute the input code. `code` must be a `string`. - `registerJsModule(name, module)`: register a JavaScript object as importable
from Python with the given name.
``` - `pyimport`: import a Python module and return it.
mp_js_init_repl()
```
Initialize MicroPython repl. Must be called before entering characters into - `runPython(code)`: execute Python code and return the result.
the repl.
``` - `runPythonAsync(code)`: execute Python code and return the result, allowing for
await mp_js_process_char(char) top-level await expressions (this call must be await'ed on the JavaScript side).
```
Input character into MicroPython repl. `char` must be of type `number`. This - `replInit()`: initialise the REPL.
will execute MicroPython code when necessary.
- `replProcessChar(chr)`: process an incoming character at the REPL.
- `replProcessCharWithAsyncify(chr)`: process an incoming character at the REPL,
for use when ASYNCIFY is enabled.
Proxying
--------
A Python `dict` instance is proxied such that:
for (const key in dict) {
print(key, dict[key]);
}
works as expected on the JavaScript side and iterates through the keys of the
Python `dict`.