esp32libs/dht22_sensor
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

readme

Browse Source
This commit is contained in:
Andrey Aleksandrov
2025-12-30 22:07:10 +02:00
parent 236d5e4a8c
commit 4f1f4c9fef
1 changed files with 499 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

554
README.md
View File

@@ -1,97 +1,541 @@
# ESP32 Custom Libraries Collection
# DHT22 Sensor Library for ESP32
A collection of custom libraries designed for ESP32 development with ESP-IDF framework. These libraries are optimized for IoT sensor projects and provide reliable, reusable components.
A robust and feature-rich DHT22/AM2302 sensor library designed for ESP32 development with ESP-IDF framework. This library uses bit-banging implementation for reliable temperature and humidity readings.
## Libraries Overview
## 📋 Features
### 🌡️ DHT22 Sensor (`dht22_sensor`)
- ✅ **Robust bit-banging implementation** - No dependency on specific hardware timers
- ✅ **Configurable timing parameters** - Adjust for different sensor variants
- ✅ **Multiple sensor support** - Read from different GPIO pins
- ✅ **Comprehensive error handling** - Timeout and checksum validation
- ✅ **Thread-safe operations** - Safe for use in multi-task environments
- ✅ **Flexible initialization** - Default or custom configuration options
- ✅ **Memory efficient** - Minimal RAM footprint
- ✅ **Well documented** - Complete API documentation
- **Version**: 1.0.0
- **Description**: Custom DHT22/AM2302 sensor library with bit-banging implementation
- **Features**: Temperature and humidity reading with robust timing control
- **Use Case**: Environmental monitoring projects
## 📦 Installation
### Method 1: Git
### Method 1: Git Submodule
```bash
cd your_project_directory
mkdir dht22
git clone https://home.arcoa.eu:8413/esp32libs/dht22_sensor.git
cd your_project_directory/lib
git submodule add https://home.arcoa.eu:8413/esp32libs/dht22_sensor.git
```
### Method 2: Manual Copy
1. Clone or download this repository
2. Copy the desired library folders to your project's `lib/` directory
3. Include the headers in your main code
2. Copy the `dht22_sensor` folder to your project's `lib/` or `components/` directory
3. Include the header in your code: `#include "dht22_sensor.h"`
### Method 3: PlatformIO Library
Each library contains a `library.json` file for PlatformIO compatibility.
Add to your `platformio.ini`:
## Usage Example
```ini
lib_deps =
git+https://home.arcoa.eu:8413/esp32libs/dht22_sensor.git
```
## 🚀 Quick Start
### Basic Usage
```c
#include "dht22_sensor.h"
#include "wifi_manager.h"
#include "mqtt_manager.h"
#include "led_manager.h"
void app_main(void) {
// Initialize WiFi
wifi_manager_config_t wifi_config = {
.ssid = "YourSSID",
.password = "YourPassword"
};
wifi_manager_init(&wifi_config);
// Initialize DHT22 on GPIO 4
esp_err_t ret = dht22_init(GPIO_NUM_4);
if (ret != ESP_OK) {
printf("DHT22 initialization failed: %s\n", esp_err_to_name(ret));
return;
}
// Initialize MQTT
mqtt_manager_config_t mqtt_config = {
.broker_url = "mqtt://your-broker.com",
.client_id = "esp32_sensor"
};
mqtt_manager_init(&mqtt_config);
// Initialize DHT22 sensor
dht22_init(GPIO_NUM_4);
// Initialize LED for status indication
led_manager_init(GPIO_NUM_8, 1);
// Your application logic here
while (1) {
float temperature, humidity;
if (dht22_read(&temperature, &humidity) == ESP_OK) {
mqtt_publish_sensor_data(temperature, humidity);
led_manager_set_color(0, 255, 0); // Green for success
dht22_result_t result = dht22_read(&temperature, &humidity);
if (result == DHT22_OK) {
printf("Temperature: %.2f°C, Humidity: %.2f%%\n", temperature, humidity);
} else {
led_manager_set_color(255, 0, 0); // Red for error
printf("Read error: %s\n", dht22_get_error_string(result));
}
vTaskDelay(pdMS_TO_TICKS(30000)); // 30 second interval
vTaskDelay(pdMS_TO_TICKS(2000)); // Wait 2 seconds
}
}
```
## Library Dependencies
### Advanced Usage with Custom Configuration
```
mqtt_manager → (none)
```c
#include "dht22_sensor.h"
void app_main(void) {
// Custom configuration for different timing requirements
dht22_config_t config = {
.gpio_pin = GPIO_NUM_4,
.start_signal_us = 18000, // 18ms start signal
.response_timeout_us = 500, // 500µs response timeout
.data_timeout_us = 150, // 150µs data timeout
.bit_threshold_us = 40 // 40µs threshold for 0/1 detection
};
esp_err_t ret = dht22_init_with_config(&config);
if (ret != ESP_OK) {
printf("DHT22 initialization failed!\n");
return;
}
// Test connection
if (dht22_test_connection()) {
printf("DHT22 sensor detected and responding\n");
} else {
printf("DHT22 sensor not responding\n");
return;
}
while (1) {
dht22_data_t sensor_data;
dht22_result_t result = dht22_read_data(&sensor_data);
if (result == DHT22_OK) {
printf("Temperature: %.2f°C\n", sensor_data.temperature);
printf("Humidity: %.2f%%\n", sensor_data.humidity);
} else {
printf("Error reading sensor: %s\n", dht22_get_error_string(result));
}
vTaskDelay(pdMS_TO_TICKS(2000));
}
}
```
## Configuration
## 📚 API Reference
Library includes configuration options through header files. Check individual library documentation for specific configuration parameters.
### Data Types
### Common GPIO Assignments
#### `dht22_result_t` (Enum)
- **DHT22**: Any GPIO pin (recommended: GPIO 4)
- **LED Strip**: Any GPIO pin (recommended: GPIO 8)
- **Built-in LED**: GPIO 2 (ESP32-C6)
Result codes returned by DHT22 read functions:
## Compatibility
| Value | Description |
| --------------------------- | ---------------------------- |
| `DHT22_OK` (0) | Reading successful |
| `DHT22_TIMEOUT_ERROR` (-1) | Timeout during communication |
| `DHT22_CHECKSUM_ERROR` (-2) | Checksum verification failed |
- **Framework**: ESP-IDF
#### `dht22_config_t` (Struct)
Configuration structure for DHT22 sensor:
```c
typedef struct {
int gpio_pin; // GPIO pin number where DHT22 is connected
uint32_t start_signal_us; // Start signal duration in microseconds (default: 18000)
uint32_t response_timeout_us; // Response timeout in microseconds (default: 500)
uint32_t data_timeout_us; // Data bit timeout in microseconds (default: 150)
uint32_t bit_threshold_us; // Threshold for 0/1 bit detection (default: 40)
} dht22_config_t;
```
**Field Descriptions:**
- `gpio_pin`: Any valid GPIO pin number (0-39 depending on ESP32 variant)
- `start_signal_us`: Duration of start signal sent to DHT22 (typically 18000µs)
- `response_timeout_us`: Maximum time to wait for sensor response
- `data_timeout_us`: Maximum time to wait for each data bit
- `bit_threshold_us`: Time threshold to distinguish between 0 and 1 bits
#### `dht22_data_t` (Struct)
Structure to hold sensor readings:
```c
typedef struct {
float temperature; // Temperature in degrees Celsius
float humidity; // Relative humidity percentage
} dht22_data_t;
```
### Constants
#### Default Timing Constants (microseconds)
| Constant | Value | Description |
| ----------------------------------- | ----- | ----------------------------------- |
| `DHT22_DEFAULT_START_SIGNAL_US` | 18000 | Default start signal duration |
| `DHT22_DEFAULT_RESPONSE_TIMEOUT_US` | 500 | Default response timeout |
| `DHT22_DEFAULT_DATA_TIMEOUT_US` | 150 | Default data bit timeout |
| `DHT22_DEFAULT_BIT_THRESHOLD_US` | 40 | Default 0/1 bit detection threshold |
### Functions
#### Initialization Functions
##### `esp_err_t dht22_init(int gpio_pin)`
Initialize DHT22 sensor with default configuration.
**Parameters:**
- `gpio_pin`: GPIO pin number where DHT22 data line is connected
**Returns:**
- `ESP_OK`: Success
- `ESP_ERR_INVALID_ARG`: Invalid GPIO pin number
- Other ESP error codes on failure
**Example:**
```c
esp_err_t ret = dht22_init(GPIO_NUM_4);
if (ret != ESP_OK) {
printf("Init failed: %s\n", esp_err_to_name(ret));
}
```
##### `esp_err_t dht22_init_with_config(const dht22_config_t *config)`
Initialize DHT22 sensor with custom configuration.
**Parameters:**
- `config`: Pointer to configuration structure
**Returns:**
- `ESP_OK`: Success
- `ESP_ERR_INVALID_ARG`: Invalid configuration or NULL pointer
- Other ESP error codes on failure
**Example:**
```c
dht22_config_t config = {
.gpio_pin = GPIO_NUM_4,
.start_signal_us = 20000, // Longer start signal
.response_timeout_us = 600,
.data_timeout_us = 200,
.bit_threshold_us = 50
};
esp_err_t ret = dht22_init_with_config(&config);
```
##### `esp_err_t dht22_deinit(void)`
Deinitialize the DHT22 sensor and free resources.
**Returns:**
- `ESP_OK`: Success
- Error code on failure
**Example:**
```c
dht22_deinit();
```
#### Reading Functions
##### `dht22_result_t dht22_read(float *temperature, float *humidity)`
Read temperature and humidity from the initialized DHT22 sensor.
**Parameters:**
- `temperature`: Pointer to store temperature value (°C)
- `humidity`: Pointer to store humidity value (%)
**Returns:**
- `DHT22_OK`: Reading successful
- `DHT22_TIMEOUT_ERROR`: Communication timeout
- `DHT22_CHECKSUM_ERROR`: Data integrity check failed
**Example:**
```c
float temp, hum;
dht22_result_t result = dht22_read(&temp, &hum);
if (result == DHT22_OK) {
printf("Temp: %.1f°C, Humidity: %.1f%%\n", temp, hum);
}
```
##### `dht22_result_t dht22_read_data(dht22_data_t *data)`
Read temperature and humidity into a data structure.
**Parameters:**
- `data`: Pointer to `dht22_data_t` structure to fill
**Returns:**
- Same as `dht22_read()`
**Example:**
```c
dht22_data_t sensor_data;
if (dht22_read_data(&sensor_data) == DHT22_OK) {
printf("Temperature: %.1f°C\n", sensor_data.temperature);
printf("Humidity: %.1f%%\n", sensor_data.humidity);
}
```
##### `dht22_result_t dht22_read_from_pin(int gpio_pin, float *temperature, float *humidity)`
Read from a specific GPIO pin (useful for multiple sensors).
**Parameters:**
- `gpio_pin`: GPIO pin number to read from
- `temperature`: Pointer to store temperature value
- `humidity`: Pointer to store humidity value
**Returns:**
- Same as `dht22_read()`
**Example:**
```c
float temp1, hum1, temp2, hum2;
// Read from sensor on GPIO 4
dht22_read_from_pin(GPIO_NUM_4, &temp1, &hum1);
// Read from sensor on GPIO 5
dht22_read_from_pin(GPIO_NUM_5, &temp2, &hum2);
```
#### Utility Functions
##### `const char *dht22_get_error_string(dht22_result_t result)`
Get human-readable error message for a result code.
**Parameters:**
- `result`: DHT22 result code
**Returns:**
- Pointer to error message string
**Example:**
```c
dht22_result_t result = dht22_read(&temp, &hum);
if (result != DHT22_OK) {
printf("Error: %s\n", dht22_get_error_string(result));
}
```
##### `bool dht22_test_connection(void)`
Test if DHT22 sensor is properly connected and responding.
**Returns:**
- `true`: Sensor is connected and responding
- `false`: Sensor not detected or not responding
**Example:**
```c
if (dht22_test_connection()) {
printf("Sensor OK\n");
} else {
printf("Sensor not detected!\n");
}
```
## 🔧 Configuration Guide
### GPIO Configuration
**Compatible GPIO pins:**
- ESP32: All GPIO pins except GPIO 0, 2, 5, 12, 15 (used for boot/flash)
- ESP32-C3/C6: GPIO 0-21 (avoid GPIO 18, 19 for USB)
- ESP32-S2/S3: GPIO 0-21, 26-45
**Recommended pins:**
- GPIO 4, 16, 17, 21, 22, 23
### Timing Parameters
The library uses these timing parameters that can be customized:
| Parameter | Default | Range | Description |
| ---------------- | ------- | ------------ | ------------------------------------ |
| Start Signal | 18000µs | 1000-25000µs | Initial low pulse to wake up sensor |
| Response Timeout | 500µs | 100-1000µs | Max time to wait for sensor response |
| Data Timeout | 150µs | 50-300µs | Max time to wait for each data bit |
| Bit Threshold | 40µs | 20-80µs | Time threshold for 0/1 detection |
### Multiple Sensors
To use multiple DHT22 sensors:
```c
void multi_sensor_example(void) {
// Read from multiple sensors
float temp1, hum1, temp2, hum2;
dht22_result_t result1 = dht22_read_from_pin(GPIO_NUM_4, &temp1, &hum1);
vTaskDelay(pdMS_TO_TICKS(10)); // Small delay between reads
dht22_result_t result2 = dht22_read_from_pin(GPIO_NUM_16, &temp2, &hum2);
if (result1 == DHT22_OK) {
printf("Sensor 1 - Temp: %.1f°C, Hum: %.1f%%\n", temp1, hum1);
}
if (result2 == DHT22_OK) {
printf("Sensor 2 - Temp: %.1f°C, Hum: %.1f%%\n", temp2, hum2);
}
}
```
## 🔍 Troubleshooting
### Common Issues
1. **DHT22_TIMEOUT_ERROR**
- Check wiring connections
- Verify GPIO pin number
- Increase timeout values in configuration
- Check power supply (3.3V or 5V)
2. **DHT22_CHECKSUM_ERROR**
- Check for electromagnetic interference
- Verify sensor is not defective
- Add pull-up resistor (4.7kΩ) to data line
- Reduce cable length
3. **Sensor not detected**
- Verify power connections (VCC, GND)
- Check data line connection
- Test with `dht22_test_connection()`
### Hardware Setup
```
DHT22 Sensor ESP32
----------- -----
VCC ---- 3.3V (or 5V)
GND ---- GND
DATA ---- GPIO_NUM_X
```
**Note:** A 4.7kΩ pull-up resistor between DATA and VCC may be required for reliable operation, especially with long cables.
### Reading Frequency
- Minimum reading interval: **2 seconds**
- Recommended interval: **2-5 seconds**
- Maximum frequency: **0.5 Hz**
**Important:** DHT22 sensors cannot be read faster than once every 2 seconds due to internal processing time.
## 🧪 Testing
### Connection Test
```c
void test_sensor_connection(void) {
if (dht22_init(GPIO_NUM_4) == ESP_OK) {
if (dht22_test_connection()) {
printf("✅ DHT22 sensor detected\n");
} else {
printf("❌ DHT22 sensor not responding\n");
}
} else {
printf("❌ Failed to initialize DHT22\n");
}
}
```
### Comprehensive Test
```c
void comprehensive_test(void) {
printf("Starting DHT22 comprehensive test...\n");
// Initialize with default settings
if (dht22_init(GPIO_NUM_4) != ESP_OK) {
printf("❌ Initialization failed\n");
return;
}
// Test connection
if (!dht22_test_connection()) {
printf("❌ Connection test failed\n");
return;
}
printf("✅ Connection test passed\n");
// Perform multiple readings
int success_count = 0;
int total_readings = 10;
for (int i = 0; i < total_readings; i++) {
float temp, hum;
dht22_result_t result = dht22_read(&temp, &hum);
if (result == DHT22_OK) {
success_count++;
printf("Reading %d: %.1f°C, %.1f%%\n", i+1, temp, hum);
} else {
printf("Reading %d failed: %s\n", i+1, dht22_get_error_string(result));
}
vTaskDelay(pdMS_TO_TICKS(2500)); // 2.5 second interval
}
printf("Test complete: %d/%d successful readings (%.1f%%)\n",
success_count, total_readings, (float)success_count/total_readings*100);
}
```
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🤝 Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 📈 Version History
See [CHANGELOG.md](CHANGELOG.md) for version history and changes.
## 🆘 Support
- Create an [issue](../../issues) for bug reports or feature requests
- Check existing issues for known problems and solutions
## ⚡ Performance Notes
- **Memory usage**: ~200 bytes RAM
- **CPU impact**: Minimal, bit-banging operations are fast
- **Thread safety**: Functions are thread-safe
- **Power consumption**: Sensor active only during readings (~2mA for 2ms)
- **Platforms**: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6
- **Tested**: ESP32-C6 DevKit
- **License**: MIT