doc: updated readme

README.md

@@ -2,13 +2,20 @@
 
 ## Features
 
-1. I2C interface with configurable frequency up to 400 kHz (Fast Mode).
+1. Measurement of ambient light intensity in lux.
-2. Support for two I2C addresses: 0x23 (ADDR low) and 0x5C (ADDR high).
+2. I2C interface with frequency up to 400 kHz (Fast Mode).
-3. One-time H-resolution measurement with 1 lux step.
+3. Support for two I2C addresses: 0x23 (ADDR low) and 0x5C (ADDR high).
-4. Built-in error statistics tracking and reset for diagnostics.
+4. One-time H-resolution measurement with 1 lux step.
 5. Automatic lux conversion from raw sensor data.
 6. Sensor presence verification during initialization via I2C probe.
-7. Support multiple sensors on one device with [zh_pca9548a](https://github.com/aZholtikov/zh_pca9548a).
+7. Built-in I2C error statistics tracking and reset for diagnostics.
+
+## Attention
+
+1. The I2C bus must be initialized before the component.
+2. Only one-time H-resolution measurement mode is supported.
+3. Each read is a blocking call of approximately 180 ms.
+4. Error statistics are global for all sensor instances on the device.
 
 ## Using
 
@@ -16,7 +23,7 @@ In an existing project, run the following command to install the component:
 
 ```bash
 cd ../your_project/components
-git clone https://github.com/aZholtikov/zh_bh1750.git
+git clone https://github.com/aZholtikov/zh_bh1750
 ```
 
 In the application, add the component:
@@ -25,7 +32,9 @@ In the application, add the component:
 #include "zh_bh1750.h"
 ```
 
-## Example
+## Examples
+
+### Basic Read Example
 
 ```c
 #include "zh_bh1750.h"
@@ -45,19 +54,150 @@ void app_main(void)
         .glitch_ignore_cnt = 7,
         .flags.enable_internal_pullup = true,
     };
-    i2c_master_bus_handle_t i2c_bus_handle;
+    i2c_master_bus_handle_t i2c_bus_handle = NULL;
-    i2c_new_master_bus(&i2c_bus_config, &i2c_bus_handle);
+    esp_err_t ret = i2c_new_master_bus(&i2c_bus_config, &i2c_bus_handle);
+    if (ret != ESP_OK)
+    {
+        printf("I2C bus initialization error\n");
+        return;
+    }
     zh_bh1750_init_config_t config = ZH_BH1750_INIT_CONFIG_DEFAULT();
     config.i2c_handle = i2c_bus_handle;
