ESP32-S3 Bitcoin Solo Miner

Project to test a setup for ESP32 S3 N16R8 as a bitcoin solo miner or ticket miner.

IDE: VSCode, using the ESP-IDF: Explorer extension.

Hardware: ESP32-S3-N16R8 (via ESP-PROG)

🎯 Project Goals

This is a learning project focused on:

• Learning C and Assembly programming
• Developing low-level, hardware-effective code
• Ensuring safety, privacy, and modularity
• Building an ESP32 Bitcoin miner from scratch

📚 Documentation

New to ESP32 Bitcoin mining? Start here:

• Quick Start Guide - Get mining in 5 minutes
• Comprehensive Mining Strategies - Deep dive into mining approaches, hardware optimization, and cooling requirements

These guides cover:

• Multiple mining approaches (NerdMiner, NMMiner, LeafMiner)
• Hardware specifications and cooling requirements
• Performance benchmarks and expectations
• Thermal management and active cooling recommendations
• Optimization techniques and troubleshooting

For a complete guide to all documentation in this repository, see Documentation Structure.

WiFi Configuration

To configure your WiFi credentials for local development:

1. Copy the example configuration file:

   cp main/config.h.example main/config.h

2. Edit main/config.h and update the WiFi credentials:

   #define WIFI_SSID "your_wifi_ssid"
   #define WIFI_PASS "your_wifi_password"

3. The config.h file is gitignored to prevent accidentally committing your credentials.

Note: Never commit your main/config.h file with real credentials to version control.

CI/CD Builds

CI/CD builds automatically skip WiFi functionality since config.h is not committed to the repository for security reasons. The WiFi code is conditionally compiled only when WIFI_SSID is defined (which comes from your local config.h file created from config.h.example). This allows automated builds to succeed without requiring WiFi credentials.

Build Instructions

1. Install ESP-IDF v5.1.2 or later
2. Set up your WiFi configuration (see above)
3. Build the project:

   idf.py set-target esp32s3
   idf.py build

4. Flash to your ESP32-S3:

   idf.py flash monitor

Testing

This project includes unit tests for core functionality using the ESP-IDF Unity test framework.

Running Tests

The test suite is located in the test/ directory. To build and run tests:

# Build the test application
idf.py set-target esp32s3
idf.py build

# Flash and monitor (if you have hardware)
idf.py flash monitor

Test Coverage

We use an automated feature detector to ensure all public functions have unit tests. To check test coverage:

python3 scripts/detect_features.py .

This script will:

• Analyze all C source files in the main/ directory
• Identify functions that lack unit tests
• Generate test stubs for missing tests

Adding Tests

When adding new functions:

1. Write the function in the appropriate source file
2. Add corresponding test functions in the test/ directory
3. Run the feature detector to verify coverage
4. Test names should follow the pattern: test_<function_name>

Example test structure:

void test_my_function(void)
{
    // 1. Setup test data
    // 2. Call the function
    // 3. Assert expected results
    TEST_ASSERT_EQUAL(expected, actual);
}

GPIO Pin Test Tool

If you need to identify the correct I2C pins on your ESP32 board, use the GPIO_Pin_Test tool located in the GPIO_Pin_Test/ directory. This standalone project helps you:

• Find working SDA/SCL pin pairs
• Scan for I2C device addresses
• Test specific pin configurations

See GPIO_Pin_Test/README.md for detailed instructions.

CI/CD

This project uses GitHub Actions for continuous integration. See CI_CD_SETUP.md for details.

All pull requests must pass:

• ✅ Build verification
• 🔍 Static code analysis
• 🔒 Security scanning
• 📝 Code quality checks
• 🧪 Test coverage verification

Contributing

See our pull request template and issue templates for contribution guidelines.

License

This is a learning project. Feel free to use and modify for educational purposes.