Skip to content

Library patches

Time
30 min
Difficulty
Medium

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.

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]

All three display patches are in one file: MCUFRIEND_kbv/utility/mcufriend_shield.h, in the ESP32 section around line 1025.

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:

MCUFRIEND_kbv/utility/mcufriend_shield.h
#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)
MCUFRIEND_kbv/utility/mcufriend_shield.h (a few lines further down)
#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 26

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.

uBitcoin/src/utility/trezor/rand.c
#include <esp_system.h>
#include <esp_random.h> // airgap_signer patch: esp_random() moved here in ESP-IDF 5
uint32_t __attribute__((weak)) random32(void){
return esp_random();

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.cpp
    • HDPrivateKey::fromMnemonic(): the BIP39 seed, and a working block of the seed calculation
    • HDPrivateKey::fromSeed(): the master private key and chain code
    • HDPrivateKey::child(): the parent private key, and the child’s key material
  • src/Bitcoin.cpp
    • mnemonicToEntropy(): the entropy (the seed’s raw random bits)
  • src/utility/trezor/bip39.c
    • mnemonic_to_entropy(): a seed word, and the entropy
    • mnemonic_check(): the entropy, and its hash
  • src/utility/trezor/options.h
    • USE_BIP39_CACHE: turns off a cache that could hold mnemonics, passphrases and seeds
  • src/utility/trezor/memzero.c
    • memzero(): 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:

uBitcoin/src/HDWallet.cpp (in HDPrivateKey::fromMnemonic)
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:

uBitcoin/src/utility/trezor/memzero.c
// 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).

  • mcufriend_shield.h has patches 1, 2 and 3, and its .orig copy is saved.
  • rand.c has patch 4.
  • The five uBitcoin files listed under patch 5 have their changes, each with an .orig copy.
  • You haven’t updated either library since patching.