deuxyeux/sensor-exporter
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions
A Prometheus exporter for ENS160 air quality and EZO-HUM humidity/temperature sensors over I2C, with fault detection and automatic recovery.
12 commits 1 branch 1 tag 63 KiB
  • Python 79%
  • Shell 21%
Find a file
Exact
Nickie Deuxyeux 97059057cd Fix ENS160 OPMODE init sequence, mask AQI byte, add Rs3 and MISR checksum 
RESET -> IDLE -> STANDARD is required before entering measurement mode
per the datasheet and sciosense/ens16x reference implementations; jumping
straight to STANDARD (as before) left the gas-sensing algorithm stuck,
which is the likely cause of AQI/TVOC/eCO2 readings pegging at their max
(clipping). Confirmed on sofia1: values dropped out of the pegged range
immediately after switching to the correct sequence.

Also, cross-checking against sciosense/ens16x-embedded and ens16x-arduino:
- DATA_AQI only uses bits[2:0] for the UBA index; mask off the reserved bits
- Add ens160_rs3_ohms: raw MOX element resistance read directly from
  GPR_READ, bypassing the AQI/TVOC/eCO2 algorithm entirely, to help tell
  apart a real gas event from an algorithm artifact
- Add MISR checksum validation: replicate the device's rolling 8-bit
  signature over every register byte we read and compare it against
  DATA_MISR each cycle, to catch I2C data corruption in transit

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-24 14:34:19 +03:00
.gitignore Initial commit: ENS160 + EZO-HUM Prometheus exporter 2026-05-14 12:37:45 +03:00
install.sh Download sensor-exporter.py automatically if not found locally 2026-05-28 16:16:50 +03:00
README.md README: show explicit wget download for both files in quick-start 2026-05-28 16:17:41 +03:00
requirements.txt Add requirements.txt 2026-05-14 12:38:27 +03:00
sensor-exporter.py Fix ENS160 OPMODE init sequence, mask AQI byte, add Rs3 and MISR checksum 2026-09-24 14:34:19 +03:00

README.md

sensor-exporter

Prometheus exporter for the ENS160 (AQI, TVOC, eCO2) and EZO-HUM (humidity, temperature) sensors over I2C, targeting Armbian SBCs.

Metrics are exposed on :8000/metrics.

Quick-start

No git required. The installer downloads everything it needs automatically.

curl

sudo bash <(curl -fsSL https://git.aetherlab.org/deuxyeux/sensor-exporter/raw/branch/main/install.sh)

wget

wget -q https://git.aetherlab.org/deuxyeux/sensor-exporter/raw/branch/main/install.sh
wget -q https://git.aetherlab.org/deuxyeux/sensor-exporter/raw/branch/main/sensor-exporter.py
sudo bash install.sh

The installer will:

  1. Check and install missing Python dependencies (python3-smbus2, python3-prometheus-client) via apt
  2. Add the i2c0 overlay to /boot/armbianEnv.txt if not already present (reboot required after first install)
  3. Download and deploy the exporter to /opt/sensor-exporter/
  4. Install, enable, and start the sensor-exporter systemd service

Usage

# Check service status
systemctl status sensor-exporter

# Follow logs
journalctl -u sensor-exporter -f

# View metrics
curl http://localhost:8000/metrics

Metrics

Metric Description
ezo_humidity_percent Relative humidity (%)
ezo_temperature_celsius Temperature (°C)
ens160_aqi Air Quality Index (1–5)
ens160_tvoc_ppb TVOC (ppb)
ens160_eco2_ppm eCO2 (ppm)
ens160_tvoc_ug_m3 TVOC (µg/m³, estimated)
ens160_sensor_faulted 1 when ENS160 is faulted
ezo_sensor_ok 1 when last EZO-HUM read succeeded