feat(docs): migrate from .md to .rst (#4129)
This commit is contained in:
Kevin Schlosser
104
docs/get-started/platforms/arduino.rst
Normal file
104
docs/get-started/platforms/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.
|
||||
@@ -1,92 +0,0 @@
|
||||
|
||||
# CMake
|
||||
LVGL supports integrating with [CMake](https://cmake.org/). It comes with preconfigured targets for:
|
||||
- [Espressif (ESP32)](https://docs.espressif.com/projects/esp-idf/en/v3.3/get-started-cmake/index.html)
|
||||
- [MicroPython](https://docs.micropython.org/en/v1.15/develop/cmodules.html)
|
||||
- [Zephyr](https://docs.zephyrproject.org/latest/guides/zephyr_cmake_package.html)
|
||||
|
||||
On top of the preconfigured targets you can also use "plain" CMake to integrate LVGL into any custom C/C++ project.
|
||||
|
||||
## Prerequisites
|
||||
- CMake ( >= 3.12.4 )
|
||||
- Compatible build tool e.g.
|
||||
- [Make](https://www.gnu.org/software/make/)
|
||||
- [Ninja](https://ninja-build.org/)
|
||||
|
||||
## Building LVGL with CMake
|
||||
There are many ways to include external CMake projects into your own. A modern one also used in this example is the CMake [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html) module. This module conveniently allows us to download dependencies directly at configure time from e.g. [GitHub](https://github.com/). Here is an example how we might include LVGL into our own project.
|
||||
|
||||
```cmake
|
||||
cmake_minimum_required(VERSION 3.14)
|
||||
include(FetchContent)
|
||||
|
||||
project(MyProject LANGUAGES C CXX)
|
||||
|
||||
# Build an executable called "MyFirmware"
|
||||
add_executable(MyFirmware src/main.c)
|
||||
|
||||
# Specify path to own LVGL config header
|
||||
set(LV_CONF_PATH
|
||||
${CMAKE_CURRENT_SOURCE_DIR}/src/lv_conf.h
|
||||
CACHE STRING "" FORCE)
|
||||
|
||||
# Fetch LVGL from GitHub
|
||||
FetchContent_Declare(lvgl GIT_REPOSITORY https://github.com/lvgl/lvgl.git)
|
||||
FetchContent_MakeAvailable(lvgl)
|
||||
|
||||
# The target "MyFirmware" depends on LVGL
|
||||
target_link_libraries(MyFirmware PRIVATE lvgl::lvgl)
|
||||
```
|
||||
|
||||
This configuration declares a dependency between the two targets **MyFirmware** and **lvgl**. Upon building the target **MyFirmware** this dependency will be resolved and **lvgl** will be built and linked with it. Since LVGL requires a config header called [lv_conf.h](https://github.com/lvgl/lvgl/blob/master/lv_conf_template.h) to be includable by its sources we also set the option `LV_CONF_PATH` to point to our own copy of it.
|
||||
|
||||
### Additional CMake options
|
||||
Besides `LV_CONF_PATH` there are few additional CMake options available.
|
||||
|
||||
#### Include paths options
|
||||
|
||||
- `LV_LVGL_H_INCLUDE_SIMPLE`: which specifies whether to `#include "lvgl.h"` absolut or relative
|
||||
|
||||
| ON (default) | OFF |
|
||||
|--------------|----------------|
|
||||
| "lvgl.h" | "../../lvgl.h" |
|
||||
|
||||
- `LV_CONF_INCLUDE_SIMPLE`: which specifies whether to `#include "lv_conf.h"` and `"lv_drv_conf.h"` absolut or relative
|
||||
|
||||
| ON (default) | OFF |
|
||||
|-----------------|-----------------------|
|
||||
| "lv_conf.h" | "../../lv_conf.h" |
|
||||
| "lv_drv_conf.h" | "../../lv_drv_conf.h" |
|
||||
|
||||
> We do not recommend disabling those options unless your folder layout makes it absolutely necessary.
|
||||
|
||||
#### Examples/demos options
|
||||
|
||||
LVGL [examples](https://docs.lvgl.io/master/examples.html) and [demos](https://github.com/lvgl/lvgl/demos) are built by default in the main CMake file.
|
||||
To disable their built, use:
|
||||
|
||||
- `LV_CONF_BUILD_DISABLE_EXAMPLES`: Set to `1` to disable _examples_ build
|
||||
- `LV_CONF_BUILD_DISABLE_DEMOS`: Set to `1` to disable _demos_ build
|
||||
|
||||
## Building LVGL drivers
|
||||
|
||||
To build [LVGL drivers](https://github.com/lvgl/lv_drivers), you can use:
|
||||
|
||||
```cmake
|
||||
FetchContent_Declare(lv_drivers
|
||||
GIT_REPOSITORY https://github.com/lvgl/lv_drivers)
|
||||
FetchContent_MakeAvailable(lv_drivers)
|
||||
|
||||
# The target "MyFirmware" depends on LVGL and drivers
|
||||
target_link_libraries(MyFirmware PRIVATE lvgl::lvgl lvgl::drivers)
|
||||
```
|
||||
|
||||
# Build shared libraries with CMake
|
||||
By default, LVGL will be built as a static library (archive). CMake can instead be instructed to build LVGL as shared library (.so/.dll/etc.):
|
||||
```cmake
|
||||
set(BUILD_SHARED_LIBS ON)
|
||||
```
|
||||
OR
|
||||
```
|
||||
$ cmake "-DBUILD_SHARED_LIBS=ON" .
|
||||
```
|
||||
137
docs/get-started/platforms/cmake.rst
Normal file
137
docs/get-started/platforms/cmake.rst
Normal file
@@ -0,0 +1,137 @@
|
||||
=====
|
||||
CMake
|
||||
=====
|
||||
|
||||
LVGL supports integrating with `CMake <https://cmake.org/>`__. It comes
|
||||
with preconfigured targets for:
|
||||
|
||||
- `Espressif (ESP32) <https://docs.espressif.com/projects/esp-idf/en/v3.3/get-started-cmake/index.html>`__
|
||||
- `MicroPython <https://docs.micropython.org/en/v1.15/develop/cmodules.html>`__
|
||||
- `Zephyr <https://docs.zephyrproject.org/latest/guides/zephyr_cmake_package.html>`__
|
||||
|
||||
On top of the preconfigured targets you can also use “plain” CMake to
|
||||
integrate LVGL into any custom C/C++ project.
|
||||
|
||||
|
||||
Prerequisites
|
||||
*************
|
||||
|
||||
* CMake ( >= 3.12.4 )
|
||||
* Compatible build tool e.g.
|
||||
* `Make <https://www.gnu.org/software/make/>`__
|
||||
* `Ninja <https://ninja-build.org/>`__
|
||||
|
||||
|
||||
Building LVGL with CMake
|
||||
************************
|
||||
|
||||
There are many ways to include external CMake projects into your own. A
|
||||
modern one also used in this example is the CMake `FetchContent <https://cmake.org/cmake/help/latest/module/FetchContent.html>`__
|
||||
module. This module conveniently allows us to download dependencies
|
||||
directly at configure time from e.g. `GitHub <https://github.com/>`__.
|
||||
Here is an example how we might include LVGL into our own project.
|
||||
|
||||
.. code:: cmake
|
||||
|
||||
cmake_minimum_required(VERSION 3.14)
|
||||
include(FetchContent)
|
||||
|
||||
project(MyProject LANGUAGES C CXX)
|
||||
|
||||
# Build an executable called "MyFirmware"
|
||||
add_executable(MyFirmware src/main.c)
|
||||
|
||||
# Specify path to own LVGL config header
|
||||
set(LV_CONF_PATH
|
||||
${CMAKE_CURRENT_SOURCE_DIR}/src/lv_conf.h
|
||||
CACHE STRING "" FORCE)
|
||||
|
||||
# Fetch LVGL from GitHub
|
||||
FetchContent_Declare(lvgl GIT_REPOSITORY https://github.com/lvgl/lvgl.git)
|
||||
FetchContent_MakeAvailable(lvgl)
|
||||
|
||||
# The target "MyFirmware" depends on LVGL
|
||||
target_link_libraries(MyFirmware PRIVATE lvgl::lvgl)
|
||||
|
||||
This configuration declares a dependency between the two targets
|
||||
**MyFirmware** and **lvgl**. Upon building the target **MyFirmware**
|
||||
this dependency will be resolved and **lvgl** will be built and linked
|
||||
with it. Since LVGL requires a config header called `lv_conf.h <https://github.com/lvgl/lvgl/blob/master/lv_conf_template.h>`__
|
||||
to be includable by its sources we also set the option :c:macro:`LV_CONF_PATH`
|
||||
to point to our own copy of it.
|
||||
|
||||
|
||||
Additional CMake options
|
||||
========================
|
||||
|
||||
Besides :c:macro:`LV_CONF_PATH` there are few additional CMake options available.
|
||||
|
||||
|
||||
Include paths options
|
||||
---------------------
|
||||
|
||||
- :c:macro:`LV_LVGL_H_INCLUDE_SIMPLE`: which specifies whether to ``#include "lvgl.h"`` absolut or relative
|
||||
|
||||
============ ==============
|
||||
ON (default) OFF
|
||||
============ ==============
|
||||
“lvgl.h” “../../lvgl.h”
|
||||
============ ==============
|
||||
|
||||
- :c:macro:`LV_CONF_INCLUDE_SIMPLE`: which specifies whether to ``#include "lv_conf.h"`` and ``"lv_drv_conf.h"`` absolut or relative
|
||||
|
||||
=============== =====================
|
||||
ON (default) OFF
|
||||
=============== =====================
|
||||
“lv_conf.h” “../../lv_conf.h”
|
||||
“lv_drv_conf.h” “../../lv_drv_conf.h”
|
||||
=============== =====================
|
||||
|
||||
..
|
||||
|
||||
We do not recommend disabling those options unless your folder layout
|
||||
makes it absolutely necessary.
|
||||
|
||||
|
||||
Examples/demos options
|
||||
----------------------
|
||||
|
||||
| LVGL `examples <https://docs.lvgl.io/master/examples.html>`__ and
|
||||
`demos <https://github.com/lvgl/lvgl/demos>`__ are built by default in
|
||||
the main CMake file.
|
||||
| To disable their built, use:
|
||||
|
||||
- :c:macro:`LV_CONF_BUILD_DISABLE_EXAMPLES`: Set to ``1`` to disable *examples* build
|
||||
- :c:macro:`LV_CONF_BUILD_DISABLE_DEMOS`: Set to ``1`` to disable *demos* build
|
||||
|
||||
|
||||
Building LVGL drivers
|
||||
*********************
|
||||
|
||||
To build `LVGL drivers <https://github.com/lvgl/lv_drivers>`__, you can use:
|
||||
|
||||
.. code:: cmake
|
||||
|
||||
FetchContent_Declare(lv_drivers
|
||||
GIT_REPOSITORY https://github.com/lvgl/lv_drivers)
|
||||
FetchContent_MakeAvailable(lv_drivers)
|
||||
|
||||
# The target "MyFirmware" depends on LVGL and drivers
|
||||
target_link_libraries(MyFirmware PRIVATE lvgl::lvgl lvgl::drivers)
|
||||
|
||||
|
||||
Build shared libraries with CMake
|
||||
*********************************
|
||||
|
||||
By default, LVGL will be built as a static library (archive). CMake can
|
||||
instead be instructed to build LVGL as shared library (.so/.dll/etc.):
|
||||
|
||||
.. code:: cmake
|
||||
|
||||
set(BUILD_SHARED_LIBS ON)
|
||||
|
||||
OR
|
||||
|
||||
.. code:: console
|
||||
|
||||
$ cmake "-DBUILD_SHARED_LIBS=ON" .
|
||||
@@ -1,58 +0,0 @@
|
||||
|
||||
# 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:
|
||||
|
||||
```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:
|
||||
|
||||
```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:
|
||||
|
||||
```sh
|
||||
git submodule add https://github.com/lvgl/lvgl_esp32_drivers.git components/lvgl_esp32_drivers
|
||||
```
|
||||
85
docs/get-started/platforms/espressif.rst
Normal file
85
docs/get-started/platforms/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
|
||||
@@ -1,17 +0,0 @@
|
||||
# Platforms
|
||||
|
||||
```eval_rst
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
pc-simulator
|
||||
nxp
|
||||
stm32
|
||||
espressif
|
||||
arduino
|
||||
tasmota-berry
|
||||
cmake
|
||||
mdk
|
||||
```
|
||||
|
||||
15
docs/get-started/platforms/index.rst
Normal file
15
docs/get-started/platforms/index.rst
Normal file
@@ -0,0 +1,15 @@
|
||||
=========
|
||||
Platforms
|
||||
=========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
pc-simulator
|
||||
nxp
|
||||
stm32
|
||||
espressif
|
||||
arduino
|
||||
tasmota-berry
|
||||
cmake
|
||||
mdk
|
||||
@@ -1,4 +0,0 @@
|
||||
|
||||
# MDK
|
||||
|
||||
TODO
|
||||
5
docs/get-started/platforms/mdk.rst
Normal file
5
docs/get-started/platforms/mdk.rst
Normal file
@@ -0,0 +1,5 @@
|
||||
===
|
||||
MDK
|
||||
===
|
||||
|
||||
TODO
|
||||
@@ -1,178 +0,0 @@
|
||||
# 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":
|
||||
```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 `LV_USE_GPU_NXP_PXP` to 1
|
||||
- Enable default implementation for interrupt handling, PXP start function and automatic initialization:
|
||||
Set `LV_USE_GPU_NXP_PXP_AUTO_INIT` to 1
|
||||
- If `SDK_OS_FREE_RTOS` symbol is defined, FreeRTOS implementation will be used, otherwise bare metal code will be
|
||||
included
|
||||
|
||||
#### Basic initialization:
|
||||
- If `LV_USE_GPU_NXP_PXP_AUTO_INIT` is enabled, no user code is required; PXP is initialized automatically in
|
||||
`lv_init()`
|
||||
- For manual PXP initialization, default configuration structure for callbacks can be used. Initialize PXP before
|
||||
calling `lv_init()`
|
||||
```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 `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, `LV_GPU_NXP_PXP_LOG_ERRORS` is enabled so that any PXP error will be seen on SDK debug console
|
||||
- By default, `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 `lv_nxp_pxp_cfg_t` with callback pointers is
|
||||
used as a parameter for the `lv_gpu_nxp_pxp_init()` function. Default implementation for FreeRTOS and bare metal is
|
||||
provided in lv_gpu_nxp_pxp_osa.c
|
||||
- `pxp_interrupt_init()`: Initialize PXP interrupt (HW setup, OS setup)
|
||||
- `pxp_interrupt_deinit()`: Deinitialize PXP interrupt (HW setup, OS setup)
|
||||
- `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
|
||||
- `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":
|
||||
```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:
|
||||
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:
|
||||
- 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 (`VG_LITE_LINEAR`).
|
||||
|
||||
#### Basic configuration:
|
||||
- Select NXP VGLite engine in lv_conf.h: Set `LV_USE_GPU_NXP_VG_LITE` to 1
|
||||
- `SDK_OS_FREE_RTOS` symbol needs to be defined so that the FreeRTOS implementation will be used
|
||||
|
||||
#### Basic initialization:
|
||||
- Initialize VGLite before calling `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.
|
||||
```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:
|
||||
- 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:
|
||||
- By default, `LV_GPU_NXP_VG_LITE_LOG_ERRORS` is enabled so that any VGLite error will be seen on SDK debug console
|
||||
- By default, `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:
|
||||
- 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
|
||||
- `LV_GPU_NXP_VG_LITE_SIZE_LIMIT`: size threshold for fill/blit (with optional transformation)
|
||||
278
docs/get-started/platforms/nxp.rst
Normal file
278
docs/get-started/platforms/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)
|
||||
@@ -1,100 +0,0 @@
|
||||
# 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 SDL driver](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 with SDL driver](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](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 [SDL 2](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](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.
|
||||
152
docs/get-started/platforms/pc-simulator.rst
Normal file
152
docs/get-started/platforms/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 with SDL driver <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.
|
||||
@@ -1,219 +0,0 @@
|
||||
|
||||
# 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:
|
||||
```
|
||||
//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: 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 ```lv_init();``` to initialise LVGL. You can then register the frame buffers using ```lv_disp_draw_buf_init()```, and create the display driver using ```lv_disp_drv_init()```.
|
||||
```
|
||||
//Initialise LVGL UI library
|
||||
lv_init();
|
||||
lv_disp_draw_buf_init(&disp_buf, buf_1, NULL, 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*/
|
||||
```
|
||||
* Create some dummy objects to test the output:
|
||||
```
|
||||
// Change the active screen's background color
|
||||
lv_obj_set_style_bg_color(lv_scr_act(), lv_color_hex(0x003a57), LV_PART_MAIN);
|
||||
lv_obj_set_style_text_color(lv_scr_act(), lv_color_hex(0xffffff), LV_PART_MAIN);
|
||||
|
||||
/*Create a spinner*/
|
||||
lv_obj_t * spinner = lv_spinner_create(lv_scr_act(), 1000, 60);
|
||||
lv_obj_set_size(spinner, 64, 64);
|
||||
lv_obj_align(spinner, LV_ALIGN_BOTTOM_MID, 0, 0);
|
||||
```
|
||||
* Add a call to ```lv_timer_handler()``` inside your ```while(1)``` loop:
|
||||
```
|
||||
/* Infinite loop */
|
||||
while (1)
|
||||
{
|
||||
lv_timer_handler();
|
||||
HAL_Delay(5);
|
||||
}
|
||||
```
|
||||
* Add a call to ```lv_tick_inc()``` inside the ```SysTick_Handler()``` function. Open the *stm32xxxx_it.c* file (the name will depend on your specific MCU), and update the ```SysTick_Handler()``` function:
|
||||
```
|
||||
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.
|
||||
```
|
||||
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;
|
||||
|
||||
//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++) {
|
||||
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);
|
||||
}
|
||||
```
|
||||
|
||||
## FreeRTOS Example
|
||||
A minimal example using STM32CubeIDE, HAL, and CMSISv1 (FreeRTOS). <br />
|
||||
*Note that we have not used Mutexes in this example, however LVGL is **NOT** thread safe and so Mutexes should be used. See: [Operating system and interrupts](https://docs.lvgl.io/master/porting/os.html)*
|
||||
* ```#include "lvgl.h"```
|
||||
* Create your frame buffer(s) as global variables:
|
||||
```
|
||||
//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 ```lv_init();```, register the frame buffers using ```lv_disp_draw_buf_init()```, and create a new display driver using ```lv_disp_drv_init()```.
|
||||
```
|
||||
//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:
|
||||
```
|
||||
// Change the active screen's background color
|
||||
lv_obj_set_style_bg_color(lv_scr_act(), lv_color_hex(0x003a57), LV_PART_MAIN);
|
||||
lv_obj_set_style_text_color(lv_scr_act(), lv_color_hex(0xffffff), LV_PART_MAIN);
|
||||
|
||||
/*Create a spinner*/
|
||||
lv_obj_t * spinner = lv_spinner_create(lv_scr_act(), 1000, 60);
|
||||
lv_obj_set_size(spinner, 64, 64);
|
||||
lv_obj_align(spinner, LV_ALIGN_BOTTOM_MID, 0, 0);
|
||||
```
|
||||
* Create two threads to call ```lv_timer_handler()```, and ```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:
|
||||
```
|
||||
//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:
|
||||
```
|
||||
/* LVGL timer for tasks. */
|
||||
void LVGLTimer(void const * argument)
|
||||
{
|
||||
for(;;)
|
||||
{
|
||||
lv_timer_handler();
|
||||
osDelay(20);
|
||||
}
|
||||
}
|
||||
/* LVGL tick source */
|
||||
void LGVLTick(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.
|
||||
```
|
||||
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);
|
||||
}
|
||||
```
|
||||
277
docs/get-started/platforms/stm32.rst
Normal file
277
docs/get-started/platforms/stm32.rst
Normal file
@@ -0,0 +1,277 @@
|
||||
=====
|
||||
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
|
||||
/*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: 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 register the frame buffers using
|
||||
:cpp:func:`lv_disp_draw_buf_init`, and create the 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, NULL, 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*/
|
||||
|
||||
- Create some dummy objects to test the output:
|
||||
|
||||
.. code:: c
|
||||
|
||||
// Change the active screen's background color
|
||||
lv_obj_set_style_bg_color(lv_scr_act(), lv_color_hex(0x003a57), LV_PART_MAIN);
|
||||
lv_obj_set_style_text_color(lv_scr_act(), lv_color_hex(0xffffff), LV_PART_MAIN);
|
||||
|
||||
/*Create a spinner*/
|
||||
lv_obj_t * spinner = lv_spinner_create(lv_scr_act(), 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_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;
|
||||
|
||||
//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++) {
|
||||
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);
|
||||
}
|
||||
|
||||
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_scr_act(), lv_color_hex(0x003a57), LV_PART_MAIN);
|
||||
lv_obj_set_style_text_color(lv_scr_act(), lv_color_hex(0xffffff), LV_PART_MAIN);
|
||||
|
||||
/*Create a spinner*/
|
||||
lv_obj_t * spinner = lv_spinner_create(lv_scr_act(), 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 LGVLTick(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);
|
||||
}
|
||||
@@ -1,73 +0,0 @@
|
||||
# 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
|
||||
|
||||
```python
|
||||
lv.start() # start LVGL
|
||||
scr = lv.scr_act() # 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/)
|
||||
105
docs/get-started/platforms/tasmota-berry.rst
Normal file
105
docs/get-started/platforms/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.scr_act() # 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/>`__
|
||||
Reference in New Issue
Block a user