Grove - Air Quality Sensor v1.3

---

This sensor is designed for comprehensive monitor over indoor air condition. It's responsive to a wide scope of harmful gases, as carbon monoxide, alcohol, acetone, thinner, formaldehyde and so on. Due to the measuring mechanism, this sensor can't output specific data to describe target gases' concentrations quantitatively. But it's still competent enough to be used in applications that require only qualitative results, like auto refresher sprayers and auto air cycling systems.

tip

We've released the [Seeed Gas Sensor Selection Guide](https://wiki.seeedstudio.com/Seeed_Gas_Sensor_Selection_Guide/), it will help you choose the gas sensor that best suits your needs.

Version

Product Version	Changes	Released Date
Grove - Air Quality Sensor v1.3	Initial	May 2016

Features

• Responsive to a wide scope of target gases
• Cost efficient
• Durable
• Compatible with 5V and 3.3V

caution

1. Requires relatively clean air as an initial condition.
2. Long time exposure to highly polluted air can significantly weaken its sensitivity.
3. Coffre-fort et armoire forte:

Platforms Supported

Arduino	Raspberry Pi	ESP-IDF

caution

The platforms mentioned above as supported is/are an indication of the module's software or theoritical compatibility. We only provide software library or code examples for Arduino platform in most cases. It is not possible to provide software library / demo code for all possible MCU platforms. Hence, users have to write their own software library.

Getting Started

note

