Library patches
What you'll learn
- Where Arduino libraries live, and how to patch one safely
- Why two display pins had to move off the ESP32's "strapping" pins
- How the secret-wiping patch removes seeds and keys from memory
Two of the libraries need small changes before the firmware compiles and runs safely. Each change is a few lines. This page shows them all.
Before you start
Section titled “Before you start”Find your libraries folder. It’s the libraries folder inside your Arduino sketchbook. On the tested Windows setup, that is Documents\Arduino\libraries. The Arduino IDE shows the sketchbook location in File → Preferences.
Keep a copy of each original file. Before editing a file, copy it next to itself with .orig added to its name, for example mcufriend_shield.h.orig. Then you can always see, or undo, exactly what you changed.
The diffs below show lines removed with - and lines added with +. The comments on the added lines are part of the patch; keep them, so you can find the patched lines later.
The firmware repository includes the already-patched library files, if you’d rather copy them than edit by hand, and the full patch notes in docs/patches.md: [REPO LINK]
MCUFRIEND_kbv (the display driver)
Section titled “MCUFRIEND_kbv (the display driver)”All three display patches are in one file: MCUFRIEND_kbv/utility/mcufriend_shield.h, in the ESP32 section around line 1025.
Patch 1: a missing header
Section titled “Patch 1: a missing header”What breaks without it: the firmware doesn’t compile. The error is 'GPIO' was not declared in this scope.
Why: the ESP32 core 3.3.10 is built on ESP-IDF 5, which no longer includes this header automatically.
Patch 2: the read pin moves from GPIO2 to GPIO21
Section titled “Patch 2: the read pin moves from GPIO2 to GPIO21”What breaks without it: with the shield wired, uploads to the DevKit fail with Failed to connect to ESP32: No serial data received, unless you hold the BOOT button.
Why: GPIO2 is a strapping pin. The ESP32 checks a few such pins at the moment it starts, to decide how to boot. GPIO2 must be low or floating to enter upload mode, but the shield’s read line sits high.
Patch 3: data bit 0 moves from GPIO12 to GPIO22
Section titled “Patch 3: data bit 0 moves from GPIO12 to GPIO22”What breaks without it: the DevKit sometimes fails to boot, and loops through resets with errors such as Failed to verify partition table and invalid header: 0xffffffff.
Why: GPIO12 is another strapping pin. At reset it sets the voltage of the flash memory chip. The shield pulls it high, so the ESP32 runs its flash at 1.8V instead of 3.3V and reads garbage. It’s intermittent, which makes it confusing.
Here are patches 1, 2 and 3 together:
#elif defined(ESP32) //regular UNO shield on TTGO D1 R32 (ESP32)#define LCD_RD 2 //LED#include "soc/gpio_struct.h" // airgap_signer patch: ESP-IDF 5 no longer includes this implicitly#define LCD_RD 21 // airgap_signer patch: was 2 (strapping pin; the shield held it high and blocked auto-download)#define LCD_WR 4#define LCD_RS 15 //hard-wired to A2 (GPIO35)#define LCD_RST 32 //hard-wired to A4 (GPIO36)
#define LCD_D0 12#define LCD_D0 22 // airgap_signer patch: was 12 (MTDI strapping pin; shield pulled it high -> 1.8V flash -> boot failures)#define LCD_D1 13#define LCD_D2 26uBitcoin (the Bitcoin library)
Section titled “uBitcoin (the Bitcoin library)”Patch 4: a moved function
Section titled “Patch 4: a moved function”What breaks without it: the firmware doesn’t compile. The error is implicit declaration of function 'esp_random'.
Why: in ESP-IDF 5, the function that reads the chip’s random number generator moved to a different header.
#include <esp_system.h>#include <esp_random.h> // airgap_signer patch: esp_random() moved here in ESP-IDF 5uint32_t __attribute__((weak)) random32(void){ return esp_random();Patch 5: wipe secrets from memory
Section titled “Patch 5: wipe secrets from memory”What breaks without it: nothing you’d notice, and that’s the danger. The firmware works, but copies of your seed and private keys are left behind in the chip’s memory after use.
Why it matters. When a program computes something, it uses scratch space in memory. Normally that space is simply reused later, with the old contents still there until something overwrites them. uBitcoin computed the seed, the master key and child keys in scratch space, and left them there. This patch adds a “wipe” (overwrite with zeros) at the end of each of those calculations. It only adds wiping: no result changes.
What patch 5 wipes, file by file:
src/HDWallet.cppHDPrivateKey::fromMnemonic(): the BIP39 seed, and a working block of the seed calculationHDPrivateKey::fromSeed(): the master private key and chain codeHDPrivateKey::child(): the parent private key, and the child’s key material
src/Bitcoin.cppmnemonicToEntropy(): the entropy (the seed’s raw random bits)
src/utility/trezor/bip39.cmnemonic_to_entropy(): a seed word, and the entropymnemonic_check(): the entropy, and its hash
src/utility/trezor/options.hUSE_BIP39_CACHE: turns off a cache that could hold mnemonics, passphrases and seeds
src/utility/trezor/memzero.cmemzero(): the wipe function itself, made impossible for the compiler to skip
Two of the changes, as examples. In HDWallet.cpp, the seed and the working block are wiped before the function returns:
fromSeed(seed, sizeof(seed), net); memzero(seed, sizeof(seed)); // airgap_signer patch 7: BIP39 seed memzero(u, sizeof(u)); // airgap_signer patch 7: PBKDF2 working block return 1;}And the wipe function is rewritten, so that an optimising compiler can’t decide the zeros are pointless and remove them:
// airgap_signer patch 7: was memset(s, 0, n). Writing through a volatile// pointer guarantees the stores happen even if the compiler (or LTO) can see// that the memory is never read again.void memzero(void *s, size_t n){ memset(s, 0, n); volatile unsigned char *p = (volatile unsigned char *)s; while (n--) { *p++ = 0; }}The other changes follow the same pattern. In bip39.c, the functions are rearranged to have a single exit, so the wipe runs on every path. In options.h, USE_BIP39_CACHE changes from 1 to 0. Every changed line is marked airgap_signer patch 7, the number this patch has in the firmware’s patch notes. For the complete bip39.c changes, copy the patched file from the firmware repository (link at the top of this page), or follow the firmware’s patch notes (docs/patches.md).
Before you continue
Section titled “Before you continue”mcufriend_shield.hhas patches 1, 2 and 3, and its.origcopy is saved.rand.chas patch 4.- The five uBitcoin files listed under patch 5 have their changes, each with an
.origcopy. - You haven’t updated either library since patching.