118 lines
4.2 KiB
ReStructuredText
118 lines
4.2 KiB
ReStructuredText
CCS811 eCO_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 eCO_2 and volatile organic compound sensors
|
|
(`Adafruit`_) with ESPHome.
|
|
|
|
.. note::
|
|
|
|
Most CCS811 modules require the WAK pin to be pulled low to wake up the sensor, as outlined in the data sheets.
|
|
Outside low-power scenarios, connecting WAK to ground is the recommended configuration. For low power installations,
|
|
pulling WAK low should happen in software prior to taking the measures.
|
|
|
|
.. 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 component 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`
|