readme.md
Markdown · 120 lines
# ESP8266 Keypad Captive Portal (HX-543 3x4)

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