feat(docs): reorganize docs (#7136)
This commit is contained in:
Victor Wheeler
501
docs/details/integration/bindings/api_json.rst
Normal file
501
docs/details/integration/bindings/api_json.rst
Normal file
@@ -0,0 +1,501 @@
|
||||
Output API as JSON data
|
||||
=======================
|
||||
|
||||
We have written a script that will read the header files in LVGL and outputs a more friendly JSON format for the API.
|
||||
This is done so that bindings that generate code automatically will have an easy way to collect the needed information
|
||||
without having to reinvent the wheel. The JSON data format has already made libraries for reading the format for just
|
||||
about every programming language out there.
|
||||
|
||||
The script in order to run does have some requirements.
|
||||
|
||||
- Python >= 3.10
|
||||
- Pycparser >= 2.21: Python Library for reading the preprocessor ouotput from the C compiler
|
||||
- PyMSVC >= 0.4.0: Python library is using MSVC Compiler
|
||||
- C compiler, gcc for Linux, clang for OSX and MSVC for Windows
|
||||
- Doxygen: used to read the docstrings from the header files.
|
||||
|
||||
|
||||
There are several options when running the script. They are as follows
|
||||
|
||||
- `--output-path`: output directory for JSON file. If one is not supplied then it will be output stdout
|
||||
- `--lvgl-config`: path to lv_conf.h (including file name), if this is not set then a config file will be
|
||||
generated that has most common things turned on
|
||||
- `--develop`: leaves the temporary folder in place.
|
||||
|
||||
|
||||
to use the script
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
python /scripts/gen_json/gen_json.py --output-path=json/output/directory --lvgl-config=path/to/lv_conf.h
|
||||
|
||||
|
||||
or if you want to run a subprocess from inside of a generation script and read the output from stdout
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
python /scripts/gen_json/gen_json.py --lvgl-config=path/to/lv_conf.h
|
||||
|
||||
|
||||
The JSON data is broken apart into a couple of main categories.
|
||||
|
||||
- enums
|
||||
- functions
|
||||
- function_pointers
|
||||
- structures
|
||||
- unions
|
||||
- variables
|
||||
- typedefs
|
||||
- forward_decls
|
||||
- macros
|
||||
|
||||
Those categories are the element names undert the root of the JSON data.
|
||||
The value for each categry is an array of JSON elements. There is a bit of
|
||||
nesting with the elements in the arrays and I have created "json_types" that
|
||||
will allow you to identify exactly what you are dealing with.
|
||||
|
||||
The different "json_types" are as follows:
|
||||
|
||||
- ``"array"``: The array type is used to identify arrays.
|
||||
|
||||
Available JSON fields:
|
||||
- ``"dim"``: number of items in the array
|
||||
- ``"quals"``: array of qualifiers, IE "const"
|
||||
- ``"type"``: This may or may not be available.
|
||||
- ``"name"``: the name of the data type
|
||||
|
||||
|
||||
- ``"field"``: This type is used to describe fields in structures and unions.
|
||||
It is used in the ``"fields"`` array of the ``"struct"`` and ``"union"`` JSON types.
|
||||
|
||||
Available JSON fields:
|
||||
- ``"name"``: The name of the field.
|
||||
- ``"type"``: This contains the type information for the field. Check the
|
||||
``"json_type"`` to know what type you are dealing with.
|
||||
- ``"bitsize"``: The number of bits the field has or ``null``
|
||||
if there is no bit size defined
|
||||
- ``"docstring"``: you should know what this is.
|
||||
|
||||
|
||||
- ``"arg"``: Used to describe an argument/parameter in a function or a function pointer.
|
||||
|
||||
Available JSON fields:
|
||||
- ``"name"``: The name of the argument/parameter.
|
||||
- ``"type"``: This contains the type information for the field. Check the
|
||||
``"json_type"`` to know what type you are dealing with.
|
||||
- ``"docstring"``: you should know what this is.
|
||||
- ``"quals"``: array of qualifiers, IE "const"
|
||||
|
||||
|
||||
- ``"forward_decl"``: Describes a forward declaration.There are structures in
|
||||
LVGL that are considered to be private and that is what these desccribe.
|
||||
|
||||
Available JSON fields:
|
||||
- ``"name"``: The name of the formard declaration.
|
||||
- ``"type"``: This contains the type information for the field. Check the
|
||||
``"json_type"`` to know what type you are dealing with.
|
||||
- ``"docstring"``: you should know what this is.
|
||||
- ``"quals"``: array of qualifiers, IE "const"
|
||||
|
||||
|
||||
- ``"function_pointer"``: Describes a function pointer. These are used when
|
||||
registering callback functions in LVGL.
|
||||
|
||||
Available JSON fields:
|
||||
- ``"name"``: The name of the function pointer.
|
||||
- ``"type"``: This contains the return type information for the function pointer.
|
||||
- ``"docstring"``: you should know what this is.
|
||||
- ``"args"``: array of ``"arg"`` Widgets. This describes the fuction arguments/parameters.
|
||||
- ``"quals"``: array of qualifiers, IE "const"
|
||||
|
||||
|
||||
- ``"variable"``: Describes a global variable.
|
||||
|
||||
Available JSON fields:
|
||||
- ``"name"``: The name of the variable.
|
||||
- ``"type"``: This contains the type information for the field. Check the
|
||||
``"json_type"`` to know what type you are dealing with.
|
||||
- ``"docstring"``: you should know what this is.
|
||||
- ``"quals"``: array of qualifiers, IE "const"
|
||||
- ``"storage"``: array of storage classifiers, IE "extern"
|
||||
|
||||
|
||||
- ``"special_type"``: Currently only used to describe an ellipsis argument
|
||||
for a function.
|
||||
|
||||
Available JSON fields:
|
||||
- ``"name"``: will always be "ellipsis".
|
||||
|
||||
|
||||
- ``"primitive_type"``: This is a base type. There or no other types beneith this.
|
||||
This tells you that the type is a basic or primitive C type.
|
||||
IE: struct, union, int, unsigned int, etc...
|
||||
|
||||
Available JSON fields:
|
||||
- ``"name"``: The name of the primitive type.
|
||||
|
||||
|
||||
- ``"enum"``: Describes a grouping of enumeration items/members.
|
||||
|
||||
Available JSON fields:
|
||||
- ``"name"``: The name of the enumeration group/type.
|
||||
- ``"type"``: This contains the type information for the enumeration group.
|
||||
This is always going to be an "int" type. Make sure you do not use this
|
||||
type as the type for the members of this enumeration group. Check the
|
||||
enumeration members type to get the correct type.
|
||||
- ``"docstring"``: you should know what this is.
|
||||
- ``"members"``: array of ``"enum_member"`` Widgets
|
||||
|
||||
|
||||
- ``"enum_member"``: Describes an enumeration item/member. Only found under
|
||||
the ``"members"`` field of an ``"enum"`` JSON type
|
||||
|
||||
Available JSON fields:
|
||||
- ``"name"``: The name of the enumeration.
|
||||
- ``"type"``: This contains the type information for the enum member.
|
||||
This gets a bit tricky because the type specified in here is not always
|
||||
going to be an "int". It will usually point to an lvgl type and the type
|
||||
of the lvgl type can be found in the ``"typedefs"`` section.
|
||||
- ``"docstring"``: you should know what this is.
|
||||
- ``"value"``: the enumeration member/item's value
|
||||
|
||||
|
||||
- ``"lvgl_type"``: This is a base type. There or no other types beneith this.
|
||||
This tells you that the type is an LVGL data type.
|
||||
|
||||
Available JSON fields:
|
||||
- ``"name"``: The name of the type.
|
||||
- ``"quals"``: array of qualifiers, IE "const
|
||||
|
||||
|
||||
- ``"struct"``: Describes a structure
|
||||
|
||||
Available JSON fields:
|
||||
- ``"name"``: The name of the structure.
|
||||
- ``"type"``: This contains the primitive type information for the structure.
|
||||
- ``"docstring"``: you should know what this is.
|
||||
- ``"fields"``: array of ``"field"`` elements.
|
||||
- ``"quals"``: array of qualifiers, IE "const"
|
||||
|
||||
|
||||
- ``"union"``: Describes a union
|
||||
|
||||
Available JSON fields:
|
||||
- ``"name"``: The name of the union.
|
||||
- ``"type"``: This contains the primitive type information for the union.
|
||||
- ``"docstring"``: you should know what this is.
|
||||
- ``"fields"``: array of ``"field"`` elements.
|
||||
- ``"quals"``: array of qualifiers, IE "const"
|
||||
|
||||
|
||||
- ``"macro"``: describes a macro. There is limited information that can be
|
||||
collected about macros and in most cases a binding will need to have these
|
||||
statically added to a binding. It is more for collecting the docstrings than
|
||||
anything else.
|
||||
|
||||
Available JSON fields:
|
||||
- ``"name"``: The name of the macro.
|
||||
- ``"docstring"``: you should know what this is.
|
||||
|
||||
|
||||
- ``"ret_type"``: return type from a function. This is only going to be seen in the ``"type"``
|
||||
element of a ``"function"`` type.
|
||||
|
||||
Available JSON fields:
|
||||
- ``"type"``: This contains the type information for the field. Check the
|
||||
``"json_type"`` to know what type you are dealing with.
|
||||
- ``"docstring"``: you should know what this is.
|
||||
|
||||
|
||||
- ``"function"``: Describes a function.
|
||||
|
||||
Available JSON fields:
|
||||
- ``"name"``: The name of the function.
|
||||
- ``"type"``: This contains the type information for the return value.
|
||||
- ``"docstring"``: you should know what this is.
|
||||
- ``"args"``: array of ``"arg"`` json types. This describes the fuction arguments/parameters.
|
||||
|
||||
|
||||
- ``"stdlib_type"``: This is a base type, meaning that there are no more
|
||||
type levels beneith this. This tells us that the type is from the C stdlib.
|
||||
|
||||
Available JSON fields:
|
||||
- ``"name"``: The name of the type.
|
||||
- ``"quals"``: array of qualifiers, IE "const
|
||||
|
||||
|
||||
- ``"unknown_type"``: This should not be seen. If it is then there needs to be
|
||||
an adjustment made to the script. Please open an issue and let us know if you see this type.
|
||||
|
||||
Available JSON fields:
|
||||
- ``"name"``: The name of the type.
|
||||
- ``"quals"``: array of qualifiers, IE "const
|
||||
|
||||
|
||||
- ``"pointer"``: This is a wrapper object to let you know that the type you
|
||||
are dealing with is a pointer
|
||||
|
||||
Available JSON fields:
|
||||
- ``"type"``: This contains the type information for the pointer. Check the
|
||||
``"json_type"`` to know what type you are dealing with.
|
||||
- ``"quals"``: array of qualifiers, IE "const", may or may not be available.
|
||||
|
||||
|
||||
- ``"typedef"``: type definitions. I will explain more on this below.
|
||||
|
||||
Available JSON fields:
|
||||
- ``"name"``: The name of the typedef.
|
||||
- ``"type"``: This contains the type information for the field. Check the
|
||||
``"json_type"`` to know what type you are dealing with.
|
||||
- ``"docstring"``: you should know what this is.
|
||||
- ``"quals"``: array of qualifiers, IE "const"
|
||||
|
||||
|
||||
|
||||
Here is an example of what the output will look like.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"enums":[
|
||||
{
|
||||
"name":"_lv_result_t",
|
||||
"type":{
|
||||
"name":"int",
|
||||
"json_type":"primitive_type"
|
||||
},
|
||||
"json_type":"enum",
|
||||
"docstring":"LVGL error codes. ",
|
||||
"members":[
|
||||
{
|
||||
"name":"LV_RESULT_INVALID",
|
||||
"type":{
|
||||
"name":"_lv_result_t",
|
||||
"json_type":"lvgl_type"
|
||||
},
|
||||
"json_type":"enum_member",
|
||||
"docstring":"",
|
||||
"value":"0x0"
|
||||
},
|
||||
{
|
||||
"name":"LV_RESULT_OK",
|
||||
"type":{
|
||||
"name":"_lv_result_t",
|
||||
"json_type":"lvgl_type"
|
||||
},
|
||||
"json_type":"enum_member",
|
||||
"docstring":"",
|
||||
"value":"0x1"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"functions":[
|
||||
{
|
||||
"name":"lv_version_info",
|
||||
"type":{
|
||||
"type":{
|
||||
"type":{
|
||||
"name":"char",
|
||||
"json_type":"primitive_type",
|
||||
"quals":[
|
||||
"const"
|
||||
]
|
||||
},
|
||||
"json_type":"pointer",
|
||||
"quals":[]
|
||||
},
|
||||
"json_type":"ret_type",
|
||||
"docstring":""
|
||||
},
|
||||
"json_type":"function",
|
||||
"docstring":"",
|
||||
"args":[
|
||||
{
|
||||
"name":null,
|
||||
"type":{
|
||||
"name":"void",
|
||||
"json_type":"primitive_type",
|
||||
"quals":[]
|
||||
},
|
||||
"json_type":"arg",
|
||||
"docstring":"",
|
||||
"quals":[]
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"function_pointers":[
|
||||
{
|
||||
"name":"lv_tlsf_walker",
|
||||
"type":{
|
||||
"type":{
|
||||
"name":"void",
|
||||
"json_type":"primitive_type",
|
||||
"quals":[]
|
||||
},
|
||||
"json_type":"ret_type",
|
||||
"docstring":""
|
||||
},
|
||||
"json_type":"function_pointer",
|
||||
"docstring":"",
|
||||
"args":[
|
||||
{
|
||||
"name":"ptr",
|
||||
"type":{
|
||||
"type":{
|
||||
"name":"void",
|
||||
"json_type":"primitive_type",
|
||||
"quals":[]
|
||||
},
|
||||
"json_type":"pointer",
|
||||
"quals":[]
|
||||
},
|
||||
"json_type":"arg",
|
||||
"docstring":""
|
||||
},
|
||||
{
|
||||
"name":"size",
|
||||
"type":{
|
||||
"name":"size_t",
|
||||
"json_type":"stdlib_type",
|
||||
"quals":[]
|
||||
},
|
||||
"json_type":"arg",
|
||||
"docstring":""
|
||||
},
|
||||
{
|
||||
"name":"used",
|
||||
"type":{
|
||||
"name":"int",
|
||||
"json_type":"primitive_type",
|
||||
"quals":[]
|
||||
},
|
||||
"json_type":"arg",
|
||||
"docstring":""
|
||||
},
|
||||
{
|
||||
"name":"user",
|
||||
"type":{
|
||||
"type":{
|
||||
"name":"void",
|
||||
"json_type":"primitive_type",
|
||||
"quals":[]
|
||||
},
|
||||
"json_type":"pointer",
|
||||
"quals":[]
|
||||
},
|
||||
"json_type":"arg",
|
||||
"docstring":""
|
||||
}
|
||||
],
|
||||
"quals":[]
|
||||
}
|
||||
],
|
||||
"structures":[
|
||||
{
|
||||
"name":"_lv_gradient_cache_t",
|
||||
"type":{
|
||||
"name":"struct",
|
||||
"json_type":"primitive_type"
|
||||
},
|
||||
"json_type":"struct",
|
||||
"docstring":null,
|
||||
"fields":[
|
||||
{
|
||||
"name":"color_map",
|
||||
"type":{
|
||||
"type":{
|
||||
"name":"lv_color_t",
|
||||
"json_type":"lvgl_type",
|
||||
"quals":[]
|
||||
},
|
||||
"json_type":"pointer",
|
||||
"quals":[]
|
||||
},
|
||||
"json_type":"field",
|
||||
"bitsize":null,
|
||||
"docstring":""
|
||||
},
|
||||
{
|
||||
"name":"opa_map",
|
||||
"type":{
|
||||
"type":{
|
||||
"name":"lv_opa_t",
|
||||
"json_type":"lvgl_type",
|
||||
"quals":[]
|
||||
},
|
||||
"json_type":"pointer",
|
||||
"quals":[]
|
||||
},
|
||||
"json_type":"field",
|
||||
"bitsize":null,
|
||||
"docstring":""
|
||||
},
|
||||
{
|
||||
"name":"size",
|
||||
"type":{
|
||||
"name":"uint32_t",
|
||||
"json_type":"stdlib_type",
|
||||
"quals":[]
|
||||
},
|
||||
"json_type":"field",
|
||||
"bitsize":null,
|
||||
"docstring":""
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"unions":[],
|
||||
"variables":[
|
||||
{
|
||||
"name":"lv_global",
|
||||
"type":{
|
||||
"name":"lv_global_t",
|
||||
"json_type":"lvgl_type",
|
||||
"quals":[]
|
||||
},
|
||||
"json_type":"variable",
|
||||
"docstring":"",
|
||||
"quals":[],
|
||||
"storage":[
|
||||
"extern"
|
||||
]
|
||||
}
|
||||
],
|
||||
"typedefs":[
|
||||
{
|
||||
"name":"lv_pool_t",
|
||||
"type":{
|
||||
"type":{
|
||||
"name":"void",
|
||||
"json_type":"primitive_type",
|
||||
"quals":[]
|
||||
},
|
||||
"json_type":"pointer"
|
||||
},
|
||||
"json_type":"typedef",
|
||||
"docstring":"",
|
||||
"quals":[]
|
||||
}
|
||||
],
|
||||
"forward_decls":[
|
||||
{
|
||||
"name":"lv_fragment_managed_states_t",
|
||||
"type":{
|
||||
"name":"struct",
|
||||
"json_type":"primitive_type"
|
||||
},
|
||||
"json_type":"forward_decl",
|
||||
"docstring":"",
|
||||
"quals":[]
|
||||
}
|
||||
],
|
||||
"macros":[
|
||||
{
|
||||
"name":"ZERO_MEM_SENTINEL",
|
||||
"json_type":"macro",
|
||||
"docstring":""
|
||||
}
|
||||
]
|
||||
}
|
||||
5
docs/details/integration/bindings/cpp.rst
Normal file
5
docs/details/integration/bindings/cpp.rst
Normal file
@@ -0,0 +1,5 @@
|
||||
===
|
||||
Cpp
|
||||
===
|
||||
|
||||
In progress: https://github.com/lvgl/lv_binding_cpp
|
||||
13
docs/details/integration/bindings/index.rst
Normal file
13
docs/details/integration/bindings/index.rst
Normal file
@@ -0,0 +1,13 @@
|
||||
========
|
||||
Bindings
|
||||
========
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
api_json
|
||||
cpp
|
||||
javascript
|
||||
micropython
|
||||
pikascript
|
||||
136
docs/details/integration/bindings/javascript.rst
Normal file
136
docs/details/integration/bindings/javascript.rst
Normal file
@@ -0,0 +1,136 @@
|
||||
==========
|
||||
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
|
||||
304
docs/details/integration/bindings/micropython.rst
Normal file
304
docs/details/integration/bindings/micropython.rst
Normal file
@@ -0,0 +1,304 @@
|
||||
.. _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 Widgets, taking advantage of Python's language features
|
||||
such as Inheritance, Closures, List Comprehension, Generators, Exception Handling, Arbitrary Precision Integers and others.
|
||||
- Make LVGL accessible to a larger audience. No need to know C to create a nice GUI on an embedded system. This goes well with
|
||||
`CircuitPython vision <https://learn.adafruit.com/welcome-to-circuitpython/what-is-circuitpython>`__.
|
||||
CircuitPython was designed with education in mind, to make it easier for new or inexperienced 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-block:: python
|
||||
|
||||
# Initialize
|
||||
import display_driver
|
||||
import lvgl as lv
|
||||
|
||||
# Create a button with a label
|
||||
scr = lv.obj()
|
||||
btn = lv.button(scr)
|
||||
btn.align(lv.ALIGN.CENTER, 0, 0)
|
||||
label = lv.label(btn)
|
||||
label.set_text('Hello World!')
|
||||
lv.screen_load(scr)
|
||||
|
||||
|
||||
How can I use it?
|
||||
-----------------
|
||||
|
||||
|
||||
Online Simulator
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
If you want to experiment with LVGL + MicroPython without downloading anything, you can use our online
|
||||
simulator! It's a fully functional LVGL + MicroPython that runs entirely in the browser and allows you to
|
||||
edit a python script and run it.
|
||||
|
||||
`Click here to experiment on the online simulator <https://sim.lvgl.io/>`__
|
||||
|
||||
Many :ref:`LVGL examples <examples>` are available also for MicroPython. Just click the link!
|
||||
|
||||
|
||||
PC Simulator
|
||||
~~~~~~~~~~~~
|
||||
|
||||
MicroPython is ported to many platforms. One notable port is "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
|
||||
- X11 on Linux
|
||||
- ESP32 specific:
|
||||
|
||||
- ILI9341
|
||||
- ILI9488
|
||||
- GC9A01
|
||||
- ST7789
|
||||
- ST7735
|
||||
|
||||
- Generic (pure Python):
|
||||
|
||||
- ILI9341
|
||||
- ST7789
|
||||
- ST7735
|
||||
|
||||
- Input drivers:
|
||||
|
||||
- SDL
|
||||
- X11
|
||||
- XPT2046
|
||||
- FT6X36
|
||||
- ESP32 ADC with resistive touch
|
||||
|
||||
|
||||
Where can I find more information?
|
||||
----------------------------------
|
||||
|
||||
- ``lv_micropython`` `README <https://github.com/lvgl/lv_micropython>`__
|
||||
- ``lv_binding_micropython`` `README <https://github.com/lvgl/lv_binding_micropython>`__
|
||||
- The `LVGL micropython forum <https://forum.lvgl.io/c/micropython>`__ (Feel free to ask anything!)
|
||||
- At MicroPython: `docs <http://docs.micropython.org/en/latest/>`__ and `forum <https://forum.micropython.org/>`__
|
||||
- `Blog Post <https://blog.lvgl.io/2019-02-20/micropython-bindings>`__, a little outdated.
|
||||
|
||||
|
||||
The MicroPython Binding is auto generated!
|
||||
------------------------------------------
|
||||
|
||||
- LVGL is a git submodule inside `lv_micropython <https://github.com/lvgl/lv_micropython>`__
|
||||
(LVGL is a git submodule of `lv_binding_micropython <https://github.com/lvgl/lv_binding_micropython>`__
|
||||
which is itself a submodule of `lv_micropython <https://github.com/lvgl/lv_micropython>`__).
|
||||
- When building lv_micropython, the public LVGL C API is scanned and MicroPython API is auto-generated. That means that
|
||||
lv_micropython provides LVGL API for **any** LVGL version, and generally does not require code changes as LVGL evolves.
|
||||
|
||||
|
||||
LVGL C API Coding Conventions
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For a summary of coding conventions to follow see the :ref:`coding-style`.
|
||||
|
||||
|
||||
.. _memory_management:
|
||||
|
||||
Memory Management
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
- When LVGL runs in MicroPython, all dynamic memory allocations (:cpp:func:`lv_malloc`) are handled by MicroPython's memory
|
||||
manager which is `garbage-collected <https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)>`__ (GC).
|
||||
- To prevent GC from collecting memory prematurely, all dynamic allocated RAM must be reachable by 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>`__
|
||||
198
docs/details/integration/bindings/pikascript.rst
Normal file
198
docs/details/integration/bindings/pikascript.rst
Normal file
@@ -0,0 +1,198 @@
|
||||
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-block:: 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-block:: 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-block:: 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_cb(event_cb_1, lv.EVENT.CLICKED, 0)
|
||||
btn2.add_event_cb(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-block:: 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-block:: 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-block:: 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
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ ./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
|
||||
80
docs/details/integration/building/cmake.rst
Normal file
80
docs/details/integration/building/cmake.rst
Normal file
@@ -0,0 +1,80 @@
|
||||
.. _build_cmake:
|
||||
|
||||
=====
|
||||
CMake
|
||||
=====
|
||||
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
This project uses CMakePresets to ensure an easy build.
|
||||
Find out more on Cmake Presets here: https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html
|
||||
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
You need to install
|
||||
|
||||
- CMake
|
||||
- Ninja (for Linux builds). Be sure to Add ninja to your PATH!
|
||||
|
||||
|
||||
How to build this project using cmake
|
||||
-------------------------------------
|
||||
|
||||
The recommended way to build this project is to use the provided CMakePresets.json. This file contains 2 configurations
|
||||
|
||||
- a windows (msvc) build using Visual Studio
|
||||
- a linux (gcc) build using Ninja
|
||||
|
||||
|
||||
More configurations will be added once available.
|
||||
|
||||
|
||||
Build with IDE
|
||||
--------------
|
||||
|
||||
The recommend way for consuming CMakePresets is a CMakePresets aware IDE such as
|
||||
|
||||
- VS 2022
|
||||
- VS Code
|
||||
- CLion
|
||||
|
||||
|
||||
Simply load this project into your IDE and select your desired preset and you are good to go.
|
||||
|
||||
|
||||
Build with CMake GUI
|
||||
--------------------
|
||||
|
||||
Open this project with CMake GUI and select your desired preset. When hitting the generate button,
|
||||
CMake will create solution files (for VS) or Ninja Files (for Linux Ninja Build)
|
||||
|
||||
The following targets are available.
|
||||
|
||||
- lvgl (the actual library, required)
|
||||
- lvgl_thorvg (an vector graphics extension, optional)
|
||||
- lvgl_examples (example usages, optional)
|
||||
- lvgl_demos (some demos, optional)
|
||||
|
||||
|
||||
All optional targets can be disabled by setting the proper cache variables.
|
||||
If you use cmake to install lvgl 3 folders will be created.
|
||||
|
||||
- include/lvgl (contains all public headers)
|
||||
- bin (contains all binaries (\*.dll))
|
||||
- lib (contains all precompiled source files (\*.lib))
|
||||
|
||||
|
||||
Build with Command line
|
||||
-----------------------
|
||||
|
||||
You can also build your project using the command line. Run the following commands
|
||||
|
||||
- ``cmake --preset windows-base``
|
||||
- ``cmake --build --preset windows-base_dbg``
|
||||
- ``ctest --preset windows-base_dbg``
|
||||
|
||||
|
||||
10
docs/details/integration/building/index.rst
Normal file
10
docs/details/integration/building/index.rst
Normal file
@@ -0,0 +1,10 @@
|
||||
=============
|
||||
Build systems
|
||||
=============
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
make
|
||||
cmake
|
||||
7
docs/details/integration/building/make.rst
Normal file
7
docs/details/integration/building/make.rst
Normal file
@@ -0,0 +1,7 @@
|
||||
.. _build_make:
|
||||
|
||||
====
|
||||
make
|
||||
====
|
||||
|
||||
LVGL can be easily integrated into any Makefile project by adding ``include lvgl/lvgl.mk`` to the main ``Makefile``.
|
||||
57
docs/details/integration/chip/arm.rst
Normal file
57
docs/details/integration/chip/arm.rst
Normal file
@@ -0,0 +1,57 @@
|
||||
.. _arm:
|
||||
|
||||
===
|
||||
Arm
|
||||
===
|
||||
|
||||
Arm is a leading semiconductor and software design company, renowned for creating the Cortex-M microcontroller (MCU) cores and Cortex-A/R (MPU) processor cores, which are integral to a wide range of devices. These cores are at the heart of many embedded systems, powering chips from industry giants such as STMicroelectronics, NXP, and Renesas. Arm's energy-efficient designs are used in billions of devices worldwide, from microcontrollers to smartphones and servers. By licensing their processor designs, Arm enables a broad ecosystem of partners to develop customized solutions optimized for performance, power, and size. Arm's architecture is highly compatible with various operating systems and software libraries, including LVGL, making it a versatile choice for developers creating efficient, high-performance graphical user interfaces.
|
||||
|
||||
Compile LVGL for Arm
|
||||
--------------------
|
||||
|
||||
No specific action is required. Any compiler that supports the target Arm architecture can be used to compile LVGL's source code, including GCC, LLVM, and AC6.
|
||||
|
||||
It is also possible to cross-compile LVGL for an MPU (instead of compiling it on the target hardware) or create a shared library. For more information, check out :ref:`build_cmake`.
|
||||
|
||||
Getting Started with AC6
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Since AC6 is a proprietary toolchain, it contains many specific optimizations, so you can expect the best performance when using it.
|
||||
|
||||
AC6 is not free, but it offers a community license that can be activated as follows:
|
||||
|
||||
1. Download and install the AC6 compiler from `Arm's website <https://developer.arm.com/Tools%20and%20Software/Arm%20Compiler%20for%20Embedded>`__.
|
||||
2. To register a community license, go to the ``bin`` folder of the compiler and, in a terminal, run ``armlm.exe activate -server https://mdk-preview.keil.arm.com -product KEMDK-COM0`` (On Linux, use ``./armlm``).
|
||||
|
||||
IDE Support
|
||||
-----------
|
||||
|
||||
There are no limitations on the supported IDEs. LVGL works in various vendors' IDEs, including Arm's Keil MDK, IAR, Renesas's e2 studio, NXP's MCUXpresso, ST's CubeIDE, as well as custom make or CMake projects.
|
||||
|
||||
Arm2D and the Helium instruction set
|
||||
------------------------------------
|
||||
|
||||
Arm Cortex-M55 and Cortex-M85 have the `SIMD Helium <https://www.arm.com/technologies/helium>`__ instruction set.
|
||||
Among many others, this can effectively speed up UI rendering. :ref:`Arm2D <arm2d>` is a library maintained by Arm that leverages the Helium instruction set.
|
||||
|
||||
Note that GCC has some known issues with Helium intrinsics. It is recommended to use AC6 or LLVM when dealing with Helium code.
|
||||
|
||||
|
||||
To add Arm2D to your project, follow these steps:
|
||||
|
||||
1. To utilize its power, ensure that ``mcpu`` is set to ``cortex-m85``, ``cortex-m55``, or ``cortex-m52`` and add the ``-fvectorize`` flag. To test without SIMD, use e.g. ``cortex-m85+nomve``.
|
||||
2. Arm2D can be downloaded from `https://github.com/ARM-software/Arm-2D <https://github.com/ARM-software/Arm-2D>`__. Consider using the ``developing`` branch, which contains the latest updates.
|
||||
3. Add ``Arm-2D/Library/Include`` to the include paths.
|
||||
4. Copy ``Arm-2D/Library/Include/template/arm_2d_cfg.h`` to any location you prefer to provide the default configuration for Arm2D. Ensure that the folder containing ``arm_2d_cfg.h`` is added to the include path.
|
||||
5. The Arm2D repository contains several examples and templates; however, ensure that only ``Arm-2D/Library/Source`` is compiled.
|
||||
6. The CMSIS DSP library also needs to be added to the project. You can use CMSIS-PACKS or add it manually.
|
||||
7. For better performance, enable ``LTO`` (Link Time Optimization) and use ``-Omax`` or ``-Ofast``.
|
||||
8. Arm2D tries to read/write multiple data with a single instruction. Therefore, it's important to use the fastest memory (e.g., ``BSS`` or ``TCM``) for LVGL's buffer to avoid memory bandwidth bottlenecks.
|
||||
9. Enable ``LV_USE_DRAW_ARM2D_SYNC 1`` and ``LV_USE_DRAW_SW_ASM LV_DRAW_SW_ASM_HELIUM`` in ``lv_conf.h``.
|
||||
|
||||
Neon Acceleration
|
||||
-----------------
|
||||
|
||||
Several Cortex-A microprocessors support the `Neon SIMD <https://www.arm.com/technologies/neon>`__ instruction set. LVGL has built-in support to improve the performance of software rendering by utilizing Neon instructions. To enable Neon acceleration, set ``LV_USE_DRAW_SW_ASM`` to ``LV_DRAW_SW_ASM_NEON`` in ``lv_conf.h``.
|
||||
|
||||
|
||||
198
docs/details/integration/chip/espressif.rst
Normal file
198
docs/details/integration/chip/espressif.rst
Normal file
@@ -0,0 +1,198 @@
|
||||
=============================
|
||||
Espressif (ESP32 Chip Series)
|
||||
=============================
|
||||
|
||||
LVGL can be used and configured as standard `ESP-IDF <https://github.com/espressif/esp-idf>`__ component.
|
||||
|
||||
If you are new to ESP-IDF, follow the instructions in the `ESP-IDF Programming guide <https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/index.html>`__ to install and set up ESP-IDF on your machine.
|
||||
|
||||
|
||||
LVGL Demo Projects for ESP32
|
||||
----------------------------
|
||||
|
||||
For a quick start with LVGL and ESP32, the following pre-configured demo projects are available for specific development boards:
|
||||
|
||||
- `ESP-BOX-3 <https://github.com/lvgl/lv_port_espressif_esp-box-3>`__
|
||||
- `ESP32-S3-LCD-EV-BOARD <https://github.com/lvgl/lv_port_espressif_esp32-s3-lcd-ev-board>`__
|
||||
- `M5Stack-CoreS3 <https://github.com/lvgl/lv_port_espressif_M5Stack_CoreS3>`__
|
||||
|
||||
Refer to the README.md files in these repositories for build and flash instructions.
|
||||
|
||||
These demo projects use Espressif's Board Support Packages (BSPs). Additional BSPs and examples are available in the `esp-bsp <https://github.com/espressif/esp-bsp>`__ repository.
|
||||
|
||||
|
||||
Using LVGL in Your ESP-IDF Project
|
||||
----------------------------------
|
||||
|
||||
The simplest way to integrate LVGL into your ESP-IDF project is via the `esp_lvgl_port <https://components.espressif.com/components/espressif/esp_lvgl_port>`__ component. This component, used in the demo projects mentioned above, provides helper functions for easy installation of LVGL and display drivers. Moreover, it can add support for touch, rotary encoders, button or USB HID inputs. It simplifies power savings, screen rotation and other platform specific nuances.
|
||||
|
||||
The esp_lvgl_port supports LVGL versions 8 and 9 and is compatible with ESP-IDF v4.4 and above. To add it to your project, use the following command:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
idf.py add-dependency "espressif/esp_lvgl_port^2.3.0"
|
||||
|
||||
By default, esp_lvgl_port depends on the latest stable version of LVGL, so no additional steps are needed for new projects. If a specific LVGL version is required, specify this in your project to avoid automatic updates. LVGL can also be used without esp_lvgl_port, as described below.
|
||||
|
||||
Obtaining LVGL
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
LVGL is distributed through `ESP Registry <https://components.espressif.com/>`__, where all LVGL releases are uploaded.
|
||||
In case you do not want to use esp_lvgl_port, you can add `LVGL component <https://components.espressif.com/component/lvgl/lvgl>`__ into your project with following command:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
idf.py add-dependency lvgl/lvgl^9.*
|
||||
|
||||
Adjust the ``^9.*`` part to match your LVGL version requirement. More information on version specifications can be found in the `IDF Component Manager documentation <https://docs.espressif.com/projects/idf-component-manager/en/latest/reference/versioning.html#range-specifications>`__. During the next build, the LVGL component will be fetched from the component registry and added to the project.
|
||||
|
||||
**Advanced usage: Use LVGL as local component**
|
||||
|
||||
For LVGL development and testing, it may be useful to use LVGL as a local component instead of from the ESP Registry, which offers only released versions and does not allow local modifications. To do this, clone LVGL to your project with the following command:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
git submodule add https://github.com/lvgl/lvgl.git components/lvgl
|
||||
|
||||
.. note::
|
||||
|
||||
All components from ``${project_dir}/components`` are automatically added to build.
|
||||
|
||||
Configuration
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
To configure LVGL, launch the configuration menu with ``idf.py menuconfig`` in your project root directory. Navigate to ``Component config`` and then ``LVGL configuration``.
|
||||
|
||||
|
||||
Support for Display and Touch Drivers
|
||||
-------------------------------------
|
||||
|
||||
For successful LVGL project you will need a display driver and optionally a touch driver. Espressif provides these drivers that are built on its `esp_lcd <https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/peripherals/lcd/index.html>`__ component.
|
||||
|
||||
- esp_lcd natively supports for some `basic displays <https://github.com/espressif/esp-idf/tree/master/components/esp_lcd/src>`__
|
||||
- Other displays are maintained in `esp-bsp repository <https://github.com/espressif/esp-bsp/tree/master/components/lcd>`__ and are uploaded to ESP Registry
|
||||
- Touch drivers are maintained in `esp-bsp repository <https://github.com/espressif/esp-bsp/tree/master/components/lcd_touch>`__ and are uploaded to ESP Registry
|
||||
|
||||
These components share a common public API, making it easy to migrate your projects across different display and touch drivers.
|
||||
|
||||
To add a display or touch driver to your project, use a command like:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
idf.py add-dependency "espressif/esp_lcd_gc9a01^2.0.0"
|
||||
|
||||
Using the File System under ESP-IDF
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
ESP-IDF uses the standard C functions (``fopen``, ``fread``) in all storage related APIs.
|
||||
This allows seamless interoperability with LVGL when enabling the :c:macro:`LV_USE_FS_STDIO` configuration.
|
||||
The process is described in details below, using ``SPIFFS`` as demonstration.
|
||||
|
||||
- **Decide what storage system you want to use**
|
||||
|
||||
ESP-IDF has many, ready-to-use examples like
|
||||
`SPIFFS <https://github.com/espressif/esp-idf/tree/master/examples/storage/spiffsgen>`__
|
||||
,
|
||||
`SD Card <https://github.com/espressif/esp-idf/tree/master/examples/storage/sd_card/sdspi>`__
|
||||
and
|
||||
`LittleFS <https://github.com/espressif/esp-idf/tree/master/examples/storage/littlefs>`__
|
||||
.
|
||||
|
||||
- **Re-configure your own project**
|
||||
|
||||
The example project should be examined for details, but in general the changes involve:
|
||||
|
||||
- Enabling LVGL's STDIO file system in the configuration
|
||||
|
||||
You can use ``menuconfig``:
|
||||
|
||||
- ``Component config → LVGL configuration → 3rd Party Libraries``: enable ``File system on top of stdio API``
|
||||
- Then select ``Set an upper cased letter on which the drive will accessible`` and set it to ``65`` (ASCII **A**)
|
||||
- You can also set ``Default driver letter`` to 65 to skip the prefix in file paths.
|
||||
|
||||
- Modifying the partition table
|
||||
|
||||
The exact configuration depends on your flash size and existing partitions,
|
||||
but the new final result should look something like this:
|
||||
|
||||
.. csv-table:: Partition Table
|
||||
|
||||
nvs, data, nvs, 0x9000, 0x6000
|
||||
phy_init, data, phy, 0xf000, 0x1000
|
||||
factory, app, factory, 0x10000, 1400k
|
||||
storage, data, spiffs, , 400k
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
If you are not using a custom ``partition.csv`` yet, it can be added
|
||||
via ``menuconfig`` (``Partition Table → Partition Table → Custom partition table CSV``).
|
||||
|
||||
- Apply changes to the build system
|
||||
|
||||
Some ESP file systems provide automatic generation from a host folder using CMake. The proper line(s) must be copied to ``main/CMakeLists.txt``
|
||||
|
||||
.. note::
|
||||
|
||||
``LittleFS`` has extra dependencies that should be added to ``main/idf_component.yml``
|
||||
|
||||
- **Prepare the image files**
|
||||
|
||||
LVGL's ``LVGLImage.py`` Python tool can be used to convert images to binary pixel map files.
|
||||
It supports various formats and compression.
|
||||
|
||||
Meanwhile 3rd party libraries
|
||||
(like :ref:`LodePNG<lodepng_rst>` and :ref:`Tiny JPEG<tjpgd>`)
|
||||
allow using image files without conversion.
|
||||
|
||||
After preparing the files, they should be moved to the target device:
|
||||
|
||||
- If properly activated a **SPIFFS** file system based on the ``spiffs_image`` folder should be automatically generated and later flashed to the target
|
||||
- Similar mechanism for **LittleFS** uses the ``flash_data`` folder, but it's only available for Linux hosts
|
||||
- For the **SD Card**, a traditional file browser can be used
|
||||
|
||||
- **Invoke proper API calls in the application code**
|
||||
|
||||
The core functionality requires only a few lines. The following example draws the image as well.
|
||||
|
||||
.. code:: c
|
||||
|
||||
#include "esp_spiffs.h"
|
||||
|
||||
void lv_example_image_from_esp_fs(void) {
|
||||
|
||||
esp_vfs_spiffs_conf_t conf = {
|
||||
.base_path = "/spiffs",
|
||||
.partition_label = NULL,
|
||||
.max_files = 5,
|
||||
.format_if_mount_failed = false
|
||||
};
|
||||
|
||||
esp_err_t ret = esp_vfs_spiffs_register(&conf);
|
||||
|
||||
if (ret != ESP_OK) {
|
||||
ESP_LOGE(TAG, "Failed to register SPIFF filesystem");
|
||||
return;
|
||||
}
|
||||
|
||||
lv_obj_t * obj = lv_image_create(lv_screen_active());
|
||||
lv_image_set_src(widget, "A:/spiffs/logo.bin");
|
||||
lv_obj_center(widget);
|
||||
}
|
||||
|
||||
- **Build and flash**
|
||||
|
||||
After calling ``idf.py build flash`` the picture should be displayed on the screen.
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
Changes made by ``menuconfig`` are not being tracked in the repository if the ``sdkconfig`` file is added to ``.gitignore``, which is the default for many ESP-IDF projects.
|
||||
To make your configuration permanent, add the following lines to ``sdkconfig.defaults``:
|
||||
|
||||
.. code:: c
|
||||
|
||||
CONFIG_PARTITION_TABLE_CUSTOM=y
|
||||
CONFIG_LV_USE_FS_STDIO=y
|
||||
CONFIG_LV_FS_STDIO_LETTER=65
|
||||
CONFIG_LV_LV_FS_DEFAULT_DRIVE_LETTER=65
|
||||
12
docs/details/integration/chip/index.rst
Normal file
12
docs/details/integration/chip/index.rst
Normal file
@@ -0,0 +1,12 @@
|
||||
============
|
||||
Chip vendors
|
||||
============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
arm
|
||||
espressif
|
||||
nxp
|
||||
renesas
|
||||
stm32
|
||||
410
docs/details/integration/chip/nxp.rst
Normal file
410
docs/details/integration/chip/nxp.rst
Normal file
@@ -0,0 +1,410 @@
|
||||
===
|
||||
NXP
|
||||
===
|
||||
|
||||
NXP has integrated LVGL into the MCUXpresso SDK packages for several of our
|
||||
microcontrollers as an optional software component, allowing easy evaluation and
|
||||
migration into your product design. LVGL is a free and open-source embedded
|
||||
graphic library with features that enable you to create embedded GUIs with
|
||||
intuitive graphical elements, beautiful visual effects and a low memory
|
||||
footprint. The complete graphic framework includes a variety of widgets for you
|
||||
to use in the creation of your GUI, and supports more advanced functions such as
|
||||
animations and anti-aliasing.
|
||||
|
||||
LVGL enables graphics in our free GUI Guider UI tool. It's available for use
|
||||
with NXP’s general purpose and crossover microcontrollers, providing developers
|
||||
with a tool for creating complete, high quality GUI applications with LVGL.
|
||||
|
||||
Creating new project with LVGL
|
||||
------------------------------
|
||||
|
||||
`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. 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
|
||||
~~~~~~~~~~~~~~~
|
||||
Basic configuration:
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- Select NXP PXP engine in "lv_conf.h": Set :c:macro:`LV_USE_PXP` to `1`.
|
||||
- In order to use PXP as a draw unit, select in "lv_conf.h": Set :c:macro:`LV_USE_DRAW_PXP` to `1`.
|
||||
- In order to use PXP to rotate the screen, select in "lv_conf.h": Set :c:macro:`LV_USE_ROTATE_PXP` to `1`.
|
||||
- Enable PXP asserts in "lv_conf.h": Set :c:macro: `LV_USE_PXP_ASSERT` to `1`.
|
||||
There are few PXP assertions that can stop the program execution in case the
|
||||
c:macro:`LV_ASSERT_HANDLER` is set to `while(1);` (Halt by default). Else,
|
||||
there will be logged just an error message via `LV_LOG_ERROR`.
|
||||
- If :c:macro:`SDK_OS_FREE_RTOS` symbol is defined, FreeRTOS implementation
|
||||
will be used, otherwise bare metal code will be included.
|
||||
|
||||
Basic initialization:
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
PXP draw initialization is done automatically in :cpp:func:`lv_init()` once the
|
||||
PXP is enabled as a draw unit or to rotate the screen, no user code is required:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#if LV_USE_DRAW_PXP || LV_USE_ROTATE_PXP
|
||||
lv_draw_pxp_init();
|
||||
#endif
|
||||
|
||||
During PXP initialization, a new draw unit `lv_draw_pxp_unit_t` will be created
|
||||
with the additional callbacks, if :c:macro:`LV_USE_DRAW_PXP` is set to `1`:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
lv_draw_pxp_unit_t * draw_pxp_unit = lv_draw_create_unit(sizeof(lv_draw_pxp_unit_t));
|
||||
draw_pxp_unit->base_unit.evaluate_cb = _pxp_evaluate;
|
||||
draw_pxp_unit->base_unit.dispatch_cb = _pxp_dispatch;
|
||||
draw_pxp_unit->base_unit.delete_cb = _pxp_delete;
|
||||
|
||||
|
||||
and an addition thread `_pxp_render_thread_cb()` will be spawned in order to
|
||||
handle the supported draw tasks.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#if LV_USE_PXP_DRAW_THREAD
|
||||
lv_thread_init(&draw_pxp_unit->thread, LV_THREAD_PRIO_HIGH, _pxp_render_thread_cb, 2 * 1024, draw_pxp_unit);
|
||||
#endif
|
||||
|
||||
If `LV_USE_PXP_DRAW_THREAD` is not defined, then no additional draw thread will be created
|
||||
and the PXP drawing task will get executed on the same LVGL main thread.
|
||||
|
||||
`_pxp_evaluate()` will get called after each task is being created and will
|
||||
analyze if the task is supported by PXP or not. If it is supported, then an
|
||||
preferred score and the draw unit id will be set to the task. An `score` equal
|
||||
to `100` is the default CPU score. Smaller score means that PXP is capable of
|
||||
drawing it faster.
|
||||
|
||||
`_pxp_dispatch()` is the PXP dispatcher callback, it will take a ready to draw
|
||||
task (having the `DRAW_UNIT_ID_PXP` set) and will pass the task to the PXP draw
|
||||
unit for processing.
|
||||
|
||||
`_pxp_delete()` will cleanup the PXP draw unit.
|
||||
|
||||
|
||||
Features supported:
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
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 tasks are available in "src/draw/nxp/pxp/lv_draw_pxp.c":
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
switch(t->type) {
|
||||
case LV_DRAW_TASK_TYPE_FILL:
|
||||
lv_draw_pxp_fill(draw_unit, t->draw_dsc, &t->area);
|
||||
break;
|
||||
case LV_DRAW_TASK_TYPE_IMAGE:
|
||||
lv_draw_pxp_img(draw_unit, t->draw_dsc, &t->area);
|
||||
break;
|
||||
case LV_DRAW_TASK_TYPE_LAYER:
|
||||
lv_draw_pxp_layer(draw_unit, t->draw_dsc, &t->area);
|
||||
break;
|
||||
default:
|
||||
break;
|
||||
}
|
||||
|
||||
Additional, the screen rotation can be handled by the PXP:
|
||||
|
||||
.. code-block::c
|
||||
|
||||
void lv_draw_pxp_rotate(const void * src_buf, void * dest_buf, int32_t src_width, int32_t src_height,
|
||||
int32_t src_stride, int32_t dest_stride, lv_display_rotation_t rotation,
|
||||
lv_color_format_t cf);
|
||||
|
||||
- Fill area with color (w/o radius, w/o gradient) + optional opacity.
|
||||
- Blit source image RGB565/ARGB888/XRGB8888 over destination.
|
||||
RGB565/RGB888/ARGB888/XRGB8888 + optional opacity.
|
||||
- Recolor source image RGB565.
|
||||
- Scale and rotate (90, 180, 270 degree) source image RGB565.
|
||||
- Blending layers (w/ same supported formats as blitting).
|
||||
- Rotate screen (90, 180, 270 degree).
|
||||
|
||||
|
||||
Known limitations:
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- PXP can only rotate at 90x angles.
|
||||
- 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.
|
||||
- Recolor or transformation for images w/ opacity or alpha channel can't be
|
||||
obtained in a single PXP pipeline configuration. Two or multiple steps would
|
||||
be required.
|
||||
- Buffer address must be aligned to 64 bytes: set :c:macro:`LV_DRAW_BUF_ALIGN`
|
||||
to `64` in "lv_conf.h".
|
||||
No stride alignment is required: set :c:macro:`LV_DRAW_BUF_STRIDE_ALIGN` to
|
||||
`1` in "lv_conf.h".
|
||||
|
||||
Project setup:
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
- Add PXP related source files (and corresponding headers if available) to
|
||||
project:
|
||||
|
||||
- "src/draw/nxp/pxp/lv_draw_buf_pxp.c": draw buffer callbacks
|
||||
- "src/draw/nxp/pxp/lv_draw_pxp_fill.c": fill area
|
||||
- "src/draw/nxp/pxp/lv_draw_pxp_img.c": blit image (w/ optional recolor or
|
||||
transformation)
|
||||
- "src/draw/nxp/pxp/lv_draw_pxp_layer.c": layer blending
|
||||
- "src/draw/nxp/pxp/lv_draw_pxp.c": draw unit initialization
|
||||
- "src/draw/nxp/pxp/lv_pxp_cfg.c": init, deinit, run/wait PXP device
|
||||
- "src/draw/nxp/pxp/lv_pxp_osa.c": OS abstraction (FreeRTOS or bare metal)
|
||||
- "src/draw/nxp/pxp/lv_pxp_utils.c": function helpers
|
||||
|
||||
- PXP related code depends on two drivers provided by MCU SDK. These drivers
|
||||
need to be added to project:
|
||||
|
||||
- fsl_pxp.c: PXP driver
|
||||
- fsl_cache.c: CPU cache handling functions
|
||||
|
||||
|
||||
PXP default configuration:
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- Implementation depends on multiple OS-specific functions. The struct
|
||||
:cpp:struct:`pxp_cfg_t` with callback pointers is used as a parameter for the
|
||||
:cpp:func:`lv_pxp_init()` function. Default implementation for FreeRTOS and
|
||||
bare metal is provided in lv_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.
|
||||
- :cpp:func:`pxp_wait()`: Wait for PXP completion.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Basic configuration:
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- Select NXP VGLite engine in "lv_conf.h": Set :c:macro:`LV_USE_DRAW_VGLITE` to
|
||||
`1`. :c:macro:`SDK_OS_FREE_RTOS` symbol needs to be defined so that FreeRTOS
|
||||
driver osal implementation will be enabled.
|
||||
- Enable VGLite asserts in "lv_conf.h": Set :c:macro: `LV_USE_VGLITE_ASSERT` to
|
||||
`1`.
|
||||
VGLite assertions will verify the driver API status code and in any error, it
|
||||
can stop the program execution in case the c:macro: `LV_ASSERT_HANDLER` is set
|
||||
to `while(1);` (Halt by default). Else, there will be logged just an error
|
||||
message via `LV_LOG_ERROR`.
|
||||
|
||||
Basic initialization:
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Initialize VGLite GPU before calling :cpp:func:`lv_init()` by specifying the
|
||||
width/height of tessellation window. The default values for tesselation width
|
||||
and height, and command buffer size are in the SDK file "vglite_support.h".
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#if LV_USE_DRAW_VGLITE
|
||||
#include "vg_lite.h"
|
||||
#include "vglite_support.h"
|
||||
#endif
|
||||
...
|
||||
#if LV_USE_DRAW_VGLITE
|
||||
if(vg_lite_init(DEFAULT_VG_LITE_TW_WIDTH, DEFAULT_VG_LITE_TW_HEIGHT) != VG_LITE_SUCCESS)
|
||||
{
|
||||
PRINTF("VGLite init error. STOP.");
|
||||
vg_lite_close();
|
||||
while (1)
|
||||
;
|
||||
}
|
||||
|
||||
if (vg_lite_set_command_buffer_size(VG_LITE_COMMAND_BUFFER_SIZE) != VG_LITE_SUCCESS)
|
||||
{
|
||||
PRINTF("VGLite set command buffer. STOP.");
|
||||
vg_lite_close();
|
||||
while (1)
|
||||
;
|
||||
}
|
||||
#endif
|
||||
|
||||
VGLite draw initialization is done automatically in :cpp:func:`lv_init()` once
|
||||
the VGLite is enabled, no user code is required:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#if LV_USE_DRAW_VGLITE
|
||||
lv_draw_vglite_init();
|
||||
#endif
|
||||
|
||||
During VGLite initialization, a new draw unit `lv_draw_vglite_unit_t` will be
|
||||
created with the additional callbacks:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
lv_draw_vglite_unit_t * draw_vglite_unit = lv_draw_create_unit(sizeof(lv_draw_vglite_unit_t));
|
||||
draw_vglite_unit->base_unit.evaluate_cb = _vglite_evaluate;
|
||||
draw_vglite_unit->base_unit.dispatch_cb = _vglite_dispatch;
|
||||
draw_vglite_unit->base_unit.delete_cb = _vglite_delete;
|
||||
|
||||
and an addition thread `_vglite_render_thread_cb()` will be spawned in order to
|
||||
handle the supported draw tasks.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#if LV_USE_VGLITE_DRAW_THREAD
|
||||
lv_thread_init(&draw_vglite_unit->thread, LV_THREAD_PRIO_HIGH, _vglite_render_thread_cb, 2 * 1024, draw_vglite_unit);
|
||||
#endif
|
||||
|
||||
If `LV_USE_VGLITE_DRAW_THREAD` is not defined, then no additional draw thread will be created
|
||||
and the VGLite drawing task will get executed on the same LVGL main thread.
|
||||
|
||||
`_vglite_evaluate()` will get called after each task is being created and will
|
||||
analyze if the task is supported by VGLite or not. If it is supported, then an
|
||||
preferred score and the draw unit id will be set to the task. An `score` equal
|
||||
to `100` is the default CPU score. Smaller score means that VGLite is capable of
|
||||
drawing it faster.
|
||||
|
||||
`_vglite_dispatch()` is the VGLite dispatcher callback, it will take a ready to
|
||||
draw task (having the `DRAW_UNIT_ID_VGLITE` set) and will pass the task to the
|
||||
VGLite draw unit for processing.
|
||||
|
||||
`_vglite_delete()` will cleanup the VGLite draw unit.
|
||||
|
||||
|
||||
Advanced configuration:
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- Enable VGLite blit split in "lv_conf.h":
|
||||
Set :c:macro: `LV_USE_VGLITE_BLIT_SPLIT` to `1`.
|
||||
Enabling the blit split workaround will mitigate any quality degradation issue
|
||||
on screen's dimension > 352 pixels.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define VGLITE_BLIT_SPLIT_THR 352
|
||||
|
||||
- By default, the blit split threshold is set to 352. Blits with width or height
|
||||
higher than this value will be done in multiple steps. Value must be multiple
|
||||
of stride alignment in px. For most color formats, the alignment is 16px
|
||||
(except the index formats). Transformation will not be supported once with
|
||||
the blit split.
|
||||
|
||||
- Enable VGLite draw task synchronously in "lv_conf.h":
|
||||
Set :c:macro: `LV_USE_VGLITE_DRAW_ASYNC` to `1`.
|
||||
Multiple draw tasks can be queued and flushed them once to the GPU based on
|
||||
the GPU idle status. If GPU is busy, the task will be queued, and the VGLite
|
||||
dispatcher will ask for a new available task. If GPU is idle, the queue with
|
||||
any pending tasks will be flushed to the GPU. The completion status of draw
|
||||
task will be sent to the main LVGL thread asynchronously.
|
||||
|
||||
Features supported:
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Several drawing features in LVGL can be offloaded to the VGLite engine. The CPU
|
||||
is available for other operations while the GPU 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 tasks are available in "src/draw/nxp/pxp/lv_draw_vglite.c":
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
switch(t->type) {
|
||||
case LV_DRAW_TASK_TYPE_LABEL:
|
||||
lv_draw_vglite_label(draw_unit, t->draw_dsc, &t->area);
|
||||
break;
|
||||
case LV_DRAW_TASK_TYPE_FILL:
|
||||
lv_draw_vglite_fill(draw_unit, t->draw_dsc, &t->area);
|
||||
break;
|
||||
case LV_DRAW_TASK_TYPE_BORDER:
|
||||
lv_draw_vglite_border(draw_unit, t->draw_dsc, &t->area);
|
||||
break;
|
||||
case LV_DRAW_TASK_TYPE_IMAGE:
|
||||
lv_draw_vglite_img(draw_unit, t->draw_dsc, &t->area);
|
||||
break;
|
||||
case LV_DRAW_TASK_TYPE_ARC:
|
||||
lv_draw_vglite_arc(draw_unit, t->draw_dsc, &t->area);
|
||||
break;
|
||||
case LV_DRAW_TASK_TYPE_LINE:
|
||||
lv_draw_vglite_line(draw_unit, t->draw_dsc);
|
||||
break;
|
||||
case LV_DRAW_TASK_TYPE_LAYER:
|
||||
lv_draw_vglite_layer(draw_unit, t->draw_dsc, &t->area);
|
||||
break;
|
||||
case LV_DRAW_TASK_TYPE_TRIANGLE:
|
||||
lv_draw_vglite_triangle(draw_unit, t->draw_dsc);
|
||||
break;
|
||||
default:
|
||||
break;
|
||||
}
|
||||
|
||||
|
||||
All the below operation can be done in addition with optional opacity.
|
||||
|
||||
- Fill area with color (w/ radius or gradient).
|
||||
- Blit source image (any format from ``_vglite_src_cf_supported()``) over
|
||||
destination (any format from ``_vglite_dest_cf_supported()``).
|
||||
- Recolor source image.
|
||||
- Scale and rotate (any decimal degree) source image.
|
||||
- Blending layers (w/ same supported formats as blitting).
|
||||
- Draw letters (blit bitmap letters / raster font).
|
||||
- Draw full borders (LV_BORDER_SIDE_FULL).
|
||||
- Draw arcs (w/ rounded edges).
|
||||
- Draw lines (w/ dash or rounded edges).
|
||||
- Draw triangles with color (w/ gradient).
|
||||
|
||||
|
||||
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`).
|
||||
|
||||
|
||||
Project setup:
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
- Add VGLite related source files (and corresponding headers if available) to
|
||||
project:
|
||||
|
||||
- "src/draw/nxp/vglite/lv_draw_buf_vglite.c": draw buffer callbacks
|
||||
- "src/draw/nxp/vglite/lv_draw_vglite_arc.c": draw arc
|
||||
- "src/draw/nxp/vglite/lv_draw_vglite_border.c": draw border
|
||||
- "src/draw/nxp/vglite/lv_draw_vglite_fill.c": fill area
|
||||
- "src/draw/nxp/vglite/lv_draw_vglite_img.c": blit image (w/ optional recolor or transformation)
|
||||
- "src/draw/nxp/vglite/lv_draw_vglite_label.c": draw label
|
||||
- "src/draw/nxp/vglite/lv_draw_vglite_layer.c": layer blending
|
||||
- "src/draw/nxp/vglite/lv_draw_vglite_line.c": draw line
|
||||
- "src/draw/nxp/vglite/lv_draw_vglite_triangle.c": draw triangle
|
||||
- "src/draw/nxp/vglite/lv_draw_vglite.c": draw unit initialization
|
||||
- "src/draw/nxp/vglite/lv_vglite_buf.c": init/get vglite buffer
|
||||
- "src/draw/nxp/vglite/lv_vglite_matrix.c": set vglite matrix
|
||||
- "src/draw/nxp/vglite/lv_vglite_path.c": create vglite path data
|
||||
- "src/draw/nxp/vglite/lv_vglite_utils.c": function helpers
|
||||
224
docs/details/integration/chip/renesas.rst
Normal file
224
docs/details/integration/chip/renesas.rst
Normal file
@@ -0,0 +1,224 @@
|
||||
.. _renesas:
|
||||
|
||||
=======
|
||||
Renesas
|
||||
=======
|
||||
|
||||
`Renesas <https://renesas.com/>`__ is an official partner of LVGL. Therefore, LVGL contains built-in support for
|
||||
`Dave2D <https://www.renesas.com/document/mas/tes-dave2d-driver-documentation>`__ (the GPU of Renesas) and we also maintain
|
||||
ready-to-use Renesas projects.
|
||||
|
||||
|
||||
Dave2D
|
||||
------
|
||||
|
||||
Dave2D is capable of accelerating most of the drawing operations of LVGL:
|
||||
|
||||
- Rectangle drawing, even with gradients
|
||||
- Image drawing, scaling, and rotation
|
||||
- Letter drawing
|
||||
- Triangle drawing
|
||||
- Line drawing
|
||||
|
||||
|
||||
As Dave2D works in the background, the CPU is free for other tasks. In practice, during rendering, Dave2D can reduce the CPU usage by
|
||||
half or to one-third, depending on the application.
|
||||
|
||||
|
||||
GLCDC
|
||||
-----
|
||||
|
||||
GLCDC is a multi-stage graphics output peripheral available in several Renesas MCUs. It is able to drive LCD panels via a highly
|
||||
configurable RGB interface.
|
||||
|
||||
More info can be found at the :ref:`driver's page<renesas_glcdc>`.
|
||||
|
||||
|
||||
Supported boards
|
||||
----------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 10 30 30 30
|
||||
|
||||
* -
|
||||
- **EK-RA8D1**
|
||||
- **EK-RA6M3G**
|
||||
- **RX72N Envision Kit**
|
||||
* - CPU
|
||||
- 480MHz, Arm Cortex-M85 core
|
||||
- 120MHz, Arm Cortex-M4 core
|
||||
- 240MHz, Renesas RXv3 core
|
||||
* - Memory
|
||||
-
|
||||
| 1MB internal, 64MB external SDRAM
|
||||
| 2MB internal, 64MB External Octo-SPI Flash
|
||||
-
|
||||
| 640kB internal SRAM
|
||||
| 2MB internal, 32MB external QSPI Flash
|
||||
-
|
||||
| 1MB internal SRAM
|
||||
| 4MB internal, 32MB external QSPI Flash
|
||||
* - Display
|
||||
-
|
||||
| 4.5”
|
||||
| 480x854
|
||||
| 2-lane MIPI
|
||||
-
|
||||
| 4.3”
|
||||
| 480x272
|
||||
| Parallel RGB565
|
||||
-
|
||||
| 4.3”
|
||||
| 480x272
|
||||
| Parallel RGB565
|
||||
* - `Board <https://lvgl.io/boards>`__ video
|
||||
- .. raw:: html
|
||||
|
||||
<iframe width="320" height="180" src="https://www.youtube.com/embed/WkJPB8wto_U" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
|
||||
|
||||
- .. raw:: html
|
||||
|
||||
<iframe width="320" height="180" src="https://www.youtube.com/embed/0kar4Ee3Qic" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
|
||||
|
||||
- .. raw:: html
|
||||
|
||||
<iframe width="320" height="180" src="https://www.youtube.com/embed/__56v8DsfH0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
|
||||
|
||||
* - Links
|
||||
- `Demo repository for EK-RA8D1 <https://github.com/lvgl/lv_port_renesas_ek-ra8d1>`__
|
||||
- `Demo repository for EK-RA6M3G <https://github.com/lvgl/lv_port_renesas_ek-ra6m3g>`__
|
||||
- `Demo repository for RX72N Envision Kit <https://github.com/lvgl/lv_port_renesas_rx72n-envision-kit>`__
|
||||
|
||||
|
||||
Get started with the Renesas ecosystem
|
||||
--------------------------------------
|
||||
|
||||
.. |img_debug_btn| image:: /misc/renesas/debug_btn.png
|
||||
:alt: Debug button
|
||||
|
||||
.. dropdown:: RA Family
|
||||
|
||||
- The official IDE of Renesas is called e² studio. As it's Eclipse-based, it runs on Windows, Linux, and Mac as well.
|
||||
The RA family requires the latest version with FSP 5.3. It can be downloaded `here <https://www.renesas.com/us/en/software-tool/flexible-software-package-fsp>`__.
|
||||
- JLink is used for debugging, it can be downloaded `here <https://www.segger.com/downloads/jlink/>`__.
|
||||
- Clone the ready-to-use repository for your selected board:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git clone https://github.com/lvgl/lv_port_renesas_ek-ra8d1.git --recurse-submodules
|
||||
|
||||
|
||||
Downloading the `.zip` from GitHub doesn't work as it doesn't download the submodules.
|
||||
- Open e² studio, go to ``File`` -> ``Import project`` and select ``General`` / ``Existing projects into workspace``
|
||||
- Browse the cloned folder and press ``Finish``.
|
||||
- Double click on ``configuration.xml``. This will activate the `Configuration Window`.
|
||||
|
||||
Renesas' Flexible Software Package (FSP) incudes BSP and HAL layer support extended with multiple RTOS variants and other middleware stacks.
|
||||
The components will be available via code generation, including the entry point of *"main.c"*.
|
||||
|
||||
Press ``Generate Project Content`` in the top right corner.
|
||||
|
||||
.. image:: /misc/renesas/generate.png
|
||||
:alt: Code generation with FSP
|
||||
|
||||
- Build the project by pressing ``Ctrl`` + ``Alt`` + ``B``
|
||||
- Click the Debug button (|img_debug_btn|). If prompted with `Debug Configurations`, on the `Debugger` tab select the ``J-Link ARM`` as `Debug hardware` and the proper IC as `Target Device`:
|
||||
|
||||
- ``R7FA8D1BH`` for EK-RA8D1
|
||||
|
||||
.. image:: /misc/renesas/debug_ra8.png
|
||||
:alt: Debugger parameters for RA8
|
||||
|
||||
- ``R7FA6M3AH`` for EK-RA6M3G
|
||||
|
||||
.. image:: /misc/renesas/debug_ra6.png
|
||||
:alt: Debugger parameters for RA6
|
||||
|
||||
.. note::
|
||||
On EK-RA8D1 boards, the ``SW1`` DIP switch (middle of the board) 7 should be ON, all others are OFF.
|
||||
|
||||
.. dropdown:: RX Family
|
||||
|
||||
- The official IDE of Renesas is called e² studio. As it's Eclipse-based, it runs on Windows, Linux, and Mac as well.
|
||||
It can be downloaded `here <https://www.renesas.com/us/en/software-tool/e-studio>`__.
|
||||
- Download and install the required driver for the debugger
|
||||
|
||||
- for Windows: `64 bit here <https://www.renesas.com/us/en/document/uid/usb-driver-renesas-mcu-tools-v27700-64-bit-version-windows-os?r=488806>`__
|
||||
and `32 bit here <https://www.renesas.com/us/en/document/uid/usb-driver-renesas-mcu-toolse2e2-liteie850ie850apg-fp5-v27700for-32-bit-version-windows-os?r=488806>`__
|
||||
- for Linux: `here <https://www.renesas.com/us/en/document/swo/e2-emulator-e2-emulator-lite-linux-driver?r=488806>`__
|
||||
|
||||
- RX72 requires an external compiler for the RXv3 core. A free and open-source version is available
|
||||
`here <https://llvm-gcc-renesas.com/rx-download-toolchains/>`__ after a registration.
|
||||
|
||||
The compiler must be activated in e² studio:
|
||||
|
||||
- Go to go to ``Help`` -> ``Add Renesas Toolchains``
|
||||
- Press the ``Add...`` button
|
||||
- Browse the installation folder of the toolchain
|
||||
|
||||
<br/>
|
||||
|
||||
.. image:: /misc/renesas/toolchains.png
|
||||
:alt: Toolchains
|
||||
|
||||
- Clone the ready-to-use `lv_port_renesas_rx72n-envision-kit <https://github.com/lvgl/lv_port_renesas_rx72n-envision-kit.git>`__ repository:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git clone https://github.com/lvgl/lv_port_renesas_rx72n-envision-kit.git --recurse-submodules
|
||||
|
||||
|
||||
Downloading the `.zip` from GitHub doesn't work as it doesn't download the submodules.
|
||||
|
||||
- Open e² studio, go to ``File`` -> ``Import project`` and select ``General`` / ``Existing projects into workspace``
|
||||
- Select the cloned folder and press ``Finish``.
|
||||
- Double click on ``RX72N_EnVision_LVGL.scfg``. This will activate the `Configuration Window`.
|
||||
|
||||
Renesas' Smart Configurator (SMC) incudes BSP and HAL layer support extended with multiple RTOS variants and other middleware stacks.
|
||||
The components will be available via code generation, including the entry point of the application.
|
||||
|
||||
Press ``Generate Code`` in the top right corner.
|
||||
|
||||
.. image:: /misc/renesas/generate_smc.png
|
||||
:alt: Code generation with SMC
|
||||
|
||||
- Build the project by pressing ``Ctrl`` + ``Alt`` + ``B``
|
||||
- Click the Debug button (|img_debug_btn|). If prompted with `Debug Configurations`, on the `Debugger` tab select the ``E2 Lite``
|
||||
as `Debug hardware` and ``R5F572NN`` as `Target Device`:
|
||||
|
||||
.. image:: /misc/renesas/debug_rx72.png
|
||||
:alt: Debugger parameters for RX72
|
||||
|
||||
.. note::
|
||||
Make sure that both channels of ``SW1`` DIP switch (next to ``ECN1``) are OFF.
|
||||
|
||||
|
||||
Modify the project
|
||||
------------------
|
||||
|
||||
|
||||
Open a demo
|
||||
~~~~~~~~~~~
|
||||
|
||||
The entry point of the main task is contained in ``src/LVGL_thread_entry.c`` in all 3 projects.
|
||||
|
||||
You can disable the LVGL demos (or just comment them out) and call some ``lv_example_...()`` functions, or add your custom code.
|
||||
|
||||
|
||||
Configuration
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
``src/lv_conf.h`` contains the most important settings for LVGL. Namely:
|
||||
|
||||
- :c:macro:`LV_COLOR_DEPTH` to set LVGL's default color depth
|
||||
- :c:macro:`LV_MEM_SIZE` to set the maximum RAM available for LVGL
|
||||
- :c:macro:`LV_USE_DAVE2D` to enable the GPU
|
||||
|
||||
|
||||
Hardware and software components can be modified in a visual way using the `Configuration Window`.
|
||||
|
||||
|
||||
Support
|
||||
-------
|
||||
|
||||
In case of any problems or questions open an issue in the corresponding repository.
|
||||
295
docs/details/integration/chip/stm32.rst
Normal file
295
docs/details/integration/chip/stm32.rst
Normal file
@@ -0,0 +1,295 @@
|
||||
=====
|
||||
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 to
|
||||
:ref:`add_lvgl_to_your_project` and 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-block:: c
|
||||
|
||||
/* Frame buffers
|
||||
* Static or global buffer(s). The second buffer is optional
|
||||
* TODO: Adjust color format and choose buffer size. DISPLAY_WIDTH * 10 is one suggestion. */
|
||||
#define BYTES_PER_PIXEL (LV_COLOR_FORMAT_GET_SIZE(LV_COLOR_FORMAT_RGB565)) /* will be 2 for RGB565 */
|
||||
#define BUFF_SIZE (DISPLAY_WIDTH * 10 * BYTES_PER_PIXEL)
|
||||
static uint8_t buf_1[BUFF_SIZE];
|
||||
static uint8_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_display_create`, and register the frame buffers using
|
||||
:cpp:func:`lv_display_set_buffers`.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
//Initialise LVGL UI library
|
||||
lv_init();
|
||||
|
||||
lv_display_t * disp = lv_display_create(WIDTH, HEIGHT); /* Basic initialization with horizontal and vertical resolution in pixels */
|
||||
lv_display_set_flush_cb(disp, my_flush_cb); /* Set a flush callback to draw to the display */
|
||||
lv_display_set_buffers(disp, buf_1, buf_2, sizeof(buf_1), LV_DISPLAY_RENDER_MODE_PARTIAL); /* Set an initialized buffer */
|
||||
|
||||
- Create some dummy Widgets to test the output:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* Change 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-block:: 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-block:: 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-block:: c
|
||||
|
||||
void my_flush_cb(lv_display_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_display_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:`threading`
|
||||
\* ``#include "lvgl.h"`` \* Create your frame buffer(s) as global variables:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* Frame buffers
|
||||
* Static or global buffer(s). The second buffer is optional */
|
||||
#define BYTES_PER_PIXEL (LV_COLOR_FORMAT_GET_SIZE(LV_COLOR_FORMAT_RGB565)) /* will be 2 for RGB565 */
|
||||
/* TODO: Declare your own BUFF_SIZE appropriate to your system. */
|
||||
static lv_color_t buf_1[BUFF_SIZE];
|
||||
#define BUFF_SIZE (DISPLAY_WIDTH * 10 * BYTES_PER_PIXEL)
|
||||
static uint8_t buf_1[BUFF_SIZE];
|
||||
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`,
|
||||
create a new display driver using :cpp:func:`lv_display_create`, and
|
||||
register the frame buffers using :cpp:func:`lv_display_set_buffers`.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* Initialise LVGL UI library */
|
||||
lv_init();
|
||||
lv_display_t *display = lv_display_create(WIDTH, HEIGHT); /* Create the display */
|
||||
lv_display_set_flush_cb(display, my_flush_cb); /* Set a flush callback to draw to the display */
|
||||
lv_display_set_buffers(disp, buf_1, buf_2, sizeof(buf_1), LV_DISPLAY_RENDER_MODE_PARTIAL); /* Set an initialized buffer */
|
||||
|
||||
/* Register the touch controller with LVGL - Not included here for brevity. */
|
||||
|
||||
|
||||
- Create some dummy Widgets to test the output:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* Change 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-block:: c
|
||||
|
||||
//Thread Handles
|
||||
osThreadId lvgl_tickHandle;
|
||||
osThreadId lvgl_timerHandle;
|
||||
|
||||
/* definition and creation of lvgl_tick */
|
||||
osThreadDef(lvgl_tick, LVGLTick, 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-block:: 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-block:: c
|
||||
|
||||
void my_flush_cb(lv_display_t * display, const lv_area_t * area, uint8_t * px_map);
|
||||
{
|
||||
uint16_t * color_p = (uint16_t *)px_map;
|
||||
|
||||
//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);
|
||||
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_display_flush_ready(display);
|
||||
}
|
||||
|
||||
.. _dma2d:
|
||||
|
||||
DMA2D Support
|
||||
-------------
|
||||
|
||||
LVGL supports DMA2D - a feature of some STM32 MCUs which can improve performance
|
||||
when blending fills and images. Some STM32 product lines such as STM32F4 STM32F7, STM32L4,
|
||||
STM32U5, and STM32H7 include models with DMA2D support.
|
||||
|
||||
LVGL's integration with DMA2D can be enabled by setting ``LV_USE_DRAW_DMA2D``
|
||||
to ``1`` in ``lv_conf.h``
|
||||
|
||||
With ``LV_USE_DRAW_DMA2D_INTERRUPT`` set to ``0`` and ``LV_USE_OS`` set to ``LV_OS_NONE``,
|
||||
DMA2D will draw some fills and images concurrently with the software render where
|
||||
possible. If ``LV_USE_DRAW_DMA2D_INTERRUPT`` is set to ``1`` and ``LV_USE_OS`` set to
|
||||
``LV_OS_FREERTOS`` (or another OS) the main difference will be that the core will idle
|
||||
instead of "busywait" while waiting for a DMA2D transfer to complete.
|
||||
|
||||
If ``LV_USE_DRAW_DMA2D_INTERRUPT`` is enabled then you are required to call
|
||||
:cpp:expr:`lv_draw_dma2d_transfer_complete_interrupt_handler` whenever the DMA2D
|
||||
"transfer complete" global interrupt is received.
|
||||
|
||||
If your STM device has a Nema GPU, you can use the :ref:`Nema GFX renderer <stm32_nema_gfx>` instead.
|
||||
127
docs/details/integration/driver/X11.rst
Normal file
127
docs/details/integration/driver/X11.rst
Normal file
@@ -0,0 +1,127 @@
|
||||
=========================
|
||||
X11 Display/Inputs driver
|
||||
=========================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
| The **X11** display/input `driver <https://github.com/lvgl/lvgl/src/drivers/x11>`__ offers support for simulating the LVGL display and keyboard/mouse inputs in an X11 desktop window.
|
||||
| It is an alternative to **Wayland**, **XCB**, **SDL** or **Qt**.
|
||||
|
||||
The main purpose for this driver is for testing/debugging the LVGL application in a **Linux** simulation window.
|
||||
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
The X11 driver uses XLib to access the linux window manager.
|
||||
|
||||
1. Install XLib: ``sudo apt-get install libx11-6`` (should be installed already)
|
||||
2. Install XLib development package: ``sudo apt-get install libx11-dev``
|
||||
|
||||
|
||||
Configure X11 driver
|
||||
--------------------
|
||||
|
||||
1. Enable the X11 driver support in lv_conf.h, by cmake compiler define or by KConfig
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_USE_X11 1
|
||||
|
||||
2. Optional configuration options:
|
||||
- Direct Exit
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_X11_DIRECT_EXIT 1 /* preferred default - ends the application automatically if last window has been closed */
|
||||
// or
|
||||
#define LV_X11_DIRECT_EXIT 0 /* application is responsible for ending the application (e.g. by own LV_EVENT_DELETE handler */
|
||||
|
||||
|
||||
- Double buffering
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_X11_DOUBLE_BUFFER 1 /* preferred default */
|
||||
// or
|
||||
#define LV_X11_DOUBLE_BUFFER 0 /* not recommended */
|
||||
|
||||
- Render mode
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_X11_RENDER_MODE_PARTIAL 1 /* LV_DISPLAY_RENDER_MODE_PARTIAL, preferred default */
|
||||
// or
|
||||
#define LV_X11_RENDER_MODE_DIRECT 1 /* LV_DISPLAY_RENDER_MODE_DIRECT, not recommended for X11 driver */
|
||||
// or
|
||||
#define LV_X11_RENDER_MODE_DULL 1 /* LV_DISPLAY_RENDER_MODE_FULL, not recommended for X11 driver */
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
| The minimal initialisation opening a window and enabling keyboard/mouse support
|
||||
| (e.g. in main.c, LV_X11_DIRECT_EXIT must be 1):
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
int main(int argc, char ** argv)
|
||||
{
|
||||
...
|
||||
|
||||
/* initialize X11 display driver */
|
||||
lv_display_t * disp = lv_x11_window_create("LVGL X11 Simulation", monitor_hor_res, monitor_ver_res);
|
||||
|
||||
/* initialize X11 input drivers (for keyboard, mouse & mousewheel) */
|
||||
lv_x11_inputs_create(disp, NULL);
|
||||
|
||||
...
|
||||
|
||||
while(true)
|
||||
{
|
||||
...
|
||||
|
||||
/* Periodically call the lv_timer handler */
|
||||
lv_timer_handler();
|
||||
}
|
||||
}
|
||||
|
||||
| Full initialisation with mouse pointer symbol and own application exit handling
|
||||
| (dependent on LV_X11_DIRECT_EXIT (can be 1 or 0))
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
bool terminated = false;
|
||||
|
||||
#if !LV_X11_DIRECT_EXIT
|
||||
static void on_close_cb(lv_event_t * e)
|
||||
{
|
||||
...
|
||||
|
||||
terminate = true;
|
||||
}
|
||||
#endif
|
||||
|
||||
int main(int argc, char ** argv)
|
||||
{
|
||||
...
|
||||
|
||||
/* initialize X11 display driver */
|
||||
lv_display_t * disp = lv_x11_window_create("LVGL X11 Simulation", monitor_hor_res, monitor_ver_res);
|
||||
lv_display_add_event_cb(disp, on_close_cb, LV_EVENT_DELETE, disp);
|
||||
|
||||
/* initialize X11 input drivers (for keyboard, mouse & mousewheel) */
|
||||
LV_IMAGE_DECLARE(my_mouse_cursor_icon);
|
||||
lv_x11_inputs_create(disp, &my_mouse_cursor_icon);
|
||||
|
||||
#if !LV_X11_DIRECT_EXIT
|
||||
/* set optional window close callback to enable application cleanup and exit */
|
||||
lv_x11_window_set_close_cb(disp, on_close_cb, disp);
|
||||
#endif
|
||||
|
||||
...
|
||||
|
||||
while(!terminated)
|
||||
{
|
||||
...
|
||||
|
||||
/* Periodically call the lv_timer handler */
|
||||
lv_timer_handler();
|
||||
}
|
||||
}
|
||||
41
docs/details/integration/driver/display/fbdev.rst
Normal file
41
docs/details/integration/driver/display/fbdev.rst
Normal file
@@ -0,0 +1,41 @@
|
||||
========================
|
||||
Linux Framebuffer Driver
|
||||
========================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The Linux framebuffer (fbdev) is a linux subsystem used to display graphics. It is a hardware-independent API that gives user space software
|
||||
access to the framebuffer (the part of a computer's video memory containing a current video frame) using only the Linux kernel's own basic
|
||||
facilities and its device file system interface, avoiding the need for libraries that implement video drivers in user space.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
Your system has a framebuffer device configured (usually under ``/dev/fb0``).
|
||||
|
||||
Configuring the driver
|
||||
----------------------
|
||||
|
||||
Enable the framebuffer driver support in lv_conf.h, by cmake compiler define or by KConfig. Additionally you may configure the rendering
|
||||
mode.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_USE_LINUX_FBDEV 1
|
||||
#define LV_LINUX_FBDEV_RENDER_MODE LV_DISPLAY_RENDER_MODE_PARTIAL
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
To set up a framebuffer-based display, first create a display with ``lv_linux_fbdev_create``. Afterwards set the framebuffer device
|
||||
node on the display (usually this is ``/dev/fb0``).
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
lv_display_t *disp = lv_linux_fbdev_create();
|
||||
lv_linux_fbdev_set_file(disp, "/dev/fb0");
|
||||
|
||||
If your screen stays black or only draws partially, you can try enabling direct rendering via ``LV_DISPLAY_RENDER_MODE_DIRECT``. Additionally,
|
||||
you can activate a force refresh mode with ``lv_linux_fbdev_set_force_refresh(true)``. This usually has a performance impact though and shouldn't
|
||||
be enabled unless really needed.
|
||||
210
docs/details/integration/driver/display/gen_mipi.rst
Normal file
210
docs/details/integration/driver/display/gen_mipi.rst
Normal file
@@ -0,0 +1,210 @@
|
||||
=================================================
|
||||
Generic MIPI DCS compatible LCD Controller driver
|
||||
=================================================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
From the `Wikipedia <https://en.wikipedia.org/wiki/MIPI_Alliance>`__:
|
||||
|
||||
`MIPI Alliance <https://www.mipi.org/>`__ is a global business alliance that develops technical specifications
|
||||
for the mobile ecosystem, particularly smart phones but including mobile-influenced industries. MIPI was founded in 2003 by Arm, Intel, Nokia, Samsung,
|
||||
STMicroelectronics and Texas Instruments.
|
||||
|
||||
MIPI Alliance published a series of specifications related to display devices, including DBI (Display Bus Interface), DSI (Display Serial Interface) and DCS
|
||||
(Display Command Set). Usually when one talks about a MIPI-compatible display, one thinks of a device with a DSI serial interface. However, the Display Bus Interface specification
|
||||
includes a number of other, legacy interfaces, like SPI serial, or i8080-compatible parallel interface, which are often used to interface LCD displays to lower-end microcontrollers.
|
||||
Furthermore, the DCS specification contains a standard command set, which is supported by a large number of legacy TFT LCD controllers, including the popular Sitronix
|
||||
(ST7735, ST7789, ST7796) and Ilitek (ILI9341) SOCs. These commands provide a common interface to configure display orientation, color resolution, various power modes, and provide generic video memory access. On top
|
||||
of that standard command set each LCD controller chip has a number of vendor-specific commands to configure voltage generator levels, timings, or gamma curves.
|
||||
|
||||
.. note::
|
||||
|
||||
It is important to understand that this generic MIPI LCD driver is not a hardware driver for displays with the DSI ("MIPI") serial interface. Instead, it implements the MIPI DCS command set used in many LCD controllers with an SPI or i8080 bus, and provides a common framework for chip-specific display controllers.
|
||||
|
||||
.. tip::
|
||||
Although this is a generic driver, it can be used to support compatible chips which do not have a specific driver.
|
||||
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
There are no prerequisites.
|
||||
|
||||
Configuring the driver
|
||||
----------------------
|
||||
|
||||
Enable the generic MIPI LCD driver support in lv_conf.h, by cmake compiler define or by KConfig
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_USE_GENERIC_MIPI 1
|
||||
|
||||
.. note::
|
||||
:c:macro:`LV_USE_GENERIC_MIPI` is automatically enabled when a compatible driver is enabled.
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
You need to implement two platform-dependent functions:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* Send short command to the LCD. This function shall wait until the transaction finishes. */
|
||||
int32_t my_lcd_send_cmd(lv_display_t *disp, const uint8_t *cmd, size_t cmd_size, const uint8_t *param, size_t param_size)
|
||||
{
|
||||
...
|
||||
}
|
||||
|
||||
/* Send large array of pixel data to the LCD. If necessary, this function has to do the byte-swapping. This function can do the transfer in the background. */
|
||||
int32_t my_lcd_send_color(lv_display_t *disp, const uint8_t *cmd, size_t cmd_size, uint8_t *param, size_t param_size)
|
||||
{
|
||||
...
|
||||
}
|
||||
|
||||
The only difference between the :cpp:func:`my_lcd_send_cmd()` and :cpp:func:`my_lcd_send_color()` functions is that :cpp:func:`my_lcd_send_cmd()` is used to send short commands and it is expected
|
||||
complete the transaction when it returns (in other words, it should be blocking), while :cpp:func:`my_lcd_send_color()` is only used to send pixel data, and it is recommended to use
|
||||
DMA to transmit data in the background. More sophisticated methods can be also implemented, like queuing transfers and scheduling them in the background.
|
||||
|
||||
Please note that while display flushing is handled by the driver, it is the user's responsibility to call :cpp:func:`lv_display_flush_ready()`
|
||||
when the color transfer completes. In case of a DMA transfer this is usually done in a transfer ready callback.
|
||||
|
||||
.. note::
|
||||
While it is acceptable to use a blocking implementation for the pixel transfer as well, performance will suffer.
|
||||
|
||||
.. tip::
|
||||
Care must be taken to avoid sending a command while there is an active transfer going on in the background. It is the user's responsibility to implement this either
|
||||
by polling the hardware, polling a global variable (which is reset at the end of the transfer), or by using a semaphore or other locking mechanism.
|
||||
|
||||
Please also note that the driver does not handle the draw buffer allocation, because this may be platform-dependent, too. Thus you need to allocate the buffers and assign them
|
||||
to the display object as usual by calling :cpp:func:`lv_display_set_buffers()`.
|
||||
|
||||
The driver can be used to create multiple displays. In such a configuration the callbacks must be able to distinguish between the displays. Usually one would
|
||||
implement a separate set of callbacks for each display. Also note that the user must take care of arbitrating the bus when multiple devices are connected to it.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. note::
|
||||
You can find a step-by-step guide and the actual implementation of the callbacks on an STM32F746 using STM32CubeIDE and the ST HAL libraries here: :ref:`lcd_stm32_guide`
|
||||
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include "src/drivers/display/st7789/lv_st7789.h"
|
||||
|
||||
#define LCD_H_RES 240
|
||||
#define LCD_V_RES 320
|
||||
#define LCD_BUF_LINES 60
|
||||
|
||||
lv_display_t *my_disp;
|
||||
|
||||
...
|
||||
|
||||
/* Initialize LCD I/O bus, reset LCD */
|
||||
static int32_t my_lcd_io_init(void)
|
||||
{
|
||||
...
|
||||
return HAL_OK;
|
||||
}
|
||||
|
||||
/* Send command to the LCD controller */
|
||||
static void my_lcd_send_cmd(lv_display_t *disp, const uint8_t *cmd, size_t cmd_size, const uint8_t *param, size_t param_size)
|
||||
{
|
||||
...
|
||||
}
|
||||
|
||||
/* Send pixel data to the LCD controller */
|
||||
static void my_lcd_send_color(lv_display_t *disp, const uint8_t *cmd, size_t cmd_size, uint8_t *param, size_t param_size)
|
||||
{
|
||||
...
|
||||
}
|
||||
|
||||
int main(int argc, char ** argv)
|
||||
{
|
||||
...
|
||||
|
||||
/* Initialize LVGL */
|
||||
lv_init();
|
||||
|
||||
/* Initialize LCD bus I/O */
|
||||
if (my_lcd_io_init() != 0)
|
||||
return;
|
||||
|
||||
/* Create the LVGL display object and the LCD display driver */
|
||||
my_disp = lv_lcd_generic_mipi_create(LCD_H_RES, LCD_V_RES, LV_LCD_FLAG_NONE, my_lcd_send_cmd, my_lcd_send_color);
|
||||
|
||||
/* Set display orientation to landscape */
|
||||
lv_display_set_rotation(my_disp, LV_DISPLAY_ROTATION_90);
|
||||
|
||||
/* Configure draw buffers, etc. */
|
||||
uint8_t * buf1 = NULL;
|
||||
uint8_t * buf2 = NULL;
|
||||
|
||||
uint32_t buf_size = LCD_H_RES * LCD_BUF_LINES * lv_color_format_get_size(lv_display_get_color_format(my_disp));
|
||||
|
||||
buf1 = lv_malloc(buf_size);
|
||||
if(buf1 == NULL) {
|
||||
LV_LOG_ERROR("display draw buffer malloc failed");
|
||||
return;
|
||||
}
|
||||
/* Allocate secondary buffer if needed */
|
||||
...
|
||||
|
||||
lv_display_set_buffers(my_disp, buf1, buf2, buf_size, LV_DISPLAY_RENDER_MODE_PARTIAL);
|
||||
|
||||
ui_init(my_disp);
|
||||
|
||||
while(true) {
|
||||
...
|
||||
|
||||
/* Periodically call the lv_timer handler */
|
||||
lv_timer_handler();
|
||||
}
|
||||
}
|
||||
|
||||
Advanced topics
|
||||
---------------
|
||||
|
||||
Create flags
|
||||
^^^^^^^^^^^^
|
||||
|
||||
The third argument of the :cpp:func:`lv_lcd_generic_mipi_create()` function is a flag array. This can be used to configure the orientation and RGB ordering of the panel if the
|
||||
default settings do not work for you. In particular, the generic MIPI driver accepts the following flags:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
LV_LCD_FLAG_NONE
|
||||
LV_LCD_FLAG_MIRROR_X
|
||||
LV_LCD_FLAG_MIRROR_Y
|
||||
LV_LCD_FLAG_BGR
|
||||
|
||||
You can pass multiple flags by ORing them together, e.g., :c:macro:`LV_LCD_FLAG_MIRROR_X` ``|`` :c:macro:`LV_LCD_FLAG_BGR`.
|
||||
|
||||
Custom command lists
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
While the chip-specific drivers do their best to initialize the LCD controller correctly, it is possible, that different TFT panels need different configurations.
|
||||
In particular a correct gamma setup is crucial for good color reproduction. Unfortunately, finding a good set of parameters is not easy. Usually the manufacturer
|
||||
of the panel provides some example code with recommended register settings.
|
||||
|
||||
You can use the ``my_lcd_send_cmd()`` function to send an arbitrary command to the LCD controller. However, to make it easier to send a large number of parameters
|
||||
the generic MIPI driver supports sending a custom command list to the controller. The commands must be put into a 'uint8_t' array:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
static const uint8_t init_cmd_list[] = {
|
||||
<command 1>, <number of parameters>, <parameter 1>, ... <parameter N>,
|
||||
<command 2>, <number of parameters>, <parameter 1>, ... <parameter N>,
|
||||
...
|
||||
LV_LCD_CMD_DELAY_MS, LV_LCD_CMD_EOF /* terminate list: this is required! */
|
||||
};
|
||||
|
||||
...
|
||||
|
||||
lv_lcd_generic_mipi_send_cmd_list(my_disp, init_cmd_list);
|
||||
|
||||
You can add a delay between the commands by using the pseudo-command ``LV_LCD_CMD_DELAY_MS``, which must be followed by the delay given in 10ms units.
|
||||
To terminate the command list you must use a delay with a value of ``LV_LCD_CMD_EOF``, as shown above.
|
||||
|
||||
See an actual example of sending a command list `here <https://github.com/lvgl/lvgl/src/drivers/display/st7789/lv_st7789.c>`__.
|
||||
73
docs/details/integration/driver/display/ili9341.rst
Normal file
73
docs/details/integration/driver/display/ili9341.rst
Normal file
@@ -0,0 +1,73 @@
|
||||
=============================
|
||||
ILI9341 LCD Controller driver
|
||||
=============================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The `ILI9341 <https://www.buydisplay.com/download/ic/ILI9341.pdf>`__ is a 262,144-color single-chip SOC driver for a-TFT liquid crystal display with resolution of 240RGBx320
|
||||
dots, comprising a 720-channel source driver, a 320-channel gate driver, 172,800 bytes GRAM for graphic
|
||||
display data of 240RGBx320 dots, and power supply circuit.
|
||||
ILI9341 supports parallel 8-/9-/16-/18-bit data bus MCU interface, 6-/16-/18-bit data bus RGB interface and
|
||||
3-/4-line serial peripheral interface (SPI).
|
||||
|
||||
The ILI9341 LCD controller `driver <https://github.com/lvgl/lvgl/src/drivers/display/ili9341>`__ is a platform-agnostic driver, based on the `generic MIPI driver <https://github.com/lvgl/lvgl/doc/integration/drivers/display/gen_mipi.rst>`__.
|
||||
It implements display initialization, supports display rotation and implements the display flush callback. The user needs to implement only two platform-specific functions to send
|
||||
a command or pixel data to the controller via SPI or parallel bus. Typically these are implemented by calling the appropriate SDK library functions on the given platform.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
There are no prerequisites.
|
||||
|
||||
Configuring the driver
|
||||
----------------------
|
||||
|
||||
Enable the ILI9341 driver support in lv_conf.h, by cmake compiler define or by KConfig
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_USE_ILI9341 1
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
You need to implement two platform-dependent functions:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* Send short command to the LCD. This function shall wait until the transaction finishes. */
|
||||
int32_t my_lcd_send_cmd(lv_display_t *disp, const uint8_t *cmd, size_t cmd_size, const uint8_t *param, size_t param_size)
|
||||
{
|
||||
...
|
||||
}
|
||||
|
||||
/* Send large array of pixel data to the LCD. If necessary, this function has to do the byte-swapping. This function can do the transfer in the background. */
|
||||
int32_t my_lcd_send_color(lv_display_t *disp, const uint8_t *cmd, size_t cmd_size, uint8_t *param, size_t param_size)
|
||||
{
|
||||
...
|
||||
}
|
||||
|
||||
To create an ILI9341-based display use the function
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/**
|
||||
* Create an LCD display with ILI9341 driver
|
||||
* @param hor_res horizontal resolution
|
||||
* @param ver_res vertical resolution
|
||||
* @param flags default configuration settings (mirror, RGB ordering, etc.)
|
||||
* @param send_cmd platform-dependent function to send a command to the LCD controller (usually uses polling transfer)
|
||||
* @param send_color platform-dependent function to send pixel data to the LCD controller (usually uses DMA transfer: must implement a 'ready' callback)
|
||||
* @return pointer to the created display
|
||||
*/
|
||||
lv_display_t * lv_ili9341_create(uint32_t hor_res, uint32_t ver_res, lv_lcd_flag_t flags,
|
||||
lv_ili9341_send_cmd_cb_t send_cmd_cb, lv_ili9341_send_color_cb_t send_color_cb);
|
||||
|
||||
|
||||
For additional details and a working example see the `generic MIPI driver documentation <https://github.com/lvgl/lvgl/doc/integration/drivers/display/gen_mipi.rst>`__.
|
||||
|
||||
.. note::
|
||||
|
||||
You can find a step-by-step guide and the actual implementation of the callbacks on an STM32F746 using STM32CubeIDE and the ST HAL libraries here: :ref:`lcd_stm32_guide`
|
||||
|
||||
16
docs/details/integration/driver/display/index.rst
Normal file
16
docs/details/integration/driver/display/index.rst
Normal file
@@ -0,0 +1,16 @@
|
||||
=======
|
||||
Display
|
||||
=======
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
fbdev
|
||||
gen_mipi
|
||||
ili9341
|
||||
lcd_stm32_guide
|
||||
renesas_glcdc
|
||||
st_ltdc
|
||||
st7735
|
||||
st7789
|
||||
st7796
|
||||
320
docs/details/integration/driver/display/lcd_stm32_guide.rst
Normal file
320
docs/details/integration/driver/display/lcd_stm32_guide.rst
Normal file
@@ -0,0 +1,320 @@
|
||||
.. _lcd_stm32_guide:
|
||||
|
||||
=========================================================================
|
||||
Step-by-step Guide: How to use the LVGL v9 LCD drivers with STM32 devices
|
||||
=========================================================================
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
This guide is intended to be a step-by-step instruction of how to configure the STM32Cube HAL with the new TFT-LCD display drivers introduced in LVGL v9.0. The example code has been tested on the STM32F746-based Nucleo-F746ZG board with an ST7789-based LCD panel connected via SPI. The application itself and the hardware configuration code were generated with the STM32CubeIDE 1.14.0 tool.
|
||||
|
||||
.. tip::
|
||||
ST Micro provide their own TFT-LCD drivers in their X-CUBE-DISPLAY Software Extension Package. While these drivers can be used with LVGL as well, the LVGL LCD drivers do not depend on this package.
|
||||
|
||||
The LVGL LCD drivers are meant as an alternative, simple to use API to implement LCD support for your LVGL-based project on any platform. Moreover, even in the initial release we support more LCD controllers than X-CUBE-DISPLAY currently provides, and we plan to add support for even more LCD controllers in the future.
|
||||
|
||||
Please note however, that – unlike X-CUBE-DISPLAY – the LVGL LCD drivers do not implement the communication part, whether SPI, parallel i8080 bus or other. It is the user's responsibility to implement – and optimize – these on their chosen platform. LVGL will only provide examples for the most popular platforms.
|
||||
|
||||
By following the steps you will have a fully functional program, which can be used as the foundation of your own LVGL-based project. If you are in a hurry and not interested in the details, you can find the final project `here <https://github.com/lvgl/lv_port_lcd_stm32>`__. You will only need to configure LVGL to use the driver corresponding to your hardware (if it is other than the ST7789), and implement the function ``ui_init()`` to create your widgets.
|
||||
|
||||
.. note::
|
||||
|
||||
This example is not meant as the best possible implementation, or the recommended solution. It relies solely on the HAL drivers provided by ST Micro, which favor portability over performance. Despite of this the performance is very good, thanks to the efficient, DMA-based implementation of the drivers.
|
||||
|
||||
.. note::
|
||||
|
||||
Although the example uses FreeRTOS, this is not a strict requirement with the LVGL LCD display drivers.
|
||||
|
||||
You can find the source code snippets of this guide in the `lv_port_lcd_stm32_template.c <https://github.com/lvgl/lvgl/examples/porting/lv_port_lcd_stm32_template.c>`__ example.
|
||||
|
||||
Hardware configuration
|
||||
----------------------
|
||||
|
||||
In this example we'll use the SPI1 peripheral to connect the microcontroller to the LCD panel. Besides the hardware-controlled SPI pins SCK and MOSI we need some additional output pins for the chip select, command/data select, and LCD reset:
|
||||
|
||||
==== ============= ======= ==========
|
||||
pin configuration LCD user label
|
||||
==== ============= ======= ==========
|
||||
PA4 GPIO_Output CS LCD_CS
|
||||
PA5 SPI1_SCK SCK --
|
||||
PA7 SPI1_MOSI SDI --
|
||||
PA15 GPIO_Output RESET LCD_RESET
|
||||
PB10 GPIO_Output DC LCD_DCX
|
||||
==== ============= ======= ==========
|
||||
|
||||
Step-by-step instructions
|
||||
-------------------------
|
||||
|
||||
#. Create new project in File/New/STM32 Project.
|
||||
#. Select target processor/board.
|
||||
#. Set project name and location.
|
||||
#. Set Targeted Project Type to STM32Cube and press Finish.
|
||||
#. Say "Yes" to Initialize peripherals with their default Mode? After the project is created, the configuration file (.ioc) is opened automatically.
|
||||
#. Switch to the Pinout & Configuration tab.
|
||||
#. In the System Core category switch to RCC.
|
||||
#. Set High Speed Clock to "BYPASS Clock Source", and Low Speed Clock to "Crystal/Ceramic Resonator".
|
||||
#. In the System Core category select SYS, and set Timebase Source to other than SysTick (in our example, TIM2).
|
||||
#. Switch to the Clock Configuration tab.
|
||||
#. Set the HCLK clock frequency to the maximum value (216 MHz for the STM32F746).
|
||||
#. Switch back to the Pinout & Configuration tab, and in the Middleware and Software Packs category select FREERTOS.
|
||||
#. Select Interface: CMSIS_V1.
|
||||
#. In the Advanced Settings tab enable USE_NEWLIB_REENTRANT. We are finished here.
|
||||
#. In the Pinout view configure PA5 as SPI1_SCK, PA7 as SPI1_MOSI (right click the pin and select the function).
|
||||
#. In the Pinout & Configuration/Connectivity category select SPI1.
|
||||
#. Set Mode to Transmit Only Master, and Hardware NSS Signal to Disable.
|
||||
#. In the Configuration subwindow switch to Parameter Settings.
|
||||
#. Set Frame Format to Motorola, Data Size to 8 Bits, First Bit to MSB First.
|
||||
#. Set the Prescaler to the maximum value according to the LCD controller’s datasheet (e.g., 15 MBits/s). Set CPOL/CPHA as required (leave as default).
|
||||
#. Set NSSP Mode to Disabled and NSS Signal Type to Software.
|
||||
#. In DMA Settings add a new Request for SPI1_TX (when using SPI1).
|
||||
#. Set Priority to Medium, Data Width to Half Word.
|
||||
#. In NVIC Settings enable SPI1 global interrupt.
|
||||
#. In GPIO Settings set SPI1_SCK to Pull-down and Very High output speed and set the User Label to ``LCD_SCK``.
|
||||
#. Set SPI1_MOSI to Pull-up and Very High, and name it ``LCD_SDI``.
|
||||
#. Select System Core/GPIO category. In the Pinout view configure additional pins for chip select, reset and command/data select. Name them ``LCD_CS``, ``LCD_RESET`` and ``LCD_DCX``, respectively. Configure them as GPIO Output. (In this example we will use PA4 for ``LCD_CS``, PA15 for ``LCD_RESET`` and PB10 for ``LCD_DCX``.)
|
||||
#. Set ``LCD_CS`` to No pull-up and no pull-down, Low level and Very High speed.
|
||||
#. Set ``LCD_RESET`` to Pull-up and High level.
|
||||
#. Set ``LCD_DCX`` to No pull-up and no pull-down, High level and Very High speed.
|
||||
#. Open the Project Manager tab, and select Advanced Settings. On the right hand side there is a Register Callback window. Select SPI and set it to ENABLE.
|
||||
#. We are ready with the hardware configuration. Save the configuration and let STM32Cube generate the source.
|
||||
#. In the project tree clone the LVGL repository into the Middlewares/Third_Party folder (this tutorial uses the release/v9.0 branch of LVGL):
|
||||
|
||||
.. code-block:: dosbatch
|
||||
|
||||
git clone https://github.com/lvgl/lvgl.git -b release/v9.0
|
||||
|
||||
#. Cloning should create an 'lvgl' subfolder inside the 'Third_Party' folder. From the 'lvgl' folder copy 'lv_conf_template.h' into the 'Middlewares' folder, and rename it to 'lv_conf.h'. Refresh the project tree.
|
||||
#. Open 'lv_conf.h', and in line 15 change ``#if 0`` to ``#if 1``.
|
||||
#. Search for the string ``LV_USE_ST7735``, and enable the appropriate LCD driver by setting its value to 1. This example uses the ST7789 driver:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_USE_ST7789 1
|
||||
|
||||
#. Right click the folder 'Middlewares/Third_Party/lvgl/tests', select Resource Configurations/Exclude from Build..., check both Debug and Release, then press OK.
|
||||
#. Right click the project name and select "Properties". In the C/C++ Build/Settings panel select MCU GCC Compiler/Include paths. In the Configuration dropdown select [ All configurations ]. Add the following Include path:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
../Middlewares/Third_Party/lvgl
|
||||
|
||||
#. Open Core/Src/stm32xxx_it.c (the file name depends on the processor variation). Add 'lv_tick.h' to the Private includes section:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* Private includes ----------------------------------------------------------*/
|
||||
/* USER CODE BEGIN Includes */
|
||||
#include "./src/tick/lv_tick.h"
|
||||
/* USER CODE END Includes */
|
||||
|
||||
#. Find the function ``TIM2_IRQHandler``. Add a call to ``lv_tick_inc()``:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
void TIM2_IRQHandler(void)
|
||||
{
|
||||
/* USER CODE BEGIN TIM2_IRQn 0 */
|
||||
|
||||
/* USER CODE END TIM2_IRQn 0 */
|
||||
HAL_TIM_IRQHandler(&htim2);
|
||||
/* USER CODE BEGIN TIM2_IRQn 1 */
|
||||
lv_tick_inc(1);
|
||||
/* USER CODE END TIM2_IRQn 1 */
|
||||
}
|
||||
|
||||
|
||||
#. Save the file, then open Core/Src/main.c. Add the following lines to the Private includes (if your LCD uses other than the ST7789, replace the driver path and header with the appropriate one):
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* Private includes ----------------------------------------------------------*/
|
||||
/* USER CODE BEGIN Includes */
|
||||
#include "lvgl.h"
|
||||
#include "./src/drivers/display/st7789/lv_st7789.h"
|
||||
/* USER CODE END Includes */
|
||||
|
||||
#. Add the following lines to Private defines (change them according to your LCD specs):
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LCD_H_RES 240
|
||||
#define LCD_V_RES 320
|
||||
#define BUS_SPI1_POLL_TIMEOUT 0x1000U
|
||||
|
||||
|
||||
#. Add the following lines to the Private variables:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
osThreadId LvglTaskHandle;
|
||||
lv_display_t *lcd_disp;
|
||||
volatile int lcd_bus_busy = 0;
|
||||
|
||||
#. Add the following line to the Private function prototypes:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
void ui_init(lv_display_t *disp);
|
||||
void LVGL_Task(void const *argument);
|
||||
|
||||
#. Add the following lines after USER CODE BEGIN RTOS_THREADS:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
osThreadDef(LvglTask, LVGL_Task, osPriorityIdle, 0, 1024);
|
||||
LvglTaskHandle = osThreadCreate(osThread(LvglTask), NULL);
|
||||
|
||||
#. Copy and paste the hardware initialization and the transfer callback functions from the example code after USER CODE BEGIN 4:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* USER CODE BEGIN 4 */
|
||||
|
||||
void lcd_color_transfer_ready_cb(SPI_HandleTypeDef *hspi)
|
||||
{
|
||||
/* CS high */
|
||||
HAL_GPIO_WritePin(LCD_CS_GPIO_Port, LCD_CS_Pin, GPIO_PIN_SET);
|
||||
lcd_bus_busy = 0;
|
||||
lv_display_flush_ready(lcd_disp);
|
||||
}
|
||||
|
||||
/* Initialize LCD I/O bus, reset LCD */
|
||||
static int32_t lcd_io_init(void)
|
||||
{
|
||||
/* Register SPI Tx Complete Callback */
|
||||
HAL_SPI_RegisterCallback(&hspi1, HAL_SPI_TX_COMPLETE_CB_ID, lcd_color_transfer_ready_cb);
|
||||
|
||||
/* reset LCD */
|
||||
HAL_GPIO_WritePin(LCD_RESET_GPIO_Port, LCD_RESET_Pin, GPIO_PIN_RESET);
|
||||
HAL_Delay(100);
|
||||
HAL_GPIO_WritePin(LCD_RESET_GPIO_Port, LCD_RESET_Pin, GPIO_PIN_SET);
|
||||
HAL_Delay(100);
|
||||
|
||||
HAL_GPIO_WritePin(LCD_CS_GPIO_Port, LCD_CS_Pin, GPIO_PIN_SET);
|
||||
HAL_GPIO_WritePin(LCD_DCX_GPIO_Port, LCD_DCX_Pin, GPIO_PIN_SET);
|
||||
|
||||
return HAL_OK;
|
||||
}
|
||||
|
||||
/* Platform-specific implementation of the LCD send command function. In general this should use polling transfer. */
|
||||
static void lcd_send_cmd(lv_display_t *disp, const uint8_t *cmd, size_t cmd_size, const uint8_t *param, size_t param_size)
|
||||
{
|
||||
LV_UNUSED(disp);
|
||||
while (lcd_bus_busy); /* wait until previous transfer is finished */
|
||||
/* Set the SPI in 8-bit mode */
|
||||
hspi1.Init.DataSize = SPI_DATASIZE_8BIT;
|
||||
HAL_SPI_Init(&hspi1);
|
||||
/* DCX low (command) */
|
||||
HAL_GPIO_WritePin(LCD_DCX_GPIO_Port, LCD_DCX_Pin, GPIO_PIN_RESET);
|
||||
/* CS low */
|
||||
HAL_GPIO_WritePin(LCD_CS_GPIO_Port, LCD_CS_Pin, GPIO_PIN_RESET);
|
||||
/* send command */
|
||||
if (HAL_SPI_Transmit(&hspi1, cmd, cmd_size, BUS_SPI1_POLL_TIMEOUT) == HAL_OK) {
|
||||
/* DCX high (data) */
|
||||
HAL_GPIO_WritePin(LCD_DCX_GPIO_Port, LCD_DCX_Pin, GPIO_PIN_SET);
|
||||
/* for short data blocks we use polling transfer */
|
||||
HAL_SPI_Transmit(&hspi1, (uint8_t *)param, (uint16_t)param_size, BUS_SPI1_POLL_TIMEOUT);
|
||||
/* CS high */
|
||||
HAL_GPIO_WritePin(LCD_CS_GPIO_Port, LCD_CS_Pin, GPIO_PIN_SET);
|
||||
}
|
||||
}
|
||||
|
||||
/* Platform-specific implementation of the LCD send color function. For better performance this should use DMA transfer.
|
||||
* In case of a DMA transfer a callback must be installed to notify LVGL about the end of the transfer.
|
||||
*/
|
||||
static void lcd_send_color(lv_display_t *disp, const uint8_t *cmd, size_t cmd_size, uint8_t *param, size_t param_size)
|
||||
{
|
||||
LV_UNUSED(disp);
|
||||
while (lcd_bus_busy); /* wait until previous transfer is finished */
|
||||
/* Set the SPI in 8-bit mode */
|
||||
hspi1.Init.DataSize = SPI_DATASIZE_8BIT;
|
||||
HAL_SPI_Init(&hspi1);
|
||||
/* DCX low (command) */
|
||||
HAL_GPIO_WritePin(LCD_DCX_GPIO_Port, LCD_DCX_Pin, GPIO_PIN_RESET);
|
||||
/* CS low */
|
||||
HAL_GPIO_WritePin(LCD_CS_GPIO_Port, LCD_CS_Pin, GPIO_PIN_RESET);
|
||||
/* send command */
|
||||
if (HAL_SPI_Transmit(&hspi1, cmd, cmd_size, BUS_SPI1_POLL_TIMEOUT) == HAL_OK) {
|
||||
/* DCX high (data) */
|
||||
HAL_GPIO_WritePin(LCD_DCX_GPIO_Port, LCD_DCX_Pin, GPIO_PIN_SET);
|
||||
/* for color data use DMA transfer */
|
||||
/* Set the SPI in 16-bit mode to match endianness */
|
||||
hspi1.Init.DataSize = SPI_DATASIZE_16BIT;
|
||||
HAL_SPI_Init(&hspi1);
|
||||
lcd_bus_busy = 1;
|
||||
HAL_SPI_Transmit_DMA(&hspi1, param, (uint16_t)param_size / 2);
|
||||
/* NOTE: CS will be reset in the transfer ready callback */
|
||||
}
|
||||
}
|
||||
|
||||
#. Add the LVGL_Task() function. Replace the ``lv_st7789_create()`` call with the appropriate driver. You can change the default orientation by adjusting the parameter of ``lv_display_set_rotation()``. You will also need to create the display buffers here. This example uses a double buffering scheme with 1/10th size partial buffers. In most cases this is a good compromise between the required memory size and performance, but you are free to experiment with other settings.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
void LVGL_Task(void const *argument)
|
||||
{
|
||||
/* Initialize LVGL */
|
||||
lv_init();
|
||||
|
||||
/* Initialize LCD I/O */
|
||||
if (lcd_io_init() != 0)
|
||||
return;
|
||||
|
||||
/* Create the LVGL display object and the LCD display driver */
|
||||
lcd_disp = lv_st7789_create(LCD_H_RES, LCD_V_RES, LV_LCD_FLAG_NONE, lcd_send_cmd, lcd_send_color);
|
||||
lv_display_set_rotation(lcd_disp, LV_DISPLAY_ROTATION_270);
|
||||
|
||||
/* Allocate draw buffers on the heap. In this example we use two partial buffers of 1/10th size of the screen */
|
||||
lv_color_t * buf1 = NULL;
|
||||
lv_color_t * buf2 = NULL;
|
||||
|
||||
uint32_t buf_size = LCD_H_RES * LCD_V_RES / 10 * lv_color_format_get_size(lv_display_get_color_format(lcd_disp));
|
||||
|
||||
buf1 = lv_malloc(buf_size);
|
||||
if(buf1 == NULL) {
|
||||
LV_LOG_ERROR("display draw buffer malloc failed");
|
||||
return;
|
||||
}
|
||||
|
||||
buf2 = lv_malloc(buf_size);
|
||||
if(buf2 == NULL) {
|
||||
LV_LOG_ERROR("display buffer malloc failed");
|
||||
lv_free(buf1);
|
||||
return;
|
||||
}
|
||||
lv_display_set_buffers(lcd_disp, buf1, buf2, buf_size, LV_DISPLAY_RENDER_MODE_PARTIAL);
|
||||
|
||||
ui_init(lcd_disp);
|
||||
|
||||
for(;;) {
|
||||
/* The task running lv_timer_handler should have lower priority than that running `lv_tick_inc` */
|
||||
lv_timer_handler();
|
||||
/* raise the task priority of LVGL and/or reduce the handler period can improve the performance */
|
||||
osDelay(10);
|
||||
}
|
||||
}
|
||||
|
||||
#. All that's left is to implement ``ui_init()`` to create the screen. Here's a simple "Hello World" example:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
void ui_init(lv_display_t *disp)
|
||||
{
|
||||
lv_obj_t *obj;
|
||||
|
||||
/* set screen background to white */
|
||||
lv_obj_t *scr = lv_screen_active();
|
||||
lv_obj_set_style_bg_color(scr, lv_color_white(), 0);
|
||||
lv_obj_set_style_bg_opa(scr, LV_OPA_100, 0);
|
||||
|
||||
/* create label */
|
||||
obj = lv_label_create(scr);
|
||||
lv_obj_set_align(widget, LV_ALIGN_CENTER);
|
||||
lv_obj_set_height(widget, LV_SIZE_CONTENT);
|
||||
lv_obj_set_width(widget, LV_SIZE_CONTENT);
|
||||
lv_obj_set_style_text_font(widget, &lv_font_montserrat_14, 0);
|
||||
lv_obj_set_style_text_color(widget, lv_color_black(), 0);
|
||||
lv_label_set_text(widget, "Hello World!");
|
||||
}
|
||||
|
||||
85
docs/details/integration/driver/display/renesas_glcdc.rst
Normal file
85
docs/details/integration/driver/display/renesas_glcdc.rst
Normal file
@@ -0,0 +1,85 @@
|
||||
.. _renesas_glcdc:
|
||||
|
||||
=============
|
||||
Renesas GLCDC
|
||||
=============
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
.. image:: /misc/renesas/glcdc.png
|
||||
:alt: Architectural overview of Renesas GLCDC
|
||||
:align: center
|
||||
|
||||
<br/>
|
||||
|
||||
GLCDC is a multi-stage graphics output peripheral used in Renesas MCUs.
|
||||
It is designed to automatically generate timing and data signals for different LCD panels.
|
||||
|
||||
- Supports LCD panels with RGB interface (up to 24 bits) and sync signals (HSYNC, VSYNC and Data Enable optional)
|
||||
- Supports various color formats for input graphics planes (RGB888, ARGB8888, RGB565, ARGB1555, ARGB4444, CLUT8, CLUT4, CLUT1)
|
||||
- Supports the Color Look-Up Table (CLUT) usage for input graphics planes (ARGB8888) with 512 words (32 bits/word)
|
||||
- Supports various color formats for output (RGB888, RGB666, RGB565, Serial RGB888)
|
||||
- Can input two graphics planes on top of the background plane and blend them on the screen
|
||||
- Generates a dot clock to the panel. The clock source is selectable from internal or external (LCD_EXTCLK)
|
||||
- Supports brightness adjustment, contrast adjustment, and gamma correction
|
||||
- Supports GLCDC interrupts to handle frame-buffer switching or underflow detection
|
||||
|
||||
|
||||
Setting up a project and further integration with Renesas' ecosystem is described in detail on :ref:`page Renesas <renesas>`.
|
||||
Check out the following repositories for ready-to-use examples:
|
||||
|
||||
- `EK-RA8D1 <https://github.com/lvgl/lv_port_renesas_ek-ra8d1>`__
|
||||
- `EK-RA6M3G <https://github.com/lvgl/lv_port_renesas_ek-ra6m3g>`__
|
||||
- `RX72N Envision Kit <https://github.com/lvgl/lv_port_renesas_rx72n-envision-kit>`__
|
||||
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
- This diver relies on code generated by e² studio. Missing the step while setting up the project will cause a compilation error.
|
||||
- Activate the diver by setting :c:macro:`LV_USE_RENESAS_GLCDC` to ``1`` in your *"lv_conf.h"*.
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
There is no need to implement any platform-specific functions.
|
||||
|
||||
The following code demonstrates using the diver in :cpp:enumerator:`LV_DISPLAY_RENDER_MODE_DIRECT` mode.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
lv_display_t * disp = lv_renesas_glcdc_direct_create();
|
||||
lv_display_set_default(disp);
|
||||
|
||||
To use the driver in :cpp:enumerator:`LV_DISPLAY_RENDER_MODE_PARTIAL` mode, an extra buffer must be allocated,
|
||||
preferably in the fastest available memory region.
|
||||
|
||||
Buffer swapping can be activated by passing a second buffer of same size instead of the :cpp:expr:`NULL` argument.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
static lv_color_t partial_draw_buf[DISPLAY_HSIZE_INPUT0 * DISPLAY_VSIZE_INPUT0 / 10] BSP_PLACE_IN_SECTION(".sdram") BSP_ALIGN_VARIABLE(1024);
|
||||
|
||||
lv_display_t * disp = lv_renesas_glcdc_partial_create(partial_draw_buf, NULL, sizeof(partial_draw_buf));
|
||||
lv_display_set_default(disp);
|
||||
|
||||
.. note::
|
||||
|
||||
Partial mode can be activated via the macro in ``src/board_init.c`` file of the demo projects.
|
||||
|
||||
|
||||
Screen rotation
|
||||
"""""""""""""""
|
||||
|
||||
Software based screen rotation is supported in partial mode. It uses the common API, no extra configuration is required:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
lv_display_set_rotation(lv_display_get_default(), LV_DISP_ROTATION_90);
|
||||
/* OR */
|
||||
lv_display_set_rotation(lv_display_get_default(), LV_DISP_ROTATION_180);
|
||||
/* OR */
|
||||
lv_display_set_rotation(lv_display_get_default(), LV_DISP_ROTATION_270);
|
||||
|
||||
Make sure the heap is large enough, as a buffer with the same size as the partial buffer will be allocated.
|
||||
75
docs/details/integration/driver/display/st7735.rst
Normal file
75
docs/details/integration/driver/display/st7735.rst
Normal file
@@ -0,0 +1,75 @@
|
||||
============================
|
||||
ST7735 LCD Controller driver
|
||||
============================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The `ST7735S <https://www.buydisplay.com/download/ic/ST7735S.pdf>`__ is a single-chip controller/driver for 262K-color, graphic type TFT-LCD. It consists of 396
|
||||
source line and 162 gate line driving circuits. This chip is capable of connecting directly to an external
|
||||
microprocessor, and accepts Serial Peripheral Interface (SPI), 8-bit/9-bit/16-bit/18-bit parallel interface.
|
||||
Display data can be stored in the on-chip display data RAM of 132 x 162 x 18 bits. It can perform display data
|
||||
RAM read/write operation with no external operation clock to minimize power consumption. In addition,
|
||||
because of the integrated power supply circuits necessary to drive liquid crystal, it is possible to make a
|
||||
display system with fewer components.
|
||||
|
||||
The ST7735 LCD controller `driver <https://github.com/lvgl/lvgl/src/drivers/display/st7735>`__ is a platform-agnostic driver, based on the `generic MIPI driver <https://github.com/lvgl/lvgl/doc/integration/drivers/display/gen_mipi.rst>`__.
|
||||
It implements display initialization, supports display rotation and implements the display flush callback. The user needs to implement only two platform-specific functions to send
|
||||
a command or pixel data to the controller via SPI or parallel bus. Typically these are implemented by calling the appropriate SDK library functions on the given platform.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
There are no prerequisites.
|
||||
|
||||
Configuring the driver
|
||||
----------------------
|
||||
|
||||
Enable the ST7735 driver support in lv_conf.h, by cmake compiler define or by KConfig
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_USE_ST7735 1
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
You need to implement two platform-dependent functions:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* Send short command to the LCD. This function shall wait until the transaction finishes. */
|
||||
int32_t my_lcd_send_cmd(lv_display_t *disp, const uint8_t *cmd, size_t cmd_size, const uint8_t *param, size_t param_size)
|
||||
{
|
||||
...
|
||||
}
|
||||
|
||||
/* Send large array of pixel data to the LCD. If necessary, this function has to do the byte-swapping. This function can do the transfer in the background. */
|
||||
int32_t my_lcd_send_color(lv_display_t *disp, const uint8_t *cmd, size_t cmd_size, uint8_t *param, size_t param_size)
|
||||
{
|
||||
...
|
||||
}
|
||||
|
||||
To create an ST7735-based display use the function
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/**
|
||||
* Create an LCD display with ST7735 driver
|
||||
* @param hor_res horizontal resolution
|
||||
* @param ver_res vertical resolution
|
||||
* @param flags default configuration settings (mirror, RGB ordering, etc.)
|
||||
* @param send_cmd platform-dependent function to send a command to the LCD controller (usually uses polling transfer)
|
||||
* @param send_color platform-dependent function to send pixel data to the LCD controller (usually uses DMA transfer: must implement a 'ready' callback)
|
||||
* @return pointer to the created display
|
||||
*/
|
||||
lv_display_t * lv_st7735_create(uint32_t hor_res, uint32_t ver_res, lv_lcd_flag_t flags,
|
||||
lv_st7735_send_cmd_cb_t send_cmd_cb, lv_st7735_send_color_cb_t send_color_cb);
|
||||
|
||||
|
||||
For additional details and a working example see the `generic MIPI driver documentation <https://github.com/lvgl/lvgl/doc/integration/drivers/display/gen_mipi.rst>`__.
|
||||
|
||||
.. note::
|
||||
|
||||
You can find a step-by-step guide and the actual implementation of the callbacks on an STM32F746 using STM32CubeIDE and the ST HAL libraries here: :ref:`lcd_stm32_guide`
|
||||
|
||||
74
docs/details/integration/driver/display/st7789.rst
Normal file
74
docs/details/integration/driver/display/st7789.rst
Normal file
@@ -0,0 +1,74 @@
|
||||
============================
|
||||
ST7789 LCD Controller driver
|
||||
============================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The `ST7789 <https://www.buydisplay.com/download/ic/ST7789.pdf>`__ is a single-chip controller/driver for 262K-color, graphic type TFT-LCD. It consists of 720
|
||||
source line and 320 gate line driving circuits. This chip is capable of connecting directly to an external
|
||||
microprocessor, and accepts, 8-bits/9-bits/16-bits/18-bits parallel interface. Display data can be stored in the
|
||||
on-chip display data RAM of 240x320x18 bits. It can perform display data RAM read/write operation with no
|
||||
external operation clock to minimize power consumption. In addition, because of the integrated power supply
|
||||
circuit necessary to drive liquid crystal; it is possible to make a display system with the fewest components.
|
||||
|
||||
The ST7789 LCD controller `driver <https://github.com/lvgl/lvgl/src/drivers/display/st7789>`__ is a platform-agnostic driver, based on the `generic MIPI driver <https://github.com/lvgl/lvgl/doc/integration/drivers/display/gen_mipi.rst>`__.
|
||||
It implements display initialization, supports display rotation and implements the display flush callback. The user needs to implement only two platform-specific functions to send
|
||||
a command or pixel data to the controller via SPI or parallel bus. Typically these are implemented by calling the appropriate SDK library functions on the given platform.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
There are no prerequisites.
|
||||
|
||||
Configuring the driver
|
||||
----------------------
|
||||
|
||||
Enable the ST7789 driver support in lv_conf.h, by cmake compiler define or by KConfig
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_USE_ST7789 1
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
You need to implement two platform-dependent functions:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* Send short command to the LCD. This function shall wait until the transaction finishes. */
|
||||
int32_t my_lcd_send_cmd(lv_display_t *disp, const uint8_t *cmd, size_t cmd_size, const uint8_t *param, size_t param_size)
|
||||
{
|
||||
...
|
||||
}
|
||||
|
||||
/* Send large array of pixel data to the LCD. If necessary, this function has to do the byte-swapping. This function can do the transfer in the background. */
|
||||
int32_t my_lcd_send_color(lv_display_t *disp, const uint8_t *cmd, size_t cmd_size, uint8_t *param, size_t param_size)
|
||||
{
|
||||
...
|
||||
}
|
||||
|
||||
To create an ST7789-based display use the function
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/**
|
||||
* Create an LCD display with ST7789 driver
|
||||
* @param hor_res horizontal resolution
|
||||
* @param ver_res vertical resolution
|
||||
* @param flags default configuration settings (mirror, RGB ordering, etc.)
|
||||
* @param send_cmd platform-dependent function to send a command to the LCD controller (usually uses polling transfer)
|
||||
* @param send_color platform-dependent function to send pixel data to the LCD controller (usually uses DMA transfer: must implement a 'ready' callback)
|
||||
* @return pointer to the created display
|
||||
*/
|
||||
lv_display_t * lv_st7789_create(uint32_t hor_res, uint32_t ver_res, lv_lcd_flag_t flags,
|
||||
lv_st7789_send_cmd_cb_t send_cmd_cb, lv_st7789_send_color_cb_t send_color_cb);
|
||||
|
||||
|
||||
For additional details and a working example see the `generic MIPI driver documentation <https://github.com/lvgl/lvgl/doc/integration/drivers/display/gen_mipi.rst>`__.
|
||||
|
||||
.. note::
|
||||
|
||||
You can find a step-by-step guide and the actual implementation of the callbacks on an STM32F746 using STM32CubeIDE and the ST HAL libraries here: :ref:`lcd_stm32_guide`
|
||||
|
||||
75
docs/details/integration/driver/display/st7796.rst
Normal file
75
docs/details/integration/driver/display/st7796.rst
Normal file
@@ -0,0 +1,75 @@
|
||||
============================
|
||||
ST7796 LCD Controller driver
|
||||
============================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The `ST7796S <https://www.buydisplay.com/download/ic/ST7796S.pdf>`__ is a single-chip controller/driver for 262K-color, graphic type TFT-LCD. It consists of 960
|
||||
source lines and 480 gate lines driving circuits. The ST7796S is capable of connecting directly to an external
|
||||
microprocessor, and accepts 8-bit/9-bit/16-bit/18-bit parallel interface, SPI, and the ST7796S also provides
|
||||
MIPI interface. Display data can be stored in the on-chip display data RAM of 320x480x18 bits. It can perform
|
||||
display data RAM read-/write-operation with no external clock to minimize power consumption. In addition,
|
||||
because of the integrated power supply circuit necessary to drive liquid crystal; it is possible to make a display
|
||||
system with fewest components.
|
||||
|
||||
The ST7796 LCD controller `driver <https://github.com/lvgl/lvgl/src/drivers/display/st7796>`__ is a platform-agnostic driver, based on the `generic MIPI driver <https://github.com/lvgl/lvgl/doc/integration/drivers/display/gen_mipi.rst>`__.
|
||||
It implements display initialization, supports display rotation and implements the display flush callback. The user needs to implement only two platform-specific functions to send
|
||||
a command or pixel data to the controller via SPI or parallel bus. Typically these are implemented by calling the appropriate SDK library functions on the given platform.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
There are no prerequisites.
|
||||
|
||||
Configuring the driver
|
||||
----------------------
|
||||
|
||||
Enable the ST7796 driver support in lv_conf.h, by cmake compiler define or by KConfig
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_USE_ST7796 1
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
You need to implement two platform-dependent functions:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* Send short command to the LCD. This function shall wait until the transaction finishes. */
|
||||
int32_t my_lcd_send_cmd(lv_display_t *disp, const uint8_t *cmd, size_t cmd_size, const uint8_t *param, size_t param_size)
|
||||
{
|
||||
...
|
||||
}
|
||||
|
||||
/* Send large array of pixel data to the LCD. If necessary, this function has to do the byte-swapping. This function can do the transfer in the background. */
|
||||
int32_t my_lcd_send_color(lv_display_t *disp, const uint8_t *cmd, size_t cmd_size, uint8_t *param, size_t param_size)
|
||||
{
|
||||
...
|
||||
}
|
||||
|
||||
To create an ST7796-based display use the function
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/**
|
||||
* Create an LCD display with ST7796 driver
|
||||
* @param hor_res horizontal resolution
|
||||
* @param ver_res vertical resolution
|
||||
* @param flags default configuration settings (mirror, RGB ordering, etc.)
|
||||
* @param send_cmd platform-dependent function to send a command to the LCD controller (usually uses polling transfer)
|
||||
* @param send_color platform-dependent function to send pixel data to the LCD controller (usually uses DMA transfer: must implement a 'ready' callback)
|
||||
* @return pointer to the created display
|
||||
*/
|
||||
lv_display_t * lv_st7796_create(uint32_t hor_res, uint32_t ver_res, lv_lcd_flag_t flags,
|
||||
lv_st7796_send_cmd_cb_t send_cmd_cb, lv_st7796_send_color_cb_t send_color_cb);
|
||||
|
||||
|
||||
For additional details and a working example see the `generic MIPI driver documentation <https://github.com/lvgl/lvgl/doc/integration/drivers/display/gen_mipi.rst>`__.
|
||||
|
||||
.. note::
|
||||
|
||||
You can find a step-by-step guide and the actual implementation of the callbacks on an STM32F746 using STM32CubeIDE and the ST HAL libraries here: :ref:`lcd_stm32_guide`
|
||||
|
||||
102
docs/details/integration/driver/display/st_ltdc.rst
Normal file
102
docs/details/integration/driver/display/st_ltdc.rst
Normal file
@@ -0,0 +1,102 @@
|
||||
=================
|
||||
STM32 LTDC Driver
|
||||
=================
|
||||
|
||||
Some STM32s have a specialized peripheral for driving
|
||||
displays called LTDC (LCD-TFT display controller).
|
||||
|
||||
Usage Modes With LVGL
|
||||
*********************
|
||||
|
||||
The driver within LVGL is designed to work with an
|
||||
already-configured LTDC peripheral. It relies on the
|
||||
HAL to detect information about the configuration.
|
||||
The color format of the created LVGL display will
|
||||
match the LTDC layer's color format. Use STM32CubeIDE
|
||||
or STM32CubeMX to generate LTDC initialization code.
|
||||
|
||||
There are some different use cases for LVGL's driver.
|
||||
All permutations of the below options are well supported.
|
||||
|
||||
- single or double buffered
|
||||
- direct or partial render mode
|
||||
- OS and no OS
|
||||
- paralellized flushing with DMA2D (only for partial render mode)
|
||||
|
||||
If OS is enabled, a synchronization primitive will be used to
|
||||
give the thread a chance to yield to other threads while blocked,
|
||||
improving CPU utilization. See :c:macro:`LV_USE_OS` in your lv_conf.h
|
||||
|
||||
LTDC Layers
|
||||
***********
|
||||
|
||||
This driver creates an LVGL display
|
||||
which is only concerned with a specific layer of the LTDC peripheral, meaning
|
||||
two LVGL LTDC displays can be created and operate independently on the separate
|
||||
layers.
|
||||
|
||||
Direct Render Mode
|
||||
******************
|
||||
|
||||
For direct render mode, invoke :cpp:func:`lv_st_ltdc_create_direct` like this:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
void * my_ltdc_framebuffer_address = (void *)0x20000000u;
|
||||
uint32_t my_ltdc_layer_index = 0; /* typically 0 or 1 */
|
||||
lv_display_t * disp = lv_st_ltdc_create_direct(my_ltdc_framebuffer_address,
|
||||
optional_other_full_size_buffer,
|
||||
my_ltdc_layer_index);
|
||||
|
||||
``my_ltdc_framebuffer_address`` is the framebuffer configured for use by
|
||||
LTDC. ``optional_other_full_size_buffer`` can be another buffer which is the same
|
||||
size as the default framebuffer for double-buffered
|
||||
mode, or ``NULL`` otherwise. ``my_ltdc_layer_index`` is the layer index of the
|
||||
LTDC layer to create the display for.
|
||||
|
||||
For the best visial results, ``optional_other_full_size_buffer`` should be used
|
||||
if enough memory is available. Single-buffered mode is what you should use
|
||||
if memory is very scarce. If there is almost enough memory for double-buffered
|
||||
direct mode, but not quite, then use partial render mode.
|
||||
|
||||
Partial Render Mode
|
||||
*******************
|
||||
|
||||
For partial render mode, invoke :cpp:func:`lv_st_ltdc_create_partial` like this:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
static uint8_t partial_buf1[65536];
|
||||
static uint8_t optional_partial_buf2[65536];
|
||||
uint32_t my_ltdc_layer_index = 0; /* typically 0 or 1 */
|
||||
lv_display_t * disp = lv_st_ltdc_create_partial(partial_buf1,
|
||||
optional_partial_buf2,
|
||||
65536,
|
||||
my_ltdc_layer_index);
|
||||
|
||||
The driver will use the information in the LTDC layer configuration to find the
|
||||
layer's framebuffer and flush to it.
|
||||
|
||||
Providing a second partial buffer can improve CPU utilization and increase
|
||||
performance compared to
|
||||
a single buffer if :c:macro:`LV_ST_LTDC_USE_DMA2D_FLUSH` is enabled.
|
||||
|
||||
DMA2D
|
||||
*****
|
||||
|
||||
:c:macro:`LV_ST_LTDC_USE_DMA2D_FLUSH` can be enabled to use DMA2D to flush
|
||||
partial buffers in parallel with other LVGL tasks, whether or not OS is
|
||||
enabled. If the display is not partial, then there is no need to enable this
|
||||
option.
|
||||
|
||||
It must not be enabled at the same time as :c:macro:`LV_USE_DRAW_DMA2D`.
|
||||
See the :ref:`DMA2D support <dma2d>`.
|
||||
|
||||
|
||||
.. admonition:: Further Reading
|
||||
|
||||
You may be interested in enabling the :ref:`Nema GFX renderer <stm32_nema_gfx>`
|
||||
if your STM32 has a GPU which is supported by Nema GFX.
|
||||
|
||||
`lv_port_riverdi_stm32u5 <https://github.com/lvgl/lv_port_riverdi_stm32u5>`__
|
||||
is a way to quick way to get started with LTDC on LVGL.
|
||||
16
docs/details/integration/driver/index.rst
Normal file
16
docs/details/integration/driver/index.rst
Normal file
@@ -0,0 +1,16 @@
|
||||
.. _drivers:
|
||||
|
||||
=======
|
||||
Drivers
|
||||
=======
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
display/index
|
||||
libinput
|
||||
opengles
|
||||
touchpad/index
|
||||
wayland
|
||||
windows
|
||||
X11
|
||||
87
docs/details/integration/driver/libinput.rst
Normal file
87
docs/details/integration/driver/libinput.rst
Normal file
@@ -0,0 +1,87 @@
|
||||
===============
|
||||
Libinput Driver
|
||||
===============
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
Libinput is an input stack for processes that need to provide events from commonly used input devices. That includes mice, keyboards, touchpads,
|
||||
touchscreens and graphics tablets. Libinput handles device-specific quirks and provides an easy-to-use API to receive events from devices.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
You have the development version of libinput installed (usually ``libinput-dev``). If your input device requires quirks, make sure they are
|
||||
installed as well (usually in ``/usr/share/libinput/*.quirks``). To test if your device is set up correctly for use with libinput, you can
|
||||
run ``libinput list-devices``.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo libinput list-devices
|
||||
...
|
||||
Device: ETPS/2 Elantech Touchpad
|
||||
Kernel: /dev/input/event5
|
||||
Group: 10
|
||||
Seat: seat0, default
|
||||
Size: 102x74mm
|
||||
Capabilities: pointer gesture
|
||||
Tap-to-click: disabled
|
||||
Tap-and-drag: enabled
|
||||
...
|
||||
|
||||
If your device doesn't show up, you may have to configure udev and the appropriate udev rules to connect it.
|
||||
|
||||
Additionally, if you want full keyboard support, including letters and modifiers, you'll need the development version of libxkbcommon
|
||||
installed (usually ``libxkbcommon-dev``).
|
||||
|
||||
Configuring the driver
|
||||
----------------------
|
||||
|
||||
Enable the libinput driver support in lv_conf.h, by cmake compiler define or by KConfig.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_USE_LIBINPUT 1
|
||||
|
||||
Full keyboard support needs to be enabled separately.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_LIBINPUT_XKB 1
|
||||
#define LV_LIBINPUT_XKB_KEY_MAP { .rules = NULL, .model = "pc101", .layout = "us", .variant = NULL, .options = NULL }
|
||||
|
||||
To find the right key map values, you may use the ``setxkbmap -query`` command.
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
To set up an input device via the libinput driver, all you need to do is call ``lv_libinput_create`` with the respective device type
|
||||
(``LV_INDEV_TYPE_POINTER`` or ``LV_INDEV_TYPE_KEYPAD``) and device node path (e.g. ``/dev/input/event5``).
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
lv_indev_t *indev = lv_libinput_create(LV_INDEV_TYPE_POINTER, "/dev/input/event5");
|
||||
|
||||
Note that touchscreens are treated as (absolute) pointer devices by the libinput driver and require ``LV_INDEV_TYPE_POINTER``.
|
||||
|
||||
Depending on your system, the device node paths might not be stable across reboots. If this is the case, you can use ``lv_libinput_find_dev``
|
||||
to find the first device that has a specific capability.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
char *path = lv_libinput_find_dev(LV_LIBINPUT_CAPABILITY_TOUCH, true);
|
||||
|
||||
The second argument controls whether or not all devices are rescanned. If you have many devices connected this can get quite slow.
|
||||
Therefore, you should only specify ``true`` on the first call when calling this method multiple times in a row. If you want to find
|
||||
all devices that have a specific capability, use ``lv_libinput_find_devs``.
|
||||
|
||||
If you want to connect a keyboard device to a textarea, create a dedicated input group and set it on both the indev and textarea.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
lv_obj_t *textarea = lv_textarea_create(...);
|
||||
...
|
||||
lv_group_t *keyboard_input_group = lv_group_create();
|
||||
lv_indev_set_group(indev, keyboard_input_group);
|
||||
lv_group_add_obj(keyboard_input_group, textarea);
|
||||
|
||||
224
docs/details/integration/driver/opengles.rst
Normal file
224
docs/details/integration/driver/opengles.rst
Normal file
@@ -0,0 +1,224 @@
|
||||
.. _opengl_es_driver:
|
||||
|
||||
===============================
|
||||
OpenGL ES Display/Inputs Driver
|
||||
===============================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
| The **OpenGL ES** display/input `driver <https://github.com/lvgl/lvgl/src/drivers/opengles>`__ offers support for simulating the LVGL display and keyboard/mouse inputs in an desktop window created via GLFW.
|
||||
| It is an alternative to **Wayland**, **XCB**, **SDL** or **Qt**.
|
||||
|
||||
The main purpose for this driver is for testing/debugging the LVGL application in an **OpenGL** simulation window.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
The OpenGL driver uses GLEW GLFW to access the OpenGL window manager.
|
||||
|
||||
1. Install GLEW and GLFW: ``sudo apt-get install libglew-dev libglfw3-dev``
|
||||
|
||||
Configure OpenGL Driver
|
||||
-----------------------
|
||||
|
||||
1. Required linked libraries: -lGL -lGLEW -lglfw
|
||||
2. Enable the OpenGL driver support in lv_conf.h, by cmake compiler define or by KConfig
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_USE_OPENGLES 1
|
||||
|
||||
Basic Usage
|
||||
-----------
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include "lvgl/lvgl.h"
|
||||
#include "lvgl/examples/lv_examples.h"
|
||||
#include "lvgl/demos/lv_demos.h"
|
||||
|
||||
#define WIDTH 640
|
||||
#define HEIGHT 480
|
||||
|
||||
int main()
|
||||
{
|
||||
/* initialize lvgl */
|
||||
lv_init();
|
||||
|
||||
/* create a window and initialize OpenGL */
|
||||
lv_glfw_window_t * window = lv_glfw_window_create(WIDTH, HEIGHT, true);
|
||||
|
||||
/* create a display that flushes to a texture */
|
||||
lv_display_t * texture = lv_opengles_texture_create(WIDTH, HEIGHT);
|
||||
lv_display_set_default(texture);
|
||||
|
||||
/* add the texture to the window */
|
||||
unsigned int texture_id = lv_opengles_texture_get_texture_id(texture);
|
||||
lv_glfw_texture_t * window_texture = lv_glfw_window_add_texture(window, texture_id, WIDTH, HEIGHT);
|
||||
|
||||
/* get the mouse indev of the window texture */
|
||||
lv_indev_t * mouse = lv_glfw_texture_get_mouse_indev(window_texture);
|
||||
|
||||
/* add a cursor to the mouse indev */
|
||||
LV_IMAGE_DECLARE(mouse_cursor_icon);
|
||||
lv_obj_t * cursor_obj = lv_image_create(lv_screen_active());
|
||||
lv_image_set_src(cursor_obj, &mouse_cursor_icon);
|
||||
lv_indev_set_cursor(mouse, cursor_obj);
|
||||
|
||||
/* create Widgets on the screen */
|
||||
lv_demo_widgets();
|
||||
|
||||
while (1)
|
||||
{
|
||||
uint32_t time_until_next = lv_timer_handler();
|
||||
lv_delay_ms(time_until_next);
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
Advanced Usage
|
||||
--------------
|
||||
|
||||
The OpenGL driver can draw textures from the user. A third-party library could be
|
||||
used to add content to a texture and the driver will draw the texture in the window.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include "lvgl/lvgl.h"
|
||||
#include <GL/glew.h>
|
||||
#include <GLFW/glfw3.h>
|
||||
|
||||
#define WIDTH 640
|
||||
#define HEIGHT 480
|
||||
|
||||
void custom_texture_example(void)
|
||||
{
|
||||
/*****************
|
||||
* MAIN WINDOW
|
||||
*****************/
|
||||
|
||||
/* create a window and initialize OpenGL */
|
||||
/* multiple windows can be created */
|
||||
lv_glfw_window_t * window = lv_glfw_window_create(WIDTH, HEIGHT, true);
|
||||
|
||||
/****************************
|
||||
* OPTIONAL MAIN TEXTURE
|
||||
****************************/
|
||||
|
||||
/* create a main display that flushes to a texture */
|
||||
lv_display_t * main_texture = lv_opengles_texture_create(WIDTH, HEIGHT);
|
||||
lv_display_set_default(main_texture);
|
||||
|
||||
/* add the main texture to the window */
|
||||
unsigned int main_texture_id = lv_opengles_texture_get_texture_id(main_texture);
|
||||
lv_glfw_texture_t * window_main_texture = lv_glfw_window_add_texture(window, main_texture_id, WIDTH, HEIGHT);
|
||||
|
||||
/* get the mouse indev of this main texture */
|
||||
lv_indev_t * main_texture_mouse = lv_glfw_texture_get_mouse_indev(window_main_texture);
|
||||
|
||||
/* add a cursor to the mouse indev */
|
||||
LV_IMAGE_DECLARE(mouse_cursor_icon);
|
||||
lv_obj_t * cursor_obj = lv_image_create(lv_screen_active());
|
||||
lv_image_set_src(cursor_obj, &mouse_cursor_icon);
|
||||
lv_indev_set_cursor(main_texture_mouse, cursor_obj);
|
||||
|
||||
/* create Widgets on the screen of the main texture */
|
||||
lv_demo_widgets();
|
||||
|
||||
/**********************
|
||||
* ANOTHER TEXTURE
|
||||
**********************/
|
||||
|
||||
/* create a sub display that flushes to a texture */
|
||||
const int32_t sub_texture_w = 300;
|
||||
const int32_t sub_texture_h = 300;
|
||||
lv_display_t * sub_texture = lv_opengles_texture_create(sub_texture_w, sub_texture_h);
|
||||
|
||||
/* add the sub texture to the window */
|
||||
unsigned int sub_texture_id = lv_opengles_texture_get_texture_id(sub_texture);
|
||||
lv_glfw_texture_t * window_sub_texture = lv_glfw_window_add_texture(window, sub_texture_id, sub_texture_w, sub_texture_h);
|
||||
|
||||
/* create Widgets on the screen of the sub texture */
|
||||
lv_display_set_default(sub_texture);
|
||||
lv_example_keyboard_2();
|
||||
lv_display_set_default(main_texture);
|
||||
|
||||
/* position the sub texture within the window */
|
||||
lv_glfw_texture_set_x(window_sub_texture, 250);
|
||||
lv_glfw_texture_set_y(window_sub_texture, 150);
|
||||
|
||||
/* optionally change the opacity of the sub texture */
|
||||
lv_glfw_texture_set_opa(window_sub_texture, LV_OPA_80);
|
||||
|
||||
/*********************************************
|
||||
* USE AN EXTERNAL OPENGL TEXTURE IN LVGL
|
||||
*********************************************/
|
||||
|
||||
unsigned int external_texture_id;
|
||||
glGenTextures(1, &external_texture_id);
|
||||
glBindTexture(GL_TEXTURE_2D, external_texture_id);
|
||||
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
|
||||
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
|
||||
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
|
||||
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
|
||||
glPixelStorei(GL_UNPACK_ALIGNMENT, 1);
|
||||
LV_IMAGE_DECLARE(img_cogwheel_argb);
|
||||
#if LV_COLOR_DEPTH == 8
|
||||
const int texture_format = GL_R8;
|
||||
#elif LV_COLOR_DEPTH == 16
|
||||
const int texture_format = GL_RGB565;
|
||||
#elif LV_COLOR_DEPTH == 24
|
||||
const int texture_format = GL_RGB;
|
||||
#elif LV_COLOR_DEPTH == 32
|
||||
const int texture_format = GL_RGBA;
|
||||
#else
|
||||
#error("Unsupported color format")
|
||||
#endif
|
||||
glTexImage2D(GL_TEXTURE_2D, 0, texture_format, img_cogwheel_argb.header.w, img_cogwheel_argb.header.h, 0, GL_BGRA, GL_UNSIGNED_BYTE, img_cogwheel_argb.data);
|
||||
glGenerateMipmap(GL_TEXTURE_2D);
|
||||
glBindTexture(GL_TEXTURE_2D, 0);
|
||||
|
||||
/* add the external texture to the window */
|
||||
lv_glfw_texture_t * window_external_texture = lv_glfw_window_add_texture(window, external_texture_id, img_cogwheel_argb.header.w, img_cogwheel_argb.header.h);
|
||||
|
||||
/* set the position and opacity of the external texture within the window */
|
||||
lv_glfw_texture_set_x(window_external_texture, 20);
|
||||
lv_glfw_texture_set_y(window_external_texture, 20);
|
||||
lv_glfw_texture_set_opa(window_external_texture, LV_OPA_70);
|
||||
|
||||
/*********************************************
|
||||
* USE AN LVGL TEXTURE IN ANOTHER LIBRARY
|
||||
*********************************************/
|
||||
|
||||
lv_refr_now(sub_texture);
|
||||
|
||||
/* the texture is drawn on by LVGL and can be used by anything that uses OpenGL textures */
|
||||
third_party_lib_use_texture(sub_texture_id);
|
||||
}
|
||||
|
||||
OpenGL Texture Caching Renderer
|
||||
-------------------------------
|
||||
|
||||
There is a renderer in LVGL which caches software-rendered areas as OpenGL textures.
|
||||
The textures are retrieved from the cache and reused when there is a match.
|
||||
The performance will be drastically improved in most cases.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_USE_DRAW_OPENGLES 1
|
||||
|
||||
Known Limitations
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
- Performance will be the same or slightly worse if the drawn areas are never found in the cache
|
||||
due to Widgets with continuously varying colors or shapes. One example is a label whose color
|
||||
is set to a random value every frame, as in the "Multiple labels" scene of the benchmark demo.
|
||||
- Layers with transparent pixels and an overall layer transparency will not blend correctly.
|
||||
The effect can be observed in the "Containers with opa_layer" scene of the benchmark demo
|
||||
in the border corners.
|
||||
- Layers with rotation are not currently supported. Images with rotation are fine.
|
||||
|
||||
|
||||
.. Comment: The above blank line is necessary for Sphinx to not complain,
|
||||
since it looks for the blank line after a bullet list.
|
||||
57
docs/details/integration/driver/touchpad/evdev.rst
Normal file
57
docs/details/integration/driver/touchpad/evdev.rst
Normal file
@@ -0,0 +1,57 @@
|
||||
==================
|
||||
Linux Evdev Driver
|
||||
==================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The Linux event device (evdev) is a hardware-independent API that gives access to input events from,
|
||||
for example, a mouse or touchscreen. It is exposed via the Linux device file system interface.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
Your system has an input device configured (usually under ``/dev/input/`` such as ``/dev/input/event0``).
|
||||
|
||||
Configuring the driver
|
||||
----------------------
|
||||
|
||||
Enable the Linux LVGL evdev driver support in ``lv_conf.h``.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_USE_EVDEV 1
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
To set up an event input, first create an input device with ``lv_edev_create`` setting it to the correct Linux event device.
|
||||
Then link this to the LVGL display with ``lv_indev_set_display``.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
lv_indev_t *touch = lv_evdev_create(LV_INDEV_TYPE_POINTER, "/dev/input/event0");
|
||||
lv_indev_set_display(touch, disp);
|
||||
|
||||
Ensure that an ``lv_display_t`` object is already created for ``disp``. An example for this is shown below, using the Linux framebuffer driver.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
lv_display_t * disp = lv_linux_fbdev
|
||||
lv_linux_fbdev_set_file(disp, "/dev/fb0");_create();
|
||||
|
||||
|
||||
Locating your input device
|
||||
--------------------------
|
||||
|
||||
If you can't determine your input device, first run
|
||||
|
||||
```$cat /proc/bus/input/devices```
|
||||
|
||||
This should show input devices and there will be entries with the word ``event`` which give a clue as to the device to use eg. ``event1`` would be ``/dev/input/event1``.
|
||||
|
||||
You can use ``evtest`` to show data from that event source to see if it is actually the one you want.
|
||||
|
||||
Try:
|
||||
|
||||
``$evtest /dev/input/event1`` replacing ``eventX`` with your event device from above.
|
||||
5
docs/details/integration/driver/touchpad/ft6x36.rst
Normal file
5
docs/details/integration/driver/touchpad/ft6x36.rst
Normal file
@@ -0,0 +1,5 @@
|
||||
======
|
||||
FT6X36
|
||||
======
|
||||
|
||||
TODO
|
||||
9
docs/details/integration/driver/touchpad/index.rst
Normal file
9
docs/details/integration/driver/touchpad/index.rst
Normal file
@@ -0,0 +1,9 @@
|
||||
========
|
||||
Touchpad
|
||||
========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
evdev
|
||||
ft6x36
|
||||
182
docs/details/integration/driver/wayland.rst
Normal file
182
docs/details/integration/driver/wayland.rst
Normal file
@@ -0,0 +1,182 @@
|
||||
.. _wayland_driver:
|
||||
|
||||
=============================
|
||||
Wayland Display/Inputs driver
|
||||
=============================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
| The **Wayland** `driver <https://github.com/lvgl/lvgl/tree/master/src/drivers/wayland>`__ offers support for simulating the LVGL display and keyboard/mouse inputs in a desktop window.
|
||||
| It is an alternative to **X11** or **SDL2**
|
||||
|
||||
The main purpose for this driver is for testing/debugging the LVGL application, it can also be used to run applications in 'kiosk mode'
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
The wayland driver requires some dependencies.
|
||||
|
||||
On Ubuntu
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo apt-get install libwayland-dev libxkbcommon-dev libwayland-bin wayland-protocols
|
||||
|
||||
On Fedora
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo dnf install wayland-devel libxkbcommon-devel wayland-utils wayland-protocols-devel
|
||||
|
||||
|
||||
Configuring the wayland driver
|
||||
------------------------------
|
||||
|
||||
1. Enable the wayland driver in ``lv_conf.h``
|
||||
|
||||
.. code:: c
|
||||
|
||||
#define LV_USE_WAYLAND 1
|
||||
|
||||
2. Optional configuration options:
|
||||
|
||||
- Enable window decorations, only required on GNOME because out of all the available wayland compositors
|
||||
**only** Mutter/GNOME enforces the use of client side decorations
|
||||
|
||||
.. code:: c
|
||||
|
||||
#define LV_WAYLAND_WINDOW_DECORATIONS 1
|
||||
|
||||
- Enable support for the deprecated 'wl_shell', Only useful when the BSP on the target has weston ``9.x``
|
||||
|
||||
.. code:: c
|
||||
|
||||
#define LV_WAYLAND_WL_SHELL 1
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
An example simulator is available in this `repo <https://github.com/lvgl/lv_port_linux/>`__
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
#. In ``main.c`` ``#incude "lv_drivers/wayland/wayland.h"``
|
||||
#. Enable the Wayland driver in ``lv_conf.h`` with ``LV_USE_WAYLAND 1``
|
||||
|
||||
#. ``LV_COLOR_DEPTH`` should be set either to ``32`` or ``16`` in ``lv_conf.h``
|
||||
|
||||
#. Add a display using ``lv_wayland_window_create()``,
|
||||
possibly with a close callback to track the status of each display:
|
||||
|
||||
.. code:: c
|
||||
|
||||
#define H_RES (800)
|
||||
#define V_RES (480)
|
||||
|
||||
/* Create a display */
|
||||
lv_disp_t * disp = lv_wayland_create_window(H_RES, V_RES, "Window Title", close_cb);
|
||||
|
||||
|
||||
As part of the above call, the Wayland driver will register four input devices
|
||||
for each display:
|
||||
|
||||
* a KEYPAD connected to Wayland keyboard events
|
||||
* a POINTER connected to Wayland touch events
|
||||
* a POINTER connected to Wayland pointer events
|
||||
* an ENCODER connected to Wayland pointer axis events
|
||||
|
||||
Handles for input devices of each display can be obtained using
|
||||
``lv_wayland_get_indev_keyboard()``, ``lv_wayland_get_indev_touchscreen()``,
|
||||
``lv_wayland_get_indev_pointer()`` and ``lv_wayland_get_indev_pointeraxis()`` respectively.
|
||||
|
||||
Fullscreen mode
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
To programmatically fullscreen the window,
|
||||
use the ``lv_wayland_window_set_fullscreen()`` function respectively with ``true``
|
||||
or ``false`` for the ``fullscreen`` argument.
|
||||
|
||||
Maximized mode
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
To programmatically maximize the window,
|
||||
use the ``lv_wayland_window_set_maximized()`` function respectively with ``true``
|
||||
or ``false`` for the ``maximized`` argument.
|
||||
|
||||
|
||||
Custom timer handler
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Always call ``lv_wayland_timer_handler()`` in your timer loop instead of the regular ``lv_timer_handler()``.
|
||||
|
||||
**Note:** ``lv_wayland_timer_handler()`` internally calls ``lv_timer_handler()``
|
||||
|
||||
This allows the wayland client to work on well on weston, resizing shared memory buffers during
|
||||
a commit does not work well on weston.
|
||||
|
||||
Wrapping the call to ``lv_timer_hander()`` is a necessity to have more control over
|
||||
when the LVGL flush callback is called.
|
||||
|
||||
The custom timer handler returns ``false`` if the frame from previous cycle is not rendered.
|
||||
When this happens, it usually means that the application is minimized or hidden behind another window.
|
||||
Causing the driver to wait until the arrival of any message on the wayland socket, the process is in interruptible sleep.
|
||||
|
||||
Building the wayland driver
|
||||
---------------------------
|
||||
|
||||
An example simulator is available in this `repo <https://github.com/lvgl/lv_port_linux/>`__
|
||||
|
||||
If there is a need to use driver with another build system. The source and header files for the XDG shell
|
||||
must be generated from the definitions for the XDG shell protocol.
|
||||
|
||||
In the example Cmake is used to perform the operation by invoking the ``wayland-scanner`` utility
|
||||
|
||||
To achieve this manually,
|
||||
|
||||
Make sure the dependencies listed at the start of the article are installed.
|
||||
|
||||
The wayland protocol is defined using XML files which are present in ``/usr/share/wayland-protocols``
|
||||
|
||||
To generate the required files run the following commands:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
wayland-scanner client-header </usr/share/wayland-protocols/stable/xdg-shell/xdg-shell.xml > wayland_xdg_shell.h
|
||||
wayland-scanner private-code </usr/share/wayland-protocols/stable/xdg-shell/xdg-shell.xml > wayland_xdg_shell.c
|
||||
|
||||
The resulting files can then be integrated into the project, it's better to re-run ``wayland-scanner`` on
|
||||
each build to ensure that the correct versions are generated, they must match the version of the ``wayland-client``
|
||||
dynamically linked library installed on the system.
|
||||
|
||||
|
||||
Current state and objectives
|
||||
----------------------------
|
||||
|
||||
* Add direct rendering mode
|
||||
* Refactor the shell integrations to avoid excessive conditional compilation
|
||||
* Technically, the wayland driver allows to create multiple windows - but this feature is experimental.
|
||||
* Eventually add enhanced support for XDG shell to allow the creation of desktop apps on Unix-like platforms,
|
||||
similar to what the win32 driver does.
|
||||
* Add a support for Mesa, currently wl_shm is used and it's not the most effective technique.
|
||||
|
||||
|
||||
Bug reports
|
||||
-----------
|
||||
|
||||
The wayland driver is currently under construction, bug reports, contributions and feedback is always welcome.
|
||||
|
||||
It is however important to create detailed issues when a problem is encountered, logs and screenshots of the problem are of great help.
|
||||
|
||||
Please enable ``LV_USE_LOG`` and launch the simulator executable like so
|
||||
|
||||
.. code::
|
||||
|
||||
WAYLAND_DEBUG=1 ./path/to/simulator_executable > /tmp/debug 2>&1
|
||||
|
||||
This will create a log file called ``debug`` in the ``/tmp`` directory, copy-paste the content of the file in the github issue.
|
||||
The log file contains LVGL logs and the wayland messages.
|
||||
|
||||
Be sure to replicate the problem quickly otherwise the logs become too big
|
||||
|
||||
113
docs/details/integration/driver/windows.rst
Normal file
113
docs/details/integration/driver/windows.rst
Normal file
@@ -0,0 +1,113 @@
|
||||
=============================
|
||||
Windows Display/Inputs driver
|
||||
=============================
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The **Windows** display/input `driver <https://github.com/lvgl/lvgl/src/drivers/windows>`__ offers support for simulating the LVGL display and keyboard/mouse inputs in a Windows Win32 window.
|
||||
|
||||
The main purpose for this driver is for testing/debugging the LVGL application in a **Windows** simulation window via **simulator mode**, or developing a standard **Windows** desktop application with LVGL via **application mode**.
|
||||
|
||||
Here are the **similarity** for simulator mode and application mode.
|
||||
|
||||
- Support LVGL pointer, keypad and encoder devices integration.
|
||||
- Support Windows touch input.
|
||||
- Support Windows input method integration input.
|
||||
- Support Per-monitor DPI Aware (both V1 and V2).
|
||||
|
||||
Here are the **differences** for simulator mode and application mode.
|
||||
|
||||
Simulator Mode
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
- Designed for LVGL simulation scenario.
|
||||
- Keep the LVGL display resolution all time for trying best to simulate UI layout which will see in their production devices.
|
||||
- When Windows DPI scaling setting is changed, Windows backend will stretch the display content.
|
||||
|
||||
Application Mode
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
- Designed for Windows desktop application development scenario.
|
||||
- Have the Window resizing support and LVGL display resolution will be changed.
|
||||
- When Windows DPI scaling setting is changed, the LVGL display DPI value will also be changed.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
The minimum Windows OS requirement for this driver is Windows Vista RTM.
|
||||
|
||||
If you use Windows API shim libraries like `YY-Thunks <https://github.com/Chuyu-Team/YY-Thunks>`__, the tested minimum Windows OS requirement for this driver is Windows XP RTM.
|
||||
|
||||
According to the Windows GDI API this driver used. Maybe the minimum Windows OS requirement limitation for this driver is Windows 2000 RTM.
|
||||
|
||||
Configure Windows driver
|
||||
------------------------
|
||||
|
||||
Enable the Windows driver support in lv_conf.h, by cmake compiler define or by KConfig
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_USE_WINDOWS 1
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include <Windows.h>
|
||||
#include "lvgl/lvgl.h"
|
||||
#include "lvgl/examples/lv_examples.h"
|
||||
#include "lvgl/demos/lv_demos.h"
|
||||
|
||||
int main()
|
||||
{
|
||||
lv_init();
|
||||
|
||||
int32_t zoom_level = 100;
|
||||
bool allow_dpi_override = false;
|
||||
bool simulator_mode = false;
|
||||
lv_display_t* display = lv_windows_create_display(
|
||||
L"LVGL Display Window",
|
||||
800,
|
||||
480,
|
||||
zoom_level,
|
||||
allow_dpi_override,
|
||||
simulator_mode);
|
||||
if (!display)
|
||||
{
|
||||
return -1;
|
||||
}
|
||||
|
||||
lv_lock();
|
||||
|
||||
lv_indev_t* pointer_device = lv_windows_acquire_pointer_indev(display);
|
||||
if (!pointer_device)
|
||||
{
|
||||
return -1;
|
||||
}
|
||||
|
||||
lv_indev_t* keypad_device = lv_windows_acquire_keypad_indev(display);
|
||||
if (!keypad_device)
|
||||
{
|
||||
return -1;
|
||||
}
|
||||
|
||||
lv_indev_t* encoder_device = lv_windows_acquire_encoder_indev(display);
|
||||
if (!encoder_device)
|
||||
{
|
||||
return -1;
|
||||
}
|
||||
|
||||
lv_demo_widgets();
|
||||
|
||||
lv_unlock();
|
||||
|
||||
while (1)
|
||||
{
|
||||
uint32_t time_till_next = lv_timer_handler();
|
||||
lv_delay_ms(time_till_next);
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
103
docs/details/integration/framework/arduino.rst
Normal file
103
docs/details/integration/framework/arduino.rst
Normal file
@@ -0,0 +1,103 @@
|
||||
=======
|
||||
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 :ref:`requirements of LVGL <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`
|
||||
|
||||
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-block:: 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/details/integration/framework/index.rst
Normal file
11
docs/details/integration/framework/index.rst
Normal file
@@ -0,0 +1,11 @@
|
||||
==========
|
||||
Frameworks
|
||||
==========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
arduino
|
||||
platformio
|
||||
tasmota-berry
|
||||
|
||||
5
docs/details/integration/framework/platformio.rst
Normal file
5
docs/details/integration/framework/platformio.rst
Normal file
@@ -0,0 +1,5 @@
|
||||
==========
|
||||
PlatformIO
|
||||
==========
|
||||
|
||||
TODO
|
||||
105
docs/details/integration/framework/tasmota-berry.rst
Normal file
105
docs/details/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 Widgets, 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-block:: 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/details/integration/ide/index.rst
Normal file
9
docs/details/integration/ide/index.rst
Normal file
@@ -0,0 +1,9 @@
|
||||
====
|
||||
IDEs
|
||||
====
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
mdk
|
||||
pc-simulator
|
||||
5
docs/details/integration/ide/mdk.rst
Normal file
5
docs/details/integration/ide/mdk.rst
Normal file
@@ -0,0 +1,5 @@
|
||||
===
|
||||
MDK
|
||||
===
|
||||
|
||||
TODO
|
||||
54
docs/details/integration/ide/pc-simulator.rst
Normal file
54
docs/details/integration/ide/pc-simulator.rst
Normal file
@@ -0,0 +1,54 @@
|
||||
.. _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.
|
||||
- Better developer experience: On PC Debuggers are usually faster and better, you can log to files,
|
||||
add a lot of ``printf`` s, do profiling, and so on.
|
||||
|
||||
|
||||
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, supports CMake as well
|
||||
- `VisualStudio <https://github.com/lvgl/lv_port_pc_visual_studio>`__: Recommended on Windows
|
||||
- `VSCode with SDL driver <https://github.com/lvgl/lv_port_pc_vscode>`__: Recommended on Linux (SDL) and Mac (SDL)
|
||||
- `CodeBlocks <https://github.com/lvgl/lv_sim_codeblocks_win>`__: Recommended on Windows
|
||||
- `PlatformIO with SDL driver <https://github.com/lvgl/lv_platformio>`__: Recommended on Linux and Mac but has an STM32 environment as well
|
||||
- `Generic Linux <https://github.com/lvgl/lv_port_linux>`__: CMake based project where you can easily switch between fbdev, DRM, and SDL.
|
||||
- `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
|
||||
|
||||
Built-in drivers
|
||||
----------------
|
||||
|
||||
LVGL comes with several :ref:`built-in drivers <drivers>`.
|
||||
|
||||
Even if a simulator project comes with e.g. SDL, you can easily replace it by enabling
|
||||
another driver in ``lv_conf.h`` and calling its ``create`` function.
|
||||
|
||||
For example to use the Linux frame buffer device instead of SDL just enable ``LV_USE_LINUX_FBDEV``
|
||||
and call
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
lv_display_t *display = lv_linux_fbdev_create();
|
||||
lv_linux_fbdev_set_file(display, "/dev/fb0")
|
||||
17
docs/details/integration/index.rst
Normal file
17
docs/details/integration/index.rst
Normal file
@@ -0,0 +1,17 @@
|
||||
.. _integration_index:
|
||||
|
||||
=======================
|
||||
Integration and Drivers
|
||||
=======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
bindings/index
|
||||
building/index
|
||||
chip/index
|
||||
driver/index
|
||||
renderers/index
|
||||
framework/index
|
||||
ide/index
|
||||
os/index
|
||||
5
docs/details/integration/os/freertos.rst
Normal file
5
docs/details/integration/os/freertos.rst
Normal file
@@ -0,0 +1,5 @@
|
||||
========
|
||||
FreeRTOS
|
||||
========
|
||||
|
||||
TODO
|
||||
14
docs/details/integration/os/index.rst
Normal file
14
docs/details/integration/os/index.rst
Normal file
@@ -0,0 +1,14 @@
|
||||
======
|
||||
(RT)OS
|
||||
======
|
||||
|
||||
.. toctree:: :maxdepth: 2
|
||||
|
||||
freertos
|
||||
mqx
|
||||
nuttx
|
||||
px5
|
||||
qnx
|
||||
rt-thread
|
||||
yocto/index
|
||||
zephyr
|
||||
10
docs/details/integration/os/mqx.rst
Normal file
10
docs/details/integration/os/mqx.rst
Normal file
@@ -0,0 +1,10 @@
|
||||
.. _mqx:
|
||||
|
||||
========
|
||||
MQX RTOS
|
||||
========
|
||||
|
||||
See `MQX RTOS's homepage <https://www.nxp.com/design/design-center/software/embedded-software/mqx-software-solutions/mqx-real-time-operating-system-rtos:MQXRTOS>`__
|
||||
|
||||
|
||||
TODO
|
||||
158
docs/details/integration/os/nuttx.rst
Normal file
158
docs/details/integration/os/nuttx.rst
Normal file
@@ -0,0 +1,158 @@
|
||||
==========
|
||||
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-block:: 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-block:: shell
|
||||
|
||||
$ mkdir ~/nuttxspace
|
||||
$ cd ~/nuttxspace
|
||||
|
||||
Clone the NuttX and Apps repositories:
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: 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-block:: 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-block:: 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-block:: 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-block:: shell
|
||||
|
||||
nsh> lvgldemo
|
||||
|
||||
Configurations
|
||||
--------------
|
||||
Here are some configurations that you can use to customize your NuttX and LVGL setup:
|
||||
|
||||
- **LV_USE_NUTTX_INDEPENDENT_IMAGE_HEAP** - You can enable or disable the
|
||||
LVGL image heap in NuttX. By default, it is disabled. If you enable
|
||||
it, LVGL will use the NuttX heap instead.
|
||||
|
||||
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/>`__
|
||||
|
||||
|
||||
.. Comment: The above blank line is necessary for Sphinx to not complain,
|
||||
since it looks for the blank line after a bullet list.
|
||||
8
docs/details/integration/os/px5.rst
Normal file
8
docs/details/integration/os/px5.rst
Normal file
@@ -0,0 +1,8 @@
|
||||
========
|
||||
PX5 RTOS
|
||||
========
|
||||
|
||||
See `PX5 RTOS's homepage <https://px5rtos.com/>`__
|
||||
|
||||
|
||||
TODO
|
||||
158
docs/details/integration/os/qnx.rst
Normal file
158
docs/details/integration/os/qnx.rst
Normal file
@@ -0,0 +1,158 @@
|
||||
.. _qnx:
|
||||
|
||||
===
|
||||
QNX
|
||||
===
|
||||
|
||||
What is QNX?
|
||||
************
|
||||
|
||||
QNX is a commercial operating system first released in 1980. The operating
|
||||
system is based on a micro-kernel design, with the file system(s), network
|
||||
stack, and various other drivers each running in its own process with a separate
|
||||
address space.
|
||||
|
||||
See www.qnx.com for more details.
|
||||
|
||||
Highlight of QNX
|
||||
----------------
|
||||
|
||||
- 64-bit only, runs on x86_64 and ARMv8
|
||||
- Requires an MMU as the design mandates separation among processes
|
||||
- Support for thousands of processes and millions of threads
|
||||
- Up to 64 cores, up to 16TB of RAM
|
||||
- Virtualization support (as host and guest)
|
||||
- Full POSIX compatibility
|
||||
- Safety certification to various automotive, industrial and medical standards
|
||||
|
||||
How to run LVGL on QNX?
|
||||
***********************
|
||||
|
||||
There are two ways to use LVGL in your QNX project. The first is similar to how
|
||||
LVGL is used on other systems. The second is to build LVGL as either a shared or
|
||||
a static library.
|
||||
|
||||
Include LVGL in Your Project
|
||||
----------------------------
|
||||
|
||||
Follow the generic instructions for getting started with LVGL. After copying
|
||||
`lv_conf_template.h` to `lv_conf.h` make the following changes to the latter:
|
||||
|
||||
1. Enable QNX support:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_USE_QNX 1
|
||||
|
||||
2. Set colour depth to 32:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_COLOR_DEPTH 32
|
||||
|
||||
3. (Optional) Enable double-buffering:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#define LV_QNX_BUF_COUNT 2
|
||||
|
||||
Build LVGL as a Library
|
||||
-----------------------
|
||||
|
||||
**Note that this method is an alternative to including LVGL in your project. If
|
||||
you choose to build a library then you do not need to follow the instructions in
|
||||
the previous section.**
|
||||
|
||||
The top-level `qnx` directory includes a recursive make file for building LVGL,
|
||||
both as a shared library and as a static library for the supported
|
||||
architectures. To build all libraries, simply invoke `make` in this directory:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
# cd $(LVGL_ROOT)/env_support/qnx
|
||||
# make
|
||||
|
||||
If you prefer to build for a specific architecture and variant, go to the
|
||||
appropriate directory and run `make` there. For example, to build a shared
|
||||
library for ARMv8:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
# cd $(LVGL_ROOT)/env_support/qnx/aarch64/so.le
|
||||
# make
|
||||
|
||||
As a general rule, if you only want to have one LVGL application in your system
|
||||
then it is better to use a static library. If you have more than one, and
|
||||
especially if they run concurrently, it is better to use the shared library.
|
||||
|
||||
Before building the library, you may wish to edit
|
||||
`$(LVGL_ROOT)/env_support/qnx/lv_conf.h`, e.g. to add fonts or disable
|
||||
double-buffering.
|
||||
|
||||
Writing a LVGL Application
|
||||
--------------------------
|
||||
|
||||
To create a LVGL application for QNX, follow these steps in your code:
|
||||
|
||||
1. Initialize the library.
|
||||
2. Create a window.
|
||||
3. Add the input devices.
|
||||
4. Create the UI.
|
||||
5. Run the event loop.
|
||||
|
||||
Steps 2, 3 and 5 use QNX-specific calls, but the rest of the code should be
|
||||
identical to that of a LVGL application written for any other platform.
|
||||
|
||||
The following code shows how to create a "Hello World" application:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include <lvgl.h>
|
||||
|
||||
int
|
||||
main(int argc, char **argv)
|
||||
{
|
||||
/* Initialize the library. */
|
||||
lv_init();
|
||||
|
||||
/* Create a 800x480 window. */
|
||||
lv_display_t *disp = lv_qnx_window_create(800, 480);
|
||||
lv_qnx_window_set_title(disp, "LVGL Example");
|
||||
|
||||
/* Add keyboard and mouse devices. */
|
||||
lv_qnx_add_keyboard_device(disp);
|
||||
lv_qnx_add_pointer_device(disp);
|
||||
|
||||
/* Generate the UI. */
|
||||
lv_obj_set_style_bg_color(lv_screen_active(), lv_color_hex(0x003a57), LV_PART_MAIN);
|
||||
|
||||
lv_obj_t * label = lv_label_create(lv_screen_active());
|
||||
lv_label_set_text(label, "Hello world");
|
||||
lv_obj_set_style_text_color(lv_screen_active(), lv_color_hex(0xffffff), LV_PART_MAIN);
|
||||
lv_obj_align(label, LV_ALIGN_CENTER, 0, 0);
|
||||
|
||||
/* Run the event loop until it exits. */
|
||||
return lv_qnx_event_loop(disp);
|
||||
}
|
||||
|
||||
Build the Application
|
||||
---------------------
|
||||
|
||||
Building the application consists of compiling the source with the LVGL headers,
|
||||
and then linking against the library. This can be done in many ways, using
|
||||
different build systems. The following is a simple make file for the example
|
||||
above, which builds for ARMv8 with the shared library:
|
||||
|
||||
.. code-block:: makefile
|
||||
|
||||
CC=qcc -Vgcc_ntoaarch64le
|
||||
|
||||
LVGL_ROOT=$(HOME)/src/lvgl
|
||||
CCFLAGS=-I$(LVGL_ROOT)/env_support/qnx -I$(LVGL_ROOT)
|
||||
LDFLAGS=-lscreen -llvgl -L$(LVGL_ROOT)/env_support/qnx/aarch64/so.le
|
||||
|
||||
lvgl_example: lvgl_example.c
|
||||
$(CC) $(CCFLAGS) -Wall -o $@ $< $(LDFLAGS)
|
||||
|
||||
clean:
|
||||
rm -f *.o *~ lvgl_example
|
||||
88
docs/details/integration/os/rt-thread.rst
Normal file
88
docs/details/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/>`__
|
||||
149
docs/details/integration/os/yocto/core_components.rst
Normal file
149
docs/details/integration/os/yocto/core_components.rst
Normal file
@@ -0,0 +1,149 @@
|
||||
.. _yocto_project_core_components:
|
||||
|
||||
=============================
|
||||
Yocto Project Core Components
|
||||
=============================
|
||||
|
||||
The BitBake task executor together with various types of configuration files
|
||||
form the OpenEmbedded-Core (OE-Core). This section overviews these components
|
||||
by describing their use and how they interact.
|
||||
|
||||
BitBake handles the parsing and execution of the data files. The data
|
||||
itself is of various types:
|
||||
|
||||
- *Recipes:* Provides details about particular pieces of software.
|
||||
|
||||
- *Class Data:* Abstracts common build information (e.g. how to build a
|
||||
Linux kernel).
|
||||
|
||||
- *Configuration Data:* Defines machine-specific settings, policy
|
||||
decisions, and so forth. Configuration data acts as the glue to bind
|
||||
everything together.
|
||||
|
||||
BitBake knows how to combine multiple data sources together and refers
|
||||
to each data source as a layer.
|
||||
|
||||
Here are some brief details on these core components.
|
||||
|
||||
.. _bitbake_section:
|
||||
|
||||
BitBake
|
||||
*******
|
||||
|
||||
BitBake is the tool at the heart of the OpenEmbedded Build System and is
|
||||
responsible for parsing the Metadata, generating a list of tasks from it, and
|
||||
then executing those tasks.
|
||||
|
||||
This section briefly introduces BitBake. If you want more information on
|
||||
BitBake, see the `BitBake User Manual <https://docs.yoctoproject.org/bitbake/2.
|
||||
8/index.html>`_.
|
||||
|
||||
To see a list of the options BitBake supports, use either of the
|
||||
following commands::
|
||||
|
||||
$ bitbake -h
|
||||
$ bitbake --help
|
||||
|
||||
The most common usage for BitBake is ``bitbake recipename``, where
|
||||
``recipename`` is the name of the recipe you want to build (referred
|
||||
to as the "target"). The target often equates to the first part of a
|
||||
recipe's filename (e.g. "foo" for a recipe named ``foo_1.3.0-r0.bb``).
|
||||
So, to process the ``matchbox-desktop_1.2.3.bb`` recipe file, you might
|
||||
type the following::
|
||||
|
||||
$ bitbake matchbox-desktop
|
||||
|
||||
Several different versions of ``matchbox-desktop`` might exist. BitBake chooses
|
||||
the one selected by the distribution configuration. You can get more details
|
||||
about how BitBake chooses between different target versions and providers in the
|
||||
"`Preferences <https://docs.yoctoproject.org/bitbake/2.8/bitbake-user-manual/
|
||||
bitbake-user-manual-execution.html#preferences>`_" section of the BitBake User
|
||||
Manual.
|
||||
|
||||
BitBake also tries to execute any dependent tasks first. So for example,
|
||||
before building ``matchbox-desktop``, BitBake would build a cross
|
||||
compiler and ``glibc`` if they had not already been built.
|
||||
|
||||
A useful BitBake option to consider is the ``-k`` or ``--continue``
|
||||
option. This option instructs BitBake to try and continue processing the
|
||||
job as long as possible even after encountering an error. When an error
|
||||
occurs, the target that failed and those that depend on it cannot be
|
||||
remade. However, when you use this option other dependencies can still
|
||||
be processed.
|
||||
|
||||
.. _recipes_section:
|
||||
|
||||
Recipes
|
||||
*******
|
||||
|
||||
Files that have the ``.bb`` suffix are "recipes" files. In general, a
|
||||
recipe contains information about a single piece of software. This
|
||||
information includes the location from which to download the unaltered
|
||||
source, any source patches to be applied to that source (if needed),
|
||||
which special configuration options to apply, how to compile the source
|
||||
files, and how to package the compiled output.
|
||||
|
||||
The term "package" is sometimes used to refer to recipes. However, since
|
||||
the word "package" is used for the packaged output from the OpenEmbedded
|
||||
build system (i.e. ``.ipk`` or ``.deb`` files), this document avoids
|
||||
using the term "package" when referring to recipes.
|
||||
|
||||
|
||||
.. _classes_section:
|
||||
|
||||
Classes
|
||||
*******
|
||||
|
||||
Class files (``.bbclass``) contain information that is useful to share
|
||||
between recipes files. An example is the autotools* class,
|
||||
which contains common settings for any application that is built with
|
||||
the `GNU Autotools <https://en.wikipedia.org/wiki/GNU_Autotools>`.
|
||||
The "`Classes <https://docs.yoctoproject.org/ref-manual/classes.
|
||||
html#classes>`_" chapter in the Yocto Project
|
||||
Reference Manual provides details about classes and how to use them.
|
||||
|
||||
|
||||
.. _configurations_section:
|
||||
|
||||
Configurations
|
||||
**************
|
||||
|
||||
The configuration files (``.conf``) define various configuration
|
||||
variables that govern the OpenEmbedded build process. These files fall
|
||||
into several areas that define machine configuration options,
|
||||
distribution configuration options, compiler tuning options, general
|
||||
common configuration options, and user configuration options in
|
||||
``conf/local.conf``, which is found in the `Build Directory <https://docs.
|
||||
yoctoproject.org/ref-manual/terms.html#term-Build-Directory>`_.
|
||||
|
||||
.. _layers_section:
|
||||
|
||||
Layers
|
||||
******
|
||||
|
||||
Layers are repositories that contain related metadata (i.e. sets of
|
||||
instructions) that tell the OpenEmbedded build system how to build a
|
||||
target. `The yocto project layer model <https://docs.yoctoproject.org/
|
||||
overview-manual/yp-intro.html#the-yocto-project-layer-model>`_
|
||||
facilitates collaboration, sharing, customization, and reuse within the
|
||||
Yocto Project development environment. Layers logically separate
|
||||
information for your project. For example, you can use a layer to hold
|
||||
all the configurations for a particular piece of hardware. Isolating
|
||||
hardware-specific configurations allows you to share other metadata by
|
||||
using a different layer where that metadata might be common across
|
||||
several pieces of hardware.
|
||||
|
||||
There are many layers working in the Yocto Project development environment. The
|
||||
`Yocto Project Compatible Layer Index <https://www.yoctoproject.org/development/
|
||||
yocto-project-compatible-layers/>`_ and `OpenEmbedded Layer Index <https://
|
||||
layers.openembedded.org/layerindex/branch/master/layers/>`_ both contain layers
|
||||
from
|
||||
which you can use or leverage.
|
||||
|
||||
By convention, layers in the Yocto Project follow a specific form. Conforming
|
||||
to a known structure allows BitBake to make assumptions during builds on where
|
||||
to find types of metadata. You can find procedures and learn about tools (i.e.
|
||||
``bitbake-layers``) for creating layers suitable for the Yocto Project in the
|
||||
"`understanding and creating layers <https://docs.yoctoproject.org/dev-manual/
|
||||
layers.html#understanding-and-creating-layers>`_" section of the
|
||||
Yocto Project Development Tasks Manual.
|
||||
28
docs/details/integration/os/yocto/index.rst
Normal file
28
docs/details/integration/os/yocto/index.rst
Normal file
@@ -0,0 +1,28 @@
|
||||
.. _yocto:
|
||||
|
||||
=====
|
||||
Yocto
|
||||
=====
|
||||
|
||||
The Yocto Project (YP) is an open source collaboration project that helps
|
||||
developers create custom Linux-based systems regardless of the hardware
|
||||
architecture.
|
||||
|
||||
The project provides a flexible set of tools and a space where embedded
|
||||
developers worldwide can share technologies, software stacks, configurations,
|
||||
and best practices that can be used to create tailored Linux images for
|
||||
embedded and IOT devices, or anywhere a customized Linux OS is needed.
|
||||
|
||||
This section objective is to ease to process of understanding the basic
|
||||
concepts of Yocto and to help beginners to start with Yocto.
|
||||
|
||||
|
||||
.. toctree::
|
||||
:titlesonly:
|
||||
:maxdepth: 1
|
||||
|
||||
core_components
|
||||
lvgl_recipe
|
||||
terms_and_variables
|
||||
|
||||
|
||||
916
docs/details/integration/os/yocto/lvgl_recipe.rst
Normal file
916
docs/details/integration/os/yocto/lvgl_recipe.rst
Normal file
@@ -0,0 +1,916 @@
|
||||
.. _yocto_lvgl_recipe:
|
||||
|
||||
=============
|
||||
LVGL in Yocto
|
||||
=============
|
||||
|
||||
This chapter serves as a guide to help you create a recipe for an application
|
||||
using LVGL. While the process will be demonstrated for the Raspberry Pi 3
|
||||
(64-bit), it can be applied to any board in a similar way.
|
||||
|
||||
Build Host Packages
|
||||
*******************
|
||||
You must install essential host packages on your build host. The following
|
||||
command installs the host packages based on an Ubuntu distribution
|
||||
|
||||
.. code-block::
|
||||
|
||||
sudo apt install gawk wget git diffstat unzip texinfo gcc build-essential \
|
||||
chrpath socat cpio python3 python3-pip python3-pexpect xz-utils \
|
||||
debianutils iputils-ping python3-git python3-jinja2 python3-subunit zstd \
|
||||
liblz4-tool file locales libacl1
|
||||
|
||||
.. note::
|
||||
|
||||
For host package requirements on all supported Linux distributions, see the
|
||||
`Required Packages for the Build Host <https://docs.yoctoproject.org/
|
||||
ref-manual/system-requirements.html#required-packages-for-the-build-host>`_
|
||||
section in the Yocto Project Reference Manual.
|
||||
|
||||
|
||||
|
||||
Use Git to clone the required repositories
|
||||
******************************************
|
||||
After this section the folder tree will be like this
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
lvgl_yocto_guide/
|
||||
├── build/
|
||||
│ ├── cache/
|
||||
│ ├── conf/
|
||||
│ ├── downloads/
|
||||
│ └── ...
|
||||
└── sources/
|
||||
├── meta-openembedded
|
||||
├── meta-raspberrypi
|
||||
└── poky
|
||||
|
||||
Start creating the folder architecture
|
||||
|
||||
.. code-block::
|
||||
|
||||
mkdir -p lvgl_yocto_guide/sources
|
||||
|
||||
Clone Poky, meta-openembedded and meta-raspberrypi in the sources
|
||||
|
||||
.. code-block::
|
||||
|
||||
cd lvgl_yocto_guide/sources
|
||||
git clone --branch scarthgap https://git.yoctoproject.org/poky.git
|
||||
git clone --branch scarthgap https://git.openembedded.org/meta-openembedded
|
||||
git clone --branch scarthgap git://git.yoctoproject.org/meta-raspberrypi
|
||||
|
||||
|
||||
Build a base image
|
||||
******************
|
||||
To understand better what is going on, let's build the image like it is
|
||||
prepared for us
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
cd ../ # go back to the root folder
|
||||
source sources/poky/oe-init-build-env
|
||||
|
||||
Now you should have a folder named ``build`` next to ``sources``. The last
|
||||
command
|
||||
also sets the current directory to the build directory.
|
||||
|
||||
In the build directory, there is a ``conf`` folder with some files in it
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
└── build/
|
||||
└── conf/
|
||||
├── bblayers.conf
|
||||
├── conf-notes.txt
|
||||
├── conf-summary.txt
|
||||
├── local.conf
|
||||
└── templateconf.cfg
|
||||
|
||||
The important files for us are ``local.conf`` and ``bblayers.conf``
|
||||
|
||||
To add layers to the project there are 2 options:
|
||||
|
||||
**Bitbake commands (Option 1)**
|
||||
|
||||
You need to be in the same terminal you did the ``source`` command. Add the
|
||||
layers with the Bitbake command like this
|
||||
|
||||
.. code-block::
|
||||
|
||||
bitbake-layers add-layer ../sources/meta-openembedded
|
||||
bitbake-layers add-layer ../sources/meta-raspberrypi
|
||||
|
||||
**Modify conf file (Option 2)**
|
||||
|
||||
Open ``conf/bblayers.conf`` file and add manually the paths:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
|
||||
# changes incompatibly
|
||||
POKY_BBLAYERS_CONF_VERSION = "2"
|
||||
|
||||
BBPATH = "${TOPDIR}"
|
||||
BBFILES ?= ""
|
||||
|
||||
BBLAYERS ?= " \
|
||||
${TOPDIR}/../sources/poky/meta \
|
||||
${TOPDIR}/../sources/poky/meta-poky \
|
||||
${TOPDIR}/../sources/poky/meta-yocto-bsp \
|
||||
${TOPDIR}/../sources/meta-raspberrypi \
|
||||
${TOPDIR}/../sources/meta-openembedded/meta-oe \
|
||||
${TOPDIR}/../sources/meta-openembedded/meta-multimedia \
|
||||
${TOPDIR}/../sources/meta-openembedded/meta-networking \
|
||||
${TOPDIR}/../sources/meta-openembedded/meta-python \
|
||||
"
|
||||
|
||||
To ensure the layers were added as expected, run the Bitbake command to show
|
||||
all the layers::
|
||||
|
||||
bitbake-layers show-layers
|
||||
|
||||
The following layers should be listed:
|
||||
- core
|
||||
- yocto
|
||||
- yoctobsp
|
||||
- raspberrypi
|
||||
- openembedded-layer
|
||||
- multimedia-layer
|
||||
- networking-layer
|
||||
- meta-python
|
||||
|
||||
Build for RaspberryPi3 64
|
||||
=========================
|
||||
|
||||
The available machine configurations for Raspberrypi can be listed like this
|
||||
|
||||
.. code-block::
|
||||
|
||||
ls ../sources/meta-raspberrypi/conf/machine/*.conf
|
||||
|
||||
To build an image for Raspberrypi3 64 bits, modify the file ``local.conf`` file
|
||||
replacing the ``MACHINE ??=`` default value like this
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
MACHINE ??= "raspberrypi3-64"
|
||||
|
||||
To build the image we will target, it is also needed to add this to the file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
LICENSE_FLAGS_ACCEPTED = "synaptics-killswitch"
|
||||
|
||||
.. note::
|
||||
|
||||
You can find more information about this variable `here <https://meta-raspberrypi.readthedocs.io/en/latest/ipcompliance.html#linux-firmware-rpidistro>`_.
|
||||
|
||||
Everything is setup, time to build the image::
|
||||
|
||||
bitbake core-image-base
|
||||
|
||||
|
||||
Overview of the build
|
||||
=====================
|
||||
|
||||
Let's go through the build folders to understand what happened.
|
||||
|
||||
Downloads
|
||||
---------
|
||||
|
||||
The folder location can be changed with the ``DL_DIR`` variable.
|
||||
|
||||
The Downloads folder is a fundamental part of the Yocto build environment,
|
||||
serving as a local cache for all external sources and dependencies. This
|
||||
caching mechanism is essential for efficient builds, ensuring that repeated
|
||||
builds do not waste time downloading the same files again.
|
||||
|
||||
|
||||
tmp/deploy
|
||||
----------
|
||||
|
||||
This folder contains the final output artifacts that are ready for deployment.
|
||||
These artifacts include kernel images, root filesystems, packages, SDKs,
|
||||
bootloader files, and other components that are generated during the Yocto
|
||||
build process.
|
||||
|
||||
There are some key folders:
|
||||
- **images**: it contains the images that can be flashed or deployed to
|
||||
the target device. Files like the Linux kernel, root filesystem (e.g., .
|
||||
ext4, .tar.gz, .squashfs), bootloaders (e.g., U-Boot), and other
|
||||
bootable images for the device are found here. t’s organized by the
|
||||
machine (or target board) for which the image was built.
|
||||
- **rmp/deb/ipk**: These folders contain the individual software packages
|
||||
generated during the build, in the specified package format (RPM, DEB,
|
||||
or IPK). These packages are typically created when you’re building your
|
||||
Yocto project with package management support enabled. These can later
|
||||
be installed on the target device using package management tools
|
||||
- **sdk**: This subdirectory contains Software Development Kits (SDKs)
|
||||
that you can use to cross-compile applications for your target system.
|
||||
The SDKs are generated when you use the ``bitbake -c populate_sdk``
|
||||
command.
|
||||
|
||||
|
||||
tmp/sysroots-components
|
||||
-----------------------
|
||||
This folder is a modular approach introduced in Yocto to handle sysroots. It
|
||||
divides the sysroot into individual components, which can be thought of as the
|
||||
building blocks or packages that make up the entire sysroot environment.
|
||||
|
||||
Each component corresponds to a specific package or dependency that is staged
|
||||
into the sysroot. This approach allows for more efficient reuse of sysroots
|
||||
across multiple packages or builds, and it helps with dependency tracking and
|
||||
management during the build process.
|
||||
|
||||
The sysroot-components directory helps optimize the build process because if
|
||||
one package changes, Yocto only needs to update the corresponding component
|
||||
rather than rebuilding or copying the entire sysroot.
|
||||
|
||||
If you followed the previous steps, here are the folders you will find:
|
||||
- ``all``: Architecture-independent files.
|
||||
- ``cortexa53``: Files for the Cortex-A53 (ARMv8-A) architecture.
|
||||
- ``manifests``: Track files installed in the sysroot by package.
|
||||
- ``raspberrypi3_64``: Files specific to the Raspberry Pi 3 (64-bit).
|
||||
- ``x86_64``: Files for the x86_64 (PC) architecture, typically for
|
||||
cross-compilation tools.
|
||||
- ``x86_64-nativesdk``: Files related to the SDK for cross-compilation on
|
||||
an x86_64 host.
|
||||
|
||||
Each folder corresponds to components relevant to the specific architecture,
|
||||
and they collectively form the complete environment needed to compile and run
|
||||
software for the target and host systems.
|
||||
|
||||
tmp/sysroots-uninative
|
||||
----------------------
|
||||
|
||||
The sysroots-uninative directory in Yocto is used to support the "uninative"
|
||||
feature, which allows for more reproducible builds by ensuring that the build
|
||||
environment remains consistent across different host systems. It essentially
|
||||
provides a way to use the same native build tools across different Linux
|
||||
distributions.
|
||||
|
||||
tmp/work
|
||||
--------
|
||||
|
||||
The ``work`` folder in Yocto is a key directory in the ``tmp`` folder that
|
||||
holds all the temporary build artifacts for each package during the build
|
||||
process. It is where the actual building and compiling of individual packages
|
||||
or recipes takes place. Each package (or "recipe") that BitBake processes
|
||||
generates temporary files and directories inside this ``work`` folder.
|
||||
|
||||
The ``work`` folder is typically structured by machine architecture and
|
||||
package. Here's how it generally works:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
work/
|
||||
└── <architecture>/
|
||||
└── <package>/
|
||||
└── <version>/
|
||||
├── temp/
|
||||
├── work/
|
||||
├── sysroot-destdir/
|
||||
└── image/
|
||||
|
||||
This folder is very important and helps a lot during debug phases. The ``temp``
|
||||
subfolder contains important logs that can help you diagnose build issues. This
|
||||
is where you'll look when a build fails to figure out what went wrong.
|
||||
|
||||
|
||||
LVGL recipe
|
||||
***********
|
||||
|
||||
Find more information about recipes in :ref:`recipes_section` section.
|
||||
|
||||
There is a recipe in ``meta-openembedded`` since ``honister``.
|
||||
|
||||
.. list-table:: lvgl recipe version
|
||||
:widths: 200 100
|
||||
:header-rows: 1
|
||||
|
||||
* - Branch
|
||||
- Recipe
|
||||
* - scarthgap (Yocto Project 5.0)
|
||||
- lvgl 9.1.0
|
||||
* - nanbield (Yocto Project 4.3)
|
||||
- lvgl 8.3.10
|
||||
* - mickledore (Yocto Project 4.2)
|
||||
- lvgl 8.1.0
|
||||
* - langdale (Yocto Project 4.1)
|
||||
- lvgl 8.1.0
|
||||
* - langdale (Yocto Project 4.1)
|
||||
- lvgl 8.1.0
|
||||
* - kirkstone (Yocto Project 4.0)
|
||||
- lvgl 8.0.3
|
||||
|
||||
In this guide, we are on the ``scarthgap`` branch, so we are using lvgl 9.1.0.
|
||||
|
||||
Let's dive into this recipe to understand what is done. The objective is to add
|
||||
this library as a shared object in the target rootfs, and also to generate a
|
||||
SDK with lvgl.
|
||||
|
||||
This is the path of lvgl recipes: ``lvgl_yocto_guide/sources/meta-openembedded/
|
||||
meta-oe/recipes-graphics/lvgl``
|
||||
|
||||
Here is the architecture of lvgl recipes folder:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
lvgl
|
||||
├── files
|
||||
│ ├── 0002-fix-sdl-handle-both-LV_IMAGE_SRC_FILE-and-LV_IMAGE_S.patch
|
||||
│ ├── 0003-Make-fbdev-device-node-runtime-configurable-via-envi.patch
|
||||
│ ├── 0004-Factor-out-fbdev-initialization-code.patch
|
||||
│ ├── 0005-Add-DRM-KMS-example-support.patch
|
||||
│ ├── 0006-Add-SDL2-example-support.patch
|
||||
│ ├── 0007-fix-cmake-generate-versioned-shared-libraries.patch
|
||||
│ └── 0008-fix-fbdev-set-resolution-prior-to-buffer.patch
|
||||
├── lv-conf.inc
|
||||
├── lvgl_9.1.0.bb
|
||||
└── lvgl-demo-fb_9.1.0.bb
|
||||
|
||||
- ``file`` folder contains all the patches that can be applied when
|
||||
building the recipe.
|
||||
- ``lv_conf.inc`` is an include file, usually containing common configuration
|
||||
settings for LVGL that can be shared between multiple recipes.
|
||||
- ``lvgl_9.1.0.bb`` is the recipe to build lvgl library.
|
||||
- ``lvgl-demo-fb_9.1.0.bb`` is a recipe to build an application using lvgl.
|
||||
|
||||
For now let's understand the recipe of lvgl library.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# SPDX-FileCopyrightText: Huawei Inc.
|
||||
#
|
||||
# SPDX-License-Identifier: MIT
|
||||
|
||||
HOMEPAGE = "https://lvgl.io/"
|
||||
DESCRIPTION = "LVGL is an OSS graphics library to create embedded GUI"
|
||||
SUMMARY = "Light and Versatile Graphics Library"
|
||||
LICENSE = "MIT"
|
||||
LIC_FILES_CHKSUM = "file://LICENCE.txt;md5=bf1198c89ae87f043108cea62460b03a"
|
||||
|
||||
SRC_URI = "\
|
||||
git://github.com/lvgl/lvgl;protocol=https;branch=master \
|
||||
file://0002-fix-sdl-handle-both-LV_IMAGE_SRC_FILE-and-LV_IMAGE_S.patch \
|
||||
file://0007-fix-cmake-generate-versioned-shared-libraries.patch \
|
||||
file://0008-fix-fbdev-set-resolution-prior-to-buffer.patch \
|
||||
"
|
||||
SRCREV = "e1c0b21b2723d391b885de4b2ee5cc997eccca91"
|
||||
|
||||
inherit cmake
|
||||
|
||||
EXTRA_OECMAKE = "-DLIB_INSTALL_DIR=${baselib} -DBUILD_SHARED_LIBS=ON"
|
||||
S = "${WORKDIR}/git"
|
||||
|
||||
require lv-conf.inc
|
||||
|
||||
do_install:append() {
|
||||
install -d "${D}${includedir}/${PN}"
|
||||
install -m 0644 "${S}/lv_conf.h" "${D}${includedir}/${PN}/lv_conf.h"
|
||||
}
|
||||
|
||||
FILES:${PN}-dev += "\
|
||||
${includedir}/${PN}/ \
|
||||
"
|
||||
|
||||
**LICENSE**: Indicates the licensing of the software, stating that it is
|
||||
distributed under the MIT License.
|
||||
|
||||
**LIC_FILES_CHKSUM**: This variable contains a checksum (in this case, an MD5 hash)
|
||||
for the license file (here assumed to be LICENCE.txt). This helps to ensure the
|
||||
integrity of the license file included in the package. In LVGL repository,
|
||||
there is a LICENSE.txt. To get the value of the hash of the file, you can do
|
||||
this command: ``md5sum LICENSE.txt``
|
||||
|
||||
SRC_URI: Specifies the locations of the source code and patches for the recipe:
|
||||
- The main source repository for LVGL specifying the master branch.
|
||||
- The following arguments are the local patch files that will be applied to
|
||||
the source code during the build process.
|
||||
|
||||
**SRCREV**: Defines the specific commit (in this case, a Git SHA hash) from
|
||||
which the source code will be fetched. This ensures that the build uses a
|
||||
consistent version of the code.
|
||||
|
||||
**inherit**: This line indicates that the recipe uses the ``cmake`` class,
|
||||
which provides functionality for building projects that use CMake as
|
||||
their build system.
|
||||
|
||||
**EXTRA_OECMAKE**: Additional options passed to CMake during the
|
||||
configuration step.
|
||||
|
||||
**S**: This variable defines the source directory where the unpacked source
|
||||
code will be located after fetching. ``${WORKDIR}`` is a standard
|
||||
variable in BitBake that points to the working directory for the recipe.
|
||||
require: This line includes another configuration file, ``lv-conf.inc``,
|
||||
which likely contains additional configuration options or variables
|
||||
specific to the LVGL library.
|
||||
|
||||
**FILES**: This is a BitBake variable used to specify the files that should
|
||||
be included in a particular package. In this case, the variable is
|
||||
specifying files for a package related to development (i.e., header
|
||||
files).
|
||||
|
||||
Recipe Tasks
|
||||
************
|
||||
|
||||
When a recipe is compiled, it will run multiple tasks. You can run each task
|
||||
manually to understand what is generated each step, or you can run ``bitbake
|
||||
lvgl`` to run all the tasks.
|
||||
|
||||
Fetch (do_fetch)
|
||||
.. code-block:: bash
|
||||
|
||||
bitbake lvgl -c fetch
|
||||
|
||||
Fetch task fetches the package source from the local or remote repository.
|
||||
|
||||
The fetch Repo address has to be stored in **SRC_URI** variable. In
|
||||
**SRCREV** Variable the commit hash of github repo is defined.
|
||||
|
||||
When the fetch task has been completed, you can find the fetched sources in
|
||||
``build/downloads``.
|
||||
|
||||
For this recipe, you will find a new folder here: ``lvgl_yocto_guide
|
||||
build/downloads/git2/github.com.lvgl.lvgl``.
|
||||
|
||||
You can also find the folder architecture created in ``lvgl_yocto_guide/
|
||||
build/tmp/work/cortexa53-poky-linux/lvgl`` but these folders are empty since
|
||||
only the fetch was done.
|
||||
|
||||
|
||||
|
||||
|
||||
Unpack (do_upack)
|
||||
.. code-block:: bash
|
||||
|
||||
bitbake lvgl -c unpack
|
||||
|
||||
Unpack task unpacks the package that has been downloaded with Fetch task.
|
||||
|
||||
In the ``lvgl_yocto_guide/build/tmp/work/cortexa53-poky-linux/lvgl/9.1.0``
|
||||
folder, you can now find the source code in ``git`` (as it was defined in
|
||||
the recipe). You will also see the patches that will be applied on the next
|
||||
step. So for now, the sources are unmodified and the same than the commit
|
||||
that was specified.
|
||||
|
||||
|
||||
|
||||
Patch (do_patch)
|
||||
.. code-block:: bash
|
||||
|
||||
bitbake lvgl -c patch
|
||||
|
||||
Patch task locates the patch files and applies the patches to the sources
|
||||
if any patch is available. This is optional task, executes if patch is
|
||||
available.
|
||||
|
||||
Patch file is also defined in **SRC_URI** variable. By default it runs in
|
||||
current source directory **${S}**.
|
||||
|
||||
Configure (do_configure)
|
||||
.. code-block:: bash
|
||||
|
||||
bitbake lvgl -c configure
|
||||
|
||||
The Configuration task configures the source by enabling and disabling any
|
||||
build-time and configuration options for the software being built before
|
||||
compilation if any configuration is available.
|
||||
|
||||
This is a optional steps, executes if configuration is available.
|
||||
|
||||
In this case, it creates a build directory, It invokes CMake to configure
|
||||
the project, specifying build options and paths based on variables in your
|
||||
recipe. It generates Makefiles or project files needed for the build. Also,
|
||||
there are operations added in the task in ``lv-conf.inc``.
|
||||
|
||||
So at the end of the task, in the ``lvgl_yocto_guide/build/tmp/work/
|
||||
cortexa53-poky-linux/lvgl/9.1.0``, you will find a ``build`` folder that was
|
||||
generated running the CMake command, but nothing is built yet. Also, the
|
||||
sysroots have everything required to build lvgl library.
|
||||
|
||||
|
||||
Compile (do_compile)
|
||||
.. code-block:: bash
|
||||
|
||||
bitbake lvgl -c compile
|
||||
|
||||
The Compilation task compiles the source code if any compilation steps are
|
||||
available and generates a binary file.
|
||||
|
||||
This is a optional steps, executes if compilation is available.
|
||||
|
||||
If there are any compilation steps, then these steps are define in
|
||||
do_compile() funtion of bitbake.
|
||||
|
||||
Like in the previous task, this is handle by ``inherit cmake``.
|
||||
|
||||
In the build folder, you can now see the built library. The ``.so`` files
|
||||
are available in ``lvgl_yocto_guide/build/tmp/work/ cortexa53-poky-linux/lvgl/9.1.0/build/lib``.
|
||||
|
||||
After this task has been completed, everything is ready to be installed.
|
||||
|
||||
Install (do_install)
|
||||
.. code-block:: bash
|
||||
|
||||
bitbake lvgl -c install
|
||||
|
||||
The Install task copies files that are to be packaged into the holding area
|
||||
**${D}**. This task runs with the current working directory **${S}** which
|
||||
is the compilation directory.
|
||||
|
||||
It creates the necessary directory for the header files in the destination
|
||||
installation directory.
|
||||
It installs the ``lv_conf.h`` header file from the source directory into the
|
||||
appropriate include directory in the destination path, ensuring it has the
|
||||
correct permissions.
|
||||
|
||||
The lvgl library (``.so`` files) are also ready to be installed in the final
|
||||
image. A new folder ``image`` was created.
|
||||
|
||||
.. important::
|
||||
|
||||
In the file ``build/conf/local.conf``, add these 2 lines at the end of the
|
||||
file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
IMAGE_INSTALL:append = " lvgl"
|
||||
TOOLCHAIN_HOST_TASK:append = " lvgl"
|
||||
|
||||
This will add the lvgl library in the generated image, and it will also add
|
||||
the library to the host SDK we will generate later on.
|
||||
|
||||
With these modifications, you can now run the image recipe again::
|
||||
|
||||
bitbake core-image-base
|
||||
|
||||
This will execute all the previous described tasks.
|
||||
|
||||
If everything went well, you should now found this file ``build/tmp/deploy/
|
||||
rpm/cortexa53/lvgl-9.1.0-r0.cortexa53.rpm`` and other rpm files related to
|
||||
lvgl.
|
||||
|
||||
SDK generation
|
||||
**************
|
||||
|
||||
Generating a Software Development Kit (SDK) in Yocto serves several important
|
||||
purposes, particularly in embedded development:
|
||||
|
||||
- **Development Environment**: The SDK provides developers with a
|
||||
ready-to-use development environment tailored for a specific target
|
||||
hardware platform.
|
||||
This includes the necessary tools, libraries, and headers to build
|
||||
applications that run on the target device.
|
||||
- **Cross-Compilation**: The SDK allows developers to cross-compile
|
||||
applications from a host machine (typically x86 or x86_64 architecture)
|
||||
for a different architecture (e.g., ARM). This is essential for embedded
|
||||
systems, where development often occurs on more powerful machines.
|
||||
- **Simplified Development**: By packaging all required components, the SDK
|
||||
simplifies the process of setting up a development environment.
|
||||
Developers don't need to manually install and configure tools and
|
||||
libraries; everything needed is included in the SDK.
|
||||
- **Consistent Build Environment**: The SDK ensures that developers are
|
||||
working with the same versions of and tools used in the Yocto
|
||||
build, which helps to avoid compatibility issues and ensures that
|
||||
applications will behave as expected on the target device.
|
||||
|
||||
To generate an SDK of the environment, run the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
bitbake core-image-base -c populate_sdk
|
||||
|
||||
This will create a sript ``build/tmp/deploy/sdk/
|
||||
poky-glibc-x86_64-core-image-base-cortexa53-raspberrypi3-64-toolchain-5.0.4.
|
||||
sh``. This script allows you to install the SDK where you prefer. Here is the
|
||||
execution output of the scrips
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ./sdk/poky-glibc-x86_64-core-image-base-cortexa53-raspberrypi3-64-toolchain-5.0.4.sh
|
||||
Poky (Yocto Project Reference Distro) SDK installer version 5.0.4
|
||||
=================================================================
|
||||
Enter target directory for SDK (default: /opt/poky/5.0.4): /opt/poky/sdk-with-lvgl
|
||||
You are about to install the SDK to "/opt/poky/sdk-with-lvgl". Proceed [Y/n]? y
|
||||
|
||||
If you want to ensure the SDK was generated with lvgl being installed, go to
|
||||
the path you extracted the SDK and find all lvgl files:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd /opt/poky/5.0.4/sysroots/cortexa53-poky-linux
|
||||
find . -name "*lvgl*"
|
||||
|
||||
The ``.so`` files you will find will depend on the LVGL configuration you used.
|
||||
|
||||
Now to use the SDK environment and cross-compile an application:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
source /opt/poke/5.0.4/environment-setup-cortexa53-poky-linux
|
||||
|
||||
.. note::
|
||||
|
||||
The tools available in LVGL library will depend on the build configuration
|
||||
the recipe was done with.
|
||||
|
||||
|
||||
Custom recipe
|
||||
*************
|
||||
|
||||
Until this section, everything was already done for you. We used existing
|
||||
recipes. The objective here is to create a recipe from scratch and to add the
|
||||
generated binary in the image.
|
||||
|
||||
Create a layer
|
||||
==============
|
||||
|
||||
First, create a layer and add it to the configuration file
|
||||
|
||||
.. code-block::
|
||||
|
||||
bitbake-layers create-layer ../sources/meta-mylvgl
|
||||
bitbake-layers add-layer ../sources/meta-mylvgl
|
||||
|
||||
In the ``sources`` folder, a new folder was created: ``meta-mylvgl`` and the
|
||||
directory tree should look like the following
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
├── conf
|
||||
│ └── layer.conf
|
||||
├── COPYING.MIT
|
||||
├── README
|
||||
└── recipes-example
|
||||
└── example
|
||||
└── example_0.1.bb
|
||||
|
||||
|
||||
Create a recipe
|
||||
===============
|
||||
|
||||
Following this structure, create a folder containing the recipies to build 1
|
||||
or multiple applications using lvgl
|
||||
|
||||
.. code-block::
|
||||
|
||||
cd ../sources/meta-mylvgl
|
||||
mkdir -p recipes-lvglapp/lvgl-fbdev-benchmark/files
|
||||
touch recipes-lvglapp/lvgl-fbdev-benchmark/lvglbenchmarkfbdev_2.4.bb
|
||||
|
||||
We will focus on 1 application that will clone an lvgl git repository and patch
|
||||
it for our needs.
|
||||
|
||||
The content of ``recipes-lvglapp/lvgl-fbdev-benchmark/lvglbenchmarkfbdev_2.4.
|
||||
bb``
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
DESCRIPTION = "My C++ lvgl app with CMake"
|
||||
|
||||
LICENSE = "MIT"
|
||||
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
|
||||
|
||||
# Update SRC_URI to point to the GitHub repository
|
||||
SRC_URI = "gitsm://github.com/lvgl/lv_port_linux.git;branch=master;protocol=https \
|
||||
file://0001-change-config-file-to-run-fbdev-with-2-threads.patch \
|
||||
file://0002-adapt-CMakeLists-file-to-compile-and-link-fbdev.patch \
|
||||
"
|
||||
|
||||
S = "${WORKDIR}/git"
|
||||
|
||||
inherit cmake
|
||||
|
||||
CMAKE_PROJECT_NAME = "lvgl_app"
|
||||
CMAKE_PROJECT_VERSION = "2.0"
|
||||
|
||||
do_install() {
|
||||
install -d ${D}${bindir}
|
||||
install -m 0755 ${S}/bin/lvglbenchmark ${D}${bindir}
|
||||
}
|
||||
|
||||
The sources come from ``lv_port_linux`` repository. We apply 2 patches to modify the ``CMakeLists.txt`` and ``lv_conf.h``.
|
||||
|
||||
Patch 1
|
||||
-------
|
||||
|
||||
Create the first patch file
|
||||
|
||||
.. code-block::
|
||||
|
||||
touch 0001-change-config-file-to-run-fbdev-with-2-threads.patch
|
||||
|
||||
Content of ``0001-change-config-file-to-run-fbdev-with-2-threads.patch``
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
From d49d475d57f69d6172a6b38095ebf3b887f0e731 Mon Sep 17 00:00:00 2001
|
||||
From: Gabriel Catel Torres <gabriel.catel@edgemtech.ch>
|
||||
Date: Tue, 1 Oct 2024 10:28:55 +0200
|
||||
Subject: [PATCH] change config file to run fbdev with 2 threads
|
||||
|
||||
---
|
||||
lv_conf.h | 34 +++++++++++++++++-----------------
|
||||
1 file changed, 17 insertions(+), 17 deletions(-)
|
||||
|
||||
diff --git a/lv_conf.h b/lv_conf.h
|
||||
index 62a834f..58fbe7a 100644
|
||||
--- a/lv_conf.h
|
||||
+++ b/lv_conf.h
|
||||
@@ -39,9 +39,9 @@
|
||||
* - LV_STDLIB_RTTHREAD: RT-Thread implementation
|
||||
* - LV_STDLIB_CUSTOM: Implement the functions externally
|
||||
*/
|
||||
-#define LV_USE_STDLIB_MALLOC LV_STDLIB_BUILTIN
|
||||
-#define LV_USE_STDLIB_STRING LV_STDLIB_BUILTIN
|
||||
-#define LV_USE_STDLIB_SPRINTF LV_STDLIB_BUILTIN
|
||||
+#define LV_USE_STDLIB_MALLOC LV_STDLIB_CLIB
|
||||
+#define LV_USE_STDLIB_STRING LV_STDLIB_CLIB
|
||||
+#define LV_USE_STDLIB_SPRINTF LV_STDLIB_CLIB
|
||||
|
||||
#define LV_STDINT_INCLUDE <stdint.h>
|
||||
#define LV_STDDEF_INCLUDE <stddef.h>
|
||||
@@ -89,7 +89,7 @@
|
||||
* - LV_OS_WINDOWS
|
||||
* - LV_OS_MQX
|
||||
* - LV_OS_CUSTOM */
|
||||
-#define LV_USE_OS LV_OS_NONE
|
||||
+#define LV_USE_OS LV_OS_PTHREAD
|
||||
|
||||
#if LV_USE_OS == LV_OS_CUSTOM
|
||||
#define LV_OS_CUSTOM_INCLUDE <stdint.h>
|
||||
@@ -117,12 +117,12 @@
|
||||
* and can't be drawn in chunks. */
|
||||
|
||||
/* The target buffer size for simple layer chunks. */
|
||||
-#define LV_DRAW_LAYER_SIMPLE_BUF_SIZE (24 * 1024) /* [bytes] */
|
||||
+#define LV_DRAW_LAYER_SIMPLE_BUF_SIZE (512 * 1024) /* [bytes] */
|
||||
|
||||
/* The stack size of the drawing thread.
|
||||
* NOTE: If FreeType or ThorVG is enabled, it is recommended to set it to 32KB or more.
|
||||
*/
|
||||
-#define LV_DRAW_THREAD_STACK_SIZE (8 * 1024) /* [bytes] */
|
||||
+#define LV_DRAW_THREAD_STACK_SIZE (32 * 1024) /* [bytes] */
|
||||
|
||||
#define LV_USE_DRAW_SW 1
|
||||
#if LV_USE_DRAW_SW == 1
|
||||
@@ -147,7 +147,7 @@
|
||||
/* Set the number of draw unit.
|
||||
* > 1 requires an operating system enabled in `LV_USE_OS`
|
||||
* > 1 means multiple threads will render the screen in parallel */
|
||||
- #define LV_DRAW_SW_DRAW_UNIT_CNT 1
|
||||
+ #define LV_DRAW_SW_DRAW_UNIT_CNT 2
|
||||
|
||||
/* Use Arm-2D to accelerate the sw render */
|
||||
#define LV_USE_DRAW_ARM2D_SYNC 0
|
||||
@@ -979,8 +979,8 @@
|
||||
#define LV_USE_LINUX_FBDEV 1
|
||||
#if LV_USE_LINUX_FBDEV
|
||||
#define LV_LINUX_FBDEV_BSD 0
|
||||
- #define LV_LINUX_FBDEV_RENDER_MODE LV_DISPLAY_RENDER_MODE_PARTIAL
|
||||
- #define LV_LINUX_FBDEV_BUFFER_COUNT 0
|
||||
+ #define LV_LINUX_FBDEV_RENDER_MODE LV_DISPLAY_RENDER_MODE_DIRECT
|
||||
+ #define LV_LINUX_FBDEV_BUFFER_COUNT 2
|
||||
#define LV_LINUX_FBDEV_BUFFER_SIZE 60
|
||||
#endif
|
||||
|
||||
@@ -1069,19 +1069,19 @@
|
||||
#define LV_USE_DEMO_WIDGETS 1
|
||||
|
||||
/* Demonstrate the usage of encoder and keyboard */
|
||||
-#define LV_USE_DEMO_KEYPAD_AND_ENCODER 1
|
||||
+#define LV_USE_DEMO_KEYPAD_AND_ENCODER 0
|
||||
|
||||
/* Benchmark your system */
|
||||
#define LV_USE_DEMO_BENCHMARK 1
|
||||
|
||||
/* Render test for each primitives. Requires at least 480x272 display */
|
||||
-#define LV_USE_DEMO_RENDER 1
|
||||
+#define LV_USE_DEMO_RENDER 0
|
||||
|
||||
/* Stress test for LVGL */
|
||||
-#define LV_USE_DEMO_STRESS 1
|
||||
+#define LV_USE_DEMO_STRESS 0
|
||||
|
||||
/* Music player demo */
|
||||
-#define LV_USE_DEMO_MUSIC 1
|
||||
+#define LV_USE_DEMO_MUSIC 0
|
||||
#if LV_USE_DEMO_MUSIC
|
||||
#define LV_DEMO_MUSIC_SQUARE 0
|
||||
#define LV_DEMO_MUSIC_LANDSCAPE 0
|
||||
@@ -1091,16 +1091,16 @@
|
||||
#endif
|
||||
|
||||
/* Flex layout demo */
|
||||
-#define LV_USE_DEMO_FLEX_LAYOUT 1
|
||||
+#define LV_USE_DEMO_FLEX_LAYOUT 0
|
||||
|
||||
/* Smart-phone like multi-language demo */
|
||||
-#define LV_USE_DEMO_MULTILANG 1
|
||||
+#define LV_USE_DEMO_MULTILANG 0
|
||||
|
||||
/* Widget transformation demo */
|
||||
-#define LV_USE_DEMO_TRANSFORM 1
|
||||
+#define LV_USE_DEMO_TRANSFORM 0
|
||||
|
||||
/* Demonstrate scroll settings */
|
||||
-#define LV_USE_DEMO_SCROLL 1
|
||||
+#define LV_USE_DEMO_SCROLL 0
|
||||
|
||||
/* Vector graphic demo */
|
||||
#define LV_USE_DEMO_VECTOR_GRAPHIC 0
|
||||
--
|
||||
2.34.1
|
||||
|
||||
|
||||
Patch 2
|
||||
-------
|
||||
|
||||
Create the first patch file
|
||||
|
||||
.. code-block::
|
||||
|
||||
touch 0002-adapt-CMakeLists-file-to-compile-and-link-fbdev.patch
|
||||
|
||||
Content of ``0002-adapt-CMakeLists-file-to-compile-and-link-fbdev.patch``
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
From ad464e0683aced74085fb89895b8d040ecad0206 Mon Sep 17 00:00:00 2001
|
||||
From: Gabriel Catel Torres <gabriel.catel@edgemtech.ch>
|
||||
Date: Tue, 1 Oct 2024 10:31:29 +0200
|
||||
Subject: [PATCH] adapt CMakeLists file to compile and link only for fbdev
|
||||
|
||||
---
|
||||
CMakeLists.txt | 17 +++++------------
|
||||
1 file changed, 5 insertions(+), 12 deletions(-)
|
||||
|
||||
diff --git a/CMakeLists.txt b/CMakeLists.txt
|
||||
index 658193f..ad56cc2 100644
|
||||
--- a/CMakeLists.txt
|
||||
+++ b/CMakeLists.txt
|
||||
@@ -1,8 +1,8 @@
|
||||
cmake_minimum_required(VERSION 3.10)
|
||||
project(lvgl)
|
||||
|
||||
-set(CMAKE_C_STANDARD 99)#C99 # lvgl officially support C99 and above
|
||||
-set(CMAKE_CXX_STANDARD 17)#C17
|
||||
+set(CMAKE_C_STANDARD 99)
|
||||
+set(CMAKE_CXX_STANDARD 17)
|
||||
set(CMAKE_CXX_STANDARD_REQUIRED ON)
|
||||
|
||||
set(EXECUTABLE_OUTPUT_PATH ${PROJECT_SOURCE_DIR}/bin)
|
||||
@@ -10,15 +10,8 @@ set(EXECUTABLE_OUTPUT_PATH ${PROJECT_SOURCE_DIR}/bin)
|
||||
add_subdirectory(lvgl)
|
||||
target_include_directories(lvgl PUBLIC ${PROJECT_SOURCE_DIR})
|
||||
|
||||
-add_executable(main main.c mouse_cursor_icon.c)
|
||||
+add_executable(lvglbenchmark main.c mouse_cursor_icon.c)
|
||||
|
||||
-include(${CMAKE_CURRENT_LIST_DIR}/lvgl/tests/FindLibDRM.cmake)
|
||||
-include_directories(${Libdrm_INCLUDE_DIRS})
|
||||
-
|
||||
-find_package(SDL2)
|
||||
-find_package(SDL2_image)
|
||||
-include_directories(${SDL2_INCLUDE_DIRS} ${SDL2_IMAGE_INCLUDE_DIRS})
|
||||
-
|
||||
-target_link_libraries(main lvgl lvgl::examples lvgl::demos lvgl::thorvg ${SDL2_LIBRARIES} ${SDL2_IMAGE_LIBRARIES} ${Libdrm_LIBRARIES} m pthread)
|
||||
-add_custom_target (run COMMAND ${EXECUTABLE_OUTPUT_PATH}/main DEPENDS main)
|
||||
+target_link_libraries(lvglbenchmark lvgl lvgl::examples lvgl::demos lvgl::thorvg m pthread)
|
||||
+add_custom_target (run COMMAND ${EXECUTABLE_OUTPUT_PATH}/lvglbenchmark DEPENDS main)
|
||||
|
||||
--
|
||||
2.34.1
|
||||
|
||||
Build the recipe
|
||||
================
|
||||
|
||||
You should now be able to see the recipe listing the existing recipes
|
||||
|
||||
.. code-block::
|
||||
|
||||
bitbake-layers show-recipes | grep lvglbenchmarkfbdev
|
||||
|
||||
Now add the recipe to the project. Modify ``build/conf/local.conf`` file adding
|
||||
this line
|
||||
|
||||
.. code-block::
|
||||
|
||||
IMAGE_INSTALL:append = " lvglbenchmarkfbdev"
|
||||
|
||||
Now build the image
|
||||
|
||||
.. code-block::
|
||||
|
||||
bitbake core-image-base
|
||||
|
||||
Run this command to ensure the binary was generated and was installed in the
|
||||
rootfs
|
||||
|
||||
.. code-block::
|
||||
|
||||
# Run this command in build/tmp folder
|
||||
find . -wholename "*bin/lvglbench*"
|
||||
196
docs/details/integration/os/yocto/terms_and_variables.rst
Normal file
196
docs/details/integration/os/yocto/terms_and_variables.rst
Normal file
@@ -0,0 +1,196 @@
|
||||
.. _yocto_project_terms:
|
||||
|
||||
===================
|
||||
Yocto Project Terms
|
||||
===================
|
||||
|
||||
Getting started in Yocto can be overwheming. There are many terms used that are
|
||||
specific to Yocto and Bitbake environment.
|
||||
|
||||
A list of terms and definitions users new to the Yocto Project
|
||||
development environment might find helpful can be found `here <https://docs.
|
||||
yoctoproject.org/ref-manual/terms.html>`_.
|
||||
|
||||
|
||||
Yocto Variables Glossary
|
||||
************************
|
||||
|
||||
This chapter lists basic variables used in the LVGL Yocto guide and gives an
|
||||
overview of their function and contents.
|
||||
|
||||
A More complete variable glossary can be found in `Yocto Variable Glossary
|
||||
<https://docs.yoctoproject.org/ref-manual/variables.html>`_. This section
|
||||
covers a lot of variables used in the OpenEmbedded build system.
|
||||
|
||||
.. _S:
|
||||
|
||||
S
|
||||
-
|
||||
|
||||
The location in the Build Directory where unpacked recipe source code resides.
|
||||
By default, this directory is ${WORKDIR}/${BPN}-${PV}, where ${BPN} is the
|
||||
base recipe name and ${PV} is the recipe version. If the source tarball
|
||||
extracts the code to a directory named anything other than ${BPN}-${PV}, or if
|
||||
the source code is fetched from an SCM such as Git or Subversion, then you
|
||||
must set S in the recipe so that the OpenEmbedded build system knows where to
|
||||
find the unpacked source.
|
||||
|
||||
As an example, assume a Source Directory top-level folder named poky and a
|
||||
default Build Directory at poky/build. In this case, the work directory the
|
||||
build system uses to keep the unpacked recipe for db is the following:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
|
||||
|
||||
The unpacked source code resides in the db-5.1.19 folder.
|
||||
|
||||
This next example assumes a Git repository. By default, Git repositories are
|
||||
cloned to ${WORKDIR}/git during do_fetch. Since this path is different from the
|
||||
default value of S, you must set it specifically so the source can be located:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
SRC_URI = "git://path/to/repo.git;branch=main"
|
||||
S = "${WORKDIR}/git"
|
||||
|
||||
|
||||
.. _D:
|
||||
|
||||
D
|
||||
-
|
||||
|
||||
The destination directory. The location in the Build Directory where components
|
||||
are installed by the do_install task. This location defaults to:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
${WORKDIR}/image
|
||||
|
||||
.. note::
|
||||
|
||||
Tasks that read from or write to this directory should run under fakeroot.
|
||||
|
||||
.. _B:
|
||||
|
||||
B
|
||||
-
|
||||
|
||||
The directory within the Build Directory in which the OpenEmbedded build system
|
||||
places generated objects during a recipe's build process. By default, this
|
||||
directory is the same as the S directory, which is defined as:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
S = "${WORKDIR}/${BP}"
|
||||
|
||||
You can separate the (S) directory and the directory pointed to by the B
|
||||
variable. Most Autotools-based recipes support separating these directories.
|
||||
The build system defaults to using separate directories for gcc and some kernel
|
||||
recipes.
|
||||
|
||||
.. _WORKDIR:
|
||||
|
||||
WORKDIR
|
||||
-------
|
||||
|
||||
The pathname of the work directory in which the OpenEmbedded build system
|
||||
builds a recipe. This directory is located within the TMPDIR directory
|
||||
structure and is specific to the recipe being built and the system for which it
|
||||
is being built.
|
||||
|
||||
The WORKDIR directory is defined as follows:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
|
||||
|
||||
The actual directory depends on several things:
|
||||
|
||||
- **TMPDIR**: The top-level build output directory
|
||||
- **MULTIMACH_TARGET_SYS**: The target system identifier
|
||||
- **PN**: The recipe name
|
||||
- **EXTENDPE**: The epoch — if PE is not specified, which is usually the
|
||||
case for most recipes, then EXTENDPE is blank.
|
||||
- **PV**: The recipe version
|
||||
- **PR**: The recipe revision
|
||||
|
||||
As an example, assume a Source Directory top-level folder name poky, a default
|
||||
Build Directory at poky/build, and a qemux86-poky-linux machine target system.
|
||||
Furthermore, suppose your recipe is named foo_1.3.0-r0.bb. In this case, the
|
||||
work directory the build system uses to build the package would be as follows:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
|
||||
|
||||
.. _PN:
|
||||
|
||||
PN
|
||||
--
|
||||
|
||||
This variable can have two separate functions depending on the context: a
|
||||
recipe name or a resulting package name.
|
||||
|
||||
PN refers to a recipe name in the context of a file used by the OpenEmbedded
|
||||
build system as input to create a package. The name is normally extracted from
|
||||
the recipe file name. For example, if the recipe is named expat_2.0.1.bb, then
|
||||
the default value of PN will be “expat”.
|
||||
|
||||
The variable refers to a package name in the context of a file created or
|
||||
produced by the OpenEmbedded build system.
|
||||
|
||||
If applicable, the PN variable also contains any special suffix or prefix. For
|
||||
example, using bash to build packages for the native machine, PN is
|
||||
bash-native. Using bash to build packages for the target and for Multilib, PN
|
||||
would be bash and lib64-bash, respectively.
|
||||
|
||||
.. _PR:
|
||||
|
||||
PR
|
||||
--
|
||||
|
||||
The revision of the recipe. The default value for this variable is
|
||||
"r0". Subsequent revisions of the recipe conventionally have the
|
||||
values "r1", "r2", and so forth. When PV increases,
|
||||
PR is conventionally reset to "r0".
|
||||
|
||||
.. note::
|
||||
|
||||
The OpenEmbedded build system does not need the aid of PR to know when to
|
||||
rebuild a recipe. The build system uses the task input checksums along with
|
||||
the stamp and shared state cache mechanisms.
|
||||
|
||||
The PR variable primarily becomes significant when a package
|
||||
manager dynamically installs packages on an already built image. In
|
||||
this case, PR, which is the default value of
|
||||
PKGR, helps the package manager distinguish which
|
||||
package is the most recent one in cases where many packages have the
|
||||
same PV (i.e. PKGV). A component having many packages with
|
||||
the same PV usually means that the packages all install the same
|
||||
upstream version, but with later (PR) version packages including
|
||||
packaging fixes.
|
||||
|
||||
.. note::
|
||||
|
||||
PR does not need to be increased for changes that do not change the
|
||||
package contents or metadata.
|
||||
|
||||
Because manually managing PR can be cumbersome and error-prone,
|
||||
an automated solution exists. See the
|
||||
"`working with a pr service <https://docs.yoctoproject.org/dev-manual/packages.
|
||||
html#working-with-a-pr-service>`_" section in the Yocto Project Development
|
||||
Tasks Manual for more information.
|
||||
|
||||
.. _PV:
|
||||
|
||||
PV
|
||||
--
|
||||
|
||||
The version of the recipe. The version is normally extracted from the recipe
|
||||
filename. For example, if the recipe is named expat_2.0.1.bb, then the default
|
||||
value of PV will be “2.0.1”. PV is generally not overridden within a recipe
|
||||
unless it is building an unstable (i.e. development) version from a source code
|
||||
repository (e.g. Git or Subversion).
|
||||
|
||||
PV is the default value of the PKGV variable.
|
||||
194
docs/details/integration/os/zephyr.rst
Normal file
194
docs/details/integration/os/zephyr.rst
Normal file
@@ -0,0 +1,194 @@
|
||||
======
|
||||
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-block:: 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-block:: shell
|
||||
|
||||
$ west build -b native_posix samples/modules/lvgl/demos
|
||||
|
||||
To run the application on your host:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ west build -t run
|
||||
|
||||
In case you chose any of the other supported boards you can flash to the device with:
|
||||
|
||||
.. code-block:: 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-block:: 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-block:: 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>`__
|
||||
- `keypad input <https://docs.zephyrproject.org/latest/build/dts/api/bindings/input/zephyr,lvgl-keypad-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-block::
|
||||
|
||||
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-block:: 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-block::
|
||||
|
||||
# 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>`__.
|
||||
|
||||
Performance Tuning in LVGL
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To optimize LVGL's performance, several `kconfig` options can be configured:
|
||||
|
||||
- **CONFIG_LV_Z_VDB_SIZE**: Sets the rendering buffer size as a percentage of the display area, adjustable from 1% to 100%. Larger buffers can enhance performance, especially when used with **CONFIG_LV_Z_FULL_REFRESH**.
|
||||
|
||||
- **CONFIG_LV_Z_DOUBLE_VDB**: Enables the use of two rendering buffers, allowing for parallel rendering and data flushing, thus improving responsiveness and reducing latency.
|
||||
|
||||
- **CONFIG_LV_Z_VDB_ALIGN**: Ensures that the rendering buffer is properly aligned, which is critical for efficient memory access based on the color depth.
|
||||
|
||||
- **CONFIG_LV_Z_VBD_CUSTOM_SECTION**: Allows rendering buffers to be placed in a custom memory section (e.g., `.lvgl_buf`), useful for leveraging specific memory types like tightly coupled or external memory to enhance performance.
|
||||
|
||||
Zephyr ≤ 3.7.0 Specific Options
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For Zephyr versions 3.7.0 and below, additional options are available to manage LVGL's frame flushing:
|
||||
|
||||
- **CONFIG_LV_Z_FLUSH_THREAD**: Enables flushing LVGL frames in a separate thread, allowing the main thread to continue rendering the next frame simultaneously. This option can be disabled if the performance gain is not needed.
|
||||
|
||||
- **CONFIG_LV_Z_FLUSH_THREAD_STACK_SIZE**: Specifies the stack size for the flush thread, with a default of 1024 bytes.
|
||||
|
||||
- **CONFIG_LV_Z_FLUSH_THREAD_PRIO**: Sets the priority of the flush thread, with a default priority of 0, indicating cooperative priority.
|
||||
|
||||
For newer versions of Zephyr, the OSAL (Operating System Abstraction Layer) can be utilized, which takes care of the flushing.
|
||||
|
||||
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/>`__
|
||||
70
docs/details/integration/renderers/arm2d.rst
Normal file
70
docs/details/integration/renderers/arm2d.rst
Normal file
@@ -0,0 +1,70 @@
|
||||
.. _arm2d:
|
||||
|
||||
==========
|
||||
Arm-2D GPU
|
||||
==========
|
||||
|
||||
Arm-2D is not a GPU but **an abstraction layer for 2D GPUs dedicated to
|
||||
Microcontrollers**. It supports all Cortex-M processors ranging from
|
||||
Cortex-M0 to the latest Cortex-M85.
|
||||
|
||||
Arm-2D accelerates LVGL9 with two modes: **Synchronous Mode** and
|
||||
**Asynchronous Mode**.
|
||||
|
||||
- When **Helium** and **ACI (Arm Custom Instruction)** are available, it is recommend
|
||||
to use **Synchronous Mode** to accelerate LVGL.
|
||||
- When Arm-2D backed 2D-GPUs are available, for example, **DMAC-350 based 2D
|
||||
GPUs**, it is recommend to use **Asynchronous Mode** to accelerate LVGL.
|
||||
|
||||
Arm-2D is an open-source project on GitHub. For more, please refer to:
|
||||
https://github.com/ARM-software/Arm-2D.
|
||||
|
||||
|
||||
How to Use
|
||||
**********
|
||||
|
||||
In general:
|
||||
|
||||
- you can set the macro :c:macro:`LV_USE_DRAW_ARM2D_SYNC` to ``1`` and
|
||||
:c:macro:`LV_DRAW_SW_ASM` to ``LV_DRAW_SW_ASM_HELIUM`` in ``lv_conf.h`` to
|
||||
enable Arm-2D synchronous acceleration for LVGL.
|
||||
- You can set
|
||||
the macro :c:macro:`LV_USE_DRAW_ARM2D_ASYNC` to ``1`` in ``lv_conf.h`` to enable
|
||||
Arm-2D Asynchronous acceleration for LVGL.
|
||||
|
||||
If you are using
|
||||
`CMSIS-Pack <https://github.com/lvgl/lvgl/tree/master/env_support/cmsis-pack>`__
|
||||
to deploy the LVGL. You don't have to define the macro
|
||||
:c:macro:`LV_USE_DRAW_ARM2D_SYNC` manually, instead the lv_conf_cmsis.h will
|
||||
check the environment and set the :c:macro:`LV_USE_DRAW_ARM2D_SYNC` accordingly.
|
||||
|
||||
Design Considerations
|
||||
*********************
|
||||
|
||||
As mentioned before, Arm-2D is an abstraction layer for 2D GPU; hence if
|
||||
there is no accelerator or dedicated instruction set (such as Helium or
|
||||
ACI) available for Arm-2D, it provides negligible performance boost for
|
||||
LVGL (sometimes worse) for regular Cortex-M processors.
|
||||
|
||||
**We highly recommend you enable Arm-2D acceleration for LVGL** when:
|
||||
|
||||
- The target processors are **Cortex-M55**, **Cortex-M52** and **Cortex-M85**
|
||||
- The target processors support
|
||||
`Helium <https://developer.arm.com/documentation/102102/0103/?lang=en>`__.
|
||||
- The device vendor provides an arm-2d compliant driver for their
|
||||
proprietary 2D accelerators and/or ACI (Arm Customized Instruction).
|
||||
- The target device contains
|
||||
`DMAC-350 <https://community.arm.com/arm-community-blogs/b/internet-of-things-blog/posts/arm-corelink-dma-350-next-generation-direct-memory-access-for-endpoint-ai>`__
|
||||
|
||||
Examples
|
||||
********
|
||||
|
||||
- `A Cortex-M55 (supports Helium) based MDK Project, PC emulation is
|
||||
available. <https://github.com/lvgl/lv_port_an547_cm55_sim>`__
|
||||
|
||||
API
|
||||
***
|
||||
|
||||
:ref:`lv_draw_sw_arm2d_h`
|
||||
|
||||
:ref:`lv_blend_arm2d_h`
|
||||
14
docs/details/integration/renderers/index.rst
Normal file
14
docs/details/integration/renderers/index.rst
Normal file
@@ -0,0 +1,14 @@
|
||||
==================
|
||||
Renderers and GPUs
|
||||
==================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
sw
|
||||
arm2d
|
||||
nema_gfx
|
||||
nxp_pxp
|
||||
nxp_vglite
|
||||
sdl
|
||||
stm32_dma2d
|
||||
94
docs/details/integration/renderers/nema_gfx.rst
Normal file
94
docs/details/integration/renderers/nema_gfx.rst
Normal file
@@ -0,0 +1,94 @@
|
||||
.. _stm32_nema_gfx:
|
||||
|
||||
===================================
|
||||
NemaGFX Acceleration (AKA NeoChrom)
|
||||
===================================
|
||||
|
||||
Some of the more powerful STM32 MCUs such as the
|
||||
STM32U5 feature a 2.5D GPU which can natively draw most
|
||||
LVGL primitives.
|
||||
|
||||
Get Started with the Riverdi STM32U5 5-inch Display
|
||||
***************************************************
|
||||
|
||||
`lv_port_riverdi_stm32u5 <https://github.com/lvgl/lv_port_riverdi_stm32u5>`__
|
||||
is a ready-to-use port for the Riverdi STM32 5.0" Embedded Display
|
||||
(STM32U599NJH6Q or STM32U5A9NJH6Q) which has Nema enabled.
|
||||
Follow the instructions in the readme to get started.
|
||||
|
||||
Usage and Configuration
|
||||
***********************
|
||||
|
||||
Enable the renderer by setting :c:macro:`LV_USE_NEMA_GFX` to ``1`` in
|
||||
lv_conf.h. If using :c:macro:`LV_USE_NEMA_VG`,
|
||||
set :c:macro:`LV_NEMA_GFX_MAX_RESX` and :c:macro:`LV_NEMA_GFX_MAX_RESY`
|
||||
to the size of the display you will be using so that enough static
|
||||
memory will be reserved for VG. Without VG, more task types will be
|
||||
performed by the software renderer.
|
||||
|
||||
"libs/nema_gfx" contains pre-compiled binaries for the Nema GPU
|
||||
drivers. In `lv_port_riverdi_stm32u5 <https://github.com/lvgl/lv_port_riverdi_stm32u5>`__
|
||||
the project is already configured to link the binaries when building.
|
||||
With a different STM32CubeIDE project, you can configure the libraries to be linked
|
||||
by right-clicking the project in the "Project Explorer" sidebar, clicking
|
||||
"Properties", navigating to "C/C++ Build", "Settings", "MCU G++ Linker", and then
|
||||
"Libraries". Add an entry under "Libraries (-l)" that is "nemagfx-float-abi-hard".
|
||||
Add an entry under "Library search path (-L)" which is a path to
|
||||
"libs/nema_gfx/lib/core/cortex_m33/gcc" e.g.
|
||||
"${workspace_loc:/${ProjName}/Middlewares/LVGL/lvgl/libs/nema_gfx/lib/core/cortex_m33/gcc}".
|
||||
You will also want to add the "libs/nema_gfx/include" directory to your include
|
||||
search paths. Under "MCU GCC Compiler", "Include paths", add an entry to "Include paths (-I)"
|
||||
which is a path to "libs/nema_gfx/include" e.g.
|
||||
"${workspace_loc:/${ProjName}/Middlewares/LVGL/lvgl/libs/nema_gfx/include}".
|
||||
Click "Apply and Close".
|
||||
|
||||
32 and 16 bit :c:macro:`LV_COLOR_DEPTH` is supported.
|
||||
|
||||
At the time of writing, :c:macro:`LV_USE_OS` support is experimental
|
||||
and not yet working in
|
||||
`lv_port_riverdi_stm32u5 <https://github.com/lvgl/lv_port_riverdi_stm32u5>`__
|
||||
|
||||
"src/draw/nema_gfx/lv_draw_nema_gfx_hal.c" implements the HAL functionality
|
||||
required by Nema to allocate memory and lock resources (in this implementation,
|
||||
no locking is done). It may conflict with existing definitions
|
||||
if you have an existing Nema HAL implementation. You may
|
||||
simply be able to remove yours.
|
||||
|
||||
TSC Images
|
||||
**********
|
||||
|
||||
TSC (ThinkSillicon Compression) images can be drawn by this renderer. The
|
||||
TSC 4/6/6A/12/12A color formats are part of :cpp:type:`lv_color_format_t`.
|
||||
All other renderers will ignore images with these color formats.
|
||||
Define an image descriptor variable with the corresponding
|
||||
TSC color format and the GPU will be able to draw it directly.
|
||||
Stride does not need to be specified because it will be computed by the
|
||||
renderer.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
const lv_image_dsc_t img_demo_widgets_avatar_tsc6a = {
|
||||
.header.cf = LV_COLOR_FORMAT_NEMA_TSC6A,
|
||||
.header.w = 144,
|
||||
.header.h = 144,
|
||||
.data = img_demo_widgets_avatar_tsc6a_map,
|
||||
.data_size = sizeof(img_demo_widgets_avatar_tsc6a_map),
|
||||
};
|
||||
|
||||
DMA2D
|
||||
*****
|
||||
|
||||
The Nema renderer uses DMA2D to flush in parallel with rendering in
|
||||
`lv_port_riverdi_stm32u5 <https://github.com/lvgl/lv_port_riverdi_stm32u5>`__.
|
||||
|
||||
If your STM does not have the Nema GPU, it may still support
|
||||
DMA2D. DMA2D is a simple peripheral which can draw fills
|
||||
and images independently of the CPU.
|
||||
See the LVGL :ref:`DMA2D support <dma2d>`.
|
||||
|
||||
API
|
||||
***
|
||||
|
||||
:ref:`lv_draw_nema_gfx_h`
|
||||
|
||||
:ref:`lv_draw_nema_gfx_utils_h`
|
||||
15
docs/details/integration/renderers/nxp_pxp.rst
Normal file
15
docs/details/integration/renderers/nxp_pxp.rst
Normal file
@@ -0,0 +1,15 @@
|
||||
===========
|
||||
NXP PXP GPU
|
||||
===========
|
||||
|
||||
API
|
||||
***
|
||||
|
||||
:ref:`lv_draw_pxp_h`
|
||||
|
||||
:ref:`lv_pxp_cfg_h`
|
||||
|
||||
:ref:`lv_pxp_osa_h`
|
||||
|
||||
:ref:`lv_pxp_utils_h`
|
||||
|
||||
86
docs/details/integration/renderers/nxp_vglite.rst
Normal file
86
docs/details/integration/renderers/nxp_vglite.rst
Normal file
@@ -0,0 +1,86 @@
|
||||
.. _vglite:
|
||||
|
||||
===============
|
||||
NXP VG-Lite GPU
|
||||
===============
|
||||
|
||||
This is a generic VG-Lite rendering backend implementation that is designed to utilize
|
||||
`VeriSilicon <https://verisilicon.com/>`_'s generic API to operate GPU hardware as much as possible.
|
||||
|
||||
Even with different chip manufacturers, as long as they use the same version of VG-Lite API as the rendering backend,
|
||||
LVGL rendering acceleration can be supported without the need for LVGL adaptation work.
|
||||
|
||||
|
||||
Configuration
|
||||
*************
|
||||
|
||||
1. Set :c:macro:`LV_USE_DRAW_VG_LITE` to 1 in ``lv_conf.h`` to enabled the VG-Lite rendering backend.
|
||||
Make sure that your hardware has been adapted to the VG-Lite API and that the absolute path to ``vg_lite.h``, which can be directly referenced by lvgl, has been exposed.
|
||||
|
||||
2. Confirm the GPU initialization method, there are two ways:
|
||||
|
||||
- The SDK calls the GPU initialization function on its own during system startup, and the GPU is available when LVGL starts; set :c:macro:`LV_VG_LITE_USE_GPU_INIT` to 0.
|
||||
- LVGL actively calls the GPU initialization function, and the SDK needs to implement the public function `gpu_init()`.
|
||||
LVGL will call it to complete the GPU hardware initialization during startup; set :c:macro:`LV_VG_LITE_USE_GPU_INIT` to 1.
|
||||
|
||||
3. Set the :c:macro:`LV_VG_LITE_USE_ASSERT` configuration to enable GPU call parameter checking.
|
||||
Due to the complexity of the parameters used in GPU calls, incorrect parameters can result in abnormal GPU hardware operation, such as forgetting to add an end symbol
|
||||
to the path or not meeting the alignment requirements for buffer stride.
|
||||
To quickly resolve such issues, strict parameter checking has been added before each VG-Lite call, including buffer stride validation and matrix invertibility check.
|
||||
When an error parameter is detected, an assertion will occur to print out the error parameter, allowing the user to promptly make corrections and reduce the time wasted on hardware simulation.
|
||||
Please note that enabling this check will decrease runtime performance. It is recommended to enable it in Debug mode and disable it in the Release version.
|
||||
|
||||
4. Set the :c:macro:`LV_VG_LITE_FLUSH_MAX_COUNT` configuration to specify the flush method.
|
||||
VG-Lite uses two sets of command buffer buffers to render instructions, and utilizing this mechanism well can greatly improve drawing efficiency.
|
||||
Currently, two buffering methods are supported:
|
||||
|
||||
- Set :c:macro:`LV_VG_LITE_FLUSH_MAX_COUNT` to zero (recommended). The rendering backend will obtain the GPU's working status every time it writes rendering instructions to the command buffer.
|
||||
|
||||
When the GPU is idle, it will immediately call ``vg_lite_flush`` to notify the GPU to start rendering and swap the command buffer. When the GPU is busy, it will continue to fill the command buffer cache with rendering instructions.
|
||||
The underlying driver will automatically determine if the command buffer has been filled. When it is about to be filled, it will forcibly wait for the unfinished drawing tasks to end and swap the command buffer.
|
||||
This method can effectively improve GPU utilization, especially in scenarios where rendering text, as the GPU's drawing time and the CPU's data preparation time are very close, allowing the CPU and GPU to run in parallel.
|
||||
|
||||
- Set :c:macro:`LV_VG_LITE_FLUSH_MAX_COUNT` to a value greater than zero, such as 8. After writing 8 rendering instructions to the command buffer, the rendering backend
|
||||
|
||||
will call ``vg_lite_flush`` to notify the GPU to start rendering and swap the command buffer.
|
||||
|
||||
5. Set the :c:macro:`LV_VG_LITE_USE_BOX_SHADOW` configuration to use GPU rendering for shadows.
|
||||
In fact, GPU hardware does not actually support shadow rendering. However, through experimentation, it has been found that a similar shadow effect
|
||||
can be achieved by using multiple layers of borders with different levels of transparency.
|
||||
It is recommended to enable this configuration in scenarios where the shadow quality requirements are not high, as it can significantly improve rendering efficiency.
|
||||
|
||||
6. Set the :c:macro:`LV_VG_LITE_GRAD_CACHE_CNT` configuration to specify the number of gradient cache entries.
|
||||
Gradient drawing includes linear gradients and radial gradients. Using a cache can effectively reduce the number of times the gradient image is created and improve drawing efficiency.
|
||||
Each individual gradient consumes around 4K of GPU memory pool. If there are many gradients used in the interface, you can try increasing the number of gradient cache entries.
|
||||
If the VG-Lite API returns the :c:macro:`VG_LITE_OUT_OF_RESOURCES` error, you can try increasing the size of the GPU memory pool or reducing the number of gradient cache entries.
|
||||
|
||||
7. Set the :c:macro:`LV_VG_LITE_STROKE_CACHE_CNT` configuration to specify the number of stroke path caches.
|
||||
When the stroke parameters do not change, the previously generated stroke parameters are automatically retrieved from the cache to improve rendering performance.
|
||||
The memory occupied by the stroke is strongly related to the path length. If the VG-Lite API returns the :c:macro:`VG_LITE_OUT_OF_RESOURCES` error,
|
||||
you can try increasing the size of the GPU memory pool or reducing the number of stroke cache entries.
|
||||
|
||||
NOTE: VG-Lite rendering backend does not support multi-threaded calls, please make sure :c:macro:`LV_USE_OS` is always configured as :c:macro:`LV_OS_NONE`.
|
||||
|
||||
|
||||
VG-Lite Simulator
|
||||
*****************
|
||||
|
||||
LVGL integrates a VG-Lite simulator based on ThorVG.
|
||||
Its purpose is to simplify the debugging of VG-Lite adaptation and reduce the time of debugging and locating problems on hardware devices.
|
||||
For detailed instructions, see :ref:`vg_lite_tvg`.
|
||||
|
||||
|
||||
API
|
||||
***
|
||||
|
||||
:ref:`lv_draw_vglite_h`
|
||||
|
||||
:ref:`lv_vglite_buf_h`
|
||||
|
||||
:ref:`lv_vglite_matrix_h`
|
||||
|
||||
:ref:`lv_vglite_path_h`
|
||||
|
||||
:ref:`lv_vglite_utils_h`
|
||||
|
||||
|
||||
9
docs/details/integration/renderers/sdl.rst
Normal file
9
docs/details/integration/renderers/sdl.rst
Normal file
@@ -0,0 +1,9 @@
|
||||
============
|
||||
SDL Renderer
|
||||
============
|
||||
|
||||
API
|
||||
***
|
||||
|
||||
:ref:`lv_draw_sdl_h`
|
||||
|
||||
9
docs/details/integration/renderers/stm32_dma2d.rst
Normal file
9
docs/details/integration/renderers/stm32_dma2d.rst
Normal file
@@ -0,0 +1,9 @@
|
||||
===============
|
||||
STM32 DMA2D GPU
|
||||
===============
|
||||
|
||||
API
|
||||
***
|
||||
|
||||
:ref:`lv_draw_dma2d_h`
|
||||
|
||||
12
docs/details/integration/renderers/sw.rst
Normal file
12
docs/details/integration/renderers/sw.rst
Normal file
@@ -0,0 +1,12 @@
|
||||
=================
|
||||
Software Renderer
|
||||
=================
|
||||
|
||||
API
|
||||
***
|
||||
|
||||
:ref:`lv_draw_sw_h`
|
||||
|
||||
:ref:`lv_draw_sw_blend_h`
|
||||
|
||||
:ref:`lv_draw_sw_gradient_h`
|
||||
Reference in New Issue
Block a user