-    zh_bh1750_init(&config, &bh1750_handle);
+    ret = zh_bh1750_init(&config, &bh1750_handle);
+    if (ret != ESP_OK)
+    {
+        printf("BH1750 initialization error: %s\n", esp_err_to_name(ret));
+        return;
+    }
     float lux = 0.0;
     for (;;)
     {
-        zh_bh1750_read(&bh1750_handle, &lux);
+        ret = zh_bh1750_read(&bh1750_handle, &lux);
-        printf("Lux %0.2f\n", lux);
+        if (ret == ESP_OK)
-        const zh_bh1750_stats_t *stats = zh_bh1750_get_stats();
+        {
-        printf("Number of i2c driver error: %ld.\n", stats->i2c_driver_error);
+            printf("Lux: %0.2f\n", lux);
+        }
+        else
+        {
+            printf("Read error: %s\n", esp_err_to_name(ret));
+        }
         vTaskDelay(5000 / portTICK_PERIOD_MS);
     }
 }
 ```
+
+---
+
+### Alternative Address Example
+
+```c
+#include "zh_bh1750.h"
+
+#define I2C_PORT (I2C_NUM_MAX - 1)
+
+zh_bh1750_handle_t *bh1750_handle = NULL;
+
+void app_main(void)
+{
+    esp_log_level_set("zh_bh1750", ESP_LOG_ERROR);
+    i2c_master_bus_config_t i2c_bus_config = {
+        .clk_source = I2C_CLK_SRC_DEFAULT,
+        .i2c_port = I2C_PORT,
+        .scl_io_num = GPIO_NUM_22,
+        .sda_io_num = GPIO_NUM_21,
+        .glitch_ignore_cnt = 7,
+        .flags.enable_internal_pullup = true,
+    };
+    i2c_master_bus_handle_t i2c_bus_handle = NULL;
+    esp_err_t ret = i2c_new_master_bus(&i2c_bus_config, &i2c_bus_handle);
+    if (ret != ESP_OK)
+    {
+        printf("I2C bus initialization error\n");
+        return;
+    }
+    zh_bh1750_init_config_t config = ZH_BH1750_INIT_CONFIG_DEFAULT();
+    config.i2c_handle = i2c_bus_handle;
+    config.i2c_address = 0x5C;
+    ret = zh_bh1750_init(&config, &bh1750_handle);
+    if (ret != ESP_OK)
+    {
+        printf("BH1750 initialization error: %s\n", esp_err_to_name(ret));
+        return;
+    }
+    float lux = 0.0;
+    ret = zh_bh1750_read(&bh1750_handle, &lux);
+    if (ret == ESP_OK)
+    {
+        printf("Lux: %0.2f\n", lux);
+    }
+    else
+    {
+        printf("Read error: %s\n", esp_err_to_name(ret));
+    }
+    ret = zh_bh1750_deinit(&bh1750_handle);
+    if (ret != ESP_OK)
+    {
+        printf("Deinitialization error: %s\n", esp_err_to_name(ret));
+    }
+}
+```
+
+---
+
+### Error Statistics Example
+
+```c
+#include "zh_bh1750.h"
+
+#define I2C_PORT (I2C_NUM_MAX - 1)
+
+zh_bh1750_handle_t *bh1750_handle = NULL;
+
+void app_main(void)
+{
+    esp_log_level_set("zh_bh1750", ESP_LOG_ERROR);
+    i2c_master_bus_config_t i2c_bus_config = {
+        .clk_source = I2C_CLK_SRC_DEFAULT,
+        .i2c_port = I2C_PORT,
+        .scl_io_num = GPIO_NUM_22,
+        .sda_io_num = GPIO_NUM_21,
+        .glitch_ignore_cnt = 7,
+        .flags.enable_internal_pullup = true,
+    };
+    i2c_master_bus_handle_t i2c_bus_handle = NULL;
+    esp_err_t ret = i2c_new_master_bus(&i2c_bus_config, &i2c_bus_handle);
+    if (ret != ESP_OK)
+    {
+        printf("I2C bus initialization error\n");
+        return;
+    }
+    zh_bh1750_init_config_t config = ZH_BH1750_INIT_CONFIG_DEFAULT();
+    config.i2c_handle = i2c_bus_handle;
+    ret = zh_bh1750_init(&config, &bh1750_handle);
+    if (ret != ESP_OK)
+    {
+        printf("BH1750 initialization error: %s\n", esp_err_to_name(ret));
+        return;
+    }
+    float lux = 0.0;
+    for (int i = 0; i < 10; i++)
+    {
+        ret = zh_bh1750_read(&bh1750_handle, &lux);
+        if (ret == ESP_OK)
+        {
+            printf("Lux: %0.2f\n", lux);
+        }
+        else
+        {
+            printf("Read error: %s\n", esp_err_to_name(ret));
+        }
+        const zh_bh1750_stats_t *stats = zh_bh1750_get_stats();
+        printf("Number of I2C driver errors: %lu\n", (unsigned long)stats->i2c_driver_error);
+        vTaskDelay(1000 / portTICK_PERIOD_MS);
+    }
+    zh_bh1750_reset_stats();
+    const zh_bh1750_stats_t *stats = zh_bh1750_get_stats();
+    printf("Number of I2C driver errors after reset: %lu\n", (unsigned long)stats->i2c_driver_error);
+    zh_bh1750_deinit(&bh1750_handle);
+}
+```