zenermerps/lvgl_esp32_drivers
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Better LVGL I2C README

Browse source
This commit is contained in:
Rop Gonggrijp 2021-07-12 10:24:24 +02:00
parent ef76fd1056
commit 6f2ce1307c
1 changed files with 32 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

57
i2c_manager/README.md
View file

@ -1,16 +1,18 @@
# I2C in `lvgl_esp32_drivers`
 
 
## Information for users
### I2C Manager support
`lvgl_esp32_drivers` comes with built-in I2C support by integrating I2C Manager, which is used in case your touch interface or screen uses the I2C bus. The native I2C support offered by ESP-IDF is not thread-safe. Maybe you use LVGL with a touch sensor that has an i2c port, and maybe your device also has another i2c device that needs to be read frequently, such as a 3D-accelerometer. If you read that from another task than the lvgl uses to read the touch data, you need some kind of mechanism to keep these communications from interfering.
`lvgl_esp32_drivers` comes with built-in I2C support by integrating I2C Manager, which is used in case you select a touch sensor or screen that uses the I2C bus. If you're just using LVGL you don't need to do anyting special.
If you have other components that can use I2C Manager (or Mika Tuupola's I2C HAL abstraction that I2C Manager is compatible with) then put I2C Manager in your components directory by cloning the repository from below and in your main program do:
I2C Manager can help if you are in a situation where you want to avoid "bus conflicts" on teh I2C bus. Suppose you use LVGL with a touch sensor that uses I2C, and your device also has another I2C device that needs to be read frequently, such as a 3D-accelerometer. ESP-IDF is not inherently "thread-safe". So if you read that from another task than the one LVGL uses to read the touch data, you need some kind of mechanism to keep these communications from interfering.
If you have (or write) a driver for that 3D-accelerometer that can use I2C Manager (or the I2C HAL and i2cdev abstraction layers that I2C Manager is compatible with) then put I2C Manager in your components directory by cloning the repository from below and in your main program do:
```c
#include "i2c_manager.h"
@ -18,54 +20,59 @@ If you have other components that can use I2C Manager (or Mika Tuupola's I2C HAL
[...]
lvgl_locking(i2c_manager_locking());
lvgl_i2c_locking(i2c_manager_locking());
lv_init();
lvgl_driver_init();
```
The `lvgl_locking` part will cause the LVGL I2C driver to play nice with anything else that uses the I2C port(s) through I2C Manager.
The `lvgl_i2c_locking` part will cause the LVGL I2C driver to play nice with anything else that uses the I2C port(s) through I2C Manager.
See the [I2C Manager GitHub repository](https://github.com/ropg/i2c_manager) for much more information.
Refer to the [I2C Manager GitHub repository](https://github.com/ropg/i2c_manager) for much more information.
 
## Information for LVGL driver developers
## Information for driver developers
I2C support in the LVGL ESP drivers is provided exclusively by the files in this directory. Code from all over the project that was talking to the I2C hardware directly has been replaced by code that communicates through the functions provided in `i2c_manager.h`. I2C is handled by the I2C Manager that was built into `lvlg_esp32_drivers`, but the code would be the same if it was routed through I2C Manager as a separate component. If you are providing a driver, you need not worry about any of this.
I2C support in the LVGL ESP drivers is provided exclusively by the files in this directory. Code from all over the project that was talking to the I2C hardware directly has been replaced by code that communicates through the functions provided in `lvgl_i2c.h`. I2C is handled by the I2C Manager that was built into lvlg_esp32_drivers, but the code would be the same if it was routed through I2C Manager as a separate component. If you are providing a driver, you need not worry about any of this.
### Using I2C in a driver, a multi-step guide
 
#### Step 1
The Kconfig entries for your driver only need to specify that you will be using I2C. This is done by `select LV_I2C_DISPLAY` or `select LV_I2C_TOUCH`.
### Using I2C in an LVGL driver, a multi-step guide
#### Step 2
Step 1
To use the I2C port in your code you would do something like:
: The Kconfig entries for your driver only need to specify that you will be using I2C. This is done by adding `select LV_I2C_DISPLAY` or `select LV_I2C_TOUCH`.
```c
#include "i2c_manager/i2c_manager.h"
Step 2
uint8_t data[2];
lvgl_i2c_read(CONFIG_LV_I2C_TOUCH_PORT, 0x23, 0x42, &data, 2);
```
: To use the I2C port in your code you would do something like:
This causes a touch driver to read two bytes at register `0x42` from the IC at address `0x23`. Replace `CONFIG_LV_I2C_TOUCH_PORT` by `CONFIG_LV_I2C_DISPLAY_PORT` when this is a display instead of a touch driver. `lvgl_i2c_write` works much the same way, except writing the bytes from the buffer instead of reading them.
```c
#include "i2c_manager/i2c_manager.h"
> The example above ignores it but these functions return `esp_err_t` so you can check if the i2c communication worked.
uint8_t data[2];
lvgl_i2c_read(CONFIG_LV_I2C_TOUCH_PORT, 0x23, 0x42, &data, 2);
```
#### Step 3
This causes a touch driver to read two bytes at register `0x42` from the IC at address `0x23`. Replace `CONFIG_LV_I2C_TOUCH_PORT` by `CONFIG_LV_I2C_DISPLAY_PORT` when this is a display instead of a touch driver. `lvgl_i2c_write` works much the same way, except it writes the bytes from the buffer instead of reading them. _(It's ignored above but these functions return `esp_err_t` so you can check if the I2C communication worked.)_
There is no step 3, you are already done.
Step 3
### Behind the scenes
: There is no step 3, you are already done.
If anything in `lvgl_esp32_drivers` uses I2C, the config system will pop up an extra menu. This will allow you to select an I2C port for screen and one for the touch driver, if applicable. An extra menu allows you to set the GPIO pins and bus speed of any port you have selected for use. It's perfectly fine for a display and a touch driver to use the same I2C port or different ones.
### Meanwhile, behind the scenes ...
If any of the drivers selected by the user uses I2C, the menuconfig system will show an extra menu to select I2C port(s) for screen and/or touch sensor. An additional menu allows for setting of GPIO pins and bus speed of any port selected for use with LVGL. It's perfectly fine for a display and a touch sensor to be on the same I2C port or different ones.
 
## More information
If you need more documentation, please refer to the [I2C Manager GitHub repository](https://github.com/ropg/i2c_manager) for more detailed information on how I2C manager works.
If you need more documentation, please refer to the [I2C Manager GitHub repository](https://github.com/ropg/i2c_manager) for more detailed information on how I2C manager works. There are features not in the simple example above, such as reads and writes without specifying a register, 16-bit registers, 10-bit I2C addressing and more.