Project 1: Environmental Monitor with Web Dashboard

Project Overview

Attribute	Value
Difficulty	Beginner-Intermediate
Time Estimate	1-2 weeks
Main Language	C
Alternatives	MicroPython, Rust, Arduino C++
Primary Book	Making Embedded Systems by Elecia White
Knowledge Areas	Embedded Systems, GPIO, WiFi, I2C, HTTP

What You’ll Build

A sensor station that reads temperature, humidity, and air quality, serves a real-time web dashboard over WiFi, and logs data to flash storage.

Physical Setup:

ESP32 development board on a breadboard
BME280 sensor (I2C) or DHT22 sensor (GPIO) for temperature and humidity
Optional: MQ-135 air quality sensor (analog ADC)
LED indicator for WiFi status
Powered via USB cable

Web Dashboard Preview:

┌─────────────────────────────────────────┐
│  Environmental Monitor - Living Room    │
├─────────────────────────────────────────┤
│                                         │
│  Temperature:  22.3°C  (72.1°F)         │
│  Humidity:     45%                      │
│  Air Quality:  Good (385 ppm)           │
│                                         │
│  Last Updated: 2 seconds ago            │
│  Auto-refresh: ON                       │
│                                         │
│  ┌────────────────────────────────┐    │
│  │ Temperature (Last 24 Hours)    │    │
│  │      ╭──╮                      │    │
│  │  ╭───╯  ╰──╮                   │    │
│  │──╯         ╰──                 │    │
│  └────────────────────────────────┘    │
│                                         │
│  Device Uptime: 3 days, 14 hours       │
│  Readings Stored: 4,320 (72 hours)     │
└─────────────────────────────────────────┘

Learning Objectives

By completing this project, you will be able to:

Configure and use I2C communication to read data from sensors
Set up ESP32 as a WiFi station and handle connection/disconnection gracefully
Implement an HTTP server on embedded hardware to serve web pages
Use Non-Volatile Storage (NVS) to persist data across reboots
Read analog sensors using ADC and understand voltage conversion
Create concurrent tasks with FreeRTOS for sensor reading and web serving

Deep Theoretical Foundation

I2C Communication Protocol

I2C (Inter-Integrated Circuit) is a synchronous, multi-master, multi-slave serial communication protocol invented by Philips in 1982. Understanding I2C is fundamental to embedded systems because most sensors, displays, and peripheral chips use it.

The Two-Wire Interface

I2C uses only two wires:

SDA (Serial Data): Bidirectional data line
SCL (Serial Clock): Clock signal generated by the master

Both lines are “open-drain” with pull-up resistors (typically 4.7kΩ), meaning devices can only pull the line LOW—they release it to go HIGH. This design enables multiple devices to share the bus without conflicts.

I2C Timing and Signaling

       ┌──────────────────────────────────────────────────────┐
       │                    I2C Transaction                    │
       └──────────────────────────────────────────────────────┘

SDA:   ─────┐     ┌─────┬─────┬─────┬─────┬─────┬─────┐     ┌─────
            │ S   │ A6  │ A5  │ ... │ A0  │ R/W │ ACK │ ... │ P
            └─────┴─────┴─────┴─────┴─────┴─────┴─────┘     └─────

SCL:   ──────┐ ┌─┐ ┌─┐ ┌─┐       ┌─┐ ┌─┐ ┌─┐ ┌─┐       ┌─┐ ┌──────
             └─┘ └─┘ └─┘ └─ ... ─┘ └─┘ └─┘ └─┘ └─ ... ─┘ └─┘

       START  │← 7-bit Address →│R/W│ACK│← Data bytes →│STOP

START Condition: SDA goes LOW while SCL is HIGH STOP Condition: SDA goes HIGH while SCL is HIGH Data Transfer: Each bit is read when SCL is HIGH; SDA must be stable

I2C Addressing

Every I2C device has a unique 7-bit address (some use 10-bit). The BME280 sensor uses address 0x76 or 0x77 depending on the SDO pin connection.

