What changed in 1.24 to 1.29, and MicroPython 2.0

Six MicroPython releases, 1.24 to 1.29, brought hundreds of changes, and seven of them can break code that worked the day before: a sys.exit() that now restarts the board, an encoding name that now raises LookupError, an SD card call whose return value turned its meaning around. Behind them MicroPython 2.0 is taking shape, with one API move announced so far.

This lesson shows where a release’s notes put the changes for your board, walks through the seven breaking changes with the fix for each, separates the features you probe for from the behaviour you check by version, and makes the vfs move of 2.0 in code that runs on today’s releases.

Release notes put the breaking changes first, then every change by port

Each release has its notes on GitHub, under the tag of its version, such as v1.29.0. They open with an overview: the new features, then a paragraph for each port that changed. Release 1.29 adds a section of its own for breaking changes; earlier releases name theirs inside the overview, which makes them easy to miss. A table of firmware sizes follows, and then the full list of changes, sorted by component: the core under “py core” and “extmod”, then documentation, tests and tools, and at the end one block per port, “rp2 port”, “esp32 port” and so on. For code on one board, read the overview, the breaking changes, and the blocks of the core and of your port.

Walk through the six releases of this lesson and the version after them:

The documentation is versioned too. docs.micropython.org/en/v1.29.0/ describes exactly that release, while /en/latest/ follows the development branch, so link and read the version your boards run. On the board, sys.implementation.version says which release it is, (1, 29, 0, '') for 1.29.0, a tuple that compares correctly.

Seven changes from 1.24 to 1.29 break code that worked before

These are the changes the release notes themselves call breakingbreaking change: A change in a new release after which code that worked before fails or behaves differently, without being changed itself. Release notes call such changes out so that they can be fixed before an upgrade. that reach Python code, with what each asks of it:

The 1.29 section lists three more, for people who build firmware or write C rather than Python: the unix port’s MICROPY_FORCE_32BIT option is gone, the powerpc port is merged into qemu, and stm32’s C function rng_get() is renamed.

The 1.24 change is the one that turns a program into a reboot loop: a main.py that calls sys.exit() when a sensor is missing now restarts, finds the sensor missing again and restarts again. The SD card change is the subtle one. Code that checked if card.writeblocks(n, buf): now reads success, 0, as failure. And the first fix that comes to mind is wrong in a way the trace shows:

for r in (True, False, 0, -5):
    ok = r == 0 or r is True
    print(r, ok)

True True
False True
0 True
-5 False

r == 0 or r is True called a failed write of an old firmware, False, a success, because in Python False == 0. The working check tests the two booleans first, then the number. The program below runs that check, the Latin-1 decoder and the vfs choice of the next sections, from one small module:

"""The compat module beside this file on three builds, imitated with their version tuples and their vfs module."""
import sys
import types

import compat

builds = {"1.22.2": (1, 22, 2, ""), "1.26.0": (1, 26, 0, ""), "1.29.0": (1, 29, 0, "")}
for name, ver in builds.items():
    impl = types.SimpleNamespace(name="micropython", version=ver)
    sys.modules["vfs"] = types.ModuleType("vfs") if ver >= (1, 23) else None  # None: import vfs fails
    print(name, "mount from", compat.load_vfs().__name__, end="; ")
    try:
        compat.requires((1, 26), "a slice assignment in a hard IRQ", impl=impl)
        print("the IRQ handler may run")
    except RuntimeError as e:
        print(e)

for r in (True, False, None, 0, -5):
    print("SDCard returned", repr(r), "-> ok:", compat.blocks_ok(r))
print(compat.latin1(b"Caf\xe9 at 21\xb0C"), "from Latin-1 bytes")

1.22.2 mount from os; a slice assignment in a hard IRQ needs MicroPython 1.26 or later, this is 1.22.2
1.26.0 mount from vfs; the IRQ handler may run
1.29.0 mount from vfs; the IRQ handler may run
SDCard returned True -> ok: True
SDCard returned False -> ok: False
SDCard returned None -> ok: True
SDCard returned 0 -> ok: True
SDCard returned -5 -> ok: False
Café at 21°C from Latin-1 bytes

