readme.md

Markdown · 289 lines

# ESP8266 DHT22 Captive Portal (Temperature & Humidity)

This project turns an ESP8266 into an open Wi-Fi Access Point with a captive portal and a simple web UI that displays live temperature and humidity readings from a DHT22 / AM2302 sensor.

When a phone or laptop connects to the ESP8266 AP, it should be redirected to the portal automatically. The portal shows:

- Temperature (°C)
- Humidity (%)
- Data age, in milliseconds since the last sensor read

## Features

- Open Wi-Fi AP, no password by default
- Captive portal using DNS wildcard
- Web dashboard at /
- JSON endpoint at /data
- DHT22 polling with safe interval, minimum 2 seconds
- Minimal lightweight UI with 1 second auto-refresh
- Captive portal compatibility routes for Android, iOS/macOS, and Windows

## Hardware

- ESP8266 development board, for example:
  - NodeMCU ESP8266
  - Wemos / LOLIN D1 mini
  - ESP-12E / ESP-12F based board
- DHT22 / AM2302 temperature and humidity sensor

## Wiring

### NodeMCU / Wemos D1 mini

| DHT22 Pin | ESP8266 |
|----------:|:--------|
| VCC       | 3V3     |
| DATA      | D2 / GPIO4 |
| GND       | GND     |

The code uses:

    #define DHT_PIN 4

On most NodeMCU and Wemos D1 mini boards, GPIO4 = D2.

You can also use the board pin alias:

    #define DHT_PIN D2

## Notes

- Use 3.3V with ESP8266.
- Do not connect the DHT22 data line directly to 5V logic.
- Most 3-pin DHT22 modules already include a pull-up resistor.
- If you use a bare 4-pin DHT22 sensor, add a 4.7k–10k pull-up resistor between VCC and DATA.
- Keep sensor wires short if readings are unstable.

## Software Requirements

- Arduino IDE or PlatformIO
- ESP8266 board support:
  - ESP8266 by ESP8266 Community

In Arduino IDE, install it via:

    File → Preferences → Additional Boards Manager URLs

Add:

    http://arduino.esp8266.com/stable/package_esp8266com_index.json

Then go to:

    Tools → Board → Boards Manager

Install:

    esp8266 by ESP8266 Community

Recommended board selections:

- NodeMCU 1.0 (ESP-12E Module)
- LOLIN(WEMOS) D1 R2 & mini

## Libraries

Install via Arduino Library Manager:

- DHT sensor library by Adafruit
- Adafruit Unified Sensor

Tested with:

    {
      "libraries": [
        {
          "name": "DHT sensor library",
          "version": "1.4.6"
        },
        {
          "name": "Adafruit Unified Sensor",
          "version": "1.1.15"
        }
      ]
    }

Built into the ESP8266 Arduino core:

    #include <ESP8266WiFi.h>
    #include <ESP8266WebServer.h>
    #include <DNSServer.h>

## Important ESP8266 Differences

This project was originally written for ESP32. For ESP8266, these includes/classes are different.

ESP32:

    #include <WiFi.h>
    #include <WebServer.h>

    WebServer webServer(80);

ESP8266:

    #include <ESP8266WiFi.h>
    #include <ESP8266WebServer.h>

    ESP8266WebServer webServer(80);

## How to Use

1. Flash the firmware to your ESP8266.
2. Power the ESP8266.
3. Connect your phone or computer to the Wi-Fi network:

       DHT22-Portal

4. The captive portal should open automatically.
5. If it does not open automatically, open a browser and go to:

       http://192.168.4.1/

6. Read temperature and humidity live on the web page.

## Configuration

Edit these constants in the sketch:

    static const char* AP_SSID = "DHT22-Portal";
    static const char* AP_PASS = "";

Leave AP_PASS empty for an open Wi-Fi network.

If you want to use a password, it must have at least 8 characters:

    static const char* AP_PASS = "12345678";

DHT22 pin:

    #define DHT_PIN 4

Default:

    GPIO4 / D2

Read interval:

    static const unsigned long READ_INTERVAL_MS = 2000;

Do not set this below 2000 ms, because DHT22 should not be read more often than every 2 seconds.

## Endpoints

### Web UI

    GET /

Shows the live dashboard.

### JSON data

    GET /data

Example response:

    {
      "temp_c": 23.4,
      "hum": 51.2,
      "age_ms": 842
    }

Fields:

| Field | Type | Description |
|------:|:-----|:------------|
| temp_c | number or null | Temperature in °C |
| hum | number or null | Humidity in % |
| age_ms | number | Milliseconds since last sensor read |

## Captive Portal Routes

The firmware handles common captive portal test paths, including:

    /generate_204
    /gen_204
    /hotspot-detect.html
    /library/test/success.html
    /ncsi.txt
    /connecttest.txt

Unknown paths are redirected to:

    http://192.168.4.1/

## Troubleshooting

### Always shows N/A

Check:

- DHT22 VCC is connected to 3.3V
- DHT22 GND is connected to GND
- DATA is connected to the configured pin
- The configured pin matches your board wiring
- Pull-up resistor is present if using a bare sensor

For NodeMCU / Wemos D1 mini:

    #define DHT_PIN 4

means:

    D2 / GPIO4

### Random or unstable readings

Try:

- Add a 4.7k–10k pull-up resistor between DATA and 3.3V
- Use shorter wires
- Make sure the read interval is at least 2 seconds
- Power the sensor from stable 3.3V

### Portal does not open automatically

Open manually:

    http://192.168.4.1/

Some devices do not always show captive portals automatically, especially if mobile data, VPN, or private DNS is enabled.

### Cannot connect to AP with password

ESP8266 Wi-Fi AP password must be at least 8 characters.

This is valid:

    static const char* AP_PASS = "12345678";

This is invalid:

    static const char* AP_PASS = "1234";

### Compilation error: WiFi.h: No such file or directory

You are compiling ESP8266 code with the wrong board/core or ESP32-style includes.

Use:

    #include <ESP8266WiFi.h>
    #include <ESP8266WebServer.h>

and select an ESP8266 board in Arduino IDE.

### Compilation error: WebServer.h: No such file or directory

WebServer.h is for ESP32.

For ESP8266 use:

    #include <ESP8266WebServer.h>

and:

    ESP8266WebServer webServer(80);

## License

MIT