first commit
This commit is contained in:
mvbingham
558
README.md
Normal file
558
README.md
Normal file
@@ -0,0 +1,558 @@
|
||||
<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-get update
|
||||
sudo apt-get install -y python3-pip python3-dev git
|
||||
```
|
||||
|
||||
### 2️⃣ Clone the Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/raspi-enviro.git
|
||||
cd raspi-enviro
|
||||
```
|
||||
|
||||
### 3️⃣ Install Python Dependencies
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Running as a Service
|
||||
|
||||
For 24/7 operation, configure systemd services:
|
||||
|
||||
### Weather Tracker Service
|
||||
|
||||
```bash
|
||||
sudo nano /etc/systemd/system/weather-tracker.service
|
||||
```
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Lab Weather Tracker with Temperature Compensation
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=pi
|
||||
WorkingDirectory=/home/pi/raspi-enviro
|
||||
ExecStart=/usr/bin/python3 /home/pi/raspi-enviro/weather_tracker.py
|
||||
Restart=on-failure
|
||||
RestartSec=10
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
### Web Dashboard Service
|
||||
|
||||
```bash
|
||||
sudo nano /etc/systemd/system/weather-dashboard.service
|
||||
```
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Lab Weather Dashboard
|
||||
After=network.target weather-tracker.service
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=pi
|
||||
WorkingDirectory=/home/pi/raspi-enviro
|
||||
ExecStart=/usr/bin/python3 /home/pi/raspi-enviro/web_dashboard.py
|
||||
Restart=on-failure
|
||||
RestartSec=10
|
||||
Environment="FLASK_ENV=production"
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
### Enable and Start Services
|
||||
|
||||
```bash
|
||||
# Enable auto-start on boot
|
||||
sudo systemctl enable weather-tracker.service
|
||||
sudo systemctl enable weather-dashboard.service
|
||||
|
||||
# Start services now
|
||||
sudo systemctl start weather-tracker.service
|
||||
sudo systemctl start weather-dashboard.service
|
||||
|
||||
# Check status
|
||||
sudo systemctl status weather-tracker.service
|
||||
sudo systemctl status weather-dashboard.service
|
||||
|
||||
# View logs
|
||||
journalctl -u weather-tracker.service -f
|
||||
journalctl -u weather-dashboard.service -f
|
||||
```
|
||||
|
||||
### Service Management Commands
|
||||
|
||||
```bash
|
||||
# Stop services
|
||||
sudo systemctl stop weather-tracker.service
|
||||
sudo systemctl stop weather-dashboard.service
|
||||
|
||||
# Restart services
|
||||
sudo systemctl restart weather-tracker.service
|
||||
sudo systemctl restart weather-dashboard.service
|
||||
|
||||
# Disable auto-start
|
||||
sudo systemctl disable weather-tracker.service
|
||||
sudo systemctl disable weather-dashboard.service
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 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>
|
||||
Reference in New Issue
Block a user