1====== 2Zephyr 3====== 4 5What is Zephyr? 6--------------- 7 8`Zephyr <https://zephyrproject.org/>`__ is an `open 9source <https://github.com/zephyrproject-rtos/zephyr>`__ real-time operating 10system (RTOS) that is easy to deploy, secure, connect and manage. 11It has a growing set of software libraries that can be used 12across various applications and industry sectors such as 13Industrial IoT, wearables, machine learning and more. 14Zephyr is built with an emphasis on broad chipset support, 15security, dependability, longterm support releases and a 16growing open source ecosystem. 17 18Highlights of Zephyr 19~~~~~~~~~~~~~~~~~~~~ 20 21- **Small** - Runs on microcontrollers as small as 8 kB Flash 22 and 5 kB of RAM. 23- **Scalable** - Usable for complex multicore systems. 24- **Customizable** - Out-of-the-box support for 500+ boards 25 and high portability. 26- **Secure** - Built with safety and security in mind, 27 offers Long-term support. 28- **Ecosystem** - Zephyr not only provides the RTOS kernel but 29 also developer tooling, device drivers, connectivity, logging, 30 tracing, power management and much more. 31- **Decoupling** - Leverages devicetree to describe and 32 configure the target system. 33- **Compliant** - Apps are runnable as native Linux applications, 34 which simplifies debugging and profiling. 35 36How to run LVGL on Zephyr? 37-------------------------- 38 39To setup your development environment refer to the 40`getting started guide <https://docs.zephyrproject.org/latest/develop/getting_started/index.html>`__. 41 42After you completed the setup above you can check out all of the `provided samples <https://docs.zephyrproject.org/latest/samples/>`__ for various boards. 43You can check the list of available boards using: 44 45.. code-block:: shell 46 47 $ west boards 48 49After you chose a board you can build one of the LVGL demos for it. Here we are using the :code:`native_posix` 50board, which allows for running the application on your posix compliant host system: 51 52.. code-block:: shell 53 54 $ west build -b native_posix samples/modules/lvgl/demos 55 56To run the application on your host: 57 58.. code-block:: shell 59 60 $ west build -t run 61 62In case you chose any of the other supported boards you can flash to the device with: 63 64.. code-block:: shell 65 66 $ west flash 67 68If you want to build any of the other demo applications check out the samples 69`README <https://docs.zephyrproject.org/latest/samples/modules/lvgl/demos/README.html>`__. 70 71Leveraging Zephyr Features 72-------------------------- 73 74Shell 75~~~~~ 76 77Zephyr includes a powerful shell implementation that can be enabled with the Kconfig symbols 78:code:`CONFIG_SHELL` and :code:`CONFIG_LV_Z_SHELL` (the demos from above have it enabled by default). 79 80The shell offers enabling/disabling of LVGL monkeys: 81 82.. code-block:: shell 83 84 # Create a new monkey with the given indev type 85 uart$ lvgl monkey create [pointer|keypad|button|encoder] 86 87 # Enable/Disable a monkey 88 uart$ lvgl monkey set <index> <inactive/active> 89 90This is useful for checking your application for memory leaks and other bugs. 91Speaking of memory leaks, you can also acquire stats of the memory used by LVGL 92 93.. code-block:: shell 94 95 uart$ lvgl stats memory 96 97For more details refer to the `shell documentation <https://docs.zephyrproject.org/latest/services/shell/index.html>`__. 98 99Devicetree 100~~~~~~~~~~ 101 102Zephyr uses the devicetree description language to create and manage LVGL input devices. 103 104The pseudo device binding descriptions can be found at: 105 106- `button input <https://docs.zephyrproject.org/latest/build/dts/api/bindings/input/zephyr,lvgl-button-input.html>`__ 107- `pointer input <https://docs.zephyrproject.org/latest/build/dts/api/bindings/input/zephyr,lvgl-pointer-input.html>`__ 108- `encoder input <https://docs.zephyrproject.org/latest/build/dts/api/bindings/input/zephyr,lvgl-encoder-input.html>`__ 109- `keypad input <https://docs.zephyrproject.org/latest/build/dts/api/bindings/input/zephyr,lvgl-keypad-input.html>`__ 110 111Essentially those buffer the :code:`input_event` generated by the device pointed to by the :code:`input` phandle or if left 112empty the binding captures all events regardless of the source. You do not have to instantiate or manage the devices yourself, 113they are created at application start up before :code:`main()` is executed. 114 115Most boards or shields that have a display or display connector have the pointer input device already declared: 116 117.. code-block:: 118 119 lvgl_pointer { 120 compatible = "zephyr,lvgl-pointer-input"; 121 input = <&ft5336_touch>; 122 }; 123 124You can access the underlying lvgl :code:`lv_indev_t` for configuration. 125Example with the encoder device to assign a :code:`lv_group_t`: 126 127.. code-block:: c 128 129 const struct device *lvgl_encoder = DEVICE_DT_GET(DT_COMPAT_GET_ANY_STATUS_OKAY(zephyr_lvgl_encoder_input)); 130 131 lv_obj_t *arc; 132 lv_group_t *arc_group; 133 134 arc = lv_arc_create(lv_screen_active()); 135 lv_obj_align(arc, LV_ALIGN_CENTER, 0, 0); 136 lv_obj_set_size(arc, 150, 150); 137 138 arc_group = lv_group_create(); 139 lv_group_add_obj(arc_group, arc); 140 lv_indev_set_group(lvgl_input_get_indev(lvgl_encoder), arc_group); 141 142 143Kconfig 144~~~~~~~~ 145 146Aside from enabling the shell you can also use Kconfig to finetune 147the footprint of your application. 148 149.. code-block:: 150 151 # Size of the memory region from which lvgl memory is allocated 152 CONFIG_LV_Z_MEM_POOL_SIZE=8192 153 154 # Do not include every widget/theme by default, enable them as needed. 155 CONFIG_LV_CONF_MINIMAL=y 156 157Overlays can be used to enable/disable features for specific boards or build 158targets. For more information refer to the 159`application development guide <https://docs.zephyrproject.org/latest/develop/application/index.html#application-configuration>`__. 160 161Performance Tuning in LVGL 162~~~~~~~~~~~~~~~~~~~~~~~~~~ 163 164To optimize LVGL's performance, several `kconfig` options can be configured: 165 166- **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**. 167 168- **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. 169 170- **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. 171 172- **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. 173 174Zephyr ≤ 3.7.0 Specific Options 175~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 176 177For Zephyr versions 3.7.0 and below, additional options are available to manage LVGL's frame flushing: 178 179- **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. 180 181 - **CONFIG_LV_Z_FLUSH_THREAD_STACK_SIZE**: Specifies the stack size for the flush thread, with a default of 1024 bytes. 182 183 - **CONFIG_LV_Z_FLUSH_THREAD_PRIO**: Sets the priority of the flush thread, with a default priority of 0, indicating cooperative priority. 184 185For newer versions of Zephyr, the OSAL (Operating System Abstraction Layer) can be utilized, which takes care of the flushing. 186 187Where can I find more information? 188---------------------------------- 189 190- Zephyr Documentation: `Zephyr Documentation <https://docs.zephyrproject.org/latest/index.html>`__ 191- Zephyr mailing list: `Zepyhr Mailing 192 List <https://lists.zephyrproject.org/g/main>`__ 193- Zephyr Discord server: `Zepyhr Discord 194 server <https://chat.zephyrproject.org/>`__ 195
