ESP-IDF driver for AGS10 Total Volatile Organic Compounds (TVOC) sensor

Defines

AGS10_I2CADDR_DEFAULT: AGS10 default I2C address.

AGS10_TVOCSTAT_REG: Status and TVOC reading.

AGS10_VERSION_REG: Firmware version.

AGS10_GASRES_REG: Raw gas resistance.

AGS10_SETADDR_REG: Change I2C address.

AGS10_CRC8_INIT: CRC8 init value.

AGS10_CRC8_POLYNOMIAL: CRC8 polynomial.

I2C_FREQ_HZ: Fixed I2C frequency for AGS10.

Functions

esp_err_t ags10_init_desc(i2c_dev_t *dev, i2c_port_t port, uint8_t addr, gpio_num_t sda_gpio, gpio_num_t scl_gpio)

Initialize the AGS10 sensor descriptor.

This function initializes the I2C device descriptor for the AGS10 sensor. It configures the I2C port, address, and GPIO pins for SDA and SCL.

#include <ags10.h>
#include <i2cdev.h>
#include <esp_log.h>

#define TAG "ags10_example"
#define I2C_PORT I2C_NUM_0
#define SDA_GPIO GPIO_NUM_21
#define SCL_GPIO GPIO_NUM_22

void app_main(void)
{
    i2c_dev_t dev;
    ESP_ERROR_CHECK(i2cdev_init());

    esp_err_t err = ags10_init_desc(&dev, I2C_PORT, AGS10_I2CADDR_DEFAULT, SDA_GPIO, SCL_GPIO);
    if (err != ESP_OK) {
        ESP_LOGE(TAG, "Failed to init AGS10: %s", esp_err_to_name(err));
        return;
    }

    uint32_t tvoc;
    err = ags10_read_tvoc(&dev, &tvoc);
    if (err == ESP_OK) {
        ESP_LOGI(TAG, "TVOC: %lu ppb", tvoc);
    }

    ags10_free_desc(&dev);
}

Parameters:

dev – [out] Pointer to the I2C device descriptor
port – [in] I2C port number
addr – [in] I2C address of the sensor
sda_gpio – [in] GPIO number for SDA
scl_gpio – [in] GPIO number for SCL

Returns:

ESP_OK on success

esp_err_t ags10_free_desc(i2c_dev_t *dev)

Free the AGS10 sensor descriptor.

This function cleans up the I2C device descriptor resources.

Parameters:: dev – [in] Pointer to the I2C device descriptor
Returns:: ESP_OK on success

esp_err_t ags10_read_tvoc(i2c_dev_t *dev, uint32_t *tvoc)

Read TVOC value from the sensor.

This function reads the Total Volatile Organic Compounds (TVOC) value from the AGS10 sensor. The value is returned in parts per billion (ppb).

Note

The sensor requires some warm-up time after power-on for accurate readings. Typical warm-up time is around 10-60 seconds.

Parameters:

dev – [in] Pointer to the I2C device descriptor
tvoc – [out] Pointer to store the TVOC value in ppb

Returns:

ESP_OK: Success
ESP_ERR_INVALID_ARG: Invalid argument
ESP_FAIL: Communication failure

esp_err_t ags10_read_version(i2c_dev_t *dev, uint8_t *version)

Read firmware version from the sensor.

This function reads the firmware version of the AGS10 sensor.

Parameters:

dev – [in] Pointer to the I2C device descriptor
version – [out] Pointer to store the firmware version

Returns:

ESP_OK: Success
ESP_ERR_INVALID_ARG: Invalid argument
ESP_FAIL: Communication failure

esp_err_t ags10_read_resistance(i2c_dev_t *dev, uint32_t *resistance)

Read resistance value from the sensor.

This function reads the raw gas resistance value from the AGS10 sensor. This value can be used for advanced calibration or diagnostics.

Parameters:

dev – [in] Pointer to the I2C device descriptor
resistance – [out] Pointer to store the resistance value

Returns:

ESP_OK: Success
ESP_ERR_INVALID_ARG: Invalid argument
ESP_FAIL: Communication failure

esp_err_t ags10_set_i2c_address(i2c_dev_t *dev, uint8_t new_address)

Set new I2C address for the sensor.

This function changes the I2C address of the AGS10 sensor. The new address will be persistent after power cycling.

Warning

Use this function with caution. Make sure no other I2C devices use the new address to avoid conflicts.

Parameters:

dev – [inout] Pointer to the I2C device descriptor (address will be updated)
new_address – [in] New I2C address (7-bit, range: 0x08-0x77)

Returns:

ESP_OK: Success
ESP_ERR_INVALID_ARG: Invalid argument
ESP_FAIL: Communication failure

esp_err_t ags10_set_zero_point_with_factory_defaults(i2c_dev_t *dev)

Set zero-point calibration with factory defaults.

This function resets the zero-point calibration to factory default values. This is useful when the sensor readings drift over time.

Parameters:

dev – [in] Pointer to the I2C device descriptor

Returns:

ESP_OK: Success
ESP_ERR_INVALID_ARG: Invalid argument
ESP_FAIL: Communication failure

esp_err_t ags10_set_zero_point_with_current_resistance(i2c_dev_t *dev)

Set zero-point calibration with current resistance.

This function sets the current resistance reading as the zero point. Use this function in clean air conditions for calibration.

Parameters:

dev – [in] Pointer to the I2C device descriptor

Returns:

ESP_OK: Success
ESP_ERR_INVALID_ARG: Invalid argument
ESP_FAIL: Communication failure

esp_err_t ags10_set_zero_point_with(i2c_dev_t *dev, uint16_t value)

Set zero-point calibration with a specific value.

This function sets the zero-point calibration to a specific value. This is for advanced users who know the exact calibration value.

Parameters:

dev – [in] Pointer to the I2C device descriptor
value – [in] Calibration value (0x0000 = current resistance, 0xFFFF = factory defaults)

Returns:

ESP_OK: Success
ESP_ERR_INVALID_ARG: Invalid argument
ESP_FAIL: Communication failure