Address Byte: | A6 | A5 | A4 | A3 | A2 | A1 | A0 | R/W |
              |←────── 7-bit address ──────→|    └── 0=Write, 1=Read

Why this matters: If two devices share the same address, you’ll get communication errors. Before adding any I2C device, check its address doesn’t conflict with existing devices.

Clock Stretching

Some slow devices need more time to process data. They can hold SCL LOW to “stretch” the clock, pausing the master until ready. The BME280 uses clock stretching during temperature conversion.

GPIO (General Purpose Input/Output)

GPIO pins are the fundamental interface between your microcontroller and the physical world. Understanding their electrical characteristics prevents damage and enables reliable designs.

Pin Modes

Mode	Description	Use Case
Input	Reads external voltage (HIGH/LOW)	Buttons, switches, digital sensors
Output	Drives voltage HIGH (3.3V) or LOW (0V)	LEDs, relays, enable signals
Input Pullup	Input with internal pull-up resistor	Buttons without external resistor
Input Pulldown	Input with internal pull-down resistor	Detecting active-high signals
Analog	Reads voltage as continuous value	Potentiometers, analog sensors

ESP32 ADC Characteristics

The ESP32’s ADC (Analog-to-Digital Converter) has important limitations:

Resolution: 12-bit (0-4095 digital values)
Voltage Range: 0 to 3.3V (with attenuation)
Non-linearity: ESP32’s ADC is notoriously inaccurate at extremes
Noise: Expect ±10 LSB noise on readings

Attenuation Settings:
┌─────────────────┬───────────────────┬─────────────────┐
│ Attenuation     │ Measurable Range  │ Recommended For │
├─────────────────┼───────────────────┼─────────────────┤
│ 0 dB            │ 0 - 1.1V          │ Low voltage     │
│ 2.5 dB          │ 0 - 1.5V          │                 │
│ 6 dB            │ 0 - 2.2V          │                 │
│ 11 dB           │ 0 - 3.3V          │ Most sensors    │
└─────────────────┴───────────────────┴─────────────────┘

WiFi on ESP32

The ESP32 includes a complete WiFi stack supporting both 2.4GHz 802.11 b/g/n and Bluetooth. Understanding the different modes is essential for IoT projects.

WiFi Station Mode vs Access Point Mode

Station Mode (STA):                    Access Point Mode (AP):

Your Phone → Router → Internet         Your Phone → ESP32
                ↑                                      │
             ESP32                      No internet access
                                       Direct connection

Station Mode (used in this project): ESP32 connects to your existing WiFi router, getting an IP address via DHCP. This allows internet access and integration with your home network.

Access Point Mode: ESP32 creates its own WiFi network. Devices connect directly to the ESP32. Useful for configuration or when no router is available.

WiFi Connection Process

1. esp_wifi_init()      → Initialize WiFi driver
2. esp_wifi_set_mode()  → Choose STA, AP, or STA+AP
3. esp_wifi_set_config()→ Set SSID and password
4. esp_wifi_start()     → Start WiFi hardware
5. esp_wifi_connect()   → Begin connection (STA mode)
       ↓
   [Scanning for SSID]
       ↓
   [Association with AP]
       ↓
   [WPA2 4-way handshake]
       ↓
   [DHCP IP acquisition]
       ↓
   WIFI_EVENT_STA_CONNECTED (callback fires)

Connection typically takes 2-5 seconds. During this time, your code should show a “connecting” state (e.g., blinking LED).

HTTP Protocol Basics

HTTP (Hypertext Transfer Protocol) is the foundation of web communication. Your ESP32 will act as an HTTP server, responding to requests from web browsers.

Request/Response Model

Browser                                    ESP32
   │                                         │
   │───── GET / HTTP/1.1 ───────────────────→│
   │      Host: 192.168.1.150                │
   │                                         │
   │←──── HTTP/1.1 200 OK ──────────────────│
   │      Content-Type: text/html            │
   │      Content-Length: 3245               │
   │                                         │
   │      <html>...</html>                   │
   │                                         │

