StarMiner ESP-Miner

StarMiner ESP-Miner is a firmware fork for StarMiner, a DC 12V Bitaxe-derived open hardware miner design. It is based on the open source ESP-Miner firmware for the Bitaxe and keeps the AxeOS web interface and ESP-IDF build flow.

For stock Bitaxe hardware, use the upstream ESP-Miner releases and upstream factory image flashing instructions. For StarMiner DC 12V boards, build and flash images from this fork with the matching config-601a.cvs file.

StarMiner DC 12V hardware notes

• Target hardware: StarMiner DC 12V boards derived from the open Bitaxe hardware design.
• Firmware base: upstream ESP-Miner with AxeOS, adapted for the StarMiner hardware configuration.
• Power input: use the DC 12V supply required by the StarMiner board design. Do not assume stock Bitaxe power requirements apply.
• Flashing: use firmware images and configuration files built from this fork for StarMiner boards. Upstream Bitaxe factory images may not match the DC 12V hardware variant.
• Tuning: verify cooling, ASIC voltage, ASIC frequency, and power delivery before increasing clocks or enabling overclock-style settings.

Hardware design files

The StarMiner BitaxeGamma601a V1.0 DC 12V hardware package is available in sch/. See sch/README_HARDWARE.md for the PADS source inventory, schematic preview, Gerber outputs, and CERN-OHL-S-2 compliance notes.

Key hardware files:

• sch/bitaxeGamma601a_V1.0.sch - editable PADS schematic source.
• sch/bitaxeGamma601a_V1.0.pcb - editable PADS PCB layout source.
• sch/bitaxeGamma601a_V1.0_20260630.pdf - schematic PDF preview.
• sch/gerbers/ - PCB fabrication outputs exported from the PADS design.

Device photos

Bitaxetool

We also have a command line python tool for flashing Bitaxe/StarMiner devices and updating the config called Bitaxetool

Bitaxetool Requires Python3.4 or later and pip

Install bitaxetool from pip. pip is included with Python 3.4 but if you need to install it check https://pip.pypa.io/en/stable/installation/

pip install --upgrade bitaxetool

The bitaxetool includes the necessary libraries for flashing binaries to Bitaxe-derived hardware, including StarMiner.

Notes

• The bitaxetool does not work properly with esptool v5.x.x, esptool v4.9.0 or earlier is required.
• Bitaxetool v0.6.1 - locked to using esptool v4.9.0

pip install bitaxetool==0.6.1

• Flash a "factory" image to reset to factory settings. Make sure to choose an image built for your exact hardware version or StarMiner board variant:

bitaxetool --firmware ./esp-miner-factory-601a-vX.Y.Z.bin

• Flash just the NVS config to a StarMiner/Bitaxe board:

bitaxetool --config ./config-601a.cvs

• Flash both a factory image and a config: note the settings in the config file will overwrite the config already baked into the factory image:

bitaxetool --config ./config-601a.cvs --firmware ./esp-miner-factory-601a-vX.Y.Z.bin

AxeOS API

The esp-miner UI is called AxeOS and provides an API to expose actions and information.

For more details take a look at main/http_server/openapi.yaml.

Available API endpoints:

GET

• /api/system/info Get system information
• /api/system/asic Get ASIC settings information
• /api/system/statistics Get system statistics (data logging should be activated)
• /api/system/statistics/dashboard Get system statistics for dashboard
• /api/system/scoreboard Get top 20 highest difficulty shares
• /api/system/wifi/scan Scan for available Wi-Fi networks
• /api/system/logs Download system logs

POST

• /api/system/restart Restart the system
• /api/system/identify Identify the device
• /api/system/OTA Update system firmware
• /api/system/OTAWWW Update AxeOS

PATCH

• /api/system Update system settings

WEBSOCKETS

• /api/ws Text stream log
• /api/ws/live JSONp stream of partial system info updates

API examples in curl (works with IP addresses or .local hostnames):

# Get system information
curl http://YOUR-BITAXE-IP/api/system/info

# Get ASIC settings information
curl http://YOUR-BITAXE-IP/api/system/asic

# Get system statistics
curl http://YOUR-BITAXE-IP/api/system/statistics

# Get dashboard statistics
curl http://YOUR-BITAXE-IP/api/system/statistics/dashboard

# Get available Wi-Fi networks
curl http://YOUR-BITAXE-IP/api/system/wifi/scan

