How blockstream/jade works
Main Components
• Bootloader Subsystem:
– Represented by the “bootloader_components” directory. It includes the bootloader support libraries, flash handling, secure boot, and various microcontroller-specific initialization code.
• Main Firmware Application:
– Contains the “main” directory with application initialization, UI, hardware interfacing (e.g., for display, camera, input, power management), cryptographic routines (e.g., attestation, RSA, AES, multisig support), network/serial communication, and firmware updating.
• Core Components & Libraries:
– The “components” folder contains supporting modules such as asset management, language autogeneration for localization, libraries like libwally-core, and hardware-specific interfacing (e.g., rotary encoder, esp32-quirc).
• Hardware Configuration:
– “configs” contains different sdkconfig defaults for various hardware platforms (e.g., display types and board revisions). Also, the “diy” folder holds documentation for DIY hardware adaptations.
• Emulation and Testing:
– The “main/qemu” directory and accompanying Dockerfiles (Dockerfile.qemu, docker-compose.yml) represent the virtualized/emulated environment. Also, there are test scripts (test_jade.py, various test_data) that verify firmware functionality.
• Client and API:
– The “jadepy” directory supplies a Python API/client to interact with the Jade device over serial, TCP, or via QEMU emulated interfaces.
• Build and Deployment:
– Multiple Dockerfiles, CMakeLists.txt files, and configuration/build scripts (including release scripts) support firmware building, deployment, and flashing operations.
Relationships and Interactions
• The Bootloader initializes hardware and then passes control to the main firmware.
• The Main Firmware, built with the esp-idf toolchain, uses various components to manage low-level hardware (display, BLE, input, camera) and higher-level functionalities (crypto, OTA, asset discovery).
• External interfaces:
• Serial ports, USB, BLE, and network interfaces enable communication and firmware updates.
• The Python client (jadepy) interacts with these interfaces for testing or remote control.
• Emulation Environment:
• QEMU containers (as defined in Dockerfile.qemu and docker-compose.yml) simulate hardware behavior, supporting CI and development.
• Build scripts ensure that configuration files (from “configs”) are copied appropriately before invoking idf.py commands.
Architectural Patterns and Design Principles
• Layered architecture: Separate bootloader from application firmware, with libraries and hardware abstraction layers in between.
• Modularity: Different hardware support modules and drivers (e.g., for different display or input types) are developed in separate directories.
• Expandability: Different configuration files and DIY hardware documentation indicate a design aimed at supporting multiple hardware revisions.
• Testing and Emulation: Multiple Docker environments and QEMU support indicate a strong emphasis on automated testing and reproducibility.