Common HTTP Methods

Method	Purpose	Example
GET	Retrieve data	Load web page
POST	Send data	Submit form
PUT	Update data	Update sensor config
DELETE	Remove data	Clear logs

For this project, you’ll primarily use GET to serve the dashboard and a JSON API endpoint.

Non-Volatile Storage (NVS)

NVS is ESP32’s key-value storage system designed for flash memory. Unlike RAM, NVS data survives reboots and power cycles.

Flash Memory Characteristics

Flash Memory Structure:
┌─────────────────────────────────────────────────────┐
│ Sector 0 │ Sector 1 │ Sector 2 │ ... │ Sector N    │
│  (4KB)   │  (4KB)   │  (4KB)   │     │   (4KB)     │
└─────────────────────────────────────────────────────┘

- Write: Can only change 1→0 (not 0→1)
- Erase: Must erase entire sector (all bits→1)
- Endurance: ~100,000 erase cycles per sector

Why NVS instead of raw flash: NVS handles wear leveling automatically, spreading writes across multiple sectors to extend flash lifetime.

NVS Namespaces and Keys

// Open namespace "sensor_data"
nvs_open("sensor_data", NVS_READWRITE, &handle);

// Write key-value pairs
nvs_set_float(handle, "last_temp", 22.3);
nvs_set_i32(handle, "reading_count", 1542);

// Commit changes to flash
nvs_commit(handle);

Best Practice: Batch multiple writes and commit once to reduce flash wear.

FreeRTOS Tasks

ESP32 runs FreeRTOS, a real-time operating system that enables concurrent execution through tasks. Each task is like a separate program running simultaneously.

Task Lifecycle

                    ┌─────────┐
        create      │ Created │
     ─────────────→ └────┬────┘
                         │ start
                         ▼
                    ┌─────────┐
    ┌──────────────→│  Ready  │←─────────────┐
    │               └────┬────┘              │
    │                    │ scheduler picks   │ preempted
    │                    ▼                   │
    │               ┌─────────┐              │
    │               │ Running │──────────────┘
    │               └────┬────┘
    │                    │ wait/delay
    │                    ▼
    │               ┌─────────┐
    └───────────────│ Blocked │ (waiting for event/time)
                    └─────────┘

Task Priorities

Higher priority tasks preempt lower priority tasks. For this project:

High Priority: WiFi handling (networking is time-sensitive)
Medium Priority: HTTP server (respond quickly to requests)
Low Priority: Sensor reading (can tolerate delays)

Project Specification

Hardware Requirements

Component	Quantity	Purpose
ESP32 DevKit	1	Main microcontroller
BME280 Sensor	1	Temperature, humidity, pressure
Breadboard	1	Prototyping
Jumper Wires	6+	Connections
LED (optional)	1	WiFi status indicator
220Ω Resistor	1	LED current limiting

Wiring Diagram

ESP32 DevKit                    BME280
┌─────────────┐                ┌────────┐
│        3.3V │────────────────│ VCC    │
│         GND │────────────────│ GND    │
│      GPIO21 │────────────────│ SDA    │
│      GPIO22 │────────────────│ SCL    │
│             │                │ CSB    │──── VCC (I2C mode)
│             │                │ SDO    │──── GND (addr 0x76)
│             │                └────────┘
│             │
│       GPIO2 │────[220Ω]────LED────GND
│             │
└─────────────┘

Functional Requirements

Sensor Reading
- Read temperature, humidity, and pressure every 10 seconds
- Support both BME280 (I2C) and DHT22 (GPIO) sensors
- Handle sensor initialization failures gracefully
WiFi Connectivity
- Connect to configured WiFi network on startup
- Automatically reconnect on disconnection
- Indicate connection status via LED
Web Dashboard
- Serve HTML dashboard on port 80
- Display current sensor readings
- Show 24-hour historical data graph
- Auto-refresh every 5 seconds via JavaScript
Data Logging
- Store readings in NVS every 10 seconds
- Maintain 72 hours of historical data
- Implement circular buffer to prevent flash exhaustion
API Endpoints
- GET / - HTML dashboard
- GET /api/readings - Current readings (JSON)
- GET /api/history - Historical data (JSON)