"""Calls that changed between MicroPython 1.24 and 1.29, and the 2.0 move of mount, made to work on every build."""
import sys


def load_vfs():
    """The module that holds mount(): vfs on 1.23 and later, the only place in 2.0; os on older builds."""
    try:
        import vfs

        return vfs
    except ImportError:
        import os

        return os


vfs = load_vfs()


def version(impl=None):
    return tuple((impl or sys.implementation).version[:3])


def requires(minimum, name="this code", impl=None):
    """Raise a clear error on a build older than minimum, a tuple such as (1, 26)."""
    have = version(impl)
    if have < tuple(minimum):
        raise RuntimeError("%s needs MicroPython %s or later, this is %s"
                           % (name, ".".join(map(str, minimum)), ".".join(map(str, have))))


def blocks_ok(result):
    """True when a block device read or write succeeded: True (esp32 and stm32 SDCard before 1.29), None or 0."""
    if result is True or result is None:  # test the bools first: False == 0 in Python
        return True
    if result is False:
        return False
    return result == 0  # from 1.29: 0, or a negative errno


def latin1(data):
    """Decode Latin-1 bytes by hand: 1.29 accepts only utf-8 and ascii, and raises LookupError for the rest."""
    return "".join(chr(b) for b in data)  # every Latin-1 byte is the code point of the same number

blocks_ok() accepts True, None and 0 as success and False and negative numbers as failure, so the same logger runs on 1.28 and on 1.29. latin1() works because every Latin-1 byte is the Unicode code point of the same number, so chr() of each byte decodes it, and b"Caf\xe9" becomes “Café” on a release that refuses the encoding name.

Probe for new features; check the version only for changed behaviour

The feature-levels lesson’s rule holds across releases: ask the build for a feature with a feature probefeature probe: A short test a program runs to find out whether the Python under it has a feature: it compiles a snippet of new syntax, tries an import or looks up an attribute, inside try and except, and uses the answer to choose a code path. More in “Which Python is this? Feature levels and probes” instead of guessing from its version, because a release may leave a feature out of a smaller build. Most of the additions of 1.24 to 1.29 can be probed in one line:

Some changes have nothing to probe: the code is the same and only its behaviour differs. Since 1.26, assigning to a slice of a bytearray or memoryview no longer allocates, so it works in a hard interrupt handler with the heap locked; before 1.26 the same line raised MemoryError there. For such a change, compare the version once at start-up and fail clearly, as requires((1, 26), ...) in the compat module does: on the 1.22.2 build it raised an error that names both versions.

MicroPython 2.0 moves mount into vfs, and you can move today

MicroPython 2.0 is the next major release, still in development, with no firmware to download; the migration guide says it can be built by enabling MICROPY_PREVIEW_VERSION_2. Its goals are consistent machine APIs across ports, running .mpy files straight from the filesystem without copying them into RAM, more flexible partitions, and code that works on CPython and MicroPython alike. One change is listed so far: six names leave os for the vfs module. The table shows where each of them lives, before, during and after the move:

The column for 1.23 to 1.29 is why the move can happen today: both modules answer there, and the os documentation of 1.29 keeps the names in os only for backwards compatibility. So import them from vfs now. compat.load_vfs() tries import vfs and falls back to os on builds older than 1.23, and the program above showed it: mount came from os on the 1.22.2 build and from vfs on 1.26.0 and 1.29.0. Code written this way runs unchanged on every 1.x release since 1.23 and on 2.0.

Practise: a compat module for MicroPython 1.20 to 1.29

Write the three functions a fleet of boards on mixed releases needs: a version requirement with a clear error, a choice between vfs and os, and a check of block-device results that works on both sides of 1.29. The sample tests pass fake modules and version tuples instead of a board:

def requires(minimum, version, name="this code"):
    """Raise RuntimeError when version is older than minimum."""


def pick_vfs(found):
    """The module that holds mount(): vfs if present, else os if it has mount."""
    return found["os"]


def blocks_ok(result):
    """True when a block device read or write succeeded, before or after 1.29."""
    return result == 0

import types

