mirror of
https://github.com/meshtastic/meshtastic.git
synced 2024-11-15 18:14:19 -08:00
82 lines
4.6 KiB
Plaintext
82 lines
4.6 KiB
Plaintext
---
|
|
id: build
|
|
title: Building Meshtastic Firmware
|
|
sidebar_label: Building Firmware
|
|
sidebar_position: 2
|
|
---
|
|
|
|
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
|
|
cd firmware && git submodule update --init
|
|
```
|
|
:::info
|
|
If you want to build the RP2040 targets and get a 'Filename too long' error on Windows, please refer to [the Platformio documentation for this toolchain](https://arduino-pico.readthedocs.io/en/latest/platformio.html#important-steps-for-windows-users-before-installing)
|
|
:::
|
|
|
|
## Build
|
|
|
|
1. Open the newly cloned folder in [Visual Studio Code](https://code.visualstudio.com). If you do this for the first time, this can take quite some while as PlatformIO will download all the necessary tooling and libraries. Also if platformio is not installed, VSCode will ask you to install it, probably requiring a restart of the program.
|
|
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: Pick 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)[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 `architecture.h` on the firmware repo in the folder of the platform you are using, and send in that Pull Request too.
|
|
6. Wait for the Pulls to be merged back into Master.
|
|
7. Profit :-)
|
|
|
|
## Alternative route: Gitpod
|
|
|
|
Gitpod offers an alternative method for compiling the firmware without installing Visual Studio Code. It is a web browser-based online IDE that can be used with a GitHub account. Gitpod provides a free tier suitable for light use, such as compiling custom firmware.
|
|
|
|
1. Go to (https://gitpod.io#https://github.com/meshtastic/firmware)[https://gitpod.io#https://github.com/meshtastic/firmware].
|
|
2. Make the desired changes to the chosen variant.
|
|
3. Build the firmware by running: `pio run -e <variant_name>`
|
|
4. Once complete, download `<variant_name>.bin` or `<variant_name>.uf2` from `/workspace/firmware/.pio/build/<variant_name>.`
|
|
5. As flashing directly to the device isn't possible using Gitpod, upload using either:
|
|
- [Drag & Drop](/docs/getting-started/flashing-firmware/nrf52/#drag--drop) for NRF52/RP2040 devices.
|
|
- [Web flasher](https://flasher.meshtastic.org/) for ESP32 devices.
|