PythonExtra/ports/zephyr
Maarten van der Schrieck 3bca93b2d0 ports: Fix sys.stdout.buffer.write() return value.
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>
2023-12-22 10:32:46 +11:00
..
boards zephyr/boards: Add config for bbc_microbit_v2. 2022-09-09 14:14:31 +10:00
src zephyr: Update include paths to use the zephyr namespace. 2022-06-17 16:44:30 +10:00
CMakeLists.txt extmod/modmachine: Factor ports' machine module dict to common code. 2023-11-30 16:11:11 +11:00
Kconfig zephyr: Build MicroPython as a cmake target. 2021-02-16 18:49:30 +11:00
README.md all: Rename MP_QSTR_umodule to MP_QSTR_module everywhere. 2023-06-08 17:53:57 +10:00
help.c ports: Standardise docs link in help text. 2023-06-02 11:48:46 +10:00
machine_i2c.c extmod/modmachine: Consolidate mem, i2c and spi headers to modmachine.h. 2023-10-26 17:40:22 +11:00
machine_pin.c extmod/modmachine: Clean up decls of machine types to use common ones. 2023-10-26 16:20:53 +11:00
machine_spi.c extmod/modmachine: Consolidate mem, i2c and spi headers to modmachine.h. 2023-10-26 17:40:22 +11:00
machine_uart.c extmod/machine_uart: Factor ports' UART Python bindings to common code. 2023-10-26 10:46:42 +11:00
main.c py/builtinevex: Handle invalid filenames for execfile. 2023-10-12 15:17:59 +11:00
make-bin-testsuite tests: Rename run-tests to run-tests.py for consistency. 2021-03-12 19:56:09 +11:00
modbluetooth_zephyr.c extmod/modbluetooth: Merge gatts_notify/indicate implementation. 2023-04-26 11:37:20 +10:00
modmachine.c extmod/modmachine: Provide common bindings for 6 bare-metal functions. 2023-11-30 16:11:11 +11:00
modmachine.h extmod/modmachine: Provide common bindings for 6 bare-metal functions. 2023-11-30 16:11:11 +11:00
modsocket.c all: Use MP_REGISTER_EXTENSIBLE_MODULE for overrideable built-ins. 2023-06-08 17:54:21 +10:00
modtime.c all: Rename *umodule*.c to remove the "u" prefix. 2023-06-08 17:54:17 +10:00
modzephyr.c zephyr: Update include paths to use the zephyr namespace. 2022-06-17 16:44:30 +10:00
modzephyr.h zephyr: Implement block device protocol via zephyr flash map api. 2020-02-07 11:24:06 +11:00
modzsensor.c all: Rename UMODULE to MODULE in preprocessor/Makefile vars. 2023-06-08 17:54:11 +10:00
mpconfigport.h ports: Move definitions of ATOMIC_SECTION macros to mphalport.h. 2023-12-01 14:37:48 +11:00
mpconfigport_bin_testsuite.h all: Update to point to files in new shared/ directory. 2021-07-12 17:08:10 +10:00
mpconfigport_minimal.h shared/readline: Use MP_REGISTER_ROOT_POINTER(). 2022-07-18 13:48:49 +10:00
mphalport.c zephyr: Run scheduled callbacks at REPL and during mp_hal_delay_ms. 2021-04-30 15:32:16 +10:00
mphalport.h ports: Move definitions of ATOMIC_SECTION macros to mphalport.h. 2023-12-01 14:37:48 +11:00
prj.conf all: Rename UMODULE to MODULE in preprocessor/Makefile vars. 2023-06-08 17:54:11 +10:00
prj_minimal.conf zephyr: Run scheduled callbacks at REPL and during mp_hal_delay_ms. 2021-04-30 15:32:16 +10:00
uart_core.c ports: Fix sys.stdout.buffer.write() return value. 2023-12-22 10:32:46 +11:00
zephyr_storage.c py/obj: Convert make_new into a mp_obj_type_t slot. 2022-09-19 19:06:15 +10:00

README.md

MicroPython port to Zephyr RTOS

