# skot/esp-miner architecture

> Architecture diagram of the GitHub repository skot/esp-miner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/skot/esp-miner
- Repository: https://github.com/skot/esp-miner

## Overview

Based on our analysis of the provided file structure and README, the project is an embedded firmware for the Bitaxe hardware built on the ESP32 using the ESP-IDF framework. It’s designed for cryptocurrency mining (hence the “miner” name) and includes both low-level hardware control – for handling various ASIC chips – and higher-level network services (like DNS, HTTP, and a mining stratum protocol). In addition, there’s a companion Python command‐line tool (Bitaxetool) for flashing firmware and configuration, and a web-based admin UI called AxeOS for monitoring and managing the device.

##### Main components
- Firmware Build & Deployment:
- Bootloader and firmware merge process (scripts like merge_bin.sh, CMakeLists.txt, Makefile).
- ESP-IDF build configuration and device-specific configuration files (sdkconfig.*, .devcontainer).
- Modular Software Components:
- “components/asic”: Contains source code and headers for driving multiple ASIC chip models (bm1366, bm1368, bm1370, bm1397, etc.) and related utilities (common, CRC, etc.).
- “components/connect”: Manages connectivity aspects.
- “components/dns_server”: Implements a DNS server functionality.
- “components/stratum”: Implements the mining protocol (stratum API, mining logic, testing/verifiers such as merklecalc.py).
- Main Application (in the “main” directory):
- Contains the core firmware logic, including ADC, display, hardware initialization, and system tasks.
- The “tasks” subdirectory holds modules for asic task scheduling, power management, stratum tasks, etc.
- Hosting the HTTP server (in “main/http_server”) that provides the AxeOS UI and the REST API for system and swarm information; also providing WebSocket support.
- Additional utilities like NVS config management, recovery page (accessible at /recovery), and OTA updates.
- External Tools & Interfaces:
- Bitaxetool (a separate Python tool) for flashing and updating firmware/configuration.
- The AxeOS web UI, built with Angular (in “main/http_server/axe-os”), which interacts with the HTTP server via the provided API endpoints.
- GitHub Actions/CI directories (”.github”) for automating unit tests, builds, and releases.

- That the firmware comprises a bootloader and a merged application image created via the merge_bin.sh script. This image is built using ESP-IDF (configured by CMake and Makefiles).
- Within the “main” block, highlight submodules:
▪ HTTP Server (which contains the API endpoints for system info, swarm management, OTA updates, and WebSocket connections).
▪ RTOS Tasks handling asic_result_task, stratum_task, power_management_task, etc.
- Bitaxetool as an external CLI interacting with the device during flashing over USB – indicating that it uploads both the firmware and configuration (the .cvs files).
- Build & deployment pipeline (e.g., GitHub workflows) as an external system that triggers builds and releases.

##### Architectural Patterns and Design Principles
- Modularity: The separation of hardware-specific (ASIC, power management) and network/social features (HTTP server, API modules, web interface).
- Configuration management: Use of Kconfig and multiple configuration files (e.g., config-xxx.cvs) to support different versions of Bitaxe hardware.
- Use of a task-based or RTOS approach, as seen in the “tasks” directory, which coordinates concurrent operations among modules.

##### Relevant Technologies, Frameworks, or Libraries
- ESP-IDF for the ESP32 firmware.
- CMake and Make for build systems.
- Angular (and NodeJS/npm) for the web-based AxeOS front end.
- Python (with Bitaxetool) for flashing and device updates.
- Standard C runtime along with hardware abstraction layers specific to the Bitaxe electronics.

##### Essential Elements
- Use clear labels for each component, such as “ASIC Module”, “Stratum Module”, “HTTP Server (AxeOS API)”, “Firmware Build System”, “Bitaxetool (CLI)”, etc.
▪ HTTP Server → AxeOS UI (for API calls)
▪ Main Application → Components (calling ASIC functionalities)
▪ Bitaxetool → Bitaxe Hardware (flashing and configuration)
▪ Firmware-level modules (e.g., rectangles for C modules)
▪ External components (e.g., ovals for external tools like Bitaxetool)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Components
    A["CI/CD Pipeline"]:::external
    B["Firmware Build & Deployment"]:::firmware
    C["Bitaxe Hardware (ESP32)"]:::hardware
    D["Main Application Firmware"]:::firmware
    I["RTOS Tasks"]:::firmware
    E["ASIC Module"]:::firmware
    F["Connectivity Module"]:::firmware
    G["DNS Server"]:::firmware
    H["Stratum Module"]:::firmware
    J["HTTP Server (AxeOS API)"]:::firmware
    K["AxeOS UI"]:::ui
    L["Bitaxetool CLI"]:::external

    %% Connections
    A -->|"triggers_build"| B
    B -->|"deploys_to"| C
    C -->|"runs"| D
    D -->|"calls"| E
    D -->|"calls"| F
    D -->|"calls"| G
    D -->|"calls"| H
    D -->|"schedules"| I
    D -->|"hosts"| J
    J -->|"serves_API_to"| K
    L -->|"flashes_firmware"| C

    %% Click Events
    click B "https://github.com/skot/esp-miner/blob/master/merge_bin.sh"
    click E "https://github.com/skot/esp-miner/tree/master/components/asic"
    click F "https://github.com/skot/esp-miner/tree/master/components/connect"
    click G "https://github.com/skot/esp-miner/tree/master/components/dns_server"
    click H "https://github.com/skot/esp-miner/tree/master/components/stratum"
    click D "https://github.com/skot/esp-miner/tree/master/main"
    click I "https://github.com/skot/esp-miner/tree/master/main/tasks"
    click J "https://github.com/skot/esp-miner/tree/master/main/http_server"
    click K "https://github.com/skot/esp-miner/tree/master/main/http_server/axe-os"
    click A "https://github.com/skot/esp-miner/blob/master/.github"

    %% Styles
    classDef firmware stroke:#333,stroke-width:2px,fill:#ffdddd;
    classDef external stroke:#333,stroke-width:2px,fill:#ddffdd;
    classDef hardware stroke:#333,stroke-width:2px,fill:#ddddff;
    classDef ui stroke:#333,stroke-width:2px,fill:#e0d1ff;
```
