Skip to content

Running on desktop

Running on desktop

Desktop builds of MicroPythonOS can run without a local source checkout. The internal_filesystem/ is frozen into the binary at build time, so a single pre-built executable is enough to try the OS.

Download a pre-built binary

  1. Go to the releases page.
  2. Download the binary for your platform:
  3. Linux / WSL2 on Windows: lvgl_micropy_unix
  4. macOS (Apple Silicon or Intel): lvgl_micropy_macOS
  5. Make it executable:
chmod +x lvgl_micropy_unix
  1. Place it where scripts/run_desktop.sh expects it. The script looks for:
  2. lvgl_micropython/build/lvgl_micropy_unix on Linux
  3. lvgl_micropython/build/lvgl_micropy_macOS on macOS

You can create that folder and copy the binary there:

mkdir -p lvgl_micropython/build
cp /path/to/downloaded/lvgl_micropy_unix lvgl_micropython/build/lvgl_micropy_unix
  1. Run it:
./scripts/run_desktop.sh

Build from source

If you want to modify the OS itself or run the very latest code, you can build it from source. The built binary will already be in lvgl_micropython/build/lvgl_micropy_XXX where XXX is unix or macOS.

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

If you do have a source checkout, you can still run the OS directly from internal_filesystem/. 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:

    ./lvgl_micropython/lib/micropython/tools/mpremote/mpremote.py cp internal_filesystem/lib/mpos/device_info.py :/lib/mpos

Notes

Back to top