github-code/lvgl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add the md files from the docs repo to start updating them to v8

Browse Source
This commit is contained in:
Gabor Kiss-Vamosi
2021-04-12 18:19:04 +02:00
parent c587fc4d2a
commit 73f4264320
93 changed files with 7007 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
docs/porting/display.md Normal file
View File

@@ -0,0 +1,179 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/porting/display.md
```
# Display interface
To set up a display an `lv_disp_buf_t` and an `lv_disp_drv_t` variables have to be initialized.
- **lv_disp_buf_t** contains internal graphic buffer(s).
- **lv_disp_drv_t** contains callback functions to interact with the display and manipulate drawing related things.
## Display buffer
`lv_disp_buf_t` can be initialized like this:
```c
/*A static or global variable to store the buffers*/
static lv_disp_buf_t disp_buf;
/*Static or global buffer(s). The second buffer is optional*/
static lv_color_t buf_1[MY_DISP_HOR_RES * 10];
static lv_color_t buf_2[MY_DISP_HOR_RES * 10];
/*Initialize `disp_buf` with the buffer(s) */
lv_disp_buf_init(&disp_buf, buf_1, buf_2, MY_DISP_HOR_RES*10);
```
There are 3 possible configurations regarding the buffer size:
1. **One buffer** LVGL draws the content of the screen into a buffer and sends it to the display.
The buffer can be smaller than the screen. In this case, the larger areas will be redrawn in multiple parts.
If only small areas changes (e.g. button press) then only those areas will be refreshed.
2. **Two non-screen-sized buffers** having two buffers LVGL can draw into one buffer while the content of the other buffer is sent to display in the background.
DMA or other hardware should be used to transfer the data to the display to let the CPU draw meanwhile.
This way the rendering and refreshing of the display become parallel.
Similarly to the *One buffer*, LVGL will draw the display's content in chunks if the buffer is smaller than the area to refresh.
3. **Two screen-sized buffers**.
In contrast to *Two non-screen-sized buffers* LVGL will always provide the whole screen's content not only chunks.
This way the driver can simply change the address of the frame buffer to the buffer received from LVGL.
Therefore this method works the best when the MCU has an LCD/TFT interface and the frame buffer is just a location in the RAM.
You can measure the performance of your display configuration using the [benchmark example](https://github.com/lvgl/lv_examples/tree/master/src/lv_demo_benchmark).
## Display driver
Once the buffer initialization is ready the display drivers need to be initialized. In the most simple case only the following two fields of `lv_disp_drv_t` needs to be set:
- **buffer** pointer to an initialized `lv_disp_buf_t` variable.
- **flush_cb** a callback function to copy a buffer's content to a specific area of the display. `lv_disp_flush_ready()` needs to be called when flushing is ready. LVGL might render the screen in multiple chunks and therefore call `flush_cb` multiple times. To see which is the last chunk of rendering use `lv_disp_flush_is_last()`.
There are some optional data fields:
- **hor_res** horizontal resolution of the display. (`LV_HOR_RES_MAX` by default from *lv_conf.h*).
- **ver_res** vertical resolution of the display. (`LV_VER_RES_MAX` by default from *lv_conf.h*).
- **color_chroma_key** a color which will be drawn as transparent on chrome keyed images. `LV_COLOR_TRANSP` by default from *lv_conf.h*).
- **user_data** custom user data for the driver. Its type can be modified in lv_conf.h.
- **anti-aliasing** use anti-aliasing (edge smoothing). `LV_ANTIALIAS` by default from *lv_conf.h*.
- **rotated** and **sw_rotate** See the [rotation](#rotation) section below.
- **screen_transp** if `1` the screen can have transparent or opaque style. `LV_COLOR_SCREEN_TRANSP` needs to enabled in *lv_conf.h*.
To use a GPU the following callbacks can be used:
- **gpu_fill_cb** fill an area in memory with colors.
- **gpu_blend_cb** blend two memory buffers using opacity.
- **gpu_wait_cb** if any GPU function return, while the GPU is still working LVGL, will use this function when required the be sure GPU rendering is ready.
Note that, these functions need to draw to the memory (RAM) and not your display directly.
Some other optional callbacks to make easier and more optimal to work with monochrome, grayscale or other non-standard RGB displays:
- **rounder_cb** round the coordinates of areas to redraw. E.g. a 2x2 px can be converted to 2x8.
It can be used if the display controller can refresh only areas with specific height or width (usually 8 px height with monochrome displays).
- **set_px_cb** a custom function to write the *display buffer*.
It can be used to store the pixels more compactly if the display has a special color format. (e.g. 1-bit monochrome, 2-bit grayscale etc.)
This way the buffers used in `lv_disp_buf_t` can be smaller to hold only the required number of bits for the given area size. `set_px_cb` is not working with `Two screen-sized buffers` display buffer configuration.
- **monitor_cb** a callback function tells how many pixels were refreshed in how much time.
- **clean_dcache_cb** a callback for cleaning any caches related to the display
To set the fields of *lv_disp_drv_t* variable it needs to be initialized with `lv_disp_drv_init(&disp_drv)`.
And finally to register a display for LVGL `lv_disp_drv_register(&disp_drv)` needs to be called.
All together it looks like this:
```c
lv_disp_drv_t disp_drv; /*A variable to hold the drivers. Can be local variable*/
lv_disp_drv_init(&disp_drv); /*Basic initialization*/
disp_drv.buffer = &disp_buf; /*Set an initialized buffer*/
disp_drv.flush_cb = my_flush_cb; /*Set a flush callback to draw to the display*/
lv_disp_t * disp;
disp = lv_disp_drv_register(&disp_drv); /*Register the driver and save the created display objects*/
```
Here some simple examples of the callbacks:
```c
void my_flush_cb(lv_disp_drv_t * disp_drv, const lv_area_t * area, lv_color_t * color_p)
{
/*The most simple case (but also the slowest) to put all pixels to the screen one-by-one*/
int32_t x, y;
for(y = area->y1; y <= area->y2; y++) {
for(x = area->x1; x <= area->x2; x++) {
put_px(x, y, *color_p)
color_p++;
}
}
/* IMPORTANT!!!
* Inform the graphics library that you are ready with the flushing*/
lv_disp_flush_ready(disp_drv);
}
void my_gpu_fill_cb(lv_disp_drv_t * disp_drv, lv_color_t * dest_buf, const lv_area_t * dest_area, const lv_area_t * fill_area, lv_color_t color);
{
/*It's an example code which should be done by your GPU*/
uint32_t x, y;
dest_buf += dest_width * fill_area->y1; /*Go to the first line*/
for(y = fill_area->y1; y < fill_area->y2; y++) {
for(x = fill_area->x1; x < fill_area->x2; x++) {
dest_buf[x] = color;
}
dest_buf+=dest_width; /*Go to the next line*/
}
}
void my_gpu_blend_cb(lv_disp_drv_t * disp_drv, lv_color_t * dest, const lv_color_t * src, uint32_t length, lv_opa_t opa)
{
/*It's an example code which should be done by your GPU*/
uint32_t i;
for(i = 0; i < length; i++) {
dest[i] = lv_color_mix(dest[i], src[i], opa);
}
}
void my_rounder_cb(lv_disp_drv_t * disp_drv, lv_area_t * area)
{
/* Update the areas as needed. Can be only larger.
* For example to always have lines 8 px height:*/
area->y1 = area->y1 & 0x07;
area->y2 = (area->y2 & 0x07) + 8;
}
void my_set_px_cb(lv_disp_drv_t * disp_drv, uint8_t * buf, lv_coord_t buf_w, lv_coord_t x, lv_coord_t y, lv_color_t color, lv_opa_t opa)
{
/* Write to the buffer as required for the display.
* Write only 1-bit for monochrome displays mapped vertically:*/
buf += buf_w * (y >> 3) + x;
if(lv_color_brightness(color) > 128) (*buf) |= (1 << (y % 8));
else (*buf) &= ~(1 << (y % 8));
}
void my_monitor_cb(lv_disp_drv_t * disp_drv, uint32_t time, uint32_t px)
{
printf("%d px refreshed in %d ms\n", time, ms);
}
void my_clean_dcache_cb(lv_disp_drv_t * disp_drv, uint32)
{
/* Example for Cortex-M (CMSIS) */
SCB_CleanInvalidateDCache();
}
```
## Rotation
LVGL supports rotation of the display in 90 degree increments. You can select whether you'd like software rotation or hardware rotation.
If you select software rotation (`sw_rotate` flag set to 1), LVGL will perform the rotation for you. Your driver can and should assume that the screen width and height have not changed. Simply flush pixels to the display as normal. Software rotation requires no additional logic in your `flush_cb` callback.
There is a noticeable amount of overhead to performing rotation in software, which is why hardware rotation is also available. In this mode, LVGL draws into the buffer as though your screen now has the width and height inverted. You are responsible for rotating the provided pixels yourself.
The default rotation of your display when it is initialized can be set using the `rotated` flag. The available options are `LV_DISP_ROT_NONE`, `LV_DISP_ROT_90`, `LV_DISP_ROT_180`, or `LV_DISP_ROT_270`. The rotation values are relative to how you would rotate the physical display in the clockwise direction. Thus, `LV_DISP_ROT_90` means you rotate the hardware 90 degrees clockwise, and the display rotates 90 degrees counterclockwise to compensate.
(Note for users upgrading from 7.10.0 and older: these new rotation enum values match up with the old 0/1 system for rotating 90 degrees, so legacy code should continue to work as expected. Software rotation is also disabled by default for compatibility.)
Display rotation can also be changed at runtime using the `lv_disp_set_rotation(disp, rot)` API.
Support for software rotation is a new feature, so there may be some glitches/bugs depending on your configuration. If you encounter a problem please open an issue on [GitHub](https://github.com/lvgl/lvgl/issues).
## API
```eval_rst
.. doxygenfile:: lv_hal_disp.h
:project: lvgl
```

203
docs/porting/indev.md Normal file
View File

@@ -0,0 +1,203 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/porting/indev.md
```
# Input device interface
## Types of input devices
To set up an input device an `lv_indev_drv_t` variable has to be initialized:
```c
lv_indev_drv_t indev_drv;
lv_indev_drv_init(&indev_drv); /*Basic initialization*/
indev_drv.type =... /*See below.*/
indev_drv.read_cb =... /*See below.*/
/*Register the driver in LVGL and save the created input device object*/
lv_indev_t * my_indev = lv_indev_drv_register(&indev_drv);
```
**type** can be
- **LV_INDEV_TYPE_POINTER** touchpad or mouse
- **LV_INDEV_TYPE_KEYPAD** keyboard or keypad
- **LV_INDEV_TYPE_ENCODER** encoder with left, right, push options
- **LV_INDEV_TYPE_BUTTON** external buttons pressing the screen
**read_cb** is a function pointer which will be called periodically to report the current state of an input device.
It can also buffer data and return `false` when no more data to be read or `true` when the buffer is not empty.
Visit [Input devices](/overview/indev) to learn more about input devices in general.
### Touchpad, mouse or any pointer
Input devices which can click points of the screen belong to this category.
```c
indev_drv.type = LV_INDEV_TYPE_POINTER;
indev_drv.read_cb = my_input_read;
...
bool my_input_read(lv_indev_drv_t * drv, lv_indev_data_t*data)
{
data->point.x = touchpad_x;
data->point.y = touchpad_y;
data->state = LV_INDEV_STATE_PR or LV_INDEV_STATE_REL;
return false; /*No buffering now so no more data read*/
}
```
``` important:: Touchpad drivers must return the last X/Y coordinates even when the state is *LV_INDEV_STATE_REL*.
```
To set a mouse cursor use `lv_indev_set_cursor(my_indev, &img_cursor)`. (`my_indev` is the return value of `lv_indev_drv_register`)
### Keypad or keyboard
Full keyboards with all the letters or simple keypads with a few navigation buttons belong here.
To use a keyboard/keypad:
- Register a `read_cb` function with `LV_INDEV_TYPE_KEYPAD` type.
- Enable `LV_USE_GROUP` in *lv_conf.h*
- An object group has to be created: `lv_group_t * g = lv_group_create()` and objects have to be added to it with `lv_group_add_obj(g, obj)`
- The created group has to be assigned to an input device: `lv_indev_set_group(my_indev, g)` (`my_indev` is the return value of `lv_indev_drv_register`)
- Use `LV_KEY_...` to navigate among the objects in the group. See `lv_core/lv_group.h` for the available keys.
```c
indev_drv.type = LV_INDEV_TYPE_KEYPAD;
indev_drv.read_cb = keyboard_read;
...
bool keyboard_read(lv_indev_drv_t * drv, lv_indev_data_t*data){
data->key = last_key(); /*Get the last pressed or released key*/
if(key_pressed()) data->state = LV_INDEV_STATE_PR;
else data->state = LV_INDEV_STATE_REL;
return false; /*No buffering now so no more data read*/
}
```
### Encoder
With an encoder you can do 4 things:
1. Press its button
2. Long-press its button
3. Turn left
4. Turn right
In short, the Encoder input devices work like this:
- By turning the encoder you can focus on the next/previous object.
- When you press the encoder on a simple object (like a button), it will be clicked.
- If you press the encoder on a complex object (like a list, message box, etc.) the object will go to edit mode whereby turning the encoder you can navigate inside the object.
- To leave edit mode press long the button.
To use an *Encoder* (similarly to the *Keypads*) the objects should be added to groups.
```c
indev_drv.type = LV_INDEV_TYPE_ENCODER;
indev_drv.read_cb = encoder_read;
...
bool encoder_read(lv_indev_drv_t * drv, lv_indev_data_t*data){
data->enc_diff = enc_get_new_moves();
if(enc_pressed()) data->state = LV_INDEV_STATE_PR;
else data->state = LV_INDEV_STATE_REL;
return false; /*No buffering now so no more data read*/
}
```
#### Using buttons with Encoder logic
In addition to standard encoder behavior, you can also utilise its logic to navigate(focus) and edit widgets using buttons.
This is especially handy if you have only few buttons avalible, or you want to use other buttons in addition to encoder wheel.
You need to have 3 buttons avalible:
- **LV_KEY_ENTER** will simulate press or pushing of the encoder button
- **LV_KEY_LEFT** will simulate turnuing encoder left
- **LV_KEY_RIGHT** will simulate turnuing encoder right
- other keys will be passed to the focused widget
If you hold the keys it will simulate encoder click with period specified in `indev_drv.long_press_rep_time`.
```c
indev_drv.type = LV_INDEV_TYPE_ENCODER;
indev_drv.read_cb = encoder_with_keys_read;
...
bool encoder_with_keys_read(lv_indev_drv_t * drv, lv_indev_data_t*data){
data->key = last_key(); /*Get the last pressed or released key*/
/* use LV_KEY_ENTER for encoder press */
if(key_pressed()) data->state = LV_INDEV_STATE_PR;
else {
data->state = LV_INDEV_STATE_REL;
/* Optionally you can also use enc_diff, if you have encoder*/
data->enc_diff = enc_get_new_moves();
}
return false; /*No buffering now so no more data read*/
}
```
### Button
*Buttons* mean external "hardware" buttons next to the screen which are assigned to specific coordinates of the screen.
If a button is pressed it will simulate the pressing on the assigned coordinate. (Similarly to a touchpad)
To assign buttons to coordinates use `lv_indev_set_button_points(my_indev, points_array)`.
`points_array` should look like `const lv_point_t points_array[] = { {12,30},{60,90}, ...}`
``` important:: The points_array can't go out of scope. Either declare it as a global variable or as a static variable inside a function.
```
```c
indev_drv.type = LV_INDEV_TYPE_BUTTON;
indev_drv.read_cb = button_read;
...
bool button_read(lv_indev_drv_t * drv, lv_indev_data_t*data){
static uint32_t last_btn = 0; /*Store the last pressed button*/
int btn_pr = my_btn_read(); /*Get the ID (0,1,2...) of the pressed button*/
if(btn_pr >= 0) { /*Is there a button press? (E.g. -1 indicated no button was pressed)*/
last_btn = btn_pr; /*Save the ID of the pressed button*/
data->state = LV_INDEV_STATE_PR; /*Set the pressed state*/
} else {
data->state = LV_INDEV_STATE_REL; /*Set the released state*/
}
data->btn = last_btn; /*Save the last button*/
return false; /*No buffering now so no more data read*/
}
```
## Other features
Besides `read_cb` a `feedback_cb` callback can be also specified in `lv_indev_drv_t`.
`feedback_cb` is called when any type of event is sent by the input devices. (independently from its type). It allows making feedback for the user e.g. to play a sound on `LV_EVENT_CLICK`.
The default value of the following parameters can be set in *lv_conf.h* but the default value can be overwritten in `lv_indev_drv_t`:
- **drag_limit** Number of pixels to slide before actually drag the object
- **drag_throw** Drag throw slow-down in [%]. Greater value means faster slow-down
- **long_press_time** Press time to send `LV_EVENT_LONG_PRESSED` (in milliseconds)
- **long_press_rep_time** Interval of sending `LV_EVENT_LONG_PRESSED_REPEAT` (in milliseconds)
- **read_task** pointer to the `lv_task` which reads the input device. Its parameters can be changed by `lv_task_...()` functions
Every Input device is associated with a display. By default, a new input device is added to the lastly created or the explicitly selected (using `lv_disp_set_default()`) display.
The associated display is stored and can be changed in `disp` field of the driver.
## API
```eval_rst
.. doxygenfile:: lv_hal_indev.h
:project: lvgl
```

