From 66f0cb6041dc44894114a3376d440fcbb7d3bdb4 Mon Sep 17 00:00:00 2001
From: mcuw <112967559+mcuw@users.noreply.github.com>
Date: Sun, 19 Apr 2026 07:37:22 +0200
Subject: [PATCH 1/2] feature(ci): cache pip and platformio core install and
 always use latest platformio version

---
 .github/workflows/build.yml         | 13 ++++++++++---
 .github/workflows/build_release.yml | 13 ++++++++++---
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 9b6a29b..4591a48 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -11,15 +11,22 @@ jobs:
     steps:
       - name: Checkout repo
         uses: actions/checkout@v6
+      # https://github.com/actions/cache
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cache/pip
+            ~/.platformio/.cache
+          key: ${{ runner.os }}-pio
       - name: Set up python
         uses: actions/setup-python@v6
         with:
           architecture: "x64"
       # https://docs.platformio.org/en/latest/core/history.html
-      - name: Install PlatformIO
-        run: python3 -m pip install platformio==6.1.19
+      - name: Install PlatformIO core
+        run: pip install --upgrade platformio
       - name: Build firmwares
-        run: FIRMWARE_VERSION=main platformio run
+        run: FIRMWARE_VERSION=main pio run
       - name: Archive
         uses: actions/upload-artifact@v7
         with:
diff --git a/.github/workflows/build_release.yml b/.github/workflows/build_release.yml
index c16712a..d3430e8 100644
--- a/.github/workflows/build_release.yml
+++ b/.github/workflows/build_release.yml
@@ -9,15 +9,22 @@ jobs:
     steps:
       - name: Checkout repo
         uses: actions/checkout@v6
+      # https://github.com/actions/cache
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cache/pip
+            ~/.platformio/.cache
+          key: ${{ runner.os }}-pio
       - name: Set up python
         uses: actions/setup-python@v6
         with:
           architecture: "x64"
       # https://docs.platformio.org/en/latest/core/history.html
-      - name: Install PlatformIO
-        run: python3 -m pip install platformio==6.1.19
+      - name: Install PlatformIO core
+        run: pip install --upgrade platformio
       - name: Build firmwares
-        run: FIRMWARE_VERSION=${{github.ref_name}} platformio run
+        run: FIRMWARE_VERSION=${{github.ref_name}} pio run
       - name: Archive
         uses: actions/upload-artifact@v7
         with:

From 51c96a67359844e69e702b9ef09d318bfb3b7147 Mon Sep 17 00:00:00 2001
From: mcuw <112967559+mcuw@users.noreply.github.com>
Date: Sun, 19 Apr 2026 07:46:01 +0200
Subject: [PATCH 2/2] doc: add description about .factory. firmwares

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 813e7fb..e496f02 100644
--- a/README.md
+++ b/README.md
@@ -84,12 +84,12 @@ git push origin v1.0.0
 
 (do not use `create release` on github)
 
-6. You can find your firmwares under `Releases` after the CI build finished
+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 `.bin` firmware file from releases then flash with:
+- download a `.factory.bin` or `.bin` firmware file from releases then flash with:
 https://mcuw.github.io/ESPConnect/
 
 Variant B - Visual Studio Code