Skip to content

Running it

MicroPythonOS can be installed on supported microcontrollers (e.g., ESP32) and on desktop systems (Linux, Raspberry Pi, MacOS, etc).

To simply install prebuilt software, read on!

Running on ESP32

Just use the WebSerial installer at install.micropythonos.com.

For advanced usage, such as installing development builds without any files, see Installing on ESP32.

Running on desktop

  1. Make sure you have the internal_filesystem/ folder

    If you built from source, you will already have a local clone that contains it.

    If you used a pre-built binary, then you need to get a local clone and change into that directory with:

    git clone --recurse-submodules https://github.com/MicroPythonOS/MicroPythonOS.git
cd MicroPythonOS/

  2. Make sure you have the software

    If you built from source, you will already have it in lvgl_micropython/build/lvgl_micropy_unix

    If you downloaded a pre-built binary (like MicroPythonOS_amd64_macOS_0.7.1.bin or MicroPythonOS_amd64_linux_0.7.1.elf), then copy it to the right location:

    mkdir -p lvgl_micropython/build
cp /Users/yourname/MicroPythonOS_amd64_macOS_0.7.1.bin lvgl_micropython/build/lvgl_micropy_macOS # for macOS
cp /home/yourname/MicroPythonOS_amd64_linux_0.7.1.elf lvgl_micropython/build/lvgl_micropy_unix # for linux

  3. Start the software:

    You're now ready to run it with:

    ./scripts/run_desktop.sh

Notes on MacOS

If you get an error about a missing /opt/homebrew/opt/libffi/lib/libffi.8.dylib then fix that with: brew install libffi

If you get an error about the code being unsigned, then allow it like this:

Allow Anyway on MacOS

Making Changes on Desktop

You'll notice that whenever you change a file in internal_filesystem/, the changes are immediately visible on desktop when you reload the file or restart the app.

When you run ./scripts/run_desktop.sh, the OS runs the MicroPythonOS scripts directly from internal_filesystem/. This means:

  • All changes to Python files are immediately active - no build or install needed
  • Instant testing - edit a file, restart the app, see the changes
  • Fast iteration cycle - the recommended way to develop and test

Try it yourself:

  1. Edit internal_filesystem/builtin/apps/com.micropythonos.about/assets/about.py
  2. Run ./scripts/run_desktop.sh
  3. Open the About app
  4. See your changes immediately!

Making Changes on ESP32

Once you've tested your changes on desktop and they work correctly, or you're doing things you can't test on desktop, then you can deploy to physical hardware.

The easiest way to install on the ESP32 is using the webinstaller, of course.

But if you need to install a version that's not available there, or you built your own, then you can manually install it on an ESP32 device.

  1. Get the firmware

    • Download a release binary (e.g., MicroPythonOS_esp32_0.5.0.bin)
    • Or build your own on MacOS or Linux

  2. Put the ESP32 in Bootloader Mode

    If you're already in MicroPythonOS: go to Settings - Restart to Bootloader - Bootloader - Save.

    Otherwise, physically keep the "BOOT" (sometimes labeled "START") button pressed while powering up the board. This is explained in more detail at the webinstaller

  3. Flash the firmware

    ~/.espressif/python_env/idf5.2_py3.9_env/bin/python -m esptool --chip esp32s3 write_flash 0 firmware_file.bin

    Add the --erase-all option if you want to erase the entire flash memory, so that no old files or apps will remain.

    There's also a convenient ./scripts/flash_over_usb.sh script that will attempt to flash the latest firmware that you compiled yourself.

  4. Access the MicroPython REPL shell

    After reset, the REPL shell should be available on the serial line.

    Any serial client will do, but it's convenient to use the mpremote.py tool that's shipped with lvgl_micropython:

    lvgl_micropython/lib/micropython/tools/mpremote/mpremote.py

  5. Populate the filesystem (only for development)

    In development, you probably want to override the "frozen" libraries and apps that are compiled in, and replace them with source files, which you can edit.

    This makes MicroPythonOS startup a lot slower, as the Python scripts have to be compiled at runtime instead of at build time. But once MicroPythonOS and the code you're testing has loaded, the speed will be normal again.

    There's a convenient script that will do this for you.

    Usage:

    ./scripts/install.sh


    ./scripts/install.sh com.micropythonos.about # to install one single app

    On MacOS, the install.sh script needs: brew install --cask serial

    If you need to frequently update a small number of files, you can also update them manually, for example:

    mpremote.py cp internal_filesystem/lib/mpos/device_info.py :/lib/mpos

Notes

Next Steps