SparkMiner v2.9.5

High-performance Bitcoin solo miner for ESP32, ESP32-S3 & ESP32-C3

<img src="images/1767589853452.jpg" alt="SparkMiner Display" width="575">

SparkMiner is optimized firmware for ESP32-based boards with displays, delivering ~1+ MH/s (pool-reported) using hardware-accelerated SHA-256 and pipelined assembly mining. Supports both ESP32 "Cheap Yellow Display" (CYD) boards and ESP32-S3 variants.

Solo Mining Disclaimer: Solo mining on an ESP32 is a lottery. The odds of finding a block are astronomically low (~1 in 10^20 per hash at current difficulty). This project is for education, fun, and supporting network decentralization - not profit.

---

Quick Start

Option 1: Launcher + SD Card (Recommended for CYD Boards)

The easiest way to install and manage SparkMiner on CYD boards (1-USB or 2-USB variants):

Step 1: Flash the Launcher (one-time)

1. Go to Bruce Launcher Web Flasher
2. Connect your CYD board via USB
3. Select your board type and click Install
4. The Launcher provides a boot menu for multiple firmwares

Step 2: Prepare SD Card

1. Format a microSD card as FAT32
2. Download cyd-2usb_firmware.bin (or your board variant) from Releases
3. Copy the .bin file to the SD card root
4. Create a config.json file (see Configuration section)
5. Insert SD card into CYD

Step 3: Boot SparkMiner

1. Power on the CYD - the Launcher menu appears
2. Select SparkMiner firmware from the SD card
3. SparkMiner loads your config and starts mining!

Why use the Launcher?

• Easy firmware updates - just replace the .bin on SD card
• Switch between multiple firmwares
• No need to re-flash via USB for updates
• Config persists on SD card

Option 2: Direct USB Flashing

1. Download the latest *_factory.bin firmware from Releases
2. Flash using ESP Web Flasher or esptool:

   esptool.py --chip esp32 --port COM3 write_flash 0x0 cyd-2usb_factory.bin
   

3. Power on the board - it will create a WiFi access point
4. Connect to SparkMiner-XXXX WiFi and configure via the web portal

Option 3: Build from Source

# Clone repository
git clone https://github.com/SneezeGUI/SparkMiner.git
cd SparkMiner

# Create virtual environment and install dependencies
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/Mac
pip install platformio

# Use the interactive devtool (recommended)
devtool.bat          # Windows - interactive menu
python devtool.py    # Cross-platform

# Or build a specific board directly
python devtool.py build -b cyd-2usb
python devtool.py flash -b cyd-2usb
python devtool.py monitor

# All-in-one: build, flash, and monitor
python devtool.py all -b cyd-2usb

---

Firmware Types

Understanding the difference between the firmware files:

• *_firmware.bin: The application only. Use this for Launcher/SD card updates or OTA updates. It does not include the bootloader.
• *_factory.bin: The complete image (Bootloader + Partition Table + App). Use this for direct USB flashing (Option 2) to a blank board or to restore a board.

---

Upgrading

To upgrade from an older version:

1. Via SD Card (Launcher): Replace the *_firmware.bin file on your SD card with the new version (e.g., cyd-2usb_firmware.bin).
2. Via USB: Flash the new *_factory.bin using the interactive devtool.py or esptool.

Note: NVS stats are persistent across standard reboots, but a full flash might clear NVS depending on your method. The SD card backup (/stats.json) ensures your lifetime totals can be restored.

---

Which Firmware Do I Download?

Find your board below and download the matching firmware from Releases.

CYD (Cheap Yellow Display) Boards - 2.8" TFT

| Your Board | Firmware File | Notes | |------------|---------------|-------| | CYD 2-USB (Type-C + Micro USB) | cyd-2usb_firmware.bin | Most common, dual USB ports | | CYD 1-USB (Single Micro USB) | cyd-1usb_firmware.bin | Single USB, ILI9341 display | | CYD 1-USB ST7789 | cyd-1usb-st7789_firmware.bin | ST7789 display variant | | ESP32-2432S028R | cyd-1usb_firmware.bin | Same as CYD 1-USB | | ESP32-2432S028R 2-USB | cyd-2usb_firmware.bin | Same as CYD 2-USB |

ESP32-S3 Boards

| Your Board | Firmware File | Notes | |------------|---------------|-------| | Freenove ESP32-S3 (FNK0104) | freenove-s3_firmware.bin | 2.8" IPS display, SD_MMC | | Freenove ESP32-S3-WROOM CAM | freenove-s3_firmware.bin | Same board, ignore camera | | ESP32-S3 DevKit | esp32-s3-devkit_firmware.bin | Headless (no display) | | Wemos/Lolin S3 Mini | esp32-s3-mini_firmware.bin | RGB LED status indicator | | WeAct S3 Mini | esp32-s3-mini_firmware.bin | Compatible with Lolin | | ESP32-S3 + SSD1306 OLED | esp32-s3-oled_firmware.bin | 128x64 I2C OLED |

ESP32-C3 Boards