If this is the first time you work with Arduino, we firmly recommend you to see [Getting Started with Arduino](https://wiki.seeedstudio.com/Getting_Started_with_Arduino/) before the start.

Play With Arduino

Demonstration

As described in Introduction, this sensor performs better in providing qualitative results over a wide scope of target gases. In this demo, we will define 4 statuses for reference in the '.cpp' file. They are:

• a. air fresh -- indicating a good air condition
• b. low pollution -- indicating a rather low concentration of target gases exist.
• c. high pollution(without "Force signal active" message printed on serial monitor) -- you should be aware of the pollution level and consider if some measures could be taken.
• d. high pollution(with "Force signal active" message printed on serial monitor) -- instant measures should be taken to improve the air quality.

We encapsulated the decision structure in a '.cpp' file. You can find information there on how to modify the thresholds.

Let's try it out!

Hardware

• Step 1. Prepare the below stuffs:

Seeeduino V4.2	Base Shield	Grove - Air Quality Sensor
Get One Now	Get One Now	Get One Now

• Step 2. Connect Grove - Air Quality Sensor to port A0 of Grove-Base Shield.
• Step 3. Plug Grove - Base Shield into Seeeduino.
• Step 4. Connect Seeeduino to PC via a USB cable.

note

If we don't have Grove Base Shield, We also can directly connect Grove - Air Quality Sensor to Seeeduino as below.

Seeeduino	Grove - Air Quality Sensor
5V	Red
GND	Black
Not Conencted	White
A0	Yellow

Software

• Step 1. Download the AirQuality_Sensor Library.
• Step 2. Refer How to install library to install library for Arduino.
• Step 3. Copy the code into Arduino IDE and upload. If you do not know how to upload the code, please check how to upload code.

/*
    Grove_Air_Quality_Sensor.ino
    Demo for Grove - Air Quality Sensor.

    Copyright (c) 2019 seeed technology inc.
    Author    : Lets Blu
    Created Time : Jan 2019
    Modified Time:

    The MIT License (MIT)

    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    THE SOFTWARE.
*/
#include "Air_Quality_Sensor.h"

AirQualitySensor sensor(A0);

void setup(void) {
    Serial.begin(9600);
    while (!Serial);

    Serial.println("Waiting sensor to init...");
    delay(20000);

    if (sensor.init()) {
        Serial.println("Sensor ready.");
    } else {
        Serial.println("Sensor ERROR!");
    }
}

void loop(void) {
    int quality = sensor.slope();

    Serial.print("Sensor value: ");
    Serial.println(sensor.getValue());

    if (quality == AirQualitySensor::FORCE_SIGNAL) {
        Serial.println("High pollution! Force signal active.");
    } else if (quality == AirQualitySensor::HIGH_POLLUTION) {
        Serial.println("High pollution!");
    } else if (quality == AirQualitySensor::LOW_POLLUTION) {
        Serial.println("Low pollution!");
    } else if (quality == AirQualitySensor::FRESH_AIR) {
        Serial.println("Fresh air.");
    }

    delay(1000);
}

• Step 4. We will see the distance display on terminal as below.

Waiting sensor to init...
Sensor ready.
Sensor value: 48
Fresh air.
Sensor value: 51
Fresh air.
Sensor value: 49
Fresh air.
Sensor value: 48
Fresh air.
Sensor value: 48
Fresh air.
Sensor value: 48
Fresh air.

To adjust the thresholds and indicating messages, refer to the decision structure below in the .cpp file.

int AirQualitySensor::slope(void) {
    _lastVoltage = _currentVoltage;
    _currentVoltage = analogRead(_pin);

    _voltageSum += _currentVoltage;
    _volSumCount += 1;

    updateStandardVoltage();
    if (_currentVoltage - _lastVoltage > 400 || _currentVoltage > 700) {
        return AirQualitySensor::FORCE_SIGNAL;
    }
    else if ((_currentVoltage - _lastVoltage > 400 && _currentVoltage < 700)
             || _currentVoltage - _standardVoltage > 150) {
        return AirQualitySensor::HIGH_POLLUTION;
    }
    else if ((_currentVoltage - _lastVoltage > 200 && _currentVoltage < 700)
             || _currentVoltage - _standardVoltage > 50) {
        return AirQualitySensor::LOW_POLLUTION;
    }
    else {
        return AirQualitySensor::FRESH_AIR;
    }

    return -1;
}

Play with Codecraft

Hardware

Step 1. Connect a Grove - Air Quality Sensor to port A0 of a Base Shield.

Step 2. Plug the Base Shield to your Seeeduino/Arduino.

Step 3. Link Seeeduino/Arduino to your PC via an USB cable.

Software

Step 1. Open Codecraft, add Arduino support, and drag a main procedure to working area.

note

If this is your first time using Codecraft, see also [Guide for Codecraft using Arduino](https://wiki.seeedstudio.com/Guide_for_Codecraft_using_Arduino/).

Step 2. Drag blocks as picture below or open the cdc file which can be downloaded at the end of this page.

Upload the program to your Arduino/Seeeduino.

tip

When the code finishes uploaded, you will see air quality in the Serial Monitor.

Play With Raspberry Pi (With Grove Base Hat for Raspberry Pi)

Hardware

• Step 1. Things used in this project:

Raspberry Pi	Grove Base Hat for RasPi	Grove - Air Quality Sensor
Get ONE Now	Get ONE Now	Get ONE Now

• Step 2. Plug the Grove Base Hat into Raspberry Pi.
• Step 3. Connect the Grove - Air Quality Sensor to the A0 port of the Base Hat.
• Step 4. Connect the Raspberry Pi to PC through USB cable.

Software

attention

 If you are using **Raspberry Pi with Raspberrypi OS >= Bullseye**, you have to use this command line **only with Python3**.

• Step 1. Follow Setting Software to configure the development environment.
• Step 2. Download the source file by cloning the grove.py library.

cd ~
git clone https://github.com/Seeed-Studio/grove.py

• Step 3. Excute below command to run the code.

cd grove.py/grove
python3 grove_air_quality_sensor_v1_3.py 0

Following is the grove_air_quality_sensor_v1_3.py code.

import math
import sys
import time
from grove.adc import ADC


class GroveAirQualitySensor:

    def __init__(self, channel):
        self.channel = channel
        self.adc = ADC()

    @property
    def value(self):
        return self.adc.read(self.channel)

Grove = GroveAirQualitySensor


def main():
    if len(sys.argv) < 2:
        print('Usage: {} adc_channel'.format(sys.argv[0]))
        sys.exit(1)

    sensor = GroveAirQualitySensor(int(sys.argv[1]))

    print('Detecting ...') 
    while True:
        value = sensor.value        
        if value > 100:
            print("{}, High Pollution.".format(value))
        else:
            print("{}, Air Quality OK.".format(value))

        time.sleep(.1)

if __name__ == '__main__':
    main()

success

If everything goes well, you will be able to see the following result:

pi@raspberrypi:~/grove.py/grove $ python3 grove_air_quality_sensor_v1_3.py 0 
Detecting ...
138, High Pollution.
139, High Pollution.
140, High Pollution.
141, High Pollution.
139, High Pollution.
140, High Pollution.
140, High Pollution.
140, High Pollution.
139, High Pollution.
138, High Pollution.
139, High Pollution.
138, High Pollution.
138, High Pollution.
^CTraceback (most recent call last):
  File "grove_air_quality_sensor_v1_3.py", line 71, in <module>
    main()
  File "grove_air_quality_sensor_v1_3.py", line 68, in main
    time.sleep(.1)
KeyboardInterrupt

You can use this sensor to detect the air quality. Press ++ctrl+c++ to quit.

note

    You may have noticed that for the analog port, the silkscreen pin number is something like **A1, A0**, however in the command we use parameter **0** and **1**, just the same as the digital port. So please make sure you plug the module into the correct port, otherwise, there may be pin conflicts.

Play With Raspberry Pi(with GrovePi_Plus)

Hardware

• Step 1. Prepare the below stuffs:

Raspberry Pi	GrovePi_Plus	Grove - Air Quality Sensor
Get One Now	Get One Now	Get One Now

• Step 2. Plug the GrovePi_Plus into Raspberry.
• Step 3. Connect Grove-MOSFET ranger to A0 port of GrovePi_Plus.
• Step 4. Connect the Raspberry to PC through USB cable.

Software

• Step 1. Navigate to the demos' directory:

cd yourpath/GrovePi/Software/Python/

• Step 2. To see the code

nano grove_air_quality_sensor.py   # "Ctrl+x" to exit #

import time
import grovepi

# Connect the Grove Air Quality Sensor to analog port A0
# SIG,NC,VCC,GND
air_sensor = 0

grovepi.pinMode(air_sensor,"INPUT")

while True:
    try:
        # Get sensor value
        sensor_value = grovepi.analogRead(air_sensor)

        if sensor_value > 700:
            print "High pollution"
        elif sensor_value > 300:
            print "Low pollution"
        else:
            print "Air fresh"

        print "sensor_value =", sensor_value
        time.sleep(.5)

    except IOError:
        print "Error"

• Step 3. Run the demo.

sudo python grove_air_quality_sensor.py

• Step 4. We will see the output display on terminal as below.

Play With ESP-IDF

Hardware

• Step 1. Prepare the below stuffs:

Seeed Studio XIAO ESP32C3	Seeed Studio Grove Base for XIAO	Grove Air Quality Sensor v1.3
Get One Now 🖱️	Get One Now 🖱️	Get One Now 🖱️

• Step 2. Connect the Grove - Air Quality Sensor to your ESP32 board:
  • Connect the sensor's VCC to 3.3V
  • Connect the sensor's GND to GND
  • Connect the sensor's SIG to an ADC-capable GPIO pin (e.g., GPIO34)

    

Software

• Step 1. Install ESP-IDF following the official guide

• Step 2. Clone the Grove Analog Air Quality Sensor component:

cd your_project/components
git clone https://github.com/Priyanshu0901/grove_analog_aqs.git

• Step 3. Configure the component using menuconfig:

idf.py menuconfig

Navigate to "Component config → Grove Analog Air Quality Sensor" to configure:

• ADC unit number (0 for ADC1, 1 for ADC2)

• ADC channel (matching your GPIO connection)

• ADC attenuation (default: ADC_ATTEN_DB_12 for 3.3V)

• Air quality thresholds

• Power management options (optional)

• Step 4. Create a new project and use the component:

#include "grove_analog_aqs.h"

void app_main(void)
{
    // Initialize with default configuration
    grove_aqs_config_t config = GROVE_AQS_DEFAULT_CONFIG();
    esp_err_t ret = grove_aqs_init(&config);
    if (ret != ESP_OK) {
        ESP_LOGE(TAG, "Sensor initialization failed: %d", ret);
        return;
    }
    
    // Read sensor data
    grove_aqs_data_t data;
    ret = grove_aqs_read_data(&data);
    if (ret == ESP_OK) {
        ESP_LOGI(TAG, "Raw ADC value: %d", data.raw_value);
        ESP_LOGI(TAG, "Voltage: %d mV", data.voltage_mv);
        ESP_LOGI(TAG, "Air quality: %s", grove_aqs_quality_to_string(data.quality));
    }
    
    // Cleanup when done
    grove_aqs_deinit();
}

• Step 5. Build and flash the project:

idf.py build
idf.py -p /dev/ttyUSB0 flash monitor

note

Replace /dev/ttyUSB0 with your ESP32's serial port.

Expected Output

I (242) sleep_gpio: Enable automatic switching of GPIO sleep configuration
I (249) main_task: Started on CPU0
I (249) main_task: Calling app_main()
I (249) grove_aqs_example: Initializing Grove Analog Air Quality Sensor
I (259) grove_aqs_example: Using ADC Unit: 0, ADC Channel: 2
I (259) grove_aqs: Initializing with ADC Unit: 0, ADC Channel: 2
I (269) grove_aqs: ADC calibration enabled
I (269) grove_aqs: Grove Analog Air Quality Sensor initialized successfully
I (279) grove_aqs_example: Waiting for sensor to stabilize...
I (3279) grove_aqs: Air quality reading: Raw=300, Voltage=218mV, Quality=Fresh
I (3279) grove_aqs_example: Reading #1:
I (3279) grove_aqs_example:   Raw ADC value: 300
I (3279) grove_aqs_example:   Voltage: 218 mV
I (3279) grove_aqs_example:   Air quality: Fresh
I (3289) grove_aqs_example:   Advice: Air is fresh and clean!
I (4289) grove_aqs: Air quality reading: Raw=298, Voltage=216mV, Quality=Fresh
I (4289) grove_aqs_example: Reading #2:
I (4289) grove_aqs_example:   Raw ADC value: 298
I (4289) grove_aqs_example:   Voltage: 216 mV
I (4289) grove_aqs_example:   Air quality: Fresh
I (4299) grove_aqs_example:   Advice: Air is fresh and clean!
I (5299) grove_aqs: Air quality reading: Raw=286, Voltage=208mV, Quality=Fresh
I (5299) grove_aqs_example: Reading #3:
I (5299) grove_aqs_example:   Raw ADC value: 286
I (5299) grove_aqs_example:   Voltage: 208 mV
I (5299) grove_aqs_example:   Air quality: Fresh
I (5309) grove_aqs_example:   Advice: Air is fresh and clean!
I (6309) grove_aqs: Air quality reading: Raw=283, Voltage=206mV, Quality=Fresh

tip

The component provides the following features:
- Automatic ADC calibration
- Configurable air quality thresholds
- Optional GPIO power control
- Error handling and logging
- Support for both ADC1 and ADC2

Schematic Online Viewer

Resources

• [Library] AirQuality Sensor Library
• [Eagle] Grove_-_Air_quality_sensor_v1.3_sch_pcb
• [PDF] Grove_-_Air_quality_sensor_v1.3_sch
• [PDF] Air_quality_sensor_MP503_Chinese
• [PDF] Air_quality sensor_MP503_English
• [Codecraft] CDC File
• [ESP-IDF] Grove Analog Air Quality Sensor Component - ESP-IDF component for Grove Air Quality Sensor
• [ESP-IDF] ESP-IDF Programming Guide - Official ESP-IDF programming guide

Projects

SPCPM (Solar Powered City Pollution Monitor): Low maintenance, high output air pollution, sound pollution that put throughout the city without wiring.

A website to see the environment data around you:

Tech Support & Product Discussion

Upgradable to Industrial Sensors

With the SenseCAP S2110 controller and S2100 data logger, you can easily turn the Grove into a LoRaWAN® sensor. Seeed not only helps you with prototyping but also offers you the possibility to expand your project with the SenseCAP series of robust industrial sensors.

The IP66 housing, Bluetooth configuration, compatibility with the global LoRaWAN® network, built-in 19 Ah battery, and powerful support from APP make the SenseCAP S210x the best choice for industrial applications. The series includes sensors for soil moisture, air temperature and humidity, light intensity, CO2, EC, and an 8-in-1 weather station. Try the latest SenseCAP S210x for your next successful industrial project.