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 pioarduino/ for old boards 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

You can use these links to buy a developer board. If you want to support this project then use the affiliate links marked with a *. For you it does not cost more.

• ESP32

  • LilyGo T-Beam v0.7/ v1.1*
  • LilyGo TTGO LORA32 v1.6.1*
  • lolin32
  • lolin D32 pro

• ESP32 S2

• ESP32 S3 with dual-core processor

  • LilyGo T-Display S3*
  • LilyGo T-Display-S3 AMOLED*
  • LilyGo T-Display-S3 Touch*
  • LilyGo T-Display S3 Long*
  • LilyGo T-Watch S3*
  • LilyGo T-CameraPlus ESP32-S3*
  • LilyGo T-RGB*
  • LilyGo T-Deck*
  • LilyGo T-Deck Plus*
  • Waveshare ESP32-S3 GEEK*
  • Waveshare ESP32-S3 AMOLED 2.06* 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* with 16MB flash
  • ESP32-C6* with 4MB flash and W2812 RGB LED
  • LILYGO T-QT C6* with 4 MB flash, touch display, 6-Axis Sensor
  • Waveshare ESP32-C6 AMOLED 2.06* 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* with 1280x800 Capacitive Touch Screen, Wi-Fi 6, battery and speaker

Protoyping

If you are new to the Arduino world then play around with free online simulators before you create a new repository or soldering. Deep dive into the arduino programming.

• Cirkit designer
• Wokwi

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. Use "create release" option on github to trigger a firmware build (input a new tag version, e.g. v1.0.0)

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. Default env builds all boards.

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 the firmware build to your dev board with the "default_envs=" configuration.

Or override the boards configs with a new .ini file under extra_connfigs and import it 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.