Skip to content

Software setup

Time
30–45 min
Difficulty
Easy

What you'll learn

  • What the Arduino IDE is, and how it compiles and uploads firmware
  • How to install an exact version of the ESP32 core and each library
  • Why upgrading a version can break the build

The firmware is written in Arduino-style C++. You compile it on your computer and upload it to the boards with the Arduino IDE, Arduino’s free code editor. Its Verify button compiles a sketch, and its Upload button compiles it and sends it to the board.

Use exactly these versions. The library patches in the next step were written for them.

Software Version
ESP32 core (esp32 by Espressif Systems) 3.3.10
MCUFRIEND_kbv 3.0.0-Release
uBitcoin 0.2.0
Adafruit GFX Library 1.12.6
Adafruit TouchScreen 1.1.6
Adafruit BusIO 1.17.4
Sparrow Wallet 2.5.5

Download the Arduino IDE 2 from the official software page and install it. On Windows there is an installer.

The IDE needs to know where Espressif publishes the ESP32 core.

  1. Open File → Preferences.

  2. In Additional boards manager URLs, paste:

    https://espressif.github.io/arduino-esp32/package_esp32_index.json
  3. Click OK.

  4. Open the Boards Manager (Tools → Board → Boards Manager…, or the board icon in the left sidebar).

  5. Search for esp32. In the entry esp32 by Espressif Systems, choose version 3.3.10 from the version list, then click Install.

When it has finished, the entry shows 3.3.10 installed.

Open the Library Manager (Tools → Manage Libraries…, or the books icon in the left sidebar). For each library below, search for its name, choose the exact version from the version list, and click Install:

Library Version
MCUFRIEND_kbv 3.0.0-Release
uBitcoin 0.2.0
Adafruit GFX Library 1.12.6
Adafruit TouchScreen 1.1.6
Adafruit BusIO 1.17.4

If the IDE asks whether to install a library’s dependencies too, choose the option that installs only the library you picked, then install the others from the table yourself, so each one is at the right version.

What each one does:

  • MCUFRIEND_kbv drives the touch shield’s display.
  • Adafruit GFX Library draws text and shapes on it. Adafruit BusIO is a helper it needs.
  • Adafruit TouchScreen reads the shield’s resistive touch panel.
  • uBitcoin does the Bitcoin work: seeds, keys, addresses, PSBTs and signing.

The QR-code generator and the QR decoder aren’t installed as libraries. Their code is copied into the firmware itself, so you don’t need to do anything for them.

Download or clone the firmware repository: [REPO LINK]

It contains two sketches (Arduino projects), one for each board. Open each one with File → Open…, and pick the matching board under Tools → Board → esp32:

Folder Board Board to select in the IDE
airgap_wallet/ ESP32 DevKit (the signer) ESP32 Dev Module
airgap_qrcam/ ESP32-CAM (the scanner) AI Thinker ESP32-CAM

The board you select tells the IDE which chip and settings to compile for. Leave the other settings in the Tools menu at their defaults, except the one the flashing steps mention.

5. Check the IDE can compile for both boards

Section titled “5. Check the IDE can compile for both boards”

Before patching anything, prove that the IDE can compile for both boards, using an empty sketch:

  1. Open File → New Sketch.
  2. Select Tools → Board → esp32 → ESP32 Dev Module, then click Verify (the tick button).
  3. Select Tools → Board → esp32 → AI Thinker ESP32-CAM, then click Verify again.

Each time, the Output panel at the bottom should end with a line like Sketch uses … bytes (…%) of program storage space. In testing, the empty sketch used about 20% of the DevKit’s flash. You don’t need to save the empty sketch.

Install Sparrow Wallet on your computer. It was tested with version 2.5.5. Note that Sparrow starts on mainnet (the real network) unless told otherwise. A later step shows how to start it on signet, so don’t create a wallet in it yet.

  • The Arduino IDE is installed.
  • The Boards Manager shows esp32 by Espressif Systems at 3.3.10 installed.
  • The five libraries are installed at the versions above.
  • The empty sketch compiles for ESP32 Dev Module and AI Thinker ESP32-CAM.
  • You have the firmware folders airgap_wallet/ and airgap_qrcam/.