esphome-docs/components/sensor/ccs811.rst
2022-04-03 19:30:25 +12:00

112 lines
3.9 KiB
ReStructuredText

CCS811 CO_2 and Volatile Organic Compound Sensor
================================================
.. seo::
:description: Instructions for setting up CCS811 sensors.
:image: ccs811.jpg
The ``ccs811`` sensor platform allows you to use CCS811 CO_2 and volatile organic compound sensors
(`Adafruit`_) with ESPHome.
.. figure:: images/ccs811-full.jpg
:align: center
:width: 50.0%
CCS811 Sensor. Image by `Adafruit`_
.. _Adafruit: https://www.adafruit.com/product/3566
The communication with this sensor is done via :ref:`I²C Bus <i2c>`, so you need to have
an ``i2c:`` section in your config for this integration to work.
.. code-block:: yaml
# Example configuration entry
i2c:
sda: D0
scl: D1
sensor:
- platform: ccs811
eco2:
name: "CCS811 eCO2 Value"
tvoc:
name: "CCS811 Total Volatile Organic Compound"
address: 0x5A
update_interval: 60s
Configuration variables:
------------------------
- **eco2** (**Required**): The eCO_2 data from the sensor in parts per million (ppm).
- **name** (**Required**, string): The name for the CO_2 sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **tvoc** (**Required**): The information for the total volatile organic compound sensor in
parts per billion (ppb).
- **name** (**Required**, string): The name for the tvoc sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
sensor. Defaults to ``60s``.
- **version** (*Optional*): This sensor reports the firmware ('application') version in text, with the internal hex representation of the version number behind it, so version 1.0.0 will be reported as '1.0.0 (0x1000)'.
- **name** (**Required**, string): The name for the version sensor.
Advanced:
- **address** (*Optional*, int): The :ref:`I²C <i2c>` address of the sensor.
- **baseline** (*Optional*, int): The baseline value for the unit, for calibration
purposes. See :ref:`ccs811-calibrating` for more info.
- **temperature** (*Optional*, :ref:`config-id`): Give an external temperature sensor ID
here. This can improve the sensor's internal calculations.
- **humidity** (*Optional*, :ref:`config-id`): Give an external humidity sensor ID
here. This can improve the sensor's internal calculations.
.. _ccs811-calibrating:
Calibrating Baseline
--------------------
The CCS811 sensor will re-calibrate itself each time it is powered on. Unfortunately
that also means that if the sensor reboots at a time when the air is less clean than normal,
the values will have a constant offset and cannot be compared to the values before the last
boot.
To have consistent values, you need to specify a static **baseline** value (the calibration factor).
To do this, first let the sensor boot up with no baseline set and let the sensor calibrate
itself. After around 20-30 minutes you can then view the remote logs on the ESP. The next
time the sensor is read out, you will see a log message with something like ``baseline=0xA483``.
Now set the baseline property in your configuration file like so with the value you got
via the logs:
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: ccs811
# ...
baseline: 0xA483
The next time you upload the code, the CCS811 will be informed of this static baseline
and you will get consistent values.
Please note that after some time (a couple of months), the baseline will need to be
re-calibrated because the internal sensor has a slight value drift over time.
See Also
--------
- :ref:`sensor-filters`
- `CCS811 Application Note <https://cdn.sparkfun.com/datasheets/BreakoutBoards/CCS811_Programming_Guide.pdf>`__
- :apiref:`ccs811/ccs811.h`
- :ghedit:`Edit`