From 8029d3dab13fb5ab232140ceaf8c2e0680787275 Mon Sep 17 00:00:00 2001 From: mcuw <112967559+mcuw@users.noreply.github.com> Date: Thu, 30 Mar 2023 09:09:07 +0200 Subject: [PATCH] Initial commit --- .github/FUNDING.yml | 12 +++ .github/workflows/build.yml | 28 +++++ .github/workflows/build_release.yml | 50 +++++++++ .gitignore | 5 + .vscode/extensions.json | 10 ++ CHANGELOG.md | 5 + LICENSE | 21 ++++ README.md | 53 ++++++++++ extra_script.py | 8 ++ include/README | 39 +++++++ lib/README | 46 ++++++++ platformio.ini | 157 ++++++++++++++++++++++++++++ src/main.cpp | 12 +++ test/README | 11 ++ 14 files changed, 457 insertions(+) create mode 100644 .github/FUNDING.yml create mode 100644 .github/workflows/build.yml create mode 100644 .github/workflows/build_release.yml create mode 100644 .gitignore create mode 100644 .vscode/extensions.json create mode 100644 CHANGELOG.md create mode 100644 LICENSE create mode 100644 README.md create mode 100644 extra_script.py create mode 100644 include/README create mode 100644 lib/README create mode 100644 platformio.ini create mode 100644 src/main.cpp create mode 100644 test/README diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..1ad38ae --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,12 @@ +# These are supported funding model platforms + +github: [mcuw, vanvuongngo] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2] +patreon: # Replace with a single Patreon username +open_collective: # Replace with a single Open Collective username +ko_fi: # Replace with a single Ko-fi username +tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel +community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry +liberapay: # Replace with a single Liberapay username +issuehunt: # Replace with a single IssueHunt username +otechie: # Replace with a single Otechie username +custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2'] diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000..490c30c --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,28 @@ +on: + push: + tags-ignore: + - '**' + pull_request: + branches: [main] +jobs: + build: + name: Build + runs-on: ubuntu-latest + steps: + - name: Checkout repo + uses: actions/checkout@v3 + - name: Set up python + uses: actions/setup-python@v4 + with: + python-version: '3.x' + architecture: 'x64' + - name: Install PlatformIO + run: python -m pip install platformio==6.1.6 + - name: Build firmwares + run: FIRMWARE_VERSION=main platformio run + - name: Archive + uses: actions/upload-artifact@v3 + with: + name: firmware + path: .pio/build/*/firmware_*.bin + retention-days: 1 \ No newline at end of file diff --git a/.github/workflows/build_release.yml b/.github/workflows/build_release.yml new file mode 100644 index 0000000..0b4fd1f --- /dev/null +++ b/.github/workflows/build_release.yml @@ -0,0 +1,50 @@ +on: + push: + tags: + - '*' + pull_request: + branches: [main] +jobs: + build: + name: Build + runs-on: ubuntu-latest + steps: + - name: Checkout repo + uses: actions/checkout@v3 + - name: Set up python + uses: actions/setup-python@v4 + with: + python-version: '3.x' + architecture: 'x64' + - name: Install PlatformIO + run: python -m pip install platformio==6.1.6 + - name: Build firmwares + run: FIRMWARE_VERSION=${{github.ref_name}} platformio run + - name: Archive + uses: actions/upload-artifact@v3 + with: + name: firmware + path: .pio/build/*/firmware_*.bin + retention-days: 1 + release: + name: Release + # if: startsWith(github.event.ref, 'refs/tags/v') + needs: build + permissions: + contents: write + runs-on: ubuntu-latest + steps: + - name: Checkout repo for CHANGELOG + uses: actions/checkout@v3 + - name: Download artifacts + uses: actions/download-artifact@v3 + with: + name: firmware + path: firmware + # - name: Display structure of downloaded files + # run: ls -R + - name: release + uses: ncipollo/release-action@v1 + with: + artifacts: "firmware/*/firmware_*.bin" + bodyFile: "CHANGELOG.md" \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..89cc49c --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +.pio +.vscode/.browse.c_cpp.db* +.vscode/c_cpp_properties.json +.vscode/launch.json +.vscode/ipch diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..080e70d --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,10 @@ +{ + // See http://go.microsoft.com/fwlink/?LinkId=827846 + // for the documentation about the extensions.json format + "recommendations": [ + "platformio.platformio-ide" + ], + "unwantedRecommendations": [ + "ms-vscode.cpptools-extension-pack" + ] +} diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..18c1792 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,5 @@ +CHANGELOG + +## v0.0.0 + +PLEASE WRITE YOUR CHANGES BEFORE YOU CREATE A RELEASE IN THE CHANGELOG.MD FILE! diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..2dcaf1c --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2023 mcuw + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..9d21c56 --- /dev/null +++ b/README.md @@ -0,0 +1,53 @@ +# ESP32 project template + +## Description + +This is a project template to create microcontroller apps with automatized firmware builds for [esp32](https://www.espressif.com/en/products/socs/esp32), [esp32s2](https://www.espressif.com/en/products/socs/esp32-s2) and [esp32s3](https://www.espressif.com/en/products/socs/esp32-s3) microcontroller boards. It uses for that [GitHub Actions](https://github.com/features/actions) and [platformio](https://platformio.org/). + + +## Requirements + +- [GitHub Actions](https://github.com/features/actions) +- [platformio](https://platformio.org/) +- [python](https://www.python.org/) + + +## GitHub Actions - Workflow + +The release build happens in the `build & release` workflow: [build_release.yml](.github/workflows/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](.github/workflows/build.yml) + + +## PlatformIO + +[PlatformIO](https://platformio.org/) is a tool to create microcontroller apps for arduino platforms and compatibles (esp32). You can install the [Visual Studio Code extension](https://platformio.org/install/ide?install=vscode) in the [Visual Studio Code](https://code.visualstudio.com/) IDE. + + +## Python + +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](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](CHANGELOG.md) before you create a release. It will be shown under the release page. + +## Example Release + +see [Releases](https://github.com/mcuw/esp-ghbuild-template/releases) on the right sidemenu. + +## Usage + +Use this repository as a template for your own esp32 repository. You can reduce and adapt your required boards in the [platformio.ini](platformio.ini). Update the [CHANGELOG.md](CHANGELOG.md) file before you are creating a new release. When you create a new git tag then a new release will always includes generated firmwares. + +--- + +## Disclaimer + +Contribution and help ... if you find an issue or wants to contribute then please do not hesitate to create a merge request or an issue. + +We provide our build template as is, and we make no promises or guarantees about this code. diff --git a/extra_script.py b/extra_script.py new file mode 100644 index 0000000..cd1042f --- /dev/null +++ b/extra_script.py @@ -0,0 +1,8 @@ +import os +Import("env") + +# Access to global construction environment +build_tag = env['PIOENV'] +version_tag = os.getenv("FIRMWARE_VERSION") + +env.Replace(PROGNAME="firmware_%s_%s" % (build_tag, version_tag)) \ No newline at end of file diff --git a/include/README b/include/README new file mode 100644 index 0000000..194dcd4 --- /dev/null +++ b/include/README @@ -0,0 +1,39 @@ + +This directory is intended for project header files. + +A header file is a file containing C declarations and macro definitions +to be shared between several project source files. You request the use of a +header file in your project source file (C, C++, etc) located in `src` folder +by including it, with the C preprocessing directive `#include'. + +```src/main.c + +#include "header.h" + +int main (void) +{ + ... +} +``` + +Including a header file produces the same results as copying the header file +into each source file that needs it. Such copying would be time-consuming +and error-prone. With a header file, the related declarations appear +in only one place. If they need to be changed, they can be changed in one +place, and programs that include the header file will automatically use the +new version when next recompiled. The header file eliminates the labor of +finding and changing all the copies as well as the risk that a failure to +find one copy will result in inconsistencies within a program. + +In C, the usual convention is to give header files names that end with `.h'. +It is most portable to use only letters, digits, dashes, and underscores in +header file names, and at most one dot. + +Read more about using header files in official GCC documentation: + +* Include Syntax +* Include Operation +* Once-Only Headers +* Computed Includes + +https://gcc.gnu.org/onlinedocs/cpp/Header-Files.html diff --git a/lib/README b/lib/README new file mode 100644 index 0000000..6debab1 --- /dev/null +++ b/lib/README @@ -0,0 +1,46 @@ + +This directory is intended for project specific (private) libraries. +PlatformIO will compile them to static libraries and link into executable file. + +The source code of each library should be placed in a an own separate directory +("lib/your_library_name/[here are source files]"). + +For example, see a structure of the following two libraries `Foo` and `Bar`: + +|--lib +| | +| |--Bar +| | |--docs +| | |--examples +| | |--src +| | |- Bar.c +| | |- Bar.h +| | |- library.json (optional, custom build options, etc) https://docs.platformio.org/page/librarymanager/config.html +| | +| |--Foo +| | |- Foo.c +| | |- Foo.h +| | +| |- README --> THIS FILE +| +|- platformio.ini +|--src + |- main.c + +and a contents of `src/main.c`: +``` +#include +#include + +int main (void) +{ + ... +} + +``` + +PlatformIO Library Dependency Finder will find automatically dependent +libraries scanning project source files. + +More information about PlatformIO Library Dependency Finder +- https://docs.platformio.org/page/librarymanager/ldf.html diff --git a/platformio.ini b/platformio.ini new file mode 100644 index 0000000..7155d2b --- /dev/null +++ b/platformio.ini @@ -0,0 +1,157 @@ +; https://docs.platformio.org/en/latest/platforms/espressif32.html + +[env] +build_flags = + ; coding_standards + -Wno-unused-variable + -Wno-unused-but-set-variable + -Wunreachable-code + + ; debug level 5=VERBOSE https://docs.platformio.org/en/latest/platforms/espressif32.html#debug-level + ; -DCORE_DEBUG_LEVEL=5 +extra_scripts = pre:extra_script.py +framework = arduino +lib_deps = + ; place global libs here or under extra.lib_deps_external (see below) +monitor_speed = 115200 +platform = espressif32 +upload_speed = 921600 + +; CUSTOM options +; You need manually inject these options into a section +; using ${extra.} (see below) +[extra] +; https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/external-ram.html +build_flags_psram = + -DBOARD_HAS_PSRAM + -mfix-esp32-psram-cache-issue ; https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/external-ram.html#esp32-rev-v1 +lib_deps_builtin = + SPI + Wire +lib_deps_external = + ; extend libs for all platforms here + +[esp32] +build_flags = + ${env.build_flags} +lib_deps = + ${env.lib_deps} + ${extra.lib_deps_builtin} + ${extra.lib_deps_external} + ; extend libs only for esp32 based modules here + +[esp32s2] +build_flags = + ${env.build_flags} +lib_deps = + ${env.lib_deps} + ${extra.lib_deps_builtin} + ${extra.lib_deps_external} + ; extend libs only for esp32s2 based modules here + +[esp32s3] +build_flags = + ${env.build_flags} +lib_deps = + ${env.lib_deps} + ${extra.lib_deps_builtin} + ${extra.lib_deps_external} + ; extend libs only for esp32s3 based modules here + + +; ********* +; * ESP32 * +; ********* + +; https://docs.platformio.org/en/latest/platforms/espressif32.html +[env:esp32dev] +extends = esp32 +board = esp32dev +build_flags = + ${esp32.build_flags} +lib_deps = + ${esp32.lib_deps} + +; https://docs.platformio.org/en/latest/boards/espressif32/lolin32.html +[env:lolin32] +extends = esp32 +board = lolin32 +build_flags = + ${esp32.build_flags} +lib_deps = + ${esp32.lib_deps} + +; https://docs.platformio.org/en/latest/boards/espressif32/lolin_d32_pro.html +; https://www.wemos.cc/en/latest/d32/d32_pro.html +[env:lolin-d32-pro] +extends = esp32 +board = lolin_d32_pro +build_flags = + ${esp32.build_flags} + ${extra.build_flags_psram} ; 4MB PSRAM +lib_deps = + ${esp32.lib_deps} + +; https://www.lilygo.cc/products/t-beam-v1-1-esp32-lora-module +[env:ttgo-t-beam] +extends = esp32 +board = ttgo-t-beam +build_flags = + ${esp32.build_flags} + ${extra.build_flags_psram} ; 8MB PSRAM +lib_deps = + ${esp32.lib_deps} + +; ************ +; * ESP32-S2 * +; ************ + +; TODO http://www.lilygo.cn/prod_view.aspx?TypeId=50033&Id=1321 with psram +; https://github.com/Xinyuan-LilyGO/LilyGo-T-Display-S2 +[env:lilygo-t-display-s2] +extends = esp32s2 +board = esp32dev ; no platformio support? + + +; ************ +; * ESP32-S3 * +; ************ + +; https://docs.platformio.org/en/latest/boards/espressif32/esp32s3box.html +[env:esp32s3box] +extends = esp32s3 +board = esp32s3box +build_flags = + ${esp32s3.build_flags} +lib_deps = + ${esp32s3.lib_deps} + +; https://docs.platformio.org/en/latest/boards/espressif32/esp32-s3-devkitc-1.html +[env:esp32-s3-devkitc-1] +extends = esp32s3 +board = esp32-s3-devkitc-1 +build_flags = + ${esp32s3.build_flags} + ; PSRAM is optional +lib_deps = + ${esp32s3.lib_deps} + +; https://docs.platformio.org/en/latest/boards/espressif32/lilygo-t-display-s3.html +; https://www.lilygo.cc/products/t-display-s3 +; https://github.com/Xinyuan-LilyGO/T-Display-S3 +[env:lilygo-t-display-s3] +extends = env:esp32-s3-devkitc-1 ; no platformio support? +; board = lilygo-t-display-s3 ; no platformio support? +build_flags = + ${esp32s3.build_flags} + ${extra.build_flags_psram} ; 8MB PSRAM +lib_deps = + ${esp32s3.lib_deps} + +; https://www.antratek.com/wt32-sco1-plus +; https://www.seeedstudio.com/WT32-3-5-Inch-Display-p-5542.html +[env:wt32-sc01-plus] +extends = env:esp32-s3-devkitc-1 +build_flags = + ${env:esp32-s3-devkitc-1.build_flags} + ${extra.build_flags_psram} ; 2MB PSRAM diff --git a/src/main.cpp b/src/main.cpp new file mode 100644 index 0000000..e73b4d2 --- /dev/null +++ b/src/main.cpp @@ -0,0 +1,12 @@ +#include + +void setup() { + Serial.begin(115200); + while (!Serial); + +} + +void loop() { + Serial.println("Hello World"); + delay(2000); +} \ No newline at end of file diff --git a/test/README b/test/README new file mode 100644 index 0000000..9b1e87b --- /dev/null +++ b/test/README @@ -0,0 +1,11 @@ + +This directory is intended for PlatformIO Test Runner and project tests. + +Unit Testing is a software testing method by which individual units of +source code, sets of one or more MCU program modules together with associated +control data, usage procedures, and operating procedures, are tested to +determine whether they are fit for use. Unit testing finds problems early +in the development cycle. + +More information about PlatformIO Unit Testing: +- https://docs.platformio.org/en/latest/advanced/unit-testing/index.html