468 lines
12 KiB
Markdown
468 lines
12 KiB
Markdown
<div align="center">
|
||
|
||
# 🌡️ Lab Weather Tracker
|
||
### *Environmental Monitoring System for Raspberry Pi*
|
||
|
||
[](https://opensource.org/licenses/MIT)
|
||
[](https://www.python.org/downloads/)
|
||
[](https://www.raspberrypi.org/)
|
||
|
||
*A professional Python-based weather monitoring system for tracking lab environmental conditions using the Pimoroni Enviro HAT*
|
||
|
||
[Features](#-features) • [Installation](#-installation) • [Usage](#-usage) • [Dashboard](#-web-dashboard) • [Configuration](#-configuration)
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## 📋 Table of Contents
|
||
|
||
- [Features](#-features)
|
||
- [Hardware Requirements](#-hardware-requirements)
|
||
- [Installation](#-installation)
|
||
- [Usage](#-usage)
|
||
- [Web Dashboard](#-web-dashboard)
|
||
- [Temperature Compensation](#-temperature-compensation)
|
||
- [Data Storage](#-data-storage)
|
||
- [Running as a Service](#-running-as-a-service)
|
||
- [Configuration](#-configuration)
|
||
- [Troubleshooting](#-troubleshooting)
|
||
- [Future Enhancements](#-future-enhancements)
|
||
- [License](#-license)
|
||
|
||
---
|
||
|
||
## ✨ Features
|
||
|
||
<table>
|
||
<tr>
|
||
<td width="50%">
|
||
|
||
### 📊 Data Collection
|
||
- 🌡️ **Temperature Monitoring** with CPU heat compensation
|
||
- 💧 **Humidity Tracking** (relative humidity %)
|
||
- 🔽 **Barometric Pressure** (hPa)
|
||
- 💡 **Ambient Light** levels (lux)
|
||
- 🎨 **Color Detection** (RGB values)
|
||
|
||
</td>
|
||
<td width="50%">
|
||
|
||
### 🎯 Core Features
|
||
- ⏱️ **5-minute sampling interval** (configurable)
|
||
- 📁 **CSV logging** (one file per day)
|
||
- 📈 **Real-time console display**
|
||
- 🌐 **Web dashboard** with live charts
|
||
- 🔄 **Auto-refresh** every 10 seconds
|
||
- 📊 **Historical data** visualization
|
||
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
### 🔥 Temperature Compensation
|
||
|
||
This system implements **intelligent CPU temperature compensation** to ensure accurate ambient temperature readings:
|
||
|
||
- 🧮 Compensates for Raspberry Pi CPU heat affecting the BME280 sensor
|
||
- 📉 Uses rolling average of 5 CPU temperature samples to reduce jitter
|
||
- 🎯 Applies scientifically-proven compensation formula
|
||
- 📊 Logs both raw and compensated temperatures for analysis
|
||
- ⚙️ Configurable compensation factor (default: 2.25)
|
||
|
||
> **Formula:** `compensated_temp = raw_temp - ((avg_cpu_temp - raw_temp) / factor)`
|
||
|
||
---
|
||
|
||
## 🔧 Hardware Requirements
|
||
|
||
| Component | Description |
|
||
|-----------|-------------|
|
||
| **Raspberry Pi** | Any model with 40-pin GPIO header (3/4/Zero recommended) |
|
||
| **Pimoroni Enviro HAT** | Environmental monitoring HAT with BME280 & LTR559 sensors |
|
||
| **Power Supply** | Official Raspberry Pi power supply (5V, 2.5A+) |
|
||
| **microSD Card** | 8GB+ with Raspberry Pi OS installed |
|
||
|
||
---
|
||
|
||
## 📥 Installation
|
||
|
||
### 1️⃣ Install System Dependencies
|
||
|
||
```bash
|
||
sudo apt update && apt upgrade
|
||
sudo apt install -y python3-pip python3-dev git i2c-tools
|
||
```
|
||
|
||
### 2️⃣ Clone the Repository
|
||
|
||
```bash
|
||
git clone https://github.com/yourusername/binglab-enviro.git
|
||
```
|
||
|
||
### 3️⃣ Create Python virtual environment and install Dependencies
|
||
|
||
```bash
|
||
python3 -m venv enviro
|
||
source enviro/bin/activate
|
||
cd binglab-enviro
|
||
pip3 install -r requirements.txt
|
||
```
|
||
|
||
### 4️⃣ Enable I2C Interface
|
||
|
||
The Enviro HAT requires I2C to be enabled:
|
||
|
||
```bash
|
||
sudo raspi-config
|
||
```
|
||
|
||
Navigate to: **Interfacing Options → I2C → Enable**
|
||
|
||
Then reboot:
|
||
```bash
|
||
sudo reboot
|
||
```
|
||
|
||
### 5️⃣ Verify Installation
|
||
|
||
```bash
|
||
i2cdetect -y 1
|
||
```
|
||
|
||
You should see device addresses `76` (BME280) and `23` (LTR559).
|
||
|
||
---
|
||
|
||
## 🚀 Usage
|
||
|
||
### Console Mode (Data Logger)
|
||
|
||
Start the weather tracker to log data every 5 minutes:
|
||
|
||
```bash
|
||
python3 weather_tracker.py
|
||
```
|
||
|
||
**Output:**
|
||
```
|
||
Lab Weather Tracker Starting...
|
||
Logging interval: 300 seconds (5.0 minutes)
|
||
✓ BME280 sensor initialized
|
||
✓ LTR559 sensor initialized
|
||
|
||
==================================================
|
||
Lab Weather Report - 2025-12-03T14:23:45.123456
|
||
==================================================
|
||
Temperature (raw): 24.32°C
|
||
Temperature (compensated): 21.85°C
|
||
Pressure: 1013.25 hPa
|
||
Humidity: 45.60%
|
||
Light Level: 234.50 lux
|
||
Proximity: 12.00
|
||
==================================================
|
||
|
||
✓ Data logged to data/weather_log_2025-12-03.csv
|
||
Next reading in 300 seconds...
|
||
```
|
||
|
||
**Keyboard Shortcuts:**
|
||
- `Ctrl + C` - Gracefully stop the tracker
|
||
|
||
---
|
||
|
||
## 🌐 Web Dashboard
|
||
|
||
### Starting the Dashboard
|
||
|
||
```bash
|
||
python3 web_dashboard.py
|
||
```
|
||
|
||
Then open your browser:
|
||
- **Local:** `http://localhost:5000`
|
||
- **Network:** `http://<raspberry-pi-ip>:5000`
|
||
|
||
### Dashboard Features
|
||
|
||
<table>
|
||
<tr>
|
||
<td width="50%">
|
||
|
||
#### 📊 Current Readings Card
|
||
- Live temperature (compensated + raw)
|
||
- Real-time pressure
|
||
- Current humidity
|
||
- Light levels
|
||
- Color swatch visualization
|
||
|
||
</td>
|
||
<td width="50%">
|
||
|
||
#### 📈 Analytics
|
||
- Min/Max/Average statistics
|
||
- Historical trend charts
|
||
- Last 100 data points
|
||
- Auto-refresh every 60 seconds
|
||
- Responsive mobile design
|
||
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
### Dashboard Preview
|
||
|
||
```
|
||
╔════════════════════════════════════════════╗
|
||
║ MBTECH Binglab Envoro Dashboard ║
|
||
╠════════════════════════════════════════════╣
|
||
║ ║
|
||
║ 🌡️ Temperature 🔽 Pressure ║
|
||
║ 21.85°C 1013.25 hPa ║
|
||
║ Raw: 24.32°C ║
|
||
║ ║
|
||
║ 💡 Light 🎨 Color ║
|
||
║ 234.5 lux [■■■] ║
|
||
║ ║
|
||
╠════════════════════════════════════════════╣
|
||
║ 📊 Today's Statistics ║
|
||
║ Temperature: 18.2°C - 22.5°C (avg 20.3) ║
|
||
║ Pressure: 1010-1015 hPa (avg 1012.5) ║
|
||
║ ║
|
||
╠════════════════════════════════════════════╣
|
||
║ 📈 Historical Trends (24 hours) ║
|
||
║ [Temperature Chart] ║
|
||
║ [Pressure Chart] ║
|
||
║ [Light Chart] ║
|
||
╚════════════════════════════════════════════╝
|
||
```
|
||
|
||
> **💡 Tip:** Run both the tracker and dashboard simultaneously! The tracker logs data, while the dashboard displays it.
|
||
|
||
---
|
||
|
||
## 🌡️ Temperature Compensation
|
||
|
||
### Why Temperature Compensation?
|
||
|
||
The BME280 sensor is located near the Raspberry Pi CPU, which generates heat. This causes raw temperature readings to be **2-5°C higher** than actual ambient temperature.
|
||
|
||
### How It Works
|
||
|
||
1. **Read CPU Temperature** from `/sys/class/thermal/thermal_zone0/temp`
|
||
2. **Smooth with Rolling Average** of last 5 readings to reduce jitter
|
||
3. **Apply Compensation Formula:**
|
||
```python
|
||
compensated_temp = raw_temp - ((avg_cpu_temp - raw_temp) / 2.25)
|
||
```
|
||
4. **Log Both Values** for comparison and analysis
|
||
|
||
### Adjusting the Compensation Factor
|
||
|
||
Edit the `TEMP_COMP_FACTOR` in both files:
|
||
|
||
```python
|
||
# weather_tracker.py (line 27)
|
||
TEMP_COMP_FACTOR = 2.25 # Decrease for more compensation, increase for less
|
||
|
||
# web_dashboard.py (line 40)
|
||
TEMP_COMP_FACTOR = 2.25 # Keep values synchronized
|
||
```
|
||
|
||
**Tuning Guide:**
|
||
- **Too Hot?** Decrease factor → `2.0` (more aggressive compensation)
|
||
- **Too Cold?** Increase factor → `2.5` (less aggressive compensation)
|
||
|
||
---
|
||
|
||
## 💾 Data Storage
|
||
|
||
Data is automatically saved to the `data/` directory:
|
||
|
||
```
|
||
data/
|
||
├── weather_log_2025-12-01.csv
|
||
├── weather_log_2025-12-02.csv
|
||
└── weather_log_2025-12-03.csv
|
||
```
|
||
|
||
### CSV Format
|
||
|
||
| Column | Description | Unit |
|
||
|--------|-------------|------|
|
||
| `timestamp` | ISO 8601 timestamp | - |
|
||
| `temperature_raw_c` | Raw BME280 reading | °C |
|
||
| `temperature_c` | CPU-compensated temperature | °C |
|
||
| `pressure_hpa` | Barometric pressure | hPa |
|
||
| `humidity_percent` | Relative humidity | % |
|
||
| `light_lux` | Ambient light level | lux |
|
||
| `proximity` | Proximity sensor value | - |
|
||
|
||
**Example:**
|
||
```csv
|
||
timestamp,temperature_raw_c,temperature_c,pressure_hpa,humidity_percent,light_lux,proximity
|
||
2025-12-03T14:23:45.123456,24.32,21.85,1013.25,45.60,234.50,12.00
|
||
```
|
||
|
||
---
|
||
|
||
## ⚙️ Configuration
|
||
|
||
### weather_tracker.py
|
||
|
||
```python
|
||
# Line 25-27
|
||
DATA_DIR = "data" # Change data storage location
|
||
LOG_INTERVAL = 300 # Seconds between readings (300 = 5 min)
|
||
TEMP_COMP_FACTOR = 2.25 # Temperature compensation tuning
|
||
```
|
||
|
||
### web_dashboard.py
|
||
|
||
```python
|
||
# Line 38-40
|
||
DATA_DIR = "data" # Must match weather_tracker.py
|
||
MAX_HISTORY_POINTS = 100 # Number of points on charts
|
||
TEMP_COMP_FACTOR = 2.25 # Temperature compensation tuning
|
||
```
|
||
|
||
**Common Configurations:**
|
||
|
||
| Interval | Seconds | Use Case |
|
||
|----------|---------|----------|
|
||
| 1 minute | `60` | High-frequency monitoring |
|
||
| 5 minutes | `300` | **Default** - Balanced |
|
||
| 15 minutes | `900` | Low power consumption |
|
||
| 1 hour | `3600` | Long-term trends |
|
||
|
||
---
|
||
|
||
## 🔍 Troubleshooting
|
||
|
||
### ❌ `ImportError: No module named 'bme280'`
|
||
|
||
**Solution:**
|
||
```bash
|
||
pip3 install pimoroni-bme280
|
||
pip3 install smbus2
|
||
```
|
||
|
||
### ❌ I2C Errors / Sensor Not Detected
|
||
|
||
**Solution:**
|
||
```bash
|
||
# 1. Enable I2C
|
||
sudo raspi-config # Interface Options → I2C → Enable
|
||
|
||
# 2. Check I2C devices
|
||
i2cdetect -y 1
|
||
|
||
# 3. Add user to i2c group
|
||
sudo usermod -a -G i2c $USER
|
||
newgrp i2c # Or logout and login again
|
||
|
||
# 4. Verify connections
|
||
# BME280 should show at 0x76
|
||
# LTR559 should show at 0x23
|
||
```
|
||
|
||
### ❌ Permission Denied Errors
|
||
|
||
**Solution:**
|
||
```bash
|
||
sudo usermod -a -G i2c,gpio $USER
|
||
sudo chmod 644 /sys/class/thermal/thermal_zone0/temp
|
||
```
|
||
|
||
### ❌ Web Dashboard Not Accessible from Network
|
||
|
||
**Solution:**
|
||
```bash
|
||
# 1. Check firewall
|
||
sudo ufw allow 5000/tcp
|
||
|
||
# 2. Find Raspberry Pi IP address
|
||
hostname -I
|
||
|
||
# 3. Verify Flask is running on all interfaces
|
||
# web_dashboard.py line 176 should be:
|
||
# app.run(host='0.0.0.0', port=5000, ...)
|
||
```
|
||
|
||
### ❌ Temperature Readings Too High/Low
|
||
|
||
**Solution:**
|
||
Adjust the `TEMP_COMP_FACTOR`:
|
||
- **Too high?** Decrease factor (e.g., `2.0` for more compensation)
|
||
- **Too low?** Increase factor (e.g., `2.5` for less compensation)
|
||
|
||
Test with a calibrated thermometer and adjust accordingly.
|
||
|
||
---
|
||
|
||
## 🎯 Future Enhancements
|
||
|
||
### Planned Features
|
||
|
||
- [ ] 📧 Email/SMS alerts for threshold breaches
|
||
- [ ] 🏠 Home Assistant integration
|
||
- [ ] 🗄️ Database storage (SQLite/InfluxDB)
|
||
- [ ] 📥 CSV export from web dashboard
|
||
- [ ] 📊 Multi-day comparison views
|
||
- [ ] 🔔 Push notifications
|
||
- [ ] 📱 Mobile app
|
||
- [ ] ☁️ Cloud sync capabilities
|
||
- [ ] 🤖 AI-powered anomaly detection
|
||
- [ ] 📈 Predictive analytics
|
||
|
||
### Contributing
|
||
|
||
Contributions are welcome! Feel free to:
|
||
- 🐛 Report bugs
|
||
- 💡 Suggest features
|
||
- 🔧 Submit pull requests
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
```
|
||
MIT License
|
||
|
||
Copyright (c) 2025 MBTECH
|
||
|
||
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.
|
||
```
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
### Made with ❤️ by MBTECH
|
||
|
||
**MBTECH Binglab Environmental Monitoring System**
|
||
|
||
*Keeping your lab conditions perfect, one reading at a time.*
|
||
|
||
[](https://github.com/yourusername/raspi-enviro)
|
||
[](#)
|
||
[](#)
|
||
|
||
</div>
|