Solution Architecture

System Block Diagram

┌─────────────────────────────────────────────────────────────────┐
│                         ESP32 System                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐      │
│  │   Sensor     │    │    WiFi      │    │    HTTP      │      │
│  │    Task      │    │   Manager    │    │   Server     │      │
│  │              │    │              │    │              │      │
│  │ - Read I2C   │    │ - Connect    │    │ - Route /    │      │
│  │ - Update     │───→│ - Reconnect  │    │ - Route /api │      │
│  │   globals    │    │ - Events     │    │ - Serve HTML │      │
│  └──────────────┘    └──────────────┘    └──────────────┘      │
│         │                                       │               │
│         ▼                                       ▼               │
│  ┌──────────────┐                      ┌──────────────┐        │
│  │   Global     │←─────────────────────│    JSON      │        │
│  │   Sensor     │                      │  Generator   │        │
│  │    Data      │                      └──────────────┘        │
│  └──────────────┘                                               │
│         │                                                       │
│         ▼                                                       │
│  ┌──────────────┐                                               │
│  │    NVS       │                                               │
│  │   Storage    │                                               │
│  │              │                                               │
│  │ - Save every │                                               │
│  │   10 seconds │                                               │
│  │ - Circular   │                                               │
│  │   buffer     │                                               │
│  └──────────────┘                                               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Data Flow

1. Sensor Task (every 10s):
   BME280 → I2C Read → Parse Raw Data → Apply Calibration → Update Global

2. Storage Flow:
   Global Data → Format → NVS Write (with index rotation)

3. HTTP Request Flow:
   Browser → GET /api/readings → Read Global → JSON Format → Response

4. Dashboard Flow:
   Browser → GET / → Serve HTML → JavaScript fetch() → Update DOM

Key Data Structures

// Sensor reading structure
typedef struct {
    float temperature;    // Celsius
    float humidity;       // Percentage
    float pressure;       // hPa
    uint32_t timestamp;   // Unix timestamp
} sensor_reading_t;

// Global state
typedef struct {
    sensor_reading_t current;
    bool wifi_connected;
    uint32_t uptime_seconds;
    uint32_t readings_stored;
} system_state_t;

// NVS storage uses circular buffer with index
// Key format: "rd_0000" to "rd_8639" (24h * 360 readings/hour)

Phased Implementation Guide

Phase 1: Hardware Verification (Day 1)

Goal: Verify ESP32 and sensor are working

Blink LED Test
- Write simple blink program
- Verify upload and serial monitor work
- If LED doesn’t blink: Check COM port, board selection, boot mode
I2C Scanner
- Scan I2C bus for devices
- BME280 should appear at 0x76 or 0x77
- If not found: Check wiring, pull-up resistors, sensor power
Sensor Raw Reading
- Use BME280 library to read values
- Print to serial monitor
- Verify readings are reasonable (not 0 or NaN)

Checkpoint: Serial monitor shows valid temperature/humidity readings

Phase 2: WiFi Connection (Day 2-3)

Goal: Reliable WiFi with reconnection handling

Basic Connection
- Connect to WiFi with hardcoded credentials
- Print IP address on success
- Add LED indication (blink while connecting, solid when connected)
Event Handling
- Register WiFi event handlers
- Handle disconnection events
- Implement reconnection logic with exponential backoff
Robustness Testing
- Power cycle router while ESP32 is connected
- Verify automatic reconnection
- Test with wrong password (should report error, not hang)

Checkpoint: ESP32 maintains WiFi connection through router restarts

Phase 3: HTTP Server (Day 4-5)

Goal: Serve web content from ESP32

