Skip to content

Commit

Permalink
UPdated documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@rzeldent
rzeldent committed Jun 20, 2024
1 parent e05d69d commit ba66bb1
Showing 1 changed file with 98 additions and 98 deletions.
196 changes: 98 additions & 98 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Currently this library supports the following boards:
- ESP32-2432S032 N/R/C
- ESP32-3248S035 R/C
- ESP32-4827S043 R/C
- ESP32-4848S040C _I_Y_1/3
- ESP32-4848S040C \_I_Y_1/3
- ESP32-8048S050 N/C/R
- ESP32-8048S070 N/C/R

Expand Down Expand Up @@ -50,8 +50,8 @@ This library depends on:
- [LVGL](https://registry.platformio.org/libraries/lvgl/lvgl), currently version 8.3.9
- [platformio-espressif32-sunton](https://github.com/rzeldent/platformio-espressif32-sunton)

>[!NOTE]
>This library uses the "official" drivers from Espressif's component service. These drivers use the newly introduced esp_lcd_panel interfaces. This should provide some support in the future for updates and new boards. These drivers have already been copied and included to this library.
> [!NOTE]
> This library uses the "official" drivers from Espressif's component service. These drivers use the newly introduced esp_lcd_panel interfaces. This should provide some support in the future for updates and new boards. These drivers have already been copied and included to this library.
## How to use

Expand Down Expand Up @@ -82,22 +82,22 @@ Make sure you have PlatformIO installed and functional. Follow the documentation

### Step 2: Boards definitions

The board definitions required for this library are defined in the boards library [platformio-espressif32-sunton](https://github.com/rzeldent/platformio-espressif32-sunton). This library must reside in the ```<project>/boards``` directory so PlatformIo will automatically recognize these boards.
The board definitions required for this library are defined in the boards library [platformio-espressif32-sunton](https://github.com/rzeldent/platformio-espressif32-sunton). This library must reside in the `<project>/boards` directory so PlatformIo will automatically recognize these boards.

**It is recommended to use ```git submodule``` to include these board definitions automatically.**
**It is recommended to use `git submodule` to include these board definitions automatically.**

>[!TIP]
>If you already have a project, clone it with the ```git clone --recurse-submodules```. If creating a new project, use ```git submodule add https://github.com/rzeldent/platformio-espressif32-sunton.git boards``` to add them to your project as a submodule.
> [!TIP]
> If you already have a project, clone it with the `git clone --recurse-submodules`. If creating a new project, use `git submodule add https://github.com/rzeldent/platformio-espressif32-sunton.git boards` to add them to your project as a submodule.
### Step 3: Create a new project

Use the standard PlatformIO create project to start a new project. When using a new PlatformIO installation these boards, defined in [platformio-espressif32-sunton](https://github.com/rzeldent/platformio-espressif32-sunton), are not present. Just use a known ESP32 board and correct this later in the platformIO file.

Optionally, you can copy the boards definition to the ```<home>/.platformio\platforms\espressif32\boards``` directory to have them always available but it is probably easier to create the project, add the boards as a git submodule and change the board afterwards. For each supported board there is a board definition.
Optionally, you can copy the boards definition to the `<home>/.platformio\platforms\espressif32\boards` directory to have them always available but it is probably easier to create the project, add the boards as a git submodule and change the board afterwards. For each supported board there is a board definition.

### Step 4: Add this library to your project

To add this library (and its dependency on LVGL) add the following line to the ```platformio.ini``` file:
To add this library (and its dependency on LVGL) add the following line to the `platformio.ini` file:

From the platformIO registry (version 2.0.x):

Expand All @@ -115,15 +115,15 @@ This will automatically download the library, the LVGL library (as a dependency)

### Step 5: Create a settings file for LVGL

LVGL needs a configuration file; ```lv_conf.h```. This file contains information about the fonts, color depths, default background, styles, etc...
The default LVGL template can be found in the LVGL library at the location: ```lvgl/lv_conf_template.h```.
This file must be copied to the include directory and renamed to ```lvgl_conf.h```. Also the ``#if 0`` must be removed to enable the file to be included.
LVGL needs a configuration file; `lv_conf.h`. This file contains information about the fonts, color depths, default background, styles, etc...
The default LVGL template can be found in the LVGL library at the location: `lvgl/lv_conf_template.h`.
This file must be copied to the include directory and renamed to `lvgl_conf.h`. Also the `#if 0` must be removed to enable the file to be included.
More information about setting up a project with LVGL can be obtained at [LVGL get-started/quick-overview](https://docs.lvgl.io/master/get-started/quick-overview.html#add-lvgl-into-your-project).
I suggest to put the ```lv_conf.h``` file in the include directory and set the build flags to specify the location of the file, see below.
I suggest to put the `lv_conf.h` file in the include directory and set the build flags to specify the location of the file, see below.

>[!TIP]
>LVGL can also be downloaded manually from: [https://github.com/lvgl/lvgl/archive/master.zip](https://github.com/lvgl/lvgl/archive/master.zip) to extract the template.
>The template can also be copied from the demo application.
> [!TIP]
> LVGL can also be downloaded manually from: [https://github.com/lvgl/lvgl/archive/master.zip](https://github.com/lvgl/lvgl/archive/master.zip) to extract the template.
> The template can also be copied from the demo application.
Important settings are:

Expand All @@ -134,22 +134,6 @@ Important settings are:
#define LV_COLOR_DEPTH 16
```
- Because of the SPI interface, the bytes are sent in big endian format so this must be corrected.
The RGB panel interface takes care of this by swapping the GPIO lines but for the SPI controllers this is not optimal. More information about this can be found [below](#lv_color_16_swap).
```h
/*Swap the 2 bytes of RGB565 color. Useful if the display has an 8-bit interface (e.g. SPI)*/
#define LV_COLOR_16_SWAP 1
```

- To have a time reference use the milliseconds reference for the Arduino

```h
/*Use a custom tick source that tells the elapsed time in milliseconds and enables this code.*/
/*It removes the need to manually update the tick with `lv_tick_inc()`)*/
#define LV_TICK_CUSTOM 1
```
- For debugging, enable CPU usage, FPS (Frames per Second) and memory defragmentation
```h
Expand All @@ -159,41 +143,70 @@ Important settings are:

- (Optionally) Include additional fonts.

The font Montserrat 14pt is required. Other fonts can be included.

```h
...
#define LV_FONT_MONTSERRAT_22 1
...

```

- Optionally, only enable widgets that are used to save on code

```h
#define LV_USE_ARC 1
#define LV_USE_BAR 1
#define LV_USE_BTN 1
#define LV_USE_BTNMATRIX 1
...
```
```h
#define LV_USE_ANIMIMG 1
#define LV_USE_ARC 1
#define LV_USE_ARC 1
#define LV_USE_BAR 1
#define LV_USE_BUTTON 1
#define LV_USE_BUTTONMATRIX 1
#define LV_USE_CALENDAR 1
#define LV_USE_CANVAS 1
#define LV_USE_CHART 1
#define LV_USE_CHECKBOX 1
#define LV_USE_DROPDOWN 1 /*Requires: lv_label*/
#define LV_USE_IMAGE 1 /*Requires: lv_label*/
#define LV_USE_IMAGEBUTTON 1
#define LV_USE_KEYBOARD 1
#define LV_USE_LABEL 1
#define LV_USE_LED 1
#define LV_USE_LINE 1
#define LV_USE_LIST 1
#define LV_USE_MENU 1
#define LV_USE_MSGBOX 1
#define LV_USE_ROLLER 1 /*Requires: lv_label*/
#define LV_USE_SCALE 1
#define LV_USE_SLIDER 1 /*Requires: lv_bar*/
#define LV_USE_SPAN 1
#define LV_USE_SPINBOX 1
#define LV_USE_SPINNER 1
#define LV_USE_SWITCH 1
#define LV_USE_TEXTAREA 1 /*Requires: lv_label*/
#define LV_USE_TABLE 1
#define LV_USE_TABVIEW 1
#define LV_USE_TILEVIEW 1
#define LV_USE_WIN 1
```
For debugging it is possible to enable logging from LVGL. The library will output to the debugging output (using ```lv_log_register_print_cb```).
For debugging it is possible to enable logging from LVGL. The library will output to the debugging output (using `lv_log_register_print_cb`).
To enable logging, set the define:
```h
/*Enable the log module*/
#define LV_USE_LOG 1
```

By default the logging is only ```LV_LOG_LEVEL_WARN``` but can be adjusted in the ```lv_conf.h```.
By default the logging is only `LV_LOG_LEVEL_WARN` but can be adjusted in the `lv_conf.h`.

More information about the LVGL configuration can be found in the excellent [LVGL documentation](https://docs.lvgl.io/8.3/index.html).

>[!WARNING]
>After the library has been build, changes in the lv_conf.h are no longer applied because libraries are cached.
>To apply these settings, delete the ```.pio``` directory so the libraries will be rebuild.
> [!WARNING]
> After the library has been build, changes in the lv_conf.h are no longer applied because libraries are cached.
> To apply these settings, delete the `.pio` directory so the libraries will be rebuild.

### Step 6: Copy the build flags below in your project

Especially the definition of the LV_CONF_PATH is critical, this must point to an **absolute path** where the ```lv_conf.h``` file is located. More about this in the [section below](#more-on-lv_confh).
Especially the definition of the LV_CONF_PATH is critical, this must point to an **absolute path** where the `lv_conf.h` file is located. More about this in the [section below](#more-on-lv_confh).

```ini
build_flags =
Expand All @@ -216,26 +229,32 @@ The -Wall flag can also be removed but outputs all the warnings.

### Step 7: Initialize the display (and touch) in your project

To enable to display in your project call the void ```smartdisplay_init()``` function at startup and optionally set the orientation:
To enable to display in your project call the void `smartdisplay_init()` function at startup and optionally set the orientation:

```cpp
void setup()
{
smartdisplay_init();

auto disp = lv_display_get_default();
// lv_display_set_rotation(disp, LV_DISP_ROT_90);
// lv_display_set_rotation(disp, LV_DISP_ROT_180);
// lv_display_set_rotation(disp, LV_DISP_ROT_270);
auto display = lv_display_get_default();
// lv_display_set_rotation(display, LV_DISPLAY_ROTATION_90);
// lv_display_set_rotation(display, LV_DISPLAY_ROTATION_180);
// lv_display_set_rotation(display, LV_DISPLAY_ROTATION_270);
}
```

and update the timer (and drawing) in the loop:
and update tick update and drawing in the loop:

```cpp
auto lv_last_tick = millis();

void loop()
{
lv_timer_handler();
// Update the ticker
lv_tick_inc(now - lv_last_tick);
lv_last_tick = now;
// Update the UI
lv_timer_handler();
}
```

Expand All @@ -248,7 +267,7 @@ There is a good UI designer available for LVGL and free (but some limitations) f
This tool makes it easy to create transitions, insert images, attach events, work with round screens etc.. A big advantage is that the UI C-code is generated!
SquareLine als provides drivers but only export the ui files!

In the project settings change the include ```lvgl/lvgl.h``` to ```lvgl.h```.
In the project settings change the include `lvgl/lvgl.h` to `lvgl.h`.

## Step 9: Compile, upload and enjoy

Expand All @@ -275,26 +294,8 @@ To include it globally, the define must be (for the include directory):
-D LV_CONF_PATH=${PROJECT_INCLUDE_DIR}/lv_conf.h
```

>[!TIP]
>The template for the `lv_conf.h` file can be found in the LVGL library at `.pio/libdeps/<board>/lvgl/lv_conf_template.h`.
## LV_COLOR_16_SWAP

The LVGL library has a define called **LV_COLOR_16_SWAP** in the ```lvgl_conf.h```. The value can be 1 or 0.
This variable will swap the byte order of the lv_color16_t. This is required because the SPI is by default LSB first.

Setting this variable to true is recommended for the SPI interfaces (GC9A01A, ST7789, ILI9341 and ST7796). If not, a warning will be issued but the code should work. The parallel 16 bits panels without interface are not affected by this; the GPIO pin layout will change accordingly.

This makes it easier to have only one definition for lv_conf.h and SquareLine.

>[!IMPORTANT]
>If this is not done, the code will run but swapping will be done runtime (degrading a bit the performance).
>So it is preferable to always set the LV_COLOR_16_SWAP to 1 when using SPI.
Additionally, when using the [SquareLine Studio](https://squareline.io/) for designing the user interface, the display properties (under the project settings) must match this variable.
It needs to be set both in `lv_conf.h` configuration file and the corresponding display properties (16 bit swap) in [SquareLine Studio](https://squareline.io/).

![SquareLine display properties](assets/images/Squareline-display-properties.png)
> [!TIP]
> The template for the `lv_conf.h` file can be found in the LVGL library at `.pio/libdeps/<board>/lvgl/lv_conf_template.h`.
## LVGL initialization Functions

Expand All @@ -312,7 +313,7 @@ The range is from [0, 1] so 0 is off, 0.5 is half and 1 is full brightness.

### void smartdisplay_lcd_set_brightness_cb(smartdisplay_lcd_adaptive_brightness_cb_t cb, uint interval)

This function can be called to periodically call a user defined function to set the brightness of the display. If a NULL value is passed for the parameter ```cb``` the functionality is disabled and the display is set to 50% brightness.
This function can be called to periodically call a user defined function to set the brightness of the display. If a NULL value is passed for the parameter `cb` the functionality is disabled and the display is set to 50% brightness.

The callback function must have the following format:

Expand All @@ -324,7 +325,7 @@ float smartdisplay_lcd_adaptive_brightness_function)()
}
```

If the board has a CdS sensor, a callback is automatically provided. The callback can be set to the internal function ```smartdisplay_lcd_set_brightness_cb```.
If the board has a CdS sensor, a callback is automatically provided. The callback can be set to the internal function `smartdisplay_lcd_set_brightness_cb`.
This function will adjust the brightness to the value read from the CdS sensor on the front of the display.

So, to enable adaptive brightness using the CdS sensor, call
Expand All @@ -343,7 +344,7 @@ A true value means: ON (LED is lit), false turns off the led.
This function allows only 8 LED colors:
| R | G | B | Color |
|--- |--- |--- |--- |
| --- | --- | --- | ------- |
| 0 | 0 | 0 | Black |
| 1 | 0 | 0 | Red |
| 0 | 1 | 0 | Green |
Expand All @@ -362,43 +363,42 @@ This data structure holds the calibration data for the touch display. If the val
### touch_calibration_data_t smartdisplay_compute_touch_calibration(const lv_point_t screen[3], const lv_point_t touch[3])
This function returns the calibration data based on 3 points. The screen array contains the (selected) calibration points on the screen and the touch array the actual measured position.
The data returned can set in to the ```touch_calibration_data```
The data returned can set in to the `touch_calibration_data`
## Rotation of the display and touch
The library supports rotating for most of the controllers using hardware. Support for the direct 16bits parallel connection is done using software emulation (in LVGL). Rotating the touch is done by LVGL when rotating.
From the LVGL documentation:
*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.*
_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._
Rotating is done calling the ```lv_display_set_rotation``` function in the LVGL library with the rotation:
Rotating is done calling the `lv_display_set_rotation` function in the LVGL library with the rotation:
```c++
auto disp = lv_display_get_default();
lv_display_set_rotation(disp, LV_DISPLAY_ROTATION_90);
auto display = lv_display_get_default();
lv_display_set_rotation(display, LV_DISPLAY_ROTATION_90);
```

Some boards are around that have flipped screens, this is probably due to differences during tha manufacturing or using different TFTs. It is possible to correct these boards overriding the default defines.

To adjust the display and touch to the default (LV_DISP_ROT_NONE) there are 6 defines in the boards definition:

| Name | Description |
|--- |--- |
| DISPLAY_SWAP_XY | Swaps the X and Y coordinates for the display |
| DISPLAY_MIRROR_X | Mirrors the X coordinate for the display |
| DISPLAY_MIRROR_Y | Mirrors the Y coordinate for the display |
| TOUCH_SWAP_XY | Swaps the X and Y coordinates for the touch |
| TOUCH_MIRROR_X | Mirrors the X coordinate for the touch |
| TOUCH_MIRROR_Y | Mirrors the Y coordinate for the touch |
| Name | Description |
| ---------------- | --------------------------------------------- |
| DISPLAY_SWAP_XY | Swaps the X and Y coordinates for the display |
| DISPLAY_MIRROR_X | Mirrors the X coordinate for the display |
| DISPLAY_MIRROR_Y | Mirrors the Y coordinate for the display |
| TOUCH_SWAP_XY | Swaps the X and Y coordinates for the touch |
| TOUCH_MIRROR_X | Mirrors the X coordinate for the touch |
| TOUCH_MIRROR_Y | Mirrors the Y coordinate for the touch |

## Appendix: Template to support ALL the boards

The platformio.ini file below supports all the boards. This is useful when running your application on multiple boards. If using one board only, uncomment the ```default_envs``` for that board in the ```[platformio]``` section.
The platformio.ini file below supports all the boards. This is useful when running your application on multiple boards. If using one board only, uncomment the `default_envs` for that board in the `[platformio]` section.

>[!TIP]
>When building using a pipeline (github action), the ini below, with all the boards, can be used automatically create builds for all the boards.
> [!TIP]
> When building using a pipeline (github action), the ini below, with all the boards, can be used automatically create builds for all the boards.
```ini
[platformio]
Expand Down Expand Up @@ -452,7 +452,7 @@ build_flags =
-D CORE_DEBUG_LEVEL=ARDUHAL_LOG_LEVEL_VERBOSE
# LVGL settings
#-DLV_CONF_PATH=${PROJECT_INCLUDE_DIR}/lv_conf.h

lib_deps =
https://github.com/rzeldent/esp32-smartdisplay.git

Expand Down Expand Up @@ -554,8 +554,8 @@ board = esp32-8048S070R

The following libraries are used from the [Espressif component registry](https://components.espressif.com/):

| Name | Version |
|--- |--- |
| Name | Version |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| [ESP_LCD_PANEL_IO_ADDITIONS](https://components.espressif.com/api/download/?object_type=component&object_id=fc4eba6f-2091-4b28-8703-df58c6c975c7) | v1.0.0 |
| [ESP IO Expander Component](https://components.espressif.com/api/download/?object_type=component&object_id=44022a0f-c4b2-40c0-b2a2-40d7b648cb52) | v1.0.0 |
| [ESP LCD Touch](https://components.espressif.com/api/download/?object_type=component&object_id=bb4a4d94-2827-4695-84d1-1b53383b8001) | v1.1.1 |
Expand Down

0 comments on commit ba66bb1

Please sign in to comment.