# ha-enviro-plus
[](https://github.com/JeffLuckett/ha-enviro-plus/actions)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/JeffLuckett/ha-enviro-plus/releases/latest)
**Enviro+ → Home Assistant MQTT Agent**
A lightweight Python agent for publishing Pimoroni Enviro+ sensor data (temperature, humidity, pressure, light, gas, and system metrics) to Home Assistant via MQTT with automatic discovery.
---
## 🚀 Overview
`ha-enviro-plus` turns a Raspberry Pi Zero 2 W (or any Pi running the Enviro+) into a self-contained Home Assistant satellite.
It reads data from:
- **BME280** (temperature, humidity, pressure)
- **LTR559** (ambient light)
- **Gas sensor** (oxidising, reducing, NH₃)
and publishes them to Home Assistant over MQTT using native **HA Discovery**.
Additional system telemetry is included:
- CPU temperature, load, and uptime
- Memory and disk utilisation
- Network info and hostname
- Service availability and reboot/restart controls
---
## 🧩 Features
- Plug-and-play Home Assistant discovery (no YAML setup)
- Fast, configurable polling (default 2 s)
- On-device temperature / humidity calibration offsets
- CPU temperature compensation for accurate readings (higher number lowers temp. output)
- Host metrics: uptime, CPU temp, load, RAM, disk
- MQTT availability and discovery payloads
- Home Assistant controls:
- Reboot device
- Restart service
- Shutdown
- Apply calibration offsets
- Adjust CPU temperature compensation factor
- Structured logging (rotation-friendly)
- Graceful shutdown handling (SIGTERM/SIGINT)
- Startup configuration validation
- Safe installer/uninstaller with config preservation
- Versioned installation support (`--release`, `--branch` flags)
- Designed and tested with a Raspberry Pi Zero 2 W + Enviro+ HAT. Also supports the original Enviro HAT (fewer sensors) and runs on any hardware that supports these devices and the necessary libraries. (Testers welcome!)
---
## ⚙️ Quick Install
### Recommended: Install Script (PyPI-first)
Run this command **on your Raspberry Pi**:
bash <(wget -qO- https://raw.githubusercontent.com/JeffLuckett/ha-enviro-plus/main/scripts/install.sh)
**Installation Methods:**
- **Latest stable (PyPI)**: `./install.sh` *(default)*
- **Specific version (PyPI)**: `./install.sh --release v0.1.1`
- **Development branch**: `./install.sh --branch feature-branch`
- **Test mode**: `./install.sh --test` *(validate without changes)*
- **Show installer info**: `./install.sh --version`
The installer automatically:
- **Prioritizes PyPI** for stable releases (faster, more reliable)
- **Falls back to GitHub** for development branches or specific versions
- Creates `/opt/ha-enviro-plus` and installs dependencies
- Prompts for MQTT host, username, and password
- Prompts for poll interval and temperature / humidity offsets
- Installs and starts the systemd service
### Alternative: Direct PyPI Install
For advanced users who prefer manual installation:
pip install ha-enviro-plus
Then manually configure and start the service (see [Manual Setup](#manual-setup)).
Home Assistant should auto-discover the sensors within a few seconds.
---
## 🔧 Configuration
Configuration lives at:
/etc/default/ha-enviro-plus
Edit values safely, then restart the service:
sudo systemctl restart ha-enviro-plus
**Example config:**
MQTT_HOST=homeassistant.local
MQTT_PORT=1883
MQTT_USER=enviro
MQTT_PASS=<use_your_own>
MQTT_DISCOVERY_PREFIX=homeassistant
POLL_SEC=2
TEMP_OFFSET=0.0
HUM_OFFSET=0.0
CPU_TEMP_FACTOR=1.8
---
## 🔧 Manual Setup
If you installed via `pip install ha-enviro-plus`, you'll need to manually configure the service:
### 1. Create Configuration File
sudo mkdir -p /etc/default
sudo tee /etc/default/ha-enviro-plus > /dev/null <<EOF
MQTT_HOST=homeassistant.local
MQTT_PORT=1883
MQTT_USER=enviro
MQTT_PASS=<use_your_own>
MQTT_DISCOVERY_PREFIX=homeassistant
POLL_SEC=2
TEMP_OFFSET=0.0
HUM_OFFSET=0.0
CPU_TEMP_FACTOR=1.8
EOF
### 2. Create Settings Directory
sudo mkdir -p /var/lib/ha-enviro-plus
sudo chown pi:pi /var/lib/ha-enviro-plus
### 3. Install Systemd Service
sudo tee /etc/systemd/system/ha-enviro-plus.service > /dev/null <<EOF
[Unit]
Description=Enviro+ → Home Assistant MQTT Agent
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
EnvironmentFile=/etc/default/ha-enviro-plus
WorkingDirectory=/opt/ha-enviro-plus
ExecStart=python3 -m ha_enviro_plus.agent
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
EOF
### 4. Start Service
sudo systemctl daemon-reload
sudo systemctl enable ha-enviro-plus.service
sudo systemctl start ha-enviro-plus.service
---
## 🧰 Uninstall
Remove the agent and optionally keep the config:
bash <(wget -qO- https://raw.githubusercontent.com/JeffLuckett/ha-enviro-plus/main/scripts/uninstall.sh)
The uninstaller:
- Stops and disables the systemd service
- Removes `/opt/ha-enviro-plus`, log files, and settings directory
- Prompts to preserve `/etc/default/ha-enviro-plus` (interactive mode)
- Works in both interactive and non-interactive modes
---
## 🧪 Testing
This project includes comprehensive tests to ensure reliability and maintainability.
### Test Structure
- **Unit Tests**: Test individual components with mocked hardware
- **Integration Tests**: Test MQTT functionality and end-to-end workflows
- **Hardware Tests**: Test with real Enviro+ sensors (optional, requires hardware)
### Running Tests
```bash
# Install development dependencies
pip install -r requirements-dev.txt
# Run all tests (excluding hardware)
pytest tests/ -m "not hardware"
# Run only unit tests
pytest tests/unit/
# Run only integration tests
pytest tests/integration/
# Run hardware tests (requires Enviro+ hardware)
pytest tests/hardware/
# Run with coverage
pytest tests/ --cov=ha_enviro_plus --cov-report=html
```
### Test Coverage
The project aims for >=75% test coverage. Coverage reports are generated in HTML format and available in the `htmlcov/` directory after running tests with coverage.
### Continuous Integration
Tests run automatically on every push and pull request via GitHub Actions, testing against Python 3.9, 3.10, 3.11, and 3.12.
### Development Setup
```bash
# Clone the repository
git clone https://github.com/JeffLuckett/ha-enviro-plus.git
cd ha-enviro-plus
# Option 1: Install in development mode (recommended)
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e .
# Option 2: Install from PyPI for testing
pip install ha-enviro-plus
# Option 3: Use the install script for development
./scripts/install.sh --branch main
# Install development dependencies
pip install -r requirements-dev.txt
# Run tests
pytest tests/ -m "not hardware"
```
---
- **Temperature Compensation**: The temperature sensor runs warm due to CPU proximity. The agent now includes automatic CPU temperature compensation using a configurable factor (default 1.8). You can adjust this factor via Home Assistant or the config file for optimal accuracy.
- **Calibration**: Use the `TEMP_OFFSET` for fine-tuning individual installations, and `CPU_TEMP_FACTOR` to adjust the CPU compensation algorithm.
- Humidity readings depend on temperature calibration — adjust both together.
- Sound and particulate sensors are planned for v0.2.0; the agent functions fully without them.
---
## 🧪 Version
**v0.1.1 — Stable Release**
This version includes:
- Complete Enviro+ sensor support (BME280, LTR559, Gas sensors)
- MQTT integration with Home Assistant discovery
- System telemetry (CPU temperature, load, memory, disk)
- Home Assistant control entities (reboot, restart, shutdown)
- Configurable polling intervals and calibration offsets
- CPU temperature compensation for accurate readings
- Graceful shutdown handling and configuration validation
- **PyPI installation support** (pip install ha-enviro-plus)
- **Enhanced install script** with PyPI-first approach
- **Test mode** for safe installation validation
- Comprehensive test suite with >=75% coverage
**Next milestone (v0.2.0):**
- Noise sensor (microphone to dB conversion)
- PMS5003 particulate sensor support
- 0.96" LCD display system with plugin architecture
---
## 📜 License
MIT © 2025 Jeff Luckett
Raw data
{
"_id": null,
"home_page": null,
"name": "ha-enviro-plus",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "homeassistant, mqtt, enviro, raspberry-pi, sensors",
"author": "Jeff Luckett",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/24/ba/f0267acce20c77760e44fb45bf1a18cb60a3babf5045717fb8065522edeb/ha_enviro_plus-0.1.1.tar.gz",
"platform": null,
"description": "# ha-enviro-plus\n\n[](https://github.com/JeffLuckett/ha-enviro-plus/actions)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/JeffLuckett/ha-enviro-plus/releases/latest)\n\n**Enviro+ \u2192 Home Assistant MQTT Agent**\nA lightweight Python agent for publishing Pimoroni Enviro+ sensor data (temperature, humidity, pressure, light, gas, and system metrics) to Home Assistant via MQTT with automatic discovery.\n\n---\n\n## \ud83d\ude80 Overview\n\n`ha-enviro-plus` turns a Raspberry Pi Zero 2 W (or any Pi running the Enviro+) into a self-contained Home Assistant satellite.\n\nIt reads data from:\n- **BME280** (temperature, humidity, pressure)\n- **LTR559** (ambient light)\n- **Gas sensor** (oxidising, reducing, NH\u2083)\nand publishes them to Home Assistant over MQTT using native **HA Discovery**.\n\nAdditional system telemetry is included:\n- CPU temperature, load, and uptime\n- Memory and disk utilisation\n- Network info and hostname\n- Service availability and reboot/restart controls\n\n---\n\n## \ud83e\udde9 Features\n\n- Plug-and-play Home Assistant discovery (no YAML setup)\n- Fast, configurable polling (default 2 s)\n- On-device temperature / humidity calibration offsets\n- CPU temperature compensation for accurate readings (higher number lowers temp. output)\n- Host metrics: uptime, CPU temp, load, RAM, disk\n- MQTT availability and discovery payloads\n- Home Assistant controls:\n - Reboot device\n - Restart service\n - Shutdown\n - Apply calibration offsets\n - Adjust CPU temperature compensation factor\n- Structured logging (rotation-friendly)\n- Graceful shutdown handling (SIGTERM/SIGINT)\n- Startup configuration validation\n- Safe installer/uninstaller with config preservation\n- Versioned installation support (`--release`, `--branch` flags)\n- Designed and tested with a Raspberry Pi Zero 2 W + Enviro+ HAT. Also supports the original Enviro HAT (fewer sensors) and runs on any hardware that supports these devices and the necessary libraries. (Testers welcome!)\n\n---\n\n## \u2699\ufe0f Quick Install\n\n### Recommended: Install Script (PyPI-first)\n\nRun this command **on your Raspberry Pi**:\n\n bash <(wget -qO- https://raw.githubusercontent.com/JeffLuckett/ha-enviro-plus/main/scripts/install.sh)\n\n**Installation Methods:**\n- **Latest stable (PyPI)**: `./install.sh` *(default)*\n- **Specific version (PyPI)**: `./install.sh --release v0.1.1`\n- **Development branch**: `./install.sh --branch feature-branch`\n- **Test mode**: `./install.sh --test` *(validate without changes)*\n- **Show installer info**: `./install.sh --version`\n\nThe installer automatically:\n- **Prioritizes PyPI** for stable releases (faster, more reliable)\n- **Falls back to GitHub** for development branches or specific versions\n- Creates `/opt/ha-enviro-plus` and installs dependencies\n- Prompts for MQTT host, username, and password\n- Prompts for poll interval and temperature / humidity offsets\n- Installs and starts the systemd service\n\n### Alternative: Direct PyPI Install\n\nFor advanced users who prefer manual installation:\n\n pip install ha-enviro-plus\n\nThen manually configure and start the service (see [Manual Setup](#manual-setup)).\n\nHome Assistant should auto-discover the sensors within a few seconds.\n\n---\n\n## \ud83d\udd27 Configuration\n\nConfiguration lives at:\n\n /etc/default/ha-enviro-plus\n\nEdit values safely, then restart the service:\n\n sudo systemctl restart ha-enviro-plus\n\n**Example config:**\n\n MQTT_HOST=homeassistant.local\n MQTT_PORT=1883\n MQTT_USER=enviro\n MQTT_PASS=<use_your_own>\n MQTT_DISCOVERY_PREFIX=homeassistant\n POLL_SEC=2\n TEMP_OFFSET=0.0\n HUM_OFFSET=0.0\n CPU_TEMP_FACTOR=1.8\n\n---\n\n## \ud83d\udd27 Manual Setup\n\nIf you installed via `pip install ha-enviro-plus`, you'll need to manually configure the service:\n\n### 1. Create Configuration File\n\n sudo mkdir -p /etc/default\n sudo tee /etc/default/ha-enviro-plus > /dev/null <<EOF\n MQTT_HOST=homeassistant.local\n MQTT_PORT=1883\n MQTT_USER=enviro\n MQTT_PASS=<use_your_own>\n MQTT_DISCOVERY_PREFIX=homeassistant\n POLL_SEC=2\n TEMP_OFFSET=0.0\n HUM_OFFSET=0.0\n CPU_TEMP_FACTOR=1.8\n EOF\n\n### 2. Create Settings Directory\n\n sudo mkdir -p /var/lib/ha-enviro-plus\n sudo chown pi:pi /var/lib/ha-enviro-plus\n\n### 3. Install Systemd Service\n\n sudo tee /etc/systemd/system/ha-enviro-plus.service > /dev/null <<EOF\n [Unit]\n Description=Enviro+ \u2192 Home Assistant MQTT Agent\n After=network-online.target\n Wants=network-online.target\n\n [Service]\n Type=simple\n EnvironmentFile=/etc/default/ha-enviro-plus\n WorkingDirectory=/opt/ha-enviro-plus\n ExecStart=python3 -m ha_enviro_plus.agent\n Restart=on-failure\n RestartSec=5\n StandardOutput=journal\n StandardError=journal\n\n [Install]\n WantedBy=multi-user.target\n EOF\n\n### 4. Start Service\n\n sudo systemctl daemon-reload\n sudo systemctl enable ha-enviro-plus.service\n sudo systemctl start ha-enviro-plus.service\n\n---\n\n## \ud83e\uddf0 Uninstall\n\nRemove the agent and optionally keep the config:\n\n bash <(wget -qO- https://raw.githubusercontent.com/JeffLuckett/ha-enviro-plus/main/scripts/uninstall.sh)\n\nThe uninstaller:\n- Stops and disables the systemd service\n- Removes `/opt/ha-enviro-plus`, log files, and settings directory\n- Prompts to preserve `/etc/default/ha-enviro-plus` (interactive mode)\n- Works in both interactive and non-interactive modes\n\n---\n\n## \ud83e\uddea Testing\n\nThis project includes comprehensive tests to ensure reliability and maintainability.\n\n### Test Structure\n\n- **Unit Tests**: Test individual components with mocked hardware\n- **Integration Tests**: Test MQTT functionality and end-to-end workflows\n- **Hardware Tests**: Test with real Enviro+ sensors (optional, requires hardware)\n\n### Running Tests\n\n```bash\n# Install development dependencies\npip install -r requirements-dev.txt\n\n# Run all tests (excluding hardware)\npytest tests/ -m \"not hardware\"\n\n# Run only unit tests\npytest tests/unit/\n\n# Run only integration tests\npytest tests/integration/\n\n# Run hardware tests (requires Enviro+ hardware)\npytest tests/hardware/\n\n# Run with coverage\npytest tests/ --cov=ha_enviro_plus --cov-report=html\n```\n\n### Test Coverage\n\nThe project aims for >=75% test coverage. Coverage reports are generated in HTML format and available in the `htmlcov/` directory after running tests with coverage.\n\n### Continuous Integration\n\nTests run automatically on every push and pull request via GitHub Actions, testing against Python 3.9, 3.10, 3.11, and 3.12.\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/JeffLuckett/ha-enviro-plus.git\ncd ha-enviro-plus\n\n# Option 1: Install in development mode (recommended)\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\npip install -e .\n\n# Option 2: Install from PyPI for testing\npip install ha-enviro-plus\n\n# Option 3: Use the install script for development\n./scripts/install.sh --branch main\n\n# Install development dependencies\npip install -r requirements-dev.txt\n\n# Run tests\npytest tests/ -m \"not hardware\"\n```\n\n---\n\n- **Temperature Compensation**: The temperature sensor runs warm due to CPU proximity. The agent now includes automatic CPU temperature compensation using a configurable factor (default 1.8). You can adjust this factor via Home Assistant or the config file for optimal accuracy.\n- **Calibration**: Use the `TEMP_OFFSET` for fine-tuning individual installations, and `CPU_TEMP_FACTOR` to adjust the CPU compensation algorithm.\n- Humidity readings depend on temperature calibration \u2014 adjust both together.\n- Sound and particulate sensors are planned for v0.2.0; the agent functions fully without them.\n\n---\n\n## \ud83e\uddea Version\n\n**v0.1.1 \u2014 Stable Release**\n\nThis version includes:\n- Complete Enviro+ sensor support (BME280, LTR559, Gas sensors)\n- MQTT integration with Home Assistant discovery\n- System telemetry (CPU temperature, load, memory, disk)\n- Home Assistant control entities (reboot, restart, shutdown)\n- Configurable polling intervals and calibration offsets\n- CPU temperature compensation for accurate readings\n- Graceful shutdown handling and configuration validation\n- **PyPI installation support** (pip install ha-enviro-plus)\n- **Enhanced install script** with PyPI-first approach\n- **Test mode** for safe installation validation\n- Comprehensive test suite with >=75% coverage\n\n**Next milestone (v0.2.0):**\n- Noise sensor (microphone to dB conversion)\n- PMS5003 particulate sensor support\n- 0.96\" LCD display system with plugin architecture\n\n---\n\n## \ud83d\udcdc License\n\nMIT \u00a9 2025 Jeff Luckett\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Enviro+ to Home Assistant MQTT Agent",
"version": "0.1.1",
"project_urls": null,
"split_keywords": [
"homeassistant",
" mqtt",
" enviro",
" raspberry-pi",
" sensors"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c81da3d1d79e02ddc1f53f5851b2492596d8b7fc686e03c27f548702f58ae804",
"md5": "95cecffb4c04f303ac4d94bd785cdb07",
"sha256": "5acf164a352b65f9ebb775694260db20b7bb7f3eb11eaee4f604d31f281b45a7"
},
"downloads": -1,
"filename": "ha_enviro_plus-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "95cecffb4c04f303ac4d94bd785cdb07",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 43642,
"upload_time": "2025-10-25T00:38:29",
"upload_time_iso_8601": "2025-10-25T00:38:29.201322Z",
"url": "https://files.pythonhosted.org/packages/c8/1d/a3d1d79e02ddc1f53f5851b2492596d8b7fc686e03c27f548702f58ae804/ha_enviro_plus-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "24baf0267acce20c77760e44fb45bf1a18cb60a3babf5045717fb8065522edeb",
"md5": "8c37030e1574fed905ce7946a89f51b1",
"sha256": "ff9afc889080926ae65dd256ed2af17739262f3f26de8945e739abf40ae28326"
},
"downloads": -1,
"filename": "ha_enviro_plus-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "8c37030e1574fed905ce7946a89f51b1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 41668,
"upload_time": "2025-10-25T00:38:30",
"upload_time_iso_8601": "2025-10-25T00:38:30.277124Z",
"url": "https://files.pythonhosted.org/packages/24/ba/f0267acce20c77760e44fb45bf1a18cb60a3babf5045717fb8065522edeb/ha_enviro_plus-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-25 00:38:30",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ha-enviro-plus"
}
JSON