| Your Board | Firmware File | Notes | |------------|---------------|-------| | ESP32-C3 SuperMini | esp32-c3-supermini_firmware.bin | Headless, ultra-compact | | ESP32-C3 + SSD1306 OLED | esp32-c3-oled_firmware.bin | 128x64 I2C OLED | | Seeed XIAO ESP32-C3 | esp32-c3-supermini_firmware.bin | Use SuperMini firmware |

Generic ESP32 Boards

| Your Board | Firmware File | Notes | |------------|---------------|-------| | ESP32 DevKit | esp32-headless_firmware.bin | Any generic ESP32, GPIO LED status | | ESP32-WROOM-32 | esp32-headless_firmware.bin | GPIO LED on pin 2 | | NodeMCU ESP32 | esp32-headless_firmware.bin | Use headless firmware |

File Types

• *_firmware.bin - Use with Bruce Launcher or SD card boot
• *_factory.bin - Use for direct USB flashing (includes bootloader)

---

Hardware

Performance by Chip

| Chip | Hashrate | Notes | |------|----------|-------| | ESP32 (dual-core) | ~715 KH/s | Best performance, hardware SHA-256 | | ESP32-S3 (dual-core) | ~280-400 KH/s | Software SHA-256, more RAM | | ESP32-C3 (single-core) | ~200-300 KH/s | RISC-V, lowest power |

Board Compatibility Status

| Board | Status | Notes | |-------|--------|-------| | CYD (ESP32-2432S028) | ✅ Full | Primary target, 3 variants | | Freenove ESP32-S3 | ✅ Full | 2.8" IPS with SD_MMC | | ESP32-S3/C3 + OLED | ✅ Full | 128x64 SSD1306 I2C | | ESP32-S3/C3 Mini | ✅ Full | RGB LED status | | ESP32 Headless | ✅ Full | GPIO LED status indicator | | LILYGO T-Display S3 | ❌ None | Not yet supported | | LILYGO T-Display V1 | ❌ None | Not yet supported | | ESP32-S2 boards | ❌ None | Single-core not supported | | M5Stack boards | ❌ None | Not configured |

Legend: ✅ Supported | ❌ Not supported

Where to Buy

• AliExpress: Search "ESP32-2432S028" for CYD boards (~$4-16 USD)
• Amazon: Search "CYD ESP32 2.8 inch" or "Freenove ESP32-S3" (~$15-25 USD)
• Freenove Store: FNK0104 ESP32-S3 Display (~$20 USD)

Hardware Features

• CPU: Dual-core Xtensa LX6 @ 240MHz (ESP32), LX7 (S3), or single-core RISC-V (C3)
• Display: TFT (ILI9341/ST7789) or OLED (SSD1306)
• Storage: MicroSD card slot (select boards)
• Connectivity: WiFi 802.11 b/g/n
• RGB LED: Status indicator (S3 Mini, Headless-LED boards)
• GPIO LED: Simple blink status indicator (Headless boards, pin 2)
• Button: Boot button for interaction

---

Configuration

SparkMiner can be configured in three ways (in order of priority):

1. SD Card Configuration (Recommended)

Create a config.json file on a FAT32-formatted microSD card:

{
  "ssid": "YourWiFiName",
  "wifi_password": "YourWiFiPassword",
  "pool_url": "public-pool.io",
  "pool_port": 21496,
  "wallet": "bc1qYourBitcoinAddressHere",
  "worker_name": "SparkMiner-1",
  "pool_password": "x",
  "brightness": 100
}

Configuration Options

| Field | Required | Default | Description | |-------|----------|---------|-------------| | ssid | Yes | - | Your WiFi network name | | wifi_password | Yes | - | Your WiFi password | | pool_url | Yes | public-pool.io | Mining pool hostname | | pool_port | Yes | 21496 | Mining pool port | | wallet | Yes | - | Your Bitcoin address (receives payouts) | | worker_name | No | SparkMiner | Identifier shown on pool dashboard | | pool_password | No | x | Pool password (usually x) | | brightness | No | 100 | Display brightness (0-100) | | screen_timeout | No | 0 | Screen auto-off timeout in seconds (0=never, 30, 60, 120, 300) | | rotation | No | 1 | Screen rotation (0-3) | | invert_colors | No | false | Invert display colors | | backup_pool_url | No | - | Failover pool hostname | | backup_pool_port | No | - | Failover pool port | | backup_wallet | No | - | Wallet for backup pool | | stats_enabled | No | true | Enable/disable live stats fetching | | stats_api_url | No | - | Custom stats API endpoint (HTTP) | | stats_proxy_url | No | - | HTTP proxy for HTTPS APIs | | enable_https_stats | No | false | Direct HTTPS (unstable) |

2. WiFi Access Point Portal

If no SD card config is found, SparkMiner creates a WiFi access point:

1. Connect to WiFi network: SparkMiner-XXXX (password: minebitcoin)
2. Open browser to http://192.168.4.1
3. You will see the new dark-themed portal with full configuration options:
   • Primary & Backup Pool settings
   • Display brightness, rotation, and color inversion
   • Target difficulty
4. Configure your settings, click Save, and the device will reboot and connect.

3. NVS (Non-Volatile Storage)

Configuration is automatically saved to flash memory after first successful setup. To reset:

• Long-press BOOT button (1.5s) during operation for 3-second countdown reset, OR
• Hold