Skip to content

How to Build AxeOS from Source

This guide shows you, how you can compile AxeOS yourself. It is split into three sections for the operating systems:

  1. ๐Ÿ’ป Windows
  2. ๐Ÿ MacOS - this does not exist yet
  3. ๐Ÿง Linux - not finished yet


  • Espressif Tool VSCode
  • This firmware is designed to run a Bitaxe v2+

๐Ÿ’ป Windows

1. Installation

  1. Install the Espressif tool from here. On this page, you will find a โ€œGet Startedโ€ guide for installing this onto your machine.
  2. Install Visual Studio Code.
  3. Install the Espressif IDF Extention in VSCode.

2. Clone repository

Clone the ESP-Miner repository and open it in VSCode.

3. Configuration

After you have installed everything we need to configure the Espressif Tool.

In Visual Studio Code go to View โ†’ ESP-IDF: Device Configuration โ†’ Device Target โ†’ ESP-Miner โ†’ esp32s3 โ†’ ESP-S3 via USB Bridge


4. Build

Open an ESP-IDF terminal and cd into the /main/http_server/axe-os/ folder because we need to build the WebUI first with:

Terminal window
npm run build

Because the firmware needs to be built from the root directory, cd back to it and then build the firmware with:

Terminal window build



This will generate a build directory at the root of the project and there you will find the www.binand the esp-miner.bin files. These will be uploaded to your Bitaxe.

๐Ÿ MacOS

๐Ÿง Linux

1. Installation

To compile using ESP-IDF, you need to get the following packages. The command to run depends on which distribution of Linux you are using:

Ubuntu & Debian
sudo apt-get install git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0
CentOS 7 & 8
sudo yum -y update && sudo yum install git wget flex bison gperf python3 cmake ninja-build ccache dfu-util libusbx
sudo pacman -S --needed gcc git make flex bison gperf python cmake ninja ccache dfu-util libusb

2. Get ESP-IDF

To build applications for the ESP32, you need the software libraries provided by Espressif in ESP-IDF repository.

To get ESP-IDF, navigate to your installation directory and clone the repository with git clone, following instructions below specific to your operating system.

Open Terminal, and run the following commands:

Terminal window
mkdir -p ~/esp
cd ~/esp
git clone --recursive

ESP-IDF is downloaded into ~/esp/esp-idf.

3. Set up the Tools

Aside from the ESP-IDF, you also need to install the tools used by ESP-IDF, such as the compiler, debugger, Python packages, etc, for projects supporting ESP32.

Terminal window
cd ~/esp/esp-idf
./ esp32s3

4. Setup Environments Variables

The installed tools are not yet added to the PATH environment variable. To make the tools usable from the command line, some environment variables must be set. ESP-IDF provides another script that does that.

In the terminal where you are going to use ESP-IDF, run:

Terminal window
. $HOME/esp/esp-idf/

Note the space between the leading dot and the path!

If you plan to use ESP-IDF frequently, you can create an alias for executing

  1. Copy and paste the following command to your shellโ€™s profile (.profile, .bashrc, .zprofile, etc.)
Terminal window
alias get_idf='. $HOME/esp/esp-idf/'
  1. Refresh the configuration by restarting the terminal session or by running source [path to profile], for example, source ~/.bashrc.

Now you can run get_idf to set up or refresh the ESP-IDF environment in any terminal session.

Clone repository

Clone the ESP-Miner repository and open it in VSCode.