# Download system logs
curl http://YOUR-BITAXE-IP/api/system/logs


# Restart the system
curl -X POST http://YOUR-BITAXE-IP/api/system/restart

# Pause mining
curl -X POST http://YOUR-BITAXE-IP/api/system/pause

# Resume mining
curl -X POST http://YOUR-BITAXE-IP/api/system/resume

# Let the device say Hi!
curl -X POST http://YOUR-BITAXE-IP/api/system/identify

# Update system firmware
curl -X POST \
     -H "Content-Type: application/octet-stream" \
     --data-binary "@esp-miner.bin" \
     http://YOUR-BITAXE-IP/api/system/OTA

# Update AxeOS
curl -X POST \
     -H "Content-Type: application/octet-stream" \
     --data-binary "@www.bin" \
     http://YOUR-BITAXE-IP/api/system/OTAWWW


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

# Stream logs
websocat ws://YOUR-BITAXE-IP/api/ws

# Stream Info API
websocat ws://YOUR-BITAXE-IP/api/ws/live

mDNS Support

ESP-Miner now includes comprehensive mDNS (multicast DNS) support for seamless network discovery and device accessibility. This feature enables automatic device discovery on local networks without requiring manual IP address configuration.

Features

• Automatic mDNS Initialization: Device automatically registers with mDNS/Bonjour/Avahi services on network connection
• Dynamic Hostname Registration: Device hostname is registered as <hostname>.local (e.g., bitaxe.local)
• Service Advertisement: HTTP service is advertised as _http._tcp on port 80
• AxeOS Subtype: Advertises _axeos._sub._http._tcp for targeted DNS-SD discovery of AxeOS devices
• Device TXT Records: Includes board version, family, ASIC model, ASIC count, and firmware version as DNS-SD TXT records
• Dynamic Hostname Updates: mDNS hostname updates automatically when device hostname is changed via web interface
• Hostname Normalization: Automatically strips .local suffix when setting hostnames to prevent duplicate registrations
• CORS Support: Enhanced CORS handling to allow requests from mDNS hostnames
• Hostname Conflict Resolution: Automatically detects and resolves hostname conflicts by appending MAC address suffix when needed
• Enhanced Swarm Discovery: Swarm mode supports both IP addresses and .local hostnames for seamless network management

Network Discovery

Once connected to your local network, the device becomes discoverable through:

# Using avahi-browse (Linux)
avahi-browse _http._tcp

# Discover AxeOS devices specifically
avahi-browse _axeos._sub._http._tcp

# Using dns-sd (macOS)
dns-sd -B _http._tcp

# Discover AxeOS devices with TXT records
dns-sd -B _axeos._sub._http._tcp

# Direct access
http://<hostname>.local

Configuration

• Default Hostname: bitaxe (configurable via web interface)
• Service Type: _http._tcp
• Subtype: _axeos._sub._http._tcp
• Port: 80
• Instance Name: Bitaxe <family> <board> (<mac_suffix>) (e.g., Bitaxe Gamma 601 (A1B2))
• TXT Records: board, family, asic, asic_count, fw_version

Hostname Conflict Resolution

If multiple devices attempt to use the same hostname, ESP-Miner automatically resolves conflicts by appending a MAC address-derived suffix (e.g., bitaxe-12ab if bitaxe is taken). This ensures unique network identification without manual intervention.

Benefits

• Zero-Configuration Discovery: Devices automatically appear in network browsers
• Cross-Platform Compatibility: Works with Windows, macOS, Linux, and mobile devices
• No IP Address Required: Access devices using human-readable names
• Automatic Resolution: DNS resolution happens transparently in the background
• Zero-Configuration Swarm Management: Automatic device discovery and management without IP configuration
• Enhanced Cross-Platform Compatibility: Improved support across different network environments and discovery protocols

Administration

The firmware hosts a small web server on port 80 for administrative purposes. Once the Bitaxe device is connected to the local network, the admin web front end may be accessed via a web browser connected to the same network at http://<IP>, replacing IP with the LAN IP address of the Bitaxe device, or http://bitaxe, provided your network supports mDNS configuration.

Recovery

In the event that the admin web front end is inaccessible, for example because of an unsuccessful firmware update (www.bin), a recovery page can be accessed at http://<IP>/recovery.

Unlock Settings

