docs: reorganize and add Integartion and drivers section
This commit is contained in:
Gabor Kiss-Vamosi
5
docs/integration/bindings/cpp.rst
Normal file
5
docs/integration/bindings/cpp.rst
Normal file
@@ -0,0 +1,5 @@
|
||||
===
|
||||
Cpp
|
||||
===
|
||||
|
||||
In progress: https://github.com/lvgl/lv_binding_cpp
|
||||
12
docs/integration/bindings/index.rst
Normal file
12
docs/integration/bindings/index.rst
Normal file
@@ -0,0 +1,12 @@
|
||||
========
|
||||
Bindings
|
||||
========
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
micropython
|
||||
cpp
|
||||
pikascript
|
||||
javascript
|
||||
133
docs/integration/bindings/javascript.rst
Normal file
133
docs/integration/bindings/javascript.rst
Normal file
@@ -0,0 +1,133 @@
|
||||
==========
|
||||
JavaScript
|
||||
==========
|
||||
|
||||
With `lv_binding_js <https://github.com/lvgl/lv_binding_js>`__ you can
|
||||
write lvgl with JavaScript.
|
||||
|
||||
It uses React's virtual DOM concept to manipulate lvgl UI components,
|
||||
providing a familiar React-like experience to users.
|
||||
|
||||
**Code**
|
||||
|
||||
**Code Running on Real Device**
|
||||
|
||||
Table of Contents
|
||||
-----------------
|
||||
|
||||
- `Features <#features>`__
|
||||
- `Demo <#demo>`__
|
||||
- `Building <#building>`__
|
||||
- `Components <#components>`__
|
||||
- `Font <#font>`__
|
||||
- `Animation <#animation>`__
|
||||
- `Style <#style>`__
|
||||
- `JSAPI <#jsapi>`__
|
||||
- `Thanks <#thanks>`__
|
||||
|
||||
Features
|
||||
--------
|
||||
|
||||
- Support all lvgl built-in components
|
||||
- Fully support lvgl flex and grid style
|
||||
- support most lvgl style, just write like html5 css
|
||||
- support dynamic load image
|
||||
- Fully support lvgl animation
|
||||
|
||||
Demo
|
||||
----
|
||||
|
||||
See the
|
||||
`demo <https://github.com/lvgl/lv_binding_js/tree/master/demo>`__ folder
|
||||
|
||||
Building
|
||||
--------
|
||||
|
||||
The following are developer notes on how to build lvgljs on your native
|
||||
platform. They are not complete guides, but include notes on the
|
||||
necessary libraries, compile flags, etc.
|
||||
|
||||
lvgljs
|
||||
~~~~~~
|
||||
|
||||
- `ubuntu build Notes for sdl
|
||||
simulator <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-ubuntu-arm.md>`__
|
||||
- `macos x86 build Notes for sdl
|
||||
simulator <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-macos-x86-simulator.md>`__
|
||||
- `ubuntu build Notes for platform
|
||||
arm <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/build-ubuntu-x86-simulator.md>`__
|
||||
|
||||
JS Bundle
|
||||
~~~~~~~~~
|
||||
|
||||
- `JS Bundle build
|
||||
Notes <https://github.com/lvgl/lv_binding_js/blob/master/doc/build/js-bundle.md>`__
|
||||
|
||||
Components
|
||||
----------
|
||||
|
||||
- `View <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/View.md>`__
|
||||
- `Image <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Image.md>`__
|
||||
- `Button <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Button.md>`__
|
||||
- `Text <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Text.md>`__
|
||||
- `Input <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Input.md>`__
|
||||
- `Textarea <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Textarea.md>`__
|
||||
- `Switch <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Switch.md>`__
|
||||
- `Checkbox <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Checkbox.md>`__
|
||||
- `Dropdownlist <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Dropdownlist.md>`__
|
||||
- `ProgressBar <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/ProgressBar.md>`__
|
||||
- `Line <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Line.md>`__
|
||||
- `Roller <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Roller.md>`__
|
||||
- `Keyboard <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Keyboard.md>`__
|
||||
- `Calendar <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Calendar.md>`__
|
||||
- `Chart <https://github.com/lvgl/lv_binding_js/blob/master/doc/component/Chart.md>`__
|
||||
|
||||
Font
|
||||
----
|
||||
|
||||
`Builtin-Symbol <https://github.com/lvgl/lv_binding_js/blob/master/doc/Symbol/symbol.md>`__
|
||||
|
||||
Animation
|
||||
---------
|
||||
|
||||
`Animation <https://github.com/lvgl/lv_binding_js/blob/master/doc/animate/animate.md>`__
|
||||
|
||||
Style
|
||||
-----
|
||||
|
||||
.. include::https://github.com/lvgl/lv_binding_js/blob/master/doc/style/position-size-layout.md
|
||||
|
||||
- `position-size-layout <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/position-size-layout.md>`__
|
||||
- `boxing-model <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/boxing-model.md>`__
|
||||
- `color <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/color.md>`__
|
||||
- `flex <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/flex.md>`__
|
||||
- `grid <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/grid.md>`__
|
||||
- `font <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/font.md>`__
|
||||
- `opacity <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/opacity.md>`__
|
||||
- `display <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/display.md>`__
|
||||
- `background <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/background.md>`__
|
||||
- `scroll <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/scroll.md>`__
|
||||
- `shadow <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/shadow.md>`__
|
||||
- `recolor <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/recolor.md>`__
|
||||
- `line <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/line.md>`__
|
||||
- `transition <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/transition.md>`__
|
||||
- `transform <https://github.com/lvgl/lv_binding_js/blob/master/doc/style/transform.md>`__
|
||||
|
||||
JSAPI
|
||||
-----
|
||||
|
||||
- `network <https://github.com/lvgl/lv_binding_js/blob/master/doc/jsapi/network.md>`__
|
||||
- `filesystem <https://github.com/lvgl/lv_binding_js/blob/master/doc/jsapi/fs.md>`__
|
||||
- `dimension <https://github.com/lvgl/lv_binding_js/blob/master/doc/jsapi/dimension.md>`__
|
||||
|
||||
Thanks
|
||||
------
|
||||
|
||||
lvgljs depends on following excellent work
|
||||
|
||||
`lvgl <https://github.com/lvgl/lvgl>`__: Create beautiful UIs for any
|
||||
MCU, MPU and display type `QuickJS <https://bellard.org/quickjs/>`__:
|
||||
JavaScript engine `libuv <https://github.com/libuv/libuv>`__: platform
|
||||
abstraction layer `curl <https://github.com/curl/curl>`__: HTTP client
|
||||
`txiki.js <https://github.com/saghul/txiki.js>`__: Tiny JavaScript
|
||||
runtime
|
||||
314
docs/integration/bindings/micropython.rst
Normal file
314
docs/integration/bindings/micropython.rst
Normal file
@@ -0,0 +1,314 @@
|
||||
.. _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.
|
||||
|
||||
|
||||
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 bigger. 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 <https://forum.micropython.org/viewtopic.php?f=18&t=5543>`__.
|
||||
LVGL is an `Object-Oriented Component Based <https://blog.lvgl.io/2018-12-13/extend-lvgl-objects>`__
|
||||
high-level GUI library, which seems to be 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 prototyping GUI.
|
||||
- Shortening the cycle of changing and fine-tuning the GUI.
|
||||
- Modelling the GUI in a more abstract way by defining reusable composite objects, 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 users to get started with
|
||||
embedded development.
|
||||
- Creating tools to work with LVGL at a higher level (e.g. drag-and-drop designer).
|
||||
|
||||
--------------
|
||||
|
||||
|
||||
So 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:: python
|
||||
|
||||
import lvgl as lv
|
||||
lv.init()
|
||||
scr = lv.obj()
|
||||
btn = lv.btn(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 `LVGL examples <https://docs.lvgl.io/master/examples.html>`__ are available also for Micropython. Just click the link!
|
||||
|
||||
|
||||
PC Simulator
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Micropython is ported to many platforms. One notable port is "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 know more information 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
|
||||
- ESP32 specific:
|
||||
|
||||
- ILI9341
|
||||
- ILI9488
|
||||
- GC9A01
|
||||
- ST7789
|
||||
- ST7735
|
||||
|
||||
- Generic (pure Python):
|
||||
|
||||
- ILI9341
|
||||
- ST7789
|
||||
- ST7735
|
||||
|
||||
- Input drivers:
|
||||
|
||||
- SDL
|
||||
- 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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To support the auto-generation of the Python API, the LVGL C API must
|
||||
follow some coding conventions:
|
||||
|
||||
- Use ``enum``\ s instead of macros. If inevitable to use ``define``\ s
|
||||
export them with :cpp:expr:`LV_EXPORT_CONST_INT(defined_value)` right after the ``define``.
|
||||
- In function arguments use ``type name[]`` declaration for array parameters instead of :cpp:expr:`type * name`
|
||||
- Use typed pointers instead of :cpp:expr:`void *` pointers
|
||||
- Widget constructor must follow the ``lv_<widget_name>_create(lv_obj_t * parent)`` pattern.
|
||||
- Widget members function must start with ``lv_<module_name>`` and should receive :cpp:expr:`lv_obj_t *` as first
|
||||
argument which is a pointer to widget object itself.
|
||||
- ``struct`` APIs should follow the widgets' conventions. That is to receive a pointer to the ``struct`` as the
|
||||
first argument, and the prefix of the ``struct`` name should be used as the prefix of the
|
||||
function name too (e.g. :cpp:expr:`lv_disp_set_default(lv_disp_t * disp)`)
|
||||
- Functions and ``struct``\ s which are not part of the public API must begin with underscore in order to mark them as "private".
|
||||
- Argument must be named in H files too.
|
||||
- Do not ``malloc`` into a static or global variables. Instead declare the variable in ``lv_global_t``
|
||||
structure in ``lv_global.h`` and mark the variable with :cpp:expr:`(LV_GLOBAL_DEFAULT()->variable)` when it's used. **See** :ref:`memory_management`
|
||||
- To register and use callbacks one of the following needs to be followed. **See** :ref:`callbacks`
|
||||
|
||||
- Pass a pointer to a ``struct`` as the first argument of both the registration function and the callback. That
|
||||
``struct`` must contain ``void * user_data`` field.
|
||||
- The last argument of the registration function must be ``void * user_data`` and the same ``user_data``
|
||||
needs to be passed as the last argument of the callback.
|
||||
|
||||
Most of these rules are simple and straightforward but there are two related concepts that worth a deeper look:
|
||||
:ref:`memory_management` and :ref:`callbacks`.
|
||||
|
||||
.. _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 GC.
|
||||
| GC is aware of most allocations, except from pointers on 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 GC
|
||||
|
||||
|
||||
Identify The Problem
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Problem happens 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.
|
||||
|
||||
|
||||
Solve The Problem
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
- Replace the global/static local var with :cpp:expr:`(LV_GLOBAL_DEFAULT()->_var)`
|
||||
- Include ``lv_global.h`` on files that use ``LV_GLOBAL_DEFAULT``
|
||||
- Add ``_var`` to ``lv_global_t`` on ``lv_global.h``
|
||||
|
||||
Example
|
||||
^^^^^^^
|
||||
|
||||
|
||||
More Information
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
- `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 the convention would 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:
|
||||
|
||||
More Information
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
- 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>`__
|
||||
203
docs/integration/bindings/pikascript.rst
Normal file
203
docs/integration/bindings/pikascript.rst
Normal file
@@ -0,0 +1,203 @@
|
||||
PikaScript
|
||||
==========
|
||||
|
||||
What is PikaScript ?
|
||||
--------------------
|
||||
|
||||
`PikaScript <https://github.com/pikasTech/pikascript>`__ is a Python
|
||||
interpreter designed specifically for microcontrollers, and it supports
|
||||
a subset of the common Python3 syntax.
|
||||
|
||||
It's lighter, requiring only 32k of code space and 4k of RAM, which
|
||||
means it can run on stm32f103c8 (blue-pill) or even stm32g030c8, on the
|
||||
other hand, you can leave valuable space for more material or larger
|
||||
buffer areas.
|
||||
|
||||
It is simpler, out of the box, runs with no porting and configuration at
|
||||
all, does not depend on OS or file system, has good support for popular
|
||||
IDEs for Windows platforms like Keil, IAR, RT-Thread-Studio, and of
|
||||
course, supports linux-gcc development platforms.
|
||||
|
||||
It's smarter, with a unique C module mechanism that allows you to
|
||||
generate bindings automatically by simply writing the API for the C
|
||||
module in Python, and you don't need to deal with the headache of
|
||||
writing any macros or global tables manually. On the other hand, all C
|
||||
modules have sophisticated smart hints, even hinting at the types of
|
||||
your arguments .
|
||||
|
||||
--------------
|
||||
|
||||
|
||||
Why PikaScript + LVGL ?
|
||||
-----------------------
|
||||
|
||||
PikaScript now supports the main features of LVGL8, and these APIs are
|
||||
fully compatible with Micropython!
|
||||
|
||||
This means that you can continue to use already written code from
|
||||
Micropython, and then use less code space and RAM.
|
||||
|
||||
Enjoy detailed code hints down to the parameter type for a better
|
||||
programming experience
|
||||
|
||||
Use a more convenient IDE, such as vs-based simulation projects
|
||||
|
||||
|
||||
So how does it look like?
|
||||
-------------------------
|
||||
|
||||
Here are some examples of lvgl that PikaScript can already run, they are
|
||||
mainly from the lvgl documentation examples
|
||||
|
||||
|
||||
LV_ARC
|
||||
~~~~~~
|
||||
|
||||
.. code:: python
|
||||
|
||||
import pika_lvgl as lv
|
||||
import PikaStdLib
|
||||
mem = PikaStdLib.MemChecker()
|
||||
# Create an Arc
|
||||
arc = lv.arc(lv.screen_active())
|
||||
arc.set_end_angle(200)
|
||||
arc.set_size(150, 150)
|
||||
arc.center()
|
||||
print('mem used max: %0.2f kB' % (mem.getMax()))
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
|
||||
|
||||
LV_BAR
|
||||
~~~~~~
|
||||
|
||||
.. code:: python
|
||||
|
||||
import pika_lvgl as lv
|
||||
import PikaStdLib
|
||||
mem = PikaStdLib.MemChecker()
|
||||
bar1 = lv.bar(lv.screen_active())
|
||||
bar1.set_size(200, 20)
|
||||
bar1.center()
|
||||
bar1.set_value(70, lv.ANIM.OFF)
|
||||
print('mem used max: %0.2f kB' % (mem.getMax()))
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
|
||||
|
||||
LV_BTN
|
||||
~~~~~~
|
||||
|
||||
.. code:: python
|
||||
|
||||
import pika_lvgl as lv
|
||||
import PikaStdLib
|
||||
mem = PikaStdLib.MemChecker()
|
||||
def event_cb_1(evt):
|
||||
print('in evt1')
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
def event_cb_2(evt):
|
||||
print('in evt2')
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
btn1 = lv.btn(lv.screen_active())
|
||||
btn1.align(lv.ALIGN.TOP_MID, 0, 10)
|
||||
btn2 = lv.btn(lv.screen_active())
|
||||
btn2.align(lv.ALIGN.TOP_MID, 0, 50)
|
||||
btn1.add_event(event_cb_1, lv.EVENT.CLICKED, 0)
|
||||
btn2.add_event(event_cb_2, lv.EVENT.CLICKED, 0)
|
||||
print('mem used max: %0.2f kB' % (mem.getMax()))
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
|
||||
|
||||
LV_CHECKBOX
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. code:: python
|
||||
|
||||
import pika_lvgl as lv
|
||||
import PikaStdLib
|
||||
mem = PikaStdLib.MemChecker()
|
||||
cb = lv.checkbox(lv.screen_active())
|
||||
cb.set_text("Apple")
|
||||
cb.align(lv.ALIGN.TOP_LEFT, 0 ,0)
|
||||
cb = lv.checkbox(lv.screen_active())
|
||||
cb.set_text("Banana")
|
||||
cb.add_state(lv.STATE.CHECKED)
|
||||
cb.align(lv.ALIGN.TOP_LEFT, 0 ,30)
|
||||
cb = lv.checkbox(lv.screen_active())
|
||||
cb.set_text("Lemon")
|
||||
cb.add_state(lv.STATE.DISABLED)
|
||||
cb.align(lv.ALIGN.TOP_LEFT, 0 ,60)
|
||||
cb = lv.checkbox(lv.screen_active())
|
||||
cb.add_state(lv.STATE.CHECKED | lv.STATE.DISABLED)
|
||||
cb.set_text("Melon")
|
||||
cb.align(lv.ALIGN.TOP_LEFT, 0 ,90)
|
||||
print('mem used max: %0.2f kB' % (mem.getMax()))
|
||||
print('mem used now: %0.2f kB' % (mem.getNow()))
|
||||
|
||||
--------------
|
||||
|
||||
|
||||
How does it work?
|
||||
-----------------
|
||||
|
||||
PikaScript has a unique C module smart binding tool
|
||||
|
||||
Just write the Python interface in pika_lvgl.pyi (.pyi is the python
|
||||
interface file)
|
||||
|
||||
.. code:: python
|
||||
|
||||
# pika_lvgl.pyi
|
||||
class arc(lv_obj):
|
||||
def set_end_angle(self, angle: int): ...
|
||||
def set_bg_angles(self, start: int, end: int): ...
|
||||
def set_angles(self, start: int, end: int): ...
|
||||
|
||||
Then PikaScript's pre-compiler can automatically bind the following C
|
||||
functions, simply by naming the functions in the module_class_method
|
||||
format, without any additional work, and all binding and registration is
|
||||
done automatically.
|
||||
|
||||
.. code:: c
|
||||
|
||||
/* pika_lvgl_arc.c */
|
||||
void pika_lvgl_arc_set_end_angle(PikaObj* self, int angle) {
|
||||
lv_obj_t* lv_obj = obj_getPtr(self, "lv_obj");
|
||||
lv_arc_set_end_angle(lv_obj, angle);
|
||||
}
|
||||
void pika_lvgl_arc_set_bg_angles(PikaObj *self, int start, int end){
|
||||
lv_obj_t* lv_obj = obj_getPtr(self, "lv_obj");
|
||||
lv_arc_set_bg_angles(lv_obj, start, end);
|
||||
}
|
||||
void pika_lvgl_arc_set_angles(PikaObj *self, int start, int end){
|
||||
lv_obj_t* lv_obj = obj_getPtr(self, "lv_obj");
|
||||
lv_arc_set_angles(lv_obj, start, end);
|
||||
}
|
||||
|
||||
To use the module, just ``import pika_lvgl`` and the precompiler will
|
||||
automatically scan main.py and bind the ``pika_lvgl`` module
|
||||
|
||||
::
|
||||
|
||||
$ ./rust-msc-latest-win10.exe
|
||||
(pikascript) packages installed:
|
||||
pikascript-core==v1.10.0
|
||||
PikaStdLib==v1.10.0
|
||||
PikaStdDevice==v1.10.0
|
||||
(pikascript) pika compiler:
|
||||
scanning main.py...
|
||||
binding pika_lvgl.pyi...
|
||||
|
||||
The precompiler is written in Rust, runs on windows and linux, and is
|
||||
completely open source.
|
||||
|
||||
In addition to binding C modules, the precompiler compiles Python
|
||||
scripts to bytecode in the PC, reducing the size of the script and
|
||||
increasing its speed.
|
||||
|
||||
--------------
|
||||
|
||||
How can I use it?
|
||||
-----------------
|
||||
|
||||
The simulation repo on vs is available on
|
||||
https://github.com/pikasTech/lv_pikascript
|
||||
85
docs/integration/chip/espressif.rst
Normal file
85
docs/integration/chip/espressif.rst
Normal file
@@ -0,0 +1,85 @@
|
||||
=============================
|
||||
Espressif (ESP32 chip series)
|
||||
=============================
|
||||
|
||||
LVGL can be used and configured as a standard `ESP-IDF <https://github.com/espressif/esp-idf>`__ component.
|
||||
|
||||
More information about ESP-IDF build system can be found `here <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html>`__.
|
||||
|
||||
|
||||
LVGL demo project for ESP32
|
||||
---------------------------
|
||||
|
||||
We've created `lv_port_esp32 <https://github.com/lvgl/lv_port_esp32>`__,
|
||||
a project using ESP-IDF and LVGL to show one of the demos from
|
||||
`demos <https://github.com/lvgl/lvgl/demos>`__. You can configure the
|
||||
project to use one of the many supported display controllers and targets
|
||||
(chips).
|
||||
|
||||
See `lvgl_esp32_drivers <https://github.com/lvgl/lvgl_esp32_drivers>`__
|
||||
repository for a complete list of supported display and indev (touch)
|
||||
controllers and targets.
|
||||
|
||||
|
||||
Using LVGL in your ESP-IDF project
|
||||
----------------------------------
|
||||
|
||||
Prerequisites
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
- ESP-IDF v4.1 and above
|
||||
- ESP evaluation board with a display
|
||||
|
||||
|
||||
Obtaining LVGL
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
**Option 1:** git submodule
|
||||
|
||||
Simply clone LVGL into your ``project_root/components`` directory and it
|
||||
will be automatically integrated into the project. If the project is a
|
||||
git repository you can include LVGL as a git submodule:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
git submodule add https://github.com/lvgl/lvgl.git components/lvgl
|
||||
|
||||
The above command will clone LVGL's main repository into the
|
||||
``components/lvgl`` directory. LVGL includes a ``CMakeLists.txt`` file
|
||||
that sets some configuration options so you can use LVGL right away.
|
||||
|
||||
**Option 2:** IDF Component Manager
|
||||
|
||||
LVGL is also distributed through `IDF Component Manager <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html>`__.
|
||||
It allows users to seamlessly integrate `LVGL component <https://components.espressif.com/component/lvgl/lvgl>`__ into
|
||||
their project with following command:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
idf.py add-dependency lvgl/lvgl>=8.*
|
||||
|
||||
During next project build, LVGL component will be fetched from the
|
||||
component registry and added to project build.
|
||||
|
||||
|
||||
Configuration
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
When you are ready to configure LVGL, launch the configuration menu with
|
||||
``idf.py menuconfig`` in your project root directory, go to
|
||||
``Component config`` and then ``LVGL configuration``.
|
||||
|
||||
|
||||
Using lvgl_esp32_drivers in ESP-IDF project
|
||||
-------------------------------------------
|
||||
|
||||
You can also add ``lvgl_esp32_drivers`` as a "component". This component
|
||||
should be located inside a directory named "components" in your project
|
||||
root directory.
|
||||
|
||||
When your project is a git repository you can include
|
||||
``lvgl_esp32_drivers`` as a git submodule:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
git submodule add https://github.com/lvgl/lvgl_esp32_drivers.git components/lvgl_esp32_drivers
|
||||
10
docs/integration/chip/index.rst
Normal file
10
docs/integration/chip/index.rst
Normal file
@@ -0,0 +1,10 @@
|
||||
============
|
||||
Chip vendors
|
||||
============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
nxp
|
||||
stm32
|
||||
espressif
|
||||
278
docs/integration/chip/nxp.rst
Normal file
278
docs/integration/chip/nxp.rst
Normal file
@@ -0,0 +1,278 @@
|
||||
===
|
||||
NXP
|
||||
===
|
||||
|
||||
NXP has integrated LVGL into the MCUXpresso SDK packages for general
|
||||
purpose and crossover microcontrollers, allowing easy evaluation and
|
||||
migration into your product design.
|
||||
`Download an SDK for a supported board <https://www.nxp.com/design/software/embedded-software/littlevgl-open-source-graphics-library:LITTLEVGL-OPEN-SOURCE-GRAPHICS-LIBRARY?&tid=vanLITTLEVGL-OPEN-SOURCE-GRAPHICS-LIBRARY>`__
|
||||
today and get started with your next GUI application.
|
||||
|
||||
|
||||
Creating new project with LVGL
|
||||
------------------------------
|
||||
|
||||
Downloading the MCU SDK example project is recommended as a starting
|
||||
point. It comes fully configured with LVGL (and with PXP/VGLite support
|
||||
if the modules are present), no additional integration work is required.
|
||||
|
||||
|
||||
HW acceleration for NXP iMX RT platforms
|
||||
----------------------------------------
|
||||
|
||||
Depending on the RT platform used, the acceleration can be done by NXP
|
||||
PXP (PiXel Pipeline) and/or the Verisilicon GPU through an API named
|
||||
VGLite. Each accelerator has its own context that allows them to be used
|
||||
individually as well simultaneously (in LVGL multithreading mode).
|
||||
|
||||
|
||||
PXP accelerator
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Several drawing features in LVGL can be offloaded to the PXP engine. The
|
||||
CPU is available for other operations while the PXP is running. RTOS is
|
||||
required to block the LVGL drawing thread and switch to another task or
|
||||
suspend the CPU for power savings.
|
||||
|
||||
Supported draw callbacks are available in "src/draw/nxp/pxp/lv_draw_pxp.c":
|
||||
|
||||
.. code:: c
|
||||
|
||||
pxp_draw_ctx->base_draw.draw_img_decoded = lv_draw_pxp_img_decoded;
|
||||
pxp_draw_ctx->blend = lv_draw_pxp_blend;
|
||||
pxp_draw_ctx->base_draw.wait_for_finish = lv_draw_pxp_wait_for_finish;
|
||||
|
||||
|
||||
Features supported:
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
All operations can be used in conjunction with optional transparency.
|
||||
|
||||
- RGB565 and ARGB8888 color formats
|
||||
- Area fill with color
|
||||
- BLIT (BLock Image Transfer)
|
||||
- Screen Rotation (90, 180, 270 degree)
|
||||
- Color keying
|
||||
- Recoloring (color tint)
|
||||
- Image Rotation (90, 180, 270 degree)
|
||||
- RTOS integration layer
|
||||
- Default FreeRTOS and bare metal code provided
|
||||
- Combination of recolor and/or rotation + color key/alpha
|
||||
blend/transparency is supported. That is achieved by PXP in two
|
||||
steps:
|
||||
|
||||
- First step is to recolor/rotate the image to a temporary buffer (statically allocated)
|
||||
- Second step is required to handle color keying, alpha channel or to apply transparency
|
||||
|
||||
|
||||
Known limitations:
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- Rotation is not supported for images unaligned to blocks of 16x16
|
||||
pixels. PXP is set to process 16x16 blocks to optimize the system for
|
||||
memory bandwidth and image processing time. The output engine
|
||||
essentially truncates any output pixels after the desired number of
|
||||
pixels has been written. When rotating a source image and the output
|
||||
is not divisible by the block size, the incorrect pixels could be
|
||||
truncated and the final output image can look shifted.
|
||||
|
||||
|
||||
Basic configuration:
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- Select NXP PXP engine in lv_conf.h: Set :c:macro:`LV_USE_GPU_NXP_PXP` to ``1``
|
||||
- Enable default implementation for interrupt handling, PXP start
|
||||
function and automatic initialization: Set
|
||||
:c:macro:`LV_USE_GPU_NXP_PXP_AUTO_INIT` to ``1``
|
||||
- If :c:macro:`SDK_OS_FREE_RTOS` symbol is defined, FreeRTOS implementation
|
||||
will be used, otherwise bare metal code will be included
|
||||
|
||||
|
||||
Basic initialization:
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- If :c:macro:`LV_USE_GPU_NXP_PXP_AUTO_INIT` is enabled, no user code is
|
||||
required; PXP is initialized automatically in :cpp:func:`lv_init`
|
||||
- For manual PXP initialization, default configuration structure for
|
||||
callbacks can be used. Initialize PXP before calling :cpp:func:`lv_init`
|
||||
|
||||
.. code:: c
|
||||
|
||||
#if LV_USE_GPU_NXP_PXP
|
||||
#include "src/draw/nxp/pxp/lv_gpu_nxp_pxp.h"
|
||||
#endif
|
||||
...
|
||||
#if LV_USE_GPU_NXP_PXP
|
||||
PXP_COND_STOP(!lv_gpu_nxp_pxp_init(), "PXP init failed.");
|
||||
#endif
|
||||
|
||||
|
||||
Project setup:
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
- Add PXP related files to project:
|
||||
|
||||
- src/draw/nxp/pxp/lv_draw_pxp.c[.h]: draw context callbacks
|
||||
- src/draw/nxp/pxp/lv_draw_pxp_blend.c[.h]: fill and blit (with optional transformation)
|
||||
- src/draw/nxp/pxp/lv_gpu_nxp_pxp.c[.h]: init, uninit, run/wait PXP device
|
||||
- src/draw/nxp/pxp/lv_gpu_nxp_pxp_osa.c[.h]: OS abstraction (FreeRTOS or bare metal)
|
||||
|
||||
- optional, required only if :c:macro:`LV_USE_GPU_NXP_PXP_AUTO_INIT` is set to ``1``
|
||||
|
||||
- PXP related code depends on two drivers provided by MCU SDK. These
|
||||
drivers need to be added to project:
|
||||
|
||||
- fsl_pxp.c[.h]: PXP driver
|
||||
- fsl_cache.c[.h]: CPU cache handling functions
|
||||
|
||||
|
||||
Logging:
|
||||
^^^^^^^^
|
||||
|
||||
- By default, :c:macro:`LV_GPU_NXP_PXP_LOG_ERRORS` is enabled so that any PXP error will be seen on SDK debug console
|
||||
- By default, :c:macro:`LV_GPU_NXP_PXP_LOG_TRACES` is disabled. Enable it for tracing logs (like PXP limitations)
|
||||
|
||||
|
||||
Advanced configuration:
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- Implementation depends on multiple OS-specific functions. The struct
|
||||
:cpp:struct:`lv_nxp_pxp_cfg_t` with callback pointers is used as a parameter
|
||||
for the :cpp:func:`lv_gpu_nxp_pxp_init` function. Default implementation
|
||||
for FreeRTOS and bare metal is provided in lv_gpu_nxp_pxp_osa.c
|
||||
|
||||
- :cpp:func:`pxp_interrupt_init`: Initialize PXP interrupt (HW setup, OS setup)
|
||||
- :cpp:func:`pxp_interrupt_deinit`: Deinitialize PXP interrupt (HW setup, OS setup)
|
||||
- :cpp:func:`pxp_run`: Start PXP job. Use OS-specific mechanism to block drawing thread.
|
||||
PXP must finish drawing before leaving this function.
|
||||
|
||||
- Area threshold (size limit) is configurable and used to decide
|
||||
whether the area will be processed by PXP or not. Areas smaller than
|
||||
the defined value will be processed by CPU and those bigger than the
|
||||
threshold will be processed by PXP. The threshold is defined as a
|
||||
macro in lv_draw_pxp.c
|
||||
|
||||
- :c:macro:`LV_GPU_NXP_PXP_SIZE_LIMIT`: size threshold for fill/blit (with optional transformation)
|
||||
|
||||
|
||||
VGLite accelerator
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Extra drawing features in LVGL can be handled by the VGLite engine. The
|
||||
CPU is available for other operations while the VGLite is running. An
|
||||
RTOS is required to block the LVGL drawing thread and switch to another
|
||||
task or suspend the CPU for power savings.
|
||||
|
||||
Supported draw callbacks are available in "src/draw/nxp/vglite/lv_draw_vglite.c":
|
||||
|
||||
.. code:: c
|
||||
|
||||
vglite_draw_ctx->base_draw.init_buf = lv_draw_vglite_init_buf;
|
||||
vglite_draw_ctx->base_draw.draw_line = lv_draw_vglite_line;
|
||||
vglite_draw_ctx->base_draw.draw_arc = lv_draw_vglite_arc;
|
||||
vglite_draw_ctx->base_draw.draw_rect = lv_draw_vglite_rect;
|
||||
vglite_draw_ctx->base_draw.draw_img_decoded = lv_draw_vglite_img_decoded;
|
||||
vglite_draw_ctx->blend = lv_draw_vglite_blend;
|
||||
vglite_draw_ctx->base_draw.wait_for_finish = lv_draw_vglite_wait_for_finish;
|
||||
|
||||
.. _features-supported-1:
|
||||
|
||||
|
||||
Features supported:
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
All operations can be used in conjunction with optional transparency.
|
||||
|
||||
- RGB565 and ARGB8888 color formats
|
||||
- Area fill with color
|
||||
- BLIT (BLock Image Transfer)
|
||||
- Image Rotation (any degree with decimal)
|
||||
- Image Scale
|
||||
- Draw rectangle background with optional radius or gradient
|
||||
- Blit rectangle background image
|
||||
- Draw rectangle border/outline with optional rounded corners
|
||||
- Draw arc with optional rounded ending
|
||||
- Draw line or dashed line with optional rounded ending
|
||||
|
||||
.. _known-limitations-1:
|
||||
|
||||
|
||||
Known limitations:
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- Source image alignment: The byte alignment requirement for a pixel
|
||||
depends on the specific pixel format. Both buffer address and buffer
|
||||
stride must be aligned. As general rule, the alignment is set to 16
|
||||
pixels. This makes the buffer address alignment to be 32 bytes for
|
||||
RGB565 and 64 bytes for ARGB8888.
|
||||
- For pixel engine (PE) destination, the alignment should be 64 bytes
|
||||
for all tiled (4x4) buffer layouts. The pixel engine has no
|
||||
additional alignment requirement for linear buffer layouts
|
||||
(:c:macro:`VG_LITE_LINEAR`).
|
||||
|
||||
.. _basic-configuration-1:
|
||||
|
||||
|
||||
Basic configuration:
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- Select NXP VGLite engine in lv_conf.h: Set :c:macro:`LV_USE_GPU_NXP_VG_LITE` to 1
|
||||
- :c:macro:`SDK_OS_FREE_RTOS` symbol needs to be defined so that the FreeRTOS implementation will be used
|
||||
|
||||
.. _basic-initialization-1:
|
||||
|
||||
Basic initialization:
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- Initialize VGLite before calling :cpp:func:`lv_init` by specifying the
|
||||
width/height of tessellation window. Value should be a multiple of
|
||||
16; minimum value is 16 pixels, maximum cannot be greater than the
|
||||
frame width. If less than or equal to 0, then no tessellation buffer
|
||||
is created, in which case VGLite is initialized only for blitting.
|
||||
|
||||
.. code:: c
|
||||
|
||||
#if LV_USE_GPU_NXP_VG_LITE
|
||||
#include "vg_lite.h"
|
||||
#endif
|
||||
...
|
||||
#if LV_USE_GPU_NXP_VG_LITE
|
||||
VG_LITE_COND_STOP(vg_lite_init(64, 64) != VG_LITE_SUCCESS, "VGLite init failed.");
|
||||
#endif
|
||||
|
||||
.. _project-setup-1:
|
||||
|
||||
Project setup:
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
- Add VGLite related files to project:
|
||||
|
||||
- src/draw/nxp/vglite/lv_draw_vglite.c[.h]: draw context callbacks
|
||||
- src/draw/nxp/vglite/lv_draw_vglite_blend.c[.h]: fill and blit (with optional transformation)
|
||||
- src/draw/nxp/vglite/lv_draw_vglite_rect.c[.h]: draw rectangle
|
||||
- src/draw/nxp/vglite/lv_draw_vglite_arc.c[.h]: draw arc
|
||||
- src/draw/nxp/vglite/lv_draw_vglite_line.c[.h]: draw line
|
||||
- src/draw/nxp/vglite/lv_vglite_buf.c[.h]: init/get vglite buffer
|
||||
- src/draw/nxp/vglite/lv_vglite_utils.c[.h]: function helpers
|
||||
|
||||
.. _logging-1:
|
||||
|
||||
Logging:
|
||||
^^^^^^^^
|
||||
|
||||
- By default, :c:macro:`LV_GPU_NXP_VG_LITE_LOG_ERRORS` is enabled so that any VGLite error will be seen on SDK debug console
|
||||
- By default, :c:macro:`LV_GPU_NXP_VG_LITE_LOG_TRACES` is disabled. Enable it
|
||||
for tracing logs (like blit split workaround or VGLite fallback to CPU due to any error on the driver)
|
||||
|
||||
.. _advanced-configuration-1:
|
||||
|
||||
Advanced configuration:
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- Area threshold (size limit) is configurable and used to decide
|
||||
whether the area will be processed by VGLite or not. Areas smaller
|
||||
than the defined value will be processed by CPU and those bigger than
|
||||
the threshold will be processed by VGLite. The threshold is defined
|
||||
as a macro in lv_draw_vglite.c
|
||||
|
||||
- :c:macro:`LV_GPU_NXP_VG_LITE_SIZE_LIMIT`: size threshold for fill/blit (with optional transformation)
|
||||
269
docs/integration/chip/stm32.rst
Normal file
269
docs/integration/chip/stm32.rst
Normal file
@@ -0,0 +1,269 @@
|
||||
=====
|
||||
STM32
|
||||
=====
|
||||
|
||||
LVGL Can be added to `STM32CubeIDE <https://www.st.com/en/development-tools/stm32cubeide.html>`__
|
||||
in a similar fashion to any other Eclipse-based IDE.
|
||||
|
||||
Including LVGL in a Project
|
||||
---------------------------
|
||||
|
||||
- Create or open a project in STM32CubeIDE.
|
||||
- Copy the entire LVGL folder to *[project_folder]/Drivers/lvgl*.
|
||||
- In the STM32CubeIDE **Project Explorer** pane: right click on the
|
||||
LVGL folder that you copied (you may need to refresh the view first
|
||||
before it will appear), and select **Add/remove include path…**. If
|
||||
this doesn't appear, or doesn't work, you can review your project
|
||||
include paths under the **Project** -> **Properties** menu, and then
|
||||
navigating to **C/C++ Build** -> **Settings** -> **Include paths**, and
|
||||
ensuring that the LVGL directory is listed.
|
||||
|
||||
Now that the source files are included in your project, follow the
|
||||
instructions for `Porting <https://docs.lvgl.io/master/porting/project.html>`__ your
|
||||
project to create the ``lv_conf.h`` file, and initialise the display.
|
||||
|
||||
Bare Metal Example
|
||||
------------------
|
||||
|
||||
A minimal example using STM32CubeIDE, and HAL. \* When setting up
|
||||
**Pinout and Configuration** using the **Device Configuration Tool**,
|
||||
select **System Core** -> **SYS** and ensure that **Timebase Source** is
|
||||
set to **SysTick**. \* Configure any other peripherals (including the
|
||||
LCD panel), and initialise them in *main.c*. \* ``#include "lvgl.h"`` in
|
||||
the *main.c* file. \* Create some frame buffer(s) as global variables:
|
||||
|
||||
.. code:: c
|
||||
|
||||
//Frame buffers
|
||||
/*Static or global buffer(s). The second buffer is optional*/
|
||||
static lv_color_t buf_1[BUFF_SIZE]; //TODO: Chose a buffer size. DISPLAY_WIDTH * 10 is one suggestion.
|
||||
static lv_color_t buf_2[BUFF_SIZE];
|
||||
|
||||
- In your ``main()`` function, after initialising your CPU,
|
||||
peripherals, and LCD panel, call :cpp:func:`lv_init` to initialise LVGL.
|
||||
You can then create the display driver using
|
||||
:cpp:func:`lv_disp_create`, and register the frame buffers using
|
||||
:cpp:func:`lv_disp_set_draw_buffers`.
|
||||
|
||||
.. code:: c
|
||||
|
||||
//Initialise LVGL UI library
|
||||
lv_init();
|
||||
|
||||
lv_disp_t * disp = lv_disp_create(WIDTH, HEIGHT); /*Basic initialization with horizontal and vertical resolution in pixels*/
|
||||
lv_disp_set_flush_cb(disp, my_flush_cb); /*Set a flush callback to draw to the display*/
|
||||
lv_disp_set_draw_buffers(disp, buf_1, buf_2, sizeof(buf_1), LV_DISP_RENDER_MODE_PARTIAL); /*Set an initialized buffer*/
|
||||
|
||||
- Create some dummy objects to test the output:
|
||||
|
||||
.. code:: c
|
||||
|
||||
// Change the active screen's background color
|
||||
lv_obj_set_style_bg_color(lv_screen_active(), lv_color_hex(0x003a57), LV_PART_MAIN);
|
||||
lv_obj_set_style_text_color(lv_screen_active(), lv_color_hex(0xffffff), LV_PART_MAIN);
|
||||
|
||||
/*Create a spinner*/
|
||||
lv_obj_t * spinner = lv_spinner_create(lv_screen_active(), 1000, 60);
|
||||
lv_obj_set_size(spinner, 64, 64);
|
||||
lv_obj_align(spinner, LV_ALIGN_BOTTOM_MID, 0, 0);
|
||||
|
||||
- Add a call to :cpp:func:`lv_timer_handler` inside your ``while(1)`` loop:
|
||||
|
||||
.. code:: c
|
||||
|
||||
/* Infinite loop */
|
||||
while (1)
|
||||
{
|
||||
lv_timer_handler();
|
||||
HAL_Delay(5);
|
||||
}
|
||||
|
||||
- Add a call to :cpp:func:`lv_tick_inc` inside the :cpp:func:`SysTick_Handler`
|
||||
function. Open the *stm32xxxx_it.c* file (the name will depend on
|
||||
your specific MCU), and update the :cpp:func:`SysTick_Handler` function:
|
||||
|
||||
.. code:: c
|
||||
|
||||
void SysTick_Handler(void)
|
||||
{
|
||||
/* USER CODE BEGIN SysTick_IRQn 0 */
|
||||
|
||||
HAL_SYSTICK_IRQHandler();
|
||||
lv_tick_inc(1);
|
||||
#ifdef USE_RTOS_SYSTICK
|
||||
osSystickHandler();
|
||||
#endif
|
||||
|
||||
/* USER CODE END SysTick_IRQn 0 */
|
||||
HAL_IncTick();
|
||||
/* USER CODE BEGIN SysTick_IRQn 1 */
|
||||
|
||||
/* USER CODE END SysTick_IRQn 1 */
|
||||
}
|
||||
|
||||
- Finally, write the callback function, ``my_flush_cb``, which will
|
||||
send the display buffer to your LCD panel. Below is one example, but
|
||||
it will vary depending on your setup.
|
||||
|
||||
.. code:: c
|
||||
|
||||
void my_flush_cb(lv_disp_t * disp, const lv_area_t * area, lv_color_t * color_p)
|
||||
{
|
||||
//Set the drawing region
|
||||
set_draw_window(area->x1, area->y1, area->x2, area->y2);
|
||||
|
||||
int height = area->y2 - area->y1 + 1;
|
||||
int width = area->x2 - area->x1 + 1;
|
||||
|
||||
//We will do the SPI write manually here for speed
|
||||
HAL_GPIO_WritePin(DC_PORT, DC_PIN, GPIO_PIN_SET);
|
||||
//CS low to begin data
|
||||
HAL_GPIO_WritePin(CS_PORT, CS_PIN, GPIO_PIN_RESET);
|
||||
|
||||
//Write colour to each pixel
|
||||
for (int i = 0; i < width * height; i++) {
|
||||
uint16_t color_full = (color_p->red << 11) | (color_p->green << 5) | (color_p->blue);
|
||||
parallel_write(color_full);
|
||||
|
||||
color_p++;
|
||||
}
|
||||
|
||||
//Return CS to high
|
||||
HAL_GPIO_WritePin(CS_PORT, CS_PIN, GPIO_PIN_SET);
|
||||
|
||||
/* IMPORTANT!!!
|
||||
* Inform the graphics library that you are ready with the flushing*/
|
||||
lv_disp_flush_ready(disp);
|
||||
}
|
||||
|
||||
FreeRTOS Example
|
||||
----------------
|
||||
|
||||
A minimal example using STM32CubeIDE, HAL, and CMSISv1 (FreeRTOS). *Note
|
||||
that we have not used Mutexes in this example, however LVGL is* **NOT**
|
||||
*thread safe and so Mutexes should be used*. See: :ref:`os_interrupt`
|
||||
\* ``#include "lvgl.h"`` \* Create your frame buffer(s) as global
|
||||
variables:
|
||||
|
||||
.. code:: c
|
||||
|
||||
//Frame buffers
|
||||
/*A static or global variable to store the buffers*/
|
||||
static lv_disp_draw_buf_t disp_buf;
|
||||
|
||||
/*Static or global buffer(s). The second buffer is optional*/
|
||||
static lv_color_t buf_1[BUFF_SIZE]; //TODO: Declare your own BUFF_SIZE appropriate to your system.
|
||||
static lv_color_t buf_2[BUFF_SIZE];
|
||||
|
||||
- In your ``main`` function, after your peripherals (SPI, GPIOs, LCD
|
||||
etc) have been initialised, initialise LVGL using :cpp:func:`lv_init`,
|
||||
register the frame buffers using :cpp:func:`lv_disp_draw_buf_init`, and
|
||||
create a new display driver using :cpp:func:`lv_disp_drv_init`.
|
||||
|
||||
.. code:: c
|
||||
|
||||
//Initialise LVGL UI library
|
||||
lv_init();
|
||||
lv_disp_draw_buf_init(&disp_buf, buf_1, buf_2, BUFF_SIZE);
|
||||
|
||||
static lv_disp_drv_t disp_drv; /*A variable to hold the drivers. Must be static or global.*/
|
||||
lv_disp_drv_init(&disp_drv); /*Basic initialization*/
|
||||
disp_drv.draw_buf = &disp_buf; /*Set an initialized buffer*/
|
||||
disp_drv.flush_cb = my_flush_cb; /*Set a flush callback to draw to the display*/
|
||||
disp_drv.hor_res = WIDTH; /*Set the horizontal resolution in pixels*/
|
||||
disp_drv.ver_res = HEIGHT; /*Set the vertical resolution in pixels*/
|
||||
|
||||
lv_disp_t * disp;
|
||||
disp = lv_disp_drv_register(&disp_drv); /*Register the driver and save the created display objects*/
|
||||
|
||||
// Register the touch controller with LVGL - Not included here for brevity.
|
||||
|
||||
- Create some dummy objects to test the output:
|
||||
|
||||
.. code:: c
|
||||
|
||||
// Change the active screen's background color
|
||||
lv_obj_set_style_bg_color(lv_screen_active(), lv_color_hex(0x003a57), LV_PART_MAIN);
|
||||
lv_obj_set_style_text_color(lv_screen_active(), lv_color_hex(0xffffff), LV_PART_MAIN);
|
||||
|
||||
/*Create a spinner*/
|
||||
lv_obj_t * spinner = lv_spinner_create(lv_screen_active(), 1000, 60);
|
||||
lv_obj_set_size(spinner, 64, 64);
|
||||
lv_obj_align(spinner, LV_ALIGN_BOTTOM_MID, 0, 0);
|
||||
|
||||
- Create two threads to call :cpp:func:`lv_timer_handler`, and
|
||||
:cpp:func:`lv_tick_inc`.You will need two ``osThreadId`` handles for
|
||||
CMSISv1. These don't strictly have to be globally accessible in this
|
||||
case, however STM32Cube code generation does by default. If you are
|
||||
using CMSIS and STM32Cube code generation it should look something
|
||||
like this:
|
||||
|
||||
.. code:: c
|
||||
|
||||
//Thread Handles
|
||||
osThreadId lvgl_tickHandle;
|
||||
osThreadId lvgl_timerHandle;
|
||||
|
||||
/* definition and creation of lvgl_tick */
|
||||
osThreadDef(lvgl_tick, LGVLTick, osPriorityNormal, 0, 1024);
|
||||
lvgl_tickHandle = osThreadCreate(osThread(lvgl_tick), NULL);
|
||||
|
||||
//LVGL update timer
|
||||
osThreadDef(lvgl_timer, LVGLTimer, osPriorityNormal, 0, 1024);
|
||||
lvgl_timerHandle = osThreadCreate(osThread(lvgl_timer), NULL);
|
||||
|
||||
- And create the thread functions:
|
||||
|
||||
.. code:: c
|
||||
|
||||
/* LVGL timer for tasks. */
|
||||
void LVGLTimer(void const * argument)
|
||||
{
|
||||
for(;;)
|
||||
{
|
||||
lv_timer_handler();
|
||||
osDelay(20);
|
||||
}
|
||||
}
|
||||
/* LVGL tick source */
|
||||
void LVGLTick(void const * argument)
|
||||
{
|
||||
for(;;)
|
||||
{
|
||||
lv_tick_inc(10);
|
||||
osDelay(10);
|
||||
}
|
||||
}
|
||||
|
||||
- Finally, create the ``my_flush_cb`` function to output the frame
|
||||
buffer to your LCD. The specifics of this function will vary
|
||||
depending on which MCU features you are using. Below is an example
|
||||
for a typical MCU interface.
|
||||
|
||||
.. code:: c
|
||||
|
||||
void my_flush_cb(lv_disp_drv_t * disp_drv, const lv_area_t * area, lv_color_t * color_p)
|
||||
{
|
||||
//Set the drawing region
|
||||
set_draw_window(area->x1, area->y1, area->x2, area->y2);
|
||||
|
||||
int height = area->y2 - area->y1 + 1;
|
||||
int width = area->x2 - area->x1 + 1;
|
||||
|
||||
//Begin SPI Write for DATA
|
||||
HAL_GPIO_WritePin(DC_PORT, DC_PIN, GPIO_PIN_SET);
|
||||
HAL_GPIO_WritePin(CS_PORT, CS_PIN, GPIO_PIN_RESET);
|
||||
|
||||
//Write colour to each pixel
|
||||
for (int i = 0; i < width * height; i++) {
|
||||
parallel_write(color_p->full);
|
||||
color_p++;
|
||||
}
|
||||
|
||||
//Return CS to high
|
||||
HAL_GPIO_WritePin(CS_PORT, CS_PIN, GPIO_PIN_SET);
|
||||
|
||||
/* IMPORTANT!!!
|
||||
* Inform the graphics library that you are ready with the flushing*/
|
||||
lv_disp_flush_ready(disp_drv);
|
||||
}
|
||||
5
docs/integration/driver/display/ili9341.rst
Normal file
5
docs/integration/driver/display/ili9341.rst
Normal file
@@ -0,0 +1,5 @@
|
||||
=======
|
||||
ILI9341
|
||||
=======
|
||||
|
||||
TODO
|
||||
8
docs/integration/driver/display/index.rst
Normal file
8
docs/integration/driver/display/index.rst
Normal file
@@ -0,0 +1,8 @@
|
||||
=======
|
||||
Drivers
|
||||
=======
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
ili9341
|
||||
9
docs/integration/driver/index.rst
Normal file
9
docs/integration/driver/index.rst
Normal file
@@ -0,0 +1,9 @@
|
||||
=======
|
||||
Drivers
|
||||
=======
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
display/index
|
||||
touchpad/index
|
||||
5
docs/integration/driver/touchpad/ft6x36.rst
Normal file
5
docs/integration/driver/touchpad/ft6x36.rst
Normal file
@@ -0,0 +1,5 @@
|
||||
======
|
||||
FT6X36
|
||||
======
|
||||
|
||||
TODO
|
||||
8
docs/integration/driver/touchpad/index.rst
Normal file
8
docs/integration/driver/touchpad/index.rst
Normal file
@@ -0,0 +1,8 @@
|
||||
=======
|
||||
Touchpad
|
||||
=======
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
ft6x36
|
||||
104
docs/integration/framework/arduino.rst
Normal file
104
docs/integration/framework/arduino.rst
Normal file
@@ -0,0 +1,104 @@
|
||||
=======
|
||||
Arduino
|
||||
=======
|
||||
|
||||
The `LVGL library <https://github.com/lvgl/lvgl>`__ is directly available as Arduino libraries.
|
||||
|
||||
Note that you need to choose a board powerful enough to run LVGL and
|
||||
your GUI. See the `requirements of LVGL <https://docs.lvgl.io/master/intro/index.html#requirements>`__.
|
||||
|
||||
For example ESP32 is a good candidate to create UI's with LVGL.
|
||||
|
||||
Get the LVGL Arduino library
|
||||
----------------------------
|
||||
|
||||
LVGL can be installed via the Arduino IDE Library Manager or as a .ZIP library.
|
||||
|
||||
You can `Download <https://github.com/lvgl/lvgl/archive/refs/heads/master.zip>`__
|
||||
the latest version of LVGL from GitHub and simply copy it to Arduino's
|
||||
library folder.
|
||||
|
||||
Set up drivers
|
||||
--------------
|
||||
|
||||
To get started it's recommended to use `TFT_eSPI <https://github.com/Bodmer/TFT_eSPI>`__ library as a TFT
|
||||
driver to simplify testing. To make it work, setup ``TFT_eSPI``
|
||||
according to your TFT display type via editing either:
|
||||
|
||||
- ``User_Setup.h``
|
||||
- or by selecting a configuration in the ``User_Setup_Select.h``
|
||||
|
||||
Both files are located in ``TFT_eSPI`` library's folder.
|
||||
|
||||
|
||||
Configure LVGL
|
||||
--------------
|
||||
|
||||
LVGL has its own configuration file called ``lv_conf.h``. When LVGL is
|
||||
installed, follow these configuration steps:
|
||||
|
||||
1. Go to the directory of the installed Arduino libraries
|
||||
2. Go to ``lvgl`` and copy ``lv_conf_template.h`` as ``lv_conf.h`` into the Arduino Libraries directory next to the ``lvgl`` library folder.
|
||||
3. Open ``lv_conf.h`` and change the first ``#if 0`` to ``#if 1`` to enable the content of the file
|
||||
4. Set the color depth of you display in :c:macro:`LV_COLOR_DEPTH`
|
||||
5. Set :c:macro:`LV_TICK_CUSTOM`
|
||||
|
||||
Finally the layout with ``lv_conf.h`` should look like this:
|
||||
|
||||
::
|
||||
|
||||
arduino
|
||||
|-libraries
|
||||
|-lvgl
|
||||
|-other_lib_1
|
||||
|-other_lib_2
|
||||
|-lv_conf.h
|
||||
|
||||
|
||||
Initialize and run LVGL
|
||||
-----------------------
|
||||
|
||||
Take a look at `LVGL_Arduino.ino <https://github.com/lvgl/lvgl/blob/master/examples/arduino/LVGL_Arduino/LVGL_Arduino.ino>`__
|
||||
to see how to initialize LVGL. ``TFT_eSPI`` is used as the display driver.
|
||||
|
||||
In the INO file you can see how to register a display and a touchpad for
|
||||
LVGL and call an example.
|
||||
|
||||
|
||||
Use the examples and demos
|
||||
--------------------------
|
||||
|
||||
Note that, there is no dedicated INO file for every example. Instead,
|
||||
you can load an example by calling an ``lv_example_...`` function. For
|
||||
example :cpp:func:`lv_example_btn_1`.
|
||||
|
||||
:important: Due to some the limitations of Arduino's build system you
|
||||
need to copy ``lvgl/examples`` to ``lvgl/src/examples``. Similarly for
|
||||
the demos ``lvgl/demos`` to ``lvgl/src/demos``.
|
||||
|
||||
|
||||
Debugging and logging
|
||||
---------------------
|
||||
|
||||
LVGL can display debug information in case of trouble. In the
|
||||
``LVGL_Arduino.ino`` example there is a ``my_print`` method, which sends
|
||||
this debug information to the serial interface. To enable this feature
|
||||
you have to edit the ``lv_conf.h`` file and enable logging in the
|
||||
section ``log settings``:
|
||||
|
||||
.. code:: c
|
||||
|
||||
/*Log settings*/
|
||||
#define USE_LV_LOG 1 /*Enable/disable the log module*/
|
||||
#if LV_USE_LOG
|
||||
/* How important log should be added:
|
||||
* LV_LOG_LEVEL_TRACE A lot of logs to give detailed information
|
||||
* LV_LOG_LEVEL_INFO Log important events
|
||||
* LV_LOG_LEVEL_WARN Log if something unwanted happened but didn't cause a problem
|
||||
* LV_LOG_LEVEL_ERROR Only critical issue, when the system may fail
|
||||
* LV_LOG_LEVEL_NONE Do not log anything
|
||||
*/
|
||||
# define LV_LOG_LEVEL LV_LOG_LEVEL_WARN
|
||||
|
||||
After enabling the log module and setting :c:macro:`LV_LOG_LEVEL` accordingly, the
|
||||
output log is sent to the ``Serial`` port @ 115200 bps.
|
||||
11
docs/integration/framework/index.rst
Normal file
11
docs/integration/framework/index.rst
Normal file
@@ -0,0 +1,11 @@
|
||||
==========
|
||||
Frameworks
|
||||
==========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
arduino
|
||||
platformio
|
||||
tasmota-berry
|
||||
|
||||
5
docs/integration/framework/platformio.rst
Normal file
5
docs/integration/framework/platformio.rst
Normal file
@@ -0,0 +1,5 @@
|
||||
==========
|
||||
Platformio
|
||||
==========
|
||||
|
||||
TODO
|
||||
105
docs/integration/framework/tasmota-berry.rst
Normal file
105
docs/integration/framework/tasmota-berry.rst
Normal file
@@ -0,0 +1,105 @@
|
||||
=================
|
||||
Tasmota and berry
|
||||
=================
|
||||
|
||||
What is Tasmota?
|
||||
----------------
|
||||
|
||||
`Tasmota <https://github.com/arendst/Tasmota>`__ is a widely used
|
||||
open-source firmware for ESP8266 and EPS32 based devices. It supports a
|
||||
wide variety of devices, sensors and integrations to Home Automation and
|
||||
Cloud services. Tasmota firmware is downloaded more than 200,000 times
|
||||
each month, and has an active and growing community.
|
||||
|
||||
Tasmota provides access to hundreds of supported devices, full support
|
||||
of MQTT, HTTP(S), integration with major Home Automation systems, myriad
|
||||
of sensors, IR, RF, Zigbee, Bluetooth, AWS IoT, Azure IoT, Alexa and
|
||||
many more.
|
||||
|
||||
What is Berry?
|
||||
--------------
|
||||
|
||||
`Berry <https://github.com/berry-lang/berry>`__ is a ultra-lightweight
|
||||
dynamically typed embedded scripting language. It is designed for
|
||||
lower-performance embedded devices. The interpreter of Berry include a
|
||||
one-pass compiler and register-based VM, all the code is written in ANSI
|
||||
C99. Berry offers a syntax very similar to Python, and is inspired from
|
||||
LUA VM. It is fully integrated in Tasmota
|
||||
|
||||
Highlights of Berry
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Berry has the following advantages:
|
||||
|
||||
- Lightweight: A well-optimized interpreter with very little resources. Ideal for use in microprocessors.
|
||||
- Fast: optimized one-pass bytecode compiler and register-based virtual machine.
|
||||
- Powerful: supports imperative programming, object-oriented programming, functional programming.
|
||||
- Flexible: Berry is a dynamic type script, and it's intended for embedding in applications.
|
||||
It can provide good dynamic scalability for the host system.
|
||||
- Simple: simple and natural syntax, support garbage collection, and easy to use FFI (foreign function interface).
|
||||
- RAM saving: With compile-time object construction, most of the constant objects are stored
|
||||
in read-only code data segments, so the RAM usage of the interpreter is very low when it starts.
|
||||
|
||||
All features are detailed in the `Berry Reference Manual <https://github.com/berry-lang/berry/wiki/Reference>`__
|
||||
|
||||
--------------
|
||||
|
||||
Why LVGL + Tasmota + Berry?
|
||||
---------------------------
|
||||
|
||||
In 2021, Tasmota added full support of LVGL for ESP32 based devices. It
|
||||
also introduced the Berry scripting language, a small-footprint language
|
||||
similar to Python and fully integrated in Tasmota.
|
||||
|
||||
A comprehensive mapping of LVGL in Berry language is now available,
|
||||
similar to the mapping of Micropython. It allows to use +98% of all LVGL
|
||||
features. It is also possible to write custom widgets in Berry.
|
||||
|
||||
Versions supported: LVGL v8.0.2, LodePNG v20201017, Freetype 2.10.4
|
||||
|
||||
Tasmota + Berry + LVGL could be used for:
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- Fast prototyping GUI.
|
||||
- Shortening the cycle of changing and fine-tuning the GUI.
|
||||
- Modelling the GUI in a more abstract way by defining reusable composite objects, taking
|
||||
advantage of Berry's language features such as Inheritance, Closures, Exception Handling…
|
||||
- Make LVGL accessible to a larger audience. No need to know C to create a nice GUI on an embedded system.
|
||||
|
||||
A higher level interface compatible with
|
||||
`OpenHASP <https://github.com/HASwitchPlate/openHASP>`__
|
||||
is also under development.
|
||||
|
||||
--------------
|
||||
|
||||
So what does it look like?
|
||||
--------------------------
|
||||
|
||||
TL;DR: Similar to MicroPython, 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:: python
|
||||
|
||||
lv.start() # start LVGL
|
||||
scr = lv.screen_active() # get default screen
|
||||
btn = lv.btn(scr) # create button
|
||||
btn.center()
|
||||
label = lv.label(btn) # create a label in the button
|
||||
label.set_text("Button") # set a label to the button
|
||||
|
||||
How can I use it?
|
||||
-----------------
|
||||
|
||||
You can start in less than 10 minutes on a M5Stack or equivalent device
|
||||
in less than 10 minutes in this `short tutorial <https://tasmota.github.io/docs/LVGL_in_10_minutes/>`__
|
||||
|
||||
Where can I find more information?
|
||||
----------------------------------
|
||||
|
||||
- `Tasmota Documentation <https://tasmota.github.io/docs/>`__
|
||||
- `Berry Documentation <https://github.com/berry-lang/berry/wiki/Reference>`__
|
||||
- `Tasmota LVGL Berry documentation <https://tasmota.github.io/docs/LVGL/>`__
|
||||
9
docs/integration/ide/index.rst
Normal file
9
docs/integration/ide/index.rst
Normal file
@@ -0,0 +1,9 @@
|
||||
====
|
||||
IDEs
|
||||
====
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
pc-simulator
|
||||
mdk
|
||||
5
docs/integration/ide/mdk.rst
Normal file
5
docs/integration/ide/mdk.rst
Normal file
@@ -0,0 +1,5 @@
|
||||
===
|
||||
MDK
|
||||
===
|
||||
|
||||
TODO
|
||||
152
docs/integration/ide/pc-simulator.rst
Normal file
152
docs/integration/ide/pc-simulator.rst
Normal file
@@ -0,0 +1,152 @@
|
||||
.. _simulator:
|
||||
|
||||
===============
|
||||
Simulator on PC
|
||||
===============
|
||||
|
||||
You can try out LVGL **using only your PC** (i.e. without any
|
||||
development boards). LVGL will run on a simulator environment on the PC
|
||||
where anyone can write and experiment with real LVGL applications.
|
||||
|
||||
Using the simulator on a PC has the following advantages:
|
||||
|
||||
- Hardware independent: Write code, run it on the PC and see the result on a monitor.
|
||||
- Cross-platform: Any Windows, Linux or macOS system can run the PC simulator.
|
||||
- Portability: The written code is portable, which means you can simply copy it when migrating to embedded hardware.
|
||||
- Easy Validation: The simulator is also very useful to report bugs because it
|
||||
provides a common platform for every user. So it's a good idea to
|
||||
reproduce a bug in the simulator and use that code snippet in the
|
||||
`Forum <https://forum.lvgl.io>`__.
|
||||
|
||||
|
||||
Select an IDE
|
||||
-------------
|
||||
|
||||
The simulator is ported to various IDEs (Integrated Development Environments).
|
||||
Choose your favorite IDE, read its README on GitHub, download the project, and load it to the IDE.
|
||||
|
||||
- `Eclipse with SDLdriver <https://github.com/lvgl/lv_sim_eclipse_sdl>`__: Recommended on Linux and Mac
|
||||
- `CodeBlocks <https://github.com/lvgl/lv_sim_codeblocks_win>`__: Recommended on Windows
|
||||
- `VisualStudio <https://github.com/lvgl/lv_sim_visual_studio_sdl>`__: For Windows
|
||||
- `VSCode with SDL driver <https://github.com/lvgl/lv_sim_vscode_sdl>`__: Recommended on Linux and Mac
|
||||
- `PlatformIO with SDL driver <https://github.com/lvgl/lv_platformio>`__: Recommended on Linux and Mac
|
||||
- `MDK with FastModel <https://github.com/lvgl/lv_port_an547_cm55_sim>`__: For Windows
|
||||
|
||||
External project not maintained by the LVGL organization:
|
||||
|
||||
- `QT Creator <https://github.com/Varanda-Labs/lvgl-qt-sim>`__: Cross platform
|
||||
|
||||
You can use any IDE for development but, for simplicity, the
|
||||
configuration for Eclipse CDT is what we'll focus on in this tutorial.
|
||||
The following section describes the set-up guide of Eclipse CDT in more
|
||||
detail.
|
||||
|
||||
:Note: If you are on Windows, it's usually better to use the Visual
|
||||
Studio or CodeBlocks projects instead. They work out of the box without
|
||||
requiring extra steps.**
|
||||
|
||||
Set-up Eclipse CDT
|
||||
------------------
|
||||
|
||||
Install Eclipse CDT
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
`Eclipse CDT <https://eclipse.org/cdt/>`__ is a C/C++ IDE.
|
||||
|
||||
Eclipse is a Java-based tool so be sure **Java Runtime Environment** is installed on your system.
|
||||
|
||||
On Debian-based distros (e.g. Ubuntu): ``sudo apt-get install default-jre``
|
||||
|
||||
:note: If you are using other distros, then please install a 'Java
|
||||
Runtime Environment' suitable to your distro. Note: If you are using
|
||||
macOS and get a "Failed to create the Java Virtual Machine" error,
|
||||
uninstall any other Java JDK installs and install Java JDK 8u. This
|
||||
should fix the problem.
|
||||
|
||||
You can download Eclipse's CDT from:
|
||||
https://www.eclipse.org/cdt/downloads.php. Start the installer and
|
||||
choose *Eclipse CDT* from the list.
|
||||
|
||||
Install SDL 2
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
The PC simulator uses the `SDL2 <https://www.libsdl.org/download-2.0.php>`__ cross-platform library to
|
||||
simulate a TFT display and a touchpad.
|
||||
|
||||
Linux
|
||||
^^^^^
|
||||
|
||||
On **Linux** you can easily install SDL2 using a terminal:
|
||||
|
||||
1. Find the current version of SDL2: ``apt-cache search libsdl2 (e.g. libsdl2-2.0-0)``
|
||||
2. Install SDL2: ``sudo apt-get install libsdl2-2.0-0`` (replace with the found version)
|
||||
3. Install SDL2 development package: ``sudo apt-get install libsdl2-dev``
|
||||
4. If build essentials are not installed yet: ``sudo apt-get install build-essential``
|
||||
|
||||
Windows
|
||||
^^^^^^^
|
||||
|
||||
If you are using **Windows** firstly you need to install
|
||||
MinGW (`64 bit version <https://www.mingw-w64.org/downloads/#msys2>`__). After
|
||||
installing MinGW, do the following steps to add SDL2:
|
||||
|
||||
1. Download the development libraries of SDL. Go to
|
||||
https://www.libsdl.org/download-2.0.php and download *Development Libraries: SDL2-devel-2.0.5-mingw.tar.gz*
|
||||
2. Decompress the file and go to *x86_64-w64-mingw32* directory (for 64 bit MinGW) or to *i686-w64-mingw32* (for 32 bit MinGW)
|
||||
3. Copy *mingw32/include/SDL2* folder to *C:/MinGW/…/x86_64-w64-mingw32/include*
|
||||
4. Copy *mingw32/lib/* content to *C:/MinGW/…/x86_64-w64-mingw32/lib*
|
||||
5. Copy *mingw32/bin/SDL2.dll* to *{eclipse_workspace}/pc_simulator/Debug/\_*. Do it later when Eclipse is installed.
|
||||
|
||||
:Note: If you are using **Microsoft Visual Studio** instead of Eclipse
|
||||
then you don't have to install MinGW.
|
||||
|
||||
OSX
|
||||
^^^
|
||||
|
||||
On **OSX** you can easily install SDL2 with brew: ``brew install sdl2``
|
||||
|
||||
If something is not working, then please refer `this tutorial <http://lazyfoo.net/tutorials/SDL/01_hello_SDL/index.php>`__ to
|
||||
get started with SDL.
|
||||
|
||||
Pre-configured project
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A pre-configured graphics library project (based on the latest release)
|
||||
is always available to get started easily. You can find the latest one
|
||||
on `GitHub <https://github.com/lvgl/lv_sim_eclipse_sdl>`__.
|
||||
(Please note that, the project is configured for Eclipse CDT).
|
||||
|
||||
Add the pre-configured project to Eclipse CDT
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Run Eclipse CDT. It will show a dialogue about the **workspace path**.
|
||||
Before accepting the path, check that path and copy (and unzip) the
|
||||
downloaded pre-configured project there. After that, you can accept the
|
||||
workspace path. Of course you can modify this path but in that case copy
|
||||
the project to the corresponding location.
|
||||
|
||||
Close the start-up window and go to **File->Import** and choose
|
||||
**General->Existing project into Workspace**. **Browse the root
|
||||
directory** of the project and click **Finish**
|
||||
|
||||
On **Windows** you have to do two additional things:
|
||||
|
||||
- Copy the **SDL2.dll** into the project's Debug folder
|
||||
- Right-click on the project -> Project properties -> C/C++ Build ->
|
||||
Settings -> Libraries -> Add … and add *mingw32* above SDLmain and
|
||||
SDL. (The order is important: mingw32, SDLmain, SDL)
|
||||
|
||||
Compile and Run
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Now you are ready to run LVGL on your PC. Click on the Hammer Icon on
|
||||
the top menu bar to Build the project. If you have done everything
|
||||
right, then you will not get any errors. Note that on some systems
|
||||
additional steps might be required to "see" SDL 2 from Eclipse but in
|
||||
most cases the configuration in the downloaded project is enough.
|
||||
|
||||
After a successful build, click on the Play button on the top menu bar
|
||||
to run the project. Now a window should appear in the middle of your
|
||||
screen.
|
||||
|
||||
Now you are ready to use LVGL and begin development on your PC.
|
||||
14
docs/integration/index.rst
Normal file
14
docs/integration/index.rst
Normal file
@@ -0,0 +1,14 @@
|
||||
=======================
|
||||
Integration and drivers
|
||||
=======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
build/index
|
||||
chip/index
|
||||
driver/index
|
||||
framework/index
|
||||
ide/index
|
||||
os/index
|
||||
bindings/index
|
||||
5
docs/integration/os/freertos.rst
Normal file
5
docs/integration/os/freertos.rst
Normal file
@@ -0,0 +1,5 @@
|
||||
========
|
||||
FreeRTOS
|
||||
========
|
||||
|
||||
TODO
|
||||
11
docs/integration/os/index.rst
Normal file
11
docs/integration/os/index.rst
Normal file
@@ -0,0 +1,11 @@
|
||||
======
|
||||
(RT)OS
|
||||
======
|
||||
|
||||
.. toctree:: :maxdepth: 2
|
||||
|
||||
nuttx
|
||||
rt-thread
|
||||
freertos
|
||||
zephyr
|
||||
px5
|
||||
146
docs/integration/os/nuttx.rst
Normal file
146
docs/integration/os/nuttx.rst
Normal file
@@ -0,0 +1,146 @@
|
||||
==========
|
||||
NuttX RTOS
|
||||
==========
|
||||
|
||||
What is NuttX?
|
||||
--------------
|
||||
|
||||
`NuttX <https://nuttx.apache.org/>`__ is a mature and secure real-time
|
||||
operating system (RTOS) with an emphasis on technical standards
|
||||
compliance and small size. It is scalable from 8-bit to 64-bit
|
||||
microcontrollers and microprocessors and compliant with the Portable
|
||||
Operating System Interface (POSIX) and the American National Standards
|
||||
Institute (ANSI) standards and with many Linux-like subsystems. The best
|
||||
way to think about NuttX is to think of it as a small Unix/Linux for
|
||||
microcontrollers.
|
||||
|
||||
Highlights of NuttX
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- **Small** - Fits and runs in microcontrollers as small as 32 kB Flash
|
||||
and 8 kB of RAM.
|
||||
- **Compliant** - Strives to be as compatible as possible with POSIX
|
||||
and Linux.
|
||||
- **Versatile** - Supports many architectures (ARM, ARM Thumb, AVR,
|
||||
MIPS, OpenRISC, RISC-V 32-bit and 64-bit, RX65N, x86-64, Xtensa,
|
||||
Z80/Z180, etc.).
|
||||
- **Modular** - Its modular design allows developers to select only
|
||||
what really matters and use modules to include new features.
|
||||
- **Popular** - NuttX is used by many companies around the world.
|
||||
Probably you already used a product with NuttX without knowing it was
|
||||
running NuttX.
|
||||
- **Predictable** - NuttX is a preemptible Realtime kernel, so you can
|
||||
use it to create predictable applications for realtime control.
|
||||
|
||||
--------------
|
||||
|
||||
Why NuttX + LVGL?
|
||||
-----------------
|
||||
|
||||
Although NuttX has its own graphic library called
|
||||
`NX <https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=139629474>`__,
|
||||
LVGL is a good alternative because users could find more eye-candy demos
|
||||
and they can reuse code from previous projects. LVGL is an
|
||||
`Object-Oriented Component
|
||||
Based <https://blog.lvgl.io/2018-12-13/extend-lvgl-objects>`__
|
||||
high-level GUI library, that could fit very well for a RTOS with
|
||||
advanced features like NuttX. LVGL is implemented in C and its APIs are
|
||||
in C.
|
||||
|
||||
Here are some advantages of using LVGL in NuttX
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- Develop GUI in Linux first and when it is done just compile it for
|
||||
NuttX. Nothing more, no wasting of time.
|
||||
- Usually, GUI development for low level RTOS requires multiple
|
||||
iterations to get things right, where each iteration consists of
|
||||
**``Change code`` > ``Build`` > ``Flash`` > ``Run``**. Using LVGL,
|
||||
Linux and NuttX you can reduce this process and just test everything
|
||||
on your computer and when it is done, compile it on NuttX and that is
|
||||
it.
|
||||
|
||||
NuttX + LVGL could be used for
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- GUI demos to demonstrate your board graphics capacities.
|
||||
- Fast prototyping GUI for MVP (Minimum Viable Product) presentation.
|
||||
- visualize sensor data directly and easily on the board without using
|
||||
a computer.
|
||||
- Final products with a GUI without a touchscreen (i.e. 3D Printer
|
||||
Interface using Rotary Encoder to Input data).
|
||||
- Final products with a touchscreen (and all sorts of bells and
|
||||
whistles).
|
||||
|
||||
--------------
|
||||
|
||||
How to get started with NuttX and LVGL?
|
||||
---------------------------------------
|
||||
|
||||
There are many boards in the `NuttX
|
||||
mainline <https://github.com/apache/incubator-nuttx>`__ with support for
|
||||
LVGL. Let's use the
|
||||
`STM32F429IDISCOVERY <https://www.st.com/en/evaluation-tools/32f429idiscovery.html>`__
|
||||
as an example because it is a very popular board.
|
||||
|
||||
First you need to install the pre-requisites on your system
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Let's use the `Windows Subsystem for
|
||||
Linux <https://acassis.wordpress.com/2018/01/10/how-to-build-nuttx-on-windows-10/>`__
|
||||
|
||||
.. code:: shell
|
||||
|
||||
$ sudo apt-get install automake bison build-essential flex gcc-arm-none-eabi gperf git libncurses5-dev libtool libusb-dev libusb-1.0.0-dev pkg-config kconfig-frontends openocd
|
||||
|
||||
Now let's create a workspace to save our files
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code:: shell
|
||||
|
||||
$ mkdir ~/nuttxspace
|
||||
$ cd ~/nuttxspace
|
||||
|
||||
Clone the NuttX and Apps repositories:
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code:: shell
|
||||
|
||||
$ git clone https://github.com/apache/incubator-nuttx nuttx
|
||||
$ git clone https://github.com/apache/incubator-nuttx-apps apps
|
||||
|
||||
Configure NuttX to use the stm32f429i-disco board and the LVGL Demo
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code:: shell
|
||||
|
||||
$ ./tools/configure.sh stm32f429i-disco:lvgl
|
||||
$ make
|
||||
|
||||
If everything went fine you should have now the file ``nuttx.bin`` to
|
||||
flash on your board:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
$ ls -l nuttx.bin
|
||||
-rwxrwxr-x 1 alan alan 287144 Jun 27 09:26 nuttx.bin
|
||||
|
||||
Flashing the firmware in the board using OpenOCD:
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code:: shell
|
||||
|
||||
$ sudo openocd -f interface/stlink-v2.cfg -f target/stm32f4x.cfg -c init -c "reset halt" -c "flash write_image erase nuttx.bin 0x08000000"
|
||||
|
||||
Reset the board and using the 'NSH>' terminal start the LVGL demo:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
nsh> lvgldemo
|
||||
|
||||
Where can I find more information?
|
||||
----------------------------------
|
||||
|
||||
- This blog post: `LVGL on
|
||||
LPCXpresso54628 <https://acassis.wordpress.com/2018/07/19/running-nuttx-on-lpcxpresso54628-om13098/>`__
|
||||
- NuttX mailing list: `Apache NuttX Mailing
|
||||
List <http://nuttx.incubator.apache.org/community/>`__
|
||||
8
docs/integration/os/px5.rst
Normal file
8
docs/integration/os/px5.rst
Normal file
@@ -0,0 +1,8 @@
|
||||
========
|
||||
PX5 RTOS
|
||||
========
|
||||
|
||||
See `PX5 RTOS's homepage <https://px5rtos.com/>`__
|
||||
|
||||
|
||||
TODO
|
||||
88
docs/integration/os/rt-thread.rst
Normal file
88
docs/integration/os/rt-thread.rst
Normal file
@@ -0,0 +1,88 @@
|
||||
==============
|
||||
RT-Thread RTOS
|
||||
==============
|
||||
|
||||
What is RT-Thread?
|
||||
------------------
|
||||
|
||||
`RT-Thread <https://www.rt-thread.io/>`__ is an `open
|
||||
source <https://github.com/RT-Thread/rt-thread>`__, neutral, and
|
||||
community-based real-time operating system (RTOS). RT-Thread has
|
||||
**Standard version** and **Nano version**. For resource-constrained
|
||||
microcontroller (MCU) systems, the Nano version that requires only 3 KB
|
||||
Flash and 1.2 KB RAM memory resources can be tailored with easy-to-use
|
||||
tools. For resource-rich IoT devices, RT-Thread can use the **online
|
||||
software package** management tool, together with system configuration
|
||||
tools, to achieve intuitive and rapid modular cutting, seamlessly import
|
||||
rich software packages; thus, achieving complex functions like Android's
|
||||
graphical interface and touch sliding effects, smart voice interaction
|
||||
effects, and so on.
|
||||
|
||||
Key features
|
||||
~~~~~~~~~~~~
|
||||
|
||||
- Designed for resource-constrained devices, the minimum kernel
|
||||
requires only 1.2KB of RAM and 3 KB of Flash.
|
||||
- A variety of standard interfaces, such as POSIX, CMSIS, C++
|
||||
application environment.
|
||||
- Has rich components and a prosperous and fast growing `package ecosystem <https://packages.rt-thread.org/en/>`__
|
||||
- Elegant code style, easy to use, read and master.
|
||||
- High Scalability. RT-Thread has high-quality scalable software
|
||||
architecture, loose coupling, modularity, is easy to tailor and
|
||||
expand.
|
||||
- Supports high-performance applications.
|
||||
- Supports all mainstream compiling tools such as GCC, Keil and IAR.
|
||||
- Supports a wide range of `architectures and chips <https://www.rt-thread.io/board.html>`__
|
||||
|
||||
How to run LVGL on RT-Thread?
|
||||
-----------------------------
|
||||
|
||||
`中文文档 <https://www.rt-thread.org/document/site/#/rt-thread-version/rt-thread-standard/packages-manual/lvgl-docs/introduction>`__
|
||||
|
||||
LVGL has registered as a
|
||||
`softwarepackage <https://packages.rt-thread.org/en/detail.html?package=LVGL>`__
|
||||
of RT-Thread. By using
|
||||
`Env tool <https://www.rt-thread.io/download.html?download=Env>`__ or
|
||||
`RT-Thread Studio IDE <https://www.rt-thread.io/download.html?download=Studio>`__,
|
||||
RT-Thread users can easily download LVGL source code and combine with
|
||||
RT-Thread project.
|
||||
|
||||
RT-Thread community has port LVGL to several BSPs:
|
||||
|
||||
+--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| BSP | BSP |
|
||||
+======================================================================================================================================+======================================================================================================================================================+
|
||||
| `QEMU simulator <https://github.com/RT-Thread/rt-thread/tree/master/bsp/qemu-vexpress-a9/applications/lvgl>`__ | `Infineon psoc6-evaluationkit-062S2 <https://github.com/RT-Thread/rt-thread/tree/master/bsp/Infineon/psoc6-evaluationkit-062S2/applications/lvgl>`__ |
|
||||
+--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| `Visual Studio simulator <https://github.com/RT-Thread/rt-thread/tree/master/bsp/simulator/applications/lvgl>`__ | `Renesas ra6m3-ek <https://github.com/RT-Thread/rt-thread/tree/master/bsp/renesas/ra6m3-ek/board/lvgl>`__ |
|
||||
+--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| `Nuvoton numaker-iot-m487 <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-iot-m487/applications/lvgl>`__ | `Renesas ra6m4-cpk <https://github.com/RT-Thread/rt-thread/tree/master/bsp/renesas/ra6m4-cpk/board/lvgl>`__ |
|
||||
+--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| `Nuvoton numaker-pfm-m487 <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-pfm-m487/applications/lvgl>`__ | `Renesas ra6m3-hmi <https://github.com/RT-Thread/rt-thread/tree/master/bsp/renesas/ra6m3-hmi-board/board/lvgl>`__ |
|
||||
+--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| `Nuvoton nk-980iot <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/nk-980iot/applications/lvgl>`__ | `STM32H750 ART-Pi <https://github.com/RT-Thread/rt-thread/tree/master/bsp/stm32/stm32h750-artpi/applications/lvgl>`__ |
|
||||
+--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| `Nuvoton numaker-m2354 <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-m2354/applications/lvgl>`__ | `STM32F469 Discovery <https://github.com/RT-Thread/rt-thread/tree/master/bsp/stm32/stm32f469-st-disco/applications/lvgl>`__ |
|
||||
+--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| `Nuvoton nk-n9h30 <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/nk-n9h30/applications/lvgl>`__ | `STM32F407 explorer <https://github.com/RT-Thread/rt-thread/tree/master/bsp/stm32/stm32f407-atk-explorer/applications/lvgl>`__ |
|
||||
+--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| `Nuvoton numaker-m032ki <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-m032ki/applications/lvgl>`__ | `STM32L475 pandora <https://github.com/RT-Thread/rt-thread/tree/master/bsp/stm32/stm32l475-atk-pandora/applications/lvgl>`__ |
|
||||
+--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| `Nuvoton numaker-hmi-ma35d1 <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-hmi-ma35d1/applications/lvgl>`__ | `NXP imxrt1060-evk <https://github.com/RT-Thread/rt-thread/tree/master/bsp/imxrt/imxrt1060-nxp-evk/applications/lvgl>`__ |
|
||||
+--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| `Nuvoton numaker-iot-m467 <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-iot-m467/applications/lvgl>`__ | `Raspberry PICO <https://github.com/RT-Thread/rt-thread/tree/master/bsp/raspberry-pico/applications/lvgl>`__ |
|
||||
+--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| `Nuvoton numaker-m467hj <https://github.com/RT-Thread/rt-thread/tree/master/bsp/nuvoton/numaker-m467hj/applications/lvgl>`__ | `NXP LPC55S69 <https://github.com/RT-Thread/rt-thread/tree/master/bsp/lpc55sxx/lpc55s69_nxp_evk/applications/lvgl>`__ |
|
||||
+--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| `synwit swm341 <https://github.com/RT-Thread/rt-thread/tree/master/bsp/synwit/swm341/applications/lvgl>`__ |
|
||||
+--------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
|
||||
|
||||
Tutorials
|
||||
~~~~~~~~~
|
||||
|
||||
- `Introduce about RT-Thread and how to run LVGL on RT-Thread in simulators <https://www.youtube.com/watch?v=k7QYk6hSwnc>`__
|
||||
- `How to import a BSP project with latest code into RT-Thread Studio <https://www.youtube.com/watch?v=fREPLuh-h8k>`__
|
||||
- `How to Use LVGL with RT-Thread Studio in STM32F469 Discovery Board <https://www.youtube.com/watch?v=O_QA99BxnOE>`__
|
||||
- `RT-Thread Youtube Channel <https://www.youtube.com/channel/UCdDHtIfSYPq4002r27ffqPw>`__
|
||||
- `RT-Thread documentation center <https://www.rt-thread.io/document/site/>`__
|
||||
168
docs/integration/os/zephyr.rst
Normal file
168
docs/integration/os/zephyr.rst
Normal file
@@ -0,0 +1,168 @@
|
||||
======
|
||||
Zephyr
|
||||
======
|
||||
|
||||
What is Zephyr?
|
||||
---------------
|
||||
|
||||
`Zephyr <https://zephyrproject.org/>`__ is an `open
|
||||
source <https://github.com/zephyrproject-rtos/zephyr>`__ real-time operating
|
||||
system (RTOS) that is easy to deploy, secure, connect and manage.
|
||||
It has a growing set of software libraries that can be used
|
||||
across various applications and industry sectors such as
|
||||
Industrial IoT, wearables, machine learning and more.
|
||||
Zephyr is built with an emphasis on broad chipset support,
|
||||
security, dependability, longterm support releases and a
|
||||
growing open source ecosystem.
|
||||
|
||||
Highlights of Zephyr
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- **Small** - Runs on microcontrollers as small as 8 kB Flash
|
||||
and 5 kB of RAM.
|
||||
- **Scalable** - Usable for complex multicore systems.
|
||||
- **Customizable** - Out-of-the-box support for 500+ boards
|
||||
and high portability.
|
||||
- **Secure** - Built with safety and security in mind,
|
||||
offers Long-term support.
|
||||
- **Ecosystem** - Zephyr not only provides the RTOS kernel but
|
||||
also developer tooling, device drivers, connectivity, logging,
|
||||
tracing, power management and much more.
|
||||
- **Decoupling** - Leverages devicetree to describe and
|
||||
configure the target system.
|
||||
- **Compliant** - Apps are runnable as native Linux applications,
|
||||
which simplifies debugging and profiling.
|
||||
|
||||
How to run LVGL on Zephyr?
|
||||
--------------------------
|
||||
|
||||
To setup your development environment refer to the
|
||||
`getting started guide <https://docs.zephyrproject.org/latest/develop/getting_started/index.html>`__.
|
||||
|
||||
After you completed the setup above you can check out all of the `provided samples <https://docs.zephyrproject.org/latest/samples/>`__ for various boards.
|
||||
You can check the list of available boards using:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
$ west boards
|
||||
|
||||
After you chose a board you can build one of the LVGL demos for it. Here we are using the :code:`native_posix`
|
||||
board, which allows for running the application on your posix compliant host system:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
$ west build -b native_posix samples/modules/lvgl/demos
|
||||
|
||||
To run the application on your host:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
$ west build -t run
|
||||
|
||||
In case you chose any of the other supported boards you can flash to the device with:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
$ west flash
|
||||
|
||||
If you want to build any of the other demo applications check out the samples
|
||||
`README <https://docs.zephyrproject.org/latest/samples/modules/lvgl/demos/README.html>`__.
|
||||
|
||||
Leveraging Zephyr Features
|
||||
--------------------------
|
||||
|
||||
Shell
|
||||
~~~~~
|
||||
|
||||
Zephyr includes a powerful shell implementation that can be enabled with the Kconfig symbols
|
||||
:code:`CONFIG_SHELL` and :code:`CONFIG_LV_Z_SHELL` (the demos from above have it enabled by default).
|
||||
|
||||
The shell offers enabling/disabling of LVGL monkeys:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
# Create a new monkey with the given indev type
|
||||
uart$ lvgl monkey create [pointer|keypad|button|encoder]
|
||||
|
||||
# Enable/Disable a monkey
|
||||
uart$ lvgl monkey set <index> <inactive/active>
|
||||
|
||||
This is useful for checking your application for memory leaks and other bugs.
|
||||
Speaking of memory leaks, you can also acquire stats of the memory used by LVGL
|
||||
|
||||
.. code:: shell
|
||||
|
||||
uart$ lvgl stats memory
|
||||
|
||||
For more details refer to the `shell documentation <https://docs.zephyrproject.org/latest/services/shell/index.html>`__.
|
||||
|
||||
Devicetree
|
||||
~~~~~~~~~~
|
||||
|
||||
Zephyr uses the devicetree description language to create and manage LVGL input devices.
|
||||
|
||||
The pseudo device binding descriptions can be found at:
|
||||
|
||||
- `button input <https://docs.zephyrproject.org/latest/build/dts/api/bindings/input/zephyr,lvgl-button-input.html>`__
|
||||
- `pointer input <https://docs.zephyrproject.org/latest/build/dts/api/bindings/input/zephyr,lvgl-pointer-input.html>`__
|
||||
- `encoder input <https://docs.zephyrproject.org/latest/build/dts/api/bindings/input/zephyr,lvgl-encoder-input.html>`__
|
||||
|
||||
Essentially those buffer the :code:`input_event` generated by the device pointed to by the :code:`input` phandle or if left
|
||||
empty the binding captures all events regardless of the source. You do not have to instantiate or manage the devices yourself,
|
||||
they are created at application start up before :code:`main()` is executed.
|
||||
|
||||
Most boards or shields that have a display or display connector have the pointer input device already declared:
|
||||
|
||||
.. code::
|
||||
|
||||
lvgl_pointer {
|
||||
compatible = "zephyr,lvgl-pointer-input";
|
||||
input = <&ft5336_touch>;
|
||||
};
|
||||
|
||||
You can access the underlying lvgl :code:`lv_indev_t` for configuration.
|
||||
Example with the encoder device to assign a :code:`lv_group_t`:
|
||||
|
||||
.. code:: c
|
||||
|
||||
const struct device *lvgl_encoder = DEVICE_DT_GET(DT_COMPAT_GET_ANY_STATUS_OKAY(zephyr_lvgl_encoder_input));
|
||||
|
||||
lv_obj_t *arc;
|
||||
lv_group_t *arc_group;
|
||||
|
||||
arc = lv_arc_create(lv_screen_active());
|
||||
lv_obj_align(arc, LV_ALIGN_CENTER, 0, 0);
|
||||
lv_obj_set_size(arc, 150, 150);
|
||||
|
||||
arc_group = lv_group_create();
|
||||
lv_group_add_obj(arc_group, arc);
|
||||
lv_indev_set_group(lvgl_input_get_indev(lvgl_encoder), arc_group);
|
||||
|
||||
|
||||
Kconfig
|
||||
~~~~~~~~
|
||||
|
||||
Aside from enabling the shell you can also use Kconfig to finetune
|
||||
the footprint of your application.
|
||||
|
||||
.. code::
|
||||
|
||||
# Size of the memory region from which lvgl memory is allocated
|
||||
CONFIG_LV_Z_MEM_POOL_SIZE=8192
|
||||
|
||||
# Do not include every widget/theme by default, enable them as needed.
|
||||
CONFIG_LV_CONF_MINIMAL=y
|
||||
|
||||
Overlays can be used to enable/disable features for specific boards or build
|
||||
targets. For more information refer to the
|
||||
`application development guide <https://docs.zephyrproject.org/latest/develop/application/index.html#application-configuration>`__.
|
||||
|
||||
|
||||
Where can I find more information?
|
||||
----------------------------------
|
||||
|
||||
- Zephyr Documentation: `Zephyr Documentation <https://docs.zephyrproject.org/latest/index.html>`__
|
||||
- Zephyr mailing list: `Zepyhr Mailing
|
||||
List <https://lists.zephyrproject.org/g/main>`__
|
||||
- Zephyr Discord server: `Zepyhr Discord
|
||||
server <https://chat.zephyrproject.org/>`__
|
||||
Reference in New Issue
Block a user