{"id":30207786,"url":"https://github.com/mysteriza/esp8266display-bme680","last_synced_at":"2026-04-19T06:49:09.988Z","repository":{"id":305894847,"uuid":"1024224705","full_name":"Mysteriza/ESP8266Display-BME680","owner":"Mysteriza","description":"Portable and offline environmental monitoring solution using an ESP8266 microcontroller with a built-in OLED display and a BME680 gas and environmental sensor.","archived":false,"fork":false,"pushed_at":"2025-08-21T10:25:37.000Z","size":1704,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-21T12:25:39.049Z","etag":null,"topics":["altitude-measurements","bme680","environmental-monitoring","esp8266","gas-sensor","humidity","iot","portable","pressure","temperature","web-server"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mysteriza.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-22T11:18:27.000Z","updated_at":"2025-08-21T10:25:40.000Z","dependencies_parsed_at":"2025-07-22T15:39:02.084Z","dependency_job_id":"a84cec51-73b1-40e3-bed7-c28cfe7b25c0","html_url":"https://github.com/Mysteriza/ESP8266Display-BME680","commit_stats":null,"previous_names":["mysteriza/esp8266display-bme680"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Mysteriza/ESP8266Display-BME680","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mysteriza%2FESP8266Display-BME680","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mysteriza%2FESP8266Display-BME680/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mysteriza%2FESP8266Display-BME680/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mysteriza%2FESP8266Display-BME680/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mysteriza","download_url":"https://codeload.github.com/Mysteriza/ESP8266Display-BME680/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mysteriza%2FESP8266Display-BME680/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271746299,"owners_count":24813557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-23T02:00:09.327Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["altitude-measurements","bme680","environmental-monitoring","esp8266","gas-sensor","humidity","iot","portable","pressure","temperature","web-server"],"created_at":"2025-08-13T16:41:57.292Z","updated_at":"2026-04-19T06:49:09.978Z","avatar_url":"https://github.com/Mysteriza.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# High-Precision ESP8266 BME680 Environmental Monitor\n\nA high-precision, portable environmental monitor using an ESP8266, a Bosch BME680 sensor, and an integrated OLED display. This project leverages the official **Bosch BSEC (Bosch Sensortec Environmental Cluster) software library** to provide accurate Indoor Air Quality (IAQ) readings, alongside temperature, humidity, pressure, and altitude.\n\nThe device is designed for **continuous operation** with robust error handling, intelligent baseline management, and an **always-on OLED display** that continuously cycles through data screens.\n\n[![Last Updated](https://img.shields.io/github/last-commit/mysteriza/ESP8266Display-BME680?label=Last%20Updated)](https://github.com/mysteriza/ESP8266Display-BME680/commits/main)\n\n\u003cimg src=\"https://github.com/user-attachments/assets/16ce6f7f-89be-46ac-ae11-b34ff67bfa96\" alt=\"ESP8266 Device Front View\" width=\"400\"\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/261b5c6e-4504-447e-8210-7e87774dcaeb\" alt=\"ESP8266 Device Side View\" width=\"400\"\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/99518c65-6359-4fd6-8f37-d91e0dde18bd\" alt=\"ESP8266 Device Rear View\" width=\"400\"\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/62e0e651-10e9-4774-bc52-773508a8fb07\" alt=\"ESP8266 Device Side View\" width=\"400\"\u003e\n\n---\n\n## Key Features\n\n### Core Sensing \u0026 IAQ\n\n- **Bosch BSEC Integration:** Utilizes Bosch's proprietary BSEC algorithm for reliable **Indoor Air Quality (IAQ)** index calculation (0–500 scale).\n- **Comprehensive Data:** Measures Temperature, Humidity, Barometric Pressure, Gas Resistance (VOCs), and calculates Altitude.\n- **Data Persistence:** Saves the BSEC calibration state to EEPROM every **4 hours**, but only when the IAQ accuracy level is high (`iaqAccuracy==3`). This minimizes flash wear and ensures stable calibration across power cycles.\n\n### Advanced Data Processing\n\n- **Variance-Aware IAQ Smoothing:** Implements an adaptive smoothing algorithm on the Static IAQ value, providing a more stable and human-readable output.\n- **Self-Adapting Gas Baseline:** Automatically adapts over time for long-term environmental stability.\n- **Transport-Aware Logic:** Freezes baseline calibration when rapid environmental changes are detected (e.g., device movement).\n- **Altitude Filtering:** Combines a median filter with an EMA for smooth and reliable altitude readings.\n\n### Display \u0026 Power\n\n- **Continuous Display Mode:** OLED display remains active 24/7, cycling through three data screens:\n  - **Screen 1 (5s):** Temperature \u0026 Humidity\n  - **Screen 2 (5s):** Pressure \u0026 Altitude\n  - **Screen 3 (5s):** Gas Resistance, IAQ, Accuracy, Air Quality Status\n- **Incremental Refresh:** Screen only updates when values change beyond thresholds, reducing flicker and CPU usage.\n- **Battery Optimized:** Sensor reads every 30 seconds with intelligent power management for 24hr+ battery life.\n\n### Overheat Protection\n\n- If temperature ≥ **45°C**, device enters \"HOT HOLD\" mode.\n- OLED shows a warning with a thermometer icon and the text **Overheat**, which shifts position every 60s to prevent burn-in.\n- Normal operation resumes when temperature drops below **41°C**.\n\n### Robustness\n\n- **Error Recovery:** Auto-retry mechanism for BSEC initialization with exponential backoff.\n- **Offline Operation:** Continues to work without network, using last known QNH or default fallback.\n- **Serial Command Interface:** Configure QNH, check status, and calibrate altitude via serial monitor.\n\n---\n\n## Hardware Components\n\n- **ESP8266 Board with Integrated OLED (0.96\" SSD1306).**\n- **Bosch BME680 Sensor** (I2C).\n- **TP4056** for LiPo battery charging and management.\n- **LiPo Battery** (e.g., 1500–2100 mAh).\n- **Power Switch** for on/off control.\n- **Custom PCB \u0026 Enclosure** for portability.\n\n---\n\n## Pin Configuration\n\n| Component          | Pin / Address |\n| ------------------ | ------------- |\n| I2C SDA (Data)     | `GPIO 14`     |\n| I2C SCL (Clock)    | `GPIO 12`     |\n| OLED I2C Address   | `0x3C`        |\n| BME680 I2C Address | `0x76`        |\n\n---\n\n## Software Requirements\n\n- Arduino IDE\n- ESP8266 Board Package for Arduino IDE\n- Libraries:\n  - `Wire.h` (Built-in)\n  - `EEPROM.h` (Built-in)\n  - `Adafruit GFX Library`\n  - `Adafruit SSD1306`\n  - `Bosch BSEC Software Library`\n\n---\n\n## ⚠️ Important: IRAM Overflow Fix\n\nIf you encounter this compilation error:\n\n```\nsection `.text1' will not fit in region `iram1_0_seg'\n```\n\nThis is a **memory configuration issue**, not a code problem. The fix requires two settings changes:\n\n### Quick Fix (Arduino IDE)\n\n1. **Tools** → **Flash Size** → Change to `4M (3M SPIFFS)`\n2. **Tools** → **MMU** → Select `16KB cache + 48KB IRAM`\n3. **Restart Arduino IDE**\n\n### Complete Guide\n\nSee **[FIX_IRAM_OVERFLOW_GUIDE.md](FIX_IRAM_OVERFLOW_GUIDE.md)** for:\n\n- Detailed step-by-step instructions\n- VS Code / PlatformIO configuration\n- Manual `platform.txt` replacement method\n- Troubleshooting and technical explanations\n\n**Included in this project:** `platform.txt` (ready-to-use replacement file)\n\n---\n\n## Installation \u0026 Setup\n\n1. **Install Arduino IDE \u0026 ESP8266 Core:**\n   Add `http://arduino.esp8266.com/stable/package_esp8266com_index.json` to Board Manager URLs.\n\n2. **Install Required Libraries** via Library Manager:\n   - \"Adafruit GFX Library\"\n   - \"Adafruit SSD1306\"\n   - \"BSEC Software Library\"\n\n3. **Configure the Sketch:**\n\n   ```cpp\n   // Optional: Edit configuration constants at top of sketch\n   #define SENSOR_READ_INTERVAL_MS 30000UL    // Sensor reading interval\n   #define OLED_DATA_SCREEN_1_DURATION 5000UL // Screen 1 duration\n   #define OLED_DATA_SCREEN_2_DURATION 5000UL // Screen 2 duration\n   #define OLED_DATA_SCREEN_3_DURATION 5000UL // Screen 3 duration\n   ```\n\n4. **Upload to ESP8266:**\n   - Go to `Tools \u003e Board` and select \"NodeMCU 1.0 (ESP-12E Module)\"\n   - **Tools \u003e Flash Size** → `4M (3M SPIFFS)`\n   - **Tools \u003e MMU** → `16KB cache + 48KB IRAM`\n   - Connect your board and select the correct COM port\n   - Click \"Upload\"\n\n---\n\n## Usage in the Field\n\n### 🔹 Calibration via QNH (when local QNH data is available)\n\n1. Connect your Android phone to the device via **USB-C OTG + data cable**.\n2. Open **Serial USB Terminal** (or any compatible terminal app).\n3. Set baud rate to **115200**, newline to **CR+LF**.\n4. Type:\n   ```\n   QNH=1013.25\n   ```\n   (Adjust this to the latest QNH in your location. Check weather apps such as [Breezy Weather](https://github.com/breezy-weather/breezy-weather) for current atmospheric pressure)\n\nThe device stores QNH in EEPROM and immediately recalculates altitude.\n\n### 🔹 Calibration via ALTREF (when you know the exact elevation)\n\n1. Stand at a location with a verified elevation (e.g., summit, basecamp, map marker).\n2. Type:\n   ```\n   ALTREF=709\n   ```\n   (Adjust this according to the altitude of your location)\n\nThe device computes QNH from the current pressure and saves it permanently. Verify with:\n\n```\nALT?\n```\n\n### 🔹 Hiking / Trekking Scenario\n\n- At **basecamp**, perform one calibration (QNH **or** ALTREF).\n- Recalibrate if the weather changes significantly.\n- **Precision Rule:** ±**1 hPa** ≈ ±**8–9 m** at mid-altitudes. Recalibrate whenever you change location or weather conditions vary.\n\n---\n\n## How It Works\n\n### IAQ (Indoor Air Quality) Index\n\nThe BSEC library provides an IAQ value on a scale from 0 to 500:\n\n- **0 - 50:** Excellent\n- **51 - 100:** Good\n- **101 - 150:** Lightly Polluted\n- **151 - 200:** Moderately Polluted\n- **201 - 300:** Heavily Polluted\n- **301+:** Severely Polluted\n\nThe device displays this scale as an \"AQS\" (Air Quality Status) string for easy interpretation. The `Acc` (Accuracy) value indicates the BSEC algorithm's confidence level (0=stabilizing, 1=low, 2=medium, 3=high). High accuracy is typically achieved after the device runs for a while.\n\n### Serial Commands\n\nConnect via serial monitor (115200 baud) and use:\n\n| Command      | Description                            | Example Response                    |\n| ------------ | -------------------------------------- | ----------------------------------- |\n| `QNH=\u003chPa\u003e`  | Set sea-level pressure                 | `OK QNH=1013.25 hPa`                |\n| `QNH?`       | Query current QNH value                | `QNH=1013.25 hPa`                   |\n| `ALT?`       | Query current altitude                 | `ALT=708.9 m`                       |\n| `PRESS?`     | Query current pressure                 | `P=933.10 hPa`                      |\n| `ALTREF=\u003cm\u003e` | Auto-calculate QNH from known altitude | `OK QNH from ALTREF -\u003e 1014.32 hPa` |\n| `STATUS`     | Show system status                     | `Mode:0 Therm:0 BSEC:Y IAQ:45.2(3)` |\n| `HELP`       | Show all commands                      | `CMD: QNH=\u003chPa\u003e\\|QNH?\\|ALT?\\|...`   |\n\n### Display Screens\n\nThe OLED continuously cycles through 3 screens:\n\n1. **Screen 1 (5s):** Temperature \u0026 Humidity\n2. **Screen 2 (5s):** Pressure \u0026 Altitude\n3. **Screen 3 (5s):** Gas Resistance, IAQ, Accuracy, AQS\n4. **Loops back to Screen 1** → Continuous monitoring mode\n\n### IAQ Scale\n\n| IAQ Range | Air Quality |\n| --------- | ----------- |\n| 0-50      | Excellent   |\n| 51-100    | Good        |\n| 101-150   | Light       |\n| 151-200   | Moderate    |\n| 201-300   | Unhealthy   |\n| 301+      | Hazardous   |\n\n### IAQ Accuracy\n\nThe `Acc` value (0-3) shows BSEC algorithm confidence:\n\n- **0:** Stabilizing (first 5-30 minutes)\n- **1:** Low confidence\n- **2:** Medium confidence\n- **3:** High confidence (optimal)\n\n---\n\n## Power Management\n\n### Display Behavior\n\n- **Continuous Mode:** Display never turns off\n- **3 screens cycle** every 5 seconds each (15s total cycle)\n- **Conditional redraw:** Only updates when values change beyond thresholds (reduces flicker)\n\n### Battery Life Estimates\n\n| Battery Capacity | Estimated Runtime |\n| ---------------- | ----------------- |\n| 1500 mAh         | ~24-30 hours      |\n| 2000 mAh         | ~30-36 hours      |\n| 2100 mAh         | ~32-40 hours      |\n\n_Estimates based on continuous display mode with 30s sensor intervals_\n\n---\n\n## Advanced Features\n\n### Thermal Protection\n\nWhen temperature reaches **45°C**:\n\n- Display shows animated \"Overheat\" warning\n- Contrast reduced to minimum (prevents OLED damage)\n- Warning icon position changes every 60s (prevents burn-in)\n- Normal operation resumes at **41°C**\n\n### Transport Detection\n\nThe device detects movement via rapid environmental changes:\n\n- Freezes gas baseline calibration during transport\n- Resumes calibration after 6 stable readings\n- Prevents false VOC readings during relocation\n\n### Adaptive IAQ Smoothing\n\nIAQ display uses variance-adaptive filtering:\n\n- **Low variance** (stable): Heavy smoothing (α=0.10) for stable reading\n- **High variance** (changing): Light smoothing (α=0.45) for responsiveness\n- **Accuracy-based:** Reduces smoothing when accuracy is low\n\n---\n\n## Accuracy Notes\n\n- **Formula:** Based on the standard barometric equation. Real-world temperature deviations may cause small altitude offsets.\n- **Sensor Tolerance:** BME680 pressure bias ≈ ±1 hPa → ±8–9 m error.\n- **Weather Impact:** QNH drifts naturally with weather; recalibrate as needed during extended outdoor sessions.\n\n---\n\n## Troubleshooting\n\n### ⚠️ IRAM Overflow Error (Compilation Error)\n\n**Symptoms:**\n\n```\nsection `.text1' will not fit in region `iram1_0_seg'\nCompilation error: exit status 1\n```\n\n**Solution:** This is a memory configuration issue, NOT a code problem.\n\n**Quick Fix:**\n\n1. **Arduino IDE:**\n   - Tools → Flash Size → Change to `4M (3M SPIFFS)`\n   - Tools → MMU → Select `16KB cache + 48KB IRAM`\n   - Restart Arduino IDE\n2. **VS Code:**\n   - Edit `.vscode/arduino.json`\n   - Change `eesz=1M64` → `eesz=4M3M`\n   - Change `mmu=3232` → `mmu=4816`\n   - Reload window\n\n**Complete Guide:** See [`FIX_IRAM_OVERFLOW_GUIDE.md`](FIX_IRAM_OVERFLOW_GUIDE.md) for detailed instructions and manual `platform.txt` replacement method.\n\n### BSEC Initialization Fails\n\n**Symptoms:** \"Sensor Error\" screen, \"Retrying...\"\n\n**Solutions:**\n\n1. Check I2C wiring (GPIO14=SDA, GPIO12=SCL)\n2. Verify BME680 address (0x76 or 0x77)\n3. Check serial monitor for error messages\n4. Power cycle device\n\n### IAQ Accuracy Stays at 0-1\n\n**Cause:** BSEC needs time to stabilize\n\n**Solution:** Leave device running for 30 minutes - 24 hours for full calibration\n\n### Display Flickers\n\n**Cause:** Normal when values change frequently\n\n**Solution:** Adjust thresholds (`TH_T`, `TH_H`, etc.) to reduce update frequency\n\n### EEPROM Corruption\n\n**Symptoms:** Settings reset on reboot\n\n**Solution:** Device auto-detects and repairs corrupted EEPROM\n\n---\n\n## Code Structure\n\n```\nESP8266Display-BME680.ino\n├── SECTION 1:  Includes\n├── SECTION 2:  Hardware Configuration\n├── SECTION 3:  Application Configuration\n├── SECTION 4:  Algorithm Parameters\n├── SECTION 5:  EEPROM Memory Map\n├── SECTION 6:  Type Definitions\n├── SECTION 7:  Global State Variables\n├── SECTION 8:  Utility Functions\n├── SECTION 9:  OLED Display Functions\n├── SECTION 10: Display State Management\n├── SECTION 11: EEPROM Storage Management\n├── SECTION 12: BME680 \u0026 BSEC Sensor Functions\n├── SECTION 13: Thermal Protection\n├── SECTION 14: Error Recovery \u0026 Retry\n├── SECTION 15: Serial Command Interface\n└── SECTION 16: Setup \u0026 Main Loop\n```\n\n---\n\n## Project Files\n\n| File                               | Description                               |\n| ---------------------------------- | ----------------------------------------- |\n| `ESP8266Display-BME680.ino`        | Main Arduino sketch (v2.0)                |\n| `ESP8266Display-BME680.ino.backup` | Original v1.x backup                      |\n| `platform.txt`                     | Fixed platform configuration for IRAM fix |\n| `FIX_IRAM_OVERFLOW_GUIDE.md`       | Complete IRAM overflow fix guide          |\n| `Fix RAM ESP8266.txt`              | Original fix notes                        |\n| `README.md`                        | This file - project documentation         |\n| `CHANGELOG.md`                     | Version history and changes               |\n| `MIGRATION.md`                     | Upgrade guide from v1.x to v2.0           |\n\n---\n\n## Performance Metrics\n\n### Memory Usage (Typical)\n\n- **Flash:** ~380 KB (varies with libraries)\n- **SRAM:** ~42 KB\n- **EEPROM:** 512 bytes (128 bytes used)\n\n### Timing\n\n- **Boot Time:** ~2 seconds to first reading\n- **BSEC Stabilization:** 5-30 minutes\n- **Sensor Read Cycle:** 30 seconds\n- **Display Cycle:** 15 seconds (3 screens, continuous loop)\n\n---\n\n## Contributing\n\n1. Fork repository\n2. Create feature branch\n3. Follow existing code structure and documentation style\n4. Test with actual hardware\n5. Submit PR with detailed description\n\n---\n\n## License\n\nThis project is provided as-is for educational and personal use.\n\nBSEC library is subject to Bosch Software License Agreement.\n\n---\n\n## Acknowledgments\n\n- **Bosch Sensortec** for BSEC library\n- **Adafruit** for display libraries\n- **ESP8266 community** for excellent core support\n\n---\n\n## Support\n\n- **Issues:** Open GitHub issue\n- **Questions:** Use GitHub Discussions\n- **Documentation:** See comments in source code and `FIX_IRAM_OVERFLOW_GUIDE.md`\n\n---\n\n**Version:** 2.0.0  \n**Last Updated:** 2026-04-11  \n**Author:** rifqi\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmysteriza%2Fesp8266display-bme680","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmysteriza%2Fesp8266display-bme680","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmysteriza%2Fesp8266display-bme680/lists"}