diff --git a/.github/workflows/compile_docs.yml b/.github/workflows/compile_docs.yml index 7828397802..5c396b556c 100644 --- a/.github/workflows/compile_docs.yml +++ b/.github/workflows/compile_docs.yml @@ -1,4 +1,4 @@ -name: Build Docs +name: Build Docs on: workflow_dispatch: # allow manual triggering @@ -23,6 +23,7 @@ on: - 'lv_version.h' - 'lvgl.h' - '.github/workflows/compile_docs.yml' + - 'include/**' push: branches: - master @@ -39,6 +40,7 @@ on: - 'lv_version.h' - 'lvgl.h' - '.github/workflows/compile_docs.yml' + - 'include/**' # https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#concurrency # Ensure that only one commit will be running tests at a time on each PR @@ -96,27 +98,28 @@ jobs: doxygen # Tool used to convert Doxygen XML to .mdx API pages - - name: Install doxymark + - name: Install doxymark run: | - npm install github:mutahharmkhan/doxymark#multi-root-prefix + npm install github:mutahharmkhan/doxymark#lvgl - # Generate Documentation API pages + # Generate Documentation API pages - name: Generate API pages run: | npx doxymark \ --input docs/doxygen/xml \ - --output docs/src \ - --index docs/src/api-index.json \ + --output docs/src/api \ + --index docs/src/api/api-index.json \ --preset fumadocs \ --auto-group \ - --root api=./include/lvgl \ - --root api-private=./src \ - --source-url-for api=https://github.com/lvgl/lvgl/tree/${{ github.sha }}/include/lvgl \ - --source-url-for api-private=https://github.com/lvgl/lvgl/tree/${{ github.sha }}/src \ - --root-title api=API \ - --root-title 'api-private=API Private' \ - --drop-empty-files - rm -rf docs/doxygen + --root public=./include/lvgl \ + --root private=./src \ + --source-url-for public=https://github.com/lvgl/lvgl/tree/${{ github.sha }}/include/lvgl \ + --source-url-for private=https://github.com/lvgl/lvgl/tree/${{ github.sha }}/src \ + --root-title 'public=Public API' \ + --root-title 'private=Private API' \ + --drop-empty-files \ + --url-prefix api + rm -rf docs/doxygen - name: Install Example Documentation run: npm i @lvgl/examples-generator diff --git a/docs/src/api/meta.json b/docs/src/api/meta.json new file mode 100644 index 0000000000..924491e451 --- /dev/null +++ b/docs/src/api/meta.json @@ -0,0 +1,7 @@ +{ + "pages": [ + "public", + "private", + "deprecated" + ] +} diff --git a/docs/src/CHANGELOG.mdx b/docs/src/changelog/CHANGELOG.mdx similarity index 100% rename from docs/src/CHANGELOG.mdx rename to docs/src/changelog/CHANGELOG.mdx diff --git a/docs/src/changelog/meta.json b/docs/src/changelog/meta.json new file mode 100644 index 0000000000..dc9ad71d4c --- /dev/null +++ b/docs/src/changelog/meta.json @@ -0,0 +1,6 @@ +{ + "pages": [ + "CHANGELOG", + "migration-v10" + ] +} diff --git a/docs/src/migration-v10.mdx b/docs/src/changelog/migration-v10.mdx similarity index 100% rename from docs/src/migration-v10.mdx rename to docs/src/changelog/migration-v10.mdx diff --git a/docs/src/getting_started/examples.mdx b/docs/src/getting_started/examples.mdx index 4f593ea218..37cc0a94e9 100644 --- a/docs/src/getting_started/examples.mdx +++ b/docs/src/getting_started/examples.mdx @@ -5,7 +5,7 @@ description: Below are several basic examples. They include the application code Below are several basic examples. They include the application code that produces the Widget Tree needed to make LVGL render the examples shown. Each example assumes -LVGL has undergone normal initialization, meaning that a `lv_display_t` object +LVGL has undergone normal initialization, meaning that a object was created and therefore has an [Active Screen](/common-widget-features/screens). ### A very simple *hello world* label diff --git a/docs/src/getting_started/index.mdx b/docs/src/getting_started/index.mdx index a794d23ce6..999aa073e6 100644 --- a/docs/src/getting_started/index.mdx +++ b/docs/src/getting_started/index.mdx @@ -2,5 +2,25 @@ title: Getting started --- +LVGL (Light and Versatile Graphics Library) is a free and open-source graphics +library providing everything you need to create an embedded GUI with easy-to-use +mobile-phone-like graphical elements, beautiful visual effects, and a low memory +footprint. + +You can think of LVGL as a collection of C and H files that can be dropped into +any project to add UI capabilities to the product. + +With the help of consistent and easy-to-learn API functions you can create [widgets](/widgets) +(buttons, sliders, charts, etc), style them, add events, layouts, or animations. + +Based on these settings LVGL will render an image (either by using its built-in +software rendering engine or a GPU) and will call a callback function to show +the rendered image on the display. This callback function is the main interface +between LVGL and the display. Most of the porting-related work is focused on +writing such a callback in an effective way. + +This chapter will show the basics to give an idea about how LVGL works and how it can be used. +For more details about each feature visit that feature's dedicated documentation page. + diff --git a/docs/src/getting_started/learn_the_basics.mdx b/docs/src/getting_started/learn_the_basics.mdx index e822c7542e..3f13a8cfb0 100644 --- a/docs/src/getting_started/learn_the_basics.mdx +++ b/docs/src/getting_started/learn_the_basics.mdx @@ -1,113 +1,25 @@ --- title: Learn the Basics -description: "LVGL (Light and Versatile Graphics Library) is a free and open-source graphics library providing everything you need to create an embedded GUI with easy-to-use mobile-phone-like graphical elements,..." +description: "Learn how to use LVGL in a few minutes" --- -## Overview -LVGL (Light and Versatile Graphics Library) is a free and open-source graphics -library providing everything you need to create an embedded GUI with easy-to-use -mobile-phone-like graphical elements, beautiful visual effects, and a low memory -footprint. +In LVGL you dynamically create and delete screens and widgets to build up your UI. Styles, animations, event handlers, and data bindings +can also be added to make the UI look better and connect it easily to an application. -You can think of LVGL as a collection of C and H files that can be dropped into -any project to add UI capabilities to the product. -With the help of consistent and easy-to-learn API functions you can create widgets -(buttons, sliders, charts, etc), style them, add events, layouts, or animations. +## Display -Based on these settings LVGL will render an image (either by using its built-in -software rendering engine or a GPU) and will call a callback function to show -the rendered image on the display. This callback function is the main interface -between LVGL and the display. Most of the porting-related work is focused on -writing such a callback in an effective way. - -This chapter will show the basics to give an idea about how LVGL works and how it can be used. -For more details about each feature visit that feature's dedicated documentation page. - -### LVGL Integration Overview - -The following is an overview of how to integrate LVGL into your project. Complete -details are available at [Overview](/integration/overview). - -| Field | Description | -|-------|-------------| -| `Driver Initialization` | It is the user's responsibility to set up the clock, timers, peripherals, etc. | -| `Call lv_init()` | Initialize LVGL itself. | -| `Create display and input devices` | Create display(s) () and input device(s) () and set up their callbacks. | -| `Create the UI` | Call LVGL functions to create screens, widgets, styles, animations, events, etc. | -| `Call lv_timer_handler() in a loop` | This handles all the LVGL-related tasks: - refresh display(s), - read input devices, - fire events based on user input (and other things), - run any animations, and - run user-created timers. | - -##### Example - -This is just a brief example of how to add LVGL to a new project. For more details -check out [Integration Overview](/integration/overview). - -```c -void main(void) -{ - your_driver_init(); - - lv_init(); - - lv_tick_set_cb(my_get_millis); - - lv_display_t * display = lv_display_create(320, 240); - - /* LVGL will render to this 1/10 screen sized buffer for 2 bytes/pixel */ - static uint8_t buf[320 * 240 / 10 * 2]; - lv_display_set_buffers(display, buf, NULL, LV_DISPLAY_RENDER_MODE_PARTIAL); - - /* This callback will display the rendered image */ - lv_display_set_flush_cb(display, my_flush_cb); - - /* Create widgets */ - lv_obj_t * label = lv_label_create(lv_screen_active()); - lv_label_set_text(label, "Hello LVGL!"); - - /* Make LVGL periodically execute its tasks */ - while(1) { - /* Provide updates to currently-displayed Widgets here. */ - lv_timer_handler(); - my_sleep(5); /*Wait 5 milliseconds before processing LVGL timer again*/ - } -} - -/* Return the elapsed milliseconds since startup. - * It needs to be implemented by the user */ -uint32_t my_get_millis(void) -{ - return my_tick_ms; -} - -/* Copy rendered image to screen. - * This needs to be implemented by the user. */ -void my_flush_cb(lv_display_t * disp, const lv_area_t * area, uint8_t * px_buf) -{ - /* Show the rendered image on the display */ - my_display_update(area, px_buf); - - /* Indicate that the buffer is available. - * If DMA were used, call in the DMA complete interrupt. */ - lv_display_flush_ready(); -} -``` - -## Displays - -*Display* refers to the actual hardware. In order to connect LVGL to the hardware an +A *Display* refers to the actual hardware. In order to connect LVGL to the hardware an object needs to be created and initialized. -LVGL has built-in support for many built-in drivers (see [Integration](/integration)), but it's easy to initialize a -display from scratch as well (as shown above). +See the [Quick porting guide](/getting_started/porting). -LVGL also handles multiple displays at once. +## Screen -## Screens - -A *Screen* is an LVGL widget created on a *Display*. It's a logical container for other widgets. A display can -have multiple screens, but there is always one active screen, which can be retrieved by using . -It returns an `lv_obj_t *` pointer. See [Active Screen](/common-widget-features/screens) for more information. +Screens are LVGL widgets created on a *Display*. They are logical containers for other widgets. A display can +have multiple screens, but there is always a single active screen, which can be retrieved by using . +It returns an pointer. See [Active Screen](/common-widget-features/screens) for more information. The most common way to create a screen is by creating a [Base widget](/widgets/base_widget) with a `NULL` parent. E.g. @@ -152,9 +64,9 @@ lv_obj_set_size(my_button1, lv_pct(100), LV_SIZE_CONTENT); lv_obj_align(my_button1, LV_ALIGN_RIGHT_MID, -20, 0); lv_obj_t * my_label1 = lv_label_create(my_button1); -lv_label_set_text_fmt(my_label1, "Click me!"); -lv_obj_set_style_text_color(my_label1, lv_color_hex(0xff0000), 0); +lv_label_set_text(my_label1, "Click me!"); /* Make the text red */ +lv_obj_set_style_text_color(my_label1, lv_color_hex(0xff0000), 0); ``` To see the full API for any widget, see its documentation at [All Widgets](/widgets), or check @@ -207,10 +119,10 @@ has only one part called . However, a [Slider (lv_slider)](/widgets/slider) has , and . -By using parts you can apply different [styles](/getting_started/learn_the_basics) to the parts +By using [parts](/common-widget-features/parts_and_states) you can apply different [styles](/common-widget-features/styles) to the different parts of a widget. -Read the Widget's documentation to learn which parts it uses. +Read the specific Widget's documentation to learn which parts it uses. ### States @@ -250,7 +162,7 @@ lv_obj_remove_state(widget, LV_STATE_...); Styles are carried in objects. They contain properties such as background color, border width, font, etc. -The styles can be added to a widget's given [Part](/getting_started/learn_the_basics) and [State](/getting_started/learn_the_basics). +The styles can be added to a widget's given [Part](/common-widget-features/parts_and_states) and [State](/common-widget-features/parts_and_states). Only their pointer is saved in the Widgets so they need to be defined as static or global variables. Before using a style it needs to be initialized with . @@ -287,8 +199,7 @@ font is specified on the widget or one of its parents. ### Local styles -Local style properties also can be added to Widgets. This creates a -style which resides inside the Widget and is used only by that Widget: +Local style properties can also be added to Widgets. The local style properties affect only the targeted widget. ```c lv_obj_set_style_bg_color(slider1, lv_color_hex(0x2080bb), LV_PART_INDICATOR | LV_STATE_PRESSED); @@ -296,9 +207,9 @@ lv_obj_set_style_bg_color(slider1, lv_color_hex(0x2080bb), LV_PART_INDICATOR | L See [Styles](/common-widget-features/styles) for full details. -## Subjects and Observers +## Data bindings -Subjects and Observers are powerful tools to easily create data bindings. +To realize data bindings, LVGL uses the Subject/Observer pattern. Subjects are global variables that store integer, color, string, etc. values. @@ -311,7 +222,7 @@ For some widgets, helper functions make it simple to connect them to subjects. E , . In general, using subjects and observers is a way to connect various parts of the UI and make them dynamically -react to application data changes—or allow the application to react to UI changes. +react to application data changes, or allow the application to react to UI changes. ```c static void label_observer_cb(lv_observer_t * observer, lv_subject_t * subject) diff --git a/docs/src/getting_started/meta.json b/docs/src/getting_started/meta.json index 9a32c56e5e..04541ce0c8 100644 --- a/docs/src/getting_started/meta.json +++ b/docs/src/getting_started/meta.json @@ -1,6 +1,7 @@ { "title": "Getting started", "pages": [ + "porting", "learn_the_basics", "examples", "whats_next" diff --git a/docs/src/getting_started/porting.mdx b/docs/src/getting_started/porting.mdx new file mode 100644 index 0000000000..5628f67b30 --- /dev/null +++ b/docs/src/getting_started/porting.mdx @@ -0,0 +1,89 @@ +--- +title: Porting overview +description: "Learn the basics about how to port LVGL to any hardware" +--- + + + +## Quick start + +The following is an overview of how to integrate LVGL into your project. +A more detailed description is available at [Overview](/integration/overview). + + +The main steps are the following: +1. **Driver Initialization**: It is the user's responsibility to set up the clock, timers, peripherals, etc. +2. **Call **: Initialize LVGL itself. +3. **Create display and input devices and set up the tick**: Create display(s) () and input device(s) () and set up their callbacks. +4. **Create the UI**: Call LVGL functions to create screens, widgets, styles, animations, events, etc. +5. **Call in a loop**: This handles all the LVGL-related tasks, such as refreshing display(s), reading input devices, firing events based on user input, running animations, and running user-created timers. + +This is just a brief example of how to add LVGL to a new project. + +```c +void main(void) +{ + your_driver_init(); + + lv_init(); + + lv_tick_set_cb(my_get_millis); + + lv_display_t * display = lv_display_create(320, 240); + + /* LVGL will render to this 1/10 screen sized buffer for 2 bytes/pixel */ + static uint8_t buf[320 * 240 / 10 * 2]; + lv_display_set_buffers(display, buf, NULL, sizeof(buf), LV_DISPLAY_RENDER_MODE_PARTIAL); + + /* This callback will display the rendered image */ + lv_display_set_flush_cb(display, my_flush_cb); + + /* Create widgets */ + lv_obj_t * label = lv_label_create(lv_screen_active()); + lv_label_set_text(label, "Hello LVGL!"); + + /* Make LVGL periodically execute its tasks */ + while(1) { + /* Provide updates to currently-displayed Widgets here. */ + lv_timer_handler(); + my_sleep(5); /*Wait 5 milliseconds before processing LVGL timer again*/ + } +} + +/* Return the elapsed milliseconds since startup. + * It needs to be implemented by the user */ +uint32_t my_get_millis(void) +{ + return my_tick_ms; +} + +/* Copy rendered image to screen. + * This needs to be implemented by the user. */ +void my_flush_cb(lv_display_t * disp, const lv_area_t * area, uint8_t * px_buf) +{ + /* Show the rendered image on the display */ + my_display_update(area, px_buf); + + /* Indicate that the buffer is available. + * If DMA were used, call in the DMA complete interrupt. */ + lv_display_flush_ready(disp); +} +``` + +## Drivers + +### Custom driver + +By writing a custom `flush_cb` for your display and `read_cb` for the input devices you can easily create +your own drivers. Learn more in the [Integration](/integration/overview#connecting-to-hardware) section. + + +## Built-in drivers + +LVGL comes with many built-in drivers for display controllers (like ILI9341, ST7789, etc.), Linux drivers (like Wayland, DRM, etc.), +(RT)OS support (FreeRTOS, NuttX, Linux, etc.), and GPUs (Dave2D, VG-Lite, OpenGL ES, etc.). + +These just need to be enabled in `lv_conf.h` to use them right away. Learn more about the built-in drivers in +the [Integration](/integration/overview#connecting-to-hardware) section. + + diff --git a/docs/src/getting_started/whats_next.mdx b/docs/src/getting_started/whats_next.mdx index c94d18322b..e444442872 100644 --- a/docs/src/getting_started/whats_next.mdx +++ b/docs/src/getting_started/whats_next.mdx @@ -1,9 +1,9 @@ --- title: "What's Next?" -description: There are several good ways ways to gain deeper knowledge of LVGL. +description: There are several good ways to gain deeper knowledge of LVGL. --- -There are several good ways ways to gain deeper knowledge of LVGL. Here is one +There are several good ways to gain deeper knowledge of LVGL. Here is one recommended order of documents to read and things to play with while you are advancing your knowledge: diff --git a/docs/src/guides/how-to-articles/index.mdx b/docs/src/guides/how-to-articles/index.mdx deleted file mode 100644 index 99bcf74cf2..0000000000 --- a/docs/src/guides/how-to-articles/index.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "How-To Articles" ---- - - diff --git a/docs/src/guides/index.mdx b/docs/src/guides/index.mdx deleted file mode 100644 index 9b762a3c99..0000000000 --- a/docs/src/guides/index.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Guides ---- - - - diff --git a/docs/src/guides/internal-subsystems/index.mdx b/docs/src/guides/internal-subsystems/index.mdx deleted file mode 100644 index 7bfe2c862c..0000000000 --- a/docs/src/guides/internal-subsystems/index.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Internal Subsystems ---- - - diff --git a/docs/src/guides/meta.json b/docs/src/guides/meta.json deleted file mode 100644 index 4c5c9d8e83..0000000000 --- a/docs/src/guides/meta.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "title": "Guides", - "pages": [ - "how-to-articles", - "internal-subsystems" - ] -} diff --git a/docs/src/integration/bindings/cpp.mdx b/docs/src/integration/bindings/cpp.mdx index 636c156b45..a617d1ab01 100644 --- a/docs/src/integration/bindings/cpp.mdx +++ b/docs/src/integration/bindings/cpp.mdx @@ -1,6 +1,6 @@ --- title: Cpp -description: "In progress: https://github." +description: "The C++ binding for LVGL is in progress. See https://github.com/lvgl/lv_binding_cpp." --- In progress: https://github.com/lvgl/lv_binding_cpp diff --git a/docs/src/integration/bindings/micropython.mdx b/docs/src/integration/bindings/micropython.mdx index 71e5b5cc6d..9a8e031252 100644 --- a/docs/src/integration/bindings/micropython.mdx +++ b/docs/src/integration/bindings/micropython.mdx @@ -35,9 +35,9 @@ LVGL is implemented in C and its APIs are in C. - 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` > `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) + [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) (the interactive prompt) ### MicroPython + LVGL could be used for: @@ -91,6 +91,8 @@ Many LVGL examples are available also for MicroPython. Just click the link! ### PC Simulator +You can also run LVGL on a [PC](/integration/pc) without MicroPython. + MicroPython is ported to many platforms. One notable port is to "Unix", which allows you to build and run MicroPython (+LVGL) on a Linux machine. (On a Windows machine you might need Virtual Box or WSL or MinGW or Cygwin etc.) @@ -112,24 +114,24 @@ It can be ported to any other platform supported by MicroPython. **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 @@ -138,8 +140,8 @@ It can be ported to any other platform supported by MicroPython. ## 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) +- [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. @@ -162,28 +164,26 @@ For a summary of coding conventions to follow see the [Coding Style](/contributi manager which is [garbage-collected](https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)) (GC). - To prevent GC from collecting memory prematurely, all dynamic allocated RAM must be reachable by the GC. - GC is aware of most allocations, except from pointers to the [Data Segment](https://en.wikipedia.org/wiki/Data_segment): - + - Pointers which are global variables - Pointers which are static global variables - Pointers which are static local variables Such pointers need to be defined in a special way to make them reachable by the GC. -##### Identify The Problem +#### Identify The Problem A problem occurs when an allocated memory's pointer (return value of ) is stored only in either **global**, **static global** or **static local** pointer variable and not as part of a previously allocated `struct` or other variable. -##### Solving the Problem +#### Solving the Problem -- Replace the global/static local var with +- Replace the global/static local var with `LV_GLOBAL_DEFAULT()->_var` (see ) - Include `lv_global.h` on files that use - Add `_var` to `lv_global_t` on `lv_global.h` -##### Example - -##### Further Reading on Memory Management +#### Further Reading on Memory Management - [In the README](https://github.com/lvgl/lv_binding_micropython#memory-management) - [In the Blog](https://blog.lvgl.io/2019-02-20/micropython-bindings#i-need-to-allocate-a-littlevgl-struct-such-as-style-color-etc-how-can-i-do-that-how-do-i-allocatedeallocate-memory-for-it) @@ -207,27 +207,27 @@ next to the function pointer when registering a callback, and access that 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 +#### Examples - contains `user_data` field. registers `path_cb` callback. Both `lv_anim_set_path_cb` and receive as their first argument @@ -236,7 +236,7 @@ In practice it's also possible to mix these options, for example provide a struc - registers `path_cb` and receives `user_data` as the last argument. The callback also receives the `user_data` as the last argument. -##### Further Reading on Callbacks +#### Further Reading on Callbacks - In the [Blog](https://blog.lvgl.io/2019-08-05/micropython-pure-display-driver#using-callbacks) and in the [README](https://github.com/lvgl/lv_binding_micropython#callbacks) diff --git a/docs/src/integration/boards/manufacturers/icop.mdx b/docs/src/integration/boards/manufacturers/icop.mdx index 4debe63163..c3db062874 100644 --- a/docs/src/integration/boards/manufacturers/icop.mdx +++ b/docs/src/integration/boards/manufacturers/icop.mdx @@ -40,7 +40,7 @@ See the [store page](https://www.icop.com.tw/product/QEC-PPC-M-090T) for documentation and the ordering information. -##### Specs +#### Specs CPU and Memory diff --git a/docs/src/integration/boards/manufacturers/toradex.mdx b/docs/src/integration/boards/manufacturers/toradex.mdx index 3bbd8ace55..338f092d41 100644 --- a/docs/src/integration/boards/manufacturers/toradex.mdx +++ b/docs/src/integration/boards/manufacturers/toradex.mdx @@ -33,16 +33,13 @@ making the board extra reliable, especially in these environments. Aquila Computer on Module: -- [Aquila iMX95](https://www.toradex.com/computer-on-modules/ - aquila-arm-family/nxp-imx95) - - [Aquila AM69](https://www.toradex.com/computer-on-modules/ - aquila-arm-family/ti-am69) +- [Aquila iMX95](https://www.toradex.com/computer-on-modules/aquila-arm-family/nxp-imx95) + - [Aquila AM69](https://www.toradex.com/computer-on-modules/aquila-arm-family/ti-am69) Aquila Carrier Boards: - [Clover](https://www.toradex.com/products/carrier-board/clover) - - [Aquila Development Board](https://www.toradex.com/products/carrier-board/ - aquila-development-board-kit) + - [Aquila Development Board](https://www.toradex.com/products/carrier-board/aquila-development-board-kit) ### Apalis @@ -58,19 +55,14 @@ offerings and the company's rich ecosystem of other products and services. Apalis Computer on Module: -- [Apalis iMX8](https://www.toradex.com/computer-on-modules/ - apalis-arm-family/nxp-imx-8) - - [Apalis iMX6](https://www.toradex.com/computer-on-modules/ - apalis-arm-family/nxp-freescale-imx-6) - - [Apalis T30](https://www.toradex.com/computer-on-modules/ - apalis-arm-family/nvidia-tegra-3) +- [Apalis iMX8](https://www.toradex.com/computer-on-modules/apalis-arm-family/nxp-imx-8) + - [Apalis iMX6](https://www.toradex.com/computer-on-modules/apalis-arm-family/nxp-freescale-imx-6) + - [Apalis T30](https://www.toradex.com/computer-on-modules/apalis-arm-family/nvidia-tegra-3) Apalis Carrier Boards: -- [Ixora](https://www.toradex.com/products/carrier-board/ - ixora-carrier-board) - - [Apalis Evaluation Board](https://www.toradex.com/products/carrier-board/ - ixora-carrier-board) +- [Ixora](https://www.toradex.com/products/carrier-board/ixora-carrier-board) + - [Apalis Evaluation Board](https://www.toradex.com/products/carrier-board/ixora-carrier-board) ### Colibri @@ -85,33 +77,21 @@ Colibri Arm family of modules. Colibri Computer on Module: -- [Colibri iMX8X](https://www.toradex.com/computer-on-modules/ - colibri-arm-family/nxp-imx-8x) - - [Colibri T30](https://www.toradex.com/computer-on-modules/ - colibri-arm-family/nvidia-tegra-3) - - [Colibri T20](https://www.toradex.com/computer-on-modules/ - colibri-arm-family/nvidia-tegra-2) - - [Colibri iMX6](https://www.toradex.com/computer-on-modules/ - colibri-arm-family/nxp-freescale-imx6) - - [Colibri iMX7](https://www.toradex.com/computer-on-modules/ - colibri-arm-family/nxp-freescale-imx7) - - [Colibri iMXiMX6ULL8X](https://www.toradex.com/computer-on-modules/ - colibri-arm-family/nxp-imx6ull) - - [Colibri VF61](https://www.toradex.com/computer-on-modules/ - colibri-arm-family/nxp-freescale-vybrid-vf6xx) - - [Colibri VF50](https://www.toradex.com/computer-on-modules/ - colibri-arm-family/nxp-freescale-vybrid-vf5xx) +- [Colibri iMX8X](https://www.toradex.com/computer-on-modules/colibri-arm-family/nxp-imx-8x) + - [Colibri T30](https://www.toradex.com/computer-on-modules/colibri-arm-family/nvidia-tegra-3) + - [Colibri T20](https://www.toradex.com/computer-on-modules/colibri-arm-family/nvidia-tegra-2) + - [Colibri iMX6](https://www.toradex.com/computer-on-modules/colibri-arm-family/nxp-freescale-imx6) + - [Colibri iMX7](https://www.toradex.com/computer-on-modules/colibri-arm-family/nxp-freescale-imx7) + - [Colibri iMX6ULL](https://www.toradex.com/computer-on-modules/colibri-arm-family/nxp-imx6ull) + - [Colibri VF61](https://www.toradex.com/computer-on-modules/colibri-arm-family/nxp-freescale-vybrid-vf6xx) + - [Colibri VF50](https://www.toradex.com/computer-on-modules/colibri-arm-family/nxp-freescale-vybrid-vf5xx) Colibri Carrier Boards: -- [Colibri Evaluation Board](https://www.toradex.com/products/carrier-board/ - colibri-evaluation-board) - - [Iris Carrier Board](https://www.toradex.com/products/carrier-board/ - iris-carrier-board) - - [Viola Carrier Board](https://www.toradex.com/products/carrier-board/ - viola-carrier-board) - - [Aster Carrier Board](https://www.toradex.com/products/carrier-board/ - aster-carrier-board) +- [Colibri Evaluation Board](https://www.toradex.com/products/carrier-board/colibri-evaluation-board) + - [Iris Carrier Board](https://www.toradex.com/products/carrier-board/iris-carrier-board) + - [Viola Carrier Board](https://www.toradex.com/products/carrier-board/viola-carrier-board) + - [Aster Carrier Board](https://www.toradex.com/products/carrier-board/aster-carrier-board) ### Verdin @@ -125,28 +105,19 @@ vibration-resistant connection. Verdin Computer on Module: -- [Verdin iMX8M Plus](https://www.toradex.com/computer-on-modules/ - verdin-arm-family/nxp-imx-8m-plus) - - [Verdin iMX8M Mini](https://www.toradex.com/computer-on-modules/ - verdin-arm-family/nxp-imx-8m-mini-nano) - - [Verdin AM62](https://www.toradex.com/computer-on-modules/ - verdin-arm-family/ti-am62) - - [i.MX 95 Verdin Evaluation Kit](https://www.toradex.com/ - computer-on-modules/verdin-arm-family/nxp-imx95-evaluation-kit) - - [Verdin iMX95](https://www.toradex.com/computer-on-modules/ - verdin-arm-family/nxp-imx95-evaluation-kit#verdin-imx95) +- [Verdin iMX8M Plus](https://www.toradex.com/computer-on-modules/verdin-arm-family/nxp-imx-8m-plus) + - [Verdin iMX8M Mini](https://www.toradex.com/computer-on-modules/verdin-arm-family/nxp-imx-8m-mini-nano) + - [Verdin AM62](https://www.toradex.com/computer-on-modules/verdin-arm-family/ti-am62) + - [i.MX 95 Verdin Evaluation Kit](https://www.toradex.com/computer-on-modules/verdin-arm-family/nxp-imx95-evaluation-kit) + - [Verdin iMX95](https://www.toradex.com/computer-on-modules/verdin-arm-family/nxp-imx95-evaluation-kit#verdin-imx95) Verdin Carrier Boards: -- [Verdin Development Board with HDMI Adapter](https://www.toradex.com/ - products/carrier-board/verdin-development-board-kit) - - [Dahlia Carrier Board with HDMI Adapter](https://www.toradex.com/products/ - carrier-board/dahlia-carrier-board-kit) +- [Verdin Development Board with HDMI Adapter](https://www.toradex.com/products/carrier-board/verdin-development-board-kit) + - [Dahlia Carrier Board with HDMI Adapter](https://www.toradex.com/products/carrier-board/dahlia-carrier-board-kit) - [Yavia](https://www.toradex.com/products/carrier-board/yavia) - - [Mallow Carrier Board](https://www.toradex.com/products/carrier-board/ - mallow-carrier-board) - - [Ivy Carrier Board](https://www.toradex.com/products/carrier-board/ - ivy-carrier-board) + - [Mallow Carrier Board](https://www.toradex.com/products/carrier-board/mallow-carrier-board) + - [Ivy Carrier Board](https://www.toradex.com/products/carrier-board/ivy-carrier-board) ## TorizonOS @@ -161,10 +132,8 @@ applications. A TorizonOS guide to develop an application using LVGL can be found in the [Torizon OS](/integration/embedded_linux/distros/torizon) section. -More information is provided in the [Torizon documentation](https://www.torizon. -io/torizon-os). +More information is provided in the [Torizon documentation](https://www.torizon.io/torizon-os). ## Toradex Examples -There are existing ready to use repositories available. Click [here](https:// -github.com/lvgl?q=lv_port_toradex&type=all&language=&sort=) to check them out. +There are existing ready to use repositories available. Click [here](https://github.com/lvgl?q=lv_port_toradex&type=all&language=&sort=) to check them out. diff --git a/docs/src/integration/building/cmake.mdx b/docs/src/integration/building/cmake.mdx index 2931b72382..db0f28be79 100644 --- a/docs/src/integration/building/cmake.mdx +++ b/docs/src/integration/building/cmake.mdx @@ -24,7 +24,7 @@ You need to install ### How to build this project using cmake -##### Build with Command line +#### Build with Command line The simplest way to build LVGL using cmake is to use the command line calls: @@ -42,7 +42,7 @@ cmake -B build # Configure phase cmake --build build # build phase ``` -##### Build with cmake presets +#### Build with cmake presets Another way to build this project is to use the provided CMakePresets.json or pass options using the command line. The CMakePresets.json file describes some cmake configurations and build phase. It is a way to quickly use a set of @@ -70,7 +70,7 @@ cmake --build --preset windows-base_dbg ctest --preset windows-base_dbg ``` -##### Build with IDE +#### Build with IDE The recommended way for consuming CMakePresets is a CMakePresets aware IDE such as @@ -80,7 +80,7 @@ The recommended way for consuming CMakePresets is a CMakePresets aware IDE such Simply load this project into your IDE and select your desired preset and you are good to go. -##### Build with CMake GUI +#### 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) diff --git a/docs/src/integration/chip_vendors/alif/overview.mdx b/docs/src/integration/chip_vendors/alif/overview.mdx index ac5c2eb647..f433bed162 100644 --- a/docs/src/integration/chip_vendors/alif/overview.mdx +++ b/docs/src/integration/chip_vendors/alif/overview.mdx @@ -13,7 +13,7 @@ Alif offers both microcontrollers and microprocessors. ## LVGL on Alif Boards This is a guide for getting started with LVGL on an Alif board. It specifically details -the all the steps needed to get the LVGL example project +all the steps needed to get the LVGL example project [alif_m55-lvgl](https://github.com/alifsemi/alif_m55-lvgl) running on the [Alif E7 Devkit Gen2](https://alifsemi.com/ensemble-e7-series/); however, any project based on the [Alif VS Code Template](https://github.com/alifsemi/alif_vscode-template) @@ -27,7 +27,7 @@ This project uses D/AVE 2D rendering acceleration with LVGL's D/AVE 2D [draw uni ### Step-by-Step Guide -##### Install Visual Studio Code +#### Install Visual Studio Code Install Visual Studio code. There are different ways of installing it depending on your platform. [See here](https://code.visualstudio.com/docs/setup/setup-overview). @@ -45,7 +45,7 @@ Install the "Dev Containers" VS Code extension. Select your container from the " side panel. -##### Install Prerequisite tools +#### Install Prerequisite tools Make sure these are installed in your environment. The VS Code extensions rely on these being present. @@ -53,7 +53,7 @@ Make sure these are installed in your environment. The VS Code extensions rely o - `curl` - `unzip` -##### Install the Alif SE Tools +#### Install the Alif SE Tools Create an Alif account and download the tools from [here](https://alifsemi.com/support/software-tools/ensemble/) under "Alif Security Toolkit". @@ -72,18 +72,18 @@ Among the results of `ls` you should see `app-release-exec-linux`. That, combine with the output of `pwd`, is the path you need to use later. I.e., `/home/you/app-release-exec-linux`. -##### Install J-Link Software (optional) +#### Install J-Link Software (optional) Download the latest stable version of the [J-Link Software](https://www.segger.com/downloads/jlink). Its installation path will be needed later. -##### Clone the `alif_m55-lvgl` Project +#### Clone the `alif_m55-lvgl` Project ```bash git clone --recursive https://github.com/alifsemi/alif_m55-lvgl ``` -##### Open `alif_m55-lvgl` in VS Code +#### Open `alif_m55-lvgl` in VS Code Open the cloned repo in VS Code. For the VS Code extensions to work properly, it's recommended to open the folder in VS Code instead of opening a @@ -98,7 +98,7 @@ or navigate to **File \> Open Folder** in VS Code and open `alif_m55-lvgl`. If you are prompted to automatically install recommended extensions, click "install" so you can skip the next step. -##### Install Required VS Code Extensions +#### Install Required VS Code Extensions Install the following VS Code extensions from the "Extensions" side panel @@ -107,7 +107,7 @@ Install the following VS Code extensions from the "Extensions" side panel - C/C++ Extension Pack - Cortex-Debug (optional. needed for debugging) -##### Activate Environment +#### Activate Environment If it hasn't happened automatically, Click "Arm Tools" on the bottom bar and then click "Activate Environment" in the list that appears. It will install CMake, @@ -115,7 +115,7 @@ ninja-build, a GCC ARM compiler, and cmsis-toolbox. If you only see "Reactivate Environment" then it is likely already active. -##### Set the Paths of Installed Tools +#### Set the Paths of Installed Tools Press ctrl + shift + p. Type "preferences" and select the option "Preferences: Open User Settings (JSON)" from the choices. @@ -149,7 +149,7 @@ If your `settings.json` looks like this initially... The above uses Windows paths as an example. A Linux path to the Alif SE Tools may look something like `"/home/you/app-release-exec-linux"`. -##### Configure the Board Variant +#### Configure the Board Variant Open the [board.h file](https://github.com/alifsemi/alif_vscode-template/blob/ce5423dbd15f62cb0aa4462533a960d79a014f97/board/board.h#L23-L30). @@ -157,7 +157,7 @@ Open the Identify your board variant in the list and set `BOARD_ALIF_DEVKIT_VARIANT` to the correct value. You may also need to set `BOARD_ILI9806E_PANEL_VARIANT` if the default does not match yours. -##### Set Up the Build Context, Compile, and Flash +#### Set Up the Build Context, Compile, and Flash Get to the "Manage Solution" view from the CMSIS Solution extension. You can reach it by either clicking the gear icon on the bottom bar or by navigating to the CMSIS panel @@ -192,7 +192,8 @@ Alif sources for more detailed steps. - [Getting Started with VSCode CMSIS pack project](https://github.com/alifsemi/alif_vscode-template/blob/main/doc/getting_started.md) - [VSCode Getting Started Template](https://github.com/alifsemi/alif_vscode-template/blob/main/README.md) -You can download the "Alif Security Toolkit Quick Start Guide" from https://alifsemi.com/support/software-tools/ensemble/ , +You can download the "Alif Security Toolkit Quick Start Guide" from the +[Alif software tools page](https://alifsemi.com/support/software-tools/ensemble/), assuming you have created an account, to learn how to use the Alif SE Tools to perform low-level manipulations on your board. @@ -203,7 +204,7 @@ an HP target or an HE target. What these are referring to are the two distinct c present in the Alif E7. "HE" stands for "High Efficiency" while "HP" stands for "High Performance". To get the best performance out of an LVGL application, select HP. Consider HE when power usage is a concern. The merit of having asymmetrical cores -is that your application can run theoretically run low-priority workloads efficiently on +is that your application can theoretically run low-priority workloads efficiently on the HE core and delegate time critical, processing intensive workloads to the HP core. There is also an option to choose a "Build Type". For best performance, choose "release". diff --git a/docs/src/integration/chip_vendors/arm/arm2d.mdx b/docs/src/integration/chip_vendors/arm/arm2d.mdx index 7ba42f41fb..1d99d8b165 100644 --- a/docs/src/integration/chip_vendors/arm/arm2d.mdx +++ b/docs/src/integration/chip_vendors/arm/arm2d.mdx @@ -7,7 +7,7 @@ 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 +Arm-2D accelerates LVGL's [drawing](/main-modules/draw) with two modes: **Synchronous Mode** and **Asynchronous Mode**. - When **Helium** and **ACI (Arm Custom Instruction)** are available, it is recommend @@ -15,18 +15,18 @@ Arm-2D accelerates LVGL9 with two modes: **Synchronous Mode** and - 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. +Arm-2D is an open-source project on GitHub. For more, please refer to +[ARM-software/Arm-2D](https://github.com/ARM-software/Arm-2D). ## How to Use In general: - you can set the macro to `1` and - to in `lv_conf.h` to + to in `lv_conf.h` to enable Arm-2D synchronous acceleration for LVGL. - You can set - the macro to `1` in `lv_conf.h` to enable + the macro `LV_USE_DRAW_ARM2D_ASYNC` to `1` in `lv_conf.h` to enable Arm-2D Asynchronous acceleration for LVGL. If you are using diff --git a/docs/src/integration/chip_vendors/arm/overview.mdx b/docs/src/integration/chip_vendors/arm/overview.mdx index 52a5ed7e68..4a97539635 100644 --- a/docs/src/integration/chip_vendors/arm/overview.mdx +++ b/docs/src/integration/chip_vendors/arm/overview.mdx @@ -5,13 +5,13 @@ description: "Arm is a leading semiconductor and software design company, renown 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 +## 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 [CMake](/integration/building/cmake). -##### Getting Started with AC6 +### 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. @@ -20,11 +20,11 @@ AC6 is not free, but it offers a community license that can be activated as foll 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 +## 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 +## 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. [Arm2D](/integration/chip_vendors/arm/arm2d) is a library maintained by Arm that leverages the Helium instruction set. @@ -41,14 +41,14 @@ To add Arm2D to your project, follow these steps: 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`. +9. Enable and set to in `lv_conf.h`. -### Neon Acceleration +## Neon Acceleration -Some ARM Cortex-A and Cortex-R processors with the ARMv7 architecture and every ARM Cortex-A and Cortex-R processor from the ARMv8 architecture support the `Neon SIMD ` instruction set. +Some ARM Cortex-A and Cortex-R processors with the ARMv7 architecture and every ARM Cortex-A and Cortex-R processor from the ARMv8 architecture 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. -### Architecture Support +## Architecture Support Both 32-bit and 64-bit ARM architectures are supported. Simply set to in `lv_conf`. diff --git a/docs/src/integration/chip_vendors/espressif/add_lvgl_to_esp32_idf_project.mdx b/docs/src/integration/chip_vendors/espressif/add_lvgl_to_esp32_idf_project.mdx index c2ababe410..de46d5a090 100644 --- a/docs/src/integration/chip_vendors/espressif/add_lvgl_to_esp32_idf_project.mdx +++ b/docs/src/integration/chip_vendors/espressif/add_lvgl_to_esp32_idf_project.mdx @@ -28,7 +28,7 @@ In case you do not want to use esp_lvgl_port, you can add [LVGL component](https 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. +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** @@ -44,7 +44,7 @@ All components from `${project_dir}/components` are automatically added to the b ### Display Integration -For a 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. +For a successful LVGL project, you will need a [display](/main-modules/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 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 @@ -63,7 +63,7 @@ idf.py add-dependency "espressif/esp_lcd_gc9a01^2.0.0" To configure LVGL, launch the configuration menu with `idf.py menuconfig` in your project root directory. Navigate to `Component config` and then `LVGL configuration`. Additionally the user can make the current LVGL settings permanent, or default, for the current -project, all that is needed is to create a file on the project root called +project, all that is needed is to create a file on the project root called `sdkconfig.defaults` and move the `CONFIG_LV_` symbols to that file. It is possible to create a per-chip default configuration files by creating a @@ -73,13 +73,13 @@ IDF project. ### Starting the LVGL component -Once the IDF project and the LVGL component have been configured, all +Once the IDF project and the LVGL component have been configured, all the early initialization process inside of the code will be ready to use, however -the user should manually start the LVGL subsystem for IDF by calling `bsp_display_start()`, +the user should manually start the LVGL subsystem for IDF by calling `bsp_display_start()`, or `lvgl_port_init()` if LVGL was manually configured, for example without using the `esp_bsp` component. -After calling this function, LVGL will be running in the background; that is, +After calling this function, LVGL will be running in the background; that is, unlike the usual approach, there is no need to periodically call , this function is called by a background task managed by the IDF. diff --git a/docs/src/integration/chip_vendors/espressif/hardware_accelerator_dma2d.mdx b/docs/src/integration/chip_vendors/espressif/hardware_accelerator_dma2d.mdx index ddfb2d3b8f..7045c407c0 100644 --- a/docs/src/integration/chip_vendors/espressif/hardware_accelerator_dma2d.mdx +++ b/docs/src/integration/chip_vendors/espressif/hardware_accelerator_dma2d.mdx @@ -9,11 +9,11 @@ Some chips from Espressif such as the ESP32-P4 family features a peripheral that enhances the copy of 2-D data from a place to another, including output this 2-D data to other peripherals. -This peripheral is the 2-D direct memory access, or DMA2D, the Espressif +This peripheral is the 2-D direct memory access, or DMA2D, the Espressif SDK, the IDF, offers a full featured driver for the DMA2D that is automatically enabled on the supported chips. -One of its primary role is to serve as support for the Pixel Processor Accelerator +One of its primary roles is to serve as support for the Pixel Processor Accelerator the PPA, being used to copy the source image data to the desired PPA client splitting these data into fixed size blocks, called bursts. Also the DMA2D is used to pick the output chunks from the PPA client and copy over to the destination buffer, or the display @@ -28,7 +28,7 @@ display driver uses the DMA2D to copy the target drawn buffer to the display buf intervention. Even though this option is available the user is responsible to explicitly enable it on the display driver of the LVGL port component. -To enabling it the user should set on its `sdkconfig.defaults` the `CONFIG_BSP_DISPLAY_LVGL_AVOID_TEAR`, +To enabling it the user should set on its `sdkconfig.defaults` the `CONFIG_BSP_DISPLAY_LVGL_AVOID_TEAR`, which will tell the driver to use the DMA2D to optimize transfer. Please notice that enabling this option will be only available when using the PSRAM memory and double buffer mode, otherwise a compiler error will be raised. diff --git a/docs/src/integration/chip_vendors/espressif/hardware_accelerator_ppa.mdx b/docs/src/integration/chip_vendors/espressif/hardware_accelerator_ppa.mdx index 0c71d7bcdf..498b856858 100644 --- a/docs/src/integration/chip_vendors/espressif/hardware_accelerator_ppa.mdx +++ b/docs/src/integration/chip_vendors/espressif/hardware_accelerator_ppa.mdx @@ -19,7 +19,7 @@ The Espressif targets that support the PPA are: LVGL supports, in experimental level, the filling and the image blending acceleration through the PPA, the user can enable it in their `sdkconfig.defaults` by -adding the following option to enable the PPA draw unit in conjunction with the software renderer, also: +adding the following option to enable the PPA [draw unit](/main-modules/draw) in conjunction with the software renderer, also: don't forget to make the draw buffers aligned with the cache line size, typically 64bytes: ```c @@ -30,7 +30,7 @@ CONFIG_LV_DRAW_BUF_ALIGN=64 Save the file and then rebuild the project, this will be sufficient to add the PPA code and it will start to run automatically, so no further steps are required from the user code perspective. -Is it suggested to use PPA with the double buffer support of the ESP LVGL Port since it will not offer performance increase when using it in partial mode due +It is suggested to use PPA with the double buffer support of the ESP LVGL Port since it will not offer performance increase when using it in partial mode due to DMA2D memory bandwidth. To have the best performance and experience you can use the following snippet code to start the LVGL subsystem for ESP-IDF: diff --git a/docs/src/integration/chip_vendors/espressif/overview.mdx b/docs/src/integration/chip_vendors/espressif/overview.mdx index 9b27ab9207..dee21e4f92 100644 --- a/docs/src/integration/chip_vendors/espressif/overview.mdx +++ b/docs/src/integration/chip_vendors/espressif/overview.mdx @@ -5,7 +5,7 @@ description: "Espressif Systems is a fabless chip manufacturer that produces the ## About -Espressif Systems is a fabless chip manufacturer that produces the ESP32 series of +Espressif Systems is a fabless chip manufacturer that produces the ESP32 series of system on chips, these chips can be based on Xtensa or Risc-V architectures, and they feature the common set of analog and digital peripherals of a general purpose microcontroller combined to a radio subsystem capable to run a Bluetooth and/or a WiFi stack. @@ -17,12 +17,12 @@ some of its components. ## Application Development -The LVGL is supported by Espressif SDK, that is it, the IDF as mentioned before, +The LVGL is supported by Espressif SDK, that is it, the IDF as mentioned before, therefore ESP32 series of chips are supported on a different sets of frameworks called by Espressif as 3rd party projects. This guide will cover the usage of the LVGL using the Espressif-IDF software development -kit. Although ESP32 are supported on other frameworks also supported by LVGL, it +kit. Although ESP32 are supported on other frameworks also supported by LVGL, it is recommended the user to check the following pages: - [Arduino Framework](/integration/frameworks/arduino) @@ -36,25 +36,25 @@ these platforms where ESP32, and other chips are abstracted by the framework. ## Ready to use projects -For a quick start with LVGL and ESP32, the LVGL maintains an demo project compatible to -several ESP32 boards under its `LV Port for ESP32 `. +For a quick start with LVGL and ESP32, LVGL maintains a demo project compatible with +several ESP32 boards under its [LV Port for ESP32](https://github.com/lvgl/lv_esp_idf). -Refer to the README.md files in this repository for quick build and +Refer to the README.md files in this repository for quick build and flash instructions. -These demo projects use Espressif's Board Support Packages (BSPs). +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. ## LVGL Support for ESP32 Graphical Peripherals Some of the ESP32 chips like the ESP32P4 family have built-in support -for driving display through standard interfaces like RGB and MIPI, -the Espressif IDF (esp-idf), provides the necessary drivers, leaving +for driving display through standard interfaces like RGB and MIPI, +the Espressif IDF (esp-idf), provides the necessary drivers, leaving to the user the responsibility to integrate them into the LVGL display subsystem. Espressif, via its component manager system, provides a ready to use -LVGL porting component, which is the recommended and preferred way of +LVGL porting component, which is the recommended and preferred way of integrating input and output devices from the ESP32 chip to the LVGL Display subsystem, this component is covered in [Add LVGL to an ESP32 IDF project](/integration/chip_vendors/espressif/add_lvgl_to_esp32_idf_project) diff --git a/docs/src/integration/chip_vendors/espressif/tips_and_tricks.mdx b/docs/src/integration/chip_vendors/espressif/tips_and_tricks.mdx index 3ed301edf8..5050090198 100644 --- a/docs/src/integration/chip_vendors/espressif/tips_and_tricks.mdx +++ b/docs/src/integration/chip_vendors/espressif/tips_and_tricks.mdx @@ -9,14 +9,14 @@ The IDF project in general are configured to optimize the final application imag in respect of its size. For some LVGL applications this may not be desired or will result on poor speed of execution. -In this case, it is interesting to set some of the IDF project wide options on the +In this case, it is interesting to set some of the IDF project wide options on the `sdkconfig.defaults` such as: ```c CONFIG_COMPILER_OPTIMIZATION_PERF=y ``` -This one will compile the application with performance as priority, using SIMD +This one will compile the application with performance as priority, using SIMD instructions where is possible. It is possible to perceive an increase up to 30% of overall speed execution increment. @@ -29,7 +29,7 @@ CONFIG_LV_ATTRIBUTE_FAST_MEM_USE_IRAM=y ``` It is also possible to set the CPU to always run on its maximum speed by -setting the `CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_` option, the value of the +setting the `CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_` option, the value of the frequency varies from chip to chip, for example P4 families support 360MHz: ```c @@ -42,7 +42,7 @@ And ESP32/ESP32-S3 support 240MHz: CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240 ``` -Please notice, some of these options needs to be enabled by setting the IDF +Please notice, some of these options needs to be enabled by setting the IDF experimental options to true: ```c @@ -51,14 +51,14 @@ CONFIG_IDF_EXPERIMENTAL_FEATURES=y ## Configuring the PSRAM on ESP32 supported devices -Some of the high-end chips of ESP32 features an external memory on its module, it is +Some of the high-end chips of ESP32 features an external memory on its module, it is Pseudo-Static Random Access Memory, the PSRAM. In general values from 4 to 16MB are present on the chip and LVGL can take a portion of this memory to: - Copy read-only objects from Flash to PSRAM to increase speed. - Use direct-mode plus dual buffer even on ESP32 that does not have built-in display controller. -In both scenarios the result will be reflected on less time to flush data to the +In both scenarios the result will be reflected on less time to flush data to the display, resulting in higher frame-rates. To enable the PSRAM usage the user should: ```c @@ -69,19 +69,19 @@ CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY=y CONFIG_SPIRAM_RODATA=y ``` -These options can reside on the IDF project `sdkconfig.defaults`, the last option +These options can reside on the IDF project `sdkconfig.defaults`. ## Application crashes when enabling PPA Is it possible to happen of an application to start crashing because the user -enabled `CONFIG_LV_USE_PPA` option. The typical symptom is the appearance of -a message on the monitor console that indicates error when esp32 calls the +enabled `CONFIG_LV_USE_PPA` option. The typical symptom is the appearance of +a message on the monitor console that indicates error when esp32 calls the `esp_msync` function. -This happens because PPA only accepts chunks of data that are aligned to the +This happens because PPA only accepts chunks of data that are aligned to the cache L1 line size, that is it 64-bytes, even though the PPA draw unit handles the alignment of the source buffer, the target draw buffer area should be also -aligned otherwise the transfer from PPA to it may fail. To prevent this +aligned otherwise the transfer from PPA to it may fail. To prevent this behavior is interesting to make `CONFIG_LV_DRAW_BUF_ALIGN` to be a multiple of the cache L1 line size, that is it, set its value to `64` instead of the default of `4`. @@ -89,7 +89,7 @@ cache L1 line size, that is it, set its value to `64` instead of the default of CONFIG_LV_DRAW_BUF_ALIGN=64 ``` -## EPS32-P4 monitor log reports buffer underrun and frame-rate decreases +## ESP32-P4 monitor log reports buffer underrun and frame-rate decreases In cases when the PSRAM is enabled and the PPA is used, it is common to see frame-rate degradation followed by a message on the log that reports the display @@ -103,7 +103,7 @@ CONFIG_SPIRAM_SPEED_200M=y ``` Additionally it is possible to set the PPA burst length in order to increase -the memory bandwidth of a particular channel to get speed improvement of the +the memory bandwidth of a particular channel to get speed improvement of the drawing operations, using the option: ```c @@ -111,7 +111,7 @@ CONFIG_LV_PPA_BURST_LENGTH=128 ``` There is a downside of increasing the burst length, if another piece of code from -ESP-IDF is using a DMA2D channel which is shared to PPA, this increase may cause +ESP-IDF is using a DMA2D channel which is shared to PPA, this increase may cause slow-down on that channel consumer. Also mind the burst length value supported are the following: 128, 64, 32, 16, and 8 bytes, other values set will result in a build error. @@ -127,7 +127,7 @@ CONFIG_LV_LOG_LEVEL_INFO=y CONFIG_LV_LOG_PRINTF=y ``` -The logging subsystem of LVGL relies on the ESP-IDF presence of the +The logging subsystem of LVGL relies on the ESP-IDF presence of the printf. ## Using the File System under ESP-IDF @@ -137,7 +137,7 @@ This allows seamless interoperability with LVGL when enabling the If you are not using a custom `partition.csv` yet, it can be added @@ -183,49 +185,49 @@ Some ESP file systems provide automatic generation from a host folder using CMak - **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 [LodePNG](/libs/image_support/lodepng) and [Tiny JPEG](/libs/image_support/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); - \} + + ```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(obj, "A:/spiffs/logo.bin"); + lv_obj_center(obj); + } + ``` - **Build and flash** - + After calling `idf.py build flash` the picture should be displayed on the screen. diff --git a/docs/src/integration/chip_vendors/nxp/elcdif.mdx b/docs/src/integration/chip_vendors/nxp/elcdif.mdx index 3397168941..d1540cef99 100644 --- a/docs/src/integration/chip_vendors/nxp/elcdif.mdx +++ b/docs/src/integration/chip_vendors/nxp/elcdif.mdx @@ -3,19 +3,19 @@ title: NXP eLCDIF description: "eLCDIF is a peripheral that is provided on some of the NXP devices capable to drive display panels through the RGB interface, it supports different color depths and, on MIPI-DSI capable devices, it..." --- -### Overview +## Overview eLCDIF is a peripheral that is provided on some of the NXP devices capable to drive display panels through -the RGB interface, it supports different color depths and, on MIPI-DSI capable devices, its output ca be +the RGB interface, it supports different color depths and, on MIPI-DSI capable devices, its output can be directed to the MIPI display physical interface. The LVGL's NXP eLCDIF driver is responsible to bind the -NXP MCUx SDK low-level driver to the LVGL display subsystem. +NXP MCUx SDK low-level driver to the LVGL [display](/main-modules/display) subsystem. -### Prerequisites +## Prerequisites - This driver relies on the presence of the MCUx SDK from NXP in the same project - Activate the driver by setting to `1` in your *"lv_conf.h"*. -### Usage +## Usage The LVGL driver for eLCDIF assumes the platform already configured the display low-level driver, set the pin-mux, clocks, etc. It also requires the base address of the peripheral and configuration @@ -26,7 +26,7 @@ please notice in this mode of operation the application is responsible to alloca and pass them to the display, in the example below `buffer1` and `buffer2` are the current and the next buffers that will be copied to the display screen, being swapped at each flush operation (managed internally by the display driver). Also observe, in direct mode, each buffer should have the space at -least to hold at least the size of the screen, that is it, the height times the width times the bytes +least to hold at least the size of the screen, that is, the height times the width times the bytes for a pixel (which is application dependent or display supported), on the code below this size is represented by `buf_size`. @@ -41,8 +41,8 @@ lv_display_set_default(g_disp); To use the driver in 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 argument. -please notice in this case the `BUF_SIZE` needs to have, at least, space to hold data of 1/10 of the actual +Buffer swapping can be activated by passing a second buffer of same size instead of the `NULL` argument. +Please notice in this case the `BUF_SIZE` needs to have, at least, space to hold data of 1/10 of the actual display dimensions. ```c @@ -51,8 +51,8 @@ static uint8_t partial_draw_buf[BUF_SIZE]; lv_display_t * g_disp = lv_nxp_display_elcdif_create_partial(LCDIF, config, partial_draw_buf, NULL, BUF_SIZE); ``` -In runtime, the event handler function from the eLCDIF driver should be called inside of the eLCDIF interrupt handler -This function is responsible for notify the LVGL display subsystem about a finished flush operation: +In runtime, the event handler function from the eLCDIF driver should be called inside of the eLCDIF interrupt handler. +This function is responsible for notifying the LVGL display subsystem about a finished flush operation: ```c void eLCDIF_IRQ_Handler(void) diff --git a/docs/src/integration/chip_vendors/nxp/overview.mdx b/docs/src/integration/chip_vendors/nxp/overview.mdx index aaa2491b6c..8b14ee2e9d 100644 --- a/docs/src/integration/chip_vendors/nxp/overview.mdx +++ b/docs/src/integration/chip_vendors/nxp/overview.mdx @@ -19,38 +19,38 @@ 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 +## 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/G2D support if the modules are present), no additional integration work is required. -### HW acceleration for NXP iMX RT platforms +## 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 +accelerator has its own context that allows them to be used individually as well as simultaneously (in LVGL multithreading mode). -### HW acceleration for NXP iMX platforms +## HW acceleration for NXP iMX platforms On MPU platforms, the acceleration can be done (hardware independent) by NXP G2D library. This accelerator has its own context that allows them to be used -individually as well simultaneously with the CPU (in LVGL multithreading mode). +individually as well as simultaneously with the CPU (in LVGL multithreading mode). -##### PXP accelerator +### PXP accelerator #### Basic configuration: - Select NXP PXP engine in "lv_conf.h": Set to `1`. -- In order to use PXP as a draw unit, select in "lv_conf.h": Set to `1`. +- In order to use PXP as a [draw unit](/main-modules/draw), select in "lv_conf.h": Set to `1`. - In order to use PXP to rotate the screen, select in "lv_conf.h": Set to `1`. - Enable PXP asserts in "lv_conf.h": Set to `1`. There are few PXP assertions that can stop the program execution in case the is set to `while(1);` (Halt by default). Else, there will be logged just an error message via `LV_LOG_ERROR`. -- If symbol is defined, FreeRTOS implementation +- If `SDK_OS_FREE_RTOS` symbol is defined, FreeRTOS implementation will be used, otherwise bare metal code will be included. #### Basic initialization: @@ -74,7 +74,7 @@ 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 +and an additional thread `_pxp_render_thread_cb()` will be spawned in order to handle the supported draw tasks. ```c @@ -88,7 +88,7 @@ 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 +preferred score and the draw unit id will be set to the task. A `score` equal to `100` is the default CPU score. Smaller score means that PXP is capable of drawing it faster. @@ -160,7 +160,7 @@ void lv_draw_pxp_rotate(const void * src_buf, void * dest_buf, int32_t src_width - 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 @@ -172,26 +172,26 @@ void lv_draw_pxp_rotate(const void * src_buf, void * dest_buf, int32_t src_width - "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 - with callback pointers is used as a parameter for the + `pxp_cfg_t` with callback pointers is used as a parameter for the function. Default implementation for FreeRTOS in lv_pxp_osa.c. - - - : Initialize PXP interrupt (HW setup, - OS setup) - - : Deinitialize PXP interrupt (HW setup, - OS setup) - - : Start PXP job. Use OS-specific mechanism to block - drawing thread. - - : Wait for PXP completion. -##### VGLite accelerator + - `pxp_interrupt_init`: Initialize PXP interrupt (HW setup, + OS setup) + - `pxp_interrupt_deinit`: Deinitialize PXP interrupt (HW setup, + OS setup) + - `pxp_run`: Start PXP job. Use OS-specific mechanism to block + drawing thread. + - `pxp_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. A @@ -201,7 +201,7 @@ task or suspend the CPU for power savings. #### Basic configuration: - Select NXP VGLite engine in "lv_conf.h": Set to - `1`. symbol needs to be defined so that FreeRTOS + `1`. `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 to `1`. @@ -260,7 +260,7 @@ 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 +and an additional thread `_vglite_render_thread_cb()` will be spawned in order to handle the supported draw tasks. ```c @@ -274,7 +274,7 @@ 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 +preferred score and the draw unit id will be set to the task. A `score` equal to `100` is the default CPU score. Smaller score means that VGLite is capable of drawing it faster. @@ -351,8 +351,8 @@ switch(t->type) { 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()`). +- 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). @@ -370,13 +370,13 @@ All the below operation can be done in addition with optional opacity. 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 (). + requirement for linear buffer layouts (`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 @@ -392,7 +392,7 @@ All the below operation can be done in addition with optional opacity. - "src/draw/nxp/vglite/lv_vglite_path.c": create vglite path data - "src/draw/nxp/vglite/lv_vglite_utils.c": function helpers -##### G2D accelerator +### G2D accelerator #### Basic configuration: @@ -406,7 +406,7 @@ All the below operation can be done in addition with optional opacity. #### Basic initialization: G2D draw initialization is done automatically in once the -G2D is enabled as a draw unit , no user code is required: +G2D is enabled as a draw unit, no user code is required: ```c #if LV_USE_DRAW_G2D @@ -424,12 +424,12 @@ draw_g2d_unit->base_unit.dispatch_cb = _g2d_dispatch; draw_g2d_unit->base_unit.delete_cb = _g2d_delete; ``` -and an addition thread `_g2d_render_thread_cb()` will be spawned in order to +and an additional thread `_g2d_render_thread_cb()` will be spawned in order to handle the supported draw tasks. ```c #if LV_USE_G2D_DRAW_THREAD - lv_thread_init(&draw_g2d_unit->thread, LV_THREAD_PRIO_HIGH, _g2d_render_thread_cb, 2 * 1024, draw_g2d_unit); + lv_thread_init(&draw_g2d_unit->thread, "g2ddraw", LV_THREAD_PRIO_HIGH, _g2d_render_thread_cb, 2 * 1024, draw_g2d_unit); #endif ``` @@ -438,7 +438,7 @@ and the G2D drawing task will get executed on the same LVGL main thread. `_g2d_evaluate()` will get called after each task is being created and will analyze if the task is supported by G2D or not. If it is supported, then an -preferred score and the draw unit id will be set to the task. An `score` equal +preferred score and the draw unit id will be set to the task. A `score` equal to `100` is the default CPU score. Smaller score means that G2D is capable of drawing it faster. @@ -455,7 +455,7 @@ available for other operations while the G2D is running. Linux OS 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/nx/g2d/lv_draw_g2d.c": +Supported draw tasks are available in "src/draw/nxp/g2d/lv_draw_g2d.c": ```c switch(t->type) { @@ -496,7 +496,7 @@ switch(t->type) { - Add G2D related source files (and corresponding headers if available) to project: - + - "src/draw/nxp/g2d/lv_draw_buf_g2d.c": draw buffer callbacks - "src/draw/nxp/g2d/lv_draw_g2d_fill.c": fill area - "src/draw/nxp/g2d/lv_draw_g2d_img.c": blit image (w/ optional recolor or diff --git a/docs/src/integration/chip_vendors/nxp/vg_lite_gpu.mdx b/docs/src/integration/chip_vendors/nxp/vg_lite_gpu.mdx index c508ff2833..7ae073b25f 100644 --- a/docs/src/integration/chip_vendors/nxp/vg_lite_gpu.mdx +++ b/docs/src/integration/chip_vendors/nxp/vg_lite_gpu.mdx @@ -7,11 +7,11 @@ This is a generic VG-Lite rendering backend implementation that is designed to u [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. +LVGL [rendering](/main-modules/draw) acceleration can be supported without the need for LVGL adaptation work. ## Configuration -1. Set to 1 in `lv_conf.h` to enabled the VG-Lite rendering backend. +1. Set to 1 in `lv_conf.h` to enable 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: @@ -43,10 +43,10 @@ LVGL rendering acceleration can be supported without the need for LVGL adaptatio 6. Set the 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 error, you can try increasing the size of the GPU memory pool or reducing the number of gradient cache entries. + If the VG-Lite API returns the `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 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 error, + The memory occupied by the stroke is strongly related to the path length. If the VG-Lite API returns the `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 is always configured as . diff --git a/docs/src/integration/chip_vendors/renesas/built_in_drivers.mdx b/docs/src/integration/chip_vendors/renesas/built_in_drivers.mdx index e67c3e3f9d..63b76587ac 100644 --- a/docs/src/integration/chip_vendors/renesas/built_in_drivers.mdx +++ b/docs/src/integration/chip_vendors/renesas/built_in_drivers.mdx @@ -20,6 +20,8 @@ Dave2D is capable of accelerating most of the drawing operations of LVGL: 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 to one-third, depending on the application. +More info can be found at the [driver's page](/integration/chip_vendors/renesas/dave2d_gpu). + ## GLCDC GLCDC is a multi-stage graphics output peripheral available in several Renesas MCUs. It is able to drive LCD panels via a highly diff --git a/docs/src/integration/chip_vendors/renesas/glcdc.mdx b/docs/src/integration/chip_vendors/renesas/glcdc.mdx index ac6aebbe0d..b4a0d796b4 100644 --- a/docs/src/integration/chip_vendors/renesas/glcdc.mdx +++ b/docs/src/integration/chip_vendors/renesas/glcdc.mdx @@ -48,7 +48,7 @@ lv_display_set_default(disp); To use the driver in 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 argument. +Buffer swapping can be activated by passing a second buffer of same size instead of the `NULL` argument. ```c static lv_color_t partial_draw_buf[DISPLAY_HSIZE_INPUT0 * DISPLAY_VSIZE_INPUT0 / 10] BSP_PLACE_IN_SECTION(".sdram") BSP_ALIGN_VARIABLE(1024); @@ -66,11 +66,11 @@ Partial mode can be activated via the macro in `src/board_init.c` file of the de Software based screen rotation is supported in partial mode. It uses the common API, no extra configuration is required: ```c -lv_display_set_rotation(lv_display_get_default(), LV_DISP_ROTATION_90); +lv_display_set_rotation(lv_display_get_default(), LV_DISPLAY_ROTATION_90); /* OR */ -lv_display_set_rotation(lv_display_get_default(), LV_DISP_ROTATION_180); +lv_display_set_rotation(lv_display_get_default(), LV_DISPLAY_ROTATION_180); /* OR */ -lv_display_set_rotation(lv_display_get_default(), LV_DISP_ROTATION_270); +lv_display_set_rotation(lv_display_get_default(), LV_DISPLAY_ROTATION_270); ``` Make sure the heap is large enough, as a buffer with the same size as the partial buffer will be allocated. diff --git a/docs/src/integration/chip_vendors/renesas/ra_family.mdx b/docs/src/integration/chip_vendors/renesas/ra_family.mdx index 1d56059ddc..051462323e 100644 --- a/docs/src/integration/chip_vendors/renesas/ra_family.mdx +++ b/docs/src/integration/chip_vendors/renesas/ra_family.mdx @@ -25,11 +25,11 @@ Supported boards in the RA Family: repositories, recursive updating of the git submodules is no longer needed. - 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, for FSP version prior to 6.0: - + ```bash git clone https://github.com/lvgl/lv_port_renesas_ek-ra8d1_gcc.git --recurse-submodules ``` - + Downloading the `.zip` from GitHub doesn't work as it doesn't download the submodules. - Clone the ready-to-use repository for your selected board, for FSP version from 6.0 and above: @@ -42,29 +42,26 @@ Supported boards in the RA Family: `General` / `Existing projects into workspace`. - Select the cloned folder and press `Finish`. - Double-click on `configuration.xml`. This will activate the `Configuration Window`. - + Renesas' Flexible Software Package (FSP) includes 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 in *"main.c"*. - + Press `Generate Project Content` in the top right corner. - - .. image:: /_static/images/renesas/generate.png - :alt: Code generation with FSP + + ![Code generation with FSP](/_static/images/renesas/generate.png) - Build the project by pressing `Ctrl` + `Alt` + `B` - Click the Debug button (![img_debug_btn](/_static/images/renesas/debug_btn.png)). 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:: /_static/images/renesas/debug_ra8.png - :alt: Debugger parameters for RA8 - + + ![Debugger parameters for RA8](/_static/images/renesas/debug_ra8.png) + - `R7FA6M3AH` for EK-RA6M3G - - .. image:: /_static/images/renesas/debug_ra6.png - :alt: Debugger parameters for RA6 + + ![Debugger parameters for RA6](/_static/images/renesas/debug_ra6.png) On EK-RA8D1 boards, the `SW1` DIP switch 7 (in the middle of the board) should be @@ -72,7 +69,7 @@ ON, all others are OFF. Also note opening a project previously built on top of the FSP prior to v6.0 will trigger a dialog asking whether the user wants to migrate to the new FSP v6.0. The migration will -not break the project,. +not break the project. ## Modify the project @@ -90,7 +87,7 @@ You can disable the LVGL demos (or just comment them out) and call some - to set LVGL's default color depth - to set the maximum RAM available to LVGL -- to enable the GPU +- to enable the [Dave2D GPU](/integration/chip_vendors/renesas/dave2d_gpu) Hardware and software components can be modified in a visual way using the `Configuration Window`. diff --git a/docs/src/integration/chip_vendors/renesas/rx_family.mdx b/docs/src/integration/chip_vendors/renesas/rx_family.mdx index c14ed1564c..95708bcf27 100644 --- a/docs/src/integration/chip_vendors/renesas/rx_family.mdx +++ b/docs/src/integration/chip_vendors/renesas/rx_family.mdx @@ -16,23 +16,22 @@ Supported boards in the RX Family: 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 registration. - + The compiler must be activated in e² studio: - - - Go to go to `Help` -> `Add Renesas Toolchains` + + - Go to `Help` -> `Add Renesas Toolchains` - Press the `Add...` button - Select the installation folder of the toolchain - - .. image:: /_static/images/renesas/toolchains.png - :alt: Toolchains + + ![Toolchains](/_static/images/renesas/toolchains.png) - Clone the ready-to-use [lv_port_renesas_rx72n-envision-kit](https://github.com/lvgl/lv_port_renesas_rx72n-envision-kit.git) repository: - + ```bash git clone https://github.com/lvgl/lv_port_renesas_rx72n-envision-kit.git --recurse-submodules ``` @@ -42,21 +41,19 @@ Downloading the `.zip` from GitHub doesn't work as it doesn't download the submo - 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` to activate the `Configuration Window`. - + Renesas' Smart Configurator (SMC) includes 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:: /_static/images/renesas/generate_smc.png - :alt: Code generation with SMC + + ![Code generation with SMC](/_static/images/renesas/generate_smc.png) - Build the project by pressing `Ctrl` + `Alt` + `B` - Click the Debug button (![img_debug_btn](/_static/images/renesas/debug_btn.png)). If prompted with `Debug Configurations`, on the `Debugger` tab select the `E2 Lite` as `Debug hardware` and `R5F572NN` as `Target Device`: - - .. image:: /_static/images/renesas/debug_rx72.png - :alt: Debugger parameters for RX72 + + ![Debugger parameters for RX72](/_static/images/renesas/debug_rx72.png) Make sure that both channels of `SW1` DIP switch (next to `ECN1`) are OFF. @@ -77,7 +74,7 @@ You can disable the LVGL demos (or just comment them out) and call some - to set LVGL's default color depth - to set the maximum RAM available to LVGL -- to enable the GPU +- to enable the [Dave2D GPU](/integration/chip_vendors/renesas/dave2d_gpu) Hardware and software components can be modified in a visual way using the `Configuration Window`. diff --git a/docs/src/integration/chip_vendors/renesas/rzg_family.mdx b/docs/src/integration/chip_vendors/renesas/rzg_family.mdx index 7e5d759539..38ec0686a9 100644 --- a/docs/src/integration/chip_vendors/renesas/rzg_family.mdx +++ b/docs/src/integration/chip_vendors/renesas/rzg_family.mdx @@ -22,8 +22,8 @@ Supported boards in the RZ/G Family: version, even though LVGL is statically linked. You may try using newer versions of LVGL. See the [v8-to-v9 Migration Guide](https://docs.lvgl.io/9.0/CHANGELOG.html#migration-guide) for things you will need to address. - Clone the ready-to-use repository for your selected board: - - + + ```bash git clone https://github.com/lvgl/lv_port_renesas_rz-g2l-evkit --recurse-submodules ``` @@ -34,21 +34,21 @@ Downloading the `.zip` from GitHub doesn't work as it doesn't download the submo build, and upload the project to the board. - Stop any automatically started demos (on G2UL run `systemctl stop demo-launcher` in the terminal). - Run the project: - + ```bash ./lvgl_demo_benchmark ``` ### Modify the project -##### Open a demo +#### Open a demo The entry point is contained in `src/main.c`. You can disable the LVGL demos (`lv_demo_benchmark()`) (or just comment them out) and call some `lv_example_...()` functions, or add your own custom code. -##### Configuration +#### Configuration Edit `lv_conf.h` and `lv_drv_conf.h` to configure LVGL. The board image contains LVGL and lv_drivers as dynamically linkable libraries. This project builds @@ -67,7 +67,7 @@ LVGL statically for customizability and to port the LVGL v9 benchmark from LVGL - LVGL is not included in the SDK so you should build whichever version you need. Later versions of LVGL include the optimal OpenGL driver. - Clone the ready-to-use repository: - + ```bash git clone https://github.com/lvgl/lv_port_renesas_rz-g3e-evkit --recurse-submodules ``` @@ -78,21 +78,21 @@ Downloading the `.zip` from GitHub doesn't work as it doesn't download the submo Yocto SD Card image and SDK (pre-built or custom-built), build, and upload the project to the board. - Stop the Wayland desktop if using the OpenGL, DRM, or fbdev drivers. Run `systemctl stop weston` in the terminal. - Run the project: - + ```bash ./lvglsim ``` ### Modify the project -##### Open a demo +#### Open a demo The entry point is contained in `lv_port_linux/src/main.c`. You can disable the LVGL demos (`lv_demo_benchmark()`) (or just comment them out) and call some `lv_example_...()` functions, or add your own custom code. -##### Configuration +#### Configuration Edit `lv_conf.h` to configure LVGL. You can edit `lv_conf.defaults` --- a sparse version of `lv_conf.h` which you can use to regenerate `lv_conf.h` by running diff --git a/docs/src/integration/chip_vendors/stm32/dma2d_gpu.mdx b/docs/src/integration/chip_vendors/stm32/dma2d_gpu.mdx index e2c67cb8dd..6eae28a395 100644 --- a/docs/src/integration/chip_vendors/stm32/dma2d_gpu.mdx +++ b/docs/src/integration/chip_vendors/stm32/dma2d_gpu.mdx @@ -54,9 +54,9 @@ other RTOS tasks while a DMA2D transfer is ongoing, do the following: ## Interop with LTDC and NeoChrom -DMA2D usage can be freely mixed with LTDC usage as long as +DMA2D usage can be freely mixed with [LTDC](/integration/chip_vendors/stm32/ltdc) usage as long as is **not** enabled. LTDC will use the DMA2D peripheral for flushing, if that is enabled. -NeoChrom and DMA2D may be enabled at the same time. They are both draw units +[NeoChrom](/integration/chip_vendors/stm32/neochrom) and DMA2D may be enabled at the same time. They are both draw units and they will both independently accept draw tasks. diff --git a/docs/src/integration/chip_vendors/stm32/lcd_stm32_guide.mdx b/docs/src/integration/chip_vendors/stm32/lcd_stm32_guide.mdx index 5dec1c1b6f..c56cd186c0 100644 --- a/docs/src/integration/chip_vendors/stm32/lcd_stm32_guide.mdx +++ b/docs/src/integration/chip_vendors/stm32/lcd_stm32_guide.mdx @@ -3,10 +3,11 @@ title: SPI Display Driver Creation for STM32 description: Here is how you can drive a RGB565 240x320 SPI display using STM32 HAL SPI. You can use direct or partial mode. --- -### Display Driver +## Display Driver Here is how you can drive a RGB565 240x320 SPI display using STM32 HAL SPI. You can use direct or partial mode. Single-buffered direct is shown in this example. +See the [Display](/main-modules/display) module for general background on LVGL displays. In your initialization code, create the display and set the buffers and flush callback. @@ -44,9 +45,9 @@ static void flush_cb(lv_display_t * disp, const lv_area_t * area, uint8_t * px_m Performance can be improved by using DMA with double buffering. -### Touch indev +## Touch indev -In your initialization code, create the touch screen indev. +In your initialization code, create the touch screen [input device](/main-modules/indev). ```c lv_indev_t * indev = lv_indev_create(); diff --git a/docs/src/integration/chip_vendors/stm32/ltdc.mdx b/docs/src/integration/chip_vendors/stm32/ltdc.mdx index 13f88ca593..a6cf872ce6 100644 --- a/docs/src/integration/chip_vendors/stm32/ltdc.mdx +++ b/docs/src/integration/chip_vendors/stm32/ltdc.mdx @@ -8,6 +8,7 @@ title: STM32 LTDC Display Driver Some STM32s have a specialized peripheral called LTDC (LCD-TFT Display Controller) for driving displays. +See the [Display](/main-modules/display) module for general background on LVGL displays. ## Usage Modes With LVGL @@ -58,7 +59,7 @@ 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 +For the best visual 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. Chips with a CPU data cache have unavoidable visual artifacts when using single-buffered direct mode. If there is almost enough @@ -134,13 +135,13 @@ disp = lv_st_ltdc_create_partial(partial_buf1, The driver supports display rotation with where rotation is one of -, , -or . The rotation is initially -. +, , +or . The rotation is initially +. The rotation is done in software and only works if the display was created using . - will be have no effect if rotation + will have no effect if rotation is used. ## Interop with the DMA2D and NeoChrom Draw Units diff --git a/docs/src/integration/chip_vendors/stm32/neochrom.mdx b/docs/src/integration/chip_vendors/stm32/neochrom.mdx index ce61ecd69d..ede5e999ff 100644 --- a/docs/src/integration/chip_vendors/stm32/neochrom.mdx +++ b/docs/src/integration/chip_vendors/stm32/neochrom.mdx @@ -28,7 +28,7 @@ Enable the renderer by setting to `1` in lv_conf.h. Set to the correct version for the core in -your MCU. If left as `LV_NEMA_LIB_NONE`, M33 RevC will be assumed. +your MCU. If left as , M33 RevC will be assumed. If using , set and @@ -137,9 +137,9 @@ const lv_image_dsc_t img_demo_widgets_avatar_tsc6a = { ## Interop with the LTDC driver and the DMA2D Draw Unit -NeoChrom can be enabled at the same time as LTDC. They will not interfere +NeoChrom can be enabled at the same time as [LTDC](/integration/chip_vendors/stm32/ltdc). They will not interfere with each other at all. -NeoChrom and DMA2D may be enabled at the same time. They are both draw units +NeoChrom and [DMA2D](/integration/chip_vendors/stm32/dma2d_gpu) may be enabled at the same time. They are both draw units and they will both independently accept draw tasks. diff --git a/docs/src/integration/embedded_linux/distros/buildroot/app_deployment.mdx b/docs/src/integration/embedded_linux/distros/buildroot/app_deployment.mdx index 22ff4cb721..9c526eac1f 100644 --- a/docs/src/integration/embedded_linux/distros/buildroot/app_deployment.mdx +++ b/docs/src/integration/embedded_linux/distros/buildroot/app_deployment.mdx @@ -3,15 +3,15 @@ title: LVGL Application on Buildroot description: "How to build and deploy an LVGL application into a Buildroot rootfs overlay." --- -# LVGL application +## LVGL application This section provides information about the steps to follow to get a custom application using LVGL running on the board. -## Update RootFS +### Update RootFS Depending on the application, it might be necessary to update the rootfs. Let's -take as example the compilation of LVGL with DRM. The system must have +take as example the compilation of LVGL with [DRM](/integration/embedded_linux/drivers/drm). The system must have `libdrm` installed. ```bash @@ -41,7 +41,7 @@ find build/ -name "*libdrm*" You should see the include folder and the .so files. -## Generate SDK and set up environment +### Generate SDK and set up environment Generate an SDK that you can use to cross-compile the application for the target (RPi4). @@ -90,10 +90,10 @@ export CFLAGS="--sysroot=${SYSROOT}" export LDFLAGS="--sysroot=${SYSROOT}" ``` -## Build the application +### Build the application The environment is now set up, and we're ready to build an application using -the [lv_benchmark` repository that is inspired from `lv_port_linux](https://github.com/lvgl/lv_port_linux). +the [`lv_benchmark`](https://github.com/EDGEMTech/lv_benchmark) repository, which is inspired by [`lv_port_linux`](https://github.com/lvgl/lv_port_linux). Navigate back to the root of the project and clone the repository: @@ -124,7 +124,7 @@ The output should contain these information: - ARM aarch64 - interpreter /lib/ld-linux-aarch64.so.1 -## Set a rootfs overlay +### Set a rootfs overlay In Buildroot, a rootfs overlay (or root filesystem overlay) is a mechanism that allows you to add custom files, directories, and configurations directly into diff --git a/docs/src/integration/embedded_linux/distros/buildroot/custom_image.mdx b/docs/src/integration/embedded_linux/distros/buildroot/custom_image.mdx index fdef63d709..fccf50f2b0 100644 --- a/docs/src/integration/embedded_linux/distros/buildroot/custom_image.mdx +++ b/docs/src/integration/embedded_linux/distros/buildroot/custom_image.mdx @@ -3,7 +3,7 @@ title: Custom Buildroot Image description: "Step-by-step guide to creating a custom Buildroot image, using the Raspberry Pi 4 as an example. Adaptable to other boards." --- -# Custom image for buildroot +## Custom image for buildroot This chapter offers a detailed guide for creating a custom image for the Raspberry Pi 4 (RPi4). Key Buildroot components and concepts will be @@ -33,8 +33,7 @@ Each folder utility will be explained throughout the guide. ## Get Buildroot -First, according to the [Builroot Manual](https://buildroot.org/downloads/ -manual/manual.html), Buildroot requires certain packages to be installed +First, according to the [Buildroot Manual](https://buildroot.org/downloads/manual/manual.html), Buildroot requires certain packages to be installed before starting the build. Lets install them using Ubuntu's package manager. ```bash @@ -58,7 +57,7 @@ cd buildroot make list-defconfigs | grep rasp ``` -There is a build available for RPi4 62 bits: `raspberrypi4_64_defconfig`. +There is a build available for RPi4 64 bits: `raspberrypi4_64_defconfig`. You can also find all the configurations in the Buildroot repository `buildroot > configs` @@ -131,7 +130,7 @@ the `build` folder, where the build process takes place. It includes files such as configuration files, source code, and object files that are generated as part of the build process. -# host +### host The `host` folder contains files and binaries that are built for the host system rather than the target system. This includes tools and utilities that @@ -139,14 +138,14 @@ are needed to build packages or to run the build system itself. It may contain compilers, build tools, and libraries that are required to support the build process for the target. -# images +### images This directory holds the final output images generated for the target system, such as filesystem images, kernel images, or bootloader images. Depending on the configuration, you may find files like `rootfs.tar`, `zImage`, `uImage`, or others that are ready to be deployed onto the target hardware. -# target +### target The `target` folder contains the files that are specifically intended for the target system. This includes the root filesystem and any additional files that diff --git a/docs/src/integration/embedded_linux/distros/buildroot/quick_start.mdx b/docs/src/integration/embedded_linux/distros/buildroot/quick_start.mdx index 32e0ad1993..8cf66e4075 100644 --- a/docs/src/integration/embedded_linux/distros/buildroot/quick_start.mdx +++ b/docs/src/integration/embedded_linux/distros/buildroot/quick_start.mdx @@ -3,7 +3,7 @@ title: Quick Start description: "Get up and running quickly with a pre-configured Buildroot setup for LVGL." --- -# Quick Start +## Quick Start A Git repository is available that includes everything needed to test the Buildroot setup without following the guide. It is intended for testing diff --git a/docs/src/integration/embedded_linux/distros/torizon.mdx b/docs/src/integration/embedded_linux/distros/torizon.mdx index 72134dfba1..8ac97064c8 100644 --- a/docs/src/integration/embedded_linux/distros/torizon.mdx +++ b/docs/src/integration/embedded_linux/distros/torizon.mdx @@ -12,7 +12,7 @@ instead of building and maintaining a custom distribution. This guide explains how to create a docker image containing LVGL and a simple demo application that can be deployed on any Toradex device running TorizonOS. -### Prerequisites +## Prerequisites To follow this guide you obviously need to have a Toradex SoM along with a carrier board. More information is available on the Toradex [website](https://www.toradex.com/computer-on-modules). @@ -25,7 +25,7 @@ this guide. Also Docker needs to be present on the development host. The [Toradex documentation](https://developer.toradex.com) is a helpful resource. This article contains many references to it. -### Board setup +## Board setup Begin by installing TorizonOS by using the Toradex Easy Installer. Follow the official bring-up [guides](https://developer.toradex.com/quickstart/bringup/). @@ -37,16 +37,16 @@ The address is displayed in the bottom right corner. It will be used later. Once the setup is complete, the device will boot into TorizonOS. -### VS Code extension +## VS Code extension -Toradex provides a [VS Code extension](https://developer.toradex.com/torizon/application-development/ide-extension/) that offers a collection of templates used +Toradex provides a [VS Code extension](https://developer.toradex.com/torizon/application-development/ide-extension/) that offers a collection of templates used to configure and automate the tasks needed to cross-compile applications and build Docker images. These templates now include support for LVGL applications, available as one of the [partner templates](https://github.com/torizon/vscode-torizon-templates?tab=readme-ov-file#partner-templates). This guide explains how to perform those operations manually. -### Creating the Docker image +## Creating the Docker image To build a Torizon container for ARM on your development machine, you need to enable Docker emulation. Run the following commands to enable it: @@ -78,7 +78,7 @@ These commands create the project directory and the `Dockerfile`. `git` is used to download the `lv_port_linux` and `lvgl` repositories from Github. -By default, `lv_port_linux` is configured to use the legacy framebuffer device +By default, `lv_port_linux` is configured to use the legacy [framebuffer](/integration/embedded_linux/drivers/fbdev) device `/dev/fb0`. It is also possible to use another rendering backend by enabling the correct options in `lv_port_linux/lv_conf.h`. @@ -131,10 +131,10 @@ The `Dockerfile` acts like a recipe to build two images: `build` and `deploy`. First it downloads the necessary packages to build the simulator using Debian's package manager `apt-get`. -After compilation, the resulting executable is written to `lv_port_linux/bin/lvglsim`. +After compilation, the resulting executable is written to `/app/build/bin/lvglsim`. The `deploy` image will be deployed on the device. -The executable created in the previous image is copied to the `/usr/bin` directory of the current image. +The executable created in the previous image is copied to the `/usr/lvgl_widgets` path of the current image. This creates a smaller image that does not include the tool chain and the build dependencies. @@ -156,7 +156,7 @@ lvgl_app latest 2967a34a9e74 2 minutes ago 118MB Alongside the image name, you'll also find its ID (`2967a34a9e74` in this example). This will be useful for later. -### Deploying the container image to the device +## Deploying the container image to the device The image is now ready to be deployed on the device. There are several ways to perform this task. @@ -191,7 +191,7 @@ Get the IP address of the development host and open a remote shell on the device ```sh sudo su # When prompted type in the password of the torizon user -# Be sure to replace set the IP address of your host instead +# Be sure to set the IP address of your host instead cat << heredoc > /etc/docker/daemon.json { "insecure-registries" : [":5000"] @@ -221,14 +221,14 @@ Start the container like so, using the image ID: docker run --device /dev/fb0:/dev/fb0 ``` -### Conclusion +## Conclusion You now have a running LVGL application. Where to go from here? - You are now ready to build your LVGL application for Torizon OS. It is recommended to get familiar with VSCode IDE extension as it will simplify your workflow. - + If you are a VSCode user, it is the best way to develop for Torizon OS. If you use another editor or IDE you can always write scripts to automate the building/pushing/pulling operations. diff --git a/docs/src/integration/embedded_linux/distros/yocto/core_components.mdx b/docs/src/integration/embedded_linux/distros/yocto/core_components.mdx index 12a3bd5281..23b9bd1c56 100644 --- a/docs/src/integration/embedded_linux/distros/yocto/core_components.mdx +++ b/docs/src/integration/embedded_linux/distros/yocto/core_components.mdx @@ -29,8 +29,7 @@ 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). +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: @@ -52,8 +51,7 @@ $ bitbake matchbox-desktop 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 +"[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, @@ -86,27 +84,24 @@ using the term "package" when referring to recipes. 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 [. -The "`Classes](https://docs.yoctoproject.org/ref-manual/classes. -html#classes)" chapter in the Yocto Project +[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 -The configuration files ([.conf`) define various configuration +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). +`conf/local.conf`, which is found in the [Build Directory](https://docs.yoctoproject.org/ref-manual/terms.html#term-Build-Directory). ## 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) +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 @@ -116,16 +111,12 @@ 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. +[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 +`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. diff --git a/docs/src/integration/embedded_linux/distros/yocto/lvgl_recipe.mdx b/docs/src/integration/embedded_linux/distros/yocto/lvgl_recipe.mdx index 92559b37a5..f6a7bd9351 100644 --- a/docs/src/integration/embedded_linux/distros/yocto/lvgl_recipe.mdx +++ b/docs/src/integration/embedded_linux/distros/yocto/lvgl_recipe.mdx @@ -21,8 +21,7 @@ liblz4-tool file locales libacl1 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) +[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. @@ -138,7 +137,7 @@ bitbake-layers show-layers - networking-layer - meta-python -# Build for RaspberryPi3 64 +## Build for RaspberryPi3 64 The available machine configurations for Raspberrypi can be listed like this @@ -169,8 +168,6 @@ Everything is setup, time to build the image: bitbake core-image-base ``` -===================== - Let's go through the build folders to understand what happened. ### Downloads @@ -194,9 +191,9 @@ 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 + bootable images for the device are found here. It's organized by the machine (or target board) for which the image was built. -- **rmp/deb/ipk**: These folders contain the individual software packages +- **rpm/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 @@ -282,7 +279,6 @@ There is a recipe in `meta-openembedded` since `honister`. | 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. @@ -291,8 +287,7 @@ 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` +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: @@ -415,11 +410,9 @@ The fetch Repo address has to be stored in **SRC_URI** variable. In 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`. +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 +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_unpack) @@ -466,8 +459,7 @@ In this case, it creates a build directory, It invokes CMake to configure 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 +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. @@ -488,7 +480,7 @@ If there are any compilation steps, then these steps are define in 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`. + 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. @@ -523,14 +515,13 @@ 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:: +With these modifications, you can now run the image recipe again: bitbake core-image-base -This will execute all the previous described tasks. +This will execute all the previously 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 +If everything went well, you should now find this file `build/tmp/deploy/rpm/cortexa53/lvgl-9.1.0-r0.cortexa53.rpm` and other rpm files related to lvgl. @@ -553,7 +544,7 @@ purposes, particularly in embedded development: 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 + working with the same versions of libraries 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. @@ -580,7 +571,7 @@ 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: ```bash -cd /opt/poky/5.0.4/sysroots/cortexa53-poky-linux +cd /opt/poky/sdk-with-lvgl/sysroots/cortexa53-poky-linux find . -name "*lvgl*" ``` @@ -589,7 +580,7 @@ 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: ```bash -source /opt/poke/5.0.4/environment-setup-cortexa53-poky-linux +source /opt/poky/sdk-with-lvgl/environment-setup-cortexa53-poky-linux ``` @@ -603,7 +594,7 @@ 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 +### Create a layer First, create a layer and add it to the configuration file @@ -625,7 +616,7 @@ directory tree should look like the following └── example_0.1.bb ``` -# Create a recipe +### Create a recipe Following this structure, create a folder containing the recipes to build 1 or multiple applications using lvgl @@ -668,7 +659,7 @@ do_install() { The sources come from `lv_port_linux` repository. We apply 2 patches to modify the `CMakeLists.txt` and `lv_conf.h`. -### Patch 1 +#### Patch 1 Create the first patch file @@ -790,9 +781,9 @@ index 62a834f..58fbe7a 100644 2.34.1 ``` -### Patch 2 +#### Patch 2 -Create the first patch file +Create the second patch file ```c touch 0002-adapt-CMakeLists-file-to-compile-and-link-fbdev.patch @@ -848,7 +839,7 @@ target_include_directories(lvgl PUBLIC ${PROJECT_SOURCE_DIR}) 2.34.1 ``` -# Build the recipe +### Build the recipe You should now be able to see the recipe listing the existing recipes diff --git a/docs/src/integration/embedded_linux/distros/yocto/terms_and_variables.mdx b/docs/src/integration/embedded_linux/distros/yocto/terms_and_variables.mdx index 77ff61bec9..a2be702af3 100644 --- a/docs/src/integration/embedded_linux/distros/yocto/terms_and_variables.mdx +++ b/docs/src/integration/embedded_linux/distros/yocto/terms_and_variables.mdx @@ -1,14 +1,13 @@ --- title: Yocto Project Terms -description: Getting started in Yocto can be overwheming. There are many terms used that are specific to Yocto and Bitbake environment. +description: Getting started in Yocto can be overwhelming. There are many terms used that are specific to Yocto and Bitbake environment. --- -Getting started in Yocto can be overwheming. There are many terms used that are +Getting started in Yocto can be overwhelming. 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). +development environment might find helpful can be found [here](https://docs.yoctoproject.org/ref-manual/terms.html). ## Yocto Variables Glossary @@ -160,8 +159,7 @@ 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 +"[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 diff --git a/docs/src/integration/embedded_linux/draw_units/draw_nanovg.mdx b/docs/src/integration/embedded_linux/draw_units/draw_nanovg.mdx index 1ac1f5916d..ef1140d219 100644 --- a/docs/src/integration/embedded_linux/draw_units/draw_nanovg.mdx +++ b/docs/src/integration/embedded_linux/draw_units/draw_nanovg.mdx @@ -3,7 +3,7 @@ title: NanoVG Draw Unit description: "NanoVG is a lightweight, antialiased 2D vector graphics library built on top of OpenGL/OpenGL ES. The NanoVG draw unit integrates NanoVG as a hardware-accelerated rendering backend for LVGL, provide..." --- -# Introduction +## Introduction NanoVG is a lightweight, antialiased 2D vector graphics library built on top of OpenGL/OpenGL ES. The NanoVG draw unit integrates NanoVG as a hardware-accelerated rendering backend for LVGL, @@ -17,13 +17,13 @@ Unlike the software renderer, NanoVG leverages the GPU for: - Box shadows and gradients - Vector graphics support -# Requirements +## Requirements - OpenGL 2.0+ / OpenGL ES 2.0+ / OpenGL ES 3.0+ - An initialized OpenGL context (via GLFW, EGL, or custom setup) - Stencil buffer support (8-bit recommended) -# Configuration +## Configuration Enable the NanoVG draw unit in `lv_conf.h`: @@ -47,7 +47,7 @@ Enable the NanoVG draw unit in `lv_conf.h`: #define LV_NANOVG_FBO_CACHE_CNT 8 /* Framebuffer object cache entries */ ``` -# Supported Features +## Supported Features The NanoVG draw unit supports all standard LVGL drawing operations: @@ -66,7 +66,7 @@ The NanoVG draw unit supports all standard LVGL drawing operations: | Canvas | Direct drawing to canvas buffers | | Vector Graphics | SVG-style path rendering (requires `LV_USE_VECTOR_GRAPHIC`) | -# Supported Image Formats +## Supported Image Formats NanoVG supports zero-copy texture upload for these LVGL color formats: @@ -78,14 +78,14 @@ NanoVG supports zero-copy texture upload for these LVGL color formats: | `LV_COLOR_FORMAT_RGB888` | BGR→RGB swizzle | No alpha channel | | `LV_COLOR_FORMAT_RGB565` | Direct upload | Note: LVGL uses BGR565 layout | -# Performance Tips +## Performance Tips 1. **Minimize Layer Usage**: Each layer requires a framebuffer object (FBO) switch 2. **Use Premultiplied Alpha**: Set `LV_IMAGE_FLAGS_PREMULTIPLIED` for pre-processed images 3. **Cache Static Content**: NanoVG caches textures automatically; avoid recreating images 4. **Batch Similar Operations**: Group widgets with similar styles for better GPU batching -# Limitations +## Limitations - **Blur**: Not natively supported; Using this style will not affect the rendering results. - **Complex Gradients**: Limited to 2-color gradients (LVGL supports multi-stop) diff --git a/docs/src/integration/embedded_linux/draw_units/draw_opengl.mdx b/docs/src/integration/embedded_linux/draw_units/draw_opengl.mdx index 8c3366c904..267bc4e430 100644 --- a/docs/src/integration/embedded_linux/draw_units/draw_opengl.mdx +++ b/docs/src/integration/embedded_linux/draw_units/draw_opengl.mdx @@ -3,9 +3,7 @@ title: OpenGL ES Draw Unit description: "The OpenGL ES Draw Unit provides a hardware-accelerated rendering backend for LVGL that leverages OpenGL ES capabilities." --- -## Introduction - -# Overview +## Overview The OpenGL ES Draw Unit provides a hardware-accelerated rendering backend for LVGL that leverages OpenGL ES capabilities. @@ -35,7 +33,7 @@ The OpenGL ES Draw Unit provides excellent performance for: ## Configuration -# Enable in lv_conf.h +Enable the OpenGL ES draw unit in `lv_conf.h`: ```c #define LV_USE_OPENGLES 1 diff --git a/docs/src/integration/embedded_linux/draw_units/draw_sdl.mdx b/docs/src/integration/embedded_linux/draw_units/draw_sdl.mdx index 1f9dcd9230..18e63a97a5 100644 --- a/docs/src/integration/embedded_linux/draw_units/draw_sdl.mdx +++ b/docs/src/integration/embedded_linux/draw_units/draw_sdl.mdx @@ -3,9 +3,7 @@ title: SDL Draw Unit description: "The SDL Draw Unit provides a hardware-accelerated rendering backend for LVGL that leverages SDL2's texture system. It uses software rendering to create SDL textures which are then cached and effici..." --- -## Introduction - -# Overview +## Overview The SDL Draw Unit provides a hardware-accelerated rendering backend for LVGL that leverages SDL2's texture system. It uses software rendering to create SDL textures which are then cached and efficiently blended together by the GPU to compose the final UI. @@ -33,7 +31,7 @@ The SDL Draw Unit excels in scenarios with: ## Configuration -# Enable in lv_conf.h +Enable the SDL draw unit in `lv_conf.h`: ```c #define LV_USE_SDL 1 diff --git a/docs/src/integration/embedded_linux/drivers/X11.mdx b/docs/src/integration/embedded_linux/drivers/X11.mdx index ea5fc2df26..42af11b4bf 100644 --- a/docs/src/integration/embedded_linux/drivers/X11.mdx +++ b/docs/src/integration/embedded_linux/drivers/X11.mdx @@ -3,7 +3,7 @@ title: X11 description: The X11 display/input driver offers support for simulating the LVGL display and keyboard/mouse inputs in an X11 desktop window. --- -### Overview +## Overview The **X11** display/input [driver](https://github.com/lvgl/lvgl/tree/master/src/drivers/x11) offers support for simulating the LVGL display and keyboard/mouse inputs in an X11 @@ -14,14 +14,14 @@ 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 +## 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 +## Configure X11 driver 1. Enable the X11 driver support in lv_conf.h, by cmake compiler define or by KConfig @@ -32,34 +32,34 @@ The X11 driver uses XLib to access the linux window manager. 2. Optional configuration options: - Direct Exit - ```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) */ - ``` + ```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 + - Double buffering - ```c - #define LV_X11_DOUBLE_BUFFER 1 /* preferred default */ - // or - #define LV_X11_DOUBLE_BUFFER 0 /* not recommended */ - ``` + ```c + #define LV_X11_DOUBLE_BUFFER 1 /* preferred default */ + // or + #define LV_X11_DOUBLE_BUFFER 0 /* not recommended */ + ``` -- Render mode + - Render mode - ```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 */ - ``` + ```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_FULL 1 /* LV_DISPLAY_RENDER_MODE_FULL, not recommended for X11 driver */ + ``` -### Usage +## Usage -| The minimal initialisation opening a window and enabling keyboard/mouse support -| (e.g. in main.c, LV_X11_DIRECT_EXIT must be 1): +The minimal initialisation opening a window and enabling keyboard/mouse support +(e.g. in main.c, LV_X11_DIRECT_EXIT must be 1): ```c int main(int argc, char ** argv) @@ -84,8 +84,8 @@ int main(int argc, char ** argv) } ``` -| Full initialisation with mouse pointer symbol and own application exit handling -| (dependent on LV_X11_DIRECT_EXIT (can be 1 or 0)) +Full initialisation with mouse pointer symbol and own application exit handling +(dependent on LV_X11_DIRECT_EXIT (can be 1 or 0)) ```c bool terminated = false; @@ -95,7 +95,7 @@ static void on_close_cb(lv_event_t * e) { ... - terminate = true; + terminated = true; } #endif diff --git a/docs/src/integration/embedded_linux/drivers/drm.mdx b/docs/src/integration/embedded_linux/drivers/drm.mdx index 8dca7e6359..948f811211 100644 --- a/docs/src/integration/embedded_linux/drivers/drm.mdx +++ b/docs/src/integration/embedded_linux/drivers/drm.mdx @@ -3,10 +3,10 @@ title: DRM description: "The DRM (Direct Rendering Manager) display driver provides support for rendering LVGL directly to Linux framebuffer devices through the DRM/KMS subsystem. It enables running LVGL without a windowin..." --- -### Overview +## Overview The **DRM** (Direct Rendering Manager) display driver provides support for rendering -LVGL directly to Linux framebuffer devices through the DRM/KMS subsystem. +LVGL directly to Linux framebuffer devices through the DRM/KMS subsystem. It enables running LVGL without a windowing system such as X11 or Wayland, making it suitable for embedded devices, single-board computers, and direct-to-display applications. @@ -14,9 +14,9 @@ applications. The DRM driver interacts directly with the GPU or display controller through `/dev/dri/cardX` nodes. -### Getting Started with DRM +## Getting Started with DRM -##### Prerequisites +### Prerequisites The DRM driver requires: @@ -31,17 +31,17 @@ On Debian/Ubuntu-based systems: sudo apt-get install libdrm-dev ``` -##### Configure DRM Driver +### Configure DRM Driver 1. Enable the DRM driver support in `lv_conf.h`, by CMake compiler define, or by KConfig: - + ```c #define LV_USE_LINUX_DRM 1 ``` 2. Link against `libdrm` when building. -##### Basic Usage +### Basic Usage ```c #include "lvgl/lvgl.h" @@ -79,9 +79,9 @@ int main(void) } ``` -##### Notes +### Notes -- `connector_id` specifies which display output (HDMI, eDP, DP, etc.) should be used. +- `connector_id` specifies which display output (HDMI, eDP, DP, etc.) should be used. If `-1` is passed, the DRM driver will try to automatically pick the first available connector. - DRM requires proper modesetting. By default, LVGL will select a preferred display mode. @@ -98,9 +98,9 @@ lv_linux_drm_set_file(disp, device, -1); lv_free(device); ``` -### Using DRM with GBM +## Using DRM with GBM -The DRM driver can optionally use **GBM** (Generic Buffer Management) for buffer allocation. +The DRM driver can optionally use **GBM** (Generic Buffer Management) for buffer allocation. This allows the driver to use GPU-friendly buffer objects instead of simple dumb framebuffers. 1. Enable the following option in your `lv_conf.h` (or via Kconfig/CMake): @@ -109,14 +109,14 @@ This allows the driver to use GPU-friendly buffer objects instead of simple dumb #define LV_USE_LINUX_DRM_GBM_BUFFERS 1 ``` -1. Link against `libgbm` when building. +2. Link against `libgbm` when building. When this option is enabled: - Buffers will be allocated using GBM. - This can improve performance and compatibility on platforms where GBM is supported. -### Using DRM with EGL +## Using DRM with EGL The DRM driver can also be combined with [EGL](/integration/embedded_linux/drivers/egl) for hardware-accelerated rendering via EGL/GLES. @@ -134,17 +134,17 @@ No special setup is required beyond the basic DRM initialization shown in [Basic For a detailed overview of EGL usage and configuration, see [EGL](/integration/embedded_linux/drivers/egl). -### Selecting Display Mode +## Selecting Display Mode -Custom mode selection is currently only supported when using DRM with EGL +Custom mode selection is currently only supported when using DRM with EGL ( enabled). When using DRM without EGL, the driver will always use the preferred display mode. By default, the DRM driver automatically selects the preferred display mode for the connected display. However, you can customize this behavior by providing a mode selection callback. -##### Custom Mode Selection +### Custom Mode Selection To implement custom mode selection logic, define a callback function and register it with : @@ -186,7 +186,7 @@ int main(void) The callback receives an array of available modes and must return the index of the desired mode. -##### Mode Information API +### Mode Information API The following functions are available to query mode properties: @@ -195,7 +195,7 @@ The following functions are available to query mode properties: - - Get refresh rate in Hz - - Check if mode is the display's preferred/native mode -##### Example: Selecting Preferred Mode +### Example: Selecting Preferred Mode ```c size_t select_preferred_mode(lv_display_t * disp, const lv_linux_drm_mode_t * modes, size_t mode_count) @@ -212,7 +212,7 @@ size_t select_preferred_mode(lv_display_t * disp, const lv_linux_drm_mode_t * mo } ``` -##### Example: Selecting Highest Resolution +### Example: Selecting Highest Resolution ```c size_t select_highest_resolution(lv_display_t * disp, const lv_linux_drm_mode_t * modes, size_t mode_count) @@ -235,7 +235,7 @@ size_t select_highest_resolution(lv_display_t * disp, const lv_linux_drm_mode_t } ``` -##### Notes +### Notes - The mode selection callback is called before the display is initialized. - If no callback is set, the driver uses the preferred mode by default. diff --git a/docs/src/integration/embedded_linux/drivers/egl.mdx b/docs/src/integration/embedded_linux/drivers/egl.mdx index af0d951944..000fdbad98 100644 --- a/docs/src/integration/embedded_linux/drivers/egl.mdx +++ b/docs/src/integration/embedded_linux/drivers/egl.mdx @@ -3,17 +3,17 @@ title: EGL description: "The EGL driver provides support for creating LVGL displays using the EGL (Embedded-System Graphics Library) API. EGL is a lower-level API that is more closely tied to the underlying drivers of the ..." --- -### Overview +## Overview -The **EGL** driver provides support for creating LVGL displays using the EGL (Embedded-System Graphics Library) API. -EGL is a lower-level API that is more closely tied to the underlying drivers of the platform. -The OpenGL support in LVGL is intended to be portable between different APIs. Currently, there is support for GLFW and EGL. +The **EGL** driver provides support for creating LVGL displays using the EGL (Embedded-System Graphics Library) API. +EGL is a lower-level API that is more closely tied to the underlying drivers of the platform. +The OpenGL support in LVGL is intended to be portable between different APIs. Currently, there is support for GLFW and EGL. Using EGL requires some additional platform integration. - can be used to create a +`lv_opengles_egl_window_create` can be used to create a which can be used with the same generic LVGL OpenGL APIs as a GLFW window. -### EGL with DRM +## EGL with DRM EGL can be used together with the DRM driver for hardware-accelerated rendering. @@ -22,7 +22,7 @@ No additional initialization is required beyond the normal DRM setup. See [DRM](/integration/embedded_linux/drivers/drm) for configuration and a basic usage example. -### EGL without DRM (Experimental) +## EGL without DRM (Experimental) This feature is experimental and the API is private. Expect breaking changes. @@ -36,10 +36,10 @@ This API is currently private and experimental, and people should expect breakin -DLV_USE_EGL=1 ``` -This allows you to use EGL with your own context management or other platforms, but the API may change +This allows you to use EGL with your own context management or other platforms, but the API may change without notice in future versions. -### Improving Performance +## Improving Performance There is a renderer in LVGL which caches software-rendered areas as OpenGL textures. See [OpenGL Texture Caching Renderer](/integration/embedded_linux/drivers/opengl_driver) to learn more about it. diff --git a/docs/src/integration/embedded_linux/drivers/evdev.mdx b/docs/src/integration/embedded_linux/drivers/evdev.mdx index d982015491..d43b63dc71 100644 --- a/docs/src/integration/embedded_linux/drivers/evdev.mdx +++ b/docs/src/integration/embedded_linux/drivers/evdev.mdx @@ -3,16 +3,16 @@ title: evdev description: "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." --- -### Overview +## 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 +## Prerequisites Your system has an input device configured (usually under `/dev/input/` such as `/dev/input/event0`). -### Configuring the driver +## Configuring the driver Enable the Linux LVGL evdev driver support in `lv_conf.h`. @@ -20,24 +20,24 @@ Enable the Linux LVGL evdev driver support in `lv_conf.h`. #define LV_USE_EVDEV 1 ``` -### Usage +## 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`. +To set up an event input, first create an input device with , setting it to the correct Linux event device. +Then link this to the LVGL display with . ```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. +Ensure that an object is already created for `disp`. An example for this is shown below, using the [Linux framebuffer](/integration/embedded_linux/drivers/fbdev) driver. ```c lv_display_t * disp = lv_linux_fbdev_create(); lv_linux_fbdev_set_file(disp, "/dev/fb0"); ``` -### Locating your input device +## Locating your input device If you can't determine your input device, first run @@ -51,7 +51,7 @@ Try: `$evtest /dev/input/event1` replacing `eventX` with your event device from above. -### Automatic input device discovery +## Automatic input device discovery There is support for automatically finding and adding input devices in `/dev/input/`. New devices will automatically be added when they are connected. To enable this feature, you can simply call . @@ -65,7 +65,7 @@ function which will be called when a new device is added. static void indev_deleted_cb(lv_event_t * e) { if(LV_GLOBAL_DEFAULT()->deinit_in_progress) return; - lv_obj_t * cursor_obj = lv_event_get_user_data(e) + lv_obj_t * cursor_obj = lv_event_get_user_data(e); lv_obj_delete(cursor_obj); } diff --git a/docs/src/integration/embedded_linux/drivers/fbdev.mdx b/docs/src/integration/embedded_linux/drivers/fbdev.mdx index 72d339e84f..e10a3625ed 100644 --- a/docs/src/integration/embedded_linux/drivers/fbdev.mdx +++ b/docs/src/integration/embedded_linux/drivers/fbdev.mdx @@ -3,17 +3,17 @@ title: Linux Framebuffer description: "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 vide..." --- -### Overview +## 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 +## Prerequisites Your system has a framebuffer device configured (usually under `/dev/fb0`). -### Configuring the driver +## 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. @@ -23,10 +23,10 @@ mode. #define LV_LINUX_FBDEV_RENDER_MODE LV_DISPLAY_RENDER_MODE_PARTIAL ``` -### Usage +## 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`). +To set up a framebuffer-based display, first create a display with . Afterwards set the framebuffer device +node on the display with (usually this is `/dev/fb0`). ```c lv_display_t *disp = lv_linux_fbdev_create(); @@ -35,21 +35,21 @@ lv_linux_fbdev_set_file(disp, "/dev/fb0"); If your screen stays black or only draws partially, you can try enabling direct rendering via . Additionally, you can -activate a force refresh mode with `lv_linux_fbdev_set_force_refresh(true)`. This +activate a force refresh mode with . This usually has a performance impact though and shouldn't be enabled unless really needed. -### Hide the cursor +## Hide the cursor You may encounter a blinking cursor on the screen. The method to hide it varies depending on the platform. For instance, here is how it can be done on a Raspberry Pi: 1. Edit `/boot/cmdline.txt` file. - 2. Add `vt.global_cursor_default=0`. +2. Add `vt.global_cursor_default=0`. -### Common mistakes +## Common mistakes -#### Default resolution issue +### Default resolution issue When the Linux kernel initializes, it sets up subsystems like the framebuffer (fbdev) to manage display output. If an HDMI display is connected, the kernel diff --git a/docs/src/integration/embedded_linux/drivers/glfw.mdx b/docs/src/integration/embedded_linux/drivers/glfw.mdx index c65d8fa6be..24a3dad835 100644 --- a/docs/src/integration/embedded_linux/drivers/glfw.mdx +++ b/docs/src/integration/embedded_linux/drivers/glfw.mdx @@ -3,7 +3,7 @@ title: GLFW description: "The GLFW display/input driver offers support for creating LVGL displays and keyboard/mouse inputs that can be used in an OpenGL context. It can be used like Wayland, XCB, SDL or Qt or it can be use..." --- -### Overview +## Overview The **GLFW** display/input driver offers support for creating LVGL displays and keyboard/mouse inputs that can be used in an OpenGL context. @@ -11,23 +11,23 @@ It can be used like **Wayland**, **XCB**, **SDL** or **Qt** or it can be used fo The GLFW driver is a quick way to get started on PC-like platforms. -### Getting Started with GLFW +## Getting Started with GLFW -##### Prerequisites +### Prerequisites -1. Install GLFW: `sudo apt-get install libglfw3-dev` +Install GLFW: `sudo apt-get install libglfw3-dev` -##### Configure GLFW Driver +### Configure GLFW Driver 1. Required linked libraries: -lglfw 2. Enable the GLFW driver and Opengles support in `lv_conf.h`, via cmake compiler define or via KConfig - + ```c #define LV_USE_GLFW 1 #define LV_USE_OPENGLES 1 ``` -##### Basic Usage +### Basic Usage ```c #include "lvgl/lvgl.h" @@ -76,7 +76,7 @@ int main() } ``` -##### Advanced Usage +### Advanced Usage The GLFW 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. @@ -194,7 +194,7 @@ void custom_texture_example(void) } ``` -### Improving Performance +## Improving Performance There is a renderer in LVGL which caches software-rendered areas as OpenGL textures. See [OpenGL Texture Caching Renderer](/integration/embedded_linux/drivers/opengl_driver) to learn more about it. diff --git a/docs/src/integration/embedded_linux/drivers/libinput.mdx b/docs/src/integration/embedded_linux/drivers/libinput.mdx index c113f11f80..75ccde33e0 100644 --- a/docs/src/integration/embedded_linux/drivers/libinput.mdx +++ b/docs/src/integration/embedded_linux/drivers/libinput.mdx @@ -3,12 +3,12 @@ title: libinput description: "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." --- -### Overview +## 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 +## 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 @@ -33,7 +33,7 @@ If your device doesn't show up, you may have to configure udev and the appropria 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 +## Configuring the driver Enable the libinput driver support in lv_conf.h, by cmake compiler define or by KConfig. @@ -50,9 +50,9 @@ Full keyboard support needs to be enabled separately. To find the right key map values, you may use the `setxkbmap -query` command. -### Usage +## 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 +To set up an input device via the libinput driver, all you need to do is call with the respective device type ( or ) and device node path (e.g. `/dev/input/event5`). ```c @@ -61,7 +61,7 @@ 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 . -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` +Depending on your system, the device node paths might not be stable across reboots. If this is the case, you can use to find the first device that has a specific capability. ```c @@ -70,7 +70,7 @@ 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`. +all devices that have a specific capability, use . 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. diff --git a/docs/src/integration/embedded_linux/drivers/opengl_driver.mdx b/docs/src/integration/embedded_linux/drivers/opengl_driver.mdx index 30d0e5f0a9..4c23c9cb67 100644 --- a/docs/src/integration/embedded_linux/drivers/opengl_driver.mdx +++ b/docs/src/integration/embedded_linux/drivers/opengl_driver.mdx @@ -3,16 +3,16 @@ title: OpenGL Driver description: The OpenGL display driver is a generic driver that creates textures for embedding LVGL content in other applications. The goal is to create textures that people can embed in other applications. --- -### Overview +## Overview The **OpenGL** display driver is a generic driver that creates textures for embedding LVGL content in other applications. The goal is to create textures that people can embed in other applications. The OpenGL context must be created by the user or they can use GLFW or EGL as backends. -### Getting Started with OpenGL +## Getting Started with OpenGL -##### Prerequisites +### Prerequisites An OpenGL context must be created before using the OpenGL driver. You can create this using: @@ -20,15 +20,15 @@ An OpenGL context must be created before using the OpenGL driver. You can create - EGL (see [EGL driver](/integration/embedded_linux/drivers/egl)) - Your own OpenGL context management -##### Configure OpenGL Driver +### Configure OpenGL Driver + +Enable the OpenGL driver support in lv_conf.h, by cmake compiler define or by KConfig: -1. Enable the OpenGL driver support in lv_conf.h, by cmake compiler define or by KConfig - ```c #define LV_USE_OPENGLES 1 ``` -##### Basic Usage +### Basic Usage ```c #include "lvgl/lvgl.h" @@ -88,7 +88,7 @@ int main() } ``` -### OpenGL Texture Caching Renderer +## 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. @@ -98,7 +98,7 @@ The performance will be drastically improved in most cases. #define LV_USE_DRAW_OPENGLES 1 ``` -##### Known Limitations +### 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 diff --git a/docs/src/integration/embedded_linux/drivers/wayland.mdx b/docs/src/integration/embedded_linux/drivers/wayland.mdx index 6749d321ab..ca2a054c4b 100644 --- a/docs/src/integration/embedded_linux/drivers/wayland.mdx +++ b/docs/src/integration/embedded_linux/drivers/wayland.mdx @@ -6,10 +6,10 @@ description: "The Wayland driver provides integration between LVGL and Wayland-b ## Overview The Wayland [driver](https://github.com/lvgl/lvgl/tree/master/src/drivers/wayland) provides integration between LVGL and Wayland-based systems, -allowing LVGL applications to render directly into a Wayland surface and handle keyboard, mouse and touch input. This makes it suitable +allowing LVGL applications to render directly into a Wayland surface and handle keyboard, mouse and touch input. This makes it suitable for production deployments, such as kiosk interfaces, control panels, or other embedded GUIs where Wayland is the display server. -In addition to production use, the driver is also useful for development on linux desktop environments, offering a convenient way to simulate and validate +In addition to production use, the driver is also useful for development on linux desktop environments, offering a convenient way to simulate and validate your LVGL applications without dedicated hardware. It serves as an alternative to the X11 and SDL2 drivers. ## Dependencies @@ -64,7 +64,7 @@ enabling GPU-accelerated graphics on Wayland compositors that support the necess **Requirements:** - OpenGL ES 2.0 support on the target hardware -- `LV_USE_OPENGLES` must be enabled in your LVGL configuration +- must be enabled in your LVGL configuration - Must link with the `wayland-egl` library **Usage:** @@ -72,13 +72,13 @@ enabling GPU-accelerated graphics on Wayland compositors that support the necess To enable the EGL backend: 1. Enable OpenGL ES support in your LVGL configuration: - + ```c #define LV_USE_OPENGLES 1 ``` 2. Link your application with the `wayland-egl` library (add to your build system): - + ```bash -lwayland-egl ``` @@ -106,25 +106,25 @@ The G2D backend leverages NXP's hardware-accelerated 2D graphics engine availabl To enable the G2D backend: 1. Enable G2D support in your LVGL configuration: - + ```c #define LV_USE_G2D 1 #define LV_USE_DRAW_G2D 1 ``` 2. Link your application with the `g2d` library (add to your build system): - + ```bash -lg2d ``` ## Configuring the wayland driver -1. Enable the wayland driver in `lv_conf.h` +Enable the wayland driver in `lv_conf.h`: - ```c - #define LV_USE_WAYLAND 1 - ``` +```c +#define LV_USE_WAYLAND 1 +``` ## Reference Project @@ -134,9 +134,9 @@ the required protocols at build time. ## Getting started 1. In `main.c` `#include "lv_drivers/wayland/wayland.h"` -2. Enable the Wayland driver in `lv_conf.h` with `LV_USE_WAYLAND 1` +2. Enable the Wayland driver in `lv_conf.h` with set to `1` 3. should be set either to `32` or `16` in `lv_conf.h` -4. Add a display using `lv_wayland_window_create()`, +4. Add a display using , possibly with a close callback to track the status of each display: ```c @@ -180,42 +180,42 @@ Once a group is set as default, any focusable widget created afterwards is autom allowing keyboard arrows and encoder rotation to move focus between widgets, and Enter/encoder click to activate them. - and both return - `NULL` if called before the display is fully initialised always check that the return disp is non-NULL before querying its input devices. + and both return + `NULL` if called before the display is fully initialised. Always check that the returned display is non-`NULL` before querying its input devices. ### Fullscreen mode -To programmatically fullscreen the window, use the `lv_wayland_window_set_fullscreen()` +To programmatically fullscreen the window, use the 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` +use the function respectively with `true` or `false` for the `maximized` argument. ### Minimize window -To programmatically minimize the window, use the `lv_wayland_window_set_minimized()` function. +To programmatically minimize the window, use the function. ### Physical display assignment When using multiple physical displays, you can control which display a fullscreen window appears on by assigning it to a specific physical display before entering fullscreen mode. -Use `lv_wayland_assign_physical_display()` to assign a window to a particular physical +Use to assign a window to a particular physical display, where the `display` parameter specifies the physical display number (typically 0, 1, 2, etc.): ```c /* Assign to physical display 0 and full screen on that display */ -lv_wayland_assign_physical_display(disp, 0); +lv_wayland_assign_physical_display(disp, 0); lv_wayland_window_set_fullscreen(window, true); ``` To remove the physical display assignment and return to default behavior, use -`lv_wayland_unassign_physical_display()`: +: ```c lv_wayland_unassign_physical_display(disp); @@ -243,8 +243,8 @@ wayland-scanner client-header $SYSROOT/usr/share/wayland-protocols/stable/linux- wayland-scanner private-code $SYSROOT/usr/share/wayland-protocols/stable/linux-dmabuf/linux-dmabuf-v1.xml wayland_linux_dmabuf.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` +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. ## Window Decorations diff --git a/docs/src/integration/embedded_linux/opengl.mdx b/docs/src/integration/embedded_linux/opengl.mdx index 8b4f3371f3..6ad4f85270 100644 --- a/docs/src/integration/embedded_linux/opengl.mdx +++ b/docs/src/integration/embedded_linux/opengl.mdx @@ -3,14 +3,14 @@ title: OpenGL Overview description: "OpenGL (Open Graphics Library) is a cross-platform, hardware-accelerated graphics API that provides a standardized interface for rendering 2D and 3D graphics. Originally developed by Silicon Graphi..." --- -# Introduction +## Introduction -## Overview +### Overview OpenGL (Open Graphics Library) is a cross-platform, hardware-accelerated graphics API that provides a standardized interface for rendering 2D and 3D graphics. Originally developed by Silicon Graphics in 1992, OpenGL has become one of the most widely adopted graphics APIs across desktop, mobile, and embedded platforms. -## OpenGL Support in LVGL +### OpenGL Support in LVGL The OpenGL integration consists of two main components: @@ -23,7 +23,7 @@ OpenGL support addresses several key use cases: 2. Cross-Platform compatibility: OpenGL's wide platform support enables LVGL UIs on desktop, mobile, and embedded systems. 3. Integration with existing applications: Embed LVGL UI elements into games, visualization tools, or other OpenGL applications. -# OpenGL Driver Options +## OpenGL Driver Options The following drivers can be used and will automatically create and maintain an OpenGL context. @@ -34,15 +34,15 @@ The following drivers can be used and will automatically create and maintain an All drivers except the GLFW driver use EGL (Embedded-System Graphics Library) under the hood. -Additionally, LVGL provides a generic OpenGL driver which the user may use to embed +Additionally, LVGL provides a generic OpenGL driver which the user may use to embed OpenGL textures in existing OpenGL applications. This driver assumes an existing OpenGL context and generates textures with hardware acceleration for integration into custom graphics pipelines. For complete implementation details, see [OpenGL driver](/integration/embedded_linux/drivers/opengl_driver). -# OpenGL Draw Unit Options +## OpenGL Draw Unit Options -When one of these draw units is enabled as well as one of the supporting drivers, LVGL will use OpenGL for +When one of these draw units is enabled as well as one of the supporting drivers, LVGL will use OpenGL for hardware-accelerated rendering. - [NanoVG](/integration/embedded_linux/draw_units/draw_nanovg) @@ -51,7 +51,7 @@ hardware-accelerated rendering. [NanoVG](/integration/embedded_linux/draw_units/draw_nanovg) is the recommended choice. It makes better use of the GPU and supports more LVGL features. OpenGL is also available but the performance is worse and it supports fewer features. -# 3D/glTF Support +## 3D/glTF Support The glTF module provides support for loading and rendering 3D models using the glTF 2.0 specification within LVGL applications. This support requires OpenGL ES 2.0 with some extra extensions and provides comprehensive 3D rendering capabilities including PBR materials, diff --git a/docs/src/integration/external_display_controllers/eve/frame_buffer_mode.mdx b/docs/src/integration/external_display_controllers/eve/frame_buffer_mode.mdx index 82e428257c..f1fb89e20d 100644 --- a/docs/src/integration/external_display_controllers/eve/frame_buffer_mode.mdx +++ b/docs/src/integration/external_display_controllers/eve/frame_buffer_mode.mdx @@ -5,6 +5,9 @@ description: A minimal framebuffer driver for EVE FT81x smart display controller A minimal framebuffer driver for EVE FT81x smart display controllers. Works for BT81x too. +For a faster, GPU-accelerated alternative that drives the same EVE chips, see the +[EVE External GPU Renderer](/integration/external_display_controllers/eve/gpu). + Single-buffered partial render mode supported for now. It may not support DSPI or QSPI currently. Tested at 32 MHz on ft812 and at 23 MHz on bt817. diff --git a/docs/src/integration/external_display_controllers/eve/gpu.mdx b/docs/src/integration/external_display_controllers/eve/gpu.mdx index 1dfef2545d..868692c826 100644 --- a/docs/src/integration/external_display_controllers/eve/gpu.mdx +++ b/docs/src/integration/external_display_controllers/eve/gpu.mdx @@ -11,8 +11,8 @@ from the driving MCU so it can be a lower-spec part or dedicate more of its processing time to other tasks. The SPI interface is simpler to connect than parallel RGB especially if the EVE chip is integrated into a display assembly. -LVGL features a renderer for EVE. LVGL UIs can be rendered by EVE -and are effectively indistinguishable from the software renderer is most cases. +LVGL features a [renderer](/main-modules/draw) for EVE. LVGL UIs can be rendered by EVE +and are effectively indistinguishable from the software renderer in most cases. See also the [EVE (FT81x)](/integration/external_display_controllers/eve/frame_buffer_mode) framebuffer driver. It drives the same EVE chips but is a simpler, more standalone implementation which uses software rendering @@ -33,11 +33,11 @@ and sends all the pixels over SPI so it is much slower. Find your display parameters and populate a struct with them. -Here is an example [lv_draw_eve_target_parameters.h` for the Riverdi RVT50HQBNWC00-B +Here is an example `lv_draw_eve_target_parameters.h` for the Riverdi RVT50HQBNWC00-B which has a BT817Q --- the EVE chip. These parameters were taken from the collection of configs provided by the EVE library supporting this renderer. -`See here](https://github.com/RudolphRiedel/FT800-FT813/blob/ee35fa45c37aed78dc4f1196b874ee1c8f80429f/EVE_config.h#L856-L872). +[See here](https://github.com/RudolphRiedel/FT800-FT813/blob/ee35fa45c37aed78dc4f1196b874ee1c8f80429f/EVE_config.h#L856-L872). Check there for your board parameters. ```c @@ -125,10 +125,10 @@ needs to be drawn, a series of commands are sent to EVE. ### Touch Indev Creation - creates a touch [Input devices (lv_indev)](/main-modules/indev) for the display. + creates a touch [input device (lv_indev)](/main-modules/indev) for the display. You may need to configure the i2c address of the touch controller connected to EVE. -See the section [EVE Register Access](/integration/external_display_controllers/eve/gpu) for more info about register access. +See the section [EVE Register Access](#eve-register-access) for more info about register access. Here is an example of setting the `REG_TOUCH_CONFIG` register on a BT817q EVE chip for a capacitive touch screen with a controller that has the i2c address `0x15`. @@ -205,7 +205,7 @@ are available if needed. They are wrappers around `EVE_memRead8()`, etc. Register definitions and other EVE enumerations are available when you include `lvgl.h` under the prefix namespace `LV_EVE_`. I.e., `REG_ID` is available -as and is available as +as and `EVE_ROM_CHIPID` is available as , etc. ### Further Reading diff --git a/docs/src/integration/external_display_controllers/gen_mipi.mdx b/docs/src/integration/external_display_controllers/gen_mipi.mdx index 1ee9b6c994..aa19271f75 100644 --- a/docs/src/integration/external_display_controllers/gen_mipi.mdx +++ b/docs/src/integration/external_display_controllers/gen_mipi.mdx @@ -46,14 +46,16 @@ 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 +by KConfig: ```c #define LV_USE_GENERIC_MIPI 1 ``` -is enabled. +The chip-specific drivers (e.g. ST7789, ILI9341) automatically enable the generic +MIPI driver, so you do not need to set explicitly +when one of those is enabled. ## Usage @@ -80,10 +82,10 @@ void my_lcd_send_color(lv_display_t * disp, const uint8_t * cmd, size_t cmd_size } ``` -The only difference between the -and functions is that is +The only difference between the `my_lcd_send_cmd` +and `my_lcd_send_color` functions is that `my_lcd_send_cmd` is used to send short commands and it is expected to complete the transaction when it -returns (in other words, it should be blocking), while +returns (in other words, it should be blocking), while `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. @@ -107,7 +109,8 @@ 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 . +them to the display object as usual by calling +(see [Draw Buffer(s)](/main-modules/display/setup)). 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 @@ -258,7 +261,7 @@ 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 function to send an arbitrary command to +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: diff --git a/docs/src/integration/external_display_controllers/ili9341.mdx b/docs/src/integration/external_display_controllers/ili9341.mdx index 658c3b2dcf..39ae116fcb 100644 --- a/docs/src/integration/external_display_controllers/ili9341.mdx +++ b/docs/src/integration/external_display_controllers/ili9341.mdx @@ -14,7 +14,7 @@ supply circuit. ILI9341 supports parallel 8-/9-/16-/18-bit data bus MCU interfac The ILI9341 LCD controller [driver](https://github.com/lvgl/lvgl/tree/master/src/drivers/display/ili9341) is -a platform-agnostic driver, based on the generic MIPI driver. It implements +a platform-agnostic driver, based on the [generic MIPI driver](/integration/external_display_controllers/gen_mipi). 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 @@ -67,5 +67,5 @@ lv_display_t * lv_ili9341_create(uint32_t hor_res, uint32_t ver_res, lv_lcd_flag 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. +For additional details and a working example see the +[generic MIPI driver](/integration/external_display_controllers/gen_mipi) documentation. diff --git a/docs/src/integration/external_display_controllers/nv3007.mdx b/docs/src/integration/external_display_controllers/nv3007.mdx index 009bf6784f..e23d95c5c8 100644 --- a/docs/src/integration/external_display_controllers/nv3007.mdx +++ b/docs/src/integration/external_display_controllers/nv3007.mdx @@ -10,13 +10,13 @@ driver for 262,144-color, a-Si TFT liquid crystal display with maximum resolution of 168RGBx428 dots. It contains 252-channel source driver, a 24-channel GIP driver which used for dual-gate control, 161,784-byte GRAM for graphic display data, internal precise power supply circuit which supports full color, -8-color display mode and sleep mode -NV3007 supports 3-/4-line serial peripheral interface (SPI) ， quad serial +8-color display mode and sleep mode. +NV3007 supports 3-/4-line serial peripheral interface (SPI) and quad serial peripheral interface (QSPI). The display area can be specified in internal GRAM by window address function. The NV3007 LCD controller [driver](https://github.com/lvgl/lvgl/tree/master/src/drivers/display/nv3007) -is a platform-agnostic driver, based on the generic MIPI driver. +is a platform-agnostic driver, based on the [generic MIPI driver](/integration/external_display_controllers/gen_mipi). 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. @@ -92,6 +92,12 @@ Here is a simple example of using the NV3007 display with Arduino framework and #define BUFFER_SIZE 142 * 50 uint8_t buf[BUFFER_SIZE]; +/* Tell LVGL how much time has elapsed */ +static uint32_t my_tick(void) +{ + return millis(); +} + /* Define your platform-specific functions to send commands and data */ 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) { @@ -165,7 +171,7 @@ void setup() lv_nv3007_set_gap(disp, 0, 14); lv_display_set_rotation(disp, LV_DISPLAY_ROTATION_270); lv_display_set_color_format(disp, LV_COLOR_FORMAT_RGB565_SWAPPED); - lv_display_set_buffers(disp, buf, NULL, BUFFER_SIZE, LV_DISP_RENDER_MODE_PARTIAL); + lv_display_set_buffers(disp, buf, NULL, BUFFER_SIZE, LV_DISPLAY_RENDER_MODE_PARTIAL); /* Create a simple label on the display */ lv_obj_t *label = lv_label_create(lv_screen_active()); @@ -180,5 +186,5 @@ void loop() } ``` -For additional details and a working example see the generic MIPI driver -documentation. +For additional details and a working example see the +[generic MIPI driver](/integration/external_display_controllers/gen_mipi) documentation. diff --git a/docs/src/integration/external_display_controllers/st7735.mdx b/docs/src/integration/external_display_controllers/st7735.mdx index ab4cac22e8..47aa7de6dd 100644 --- a/docs/src/integration/external_display_controllers/st7735.mdx +++ b/docs/src/integration/external_display_controllers/st7735.mdx @@ -17,7 +17,7 @@ liquid crystal, it is possible to make a display system with fewer components. The ST7735 LCD controller [driver](https://github.com/lvgl/lvgl/tree/master/src/drivers/display/st7735) is a -platform-agnostic driver, based on the generic MIPI driver. It implements +platform-agnostic driver, based on the [generic MIPI driver](/integration/external_display_controllers/gen_mipi). 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 @@ -82,16 +82,16 @@ Setting the color format is also recommended (please refer to [Color Format](/ma ```c /* Example of initializing ST7735 display and its draw buffers */ uint32_t buf_size = 128 * 160 / 10 * sizeof(lv_color_t); -``` lv_color_t *buf1 = malloc(buf_size); - lv_color_t *buf2 = malloc(buf_size); - assert(buf1 != NULL && buf2 != NULL); - lv_display_t *const disp = lv_st7735_create(128, 160, LV_LCD_FLAG_NONE, - my_lcd_send_cmd, my_lcd_send_color); - lv_display_set_color_format(disp, LV_COLOR_FORMAT_RGB565_SWAPPED); - lv_display_set_buffers(disp, buf1, buf2, buf_size, - LV_DISPLAY_RENDER_MODE_PARTIAL); +lv_color_t *buf2 = malloc(buf_size); +assert(buf1 != NULL && buf2 != NULL); +lv_display_t *const disp = lv_st7735_create(128, 160, LV_LCD_FLAG_NONE, + my_lcd_send_cmd, my_lcd_send_color); +lv_display_set_color_format(disp, LV_COLOR_FORMAT_RGB565_SWAPPED); +lv_display_set_buffers(disp, buf1, buf2, buf_size, + LV_DISPLAY_RENDER_MODE_PARTIAL); +``` -For additional details and a working example see the generic MIPI driver -documentation. +For additional details and a working example see the +[generic MIPI driver](/integration/external_display_controllers/gen_mipi) documentation. diff --git a/docs/src/integration/external_display_controllers/st7789.mdx b/docs/src/integration/external_display_controllers/st7789.mdx index dabee0b748..830759421b 100644 --- a/docs/src/integration/external_display_controllers/st7789.mdx +++ b/docs/src/integration/external_display_controllers/st7789.mdx @@ -17,7 +17,7 @@ system with the fewest components. The ST7789 LCD controller [driver](https://github.com/lvgl/lvgl/tree/master/src/drivers/display/st7789) is a -platform-agnostic driver, based on the generic MIPI driver. It implements +platform-agnostic driver, based on the [generic MIPI driver](/integration/external_display_controllers/gen_mipi). 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 @@ -70,5 +70,5 @@ lv_display_t * lv_st7789_create(uint32_t hor_res, uint32_t ver_res, lv_lcd_flag_ 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. +For additional details and a working example see the +[generic MIPI driver](/integration/external_display_controllers/gen_mipi) documentation. diff --git a/docs/src/integration/external_display_controllers/st7796.mdx b/docs/src/integration/external_display_controllers/st7796.mdx index 65d4b3e87e..dbbc2e86f6 100644 --- a/docs/src/integration/external_display_controllers/st7796.mdx +++ b/docs/src/integration/external_display_controllers/st7796.mdx @@ -17,7 +17,7 @@ drive liquid crystal; it is possible to make a display system with fewest compon The ST7796 LCD controller [driver](https://github.com/lvgl/lvgl/tree/master/src/drivers/display/st7796) is a -platform-agnostic driver, based on the generic MIPI driver. It implements +platform-agnostic driver, based on the [generic MIPI driver](/integration/external_display_controllers/gen_mipi). 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 @@ -70,5 +70,5 @@ lv_display_t * lv_st7796_create(uint32_t hor_res, uint32_t ver_res, lv_lcd_flag_ 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. +For additional details and a working example see the +[generic MIPI driver](/integration/external_display_controllers/gen_mipi) documentation. diff --git a/docs/src/integration/frameworks/arduino.mdx b/docs/src/integration/frameworks/arduino.mdx index fff3ae5b3d..4922a0e305 100644 --- a/docs/src/integration/frameworks/arduino.mdx +++ b/docs/src/integration/frameworks/arduino.mdx @@ -12,7 +12,7 @@ For example ESP32 is a good candidate to create UI's with LVGL. If you are using the Arduino GIGA Display Shield (docs [here](https://docs.arduino.cc/hardware/giga-display-shield)), use the [Arduino_H7_Video](https://github.com/arduino/ArduinoCore-mbed/tree/main/libraries/Arduino_H7_Video) library, included in the Arduino Mbed OS board package ([here](https://github.com/arduino/ArduinoCore-mbed)), which provides built-in LVGL compatibility. -### Get the LVGL Arduino library +## Get the LVGL Arduino library LVGL can be installed via the Arduino IDE Library Manager or as a .ZIP library. @@ -20,16 +20,16 @@ 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 +## Set up drivers To get started, the recommended option is to use the LovyanGFX -library as the TFT driver, since it makes testing much easier. -You’ll need to create a display configuration file, such as [my_display.hpp` -similar to the example in `LovyanGFX user_setting.ino](https://github.com/lovyan03/LovyanGFX/blob/master/examples/HowToUse/2_user_setting/2_user_setting.ino) -In the Arduino IDE, you can create a new tab and name it [my_display.hpp` and paste the content of your configuration file there. -If you prefer not to use LovyanGFX, you can integrate other graphics libraries as well by implementing a wrapper class in the same way LovyanGFX is handled; -`lv_lgfx_user.hpp](https://github.com/lvgl/lvgl/blob/master/src/drivers/display/lovyan_gfx/lv_lgfx_user.hpp) -provides a good example of this. Once your configuration file +library as the TFT driver, since it makes testing much easier. +You’ll need to create a display configuration file, such as `my_display.hpp`, +similar to the example in [LovyanGFX's `user_setting.ino`](https://github.com/lovyan03/LovyanGFX/blob/master/examples/HowToUse/2_user_setting/2_user_setting.ino). +In the Arduino IDE, you can create a new tab and name it `my_display.hpp` and paste the content of your configuration file there. +If you prefer not to use LovyanGFX, you can integrate other graphics libraries as well by implementing a wrapper class in the same way LovyanGFX is handled; +[`lv_lgfx_user.hpp`](https://github.com/lvgl/lvgl/blob/master/src/drivers/display/lovyan_gfx/lv_lgfx_user.hpp) +provides a good example of this. Once your configuration file is ready, update `lv_conf.h` to include it, for example: ```c @@ -42,7 +42,7 @@ is ready, update `lv_conf.h` to include it, for example: ``` Alternatively, you can use [TFT_eSPI](https://github.com/Bodmer/TFT_eSPI) library. -To make it work, set up `TFT_eSPI` according to your +To make it work, set up `TFT_eSPI` according to your TFT display type via editing either: - `User_Setup.h` @@ -50,7 +50,7 @@ TFT display type via editing either: Both files are located in `TFT_eSPI` library's folder. -### Configure LVGL +## Configure LVGL LVGL has its own configuration file called `lv_conf.h`. When LVGL is installed, follow these configuration steps: @@ -71,15 +71,13 @@ arduino |-lv_conf.h ``` ------------------------ - 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. +In the INO file you can see how to register a [display](/main-modules/display) and a +[touchpad](/main-modules/indev) for LVGL and call an example. -### Use the examples and demos +## 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 @@ -87,9 +85,9 @@ example . | Field | Description | |-------|-------------| -| `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`. | +| `important` | Due to some 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 +## 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 @@ -99,7 +97,7 @@ section `log settings`: ```c /* Log settings */ -#define USE_LV_LOG 1 /* Enable/disable the log module */ +#define LV_USE_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 diff --git a/docs/src/integration/frameworks/platformio.mdx b/docs/src/integration/frameworks/platformio.mdx index 9ec13c3a0e..7416f819a5 100644 --- a/docs/src/integration/frameworks/platformio.mdx +++ b/docs/src/integration/frameworks/platformio.mdx @@ -3,10 +3,10 @@ title: PlatformIO description: "PlatformIO is an open-source ecosystem for embedded development that integrates with VS Code and supports many boards and frameworks." --- -[PlatformIO](https://platformio.org/) is an open-source ecosystem for +[PlatformIO](https://platformio.org/) is an open-source ecosystem for embedded development that integrates with VS Code and supports many boards and frameworks. -The [LVGL library](https://github.com/lvgl/lvgl) is directly available +The [LVGL library](https://github.com/lvgl/lvgl) is directly available in the PlatformIO library registry and can be added to your project with just a few clicks. Note that you need to choose a board powerful enough to run LVGL and @@ -35,7 +35,7 @@ lib_deps = lvgl/lvgl ``` -You can also specify the library version to use. +You can also specify the library version to use. See [platformio.ini configuration](https://docs.platformio.org/en/latest/projectconf/index.html) If you prefer manual installation, you can also clone the LVGL repository @@ -43,7 +43,7 @@ into the `lib/` directory of your PlatformIO project. ## Set up drivers -To get started, the recommended option is to use the `LovyanGFX library` as the TFT driver, +To get started, the recommended option is to use the `LovyanGFX library` as the TFT driver, since it makes testing much easier. In PlatformIO, you’ll add both `LVGL` and `LovyanGFX` as dependencies in your `platformio.ini`: @@ -60,14 +60,14 @@ See the [supported drivers section](/integration/external_display_controllers) f ## Display Configuration -You’ll need to create a display configuration file, such as [my_display.hpp` similar to the example in -`LovyanGFX user_setting.ino](https://github.com/lovyan03/LovyanGFX/blob/master/examples/HowToUse/2_user_setting/2_user_setting.ino). +You’ll need to create a display configuration file, such as `my_display.hpp`, similar to the example in +[LovyanGFX's `user_setting.ino`](https://github.com/lovyan03/LovyanGFX/blob/master/examples/HowToUse/2_user_setting/2_user_setting.ino). In PlatformIO, you can place this file in the `include/` folder of your project (e.g., `include/my_display.hpp`). -If you prefer not to use LovyanGFX, you can integrate other graphics libraries as well by +If you prefer not to use LovyanGFX, you can integrate other graphics libraries as well by implementing a wrapper class in the same way LovyanGFX is handled; -[lv_lgfx_user.hpp](https://github.com/lvgl/lvgl/blob/master/src/drivers/display/lovyan_gfx/lv_lgfx_user.hpp) +[`lv_lgfx_user.hpp`](https://github.com/lvgl/lvgl/blob/master/src/drivers/display/lovyan_gfx/lv_lgfx_user.hpp) provides a good example of this. Once your configuration file is ready, update `lv_conf.h` to include it, for example: @@ -97,7 +97,7 @@ To make it work, set up TFT_eSPI according to your TFT display type via editing Both files are located in `TFT_eSPI` library's folder inside PlatformIO’s `.pio/libdeps//TFT_eSPI/` directory. -With PlatformIO, you can also override the configuration using build_flags in +With PlatformIO, you can also override the configuration using build_flags in `platformio.ini`, which avoids editing library files directly. For example: @@ -120,9 +120,9 @@ This approach keeps your configuration under version control. - Using `lv_conf.h` -After installing LVGL, copy `lv_conf_template.h` from the LVGL repo into your project +After installing LVGL, copy `lv_conf_template.h` from the LVGL repo into your project and rename it to `lv_conf.h` -Place it in your `include/` or `src/` folder, and enable/disable LVGL features by +Place it in your `include/` or `src/` folder, and enable/disable LVGL features by editing the macros. For example: ```c @@ -198,11 +198,11 @@ build_src_filter = ``` This will include all LVGL `demos` and `examples` in the build. -Once you are ready to work on your own project, you should remove those lines so only your +Once you are ready to work on your own project, you should remove those lines so only your project sources are compiled. -For reference, the [lv_platformio](https://github.com/lvgl/lv_platformio) repository demonstrates -how to set up and run LVGL on different targets, including ESP32, STM32, and a PC simulator (SDL2). +For reference, the [lv_platformio](https://github.com/lvgl/lv_platformio) repository demonstrates +how to set up and run LVGL on different targets, including ESP32, STM32, and a PC simulator (SDL2). This can be very helpful when exploring how LVGL behaves across platforms. ## Debugging and logging diff --git a/docs/src/integration/frameworks/tasmota-berry.mdx b/docs/src/integration/frameworks/tasmota-berry.mdx index 57ec33ce2e..62cf52f1a7 100644 --- a/docs/src/integration/frameworks/tasmota-berry.mdx +++ b/docs/src/integration/frameworks/tasmota-berry.mdx @@ -3,7 +3,7 @@ title: Tasmota and berry description: "Tasmota is a widely used open-source firmware for ESP8266 and ESP32 based devices. It supports a wide variety of devices, sensors and integrations to Home Automation and Cloud services." --- -### What is Tasmota? +## What is Tasmota? [Tasmota](https://github.com/arendst/Tasmota) is a widely used open-source firmware for ESP8266 and ESP32 based devices. It supports a @@ -16,7 +16,7 @@ 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? +## What is Berry? [Berry](https://github.com/berry-lang/berry) is a ultra-lightweight dynamically typed embedded scripting language. It is designed for @@ -25,7 +25,7 @@ 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 +### Highlights of Berry Berry has the following advantages: @@ -42,7 +42,7 @@ All features are detailed in the [Berry Reference Manual](https://github.com/ber --- -### Why LVGL + Tasmota + Berry? +## 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 @@ -54,7 +54,7 @@ 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: +### Tasmota + Berry + LVGL could be used for: - Fast prototyping GUI. - Shortening the cycle of changing and fine-tuning the GUI. @@ -68,13 +68,13 @@ is also under development. --- -### So what does it look like? +## 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 +### A simple example ```python lv.start() # start LVGL @@ -85,12 +85,12 @@ 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? +## 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? +## Where can I find more information? - [Tasmota Documentation](https://tasmota.github.io/docs/) - [Berry Documentation](https://github.com/berry-lang/berry/wiki/Reference) diff --git a/docs/src/integration/overview.mdx b/docs/src/integration/overview.mdx index c0ae2ddc81..f5631e7fd1 100644 --- a/docs/src/integration/overview.mdx +++ b/docs/src/integration/overview.mdx @@ -7,19 +7,18 @@ description: "LVGL is available on GitHub: https://github.com/lvgl/lvgl." ### Clone or Download -LVGL is available on GitHub: https://github.com/lvgl/lvgl. +If you would like to integrate LVGL yourself you can get it from GitHub: https://github.com/lvgl/lvgl. -You can clone it or -[Download](https://github.com/lvgl/lvgl/archive/refs/heads/master.zip) -the latest version of the library from GitHub. +You can clone it or [Download](https://github.com/lvgl/lvgl/archive/refs/heads/master.zip) +the latest version as a ZIP. -In this case, you can copy the `lvgl` into your project, use a -built-in display driver or write your own, and compile LVGL with the + +If you download LVGL yourself you need to save it into your project folder so that it can be compiled with the rest of your source code. ### Frameworks and Package Registries -LVGL is also available as: +LVGL is also available in various frameworks and registries where most of the integration work is already done: - [Arduino library](/integration/frameworks/arduino) - [PlatformIO package](https://registry.platformio.org/libraries/lvgl/lvgl) @@ -31,9 +30,6 @@ LVGL is also available as: - CMSIS-Pack - [RIOT OS package](https://doc.riot-os.org/group__pkg__lvgl.html#details) -Usually, LVGL is ready to use in these frameworks. You can also find a description -at [Integration](/integration). - ### Folder Structure The graphics library itself is the `lvgl` directory. It contains several @@ -81,24 +77,16 @@ lv_conf.h other files and folders in your project ``` -1. Set the define to your compiler - -options (e.g. `-DLV_CONF_INCLUDE_SIMPLE` for GCC compiler) and set the +1. Set the define to your compiler options (e.g. `-DLV_CONF_INCLUDE_SIMPLE` for GCC compiler) and set the include path manually (e.g. `-I../include/gui`). In this case, LVGL will attempt to include `lv_conf.h` simply with `#include "lv_conf.h"` instead of `lvgl/lvgl.h`. -1. Set a custom path via the define. +2. Set a custom path via the define. For example: `-DLV_CONF_PATH="/home/joe/my_project/my_custom_conf.h"`. -For example: `-DLV_CONF_PATH="/home/joe/my_project/my_custom_conf.h"`. +3. Delete some settings from `lv_conf.h` and set them via compile options. For example: `-DLV_COLOR_DEPTH=32 -DLV_USE_BUTTON=1`. -1. Delete some settings from `lv_conf.h` and set them via compile options. - -For example: `-DLV_COLOR_DEPTH=32 -DLV_USE_BUTTON=1`. - -1. To fully skip `lv_conf.h` and use only compiler options (see point 3), - -define as a compiler option. Unset options will get a +4. To fully skip `lv_conf.h` and use only compiler options (see point 3), define as a compiler option. Unset options will get a default value which is the same as the content of `lv_conf_template.h`. ### Kconfig @@ -124,7 +112,7 @@ commands. Here is a list of some useful commands: - `alldefconfig`: Creates a .config with all default values. - `genconfig`: Generates a C header from the config, following `autoconf.h` format. -##### Usage +#### Usage 1. Install the prerequisites using `scripts/install_prerequisites.sh/bat`. 2. Create the configuration (.config) @@ -137,7 +125,7 @@ menuconfig Make changes to the config and exit using `Esc` or `Q`, and save your configuration. The `.config` file is now created and lists the configuration values. -1. Run CMake with the `-DLV_USE_KCONFIG=ON` flag: +3. Run CMake with the `-DLV_USE_KCONFIG=ON` flag: ```bash cd @@ -181,13 +169,13 @@ everything from scratch is also simple. The process can be read in the following 1. Include `lvgl/lvgl.h` 2. Initialize your hardware (clock, peripherals, etc.) -3. Call `lv_init()` to initialize LVGL +3. Call to initialize LVGL ### Tick Interface -Set the tick for LVGL by calling `lv_tick_inc(x)` in a timer interrupt every +Set the tick for LVGL by calling in a timer interrupt every `x` milliseconds, or set a callback that returns the milliseconds elapsed -since startup with `lv_tick_set_cb(my_cb)`. Many platforms have built-in +since startup with . Many platforms have built-in functions that can be used as they are. For example: - SDL: `lv_tick_set_cb(SDL_GetTicks);` @@ -200,14 +188,14 @@ functions that can be used as they are. For example: ### Displays and Input Devices -Create a **Display** (`lv_display`), set the buffers, and the flush callback. +Create a **Display** (), set the buffers, and the flush callback. In practice, this means implementing a single function that can show the rendered image on the screen. It is called a `flush` callback. To learn more about buffering options, see implementation examples and learn more about all the features in [Display (lv_display)](/main-modules/display). Add **Input devices** if needed (touchpad, external buttons, keyboard, etc.) by -creating `lv_indev`s. To do so, a single `read` callback needs to be implemented +creating s. To do so, a single `read` callback needs to be implemented which returns the state of the given input device. Read more about the input device types, their features, and check the examples at [Input devices (lv_indev)](/main-modules/indev). @@ -244,7 +232,7 @@ If `LV_USE_OS` is set, will be the sleep function provided by the operating system, otherwise it will fall back to a blocking delay. Of course, you can use any custom delay, wait, or sleep functions instead. -##### Sleep Management +#### Sleep Management To better control the delay/sleep time, returns the remaining time until the next timer: @@ -456,8 +444,8 @@ void other_thread(void) ## Multiple Instances It is possible to run multiple, independent instances of LVGL in the same firmware. -To enable its multi-instance feature, set in `lv_conf.h -and provide a custom function to using thread` or +To enable its multi-instance feature, set in `lv_conf.h` +and provide a custom function to using `__thread` or `pthread_key_t`. This allows running multiple LVGL instances by storing LVGL's global variables in TLS (Thread-Local Storage). diff --git a/docs/src/integration/pc/sdl.mdx b/docs/src/integration/pc/sdl.mdx index e08e4e4832..f188487390 100644 --- a/docs/src/integration/pc/sdl.mdx +++ b/docs/src/integration/pc/sdl.mdx @@ -11,7 +11,7 @@ a PC. The [Eclipse](https://github.com/lvgl/lv_port_pc_eclipse), [VSCode](https://github.com/lvgl/lv_port_pc_vscode), and [Generic Linux](https://github.com/lvgl/lv_port_linux) -projects of LVGL use SDL to open a window and manage input devices. +projects of LVGL use SDL to open a window and manage [input devices](/main-modules/indev). As SDL is fully cross-platform, it is easy to integrate into any environment. @@ -21,8 +21,8 @@ Install SDL according to your platform: - Linux: `sudo apt install libsdl2-dev` - macOS: `brew install sdl2` -- Windows: Recommended: [vcpkg install sdl2` - Alternatively, you can download prebuilt SDL2 binaries from the `SDL website](https://www.libsdl.org/download-2.0.php) and follow their installation instructions. +- Windows: Recommended: `vcpkg install sdl2`. + Alternatively, you can download prebuilt SDL2 binaries from the [SDL website](https://www.libsdl.org/download-2.0.php) and follow their installation instructions. ## Configuration @@ -83,15 +83,15 @@ When building for 32-bit architecture, add the following workaround at the begin The SDL driver supports multiple rendering backends that determine how LVGL renders content to the screen. Each backend offers different performance characteristics and use cases. -# Standard Software Rendering (Default) +### Standard Software Rendering (Default) By default, the SDL driver uses pure software rendering with no additional configuration required. **Configuration:** -No additional configuration needed - this is the default when only `LV_USE_SDL 1` is enabled. +No additional configuration needed - this is the default when only is enabled. -# SDL Draw Unit +### SDL Draw Unit The SDL Draw Unit uses software rendering to create SDL textures which are then cached and blended together by the GPU, providing a hybrid approach that combines software rendering flexibility with hardware-accelerated texture composition. @@ -105,7 +105,7 @@ providing a hybrid approach that combines software rendering flexibility with ha For complete details, see [SDL Draw Unit](/integration/embedded_linux/draw_units/draw_sdl). -# OpenGL-Based Rendering +### OpenGL-Based Rendering The SDL driver can leverage OpenGL for hardware-accelerated rendering. LVGL provides two OpenGL-based rendering options: @@ -117,7 +117,7 @@ The SDL driver can leverage OpenGL for hardware-accelerated rendering. LVGL prov #define LV_USE_OPENGLES 1 /* For NanoVG Draw Unit*/ -#define LV_USE_DRAW_NANOVG 1 +#define LV_USE_DRAW_NANOVG 1 #define LV_USE_NANOVG 1 /* For OpenGL Draw Unit */ diff --git a/docs/src/integration/pc/uefi.mdx b/docs/src/integration/pc/uefi.mdx index eeb29fec6e..634982a8d7 100644 --- a/docs/src/integration/pc/uefi.mdx +++ b/docs/src/integration/pc/uefi.mdx @@ -28,19 +28,19 @@ You need the following UEFI protocols available: #define LV_USE_UEFI 1 ``` -- Enable the memory core functions, which are wrappers around `AllocatePool` and `FreePool` (using memory of type *EfiBootServicesData*) if you do not want to use your own implementations +2. Enable the memory core functions, which are wrappers around `AllocatePool` and `FreePool` (using memory of type *EfiBootServicesData*) if you do not want to use your own implementations ```c #define LV_UEFI_USE_MEMORY_SERVICES 1 ``` -1. Enable file system support for the volume the application was loaded from (defaults to drive letter `E`): +3. Enable file system support for the volume the application was loaded from (defaults to drive letter `E`): ```c #define LV_USE_FS_UEFI 1 ``` -1. Include UEFI type definitions. There are predefined includes for EDK2 and GNU-EFI: +4. Include UEFI type definitions. There are predefined includes for EDK2 and GNU-EFI: ```c #define LV_USE_UEFI_INCLUDE diff --git a/docs/src/integration/rtos/freertos.mdx b/docs/src/integration/rtos/freertos.mdx index 47fdf460e5..7a75a3f02a 100644 --- a/docs/src/integration/rtos/freertos.mdx +++ b/docs/src/integration/rtos/freertos.mdx @@ -5,10 +5,10 @@ description: "To enable LVGL's FreeRTOS support, just set LV_USE_OS LV_OS_FREERT ## Usage -To enable LVGL's FreeRTOS support, just set `LV_USE_OS LV_OS_FREERTOS` in -`lv_conf.h`. After this, LVGL: +To enable LVGL's FreeRTOS support, just set to + in `lv_conf.h`. After this, LVGL: -- GPUs will yield the task while waiting for the GPU to complete (lowering CPU usage) +- will yield the task while waiting for the GPU to complete (lowering CPU usage) - will return the OS-aware CPU usage - will be a wrapper to `vTaskDelay` @@ -38,10 +38,10 @@ implementation. Then, you can provide a custom implementation of ## Example: Custom implementation for ESP32 SMP -For multi-core environments like the ESP32 (which uses dual-core SMP), the default -implementation might not track all idle tasks. Below is an example of a custom -implementation using `uxTaskGetSystemState()`. This requires -`configGENERATE_RUN_TIME_STATS` and `configUSE_TRACE_FACILITY` to be enabled +For multi-core environments like the ESP32 (which uses dual-core SMP), the default +implementation might not track all idle tasks. Below is an example of a custom +implementation using `uxTaskGetSystemState()`. This requires +`configGENERATE_RUN_TIME_STATS` and `configUSE_TRACE_FACILITY` to be enabled in your `FreeRTOSConfig.h` (or via menuconfig for ESP-IDF). ```c diff --git a/docs/src/integration/rtos/nuttx.mdx b/docs/src/integration/rtos/nuttx.mdx index e725faed9b..3290b8449c 100644 --- a/docs/src/integration/rtos/nuttx.mdx +++ b/docs/src/integration/rtos/nuttx.mdx @@ -102,7 +102,7 @@ The NuttX simulator allows you to run NuttX and LVGL on your PC. This can be especially useful for developing LVGL UIs with immediate visual feedback, and also developing platform independent NuttX apps. -##### Configure NuttX to use the `sim` board and the LVGL Demo +#### Configure NuttX to use the `sim` board and the LVGL Demo ```bash $ ./tools/configure.sh sim:lvgl_fb @@ -116,7 +116,7 @@ $ ls -l nuttx -rwxr-xr-x 1 root root 2819920 May 12 15:01 nuttx ``` -##### Running the NuttX Simulator +#### Running the NuttX Simulator ```bash $ ./nuttx @@ -133,7 +133,7 @@ nsh> lvgldemo If you don't have an STM32F429I-DISCO, this process will be similar for other boards. -##### Configure NuttX to use the stm32f429i-disco board and the LVGL Demo +#### Configure NuttX to use the stm32f429i-disco board and the LVGL Demo ```bash $ ./tools/configure.sh stm32f429i-disco:lvgl @@ -148,7 +148,7 @@ $ ls -l nuttx.bin -rwxrwxr-x 1 alan alan 287144 Jun 27 09:26 nuttx.bin ``` -##### Flashing the firmware in the board using OpenOCD +#### Flashing the firmware in the board using OpenOCD ```bash $ sudo openocd -f interface/stlink-v2.cfg -f target/stm32f4x.cfg -c init -c "reset halt" -c "flash write_image erase nuttx.bin 0x08000000" @@ -165,7 +165,7 @@ nsh> lvgldemo The example app called `lvgldemo` uses LVGL's NuttX integration to run the demos in NuttX. -https://github.com/apache/nuttx-apps/tree/master/examples/lvgldemo +[examples/lvgldemo](https://github.com/apache/nuttx-apps/tree/master/examples/lvgldemo) It is used by all LVGL defconfigs. See `sim:lvgl_fb` and `sim:lvgl_lcd`. @@ -224,7 +224,7 @@ to allocate from the NuttX global heap or use its own. NuttX tries to be POSIX compliant where possible, meaning it supports pthreads (POSIX threads). To enable OS features in LVGL on NuttX, set to . -The main reason for enabling OS features is for multi-core rendering. +The main reason for enabling OS features is for [multi-core rendering](/main-modules/draw/draw_units). See . Otherwise there is no case for setting it. diff --git a/docs/src/integration/rtos/qnx.mdx b/docs/src/integration/rtos/qnx.mdx index 59c2fa9308..3929e170f5 100644 --- a/docs/src/integration/rtos/qnx.mdx +++ b/docs/src/integration/rtos/qnx.mdx @@ -30,7 +30,7 @@ a static library. ### Include LVGL in Your Project -Follow the generic instructions for getting started with LVGL. After copying +Follow the generic instructions for [getting started](/getting_started/porting) with LVGL. After copying `lv_conf_template.h` to `lv_conf.h` make the following changes to the latter: 1. Enable QNX support: @@ -39,13 +39,13 @@ Follow the generic instructions for getting started with LVGL. After copying #define LV_USE_QNX 1 ``` -1. Set colour depth to 32: +2. Set colour depth to 32: ```c #define LV_COLOR_DEPTH 32 ``` -1. (Optional) Enable double-buffering: +3. (Optional) Enable double-buffering: ```c #define LV_QNX_BUF_COUNT 2 @@ -120,7 +120,7 @@ main(int argc, char **argv) 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_set_style_text_color(label, lv_color_hex(0xffffff), LV_PART_MAIN); lv_obj_align(label, LV_ALIGN_CENTER, 0, 0); /* Run the event loop until it exits. */ diff --git a/docs/src/integration/rtos/rt-thread.mdx b/docs/src/integration/rtos/rt-thread.mdx index 21615a92de..b29efe37eb 100644 --- a/docs/src/integration/rtos/rt-thread.mdx +++ b/docs/src/integration/rtos/rt-thread.mdx @@ -3,7 +3,7 @@ title: "RT-Thread RTOS" description: "RT-Thread is an open source, neutral, and community-based real-time operating system (RTOS). RT-Thread has Standard version and Nano version." --- -### What is RT-Thread? +## What is RT-Thread? [RT-Thread](https://www.rt-thread.io/) is an [open source](https://github.com/RT-Thread/rt-thread), neutral, and @@ -18,7 +18,7 @@ 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 +### Key features - Designed for resource-constrained devices, the minimum kernel requires only 1.2KB of RAM and 3 KB of Flash. @@ -33,19 +33,19 @@ effects, and so on. - 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? +## 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) +[software package](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 Board-Support Packages (BSPs): +RT-Thread community has ported LVGL to several Board-Support Packages (BSPs): | BSP | BSP | | --- | --- | @@ -63,7 +63,7 @@ RT-Thread community has port LVGL to several Board-Support Packages (BSPs): | Infineon psoc6-evaluationkit-062S2 | NXP imxrt1060-evk | | Raspberry PICO | NXP LPC55S69 | -##### Tutorials +### Tutorials - Introduce about RT-Thread and how to run LVGL on RT-Thread in simulators - How to import a BSP project with latest code into RT-Thread Studio @@ -71,8 +71,6 @@ RT-Thread community has port LVGL to several Board-Support Packages (BSPs): - RT-Thread Youtube Channel - RT-Thread documentation center -https://www.youtube.com/watch?v=k7QYk6hSwnc - -https://www.youtube.com/watch?v=fREPLuh-h8k - -https://www.youtube.com/watch?v=O_QA99BxnOE +- [Run LVGL on RT-Thread in a simulator](https://www.youtube.com/watch?v=k7QYk6hSwnc) +- [Import a BSP project into RT-Thread Studio](https://www.youtube.com/watch?v=fREPLuh-h8k) +- [Use LVGL with RT-Thread Studio on the STM32F469 Discovery board](https://www.youtube.com/watch?v=O_QA99BxnOE) diff --git a/docs/src/integration/rtos/zephyr.mdx b/docs/src/integration/rtos/zephyr.mdx index eefbd5c078..a8a30f24af 100644 --- a/docs/src/integration/rtos/zephyr.mdx +++ b/docs/src/integration/rtos/zephyr.mdx @@ -3,7 +3,7 @@ title: Zephyr description: "Zephyr is an open source 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 application..." --- -### What is Zephyr? +## What is Zephyr? [Zephyr](https://zephyrproject.org/) is an [open source](https://github.com/zephyrproject-rtos/zephyr) real-time operating @@ -15,7 +15,7 @@ Zephyr is built with an emphasis on broad chipset support, security, dependability, long-term support releases and a growing open source ecosystem. -##### Highlights of Zephyr +### Highlights of Zephyr - **Small** - Runs on microcontrollers as small as 8 kB Flash and 5 kB of RAM. @@ -32,7 +32,7 @@ growing open source ecosystem. - **Compliant** - Apps are runnable as native Linux applications, which simplifies debugging and profiling. -### How to run LVGL on Zephyr? +## How to run LVGL on Zephyr? To set up your development environment refer to the [getting started guide](https://docs.zephyrproject.org/latest/develop/getting_started/index.html). @@ -44,7 +44,7 @@ You can check the list of available boards using: $ 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` +After you chose a board you can build one of the LVGL demos for it. Here we are using the `native_posix` board, which allows for running the application on your posix compliant host system: ```bash @@ -66,12 +66,12 @@ $ 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 +## Leveraging Zephyr Features -##### Shell +### 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). +`CONFIG_SHELL` and `CONFIG_LV_Z_SHELL` (the demos from above have it enabled by default). The shell offers enabling/disabling of LVGL monkeys: @@ -92,9 +92,9 @@ uart$ lvgl stats memory For more details refer to the [shell documentation](https://docs.zephyrproject.org/latest/services/shell/index.html). -##### Devicetree +### Devicetree -Zephyr uses the devicetree description language to create and manage LVGL input devices. +Zephyr uses the devicetree description language to create and manage LVGL [input devices](/main-modules/indev/overview). The pseudo device binding descriptions can be found at: @@ -103,9 +103,9 @@ The pseudo device binding descriptions can be found at: - [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 +Essentially those buffer the `input_event` generated by the device pointed to by the `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. +they are created at application start up before `main()` is executed. Most boards or shields that have a display or display connector have the pointer input device already declared: @@ -116,8 +116,8 @@ lvgl_pointer { }; ``` -You can access the underlying lvgl :code:`lv_indev_t` for configuration. -Example with the encoder device to assign a :code:`lv_group_t`: +You can access the underlying lvgl for configuration. +Example with the encoder device to assign a : ```c const struct device *lvgl_encoder = DEVICE_DT_GET(DT_COMPAT_GET_ANY_STATUS_OKAY(zephyr_lvgl_encoder_input)); @@ -134,7 +134,7 @@ lv_group_add_obj(arc_group, arc); lv_indev_set_group(lvgl_input_get_indev(lvgl_encoder), arc_group); ``` -##### Kconfig +### Kconfig Aside from enabling the shell you can also use Kconfig to fine-tune the footprint of your application. @@ -151,28 +151,28 @@ 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 +### 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. +- **CONFIG_LV_Z_VDB_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 +### Zephyr >= 3.7.0 Specific Options -For Zephyr versions 3.7.0 and below, additional options are available to manage LVGL's frame flushing: +For Zephyr versions 3.7.0 and above, 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? +## Where can I find more information? - Zephyr Documentation: [Zephyr Documentation](https://docs.zephyrproject.org/latest/index.html) - Zephyr mailing list: [Zephyr Mailing diff --git a/docs/src/introduction/faq.mdx b/docs/src/introduction/faq.mdx index 7020781691..cb476e29ed 100644 --- a/docs/src/introduction/faq.mdx +++ b/docs/src/introduction/faq.mdx @@ -1,25 +1,32 @@ --- title: FAQ -description: "You can ask questions in the forum: https://forum.lvgl." +description: "Check these questions and answers first to quickly solve common issues" --- -## Where can I ask questions? +## Where can I ask questions from the community? -You can ask questions in the forum: https://forum.lvgl.io/. +You can ask questions in the [forum](https://forum.lvgl.io/). We use [GitHub issues](https://github.com/lvgl/lvgl/issues) for development related discussion. You should use them only if your question or issue is tightly related to the development of the library. Before posting a question, please read this FAQ section since you might find the answer to your issue here as well. -## Is my MCU/hardware supported? +## Where can I get professional support? -Every MCU which is capable of driving a display via parallel port, SPI, RGB interface or anything else and fulfills the [Requirements](/introduction/requirements) is supported by LVGL. +LVGL LTD, the company behind LVGL, provides UI development services, consultancy, and training. We also have a wide range of +partners globally, so we can connect you with trusted local experts. + +Contact us via [lvgl@lvgl.io](mailto:lvgl@lvgl.io) + +## Is my MCU or MPU supported? + +Every MCU and MPU which is capable of driving a display via parallel port, SPI, RGB interface or anything else and fulfills the [Requirements](/introduction/requirements) is supported by LVGL. This includes: -- "Common" MCUs like STM32F, STM32H, NXP Kinetis, LPC, iMX, dsPIC33, PIC32, SWM341 etc. -- Bluetooth, GSM, Wi-Fi modules like Nordic NRF, Espressif ESP32 and Raspberry Pi Pico W +- "Common" MCUs like STM32F, STM32H, NXP Kinetis, LPC, iMX, PIC32, TI AMxxx, etc. +- Bluetooth, GSM, Wi-Fi modules like Nordic NRF, Espressif ESP32 and Raspberry Pi Pico - Linux with frame buffer device such as /dev/fb0. This includes Single-board computers like the Raspberry Pi - Anything else with a strong enough MCU and a peripheral to drive a display @@ -42,26 +49,22 @@ See the [Display (lv_display)](/main-modules/display) section to learn more. ## LVGL doesn't start, randomly crashes or nothing is drawn on the display. What might be the problem? - Try increasing . -- Be sure your display works without LVGL. E.g. paint it to red on start up. +- Be sure that your display works without LVGL. E.g. paint it to red on start up. - Enable [Logging](/debugging/log). - Enable assertions in `lv_conf.h` (`LV_USE_ASSERT_...`). -- If you use an RTOS: - - * Increase the stack size of the task that calls . - * Be sure you are using one of the methods for thread management as described in [Operating Systems and Threads](/integration/overview). +- If you use an RTOS, increase the stack size of the task that calls . ## My display driver is not called. What have I missed? -Be sure you are calling as prescribed in -[Tick Interface](/integration/overview) and are calling as prescribed in -[Timer Handler](/integration/overview). - -Learn more in the [Tick Interface](/integration/overview) and [Timer Handler](/integration/overview) sections. +Be sure you are calling or have set + as described in +[Tick Interface](/integration/overview#tick-interface) and are calling as described in +[Timer Handler](/integration/overview#timer-handler). ## Why is the display driver called only once? Only the upper part of the display is refreshed. -Be sure you are calling at the end of your -"*display flush callback*" as per the [Flush Callback](/main-modules/display/setup) section. +Be sure you are calling at the end of your +"*display flush callback*" as per the [Flush Callback](/main-modules/display/setup#flush-callback) section. ## Why do I see only garbage on the screen? @@ -90,28 +93,37 @@ for(i = 0; i < BUF_WIDTH; i++) { The configured LVGL color format is probably not compatible with your display's color format. Check in *lv_conf.h*. +If you're using a 16 bit (RGB565) display connected via SPI the bytes might be swapped. Try +setting + + ## How do I speed up my UI? -- Turn on compiler optimization and enable instruction- and data-caching if your MCU has them. -- Increase the size of the display buffer. -- Use two display buffers and flush the buffer with DMA (or similar peripheral) in the background. +- Turn on compiler optimization +- Enable instruction- and data-caching if your MCU has them. - Increase the clock speed of the SPI or parallel port if you use them to drive the display. - If your display has an SPI port consider changing to a model with a parallel interface because it has much higher throughput. +- In case of [Partial rendering mode](/main-modules/display/setup#draw-buffers): + - Increase the size of the display buffer. 1/10 screen size is the minimum, but 1/5 is recommended + - Use two display buffers and flush the buffer with DMA (or similar peripheral) in the background. +- If you have enough RAM use [Direct rendering mode](/main-modules/display/setup#draw-buffers) with 2 frame buffers and: + - Switch only the frame buffer address in the `flush_cb` + - Call from the VSYNC ready interrupt, so that you are not blocking while waiting for the frame buffer switch - Keep the display buffer in internal RAM (not in external SRAM) because LVGL uses it a lot and it should have fast access time. - Consider minimizing LVGL CPU overhead by updating Widgets: - - - only once just before each display refresh, and - - only when it will change what the end user sees. + - Only once just before each display refresh, and + - Only when it will change what the end user sees. ## How do I reduce flash/ROM usage? -You can disable unused features (such as animations, file system, GPU etc.) and widget types in *lv_conf.h*. +You can disable unused features (such as widgets, file system, GPU etc.) and widget types in *lv_conf.h*. If you are using GCC/CLANG you can add `-fdata-sections -ffunction-sections` compiler flags and `--gc-sections` linker flag to remove unused functions and variables from the final binary. If possible, add the `-flto` compiler flag to enable link-time-optimisation together with `-Os` for GCC or `-Oz` for CLANG and newer GCC versions. ## How do I reduce RAM usage? -- Lower the size of the *Display buffer*. +- In case of [Partial rendering mode](/main-modules/display/setup#draw-buffers) lower the size of the *Display buffer(s)*. +- Switch to Partial rendering mode from Direct or Full rendering mode - Reduce in *lv_conf.h*. This memory is used when you create Widgets like buttons, labels, etc. - To work with lower you can create Widgets only when required and delete them when they are no longer needed. @@ -119,5 +131,7 @@ If you are using GCC/CLANG you can add `-fdata-sections -ffunction-sections` com To work with an operating system where tasks can interrupt each other (preemptively), you must ensure that no LVGL function call be called while another LVGL call is in -progress. There are several ways to do this. See the [Operating Systems and Threads](/integration/overview) section to +progress. LVGL has built-in mechanisms to support this, and also has built-in support to use mainstream operating systems out of the box. + +There are several ways to do this. See the [Operating Systems and Threads](/integration/overview#operating-system-support) section to learn more. diff --git a/docs/src/introduction/index.mdx b/docs/src/introduction/index.mdx index e0825cdc39..c205da8a36 100644 --- a/docs/src/introduction/index.mdx +++ b/docs/src/introduction/index.mdx @@ -3,46 +3,22 @@ title: Introduction description: "LVGL (Light and Versatile Graphics Library) is a free and open-source C graphics library providing everything you need to create an embedded GUI with easy-to-use graphical elements, beautiful visua..." --- -LVGL (Light and Versatile Graphics Library) is a free and open-source C graphics + +**LVGL** (Light and Versatile Graphics Library) is a free and open-source graphics library providing everything you need to create an embedded GUI with easy-to-use -graphical elements, beautiful visual effects, and a low memory footprint. +mobile-phone-like graphical elements, beautiful visual effects, and a low memory +footprint. -LVGL provides the "GUI engine" that handles all end-user interaction with your -application, including not only drawing the contents of the display and accepting -user input and turning it into events "catchable" by the application, but also -providing 30+ built-in widgets, 100+ style properties, scrolling, animations, -advanced software rendering, built-in GPU support from MCUs to OpenGL, and much more. -The combination of these enable you to efficiently develop UIs without having to -re-invent the wheel. +LVGL provides 30+ built-in widgets, 100+ style properties, scrolling, animations, +advanced software rendering, built-in GPU support from MCUs to OpenGL, user input and +event support, and much more. -Using LVGL in a firmware project effectively reduces the GUI-developer's job to -defining the GUI and furnishing it with appropriate event hooks to carry out the -valuable work of the GUI. +You can think of LVGL as a collection of C and H files that can be dropped into +any project to add UI capabilities to the product. LVGL can be compiled by any build system and +integrated into any environment and framework. -LVGL can use GUIs that are 100% defined in C code you write (for which any updates to -the GUI require modifying that C code and re-flashing the firmware), or GUI -definitions provided in XML files (for which updates to the GUI require only -modifying the XML files that define the GUI for that firmware), or any combination of -these two that suits your project. +**LVGL Pro** is the official UI Editor toolkit for LVGL, allowing you to speed up UI development +by defining reusable UI components in XML, integrating with Figma, and more professional features. +Learn more at [https://lvgl.io/pro](https://lvgl.io/pro) -## Key Features - -- Powerful building blocks such as [buttons, charts, lists, sliders, images](/widgets), etc. -- Advanced graphics with animations, anti-aliasing, opacity, smooth scrolling -- Various input devices such as touchpad, mouse, keyboard, encoder, etc. -- Multi-language support with UTF-8 encoding -- Multi-display support, even with mixed color formats -- Fully customizable graphic elements with CSS-like styles -- Hardware independent: use with any microcontroller or display -- Scalable: able to operate with little memory (64 kB Flash, 16 kB RAM) -- [OS](/integration/overview), external memory and [GPU](/main-modules/draw) are supported but not required -- Single frame buffer operation even with advanced graphic effects -- Written in C for maximal compatibility (C++ compatible) -- [Simulator](/integration/pc) to start embedded GUI design on a PC without embedded hardware -- User code developed under simulator can be shared with firmware to make UI development more efficient. -- Binding to MicroPython -- Tutorials, examples, themes for rapid GUI design -- Documentation is available online -- Free and open-source under MIT license -- Free for commercial projects diff --git a/docs/src/introduction/key_features.mdx b/docs/src/introduction/key_features.mdx new file mode 100644 index 0000000000..cbd401ce89 --- /dev/null +++ b/docs/src/introduction/key_features.mdx @@ -0,0 +1,48 @@ +--- +title: Key features +description: "LVGL provides all the features to build smartphone-like UIs with a small memory footprint, scalable across MCUs, MPUs and vendors." +--- + +## Graphical features + +- Powerful building blocks such as [buttons, charts, lists, sliders, images](/widgets), etc. +- Advanced graphics with animations, anti-aliasing, opacity, smooth scrolling +- Various input devices such as touchpad, mouse, keyboard, encoder, etc. +- Multi-language support with UTF-8 encoding +- Multi-display support, even with mixed color formats +- Fully customizable graphic elements with CSS-like styles + +## Scalability and Portability + +- Hardware independent: use with any microcontroller or display +- Scalable: able to operate with little memory (64 kB Flash, 16 kB RAM) +- [OS](/integration/overview), external memory and [GPU](/main-modules/draw) are supported but not required +- Single frame buffer operation even with advanced graphic effects +- Written in C for maximal compatibility (C++ compatible) +- [Simulator](/integration/pc) to start embedded GUI design on a PC without embedded hardware +- User code developed under simulator can be shared with firmware to make UI development more efficient. + + +## Developer Experience +- Tutorials, examples, themes for rapid GUI design +- Documentation is available online + + +## Licensing + +- Free and open-source under MIT license +- Free for commercial projects + +## Advanced tooling + +[LVGL Pro](https://lvgl.io/pro), the UI Editor tooling of LVGL, dramatically speeds up UI development and team work: + +- Develop UI much faster in XML +- Effectively build cross-product UI libraries +- Collaborate better with your team by sharing projects in the browser +- Easily add and run UI tests +- Integrate well with AI and Figma based workflows +- Export code in C or load XML based UI at runtime + +Learn more about the licensing options at [https://lvgl.io/pro/pricing](https://lvgl.io/pro/pricing) + diff --git a/docs/src/introduction/license.mdx b/docs/src/introduction/license.mdx index 0e9ff83b34..18d17756c3 100644 --- a/docs/src/introduction/license.mdx +++ b/docs/src/introduction/license.mdx @@ -1,19 +1,35 @@ --- title: License -description: "The LVGL project (including all repositories) is licensed under the MIT license. This means you can use it even in commercial projects." +description: "Learn the obligations to use LVGL in commercial projects" --- +## Using LVGL + The LVGL project (including all repositories) is licensed under the [MIT license](https://github.com/lvgl/lvgl/blob/master/LICENCE.txt). This means you can use it even in commercial projects. -It is not mandatory, but we highly appreciate it if you write a few words about your -project in the [My projects](https://forum.lvgl.io/c/my-projects/10) category of -the forum or a private message to [lvgl.io](https://lvgl.io/#contact). -Although you can get LVGL for free there is a massive amount of work behind it. It's -created by a group of volunteers who made it available for you in their free time. +## Supporting LVGL + +If LVGL was useful for you in your project, please: +- Write a few words about your project in the [My projects](https://forum.lvgl.io/c/my-projects/10) category of the forum +- Write a LinkedIn post about your project and tag `@lvgl` +- Add a guest post at [lvgl.io/blog](https://lvgl.io/blog) +- Let us write a [User story](https://lvgl.io/case-studies) about your project. + + +Contact us via [lvgl@lvgl.io](mailto:lvgl@lvgl.io). + + +## Related products + +[LVGL Pro](https://lvgl.io/pro), the UI Editor tooling of LVGL, is a commercial product allowing you to: +- Develop UI much faster in XML +- Effectively build cross-product UI libraries +- Collaborate better with your team by sharing projects in the browser +- Easily add and run UI tests +- Integrate well with AI and Figma based workflows +- Export code in C or load XML based UI at runtime + +Learn more about the licensing options at [https://lvgl.io/pro/pricing](https://lvgl.io/pro/pricing) -To make the LVGL project sustainable, please consider [Contributing](/contributing) to the -project. You can choose from many different ways of contributing. See -[Contributing](/contributing) such as simply writing a tweet about you using LVGL, fixing bugs, -translating the documentation, or even becoming a maintainer. diff --git a/docs/src/introduction/meta.json b/docs/src/introduction/meta.json index 387fb61255..b7a640c00c 100644 --- a/docs/src/introduction/meta.json +++ b/docs/src/introduction/meta.json @@ -1,9 +1,10 @@ { - "title": "Key Features", + "title": "Introduction", "pages": [ + "key_features", "requirements", "license", - "faq", - "repo" + "policies", + "faq" ] } diff --git a/docs/src/introduction/repo.mdx b/docs/src/introduction/policies.mdx similarity index 92% rename from docs/src/introduction/repo.mdx rename to docs/src/introduction/policies.mdx index 8368173dbb..083c146647 100644 --- a/docs/src/introduction/repo.mdx +++ b/docs/src/introduction/policies.mdx @@ -1,6 +1,6 @@ --- -title: The LVGL Repository -description: All repositories of the LVGL project are hosted on GitHub. +title: Policies +description: Learn about release policies and version support --- ## Repository layout @@ -13,7 +13,7 @@ You will find these repositories at the following locations: - [blog](https://github.com/lvgl/blog): Source of the [blog's site](https://blog.lvgl.io) - [sim](https://github.com/lvgl/sim): Source of the [online simulator's site](https://sim.lvgl.io) - [lv_port_*](https://github.com/lvgl?q=lv_port&type=&language=): LVGL ports to development boards and other platforms -- [lv_binding_*](https://github.com/lvgl?q=lv_binding&type=&language=l): Bindings to other languages +- [lv_binding_*](https://github.com/lvgl?q=lv_binding&type=&language=): Bindings to other languages ## Release policy @@ -60,6 +60,6 @@ Starting from v8, every minor release is supported for 1 year. | v9.0 | 22 Jan, 2024 | 22 Jan, 2025 | No | | v9.1 | 20 Mar, 2024 | 20 Mar, 2025 | No | | v9.2 | 26 Aug, 2024 | 26 Aug, 2025 | No | -| v9.3 | 3 June, 2025 | 3 June, 2026 | Yes | +| v9.3 | 3 June, 2025 | 3 June, 2026 | No | | v9.4 | 16 Oct, 2025 | 16 Oct, 2026 | Yes | | v9.5 | 18 Feb, 2026 | 18 Feb, 2027 | Yes | diff --git a/docs/src/introduction/requirements.mdx b/docs/src/introduction/requirements.mdx index bb6ff80076..5d3283645d 100644 --- a/docs/src/introduction/requirements.mdx +++ b/docs/src/introduction/requirements.mdx @@ -1,28 +1,29 @@ --- title: Requirements -description: "Basically, every modern controller which is able to drive a display is suitable to run LVGL." +description: "Learn the minimal memory and other requirements to run LVGL." --- Basically, every modern controller which is able to drive a display is suitable to run LVGL. The minimal requirements are: -- 16, 32 or 64 bit microcontroller or processor -- > 16 MHz clock speed is recommended -- Flash/ROM: > 64 kB for the very essential components (> 180 kB is recommended) -- RAM: - +- **Processor**: 16, 32 or 64 bit microcontroller or processor (> 16 MHz clock speed is recommended) +- **Flash/ROM**: > 64 kB for the very essential components (> 180 kB is recommended) +- **RAM**: + * Static RAM usage: ~2 kB depending on the used features and Widget types - * stack: > 2kB (> 8 kB recommended) + * Stack: > 2kB (> 8 kB recommended) * Dynamic data (heap): > 2 KB (> 48 kB is recommended if using many GUI Widgets). Set by in `lv_conf.h`. - * Display buffer: > *"Horizontal resolution"* pixels (> 10 X *"Horizontal resolution"* is recommended) + * Display buffer: > *"Horizontal resolution"* pixels (> 10 × *"Horizontal resolution"* is recommended) * One frame buffer in the MCU or in an external display controller +- **Operating system**: Bare metal or any RTOS (FreeRTOS, Zephyr, NuttX, etc.) or desktop OS (e.g. Linux) +- **Frameworks**: CMake, Make, Managed builds (e.g. Eclipse), Arduino, Chip vendor IDEs, also easy to integrate into any build system +- **GPU**: LVGL has its own software rendering engine, but GPUs in MCUs can be enabled in `lv_conf.h`. OpenGL ES is needed only to render [glTF](/libs/gltf) - C99 or newer compiler - Basic C (or C++) knowledge: - - * [pointers](https://www.tutorialspoint.com/cprogramming/c_pointers.htm). - * [structs](https://www.tutorialspoint.com/cprogramming/c_structures.htm). - * [callbacks](https://www.geeksforgeeks.org/c/callbacks-in-c/). + * [Pointers](https://www.tutorialspoint.com/cprogramming/c_pointers.htm). + * [Structs](https://www.tutorialspoint.com/cprogramming/c_structures.htm). + * [Callbacks](https://www.geeksforgeeks.org/c/callbacks-in-c/). *Memory usage may vary depending on architecture, compiler and build options.* diff --git a/docs/src/meta.json b/docs/src/meta.json index e1a9c5ff9f..caa5fc9c47 100644 --- a/docs/src/meta.json +++ b/docs/src/meta.json @@ -2,7 +2,6 @@ "pages": [ "introduction", "getting_started", - "examples", "integration", "main-modules", "common-widget-features", @@ -11,12 +10,9 @@ "auxiliary-modules", "libs", "debugging", - "guides", - "migration-v10", + "examples", "contributing", "api", - "api-private", - "CHANGELOG", - "deprecated" + "changelog" ] }