readme.md

Markdown · 120 lines

# ESP8266 Keypad Captive Portal (HX-543 3x4)

![Example usage](https://i.imgur.com/VusZoHB.png "Example usage")

This project turns an ESP8266 (NodeMCU / Wemos D1 mini) into an **open Wi-Fi Access Point** with a **captive portal** (no login page) that displays the **last pressed key** from a **3x4 membrane keypad**.

The keypad used here is labeled **HX-543**.

---

## Features

- Open Wi-Fi AP (no password) for quick access
- Captive portal using DNS wildcard (redirects any domain to ESP8266)
- Web dashboard (`/`) showing the last pressed key
- JSON endpoint (`/data`) for live updates
- Non-blocking keypad scanning (fast response)

---

## Hardware

- ESP8266 (NodeMCU / Wemos D1 mini recommended)
- 3x4 membrane keypad labeled **HX-543**
- Jumper wires / breadboard

---

## Important HX-543 wiring note (cable orientation)

On the **HX-543** keypad ribbon connector there is a printed marking **"7"** near one side of the connector.

**IMPORTANT:**
- Start plugging from ESP8266 pin **D1** at the ribbon pin closest to the printed **"7"** marking.
- In other words: **D1 must be connected to the keypad ribbon pin at the side where "7" is printed.**

This ensures the pin order matches the mapping used in the code.

---

## Wiring (recommended mapping)

Keypad has 7 lines total: **4 rows + 3 columns**.
This project uses the following ESP8266 pins (NodeMCU labels):

Rows:
- R1 -> D1 (GPIO5)
- R2 -> D2 (GPIO4)
- R3 -> D5 (GPIO14)
- R4 -> D6 (GPIO12)

Columns:
- C1 -> D7 (GPIO13)
- C2 -> D3 (GPIO0)
- C3 -> D4 (GPIO2)

### Notes about ESP8266 boot pins

Pins **D3 (GPIO0)** and **D4 (GPIO2)** are boot strap pins.
If you get boot issues, move columns to safer pins (for example D7/D5/D6/D8) and update the pin arrays in code.

---

## Software Requirements

- Arduino IDE (or PlatformIO)
- ESP8266 board support installed in Arduino IDE

### Libraries

Install via Arduino Library Manager:
- Keypad (by Mark Stanley, Alexander Brevig)

Built-in with ESP8266 Arduino core:
- ESP8266WiFi
- ESP8266WebServer
- DNSServer

---

## How to Use

1. Flash the firmware to the ESP8266.
2. Power the board.
3. Connect your phone/PC to the Wi-Fi network:
   - SSID: `Keypad-Portal`
4. The captive portal should open automatically.
   - If it does not, open: `http://192.168.4.1/`
5. Press keys on the HX-543 keypad and watch the last pressed key update on the page.

---

## Endpoints

- GET `/`     : web UI
- GET `/data` : JSON with last key and age in milliseconds

Example JSON:
{
  "last_key": "5",
  "age_ms": 120
}

---

## Troubleshooting

- If the displayed key is wrong:
  - verify the ribbon orientation rule: **D1 starts at the "7" marking**
  - verify the keypad line order matches the code mapping
- If the ESP8266 sometimes fails to boot:
  - avoid using D3/D4 for keypad lines and remap to safer pins
- If the portal does not pop up:
  - open `http://192.168.4.1/` manually

---

## License

MIT