ESP32 project template

Description

This is a project template to create microcontroller apps with automatized firmware builds for ESP32, ESP32-S2, ESP32-S3, ESP32-C6, ESP32-H2 and ESP32-P4 microcontroller boards. It uses for that GitHub Actions and platformio. Use this repository as a template for your own esp32 projects.

Features

• Uses Platformio
• Supports multiple firmwares builds with github actions
• Example code

Prerequisites

• VSCode IDE

• pioarduino IDE for VSCode IDE

Supported boards

If you want to support this project, you can use these affiliate links ...

• ESP32

  • LilyGo T-Beam v0.7/ v1.1 (aliexpress affiliate link)
  • LilyGo TTGO LORA32 v1.6.1 (aliexpress affiliate link)
  • lolin32
  • lolin D32 pro

• ESP32 S2

• ESP32 S3 with dual-core processor

  • LilyGo T-Display S3 (aliexpress affiliate link)
  • LilyGo T-Display-S3 AMOLED (aliexpress affiliate link)
  • LilyGo T-Display-S3 Touch (aliexpress affiliate link)
  • LilyGo T-Display S3 Long (aliexpress affiliate link)
  • LilyGo T-Watch S3 (aliexpress affiliate link)
  • LilyGo T-CameraPlus ESP32-S3 (aliexpress affiliate link)
  • LilyGo T-RGB (aliexpress affiliate link)
  • LilyGo T-Deck (aliexpress affiliate link)
  • LilyGo T-Deck Plus (aliexpress affiliate link)
  • Waveshare ESP32-S3 GEEK (aliexpress affiliate link)
  • Waveshare ESP32-S3 AMOLED 2.06 (aliexpress affiliate link) with 16 MB flash, AMOLED touch display, Wi-Fi 5, BT 5 LE, accelerometer, gyroscope

• ESP32 C6 with WiFi 6 and BT-5 LE

  • NanoESP32-C6 (aliexpress affiliate link) with 16MB flash
  • ESP32-C6 (aliexpress affiliate link) with 4MB flash and W2812 RGB LED
  • LILYGO T-QT C6 (aliexpress affiliate link) with 4 MB flash, touch display, 6-Axis Sensor
  • Waveshare ESP32-C6 AMOLED 2.06 (aliexpress affiliate link) with 16 MB flash, AMOLED touch display, Wi-Fi 6, BT 5 LE, accelerometer, gyroscope

• ESP32 P4 with dual-core processor up to 400 MHz

  • 10.1" ESP32-P4 LCD Display Development Board (aliexpress affiliate link) with 1280x800 Capacitive Touch Screen, Wi-Fi 6, battery and speaker

Get Started

1. Login to github

2. Click on Use this template to create a new git repository

3. Replace the whole content of this README.md file

4. Implement your application in the src/main.cpp

5. Comment your new change in the CHANGELOG.md file

6. Push your changes

git add .

git commit -am "my app"

git push -u origin main

5. Create a new tag to trigger a release, e.g. for v1.0.0

git tag v1.0.0

git push origin v1.0.0

(do not use create release on github)

6. After the CI build, you can find your firmware files under “Releases”. Files with .factory. in the name are meant for the initial flashing via cable. The others are for updates (e.g. OTA) when a factory version is already on the device. The .factory. files also include a pre-installed file system, bootloader, partition scheme, and safeboot partition.

How to flash your microcontroller

Variant A - Online and no need to install an app

• download a .factory.bin or .bin firmware file from releases then flash with: https://mcuw.github.io/ESPConnect/

Variant B - Visual Studio Code

1. Select a board in Visual Studio Code

2. Flash your board

Contribution

Please see CONTRIBUTING.md for details on how to contribute issues, fixes, and patches to this project.

GitHub Actions - Workflow

The release build happens in the build & release workflow: build_release.yml. It creates a release, after creation of a new git tag (named it like v1.0.0).

If you want to test the build on all merge w/o creating a tag then the build workflow is what you looking for: build.yml

Pioarduino

The pioarduino platform supports latest boards like ESP32-C6, ESP32-H2 and ESP32-P4 and others. There is a pioarduino IDE extension which replaces the PlatformIO IDE extension for VSCode.

PlatformIO

PlatformIO is a tool to create microcontroller apps for arduino platforms and compatibles (esp32). You can install the Visual Studio Code extension in the Visual Studio Code IDE.

Python extra_script.py

There is a tiny python script needed to customize the firmware filenames within platformio, see documentation: https://docs.platformio.org/en/stable/scripting/examples/custom_program_name.html

The extra_script.py script gets the platformio env (e.g. lolin32) and the git-tag for the firmware filename. This is required to publish several firmware names in the github artifacts of a release.

CHANGELOG

You can write your changes in the CHANGELOG.md before you create a release. It will be shown under the release page.

Example Release

see Releases on the right sidemenu.

Customize your project

You can reduce and adapt your required boards in the platformio.ini.

Update the CHANGELOG.md file before you are creating a new release. By creating a new git tag you trigger a new release which generate for you the firmwares.

Disclaimer

Contribution and help - if you find an issue or wants to contribute then please do not hesitate to create a pull request or an issue.

We provide our build template as is, and we make no promises or guarantees about this code.