ESP-Miner: the open firmware behind the Bitaxe bitcoin miner

Firmware for one specific device, not a general miner

ESP-Miner is open source ESP32 firmware for the Bitaxe, and scoping it that way is the first thing to get right. The Bitaxe is a small device built around an ESP32 and a bitcoin ASIC, and this firmware is the software that drives it, including the mining work, the pool connection and the web interface. The project is not a mining pool, not a controller for a farm of GPUs and not a mining operating system for boards you assemble yourself. It is one firmware image for one hardware family, which has a direct effect on how you install and upgrade it. The firmware is maintained by OSMU, which also runs its own discussion forum at osmu.xyz. If you want a ready made image rather than a build, the project points you at the latest release page, and the flashing.md document in the repository explains how to load factory images onto the hardware.

bitaxetool does the flashing, and it is pinned to an old esptool

Flashing is handled by a separate command line Python tool called bitaxetool, which covers both firmware and configuration. Installing it is ordinary:

pip install --upgrade bitaxetool

The version constraint is the part to read twice. The tool does not work properly with esptool v5.x.x, and esptool v4.9.0 or earlier is required, with bitaxetool v0.6.1 locked to using esptool v4.9.0:

pip install bitaxetool==0.6.1

That pin is a real operational constraint rather than a footnote, because it means your flashing path depends on a specific version of a dependency and will not simply track whatever esptool publishes next. Three operations are supported. You can flash a factory image to reset the device, in which case you must choose the image built for your hardware version:

bitaxetool --firmware ./esp-miner-factory-401-v2.4.2.bin

You can flash only the NVS configuration, or both the image and the configuration in one command:

bitaxetool --config ./configs/config-401.csv --firmware ./esp-miner-factory-401-v2.4.2.bin

The README states the consequence of that combined command plainly: the settings in the config file overwrite the config already baked into the factory image. Flash a factory image thinking you are resetting the device, and your Wi-Fi and pool settings are replaced by whatever the config file says.

AxeOS is a web interface with a documented HTTP API

The firmware's user interface is called AxeOS, and it comes with an API that exposes actions and information, described in an OpenAPI document in the repository at main/http_server/openapi.yaml. The read endpoints cover system information, ASIC settings, system statistics for the dashboard, a scoreboard of the top 20 highest difficulty shares, a Wi-Fi network scan and a download of the system logs. The write side is smaller: restarting the system, making the device identify itself so you can find it by ear, and two update endpoints, one for system firmware and one for the AxeOS web interface partition, which is how you ship a custom web UI. Settings are changed with a PATCH on the system resource:

curl -X PATCH http://YOUR-BITAXE-IP/api/system \
     -H "Content-Type: application/json" \
     -d '{"fanspeed": "desired_speed_value"}'

Pool configuration is a PUT on a numbered slot, and the README shows both a Stratum V1 payload and a Stratum V2 payload with the extra fields that protocol needs, including the channel type and the authority public key.

Two WebSocket channels for logs and live state

The API is not only request and response. Two WebSocket endpoints give you a push model, and they are the reason a monitoring setup around a Bitaxe is worth building. The first is a text stream log at /api/ws, and the second at /api/ws/live is a JSONp stream of partial system information updates, meaning you receive the fields that changed rather than a full snapshot every time. Both are plain WebSockets, and the README shows how to attach:

websocat ws://YOUR-BITAXE-IP/api/ws

A log tail for a device that runs unattended is the obvious first use, and the live channel is the more interesting one, because a mining device's interesting state is a set of values that move: hashrate, temperature, fan speed, share counts. Polling the statistics endpoints for those is workable but wasteful, and the live stream gives you the change directly. Note that the endpoints are served over plain HTTP in the examples, which matters when you decide what network the device sits on.

mDNS turns the device into bitaxe.local

The firmware now includes comprehensive mDNS support, which is described as enabling automatic device discovery on local networks without manual IP address configuration. The mechanics are specific. The device registers itself automatically with mDNS, Bonjour or Avahi services when it connects to a network, and its hostname is registered as <hostname>.local, for example bitaxe.local. The HTTP service is advertised as _http._tcp on port 80, and AxeOS devices also advertise a subtype, _axeos._sub._http._tcp, so you can target discovery at AxeOS hardware rather than at every web server on the network. Device TXT records carry the board version, the family, the ASIC model, the ASIC count and the firmware version, which means discovery results alone tell you what a device is before you connect to it. Two details make it usable in practice. The hostname updates automatically when you change it through the web interface, and the hostname normalisation step strips the .local suffix when the name is set, so you do not end up with a duplicate registration.

Building the firmware with ESP-IDF and merging the binaries

The repository is an ESP-IDF project, and the evidence is in the build files. The Makefile is the small standard ESP-IDF stub, setting PROJECT_NAME to i2c-simple and including $(IDF_PATH)/make/project.mk, and the tree also carries a CMakeLists.txt, sdkconfig.defaults for the default configuration, partitions.csv for the flash layout, and a components directory alongside main. The build therefore depends on the Espressif SDK being present in your environment, which is a much larger dependency than a pip install. Producing something you can flash takes another step: the merge_bin.sh family of scripts, in four variants for different combinations of binary and configuration, assembles the pieces into the image files that the flashing instructions reference. There is also a configs directory holding the per hardware version CSV files used by bitaxetool, a doc directory, a tools directory, a test directory and a separate test-ci directory, and the presence of .devcontainer and sdkconfig.ci suggests the CI environment pins its own SDK configuration.

Release cadence, a dependency risk and the security notes

The recent tags give a sense of the pace: v2.15.2 on 2026-09-18, v2.15.3 on 2026-09-20, and a tag named checksum-test-0 on 2026-09-26, which reads as a test build rather than a normal release. The last push was on 2026-10-18, so work is happening after those tags. Two things deserve attention. The first is the esptool pin, which turns a routine dependency upgrade into a decision for the maintainers of bitaxetool rather than something you can do yourself, and that is the kind of coupling that ages badly. The second is security. The device exposes a REST API, an OTA endpoint that accepts a binary upload and a WebSocket log stream, and the repository carries a SECURITY.md file, so the project does have a place for disclosure and hardening notes. The firmware is licensed under GPL-3.0, and the AxeOS interface and the API are documented well enough that a monitoring tool is a weekend project rather than a research effort.

Editorial conclusion

ESP-Miner is a good fit if you own a Bitaxe and want to run it on firmware you can read, flash yourself and drive over the network, and the AxeOS API is the feature that justifies building a monitoring setup around it. It is the wrong choice if you want a mining rig rather than a single purpose built device, or if you expect the flashing toolchain to track current esptool releases, because bitaxetool is locked to esptool 4.9.0. Before you flash, check the hardware version so you pick the right factory image, keep a note that the NVS config overwrites whatever the factory image carries, and read the security notes in SECURITY.md before exposing the API beyond your own network.

Frequently asked questions

Official sources

1. bitaxeorg/ESP-Miner on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases