Sensing library

Sensei Smart Home monitoring tools. Currently aimed at air quality monitoring.

Sensei samples connected sensors, sending readings over MQTT to a connector place (MQTT server part not included). Home Assistant and Grafana can be setup to collect sensor readings.

Supports:

• Python (RPi / busio)
• Micropython (ESP32)

with the same code.

Supported sensors, connected over I²C bus:

• SGP30 TVOC & eCO2 sensor (ethanol, H₂). CO2 is not measured directly, estimated based on Ethanol/H₂. Now end of life. Successor: SGP4x.
• SGP41 TVOC & NOx sensor (2 pixel-arrays, MOx, ethanol / NO₂), post-processing via Sensirion Gas Index Algorithm
• CCS811 Metal oxide (MOX) gas sensor to detect a wide range of Volatile Organic Compounds (VOCs). Produces: VOC (eTVOC) and equivalent CO2 (eCO2) values, where the main cause of VOCs is from humans.
• SCD41 High CO₂ accuracy with extended measurement range and low power modes. Measures CO₂ directly.
• ATHx0 Temperature and humidity sensor
• HDC1080 Temperature and humidity sensor, often paired with CCS811 chip on a single board
• SPS30 laser-based particular matter detector, PM1, PM2.5, PM4, PM10. Supports both I²C and UART.
• ZH03b laser-based particular matter detector, PM1, PM2.5, PM4, PM10 (SPS30 seems to be better). Support UART only.

Practical use

Config file config.yaml defines basic sensei settings, such as connected sensors.

Raspberry PI

For installation on Raspberry PI, this library can be installed with pip. Python 3.10 is recommended.

Directory isense_py demonstrates use of this library with RPi. Create custom config.yaml from config-example.yaml. Calling install.sh installs the library as a service.

ESP32

Sensei works also on ESP32 running Micropython. It can be copied to the board using VSCode and PyMakr.

Copy ph4_sense as-is to ESP32, then copy instance setting directory, such as isense_esp32_test to the root, i.e., ./main.py is present on ESP32.

ESP32 config is json (yaml not supported). ESP32 supports connecting to the WiFi, you have to thus specify SSID and Passphrase to connect to.

Project structure

• ph4_sense base library package, compatible with both Micropython and Python 3.10+.
  • ph4_sense/sensors various sensors basic controllers.
  • ph4_sense/support support classes used in sensor controllers and other parts of the project (e.g, i2c helpers)
• ph4_sense_py Python 3.10 only compatible code. Some parts uses Adafruit code (wrappers around the Adafruit sensor controllers).

Circuitry

Pull-up resistors

I²C bus requires pull-up resistors to operate correctly. By default, pull-up pulls SDA and SCL lines to logical 1, sensors then pull line to the ground to change state to 0.

If the pull-up resistor is too high, signal recovers from 0 to 1 too slowly. If resistor is too low, current flowing through the sensor when transmitting 0 may be too high and either damage the sensor or cause unreliable communication.

Almost all sensor boards available on the market usually already contain 10k pull-up resistors. The problem is when connecting more sensors to a single I²C bus. Resistors form a parallel resistor circuit, lowering overall resistance. I.e., the whole setup stops working after reaching number of sensors.

$$ R_{\text{total}} = \frac{R}{N} $$

i.e., when 5 sensor boards are connected on the same bus, pull-up resistance is 2k, reaching borderline values. To support more sensors, it is needed to remove external pull-ups from the sensor boards.

In case of SCD41 it is easy as pull-up is a single resistor. In others, disconnecting pull-ups is more tricky as pull-up is part of a single SMD component containing 4 independent resistors.

Gently reminder on a formula for parallel resistors:

$$ \frac{1}{R_{\text{total}}} = \frac{1}{R_1} + \frac{1}{R_2} + \frac{1}{R_3} + \ldots + \frac{1}{R_n} $$

Capacitance

I²C has capacitance limit 400 pF. With higher values, speed of voltage transition degrades, causing bus to be unreliable.

For sensing purpose it is recommended to use lower bus speeds, e.g., 100 kHz. Lower the frequency, higher the tolerance to the capacitance.

Capacitance is inherent to the circuit (parasitical capacitance), each new board and sensor increases the capacitance (signal traces length, PCB material, chip capacitance). Higher capacitance can be into some degree compensated with lower pull-up. But after some limit, bus reaches maximum capacity and no new sensors can be added.

Bus segmentation

If more sensors needs to be connected to a single bus, or it is needed to combine sensors operating on various bus speeds or voltages, the following can be used:

• Bus repeaters PCA9515A. While retaining all the operating modes and features of the I²C-bus system, it permits extension of the I²C-bus by buffering both the data (SDA) and the clock (SCL) lines, thus enabling two buses of 400 pF.
• Bus multiplexers TCA9548A. More powerful than bus extender. Also enables to connect multiple devices with the same address.
• Level shifters: When adding another sensors operating on different voltage levels, a level shifter may be needed for 3.3V and 5V sensors to operate on the same I²C bus.

UdpLogger

Sensei supports simple UDP logging to a remote server to make debugging easier, e.g., when running on ESP32.

Start UDP logger on the server side:

while true; do nc -ul 9998; done

Alternative python installation

sudo apt update && sudo apt upgrade -y
sudo apt install build-essential zlib1g-dev libncurses5-dev libgdbm-dev libnss3-dev libssl-dev libreadline-dev libffi-dev libsqlite3-dev wget libbz2-dev
wget https://www.python.org/ftp/python/3.10.12/Python-3.10.12.tgz
tar -xf Python-3.10.*.tgz
cd Python-3.10.*/
./configure --prefix=/usr/local --enable-optimizations --enable-shared LDFLAGS="-Wl,-rpath /usr/local/lib"
make -j $(nproc)
sudo make altinstall

python3.10 --version

Dependencies

Repository has directly included Sensirion gas index algorithm for ease of deployment to ESP32: https://github.com/ph4r05/ph4-sensirion-gas-index-algorithm-py

Development

Install pre-commit hooks defined by .pre-commit-config.yaml

pip3 install -U pre-commit
pre-commit install

Auto fix

pre-commit run --all-files

Plugin version update

pre-commit autoupdate