Metadata-Version: 2.4
Name: enviroplus-community
Version: 1.0.6
Summary: Community edition of Enviro pHAT Plus environmental monitoring for Raspberry Pi with opensensor.space integration
Project-URL: Repository, https://github.com/walkthru-earth/enviroplus-community
Project-URL: Homepage, https://opensensor.space
Project-URL: Documentation, https://github.com/walkthru-earth/enviroplus-community
Project-URL: Bug Tracker, https://github.com/walkthru-earth/enviroplus-community/issues
Project-URL: Source Code, https://github.com/walkthru-earth/enviroplus-community
Author-email: Philip Howard <phil@pimoroni.com>
Maintainer-email: Youssef Harby <yharby@walkthru.earth>
License: MIT License
        
        Copyright (c) 2018 Pimoroni Ltd.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: Pi,Raspberry,air-quality,environmental,enviroplus,iot,monitoring,opensensor,sensors
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.9
Requires-Dist: ads1015>=1.0.0
Requires-Dist: gpiod>=2.1.3
Requires-Dist: gpiodevice>=0.0.3
Requires-Dist: ltr559>=1.0.0
Requires-Dist: pimoroni-bme280>=1.0.0
Requires-Dist: pms5003>=1.0.1
Requires-Dist: st7735>=1.0.0
Provides-Extra: examples
Requires-Dist: astral; extra == 'examples'
Requires-Dist: font-roboto; extra == 'examples'
Requires-Dist: fonts; extra == 'examples'
Requires-Dist: paho-mqtt; extra == 'examples'
Requires-Dist: pillow; extra == 'examples'
Requires-Dist: pytz; extra == 'examples'
Requires-Dist: sounddevice; extra == 'examples'
Description-Content-Type: text/markdown

# Enviro+ Community Edition

![Enviro Plus pHAT](Enviro-Plus-pHAT.jpg)
![Enviro Mini pHAT](Enviro-mini-pHAT.jpg)

**Environmental monitoring for Raspberry Pi** - Measure air quality (gases and particulates), temperature, pressure, humidity, light, and noise.