Minimal Server
- Start HTTP server on port 80
- Serve “Hello World” on root path
- Access from browser using ESP32’s IP
Static HTML Dashboard
- Create HTML template with placeholder values
- Embed HTML in C code using raw string literals
- Serve complete HTML page
API Endpoint
- Add /api/readings route
- Return JSON with current sensor values
- Test with curl command
Auto-Refresh
- Add JavaScript to dashboard
- Fetch from API every 5 seconds
- Update DOM without page reload

Checkpoint: Dashboard shows live sensor data updating automatically

Phase 4: Data Persistence (Day 6-7)

Goal: Store and retrieve historical data

NVS Basics
- Open NVS namespace
- Write and read test values
- Verify data survives reboot
Circular Buffer
- Implement index rotation (0-8639)
- Store readings with timestamp keys
- Handle wraparound gracefully
History API
- Add /api/history endpoint
- Return last 24 hours of data
- Format as JSON array
Dashboard Graph
- Add simple ASCII or Canvas graph
- Fetch history data on page load
- Display temperature trend

Checkpoint: Dashboard shows 24-hour temperature graph that persists across reboots

Phase 5: Polish and Testing (Day 8+)

Goal: Production-ready behavior

Error Handling
- Handle sensor read failures
- Handle NVS full condition
- Add watchdog timer for recovery
Memory Optimization
- Check heap usage with esp_get_free_heap_size()
- Ensure no memory leaks over time
- Optimize HTML/JSON string handling
Configuration
- Move WiFi credentials to NVS
- Add configuration page for settings
- Store sensor calibration offsets

Testing Strategy

Unit Tests

Component	Test	Expected Result
I2C	Scan for device at 0x76	Device found
Sensor	Read temperature	15-35°C (room temp)
WiFi	Connect with correct password	IP assigned
WiFi	Connect with wrong password	Error event
HTTP	GET /	200 OK + HTML
HTTP	GET /api/readings	Valid JSON
NVS	Write then read	Same value

Integration Tests

Long-Running Stability
- Run for 24 hours minimum
- Monitor heap usage (should be stable)
- Check for WiFi disconnection/reconnection events
Power Cycle Recovery
- Store some data
- Power off/on
- Verify data is still accessible
Multi-Client Access
- Open dashboard from multiple devices
- All should see same data
- No crashes or hangs

Performance Benchmarks

Metric	Target	How to Measure
Sensor read time	< 100ms	`esp_timer_get_time()`
HTTP response time	< 50ms	Browser dev tools
NVS write time	< 10ms	Timer around nvs_commit
Memory usage	< 100KB heap	`esp_get_free_heap_size()`

Common Pitfalls and Debugging

I2C Issues

Problem: Sensor not detected

Check wiring (SDA to GPIO21, SCL to GPIO22)
Verify 3.3V power to sensor
Try both addresses (0x76 and 0x77)
Add pull-up resistors if using long wires

Problem: Garbage readings

Check I2C clock speed (start with 100kHz)
Verify sensor is genuine (counterfeit BME280s exist)
Add delay after sensor power-on (100ms)

WiFi Issues

Problem: Connection fails immediately

Verify SSID and password are correct (case-sensitive)
Check router isn’t at device limit
Try static IP if DHCP fails

Problem: Frequent disconnections

Check signal strength (WiFi.RSSI())
Reduce distance to router
Check for 2.4GHz interference

HTTP Server Issues

Problem: Browser can’t connect

Verify ESP32 IP address
Check firewall on computer
Ensure server started successfully

Problem: Partial page loads

Increase HTTP response buffer size
Check for memory exhaustion
Split large pages into smaller chunks

Memory Issues

Problem: Crash after running for hours

Memory leak in HTTP handlers (forgetting to free JSON strings)
Stack overflow in tasks (increase stack size)
Use heap tracing to find leaks

Extensions and Challenges

Beginner Extensions