from compat import blocks_ok, pick_vfs, requires


def test_requires_passes():
    """allows the minimum and later versions"""
    requires((1, 26), (1, 26, 0, ""))
    requires((1, 26), (1, 29, 0, ""))


def test_requires_refuses():
    """refuses an older version with both versions in the message"""
    try:
        requires((1, 26), (1, 24, 1, ""), "I2CTarget")
    except RuntimeError as e:
        assert str(e) == "I2CTarget needs MicroPython 1.26 or later, this is 1.24.1"
    else:
        raise AssertionError("no RuntimeError")


def test_requires_not_strings():
    """compares numbers, so 1.9 is older than 1.24"""
    try:
        requires((1, 24), (1, 9, 4, ""))
    except RuntimeError:
        return
    raise AssertionError("1.9.4 passed as 1.24 or later")


def test_pick_vfs():
    """prefers vfs, falls back to an os that has mount, and refuses otherwise"""
    vfs = types.SimpleNamespace(mount=lambda *a: None)
    old_os = types.SimpleNamespace(mount=lambda *a: None)
    cpython_os = types.SimpleNamespace()
    assert pick_vfs({"vfs": vfs, "os": old_os}) is vfs
    assert pick_vfs({"vfs": None, "os": old_os}) is old_os
    try:
        pick_vfs({"vfs": None, "os": cpython_os})
    except ImportError:
        return
    raise AssertionError("no ImportError")


def test_blocks_ok():
    """accepts both conventions and never mistakes False for 0"""
    assert [blocks_ok(r) for r in (True, None, 0)] == [True, True, True]
    assert [blocks_ok(r) for r in (False, -5, -110)] == [False, False, False]

Then check yourself on release notes, breaking changes, probes and 2.0:

Interview questions

Warm-up (fresher): Where do you look to see what changed in a MicroPython release for your board?

Open the release’s notes on GitHub, under the tag of the version, such as v1.29.0. Read the overview, the breaking changes, which 1.29 lists in a section of its own and earlier releases inside the overview, and in the detailed list the blocks for the core, “py core” and “extmod”, and for your port, such as “rp2 port”. Then read the documentation of that exact version at docs.micropython.org/en/v1.29.0/ rather than the latest, and check on the board with sys.implementation.version which release it really runs.

Warm-up (fresher): What does MicroPython 2.0 change so far, and how can code prepare for it?

MicroPython 2.0 is still in development and has no builds to download. Its migration guide lists one change so far: os.mount, os.umount and the Vfs classes move from os to the vfs module. Code prepares by importing them from vfs today, which every release since 1.23 has, with a fallback to os for older builds. The guide is not final, so reading it with each release shows the next moves early.

Warm-up (fresher): How do you check in code that a board runs MicroPython 1.24 or later?

Compare sys.implementation.version with a tuple: sys.implementation.version >= (1, 24). The version is a tuple of the major, minor and micro numbers and a release level, such as (1, 29, 0, '') for 1.29.0, and tuples compare number by number, so (1, 9, 4, '') counts as older than (1, 24). Comparing the strings of os.uname().release gets it wrong, because “1.9.4” sorts after “1.24” letter by letter. Keep such a check for behaviour that changed between releases; a feature that a build may leave out is probed instead, with hasattr() or an import in a try.

Two longer questions about upgrades follow; each row leads to what it tests and a first step:

Key takeaways

• A release’s notes give the overview and the breaking changes first, then every change by component and port; read the blocks of the core and of your port, in the documentation of the version you run.
• Seven changes from 1.24 to 1.29 break old code: sys.exit() soft-resets, stm32 releases buses at a soft reset, nrf’s enable_irq(state), only utf-8 and ascii, SDCard results of 0 or a negative number, sys.platform “nrf”, and stm32’s stm names without _S or _NS.
• Check results that may be a bool on one version and a number on another with is True and is False first, because False == 0.
• Probe for features with hasattr(), import or compile(), and compare sys.implementation.version as a tuple only for behaviour that changed.
• MicroPython 2.0 is in development; its one listed change moves mount, umount and the Vfs classes to vfs, which code can import today on any release since 1.23.