How to Run Bitcoin Mining on an ESP32 Microcontroller

Mining the first cryptocurrency has long turned into a closed club of industrial data centers with giant hangars full of humming ASICs. For an ordinary developer, building a home mining rig today for fun is pointless and expensive. But the Bitaxe project and the ESP-Miner repository bring back the feeling of garage DIY. The guys created a full-featured open-source firmware for a board based on the ESP32 chip that controls a standalone ASIC chip (for example, BM1397 or BM1366 from disassembled Antminers) and mines Bitcoin directly over home Wi-Fi.

Essentially, this is an open-source micro-miner the size of a palm that consumes a couple dozen watts, sits quietly on a desk, and delivers honest hashrate. Let's figure out how this system works internally and what makes the repository interesting for programmers.

What's Inside the Project

ESP-Miner is written in pure C under Espressif's ESP-IDF framework. The firmware handles all the grunt work: initializes the ASIC, configures core voltage and frequency, connects to Wi-Fi, and maintains communication with the mining pool via the Stratum protocol.

The system includes AxeOS. This is a built-in web interface and HTTP server that serves metrics, allows changing pools, and controls the fan. Previously, the web interface was compiled separately and flashed to a separate SPIFFS partition, but in recent versions the authors bundled the frontend directly into the main application binary (esp-miner.bin), compressing it with gzip. If you need to apply a custom theme or your own UI, you can enable a separate partition www.bin in the settings.

The board doesn't work with just any module. The firmware critically requires an ESP32-S3-WROOM-1 module revision N16R8, which has 16 MB of flash memory and 8 MB of octal PSRAM soldered on board. Without this RAM, the firmware simply won't boot, given the buffer sizes and built-in network services.

Control via REST API and WebSockets

The most pleasant thing for developers is that the device doesn't try to be a "closed box." AxeOS provides a full OpenAPI interface through which you can automate any actions.

Here's what a typical poll of the ASIC status looks like via curl:

curl http://bitaxe.local/api/system/asic

The response delivers a JSON with current frequency, voltage, temperature, and hashrate. If you need to switch the fan speed, send a PATCH request:

curl -X PATCH http://bitaxe.local/api/system \
     -H "Content-Type: application/json" \
     -d '{"fanspeed": "80"}'

Both generations of the Stratum protocol are supported: classic V1 and modern V2 with encrypted channels and reduced traffic. You can configure the pool right from the terminal:

curl -X PUT http://bitaxe.local/api/system/pools/0 \
     -H "Content-Type: application/json" \
     -d '{
       "stratumProtocol": "SV1",
       "stratumURL": "solo.ckpool.org",
       "stratumPort": 3333,
       "stratumUser": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa.worker1",
       "stratumPassword": "x",
       "stratumSuggestedDifficulty": 0,
       "stratumExtranonceSubscribe": true,
       "stratumTLS": 0,
       "stratumDecodeCoinbase": true
     }'

For streaming monitoring, there are two WebSockets available. At address /api/ws, text system logs flow in real time, and /api/ws/live broadcasts a JSON stream with system state changes. Using the websocat utility, you can immediately redirect this stream to a local dashboard or metric collection script:

websocat ws://bitaxe.local/api/ws/live

Auto-Discovery on the Network via mDNS

If you're connecting not just one Bitaxe but a whole batch (a so-called swarm), searching for each IP address through the router gets tedious. The developers built in multicast DNS (mDNS) support with service advertisement via DNS-SD.

The device registers itself with the subtype _axeos._sub._http._tcp. In TXT records, it immediately provides the board version, ASIC chip model, their count, and firmware version. On Linux, you can find all active miners on the local network with a single command:

avahi-browse _axeos._sub._http._tcp

If two devices with the same name bitaxe appear on the network, the conflict is resolved automatically. The firmware takes the MAC address suffix and renames itself, for example, to bitaxe-12ab.

Building and Flashing

For flashing pre-built releases and editing NVS settings, the team made their own Python CLI utility — bitaxetool. Pay attention to the dependency versions: the utility is tied to an old version of esptool 4.9.0 and currently breaks on the fifth branch.

Installation and flashing the factory image looks like this:

pip install bitaxetool==0.6.1
bitaxetool --config ./config-401.cvs --firmware ./esp-miner-factory-401-v2.4.2.bin

If you want to dig into the source code and build the project locally, you won't even need to install the entire ESP-IDF stack on your host. The repository has a ready-made .devcontainer. You can run the build inside an isolated Docker container:

git clone --recursive https://github.com/bitaxeorg/ESP-MINER.git
cd ESP-MINER
docker build -t espminer-build .devcontainer
docker run --rm -it -v $PWD:/workspace espminer-build /bin/bash

Inside the container, we run the standard idf.py build command. Then we launch the helper script merge_bin.sh, which merges the bootloader, partition table, and firmware image into a single flashable file.

What Quirks You Might Encounter

There are a couple of nuances that the creators honestly warn about in the documentation.

First, home routers. Some ASUS and TP-Link models with built-in traffic filtering systems (like AiProtection or IoT Shield) silently block the Stratum protocol, mistaking the miner's packets for malicious software activity. As a result, the board successfully maintains Wi-Fi, but the hashrate stubbornly stays at zero. You have to disable these settings in the router's admin panel.

Second, overclocking. By default, the frequency and core voltage adjustment fields are locked in the web interface for safety. To unlock access to fine-tuning, you need to add the parameter ?oc to the browser address bar on the settings tab. Without a proper heatsink and good fan, doing this is clearly not worth it.

Third, physical connection. Some revisions of Bitaxe boards are finicky about direct Type-C to Type-C cable connections due to CC-line resistor routing. An adapter to USB-A immediately solves the problem.

Why Developers Should Look at This Project

ESP-Miner is interesting not so much for the ability to earn satoshis (at this power level, it's more like participating in a solo mining lottery), but for its architecture. It's a great reference for how to build complex devices based on ESP32:

• How to organize a full REST API and WebSockets on a microcontroller without freezing.
• How to combine a web interface and low-level C code in a single compressed binary.
• How to implement device auto-discovery via mDNS without a central server.
• How to work with third-party cryptographic libraries like libsecp256k1 on embedded chips.

If you have an ESP32-S3 with PSRAM lying around unused or have long wanted to understand the Stratum protocol in practice, digging into the repository is definitely worth it.