meshtastic/docs/development/firmware/building.mdx

---
id: build
title: Building Meshtastic Firmware
sidebar_label: Building Firmware
---

Meshtastic uses [PlatformIO](https://platformio.org), a development environment that enables easy multi-platform development and centralized tooling.

## Setup the Build Environment

1. [Install PlatformIO](https://platformio.org/platformio-ide)
2. Clone the [Meshtastic Firmware](https://github.com/meshtastic/firmware) repository
   ```shell
   git clone https://github.com/meshtastic/firmware.git
   ```
3. Update the repository's [submodules](https://github.com/meshtastic/firmware/blob/master/.gitmodules)
   ```shell
   git submodule update --init
   ```

## Build

1. Open the newly cloned folder in [Visual Studio Code](https://code.visualstudio.com).
2. To select the device you you wish to build, open your [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette):
   - Windows: `Ctrl + Shift + P`
   - Mac: `command + Shift + P`
3. Enter: `platformio: Switch Project Environment` and select your target.
4. To build the firmware, simply run `PlatformIO: Build` from your command palette.
5. Finally, flash the firmware to your device by running `PlatformIO: Upload`

## Adding Custom Hardware

The build system is modular. Adding a new board variant for an already supported architecture is straightforward.

### Build with Custom Hardware

1. Go to the `variants` folder in the firmware source code and make a new directory for your hardware, let's call it `m5stack_atom` and copy an existing configuration you wanna modify:
   ```shell
   cd variants; mkdir m5stack_atom
   cp heltec_v1/* m5stack_atom
   cd m5stack_atom
   ```
2. Modify the `platformio.ini`_in this subdirectory_ from the canonical define of the hardware variant (`HELTEC_V1` in this case) to `PRIVATE_HW` and make the `-I` on the `build_flags` point to the newly created dir.
   ```shell
   [env:m5stack-atom]
   extends = esp32_base
   board = m5stack-atom
   monitor_filters = esp32_exception_decoder
   build_flags =
      ${esp32_base.build_flags} -D PRIVATE_HW -I variants/m5stack_atom
   lib_deps =
      ${esp32_base.lib_deps}
   ```
3. Edit the `variant.h` file _in this subdirectory_ to reflect the defines and configurations for your board. The example is very well commented.
4. Build, run and debug until you are satisfied with the result.

### Distribute / Publish Custom Builds

1. Perform all of the steps [building with custom hardware](#build-with-custom-hardware) until your hardware runs fine.
2. [Send a proposal](https://github.com/meshtastic/firmware/issues/new?assignees=&labels=enhancement%2Ctriage&template=New+Board.yml&title=%5BBoard%5D%3A+) to add a new board.
3. If approved, go to (https://github.com/meshtastic/protobufs) and send a Pull Request for the `mesh.proto` file, adding your board to the `HardwareModel` Enum.
4. Change your define in `platformio.ini` from `PRIVATE_HW` to `YOUR_BOARD`. Adjust any macro guards in the code you need to support your board.
5. Add your board identifier to `configuration.h` on the firmware repo and send in that Pull Request too.
6. Wait for the Pulls to be merged back into Master.
7. Profit :-)