# NerdMiner V2 - LilyGO T-HMI Technical Documentation
[Toc]

## Overview

This document provides comprehensive technical information for implementing NerdMiner V2 on the LilyGO T-HMI ESP32-S3 development board.

### Hardware Information

**Purchase Link:** [LILYGO T-HMI at Aliexpress](https://s.click.aliexpress.com/e/_oFII4s2)

**GitHub Repository:** [T-HMI Libraries and Examples](https://github.com/Xinyuan-LilyGO/T-HMI)

**3D Model:** [T-HMI Printable Model](https://www.printables.com/model/871409-lilygo-t-hmi-model)

### Pinout Diagram


*Figure 1: Complete pinout diagram showing all GPIO connections, power pins, and peripheral interfaces*

---

## Release History

### Initial Release (April 9, 2024)

**Pull Request:** [#302](https://github.com/BitMaker-hub/NerdMiner_v2/pull/302)

**Key Features:**
- Added LilyGO T-HMI board support
- Implemented fees display in bottom panel
- Experimented with price information in bottom title
- Touchscreen hardware present but not enabled in firmware
- Screen rotation sequence: Mining (pool) → Clock (fees) → Global (fees) → Price (pool)
- Button configuration (left to right, USB-C side):
- **B1:** Advance screen
- **B2:** Reset device
- **B3:** No function assigned

**Pinout Reference:** [Electronics Lab Diagram](https://www.electronics-lab.com/wp-content/uploads/2023/07/T-HMI-Pinout-Diagram-850x758.webp)

**Credits:** Special thanks to @nitroxgas for graphic design assistance

#### Device Photos


*Figure 2: T-HMI displaying mining statistics*


*Figure 3: Alternative screen view showing operational status*

---

### Feature Update (May 25, 2024)

**Pull Request:** [#379](https://github.com/BitMaker-hub/NerdMiner_v2/pull/379)

**Enhancements:**
- Battery option enabled for portable operation
- Improved pool data API URL discovery based on `Settings.PoolAddress` and/or `Settings.PoolPort`
- API improvements potentially applicable to other board variants:
- ESP32_2432S028R
- ESP32_2432S028_2USB
- ESP32_2432S024
- NERDMINER_T_HMI

---

### Major Update (June 10, 2024)

**Pull Request:** [#420](https://github.com/BitMaker-hub/NerdMiner_v2/pull/420)

**Critical Features:**

#### SD Card Support
Two separate implementation challenges were resolved:

1. **SD Card Detection Issue**
- Proper detection achieved by reducing SD_MMC frequency from default 40000 to 20000
- Details: [GitHub Issue #27](https://github.com/Xinyuan-LilyGO/T-HMI/issues/27#issuecomment-2132046978)

2. **Class Architecture Problem**
- SDcard class incompatible with 1-bit mode
- Solution: Moved `initSDCard()` to public access

#### Touchscreen Implementation
- **Top 3/4 of screen:** Advances through display screens
- **Bottom 1/4 of screen:** Toggles lower panel between workers and fees display

#### Other Changes
- Removed vkbit.com pool ([PR #410](https://github.com/BitMaker-hub/NerdMiner_v2/pull/410))
- Updated OneButton library to version 2.5.0

**Demonstration Video:** [YouTube Demo](https://youtu.be/El1wv85a0DI)

### Minor Update (July 31, 2025)

#### Worker API Enhancement
**Pull Request:** [#486](https://github.com/BitMaker-hub/NerdMiner_v2/pull/486)

This enhancement worker data by enabling platform-specific mining worker API calls across multiple hardware variants. The implementation introduces configurable defines that allow boards to independently enable worker metrics and fees data retrieval from their respective mining pools. By adding SCREEN_WORKERS_ENABLE to platform-specific headers, devices can now query and display worker statistics from [supported mining sites](https://hackmd.io/@cosmicpsyop/Skr4CUlE0#Worker-API-URL-Mapping-from-getPoolAPIUrl-function).

src/drivers/devices/lilygoT_HMI.h
src/drivers/devices/esp322432s028r.h

// calls api to retrieve worker metrics
#define SCREEN_WORKERS_ENABLE (1)

Also proposed is a SCREEN_FEES_ENABLE define, which renders cuuent pool fees. Implementation requires code reorganization as it depends on touchscreen functionality to toggle the lower screen display.

// retrieve current btc fees data
#define SCREEN_FEES_ENABLE (1)

While initially developed and tested for the T-HMI platform touchscreen capabilities, the architecture supports extension to other board variants including ESP32_2432S028R, ESP32_2432S028_2USB, and ESP32_2432S024, pending platform-specific verification and testing on other hardware.

#### Worker API Pool Expansion
This pull request expands the worker API support to include additional mining pools beyond the initial implementation. See [Worker API URL Mapping](https://hackmd.io/@cosmicpsyop/Skr4CUlE0#Worker-API-URL-Mapping-from-getPoolAPIUrl-function)

**Pull Request:** [#610](https://github.com/BitMaker-hub/NerdMiner_v2/pull/610)

> **Note**: the public-pool.io label on the lower screen is hardcoded in the graphic

---

## Flashing Instructions

### Using esptool.py

The T-HMI typically appears as `/dev/ttyACM0` on Linux systems. Verify your port assignment before proceeding.

#### Clone and Build Factory Firmware

git clone https://github.com/Xinyuan-LilyGO/T-HMI.git
cd T-HMI/examples/factory/

#### Flash Factory Application

After building, locate artifacts and flash:

cd .pio/build/debug
esptool.py --port /dev/ttyACM0 erase_flash
esptool.py --port /dev/ttyACM0 write_flash 0x0 bootloader.bin 0x8000 partitions.bin 0x10000 firmware.bin

#### Flash NerdMiner V2 Firmware

cd NerdMiner_v2/.pio/build/NerdminerV2-T-HMI
esptool.py --port /dev/ttyACM0 write_flash 0x10000 firmware.bin

## Worker API URL Mapping (from getPoolAPIUrl function)

| Pool Address | Pool Port | API URL | Notes |
|--------------|-----------|---------|-------|
| `public-pool.io` | | `https://public-pool.io:40557/api/client/` | Default public pool API |
| `nerdminers.org` | | `https://pool.nerdminers.org/users/` | Community pool |
| `pool.vkbit.com` | 3333 | `https://vkbit.com/miner/` | VKBit pool (removed in PR #410) |
| `pool.sethforprivacy.com` | 3333 | `https://pool.sethforprivacy.com/api/client/` | Privacy-focused pool |
| Umbrel IP | 2018 | `http://[POOL_ADDRESS]:2019/api/client/` | Dynamic | Port 2018 mining → Port 2019 API |
| Default/Fallback | | `String(getPublicPool)` | Returns to public pool API |

### API URL Construction Rules

1. **Exact Match Priority:**
- `public-pool.io` → Uses hardcoded API endpoint on port 40557
- `nerdminers.org` → Uses `/users/` endpoint

2. **Port-Based Matching (3333):**
- `pool.vkbit.com` → VKBit miner API
- `pool.sethforprivacy.com` → Seth's client API

3. **Umbrel Port Mapping (2018):**
- Mining port: 2018
- API port: 2019
- Format: `http://[pool-address]:2019/api/client/`

4. **Fallback:**
- All unmatched cases return public-pool.io API value

### Testing URLs

To test these APIs URLs:

$ curl https://public-pool.io:40557/api/client/bc1qpzhf5k123456l2tef3sf3awm7zpktjh7vjcuq4 
{"workersCount":0,"workers":[]}    


$ curl https://pool.sethforprivacy.com/api/client/bc1qpzhf5k123456l2tef3sf3awm7zpktjh7vjcuq4 
{"workersCount":0,"workers":[]} 

### Worker API URL Format

Most pools follow this standard format for worker statistics:

---

## SD Card Configuration

### SD_MMC Frequency Issue and Resolution

#### Problem Description

The default SD_MMC frequency of 40000 Hz in ESP-IDF v5.0.2 causes detection failures on the T-HMI hardware. This issue was observed in both custom implementations and the factory example code.

#### Symptoms

**Without SD Card Inserted:**

E (6044) sdmmc_common: sdmmc_init_ocr: send_op_cond (1) returned 0x107
E (6045) vfs_fat_sdmmc: sdmmc_card_init failed (0x107).
[ 6149][E][SD_MMC.cpp:138] begin(): Failed to initialize the card (0x107). 
Make sure SD card lines have pull-up resistors in place.
SD init failed
➸ No detected SdCard
SD close

**With SD Card Inserted (Default Frequency):**

E (26223) sdmmc_sd: sdmmc_check_scr: send_scr returned 0x109
E (26223) vfs_fat_sdmmc: sdmmc_card_init failed (0x109).
[ 26328][E][SD_MMC.cpp:138] begin(): Failed to initialize the card (0x109). 
Make sure SD card lines have pull-up resistors in place.
SD init failed
➸ No detected SdCard

#### Solution

Reduce the SD_MMC frequency to 20000 Hz (5000 Hz also works, but 20000 provides better performance):

bool rlst = SD_MMC.begin("/sdcard", true, false, 20000);

**Successful Output:**

SD close
SD init success
➸ Detected SdCard insert: 7.40 GB
SD close

---

### Formatting SD Card on Linux

#### Step-by-Step Instructions

1. **Identify the SD card device:**

   lsblk

Look for your SD card (typically `sdb` or similar)

2. **Unmount the SD card:**

   sudo umount /dev/sdb*

3. **Create W95 FAT32 partition:**

   echo ",,b;" | sudo sfdisk /dev/sdb

4. **Format to FAT32:**

Option 1:

   sudo mkfs.vfat /dev/sdb1

Option 2 (verbose):

   sudo mkfs.fat -F32 -v -I /dev/sdb1

---

### SD Card Test Example Code

Complete working example demonstrating the frequency fix:

#include "pins.h"
#include <Arduino.h>
#include <SD_MMC.h>
#include <FS.h>
#include <SPI.h>
#include <SD.h>

void setup() {
    pinMode(PWR_ON_PIN, OUTPUT);
    digitalWrite(PWR_ON_PIN, HIGH);
    
    Serial.begin(115200);
    delay(1000);
    
    pinMode(PWR_EN_PIN, OUTPUT);
    digitalWrite(PWR_EN_PIN, HIGH);
    
    SD_MMC.setPins(SD_SCLK_PIN, SD_MOSI_PIN, SD_MISO_PIN);
}

void loop() {
    delay(5000);
    
    bool rlst = SD_MMC.begin("/sdcard", true, false, 20000);
    
    if (!rlst) {
        Serial.println("SD init failed");
        Serial.println("➸ No detected SdCard");
    } else {
        Serial.println("SD init success");
        Serial.printf("➸ Detected SdCard insert: %.2f GB\r\n", 
                      SD_MMC.cardSize() / 1024.0 / 1024.0 / 1024.0);
    }
    
    delay(15000);
    Serial.println("SD close");
    SD_MMC.end();
}

---

## NerdMiner V2 SD Card Integration

### Hardware Pin Definitions

Add to `src/drivers/devices/lilygoT_HMI.h`:

#define SDMMC_CLK (12)
#define SDMMC_CMD (11)
#define SDMMC_D0 (13)

### 1-Bit SDMMC Mode Implementation

Modify `src/drivers/storage/SDCard.cpp` in the `initSDcard()` function:

#warning SDMMC : 1-bit mode is not always working. If you experience issues, try other modes.
iSD_->setPins(SDMMC_CLK, SDMMC_CMD, SDMMC_D0);

#ifdef NERDMINER_T_HMI
    cardInitialized_ = iSD_->begin("/sd", true, false, 20000);
#else
    cardInitialized_ = iSD_->begin("/sd", true);
#endif

Serial.println("SDCard: 1-Bit Mode.");

### Known Issue: Boot Loop with SD Card

When SD card support is enabled in 1-bit mode with a card inserted, the device may experience rapid boot loops. To recover:

1. Hold the **BOOT** button
2. Press the **RST** button
3. Release **RST**
4. Release **BOOT**

**Boot Loop Output:**

entry 0x403c98d4
ESP-ROM:esp32s3-20210327
Build:Mar 27 2021
rst:0x3 (RTC_SW_SYS_RST),boot:0x8 (SPI_FAST_FLASH_BOOT)
Saved PC:0x403cd9f6
SPIWP:0xee
mode:DIO, clock div:1
load:0x3fce3808,len:0x44c
load:0x403c9700,len:0xbe4
load:0x403cc700,len:0x2a38

### First Boot SPIFFS Error

Expected output on first boot:

--- Terminal on /dev/ttyACM0 | 115200 8-N-1
SPIFS: Mounting File System...
E (4843) SPIFFS: mount failed, -10025
[ 5221][E][SPIFFS.cpp:89] begin(): Mounting SPIFFS failed! Error: -1
E (4844) SPIFFS: mount failed, -10025
[ 5223][E][esp32-hal-misc.c:128] disableCore0WDT(): Failed to remove Core 0 IDLE task from WDT

---

## SD Card Configuration Transfer to NVM

### Purpose

This function automatically detects an SD card containing configuration data and transfers settings to non-volatile memory, eliminating the need for hard-coded WiFi credentials.

### Implementation

#include <FS.h>
#include <ArduinoJson.h>
#include <WiFi.h>
#include "drivers/storage/nvMemory.h"
#include "drivers/storage/SDCard.h"

extern nvMemory nvMem;
extern TSettings Settings;

void t_hmiCheckForSDCardAndMoveToNVM(void)
{
    // Workaround: Direct SD_MMC usage instead of SDCard class
    // SDCard class has issues in initSDcard() with 1-bit mode
    // Lower frequency to 20000 for reliable detection
    
    SD_MMC.setPins(SDMMC_CLK, SDMMC_CMD, SDMMC_D0);
    delay(500);
    
    bool rlst = SD_MMC.begin("/sd", true, false, 20000);
    
    if (!rlst) {
        Serial.println("SD init failed");
        Serial.println("➸ No detected SdCard");
    } else {
        Serial.println("SD init success");
        Serial.printf("➸ Detected SdCard insert: %.2f GB\r\n", 
                      SD_MMC.cardSize() / 1024.0 / 1024.0 / 1024.0);
        
        if (SD_MMC.exists(JSON_CONFIG_FILE)) {
            // Configuration file found - load and parse
            File configFile = SD_MMC.open(JSON_CONFIG_FILE, "r");
            
            if (configFile) {
                StaticJsonDocument<512> json;
                DeserializationError error = deserializeJson(json, configFile);
                configFile.close();
                
                Serial.println("SDCard: Loading config file");
                
                if (!error) {
                    serializeJsonPretty(json, Serial);
                    Serial.print('\n');
                    
                    TSettings *pSettings = &Settings;
                    
                    // Load configuration parameters
                    pSettings->WifiSSID = json[JSON_KEY_SSID] | pSettings->WifiSSID;
                    pSettings->WifiPW = json[JSON_KEY_PASW] | pSettings->WifiPW;
                    pSettings->PoolAddress = json[JSON_KEY_POOLURL] | pSettings->PoolAddress;
                    strcpy(pSettings->PoolPassword, 
                           json[JSON_KEY_POOLPASS] | pSettings->PoolPassword);
                    strcpy(pSettings->BtcWallet, 
                           json[JSON_KEY_WALLETID] | pSettings->BtcWallet);
                    
                    if (json.containsKey(JSON_KEY_POOLPORT))
                        pSettings->PoolPort = json[JSON_KEY_POOLPORT].as<int>();
                    
                    if (json.containsKey(JSON_KEY_TIMEZONE))
                        pSettings->Timezone = json[JSON_KEY_TIMEZONE].as<int>();
                    
                    if (json.containsKey(JSON_KEY_STATS2NV))
                        pSettings->saveStats = json[JSON_KEY_STATS2NV].as<bool>();
                    
                    // Save to NVM and restart
                    nvMem.saveConfig(pSettings);
                    WiFi.begin(pSettings->WifiSSID, pSettings->WifiPW);
                    
                    Serial.println("SDCard: Settings transferred to internal memory. Restarting now.");
                    ESP.restart();
                } else {
                    Serial.println("SDCard: Error parsing config file!");
                }
            } else {
                Serial.println("SDCard: Error opening config file!");
            }
        } else {
            Serial.println("SDCard: No config file available!");
        }
        
        SD_MMC.end();
        Serial.println("SD close");
    }
}

### Configuration File Format

Create a JSON configuration file on the SD card with the following structure:

{
    "SSID": "YourWiFiSSID",
    "WifiPW": "YourWiFiPassword",
    "PoolUrl": "pool.example.com",
    "PoolPassword": "x",
    "BtcWallet": "YourBitcoinAddress",
    "PoolPort": 3333,
    "Timezone": 0,
    "saveStats": true
}

---

## Technical Specifications

### ESP32-S3 Configuration
- **Chip:** ESP32-S3
- **Flash Mode:** DIO
- **Clock Division:** 1
- **Boot Mode:** SPI_FAST_FLASH_BOOT

### Display
- **Type:** Color TFT LCD with touchscreen
- **Interface:** SPI
- **Touch Control:** Capacitive (enabled in PR #420)

### Storage Options
- **SPIFFS:** Internal flash file system
- **SD Card:** SD_MMC interface (1-bit mode)
- Clock: GPIO 12
- Command: GPIO 11
- Data: GPIO 13

### Power Management
- Battery support enabled
- Power enable and control pins configured in firmware

---

## Troubleshooting

### SD Card Not Detected
1. Verify SD card is properly formatted (FAT32)
2. Ensure frequency is set to 20000 Hz in SD_MMC.begin()
3. Check pin connections match hardware configuration
4. Try a different SD card (some cards are incompatible)

### Boot Loop with SD Card
1. Hold BOOT button, press and release RST, then release BOOT
2. Reflash firmware using esptool.py
3. Verify SD card pin definitions in hardware header file

### SPIFFS Mount Failure
- Expected on first boot
- File system will be created automatically
- If persistent, perform a full flash erase before reflashing

### Display Issues
1. Verify power pins are properly configured
2. Check SPI pin assignments
3. Ensure display backlight is enabled in code

---

## Resources and References

- **Hardware Vendor:** [LILYGO Official Store](https://s.click.aliexpress.com/e/_oFII4s2)
- **GitHub Repository:** [NerdMiner V2](https://github.com/BitMaker-hub/NerdMiner_v2)
- **T-HMI Examples:** [Official T-HMI Repo](https://github.com/Xinyuan-LilyGO/T-HMI)
- **Pinout Documentation:** [Electronics Lab](https://www.electronics-lab.com/)

---

## Credits

**Hardware Platform:** LILYGO
**Firmware:** BitMaker-hub NerdMiner V2 Project
**Graphics Assistance:** @nitroxgas
**Community Contributors:** Multiple developers via GitHub pull requests

---

*Document Version: 1.0*
*Last Updated: October 2025*