Multi-Room Monitoring
- Add second sensor on different I2C address
- Show both locations on dashboard
Email Alerts
- Send email when temperature exceeds threshold
- Use SMTP library or webhook service
CSV Export
- Add button to download data as CSV
- Implement streaming response for large files

Intermediate Challenges

mDNS Discovery
- Register as envmonitor.local
- Access without knowing IP address
HTTPS Support
- Generate self-signed certificate
- Enable TLS on HTTP server
MQTT Integration
- Publish readings to MQTT broker
- Compatible with Home Assistant

Advanced Challenges

Custom PCB Design
- Design PCB with ESP32 module
- Add battery charging circuit
- Weatherproof enclosure for outdoor use
Machine Learning
- Train model to predict temperature trends
- Run inference on ESP32 (TensorFlow Lite Micro)
Mesh Network
- Multiple sensors using ESP-NOW
- One hub aggregates all data

Real-World Connections

Industry Applications

Industry	Application	Your Project Skill
Smart Buildings	HVAC monitoring	Sensor + WiFi
Agriculture	Greenhouse control	Environmental sensing
Cold Chain	Food transport monitoring	Data logging
Data Centers	Server room monitoring	Web dashboard

Commercial Products Using Similar Technology

Ecobee Thermostat: Environmental sensing + WiFi + cloud
AirThings Wave: Air quality monitoring with web dashboard
Nest Temperature Sensors: Battery-powered I2C sensors

Career Paths

Skills from this project apply to:

IoT Developer: Building connected devices
Embedded Systems Engineer: Low-level firmware development
Full-Stack IoT: Device + Cloud + Mobile app development

Resources

Official Documentation

Resource	URL
ESP-IDF GPIO API	docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/gpio.html
ESP-IDF I2C API	docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/i2c.html
ESP-IDF WiFi API	docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_wifi.html
ESP-IDF NVS API	docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/storage/nvs_flash.html

Books

Book	Author	Relevant Chapters
Making Embedded Systems, 2nd Ed	Elecia White	Ch. 5, 6, 10
IoT Product Development Using ESP32	Sai Yamanoor	WiFi chapter
HTTP: The Definitive Guide	David Gourley	Ch. 1-3

Libraries

Library	Purpose	Platform
Adafruit BME280	Sensor driver	Arduino
ESPAsyncWebServer	HTTP server	Arduino
ArduinoJson	JSON handling	Arduino
cJSON	JSON handling	ESP-IDF

Self-Assessment Checklist

Fundamentals

I can explain how I2C addressing works
I understand the difference between WiFi STA and AP modes
I can describe how HTTP GET requests work
I know why NVS uses wear leveling

Implementation

My sensor reads are accurate within ±1°C
WiFi reconnects automatically after router restart
Dashboard updates without page refresh
Data persists across power cycles

Code Quality

No compiler warnings
Heap usage is stable over 24 hours
Error conditions are handled gracefully
Code is organized into logical functions

Understanding

I can modify the sensor reading interval without bugs
I can add a new API endpoint
I understand why we use FreeRTOS tasks
I can explain the data flow from sensor to browser

Interview Preparation

Be ready to answer these questions:

“Explain how I2C communication works. What are the key signals?”
- SDA (data), SCL (clock), start/stop conditions, addressing, ACK/NACK
“Why use I2C instead of SPI for the BME280 sensor?”
- I2C uses 2 wires vs 4+ for SPI; I2C is simpler for short distances
“How does WiFi station mode differ from access point mode?”
- Station connects to existing WiFi; AP creates WiFi hotspot
“What is NVS and why not use a regular file system?”
- NVS is key-value storage optimized for flash wear leveling
“How would you handle WiFi disconnection gracefully?”
- Retry with exponential backoff, blink LED, continue sensor logging offline
“What is the ESP32’s ADC resolution and voltage range?”
- 12-bit (0-4095), 0-3.3V with 11dB attenuation

Next Project: P02-ble-remote-control.md - Bluetooth Low Energy Remote Control