[![Build Status](https://img.shields.io/github/actions/workflow/status/walkthru-earth/enviroplus-community/test.yml?branch=main)](https://github.com/walkthru-earth/enviroplus-community/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/enviroplus-community.svg)](https://pypi.org/project/enviroplus-community/)
[![Python Versions](https://img.shields.io/pypi/pyversions/enviroplus-community.svg)](https://pypi.org/project/enviroplus-community/)

---

## 🌍 Join the Open Sensor Network

**[opensensor.space](https://opensensor.space/)** is a cloud-native platform for streaming environmental sensor data to open datasets.

Part of the [walkthru.earth](https://walkthru.earth/) initiative for people-first urban intelligence:
- 🌱 **Minimum carbon footprint** - Edge processing reduces transmission by 60-90%
- 📊 **Open data** - All readings stored in Parquet format on [Source Cooperative](https://source.coop/)
- ⚡ **Near real-time** - Query sensor data in the browser with DuckDB
- 🔄 **Resilient** - Offline-first with automatic sync

[**See live data from Enviro+ sensors →**](https://opensensor.space/)

---

## 🚀 Quick Start

### Installation

```bash
# Install UV (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create isolated environment and install package
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install enviroplus-community

# Check system requirements
enviroplus-setup --check

# Install system dependencies and configure hardware
sudo enviroplus-setup --install

# Reboot (required for hardware changes)
sudo reboot
```

### Run Examples

```bash
# List all available examples
enviroplus-examples

# Get details about a specific example
enviroplus-examples --info weather.py

# Copy examples to your project
enviroplus-examples --copy ~/my-sensors/

# Run an example
uv run python -m enviroplus.examples.weather

# Or run directly (if venv is activated)
python -m enviroplus.examples.weather
```

### Quick Test

```python
import time
from pimoroni_bme280 import BME280

try:
    from smbus2 import SMBus
except ImportError:
    from smbus import SMBus

bme280 = BME280(i2c_dev=SMBus(1))

while True:
    temperature = bme280.get_temperature()
    pressure = bme280.get_pressure()
    humidity = bme280.get_humidity()

    print(f"Temperature: {temperature:.1f}°C")
    print(f"Pressure: {pressure:.1f}hPa")
    print(f"Humidity: {humidity:.1f}%")
    print("---")

    time.sleep(2)
```

---

## 📦 What's Included

### Hardware Support
- **BME280** - Temperature, pressure, humidity
- **LTR559** - Light and proximity
- **MICS6814** - Gas sensor (oxidising, reducing, NH3)
- **PMS5003** - Particulate matter (PM1, PM2.5, PM10)
- **ADAU7002** - MEMS microphone for noise measurement
- **ST7735** - 0.96" color LCD display (160x80)

### Python Package
- Core sensor libraries
- 17 example scripts
- Hardware setup tool (`enviroplus-setup`)
- Examples helper (`enviroplus-examples`)
- Full documentation

### Example Scripts

**Basic Sensors:**
- `weather.py` - Temperature, pressure, humidity
- `light.py` - Light sensor readings
- `gas.py` - Gas sensor readings
- `particulates.py` - Particulate matter readings
- `compensated-temperature.py` - CPU-compensated temperature

**Advanced:**
- `all-in-one.py` - Full dashboard with all sensors
- `mqtt-all.py` - Publish to MQTT broker
- `sensorcommunity.py` - Upload to Sensor.Community network
- `noise-profile.py` - Noise measurement with frequency analysis

[**See all examples →**](https://github.com/walkthru-earth/enviroplus-community/tree/main/enviroplus/examples)

---

## 🛠️ Hardware Setup

The `enviroplus-setup` tool automatically configures your Raspberry Pi:

```bash
# Check what's needed
enviroplus-setup --check

# Install and configure everything
sudo enviroplus-setup --install
```

**What it does:**
- ✅ Installs system packages (`python3-cffi`, `libportaudio2`)
- ✅ Enables I2C interface (for sensors)
- ✅ Enables SPI interface (for LCD display)
- ✅ Configures serial/UART (for PMS5003 sensor)
- ✅ Adds device tree overlays to `/boot/firmware/config.txt`
- ✅ Creates backup before changes

**Note:** A reboot is required after hardware configuration.

---

## 📖 Documentation

- **Installation Guide:** See above
- **Example Scripts:** [enviroplus/examples/](enviroplus/examples/)
- **API Reference:** Use `enviroplus-examples --info <script>` for details
- **Hardware Setup:** Run `enviroplus-setup --help`
- **Publishing Guide:** [PYPI_PUBLISHING.md](PYPI_PUBLISHING.md)
- **Development:** [DEVELOPMENT.md](DEVELOPMENT.md)

---

## 🤝 Community Projects & Integrations

Amazing projects built by the community using Enviro+:

### Cloud & IoT Platforms
- **[opensensor.space](https://opensensor.space/)** - Cloud-native open sensor network with edge processing and open data (walkthru.earth)
- **[enviroplus_exporter](https://github.com/tijmenvandenbrink/enviroplus_exporter)** - Prometheus exporter with Luftdaten and InfluxDB Cloud support
- **[mqtt-all](https://github.com/robmarkcole/rpi-enviro-mqtt)** - MQTT integration (now upstream in [examples/mqtt-all.py](enviroplus/examples/mqtt-all.py))
- **[sensorcommunity](https://sensor.community/)** - Upload data to Sensor.Community (Luftdaten) network

### Web Dashboards
- **[Enviro Plus Dashboard](https://gitlab.com/dedSyn4ps3/enviroplus-dashboard)** - React-based web dashboard for viewing sensor data
- **[Enviro Plus Web](https://gitlab.com/idotj/enviroplusweb)** - Flask application serving web pages with current readings and graphs
- **[enviro monitor](https://github.com/roscoe81/enviro-monitor)** - Comprehensive environmental monitoring solution

### Home Automation
- **[homekit-enviroplus](https://github.com/sighmon/homekit-enviroplus)** - Apple HomeKit accessory for Enviro+
- **[homebridge-enviroplus](https://github.com/mhawkshaw/homebridge-enviroplus)** - Homebridge plugin for HomeKit integration

### Development Libraries
- **[go-enviroplus](https://github.com/rubiojr/go-enviroplus)** - Go modules to read Enviro+ sensors
- **[Enviro+ Example Projects](https://gitlab.com/dedSyn4ps3/enviroplus-community-projects)** - Includes original examples plus code to stream to Adafruit IO

**Got a project?** [Add it here →](https://github.com/walkthru-earth/enviroplus-community/issues)

---

## 🆘 Help & Support

Need help getting started or troubleshooting?

### Documentation
- **Installation Guide:** See Quick Start above
- **Hardware Setup:** Run `enviroplus-setup --help`
- **Examples:** Run `enviroplus-examples` to see all available examples
- **API Reference:** Run `enviroplus-examples --info <script>` for details
- **GPIO Pinout:** [pinout.xyz/enviro_plus](https://pinout.xyz/pinout/enviro_plus)

### Get Help
- **GitHub Issues:** [Report bugs or request features](https://github.com/walkthru-earth/enviroplus-community/issues)
- **GitHub Discussions:** [Ask questions and share ideas](https://github.com/walkthru-earth/enviroplus-community/discussions)
- **Pimoroni Forums:** [Community support](https://forums.pimoroni.com/c/support)
- **Discord:** [Join the conversation](https://discord.gg/hr93ByC)
- **Email:** yharby@walkthru.earth (for opensensor.space integration)

### Useful Links
- **Enviro+ Product:** [shop.pimoroni.com/products/enviro-plus](https://shop.pimoroni.com/products/enviro-plus)
- **Getting Started Guide:** [learn.pimoroni.com/enviro-plus](https://learn.pimoroni.com/article/getting-started-with-enviro-plus)
- **opensensor.space:** [opensensor.space](https://opensensor.space/)
- **walkthru.earth:** [walkthru.earth](https://walkthru.earth/)

---

## 🔧 Development

Want to contribute? See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed setup instructions.

```bash
# Clone repository
git clone https://github.com/walkthru-earth/enviroplus-community.git
cd enviroplus-community

# Create isolated environment
uv venv
source .venv/bin/activate

# Install for development
uv pip install -e .

# Install dev dependencies
make dev-deps

# Run tests
make pytest

# Run QA checks
make qa

# Build package
make build
```

---

## 📋 Requirements

- **Hardware:** Raspberry Pi with Enviro+ or Enviro Mini pHAT
- **OS:** Raspberry Pi OS (Debian Bookworm or later recommended)
- **Python:** 3.9 - 3.13 (fully tested across all versions)
- **System packages:** Automatically installed by `enviroplus-setup`

**Supported boards:**
- Enviro+ (all sensors)
- Enviro Mini (no gas sensor or PM sensor)

---

## 📜 License

MIT License - see [LICENSE](LICENSE)

**Original Author:** Philip Howard (Pimoroni)
**Maintained by:** Youssef Harby ([walkthru.earth](https://walkthru.earth/))

---

## 🙏 Acknowledgments

- **Pimoroni** for creating the Enviro+ hardware and original library
- **walkthru.earth** for opensensor.space integration
- **Community contributors** for examples and integrations

---

**Made with ❤️ for open environmental data**

1.0.6
-----

* **Changelog**: Update changelog with missing entries

1.0.5
-----

* **Repository Rename**: Renamed repository to `enviroplus-community`
* **Documentation**: Updated all links to point to the new repository URL
* **Version Bump**: Bumped version to 1.0.5

1.0.4
-----

* **Setup**: Add udev rules configuration for serial devices
* **Setup**: Add dialout group check for PMS5003 serial access

1.0.3
-----

* **Maintainer update**: Set Youssef Harby as sole maintainer (displayed on PyPI)
* Philip Howard remains original author

1.0.2
-----

### Community Edition Updates
* **Package renamed** to `enviroplus-community` for PyPI distribution
* **Python 3.12 and 3.13** support added and fully tested
* **Modern packaging** with UV package manager and PEP 735 dependency groups
* **New tools**: `enviroplus-setup` for hardware configuration, `enviroplus-examples` for examples management
* **CI/CD modernization**: GitHub Actions with ruff, UV, and Trusted Publishers for PyPI
* **Code quality**: Migrated to ruff for linting/formatting (replaces black, isort, flake8)
* **Documentation**: Comprehensive guides for development and PyPI publishing
* **opensensor.space integration**: Cloud-native platform for open sensor data
* README.md: Update install instructions
* Fix installer to enable serial
* Fix gas sensor heater pin

1.0.1
-----

* README.md: Fix images

1.0.0
-----

* BREAKING: Port to gpiod/gpiodevice for Pi 5/Bookworm.

0.0.6
-----

* Fix noise by specifying adau7002 device

0.0.5
-----

* Drop Python 2.x support
* Add "available()" method for gas sensor

0.0.4
-----

* Add support for ads1015 >= v0.0.7 (ADS1115 ADCs)
* Packaging tweaks

0.0.3
-----

* Fix "self.noise_floor" bug in get_noise_profile

0.0.2
-----

* Add support for extra ADC channel in Gas
* Handle breaking change in new ltr559 library
* Add Noise functionality

0.0.1
-----

* Initial Release