24
docs/porting/index.md Normal file
View File

@@ -0,0 +1,24 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/porting/index.md
```
# Porting
```eval_rst
.. toctree::
:maxdepth: 2
sys
project
display
indev
tick
task-handler
sleep
os
log
```

61
docs/porting/log.md Normal file
View File

@@ -0,0 +1,61 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/porting/log.md
```
# Logging
LVGL has built-in *log* module to inform the user about what is happening in the library.
## Log level
To enable logging, set `LV_USE_LOG 1` in *lv_conf.h* and set `LV_LOG_LEVEL` to one of the following values:
- **LV_LOG_LEVEL_TRACE** A lot of logs to give detailed information
- **LV_LOG_LEVEL_INFO** Log important events
- **LV_LOG_LEVEL_WARN** Log if something unwanted happened but didn't cause a problem
- **LV_LOG_LEVEL_ERROR** Only critical issue, when the system may fail
- **LV_LOG_LEVEL_NONE** Do not log anything
The events which have a higher level than the set log level will be logged too. E.g. if you `LV_LOG_LEVEL_WARN`, *errors* will be also logged.
## Logging with printf
If your system supports `printf`, you just need to enable `LV_LOG_PRINTF` in *lv_conf.h* to send the logs with `printf`.
## Custom log function
If you can't use `printf` or want to use a custom function to log, you can register a "logger" callback with `lv_log_register_print_cb()`.
For example:
```c
void my_log_cb(lv_log_level_t level, const char * file, uint32_t line, const char * fn_name, const char * dsc)
{
/*Send the logs via serial port*/
if(level == LV_LOG_LEVEL_ERROR) serial_send("ERROR: ");
if(level == LV_LOG_LEVEL_WARN) serial_send("WARNING: ");
if(level == LV_LOG_LEVEL_INFO) serial_send("INFO: ");
if(level == LV_LOG_LEVEL_TRACE) serial_send("TRACE: ");
serial_send("File: ");
serial_send(file);
char line_str[8];
sprintf(line_str,"%d", line);
serial_send("#");
serial_send(line_str);
serial_send(": ");
serial_send(fn_name);
serial_send(": ");
serial_send(dsc);
serial_send("\n");
}
...
lv_log_register_print_cb(my_log_cb);
```
## Add logs
You can also use the log module via the `LV_LOG_TRACE/INFO/WARN/ERROR(description)` functions.

