Components for Espressif ESP32 ESP-IDF framework and ESP8266 RTOS SDK.
Part of them ported from esp-open-rtos.
- master
- 4.x
- 3.2.2
- ESP32
- ESP32S2
Use "idf.py set-target esp32s2" before "idf.py menuconfig" to change the chip type.
- master
- 3.3
- 3.2
Due to incompatibilities in ESP8266 RTOS SDK's SPI driver and hardware, the following libraries are not supported on ESP8266.
max7219
mcp23x17
led_strip
Clone this repository somewhere, e.g.:
cd ~/myprojects/esp
git clone https://github.com/UncleRus/esp-idf-lib.git
Add path to components in your project makefile, e.g:
PROJECT_NAME := my-esp-project
EXTRA_COMPONENT_DIRS := /home/user/myprojects/esp/esp-idf-lib/components
include $(IDF_PATH)/make/project.mk
or in CMakeLists.txt:
cmake_minimum_required(VERSION 3.5)
set(EXTRA_COMPONENT_DIRS /home/user/myprojects/esp/esp-idf-lib/components)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(my-esp-project)
or with CMake FetchContent
cmake_minimum_required(VERSION 3.11)
include(FetchContent)
FetchContent_Declare(
espidflib
GIT_REPOSITORY https://github.com/UncleRus/esp-idf-lib.git
)
FetchContent_MakeAvailable(espidflib)
set(EXTRA_COMPONENT_DIRS ${espidflib_SOURCE_DIR}/components)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(my-esp-project)
Clone this repository somewhere, e.g.:
cd ~/myprojects/esp
git clone https://github.com/UncleRus/esp-idf-lib.git
Add path to components in your project makefile, e.g:
PROJECT_NAME := my-esp-project
EXTRA_COMPONENT_DIRS := /home/user/myprojects/esp/esp-idf-lib/components
EXCLUDE_COMPONENTS := max7219 mcp23x17 led_strip
include $(IDF_PATH)/make/project.mk
See GitHub examples or GitLab examples.
If examples is not enough you can read autogenerated documentation: https://esp-idf-lib.readthedocs.io/en/latest/
Component | Description | License | Thread safety |
---|---|---|---|
i2cdev | I2C utilites | MIT | Yes |
onewire | Bit-banging one wire driver | MIT * | No |
Component | Description | License | Thread safety |
---|---|---|---|
ds1302 | Driver for DS1302 RTC module | BSD | No |
ds1307 | Driver for DS1307 RTC module | BSD | Yes |
ds3231 | Driver for DS1337 RTC and DS3231 high precision RTC module | MIT | Yes |
pcf8563 | Driver for PCF8563 real-time clock/calendar | BSD | Yes |
Component | Description | License | Thread safety |
---|---|---|---|
dht | Driver for DHT11, AM2301 (DHT21, DHT22, AM2302, AM2321), Itead Si7021 | BSD | No |
sht31x | Driver for Sensirion SHT3x digital temperature and humidity sensor | BSD | Yes |
si7021 | Driver for Si7013/Si7020/Si7021/HTU21D/SHT2x and compatible | BSD | Yes |
ds18x20 | Driver for DS18B20/DS18S20 families of one-wire temperature sensor ICs | BSD | No |
max31725 | Driver for MAX31725/MAX31726 temperature sensors | BSD | Yes |
lm75 | Driver for LM75, a digital temperature sensor and thermal watchdog | ISC | Yes |
mcp9808 | Driver for MCP9808, precision digital temperature sensor | BSD | Yes |
Component | Description | License | Thread safety |
---|---|---|---|
bmp180 | Driver for BMP180 digital pressure sensor | MIT | Yes |
bmp280 | Driver for BMP280/BME280 digital pressure sensor | MIT | Yes |
bme680 | Driver for BME680 digital environmental sensor | BSD | Yes |
ms5611 | Driver for barometic pressure sensor MS5611-01BA03 | BSD | Yes |
Component | Description | License | Thread safety |
---|---|---|---|
ads111x | Driver for ADS1113/ADS1114/ADS1115 and ADS1013/ADS1014/ADS1015 I2C ADC | BSD | Yes |
hx711 | Driver for HX711 24-bit ADC for weigh scales | BSD | Yes |
mcp4725 | Driver for 12-bit DAC MCP4725 | BSD | Yes |
pcf8591 | Driver for 8-bit ADC and an 8-bit DAC PCF8591 | BSD | Yes |
mcp342x | Driver for 18-Bit, delta-sigma ADC MCP3426/MCP3427/MCP3428 | BSD | Yes |
Component | Description | License | Thread safety |
---|---|---|---|
ina3221 | Driver for INA3221 shunt and bus voltage monitor | MIT | Yes |
ina219 | Driver for INA219/INA220 bidirectional current/power monitor | BSD | Yes |
ina260 | Driver for INA260 precision digital current and power monitor | BSD | Yes |
Component | Description | License | Thread safety |
---|---|---|---|
hmc5883l | Driver for HMC5883L 3-axis digital compass | BSD | Yes |
qmc5883l | Driver for QMC5883L 3-axis magnetic sensor | BSD | Yes |
Component | Description | License | Thread safety |
---|---|---|---|
bh1750 | Driver for BH1750 light sensor | BSD | Yes |
tsl2561 | Driver for light-to-digital converter TSL2561 | BSD | Yes |
tsl4531 | Driver for digital ambient light sensor TSL4531 | BSD | Yes |
Component | Description | License | Thread safety |
---|---|---|---|
pcf8574 | Driver for PCF8574 remote 8-bit I/O expander for I2C-bus | MIT | Yes |
pcf8575 | Driver for PCF8575 remote 16-bit I/O expander for I2C-bus | MIT | Yes |
tca95x5 | Driver for TCA9535/TCA9555 remote 16-bit I/O expanders for I2C-bus | BSD | Yes |
mcp23008 | Driver for 8-bit I2C GPIO expander MCP23008 | BSD | Yes |
mcp23x17 | Driver for I2C/SPI 16 bit GPIO expanders MCP23017/MCP23S17 | BSD | Yes |
Component | Description | License | Thread safety |
---|---|---|---|
ultrasonic | Driver for ultrasonic range meters, e.g. HC-SR04, HY-SRF05 | BSD | No |
hd44780 | Universal driver for HD44780 LCD display | BSD | No |
pca9685 | Driver for 16-channel, 12-bit PWM PCA9685 | BSD | Yes |
max7219 | Driver for 8-Digit LED display drivers, MAX7219/MAX7221 | BSD | Yes |
tda74xx | Driver for TDA7439/TDA7439DS/TDA7440D audioprocessors | MIT | Yes |
encoder | HW timer-based driver for incremental rotary encoders | BSD | Yes |
tca9548 | Driver for TCA9548A/PCA9548A low-voltage 8-channel I2C switch | BSD | Yes |
led_strip | RMT-based driver for WS2812B/SK6812/APA106 LED strips | MIT | Yes |
rda5807m | Driver for single-chip broadcast FM radio tuner RDA5807M | BSD | Yes |
Common causes of I2C issues are:
- wrong wiring
- wrong pull-up resistors
- wrong I2C address
- broken I2C module
- the driver has a bug
When any of I2C-based drivers does not work, follow the steps below.
Build an I2C scanner device. The device is not necessarily an ESP device.
There are many examples for various platforms. Search by keyword i2c scanner
.
Connect the I2C module to the I2C scanner device. Make sure appropriate
pull-up registers are connected to SCL
and SDA
lines.
Scan devices on the I2C bus. If the scanner does not find the I2C device, then your wiring might have issues. If the scanner finds the I2C device, make sure the address found is what the driver expects. If you have more than one same I2C modules, try them all.
If the scanner finds the I2C device and you are sure that the wiring is correct, see the signals on the wire using an oscilloscope. Most oscilloscopes can decode I2C signals and display I2C transactions in human-readable way.
If the driver does not work after these steps, please let us know.
i2cdev uses two types of mutexes: port and transactional.
Port mutexes (there are only two of them, by the number of I2C ports) are necessary to avoid problems in the situation mentioned in the documentation:
The I2C APIs are not thread-safe, if you want to use one I2C port in different tasks, you need to take care of the multi-thread issue.
They are taken before executing single I2C transactions and are released immediately after them.
Mutexes of the second type are created one per device and are necessary if the same device is used in several tasks:
static i2c_dev_t some_dev;
void task1(void *arg)
{
// some_dev used here
}
void task2(void *arg)
{
// and here some_dev used too
}
...
xTaskCreate(task1, "task1", ....);
xTaskCreate(task2, "task2", ....);
These mutexes are used when single device operation requires several I2C transactions in a row.
With i2cdev, you can use almost any way to connect I2C devices.
For example, in the case of using SSD1306 and two MCP3428s, I would recommend connecting them like this:
- 2 GPIO outputs on ESP32 for dedicated screen connection via I2C bus 0
- 2 GPIO outputs to the second I2C bus, to which 2 MCP3428 are connected with different addresses.
If you need to connect more than one sensor with the same addresses and there are free GPIOs, then you can directly connect these sensors to individual GPIO outputs instead of using the I2C multiplexer. i2cdev will take care of reconfiguring I2C driver to the according outputs when you exchange data with these devices.
How can I change frequency of I2C clock? At default frequency my device is unstable or not working at all.
You can change the frequency after initializing the device handler, like this:
#include <esp_idf_lib_helpers.h>
...
ESP_ERROR_CHECK(ads111x_init_desc(&dev, addr, I2C_PORT, SDA_GPIO, SCL_GPIO));
#if HELPER_TARGET_IS_ESP32
dev.cfg.master.clk_speed = 100000; // Hz
#endif
ESP_ERROR_CHECK(ads111x_set_mode(&dev, ADS111X_MODE_CONTINUOS)); // Continuous conversion mode
ESP_ERROR_CHECK(ads111x_set_data_rate(&dev, ADS111X_DATA_RATE_32)); // 32 samples per second
...
- Tomoyuki Sakurai, developer of the LM75 driver, author of the RTOS SDK ESP82666 support, master CI
- Gunar Schorcht, developer of SHT3x and BME680 drivers
- Brian Schwind, developer of TS2561 and TSL4531 drivers
- Andrej Krutak, developer of BH1750 driver
- Frank Bargstedt, developer of BMP180 driver
- sheinz, developer of BMP280 driver
- Jonathan Hartsuiker, developer of DHT driver
- Grzegorz Hetman, developer of DS18B20 driver
- Alex Stewart, developer of DS18B20 driver
- Richard A Burton, developer of DS3231 driver
- Bhuvanchandra DV, developer of DS3231 driver
- Zaltora, developer of INA3231 driver
- Bernhard Guillon, developer of MS5611-01BA03 driver
- Pham Ngoc Thanh, developer of PCF8591 driver
- Lucio Tarantino, developer of ADS111x driver