Software setup
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.
Versions used
Section titled “Versions used”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 |
1. Install the Arduino IDE
Section titled “1. Install the Arduino IDE”Download the Arduino IDE 2 from the official software page and install it. On Windows there is an installer.
2. Add the ESP32 boards
Section titled “2. Add the ESP32 boards”The IDE needs to know where Espressif publishes the ESP32 core.
-
Open File → Preferences.
-
In Additional boards manager URLs, paste:
https://espressif.github.io/arduino-esp32/package_esp32_index.json -
Click OK.
-
Open the Boards Manager (Tools → Board → Boards Manager…, or the board icon in the left sidebar).
-
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.
3. Install the libraries
Section titled “3. Install the libraries”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.
4. Get the firmware
Section titled “4. Get the firmware”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:
- Open File → New Sketch.
- Select Tools → Board → esp32 → ESP32 Dev Module, then click Verify (the tick button).
- 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.
6. Install Sparrow Wallet
Section titled “6. Install Sparrow Wallet”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.
Before you continue
Section titled “Before you continue”- 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/andairgap_qrcam/.