docs(all) Proofread, fix typos and add clarifications in confusing areas (#2528)
Co-authored-by: Gabor Kiss-Vamosi <kisvegabor@gmail.com>
This commit is contained in:
Kevin Thibedeau
@@ -5,7 +5,7 @@
|
||||
|
||||
# Introduction
|
||||
|
||||
LVGL (Light and Versatile Graphics Library) is a free and open-source graphics library providing everything you need to create embedded GUI with easy-to-use graphical elements, beautiful visual effects and a low memory footprint.
|
||||
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.
|
||||
|
||||
|
||||
## Key features
|
||||
@@ -17,29 +17,29 @@ LVGL (Light and Versatile Graphics Library) is a free and open-source graphics l
|
||||
- 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, external memory and GPU supported but not required
|
||||
- OS, external memory and GPU are supported but not required
|
||||
- Single frame buffer operation even with advanced graphic effects
|
||||
- Written in C for maximal compatibility (C++ compatible)
|
||||
- Simulator to start embedded GUI design on a PC without embedded hardware
|
||||
- Binding to MicroPython
|
||||
- Tutorials, examples, themes for rapid GUI design
|
||||
- Documentation is available online and PDF
|
||||
- Documentation is available online and as PDF
|
||||
- Free and open-source under MIT license
|
||||
|
||||
## Requirements
|
||||
Basically, every modern controller (which is able to drive a display) is suitable to run LVGL. The minimal requirements are:
|
||||
Basically, every modern controller which is able to drive a display is suitable to run LVGL. The minimal requirements are:
|
||||
<ul>
|
||||
<li> 16, 32 or 64 bit microcontroller or processor</li>
|
||||
<li>> 16 MHz clock speed is recommended</li>
|
||||
<li> Flash/ROM: > 64 kB for the very essential components (> 180 kB is recommended)</li>
|
||||
<li> RAM:
|
||||
<ul>
|
||||
<li> Static RAM usage: ~2 kB depending on the used features and objects types</li>
|
||||
<li> Static RAM usage: ~2 kB depending on the used features and object types</li>
|
||||
<li> Stack: > 2kB (> 8 kB is recommended)</li>
|
||||
<li> Dynamic data (heap): > 4 KB (> 32 kB is recommended if using several objects).
|
||||
Set by <em>LV_MEM_SIZE</em> in <em>lv_conf.h</em>. </li>
|
||||
<li> Display buffer: > <em>"Horizontal resolution"</em> pixels (> 10 × <em>"Horizontal resolution"</em> is recommended) </li>
|
||||
<li> One frame buffer in the MCU or in external display controller</li>
|
||||
<li> One frame buffer in the MCU or in an external display controller</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li> C99 or newer compiler</li>
|
||||
@@ -52,7 +52,7 @@ Basically, every modern controller (which is able to drive a display) is suita
|
||||
|
||||
## License
|
||||
The LVGL project (including all repositories) is licensed under [MIT license](https://github.com/lvgl/lvgl/blob/master/LICENCE.txt).
|
||||
It means you can use it even in commercial projects.
|
||||
This means you can use it even in commercial projects.
|
||||
|
||||
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).
|
||||
|
||||
@@ -85,16 +85,16 @@ The core repositories follow the rules of [Semantic versioning](https://semver.o
|
||||
Tags like `vX.Y.Z` are created for every release.
|
||||
|
||||
### Release cycle
|
||||
- Bugfixes: Released on demand even weekly
|
||||
- Bug fixes: Released on demand even weekly
|
||||
- Minor releases: Every 3-4 months
|
||||
- Major releases: Approximatelly yearly
|
||||
- Major releases: Approximately yearly
|
||||
|
||||
### Branches
|
||||
The core repositories have at least the following branches:
|
||||
- `master` latest version, patches are merged directly here.
|
||||
- `release/vX.Y` stable versions of the minor releases
|
||||
- `fix/some-description` temporal branches for bug fixes
|
||||
- `feat/some-description` temporal branches for features
|
||||
- `fix/some-description` temporary branches for bug fixes
|
||||
- `feat/some-description` temporary branches for features
|
||||
|
||||
|
||||
### Changelog
|
||||
@@ -103,7 +103,7 @@ The changes are recorded in [CHANGELOG.md](/CHANGELOG).
|
||||
|
||||
### Version support
|
||||
Before v8 every minor release of major releases is supported for 1 year.
|
||||
From v8 every minor release is supported for 1 year.
|
||||
Starting from v8, every minor release is supported for 1 year.
|
||||
|
||||
| Version | Release date | Support end | Active |
|
||||
|---------|--------------|-------------|--------|
|
||||
@@ -119,24 +119,24 @@ From v8 every minor release is supported for 1 year.
|
||||
You can ask questions in the forum: [https://forum.lvgl.io/](https://forum.lvgl.io/).
|
||||
|
||||
We use [GitHub issues](https://github.com/lvgl/lvgl/issues) for development related discussion.
|
||||
So you should use them only if your question or issue is tightly related to the development of the library.
|
||||
You should use them only if your question or issue is tightly related to the development of the library.
|
||||
|
||||
### Is my MCU/hardware supported?
|
||||
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 LLVGL.
|
||||
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.
|
||||
|
||||
This includes:
|
||||
- "Common" MCUs like STM32F, STM32H, NXP Kinetis, LPC, iMX, dsPIC33, PIC32 etc.
|
||||
- Bluetooth, GSM, Wi-Fi modules like Nordic NRF and Espressif ESP32
|
||||
- Linux with frame buffer device such as /dev/fb0. This includes Single-board computers like the Raspberry Pi
|
||||
- And anything else with a strong enough MCU and a periphery to drive a display
|
||||
- Anything else with a strong enough MCU and a peripheral to drive a display
|
||||
|
||||
### Is my display supported?
|
||||
LVGL needs just one simple driver function to copy an array of pixels into a given area of the display.
|
||||
If you can do this with your display then you can use that display with LVGL.
|
||||
If you can do this with your display then you can use it with LVGL.
|
||||
|
||||
Some examples of the supported display types:
|
||||
- TFTs with 16 or 24 bit color depth
|
||||
- Monitors with HDMI port
|
||||
- Monitors with an HDMI port
|
||||
- Small monochrome displays
|
||||
- Gray-scale displays
|
||||
- even LED matrices
|
||||
@@ -147,7 +147,7 @@ See the [Porting](/porting/display) section to learn more.
|
||||
### Nothing happens, my display driver is not called. What have I missed?
|
||||
Be sure you are calling `lv_tick_inc(x)` in an interrupt and `lv_timer_handler()` in your main `while(1)`.
|
||||
|
||||
Learn more in the [Tick](/porting/tick) and [Task handler](/porting/task-handler) section.
|
||||
Learn more in the [Tick](/porting/tick) and [Task handler](/porting/task-handler) sections.
|
||||
|
||||
### Why is the display driver called only once? Only the upper part of the display is refreshed.
|
||||
Be sure you are calling `lv_disp_flush_ready(drv)` at the end of your "*display flush callback*".
|
||||
@@ -178,35 +178,31 @@ a.y2 = a.y1 + BUF_H - 1;
|
||||
my_flush_cb(NULL, &a, buf);
|
||||
```
|
||||
|
||||
### Why I see nonsense colors on the screen?
|
||||
Probably LVGL's color format is not compatible with your displays color format. Check `LV_COLOR_DEPTH` in *lv_conf.h*.
|
||||
### Why do I see nonsense colors on the screen?
|
||||
Probably LVGL's color format is not compatible with your display's color format. Check `LV_COLOR_DEPTH` in *lv_conf.h*.
|
||||
|
||||
If you are using 16-bit colors with SPI (or other byte-oriented interface) probably you need to set `LV_COLOR_16_SWAP 1` in *lv_conf.h*.
|
||||
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*.
|
||||
It swaps the upper and lower bytes of the pixels.
|
||||
|
||||
### How to speed up my UI?
|
||||
- Turn on compiler optimization and enable cache if your MCU has
|
||||
- Turn on compiler optimization and enable cache if your MCU has it
|
||||
- Increase the size of the display buffer
|
||||
- Use 2 display buffers and flush the buffer with DMA (or similar periphery) in the background
|
||||
- Increase the clock speed of the SPI or Parallel port if you use them to drive the display
|
||||
- If your display has SPI port consider changing to a model with parallel because it has much higher throughput
|
||||
- Keep the display buffer in the internal RAM (not in external SRAM) because LVGL uses it a lot and it should have a small access time
|
||||
- Use two display buffers and flush the buffer with DMA (or similar peripheral) in the background
|
||||
- Increase the clock speed of the SPI or parallel port if you use them to drive the display
|
||||
- If your display has a SPI port consider changing to a model with a parallel interface because it has much higher throughput
|
||||
- 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
|
||||
|
||||
### How to reduce flash/ROM usage?
|
||||
You can disable all the unused features (such as animations, file system, GPU etc.) and object types in *lv_conf.h*.
|
||||
|
||||
If you are using GCC you can add
|
||||
- `-fdata-sections -ffunction-sections` compiler flags
|
||||
- `--gc-sections` linker flag
|
||||
|
||||
to remove unused functions and variables from the final binary
|
||||
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.
|
||||
|
||||
### How to reduce the RAM usage
|
||||
- Lower the size of the *Display buffer*
|
||||
- Reduce `LV_MEM_SIZE` in *lv_conf.h*. This memory used when you create objects like buttons, labels, etc.
|
||||
- To work with lower `LV_MEM_SIZE` you can create the objects only when required and deleted them when they are not required anymore
|
||||
- Reduce `LV_MEM_SIZE` in *lv_conf.h*. This memory is used when you create objects like buttons, labels, etc.
|
||||
- To work with lower `LV_MEM_SIZE` you can create objects only when required and delete them when they are not needed anymore
|
||||
|
||||
### How to work with an operating system?
|
||||
|
||||
To work with an operating system where tasks can interrupt each other (preemptive) you should protect LVGL related function calls with a mutex.
|
||||
To work with an operating system where tasks can interrupt each other (preemptively) you should protect LVGL related function calls with a mutex.
|
||||
See the [Operating system and interrupts](/porting/os) section to learn more.
|
||||
|
||||
Reference in New Issue
Block a user