# cardware-wallet/cardware-hardware architecture

> Architecture diagram of the GitHub repository cardware-wallet/cardware-hardware, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cardware-wallet/cardware-hardware
- Repository: https://github.com/cardware-wallet/cardware-hardware

## Overview

##### Project Type and Purpose
- The project is firmware designed for a cryptocurrency hardware wallet (specifically BTC only).
- Its purpose is to securely manage Bitcoin functionalities such as transaction creation, cryptographic operations (using both built-in crypto and external secure elements), and potentially QR code generation for display.
- The firmware integrates various modules including display drivers (e.g., ST7735), cryptographic routines (Bitcoin module with mbedTLS and optiga libraries), and hardware device drivers (STM32 HAL and CMSIS).

##### Main Components
- Hardware Abstraction Layer (HAL) & Microcontroller Infrastructure:
- STM32H7xx HAL Driver files in the “Drivers” directory (e.g., stm32h7xx_hal*.c/h).
- Startup assembly (Core/Startup) and linker scripts (STM32H743VITX_FLASH.ld, STM32H743VITX_RAM.ld) indicating the microcontroller’s boot and memory configuration.
- Core Firmware Application (under “Core”):
- Initialization and main application entry (Core/Src/main.cpp).
- Peripheral drivers and middleware (e.g., GFX_FUNCTIONS for display, ST7735 for LCD control, fonts, JPEG utilities).
- Bitcoin Module:
- All Bitcoin-related source files (Core/Src/Bitcoin) that cover Bitcoin-specific algorithms, data conversions, transaction handling, hashing (SHA, ripemd160, secp256k1) and utility functions.
- Supporting submodules for cryptographic routines, including a well-organized “utility/crypto” folder.
- Secure Element and Cryptographic Interface:
- “Optiga” libraries in both Inc and Src directories under Core/Inc/optiga and Core/Src/optiga provide abstraction for secure cryptographic operations.
- The included Ifx_I2C and PAL (platform abstraction layer) subdirectories indicate structured communication with a potential secure element chip.
- Integration with mbedTLS (see Core/Src/optiga/mbedtls) for a standard crypto framework.
- Peripheral & Utility Modules:
- Imaging and QR code functionalities (Core/Src/qrcode.c, Core/Src/quirc) for handling QR code data which is useful for wallet operation.
- JPEG functionality provided in the “Utilities/JPEG” folder for image handling (possibly for displaying logos or QR codes).

##### Relationships and Interactions
- At the bottom, the Hardware Layer including the STM32 microcontroller, its startup code, and low-level drivers (Drivers, CMSIS, STM32 HAL).
- Above that, the Hardware Abstraction Layer combines the STM32 HAL and CMSIS layers with board-specific configuration.
- The Application Layer (Core) sits on this platform and includes modules for display control, secure communications (optiga, I2C layers), and overall firmware logic.
- A dedicated module for Bitcoin handling connects to both the cryptographic routines and the UI/display components. It interacts with secure element modules to perform sensitive operations securely.
- The optiga module communicates with external secure elements (over I2C) which should be shown as an external dependency for secure operations.

##### Architectural Patterns and Design Principles
- Layered design is evident: separation between hardware drivers, middleware (crypto, secure element interfaces), and application logic.
- Modular organization: Each specific functionality (Bitcoin, display, secure element communications) is isolated in its own folder/module to maintain clarity and ease maintenance.
- Abstraction over hardware specifics: The use of CMSIS, HAL libraries, and PAL indicates that hardware details are abstracted away from the high-level Bitcoin logic.
- Security-first approach: Integration of secure cryptographic libraries (mbedTLS) and specialized hardware modules (optiga) shows a focus on maintaining a secure firmware environment.

##### Specific Elements
- Initialization sequence from Bootloader/Startup → HAL Drivers → Application.
- Data flows between Bitcoin logic ←→ Crypto modules and Bitcoin logic ←→ UI Display.
- That security-critical interfaces (optiga, crypto libraries) are visually distinct to highlight their importance.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        MCU["Microcontroller (STM32H7)"]:::hardware
        I2C["I2C Bus (for secure element)"]:::hardware
    end

    %% Firmware Foundation Layer
    subgraph "Firmware Foundation Layer"
        SH["Startup & Linker Scripts"]:::firmware
        HAL["STM32 HAL Drivers"]:::firmware
        CMSIS["CMSIS Drivers"]:::firmware
    end

    %% Application Layer
    subgraph "Application Layer"
        MA["Main Application Entry"]:::application
        PD["Peripheral Drivers & Display Control"]:::application
        BM["Bitcoin Module"]:::bitcoin
        OE["Optiga Secure Element Interface"]:::secure
        MB["Crypto Libraries (mbedTLS)"]:::secure
        QR["QR Code Functionality"]:::peripheral
        JPEG["JPEG Utilities"]:::peripheral
    end

    %% Relationships - Initialization and Data Flow
    SH --> HAL
    SH --> CMSIS
    HAL --> MA
    CMSIS --> MA
    MA --> BM
    MA --> PD
    BM --> OE
    BM --> MB
    BM --> PD
    QR --> PD
    JPEG --> PD
    I2C --> OE

    %% Click Events
    click SH "https://github.com/cardware-wallet/cardware-hardware/blob/main/Core/Startup/startup_stm32h743vitx.s"
    click HAL "https://github.com/cardware-wallet/cardware-hardware/tree/main/Drivers/STM32H7xx_HAL_Driver"
    click CMSIS "https://github.com/cardware-wallet/cardware-hardware/tree/main/Drivers/CMSIS"
    click MA "https://github.com/cardware-wallet/cardware-hardware/blob/main/Core/Src/main.cpp"
    click PD "https://github.com/cardware-wallet/cardware-hardware/blob/main/Core/Inc/GFX_FUNCTIONS.h"
    click BM "https://github.com/cardware-wallet/cardware-hardware/tree/main/Core/Src/Bitcoin"
    click OE "https://github.com/cardware-wallet/cardware-hardware/tree/main/Core/Inc/optiga"
    click MB "https://github.com/cardware-wallet/cardware-hardware/tree/main/Core/Src/optiga/mbedtls"
    click QR "https://github.com/cardware-wallet/cardware-hardware/blob/main/Core/Src/qrcode.c"
    click JPEG "https://github.com/cardware-wallet/cardware-hardware/tree/main/Utilities/JPEG"

    %% Styling Classes
    classDef hardware fill:#ffcc99,stroke:#333,stroke-width:2px;
    classDef firmware fill:#bbdefb,stroke:#333,stroke-width:2px;
    classDef application fill:#c8e6c9,stroke:#333,stroke-width:2px;
    classDef bitcoin fill:#ffcdd2,stroke:#333,stroke-width:2px;
    classDef secure fill:#ffe082,stroke:#333,stroke-width:2px;
    classDef peripheral fill:#b3e5fc,stroke:#333,stroke-width:2px;
```
