.. _micropython:

=========== MicroPython

What is MicroPython?

MicroPython <http://micropython.org/>__ is Python for microcontrollers. Using MicroPython, you can write Python3 code and run it even on a bare metal architecture with limited resources. One of its powerful features is the ability to change the behavior of a device by changing the Python code on removable (or internal) storage, without having to change the device's firmware.

Highlights of MicroPython

:Compact: Fits and runs within just 256k of code space and 16k of RAM. No OS is needed, although you can also run it with an OS, if you want. :Compatible: Strives to be as compatible as possible with normal Python (known as CPython). :Versatile: Supports many architectures (x86, x86-64, ARM, ARM Thumb, Xtensa). :Interactive: No need for the compile-flash-boot cycle. With the REPL (interactive prompt) you can type commands and execute them immediately, run scripts, etc. :Popular: Many platforms are supported. The user base is growing larger. Notable forks:

            - `MicroPython <https://github.com/micropython/micropython>`__
            - `CircuitPython <https://github.com/adafruit/circuitpython>`__
            - `MicroPython_ESP32_psRAM_LoBo <https://github.com/loboris/MicroPython_ESP32_psRAM_LoBo>`__

:Embedded Oriented: Comes with modules specifically for embedded systems, such as the machine module <https://docs.micropython.org/en/latest/library/machine.html#classes>__ for accessing low-level hardware (I/O pins, ADC, UART, SPI, I2C, RTC, Timers etc.)

Why MicroPython + LVGL?

MicroPython does not have a good native high-level GUI library. LVGL is an Object-Oriented Component Based <https://blog.lvgl.io/2018-12-13/extend-lvgl-objects>__ high-level GUI library, which is a natural candidate to map into a higher level language, such as Python. LVGL is implemented in C and its APIs are in C.

Here are some advantages of using LVGL in MicroPython:

Develop GUI in Python, a very popular high level language. Use paradigms such as Object-Oriented Programming.
Usually, GUI development requires multiple iterations to get things right. With C, each iteration consists of Change code > Build > Flash > Run. In MicroPython it's just Change code > Run\ ! You can even run commands interactively using the REPL <https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop>__ (the interactive prompt)

MicroPython + LVGL could be used for:

Fast GUI prototyping
Shortening the cycle of changing and fine-tuning a GUI
Modelling a GUI in a more abstract way by defining reusable composite Widgets, taking advantage of Python's language features such as Inheritance, Closures, List Comprehension, Generators, Exception Handling, Arbitrary Precision Integers and others.
Make LVGL accessible to a larger audience. No need to know C to create a nice GUI on an embedded system. This goes well with CircuitPython vision <https://learn.adafruit.com/welcome-to-circuitpython/what-is-circuitpython>__. CircuitPython was designed with education in mind, to make it easier for new or inexperienced programmers to get started with embedded development.
Creating tools to work with LVGL at a higher level (e.g. drag-and-drop designer).

What does it look like?

It's very much like the C API, but Object-Oriented for LVGL components.

Let's dive right into an example!

A simple example

.. code-block:: python

# Initialize
import display_driver
import lvgl as lv

# Create a button with a label
scr = lv.obj()
btn = lv.button(scr)
btn.align(lv.ALIGN.CENTER, 0, 0)
label = lv.label(btn)
label.set_text('Hello World!')
lv.screen_load(scr)

How Can I Use It?

Online Simulator

If you want to experiment with LVGL + MicroPython without downloading anything, you can use our online simulator! It's a fully functional LVGL + MicroPython that runs entirely in the browser and allows you to edit a python script and run it.

Click here to experiment on the online simulator <https://sim.lvgl.io/>__

Many :ref:LVGL examples <examples> are available also for MicroPython. Just click the link!

PC Simulator

MicroPython is ported to many platforms. One notable port is to "Unix", which allows you to build and run MicroPython (+LVGL) on a Linux machine. (On a Windows machine you might need Virtual Box or WSL or MinGW or Cygwin etc.)

Click here to learn more about building and running the Unix port. <https://github.com/lvgl/lv_micropython>__

Embedded Platforms

In the end, the goal is to run it all on an embedded platform. Both MicroPython and LVGL can be used on many embedded architectures. lv_micropython <https://github.com/lvgl/lv_micropython>__ is a fork of MicroPython+LVGL and currently supports Linux, ESP32, STM32 and RP2. It can be ported to any other platform supported by MicroPython.

You would also need display and input drivers. You can either use one of the existing drivers provided with lv_micropython, or you can create your own input/display drivers for your specific hardware.
Drivers can be implemented either in C as a MicroPython module, or in pure Python.

lv_micropython already contains these drivers:

Display drivers:
- SDL on Linux
- X11 on Linux
- ESP32 specific:
  - ILI9341
  - ILI9488
  - GC9A01
  - ST7789
  - ST7735
- Generic (pure Python):
  - ILI9341
  - ST7789
  - ST7735
Input drivers:
- SDL
- X11
- XPT2046
- FT6X36
- ESP32 ADC with resistive touch

Where can I find more information?

lv_micropython README <https://github.com/lvgl/lv_micropython>__
lv_binding_micropython README <https://github.com/lvgl/lv_binding_micropython>__
The LVGL micropython forum <https://forum.lvgl.io/c/micropython>__ (Feel free to ask anything!)
At MicroPython: docs <http://docs.micropython.org/en/latest/>__ and forum <https://forum.micropython.org/>__
Blog Post <https://blog.lvgl.io/2019-02-20/micropython-bindings>__, a little outdated.