In order to unlock the Input fields for ASIC Frequency and ASIC Core Voltage you need to append ?oc to the end of the settings tab URL in your browser. Be aware that without additional cooling overclocking can overheat and/or damage your StarMiner/Bitaxe board.

Development using esp-miner/devcontainer

This configuration allows you to edit locally and compile the source code using a docker container so you don't have to install the ESP-IDF toolchain and other supporting software on your computer to compile the firmware.

Prerequisites

• Docker server

Local PC Setup

These instructions will assume an installation to your home directory.

cd ~
git clone --recursive https://github.com/awxhw/StarMiner.git
cd StarMiner
git checkout <the branch you want>
git submodule update --init --recursive
# The next step builds the docker container that will compile the source code
# This will take several minutes to finish
docker build -t espminer-build .devcontainer

Building

cd ~/StarMiner
docker run --rm -it -v $PWD:/workspace espminer-build /bin/bash
git config --global --add safe.directory /workspace    # set git permissions or build will fail; only done once
cd /workspace
idf.py build

Once the build is done exit out of the docker session and flash the new firmware.

Development

Prerequisites

• Install the ESP-IDF toolchain from https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/
• Install nodejs/npm from https://nodejs.org/en/download
• (Optional) Install the ESP-IDF extension for VSCode from https://marketplace.visualstudio.com/items?itemName=espressif.esp-idf-extension

Cloning

This project uses git submodules (e.g. libsecp256k1). Clone with --recursive:

git clone --recursive https://github.com/awxhw/StarMiner.git

If you already have a checkout, initialize the submodules with:

git submodule update --init --recursive

Building

At the root of the repository, run:

idf.py build && ./merge_bin.sh ./esp-miner-merged.bin

Note: the merge_bin.sh script is a custom script that merges the bootloader, partition table, and the application binary into a single file.

Note: if using VSCode, you may have to configure the settings.json file to match your esp hardware version. For example, if your bitaxe has something other than an esp32-s3, you will need to change the version in the .vscode/settings.json file.

Flashing

With the StarMiner/Bitaxe connected to your computer via USB, run:

bitaxetool --config ./config-601a.cvs --firmware ./esp-miner-merged.bin

where 601a is the config file for your hardware version. For StarMiner DC 12V boards, use the config file that matches the StarMiner hardware variant from this fork. You can see the list of available config files in the root of the repository.

A custom board version is also possible with config-custom.cvs. A custom board needs to be based on an existing devicemodel and asicmodel.

Notes:

• If you are developing within a dev container, you will need to run the bitaxetool command from outside the container. Otherwise, you will get an error about the device not being found.
• Some Bitaxe versions can't directly connect to a USB-C port. If yours is affected use a USB-A adapter as a workaround. More about it here.
• Only ESP32-S3-WROOM-1 module type N16R8 (16MB Flash, 8MB Octal SPI PSRAM) is supported. This model number should be visible on the ESP32 module. Other module types without PSRAM or with Quad SPI PSRAM will not work with the normal firmware. More about it here.

Wi-Fi routers

There are some Wi-Fi routers that will block mining, ASUS Wi-Fi routers & some TP-Link Wi-Fi routers for example. If you find that your not able to mine / have no hash rate you will need to check the Wi-Fi routers settings and disable the following;

1/ AiProtection

2/ IoT

If your Wi-Fi router has both of these options you might have to disable them both.

If your still having problems here, check other settings within the Wi-Fi router and the bitaxe device, this includes the URL for the Stratum Host and Stratum Port.

Contact

Email	Telegram	WhatsApp	Home Page
support@ustarminer.com			www.ustarminer.com

For StarMiner DC 12V hardware questions, firmware issues, or compatibility reports, please contact support or open a GitHub issue with your board variant, firmware version, power supply details, and relevant logs.

Brand and trademark notice

StarMiner is used in this repository as the project and product mark for this DC 12V Bitaxe-derived hardware and firmware fork. The StarMiner name, device photos, and related project branding should not be used in a way that suggests official endorsement, certification, or release ownership without permission from the project maintainers.

Bitaxe, ESP-Miner, AxeOS, and other third-party names remain the property of their respective owners. References to upstream projects are descriptive and are provided for attribution and compatibility context only.

Attributions

The display font is Portfolio 6x8 from https://int10h.org/oldschool-pc-fonts/ by VileR.