mirror of
https://github.com/meshtastic/meshtastic.git
synced 2024-11-16 18:44:16 -08:00
66 lines
3.1 KiB
Plaintext
66 lines
3.1 KiB
Plaintext
---
|
|
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 :-)
|