acid-drop- Hacking the planet from a LilyGo T-Deck using custom firmware |
git clone git://git.acid.vegas/acid-drop.git |
Log | Files | Refs | Archive | README | LICENSE |
index.md (10866B)
1 ```eval_rst 2 .. include:: /header.rst 3 :github_url: |github_link_base|/intro/index.md 4 ``` 5 6 # Introduction 7 8 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. 9 10 11 ## Key features 12 - Powerful building blocks such as buttons, charts, lists, sliders, images, etc. 13 - Advanced graphics with animations, anti-aliasing, opacity, smooth scrolling 14 - Various input devices such as touchpad, mouse, keyboard, encoder, etc. 15 - Multi-language support with UTF-8 encoding 16 - Multi-display support, i.e. use multiple TFT, monochrome displays simultaneously 17 - Fully customizable graphic elements with CSS-like styles 18 - Hardware independent: use with any microcontroller or display 19 - Scalable: able to operate with little memory (64 kB Flash, 16 kB RAM) 20 - OS, external memory and GPU are supported but not required 21 - Single frame buffer operation even with advanced graphic effects 22 - Written in C for maximal compatibility (C++ compatible) 23 - Simulator to start embedded GUI design on a PC without embedded hardware 24 - Binding to MicroPython 25 - Tutorials, examples, themes for rapid GUI design 26 - Documentation is available online and as PDF 27 - Free and open-source under MIT license 28 29 ## Requirements 30 Basically, every modern controller which is able to drive a display is suitable to run LVGL. The minimal requirements are: 31 <ul> 32 <li> 16, 32 or 64 bit microcontroller or processor</li> 33 <li>> 16 MHz clock speed is recommended</li> 34 <li> Flash/ROM: > 64 kB for the very essential components (> 180 kB is recommended)</li> 35 <li> RAM: 36 <ul> 37 <li> Static RAM usage: ~2 kB depending on the used features and object types</li> 38 <li> Stack: > 2kB (> 8 kB is recommended)</li> 39 <li> Dynamic data (heap): > 4 KB (> 32 kB is recommended if using several objects). 40 Set by <em>LV_MEM_SIZE</em> in <em>lv_conf.h</em>. </li> 41 <li> Display buffer: > <em>"Horizontal resolution"</em> pixels (> 10 × <em>"Horizontal resolution"</em> is recommended) </li> 42 <li> One frame buffer in the MCU or in an external display controller</li> 43 </ul> 44 </li> 45 <li> C99 or newer compiler</li> 46 <li> Basic C (or C++) knowledge: 47 <a href="https://www.tutorialspoint.com/cprogramming/c_pointers.htm">pointers</a>, 48 <a href="https://www.tutorialspoint.com/cprogramming/c_structures.htm">structs</a>, 49 <a href="https://www.geeksforgeeks.org/callbacks-in-c/">callbacks</a>.</li> 50 </ul> 51 <em>Note that memory usage may vary depending on architecture, compiler and build options.</em> 52 53 ## License 54 The LVGL project (including all repositories) is licensed under [MIT license](https://github.com/lvgl/lvgl/blob/master/LICENCE.txt). 55 This means you can use it even in commercial projects. 56 57 It's 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). 58 59 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. 60 61 To make the LVGL project sustainable, please consider [contributing](/CONTRIBUTING) to the project. 62 You can choose from [many different ways of contributing](/CONTRIBUTING) such as simply writing a tweet about you using LVGL, fixing bugs, translating the documentation, or even becoming a maintainer. 63 64 ## Repository layout 65 All repositories of the LVGL project are hosted on GitHub: https://github.com/lvgl 66 67 You will find these repositories there: 68 - [lvgl](https://github.com/lvgl/lvgl) The library itself with many [examples](https://github.com/lvgl/lvgl/blob/master/examples/) and [demos](https://github.com/lvgl/lvgl/blob/master/demos/). 69 - [lv_drivers](https://github.com/lvgl/lv_drivers) Display and input device drivers 70 - [blog](https://github.com/lvgl/blog) Source of the blog's site (https://blog.lvgl.io) 71 - [sim](https://github.com/lvgl/sim) Source of the online simulator's site (https://sim.lvgl.io) 72 - [lv_port_...](https://github.com/lvgl?q=lv_port&type=&language=) LVGL ports to development boards or environments 73 - [lv_binding_..](https://github.com/lvgl?q=lv_binding&type=&language=l) Bindings to other languages 74 75 ## Release policy 76 77 The core repositories follow the rules of [Semantic versioning](https://semver.org/): 78 - Major versions for incompatible API changes. E.g. v5.0.0, v6.0.0 79 - Minor version for new but backward-compatible functionalities. E.g. v6.1.0, v6.2.0 80 - Patch version for backward-compatible bug fixes. E.g. v6.1.1, v6.1.2 81 82 Tags like `vX.Y.Z` are created for every release. 83 84 ### Release cycle 85 - Bug fixes: Released on demand even weekly 86 - Minor releases: Every 3-4 months 87 - Major releases: Approximately yearly 88 89 ### Branches 90 The core repositories have at least the following branches: 91 - `master` latest version, patches are merged directly here. 92 - `release/vX.Y` stable versions of the minor releases 93 - `fix/some-description` temporary branches for bug fixes 94 - `feat/some-description` temporary branches for features 95 96 97 ### Changelog 98 99 The changes are recorded in [CHANGELOG.md](/CHANGELOG). 100 101 ### Version support 102 Before v8 the last minor release of each major series was supported for 1 year. 103 Starting from v8, every minor release is supported for 1 year. 104 105 | Version | Release date | Support end | Active | 106 |---------|--------------|-------------|--------| 107 | v5.3 | Feb 1, 2019 |Feb 1, 2020 | No | 108 | v6.1 | Nov 26, 2019 |Nov 26, 2020 | No | 109 | v7.11 | Mar 16, 2021 |Mar 16, 2022 | No | 110 | v8.0 | 1 Jun, 2021 |1 Jun, 2022 | Yes | 111 | v8.1 | 10 Nov, 2021 |10 Nov, 2022 | Yes | 112 | v8.2 | In progress | | | 113 114 115 ## FAQ 116 117 ### Where can I ask questions? 118 You can ask questions in the forum: [https://forum.lvgl.io/](https://forum.lvgl.io/). 119 120 We use [GitHub issues](https://github.com/lvgl/lvgl/issues) for development related discussion. 121 You should use them only if your question or issue is tightly related to the development of the library. 122 123 Before posting a question, please ready this FAQ section as you might find answer to your issue here too. 124 125 ### Is my MCU/hardware supported? 126 Every MCU which is capable of driving a display via parallel port, SPI, RGB interface or anything else and fulfills the [Requirements](#requirements) is supported by LVGL. 127 128 This includes: 129 - "Common" MCUs like STM32F, STM32H, NXP Kinetis, LPC, iMX, dsPIC33, PIC32 etc. 130 - Bluetooth, GSM, Wi-Fi modules like Nordic NRF and Espressif ESP32 131 - Linux with frame buffer device such as /dev/fb0. This includes Single-board computers like the Raspberry Pi 132 - Anything else with a strong enough MCU and a peripheral to drive a display 133 134 ### Is my display supported? 135 LVGL needs just one simple driver function to copy an array of pixels into a given area of the display. 136 If you can do this with your display then you can use it with LVGL. 137 138 Some examples of the supported display types: 139 - TFTs with 16 or 24 bit color depth 140 - Monitors with an HDMI port 141 - Small monochrome displays 142 - Gray-scale displays 143 - even LED matrices 144 - or any other display where you can control the color/state of the pixels 145 146 See the [Porting](/porting/display) section to learn more. 147 148 ### LVGL doesn't start, randomly crashes or nothing is drawn on the display. What can be the problem? 149 - Try increasing `LV_MEM_SIZE`. 150 - Be sure `lv_disp_drv_t`, `lv_indev_drv_t` and `lv_fs_drv_t` are global or `static`. 151 - Be sure your display works without LVGL. E.g. paint it to red on start up. 152 - Enable [Logging](porting/log) 153 - Enable asserts in `lv_conf.h` (`LV_USE_ASSERT_...`) 154 - If you use an RTOS 155 - increase the stack size of the task which calls `lv_timer_handler()` 156 - Be sure you used a mutex as [described here](/porting/os) 157 158 ### My display driver is not called. What have I missed? 159 Be sure you are calling `lv_tick_inc(x)` in an interrupt and `lv_timer_handler()` in your main `while(1)`. 160 161 Learn more in the [Tick](/porting/tick) and [Timer handler](/porting/timer-handler) sections. 162 163 ### Why is the display driver called only once? Only the upper part of the display is refreshed. 164 Be sure you are calling `lv_disp_flush_ready(drv)` at the end of your "*display flush callback*". 165 166 ### Why do I see only garbage on the screen? 167 Probably there a bug in your display driver. Try the following code without using LVGL. You should see a square with red-blue gradient. 168 169 ```c 170 #define BUF_W 20 171 #define BUF_H 10 172 173 lv_color_t buf[BUF_W * BUF_H]; 174 lv_color_t * buf_p = buf; 175 uint16_t x, y; 176 for(y = 0; y < BUF_H; y++) { 177 lv_color_t c = lv_color_mix(LV_COLOR_BLUE, LV_COLOR_RED, (y * 255) / BUF_H); 178 for(x = 0; x < BUF_W; x++){ 179 (*buf_p) = c; 180 buf_p++; 181 } 182 } 183 184 lv_area_t a; 185 a.x1 = 10; 186 a.y1 = 40; 187 a.x2 = a.x1 + BUF_W - 1; 188 a.y2 = a.y1 + BUF_H - 1; 189 my_flush_cb(NULL, &a, buf); 190 ``` 191 192 ### Why do I see nonsense colors on the screen? 193 Probably LVGL's color format is not compatible with your display's color format. Check `LV_COLOR_DEPTH` in *lv_conf.h*. 194 195 If you are using 16-bit colors with SPI (or another byte-oriented interface) you probably need to set `LV_COLOR_16_SWAP 1` in *lv_conf.h*. 196 It swaps the upper and lower bytes of the pixels. 197 198 ### How to speed up my UI? 199 - Turn on compiler optimization and enable cache if your MCU has it 200 - Increase the size of the display buffer 201 - Use two display buffers and flush the buffer with DMA (or similar peripheral) in the background 202 - Increase the clock speed of the SPI or parallel port if you use them to drive the display 203 - If your display has an SPI port consider changing to a model with a parallel interface because it has much higher throughput 204 - Keep the display buffer in internal RAM (not in external SRAM) because LVGL uses it a lot and it should have a fast access time 205 206 ### How to reduce flash/ROM usage? 207 You can disable all the unused features (such as animations, file system, GPU etc.) and object types in *lv_conf.h*. 208 209 If you are using GCC you can add `-fdata-sections -ffunction-sections` compiler flags and `--gc-sections` linker flag to remove unused functions and variables from the final binary. 210 211 ### How to reduce the RAM usage 212 - Lower the size of the *Display buffer* 213 - Reduce `LV_MEM_SIZE` in *lv_conf.h*. This memory is used when you create objects like buttons, labels, etc. 214 - To work with lower `LV_MEM_SIZE` you can create objects only when required and delete them when they are not needed anymore 215 216 ### How to work with an operating system? 217 218 To work with an operating system where tasks can interrupt each other (preemptively) you should protect LVGL related function calls with a mutex. 219 See the [Operating system and interrupts](/porting/os) section to learn more.