3bca93b2d0
MicroPython code may rely on the return value of sys.stdout.buffer.write()
to reflect the number of bytes actually written. While in most scenarios a
write() operation is successful, there are cases where it fails, leading to
data loss. This problem arises because, currently, write() merely returns
the number of bytes it was supposed to write, without indication of
failure.
One scenario where write() might fail, is where USB is used and the
receiving end doesn't read quickly enough to empty the receive buffer. In
that case, write() on the MicroPython side can timeout, resulting in the
loss of data without any indication, a behavior observed notably in
communication between a Pi Pico as a client and a Linux host using the ACM
driver.
A complex issue arises with mp_hal_stdout_tx_strn() when it involves
multiple outputs, such as USB, dupterm and hardware UART. The challenge is
in handling cases where writing to one output is successful, but another
fails, either fully or partially. This patch implements the following
solution:
mp_hal_stdout_tx_strn() attempts to write len bytes to all of the possible
destinations for that data, and returns the minimum successful write
length.
The implementation of this is complicated by several factors:
- multiple outputs may be enabled or disabled at compiled time
- multiple outputs may be enabled or disabled at runtime
- mp_os_dupterm_tx_strn() is one such output, optionally containing
multiple additional outputs
- each of these outputs may or may not be able to report success
- each of these outputs may or may not be able to report partial writes
As a result, there's no single strategy that fits all ports, necessitating
unique logic for each instance of mp_hal_stdout_tx_strn().
Note that addressing sys.stdout.write() is more complex due to its data
modification process ("cooked" output), and it remains unchanged in this
patch. Developers who are concerned about accurate return values from
write operations should use sys.stdout.buffer.write().
This patch might disrupt some existing code, but it's also expected to
resolve issues, considering that the peculiar return value behavior of
sys.stdout.buffer.write() is not well-documented and likely not widely
known. Therefore, it's improbable that much existing code relies on the
previous behavior.
Signed-off-by: Maarten van der Schrieck <maarten@thingsconnected.nl>
|
||
|---|---|---|
| .. | ||
| Makefile | ||
| README.md | ||
| library.h | ||
| library.js | ||
| main.c | ||
| mpconfigport.h | ||
| mphalport.c | ||
| mphalport.h | ||
| node_run.sh | ||
| qstrdefsport.h | ||
| wrapper.js | ||
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);
await 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 += 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')");
};
</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.
await 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.
await mp_js_process_char(char)
Input character into MicroPython repl. char must be of type number. This
will execute MicroPython code when necessary.