Skip to content

Commit 26d6969

Browse files
dpgeorgedpgeorge
committed
webassembly: Update README.md to describe latest changes.
Signed-off-by: Damien George <[email protected]>
1 parent b9eb74e commit 26d6969

File tree

1 file changed

+96
-51
lines changed

1 file changed

+96
-51
lines changed

Diff for: ‎ports/webassembly/README.md

+96-51
Original file line numberDiff line numberDiff line change
@@ -6,22 +6,22 @@ MicroPython for [WebAssembly](https://webassembly.org/).
66
Dependencies
77
------------
88

9-
Building webassembly port bears the same requirements as the standard
10-
MicroPython ports with the addition of Emscripten (and uglify-js for the
11-
minified file).
9+
Building the webassembly port bears the same requirements as the standard
10+
MicroPython ports with the addition of Emscripten, and optionally terser for
11+
the minified file.
1212

13-
The output includes `micropython.js` (a JavaScript wrapper for the
14-
MicroPython runtime) and `firmware.wasm` (actual MicroPython compiled to
13+
The output includes `micropython.mjs` (a JavaScript wrapper for the
14+
MicroPython runtime) and `micropython.wasm` (actual MicroPython compiled to
1515
WASM).
1616

1717
Build instructions
1818
------------------
1919

20-
In order to build micropython.js, run:
20+
In order to build `micropython.mjs`, run:
2121

2222
$ make
2323

24-
To generate the minified file micropython.min.js, run:
24+
To generate the minified file `micropython.min.mjs`, run:
2525

2626
$ make min
2727

@@ -30,55 +30,90 @@ Running with Node.js
3030

3131
Access the repl with:
3232

33-
$ node build/micropython.js
33+
$ make repl
3434

35-
Stack size may be modified using:
35+
This is the same as running:
3636

37-
$ node build/micropython.js -X stack=64K
37+
$ node build-standard/micropython.mjs
3838

39-
Where stack size may be represented in Bytes, KiB or MiB.
39+
The initial MicroPython GC heap size may be modified using:
40+
41+
$ node build-standard/micropython.mjs -X heapsize=64k
42+
43+
Where stack size may be represented in bytes, or have a `k` or `m` suffix.
4044

4145
MicroPython scripts may be executed using:
4246

43-
$ node build/micropython.js hello.py
47+
$ node build-standard/micropython.mjs hello.py
4448

45-
Alternatively micropython.js may by accessed by other javascript programs in node
49+
Alternatively `micropython.mjs` may by accessed by other JavaScript programs in node
4650
using the require command and the general API outlined below. For example:
4751

4852
```javascript
49-
var mp_js = require('./build/micropython.js');
53+
const mp_mjs = await import("micropython.mjs");
54+
const mp = await mp_mjs.loadMicroPython();
55+
56+
mp.runPython("print('hello world')");
57+
```
5058

51-
mp_js_init(64 * 1024);
52-
await mp_js_do_str("print('hello world')\n");
59+
Or without await notation:
60+
61+
```javascript
62+
import("micropython.mjs").then((mp_mjs) => {
63+
mp_mjs.loadMicroPython().then((mp) => {
64+
mp.runPython("print('hello world')");
65+
});
66+
});
5367
```
5468

5569
Running with HTML
5670
-----------------
5771

58-
The prerequisite for browser operation of micropython.js is to listen to the
59-
`micropython-print` event, which is passed data when MicroPython code prints
60-
something to stdout. The following code demonstrates basic functionality:
72+
The following code demonstrates the simplest way to load `micropython.mjs` in a
73+
browser, create an interpreter context, and run some Python code:
74+
75+
```html
76+
<!doctype html>
77+
<html>
78+
<head>
79+
<script src="build-standard/micropython.mjs" type="module"></script>
80+
</head>
81+
<body>
82+
<script type="module">
83+
const mp = await loadMicroPython();
84+
mp.runPython("print('hello world')");
85+
</script>
86+
</body>
87+
</html>
88+
```
89+
90+
The output in the above example will go to the JavaScript console. It's possible
91+
to instead capture the output and print it somewhere else, for example in an
92+
HTML element. The following example shows how to do this, and also demonstrates
93+
the use of top-level await and the `js` module:
6194

6295
```html
6396
<!doctype html>
6497
<html>
6598
<head>
66-
<script src="build/micropython.js"></script>
99+
<script src="build-standard/micropython.mjs" type="module"></script>
67100
</head>
68101
<body>
69102
<pre id="micropython-stdout"></pre>
70-
<script>
71-
document.addEventListener("micropython-print", function(e) {
72-
let output = document.getElementById("micropython-stdout");
73-
output.innerText += new TextDecoder().decode(e.detail);
74-
}, false);
75-
76-
var mp_js_startup = Module["onRuntimeInitialized"];
77-
Module["onRuntimeInitialized"] = async function() {
78-
mp_js_startup();
79-
mp_js_init(64 * 1024);
80-
await mp_js_do_str("print('hello world')");
103+
<script type="module">
104+
const stdoutWriter = (line) => {
105+
document.getElementById("micropython-stdout").innerText += line + "\n";
81106
};
107+
const mp = await loadMicroPython({stdout:stdoutWriter});
108+
await mp.runPythonAsync(`
109+
import js
110+
url = "https://api.github.com/users/micropython"
111+
print(f"fetching {url}...")
112+
res = await js.fetch(url)
113+
json = await res.json()
114+
for i in dir(json):
115+
print(f"{i}: {json[i]}")
116+
`);
82117
</script>
83118
</body>
84119
</html>
@@ -98,31 +133,41 @@ Run the test suite using:
98133
API
99134
---
100135

101-
The following functions have been exposed to javascript.
136+
The following functions have been exposed to JavaScript through the interpreter
137+
context, created and returned by `loadMicroPython()`.
102138

103-
```
104-
mp_js_init(stack_size)
105-
```
139+
- `PyProxy`: the type of the object that proxies Python objects.
106140

107-
Initialize MicroPython with the given stack size in bytes. This must be
108-
called before attempting to interact with MicroPython.
141+
- `FS`: the Emscripten filesystem object.
109142

110-
```
111-
await mp_js_do_str(code)
112-
```
143+
- `globals`: an object exposing the globals from the Python `__main__` module,
144+
with methods `get(key)`, `set(key, value)` and `delete(key)`.
113145

114-
Execute the input code. `code` must be a `string`.
146+
- `registerJsModule(name, module)`: register a JavaScript object as importable
147+
from Python with the given name.
115148

116-
```
117-
mp_js_init_repl()
118-
```
149+
- `pyimport`: import a Python module and return it.
119150

120-
Initialize MicroPython repl. Must be called before entering characters into
121-
the repl.
151+
- `runPython(code)`: execute Python code and return the result.
122152

123-
```
124-
await mp_js_process_char(char)
125-
```
153+
- `runPythonAsync(code)`: execute Python code and return the result, allowing for
154+
top-level await expressions (this call must be await'ed on the JavaScript side).
155+
156+
- `replInit()`: initialise the REPL.
157+
158+
- `replProcessChar(chr)`: process an incoming character at the REPL.
159+
160+
- `replProcessCharWithAsyncify(chr)`: process an incoming character at the REPL,
161+
for use when ASYNCIFY is enabled.
162+
163+
Proxying
164+
--------
165+
166+
A Python `dict` instance is proxied such that:
167+
168+
for (const key in dict) {
169+
print(key, dict[key]);
170+
}
126171

127-
Input character into MicroPython repl. `char` must be of type `number`. This
128-
will execute MicroPython code when necessary.
172+
works as expected on the JavaScript side and iterates through the keys of the
173+
Python `dict`.

0 commit comments

Comments
 (0)