mhz19b - Driver for MH-Z19B NDIR CO₂ sensor connected to UART
- group mhz19b
ESP-IDF driver for MH-Z19B NDIR CO2 sensor connected to UART.
Inspired from https://github.com/Erriez/ErriezMHZ19B
Copyright (c) 2020 Erriez https://github.com/Erriez Copyright (c) 2021 David Douard david.douard@sdfa3.org
BSD Licensed as described in the file LICENSE
Defines
-
MHZ19B_WARMING_UP_TIME_MS
3 minutes warming-up time after power-on before valid data returned
-
MHZ19B_WARMING_UP_TIME_US
-
MHZ19B_READ_INTERVAL_MS
Minimum response time between CO2 reads (EXPERIMENTALLY DEFINED)
-
MHZ19B_SERIAL_RX_BYTES
Fixed 9 Bytes response.
-
MHZ19B_SERIAL_BUF_LEN
128 is the minimal value the UART driver will accept (at least on esp32)
-
MHZ19B_SERIAL_RX_TIMEOUT_MS
Response timeout between 15..120 ms at 9600 baud works reliable for all commands.
-
MHZ19B_CMD_SET_AUTO_CAL
set auto calibration on/off
-
MHZ19B_CMD_READ_CO2
read CO2 concentration
-
MHZ19B_CMD_CAL_ZERO_POINT
calibrate zero point at 400ppm
-
MHZ19B_CMD_CAL_SPAN_PIONT
calibrate span point (NOT IMPLEMENTED)
-
MHZ19B_CMD_SET_RANGE
set detection range
-
MHZ19B_CMD_GET_AUTO_CAL
get auto calibration status (NOT DOCUMENTED)
-
MHZ19B_CMD_GET_RANGE
get range detection (NOT DOCUMENTED)
-
MHZ19B_CMD_GET_VERSION
get firmware version (NOT DOCUMENTED)
Enums
Functions
-
esp_err_t mhz19b_init(mhz19b_dev_t *dev, uart_port_t uart_port, gpio_num_t tx_gpio, gpio_num_t rx_gpio)
Initialize device descriptor.
- Parameters:
dev – Pointer to the sensor device data structure
uart_port – UART poert number
tx_gpio – GPIO pin number for TX
rx_gpio – GPIO pin number for RX
- Returns:
ESP_OK on success
-
esp_err_t mhz19b_free(mhz19b_dev_t *dev)
Free device descriptor.
- Parameters:
dev – Pointer to the sensor device data structure
- Returns:
ESP_OK on success
-
bool mhz19b_detect(mhz19b_dev_t *dev)
Detect sensor by checking range response.
- Parameters:
dev – Pointer to the sensor device data structure
- Returns:
true if sensor is detected
-
bool mhz19b_is_warming_up(mhz19b_dev_t *dev, bool smart_warming_up)
Check if sensor is warming up.
- Parameters:
dev – Pointer to the sensor device data structure
smart_warming_up – Smart check
- Returns:
true if sensor is warming up
-
bool mhz19b_is_ready(mhz19b_dev_t *dev)
Check minimum interval between CO2 reads.
Not described in the datasheet, but it is the same frequency as the built-in LED blink.
- Parameters:
dev – Pointer to the sensor device data structure
- Returns:
true if ready to call mhz19b_read_co2()
-
esp_err_t mhz19b_read_co2(mhz19b_dev_t *dev, int16_t *co2)
Read CO2 from sensor.
- Parameters:
dev – Pointer to the sensor device data structure
co2 – [out] CO2 level
< 0: MH-Z19B response error codes.
0..399 ppm: Incorrect values. Minimum value starts at 400ppm outdoor fresh air.
400..1000 ppm: Concentrations typical of occupied indoor spaces with good air exchange.
1000..2000 ppm: Complaints of drowsiness and poor air quality. Ventilation is required.
2000..5000 ppm: Headaches, sleepiness and stagnant, stale, stuffy air. Poor concentration, loss of attention, increased heart rate and slight nausea may also be present.
Higher values are extremely dangerous and cannot be measured.
- Returns:
ESP_OK on success
-
esp_err_t mhz19b_get_version(mhz19b_dev_t *dev, char *version)
Get firmware version (NOT DOCUMENTED)
This is an undocumented command, but most sensors returns ASCII “0430 or “0443”.
- Parameters:
dev – Pointer to the sensor device data structure
version – [out]
Returned character pointer to version (must be at least 5 Bytes)
Only valid when return is set to ESP_OK.
- Returns:
ESP_OK on success
-
esp_err_t mhz19b_set_range(mhz19b_dev_t *dev, mhz19b_range_t range)
Set CO2 range.
- Parameters:
dev – Pointer to the sensor device data structure
range – Range of the sensor (2000 or 5000, in ppm)
- Returns:
ESP_OK on success
-
esp_err_t mhz19b_get_range(mhz19b_dev_t *dev, uint16_t *range)
Get CO2 range in PPM (NOT DOCUMENTED)
This function verifies valid read ranges of 2000 or 5000 ppm.
Note: Other ranges may be returned, but are undocumented and marked as invalid.
- Parameters:
dev – Pointer to the sensor device data structure
range – Current value of the range of the sensor (output)
- Returns:
ESP_OK on success
-
esp_err_t mhz19b_set_auto_calibration(mhz19b_dev_t *dev, bool calibration_on)
Enable or disable automatic calibration.
- Parameters:
dev – Pointer to the sensor device data structure
calibration_on –
true: Automatic calibration on.
false: Automatic calibration off.
- Returns:
ESP_OK on success
-
esp_err_t mhz19b_get_auto_calibration(mhz19b_dev_t *dev, bool *calibration_on)
Get status of automatic calibration (NOT DOCUMENTED)
- Parameters:
dev – Pointer to the sensor device data structure
calibration_on – [out] Automatic calibration status
- Returns:
ESP_OK on success
-
esp_err_t mhz19b_start_calibration(mhz19b_dev_t *dev)
Start Zero Point Calibration manually at 400ppm.
The sensor must be powered-up for at least 20 minutes in fresh air at 400ppm room temperature. Then call this function once to execute self calibration.
Recommended to use this function when auto calibration is off.
- Parameters:
dev – Pointer to the sensor device data structure
- Returns:
ESP_OK on success
-
esp_err_t mhz19b_send_command(mhz19b_dev_t *dev, uint8_t cmd, uint8_t b3, uint8_t b4, uint8_t b5, uint8_t b6, uint8_t b7)
Send serial command to sensor and read response.
Send command to sensor and read response, protected with a receive timeout.
Result is available in the device descriptor buffer.
- Parameters:
dev – Pointer to the sensor device data structure
cmd – Command Byte
b3 – Byte 3 (default 0)
b4 – Byte 4 (default 0)
b5 – Byte 5 (default 0)
b6 – Byte 6 (default 0)
b7 – Byte 7 (default 0)
-
uint8_t mhz19b_calc_crc(uint8_t *data)
Calculate CRC on 8 data Bytes buffer.
- Parameters:
data – Buffer pointer to calculate CRC.
- Returns:
Calculated 8-bit CRC.
-
struct mhz19b_dev_t
- #include <mhz19b.h>
MHZ19B sensor device data structure.
-
MHZ19B_WARMING_UP_TIME_MS