The MicroPython Binding is auto generated!

LVGL is a git submodule inside lv_micropython <https://github.com/lvgl/lv_micropython>__ (LVGL is a git submodule of lv_binding_micropython <https://github.com/lvgl/lv_binding_micropython>__ which is itself a submodule of lv_micropython <https://github.com/lvgl/lv_micropython>__).
When building lv_micropython, the public LVGL C API is scanned and MicroPython API is auto-generated. That means that lv_micropython provides LVGL API for any LVGL version, and generally does not require code changes as LVGL evolves.

LVGL C API Coding Conventions

For a summary of coding conventions to follow see the :ref:coding-style.

.. _memory_management:

Memory Management

When LVGL runs in MicroPython, all dynamic memory allocations (:cpp:func:lv_malloc) are handled by MicroPython's memory manager which is garbage-collected <https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)>__ (GC).
To prevent GC from collecting memory prematurely, all dynamic allocated RAM must be reachable by the GC.
GC is aware of most allocations, except from pointers to the Data Segment <https://en.wikipedia.org/wiki/Data_segment>__:
- Pointers which are global variables
- Pointers which are static global variables
- Pointers which are static local variables

Such pointers need to be defined in a special way to make them reachable by the GC.

Identify The Problem


A problem occurs when an allocated memory's pointer (return value of :cpp:func:`lv_malloc`)
is stored only in either **global**, **static global** or **static local** pointer
variable and not as part of a previously allocated ``struct`` or other variable.


Solving the Problem
~~~~~~~~~~~~~~~~~~~

- Replace the global/static local var with :cpp:expr:`(LV_GLOBAL_DEFAULT()->_var)`
- Include ``lv_global.h`` on files that use :c:macro:`LV_GLOBAL_DEFAULT`
- Add ``_var`` to ``lv_global_t`` on ``lv_global.h``


Example
~~~~~~~


Further Reading on Memory Management

In the README <https://github.com/lvgl/lv_binding_micropython#memory-management>__
In the Blog <https://blog.lvgl.io/2019-02-20/micropython-bindings#i-need-to-allocate-a-littlevgl-struct-such-as-style-color-etc-how-can-i-do-that-how-do-i-allocatedeallocate-memory-for-it>__

.. _callbacks:

Callbacks

In C a callback is just a function pointer. But in MicroPython we need to register a MicroPython callable object for each callback. Therefore in the MicroPython binding we need to register both a function pointer and a MicroPython object for every callback.

Therefore we defined a callback convention for the LVGL C API that expects LVGL headers to be defined in a certain way. Callbacks that are declared according to this convention allow the binding to register a MicroPython object next to the function pointer when registering a callback, and access that object when the callback is called.

The basic idea is that we have void * user_data field that is used automatically by the MicroPython Binding to save the MicroPython callable object for a callback. This field must be provided when registering the function pointer, and provided to the callback function itself.
Although called "user_data", the user is not expected to read/write that field. Instead, the MicroPython glue code uses user_data to automatically keep track of the MicroPython callable object. The glue code updates it when the callback is registered, and uses it when the callback is called in order to invoke a call to the original callable object.

There are a few options for defining a callback in LVGL C API:

Option 1: user_data in a struct
- There's a struct that contains a field called void * user_data
  - A pointer to that struct is provided as the first argument of a callback registration function.
  - A pointer to that struct is provided as the first argument of the callback itself.
Option 2: user_data as a function argument
- A parameter called void * user_data is provided to the registration function as the last argument
  - The callback itself receives void * as the last argument
Option 3: both callback and user_data are struct fields
- The API exposes a struct with both function pointer member and user_data member
  - The function pointer member receives the same struct as its first argument

In practice it's also possible to mix these options, for example provide a struct pointer when registering a callback (option 1) and provide user_data argument when calling the callback (options 2), as long as the same user_data that was registered is passed to the callback when it's called.

Examples


- :cpp:type:`lv_anim_t` contains ``user_data`` field. :cpp:func:`lv_anim_set_path_cb` registers `path_cb` callback.
  Both ``lv_anim_set_path_cb`` and :cpp:type:`lv_anim_path_cb_t` receive :cpp:type:`lv_anim_t` as their first argument
- ``path_cb`` field can also be assigned directly in the Python code because it's a member of :cpp:type:`lv_anim_t`
  which contains ``user_data`` field, and :cpp:type:`lv_anim_path_cb_t` receive :cpp:type:`lv_anim_t` as its first argument.
- :cpp:func:`lv_imgfont_create` registers ``path_cb`` and receives ``user_data`` as the last argument.
  The callback :cpp:type:`lv_imgfont_get_path_cb_t` also receives the ``user_data`` as the last argument.


.. _more-information-1:

Further Reading on Callbacks

In the Blog <https://blog.lvgl.io/2019-08-05/micropython-pure-display-driver#using-callbacks>__ and in the README <https://github.com/lvgl/lv_binding_micropython#callbacks>__
[v6.0] Callback conventions #1036 <https://github.com/lvgl/lvgl/issues/1036>__
Various discussions: here <https://github.com/lvgl/lvgl/pull/3294#issuecomment-1184895335>__ and here <https://github.com/lvgl/lvgl/issues/1763#issuecomment-762247629>__ and here <https://github.com/lvgl/lvgl/issues/316#issuecomment-467221587>__