This is a work-in-progress port of MicroPython to Zephyr RTOS (http://zephyrproject.org).

This port requires Zephyr version v3.1.0, and may also work on higher versions. All boards supported by Zephyr (with standard level of features support, like UART console) should work with MicroPython (but not all were tested).

Features supported at this time:

  • REPL (interactive prompt) over Zephyr UART console.
  • time module for time measurements and delays.
  • machine.Pin class for GPIO control, with IRQ support.
  • machine.I2C class for I2C control.
  • machine.SPI class for SPI control.
  • socket module for networking (IPv4/IPv6).
  • "Frozen modules" support to allow to bundle Python modules together with firmware. Including complete applications, including with run-on-boot capability.
  • virtual filesystem with FAT and littlefs formats, backed by either DiskAccess or FlashArea (flash map).

Over time, bindings for various Zephyr subsystems may be added.

Building

Follow to Zephyr web site for Getting Started instruction of installing Zephyr SDK, getting Zephyr source code, and setting up development environment. (Direct link: https://docs.zephyrproject.org/latest/getting_started/index.html). You may want to build Zephyr's own sample applications to make sure your setup is correct.

If you already have Zephyr installed but are having issues building the MicroPython port then try installing the correct version of Zephyr via:

$ west init zephyrproject -m https://github.com/zephyrproject-rtos/zephyr --mr v3.1.0

Alternatively, you don't have to redo the Zephyr installation to just switch from master to a tagged release, you can instead do:

$ cd zephyrproject/zephyr
$ git checkout v3.1.0
$ west update

With Zephyr installed you may then need to configure your environment, for example by sourcing zephyrproject/zephyr/zephyr-env.sh.

Once Zephyr is ready to use you can build the MicroPython port just like any other Zephyr application. You can do this anywhere in your file system, it does not have to be in the ports/zephyr directory. Assuming you have cloned the MicroPython repository into your home directory, you can build the Zephyr port for a frdm_k64f board like this:

$ west build -b frdm_k64f ~/micropython/ports/zephyr

To build for QEMU instead:

$ west build -b qemu_x86 ~/micropython/ports/zephyr

Consult the Zephyr documentation above for the list of supported boards. Board configuration files appearing in ports/zephyr/boards/ correspond to boards that have been tested with MicroPython and may have additional options enabled, like filesystem support.

Running

To flash the resulting firmware to your board:

$ west flash

Or, to flash it to your board and start a gdb debug session:

$ west debug

To run the resulting firmware in QEMU (for BOARDs like qemu_x86, qemu_cortex_m3):

$ west build -t run

Networking is enabled with the default configuration, so you need to follow instructions in https://docs.zephyrproject.org/latest/guides/networking/qemu_setup.html#networking-with-qemu to setup the host side of TAP/SLIP networking. If you get an error like:

could not connect serial device to character backend 'unix:/tmp/slip.sock'

it's a sign that you didn't follow the instructions above. If you would like to just run it quickly without extra setup, see "minimal" build below.

Quick example

To blink an LED:

import time
from machine import Pin

LED = Pin(("GPIO_1", 21), Pin.OUT)
while True:
    LED.value(1)
    time.sleep(0.5)
    LED.value(0)
    time.sleep(0.5)

The above code uses an LED location for a FRDM-K64F board (port B, pin 21; following Zephyr conventions port are identified by "GPIO_x", where x starts from 0). You will need to adjust it for another board (using board's reference materials). To execute the above sample, copy it to clipboard, in MicroPython REPL enter "paste mode" using Ctrl+E, paste clipboard, press Ctrl+D to finish paste mode and start execution.

To respond to Pin change IRQs, on a FRDM-K64F board run:

from machine import Pin

SW2 = Pin(("GPIO_2", 6), Pin.IN)
SW3 = Pin(("GPIO_0", 4), Pin.IN)

SW2.irq(lambda t: print("SW2 changed"))
SW3.irq(lambda t: print("SW3 changed"))

while True:
    pass

Example of using I2C to scan for I2C slaves:

from machine import I2C

i2c = I2C("I2C_0")
i2c.scan()

Example of using SPI to write a buffer to the MOSI pin:

from machine import SPI

spi = SPI("SPI_0")
spi.init(baudrate=500000, polarity=1, phase=1, bits=8, firstbit=SPI.MSB)
spi.write(b'abcd')

Minimal build

MicroPython is committed to maintain minimal binary size for Zephyr port below 128KB, as long as Zephyr project is committed to maintain stable minimal size of their kernel (which they appear to be). Note that at such size, there is no support for any Zephyr features beyond REPL over UART, and only very minimal set of builtin Python modules is available. Thus, this build is more suitable for code size control and quick demonstrations on smaller systems. It's also suitable for careful enabling of features one by one to achieve needed functionality and code size. This is in the contrast to the "default" build, which may get more and more features enabled over time.

To make a minimal build:

$ west build -b qemu_x86 ~/micropython/ports/zephyr -- -DCONF_FILE=prj_minimal.conf

To run a minimal build in QEMU without requiring TAP networking setup run the following after you built an image with the previous command:

$ west build -t run