21
docs/porting/os.md Normal file
View File

@@ -0,0 +1,21 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/porting/os.md
```
# Operating system and interrupts
LVGL is **not thread-safe** by default.
However, in the following conditions it's valid to call LVGL related functions:
- In *events*. Learn more in [Events](/overview/event).
- In *lv_tasks*. Learn more in [Tasks](/overview/task).
## Tasks and threads
If you need to use real tasks or threads, you need a mutex which should be invoked before the call of `lv_task_handler` and released after it.
Also, you have to use the same mutex in other tasks and threads around every LVGL (`lv_...`) related function calls and codes.
This way you can use LVGL in a real multitasking environment. Just make use of a mutex to avoid the concurrent calling of LVGL functions.
## Interrupts
Try to avoid calling LVGL functions from the interrupts (except `lv_tick_inc()` and `lv_disp_flush_ready()`). But, if you need to do this you have to disable the interrupt which uses LVGL functions while `lv_task_handler` is running.
It's a better approach to set a flag or some value and periodically check it in an `lv_task`.

37
docs/porting/project.md Normal file
View File

@@ -0,0 +1,37 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/porting/project.md
```
# Set-up a project
## Get the library
LVGL Graphics Library is available on GitHub: [https://github.com/lvgl/lvgl](https://github.com/lvgl/lvgl).
You can clone it or download the latest version of the library from GitHub.
The graphics library is the **lvgl** directory which should be copied into your project.
## Configuration file
There is a configuration header file for LVGL called **lv_conf.h**. It sets the library's basic behaviour, disables unused modules and features, adjusts the size of memory buffers in compile-time, etc.
Copy **lvgl/lv_conf_template.h** next to the *lvgl* directory and rename it to *lv_conf.h*. Open the file and change the `#if 0` at the beginning to `#if 1` to enable its content.
*lv_conf.h* can be copied other places as well but then you should add `LV_CONF_INCLUDE_SIMPLE` define to your compiler options (e.g. `-DLV_CONF_INCLUDE_SIMPLE` for gcc compiler) and set the include path manually.
In the config file comments explain the meaning of the options. Check at least these three configuration options and modify them according to your hardware:
1. **LV_HOR_RES_MAX** Your display's horizontal resolution.
2. **LV_VER_RES_MAX** Your display's vertical resolution.
3. **LV_COLOR_DEPTH** 8 for (RG332), 16 for (RGB565) or 32 for (RGB888 and ARGB8888).
## Initialization
To use the graphics library you have to initialize it and the other components too. The order of the initialization is:
1. Call *lv_init()*.
2. Initialize your drivers.
3. Register the display and input devices drivers in LVGL. More about [Display](/porting/display) and [Input device](/porting/indev) registration.
4. Call `lv_tick_inc(x)` in every `x` milliseconds in an interrupt to tell the elapsed time. [Learn more](/porting/tick).
5. Call `lv_task_handler()` periodically in every few milliseconds to handle LVGL related tasks. [Learn more](/porting/task-handler).

31
docs/porting/sleep.md Normal file
View File

@@ -0,0 +1,31 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/porting/sleep.md
```
# Sleep management
The MCU can go to sleep when no user input happens. In this case, the main `while(1)` should look like this:
```c
while(1) {
/*Normal operation (no sleep) in < 1 sec inactivity*/
if(lv_disp_get_inactive_time(NULL) < 1000) {
lv_task_handler();
}
/*Sleep after 1 sec inactivity*/
else {
timer_stop(); /*Stop the timer where lv_tick_inc() is called*/
sleep(); /*Sleep the MCU*/
}
my_delay_ms(5);
}
```
You should also add below lines to your input device read function if a wake-up (press, touch or click etc.) happens:
```c
lv_tick_inc(LV_DISP_DEF_REFR_PERIOD); /*Force task execution on wake-up*/
timer_start(); /*Restart the timer where lv_tick_inc() is called*/
lv_task_handler(); /*Call `lv_task_handler()` manually to process the wake-up event*/
```
In addition to `lv_disp_get_inactive_time()` you can check `lv_anim_count_running()` to see if every animations are finished.

29
docs/porting/sys.md Normal file
View File

@@ -0,0 +1,29 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/porting/sys.md
```
# System overview
![](/misc/sys.png "System architecture with LVGL (formerly LittlevGL)")
**Application**
Your application which creates the GUI and handles the specific tasks.
**LVGL**
The graphics library itself. Your application can communicate with the library to create a GUI. It contains a HAL (Hardware Abstraction Layer) interface to register your display and input device drivers.
**Driver**
Besides your specific drivers, it contains functions to drive your display, optionally to a GPU and to read the touchpad or buttons.
* * *
Depending on the MCU, there are two typical hardware set-ups. One with built-in LCD/TFT driver periphery and another without it. In both cases, a frame buffer will be required to store the current image of the screen.
1. **MCU with TFT/LCD driver**
If your MCU has a TFT/LCD driver periphery then you can connect a display directly via RGB interface.
In this case, the frame buffer can be in the internal RAM (if the MCU has enough RAM) or in the external RAM (if the MCU has a memory interface).
2. **External display controller**
If the MCU doesn't have TFT/LCD driver interface then an external display controller (E.g. SSD1963, SSD1306, ILI9341) has to be used.
In this case, the MCU can communicate with the display controller via Parallel port, SPI or sometimes I2C.
The frame buffer is usually located in the display controller which saves a lot of RAM for the MCU.

23
docs/porting/task-handler.md Normal file
View File

@@ -0,0 +1,23 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/porting/task-handler.md
```
# Task Handler
To handle the tasks of LVGL you need to call `lv_task_handler()` periodically in one of the followings:
- *while(1)* of *main()* function
- timer interrupt periodically (low priority then `lv_tick_inc()`)
- an OS task periodically
The timing is not critical but it should be about 5 milliseconds to keep the system responsive.
Example:
```c
while(1) {
lv_task_handler();
my_delay_ms(5);
}
```
To learn more about task visit the [Tasks](/overview/task) section.

35
docs/porting/tick.md Normal file
View File

@@ -0,0 +1,35 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/porting/tick.md
```
# Tick interface
The LVGL needs a system tick to know the elapsed time for animation and other tasks.
You need to call the `lv_tick_inc(tick_period)` function periodically and tell the call period in milliseconds. For example, `lv_tick_inc(1)` for calling in every millisecond.
`lv_tick_inc` should be called in a higher priority routine than `lv_task_handler()` (e.g. in an interrupt) to precisely know the elapsed milliseconds even if the execution of `lv_task_handler` takes longer time.
With FreeRTOS `lv_tick_inc` can be called in `vApplicationTickHook`.
On Linux based operating system (e.g. on Raspberry Pi) `lv_tick_inc` can be called in a thread as below:
```c
void * tick_thread (void *args)
{
while(1) {
usleep(5*1000); /*Sleep for 5 millisecond*/
lv_tick_inc(5); /*Tell LVGL that 5 milliseconds were elapsed*/
}
}
```
## API
```eval_rst
.. doxygenfile:: lv_hal_tick.h
:project: lvgl
```