Fixing the PUYA flash chip crash on ESP-01 modules

If you have ever flashed a program to a cheap ESP-01 WiFi module and had it crash with a Flash read error or corrupt the settings you just saved, you may have met the infamous PUYA flash chip. Some ESP-01 modules ship with a PUYA PY25Q64 flash chip instead of the usual Gigadevice or Winbond chips. That chip has a hardware quirk: before you can overwrite data, you must erase a full sector, and the stock ESP8266 Arduino core did not do that correctly on these chips.

What this repository is

github.com/bobhuang1/esp8266-FixPUYAChip is a tiny repository — essentially one patched file, Esp.cpp — that replaces the same file inside the ESP8266 Arduino core. The patch adds the sector-erase handling the PUYA chips require, so writing to flash becomes safe on those modules.

How to use it, step by step

1. Find your Arduino ESP8266 core installation. On Windows it is usually C:\Users\you\AppData\Local\Arduino15\packages\esp8266\hardware\esp8266\<version>\cores\esp8266\.
2. Back up the original Esp.cpp (rename it Esp.cpp.bak).
3. Copy the Esp.cpp from the repository over it.
4. Restart the Arduino IDE and recompile your sketch.

Because this modifies the core itself, you must re-apply it whenever the ESP8266 core updates — that is exactly the same trade-off as my ST7565 display patch.

How do you know you have a PUYA chip?

Run a flash-dump utility or read the chip ID at boot; PUYA chips report a distinctive manufacturer ID. In practice, most people discover it from the symptoms: a sketch that runs fine until it writes settings, then reboots. If your ESP-01 is recent and cheap, suspect PUYA.

What a beginner should learn from this

Embedded development often means reading the source of the platform itself. The Arduino core is just C++ on your disk. When hardware misbehaves, the fix may be a two-line change in code you did not write — but only if you are willing to open it. This repository is one of the smallest on my GitHub account, and also one of the most useful.