chore(build): Implement ESP web tools for initial device setup (#178)

Slider0007 · Oct 17, 2024 · dfb0b7c · dfb0b7c
1 parent 7b6083f
commit dfb0b7c
Show file tree

Hide file tree

Showing 6 changed files with 176 additions and 21 deletions.
diff --git a/.github/workflows/build-release.yaml b/.github/workflows/build-release.yaml
@@ -106,6 +106,7 @@ jobs:
         echo "Update hash..."
         cd ./html; find . -type f -exec sed -i 's/$COMMIT_HASH/${{ steps.vars.outputs.sha_short }}/g' {} \;
 
+
     #########################################################################################
     ## Create firmware package
     # - Inital flashing using web installer, device's access point or serial console
@@ -170,6 +171,9 @@ jobs:
 #########################################################################################
   upload-release-artifacts:
     runs-on: ubuntu-latest
+    outputs:
+      branch: ${{ steps.vars.outputs.branch }}
+      sha_short: ${{ steps.vars.outputs.sha_short }}
     needs: [prepare-release, build]
     if: ${{ needs.prepare-release.outputs.release_created }}
     strategy:
@@ -203,10 +207,10 @@ jobs:
       run: |
         rm -rf release
         mkdir -p release
-        cd "AI-on-the-edge-device__${{ matrix.plat }}__SLFork_${{ steps.vars.outputs.branch }}_(${{ steps.vars.outputs.sha_short }})"
+        cd "AI-on-the-edge-device__${{ matrix.plat }}__SLFork_${{ steps.vars.outputs.branch }}_${{ steps.vars.outputs.sha_short }}"
         zip -r ../release/AI-on-the-edge-device__${{ matrix.plat }}__SLFork_v${{ needs.prepare-release.outputs.version }}.zip *
         cd ..
-        cd "AI-on-the-edge-device__${{ matrix.plat }}__debug-files__SLFork_${{ steps.vars.outputs.branch }}_(${{ steps.vars.outputs.sha_short }})"
+        cd "AI-on-the-edge-device__${{ matrix.plat }}__debug-files__SLFork_${{ steps.vars.outputs.branch }}_${{ steps.vars.outputs.sha_short }}"
         zip -r ../release/AI-on-the-edge-device__${{ matrix.plat }}__debug-files__SLFork_v${{ needs.prepare-release.outputs.version }}.zip *
         cd ..
 
@@ -215,3 +219,65 @@ jobs:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       run:
         gh release upload ${{ needs.prepare-release.outputs.tag_name }} release/*
+
+
+#########################################################################################
+## Update web installer (branch: gh-pages-webinstaller)
+#
+# Firmware files are commited to branch gh-pages-webinstaller
+#########################################################################################
+  update-webinstaller:
+    runs-on: ubuntu-latest
+    needs: [prepare-release, build, upload-release-artifacts]
+    if: ${{ needs.prepare-release.outputs.release_created }}
+    strategy:
+      max-parallel: 1
+      fail-fast: false
+      matrix:
+        plat:
+         - esp32cam
+         - xiao-esp32s3-sense
+
+    # Sets permissions of the GITHUB_TOKEN to allow downloading artifacts
+    permissions:
+      actions: read
+      contents: write
+
+    steps:
+    - name: Checkout branch gh-pages-webinstaller
+      uses: actions/checkout@v4
+      with:
+        ref: gh-pages-webinstaller
+
+    - name: Pull artifact
+      uses: actions/download-artifact@v4
+      with:
+        name: "AI-on-the-edge-device__${{ matrix.plat }}__SLFork_${{ needs.upload-release-artifacts.outputs.branch }}_${{ needs.upload-release-artifacts.outputs.sha_short }}"
+        path: './artifacts/'
+
+    - name: Prepare data
+      run: |
+        echo "Updating files ..."
+        cd ./artifacts
+        ls
+        cd ..
+        cp -f ./artifacts/bootloader.bin ./firmware/${{ matrix.plat }}/bootloader.bin
+        cp -f ./artifacts/partitions.bin ./firmware/${{ matrix.plat }}/partitions.bin
+        cp -f ./artifacts/firmware.bin ./firmware/${{ matrix.plat }}/firmware.bin
+
+        echo "Updating version strings (index.html, manifest) ..."
+        sed -i -E 's/Firmware: .*./\Firmware: <b\>${{ needs.prepare-release.outputs.tag_name }}\<\/b\>/g' index.html
+        sed -i -E 's/"version":.*.,/"version": "${{ needs.prepare-release.outputs.tag_name }}",/g' manifest_${{ matrix.plat }}.json
+
+    - name: Commit data to branch gh-pages-webinstaller
+      shell: pwsh
+      run: |
+        & git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
+        & git config --local user.name "github-actions[bot]"
+        & git add .
+        & git diff HEAD --exit-code | Out-Null
+        if ($LASTEXITCODE -ne 0)
+        {
+          & git commit -m "${{ matrix.plat }}: Update firmware files to ${{ needs.prepare-release.outputs.tag_name }}"
+          & git push
+        }
diff --git a/.github/workflows/update-webinstaller.yaml b/.github/workflows/update-webinstaller.yaml
@@ -0,0 +1,66 @@
+name: Update Web Installer
+
+on:
+  workflow_dispatch:
+
+
+jobs:
+  update-webinstaller:
+    runs-on: ubuntu-latest
+    strategy:
+      max-parallel: 1
+      fail-fast: false
+      matrix:
+        plat:
+         - esp32cam
+         - xiao-esp32s3-sense
+
+    # Sets permissions of the GITHUB_TOKEN to allow downloading artifacts
+    permissions:
+      actions: read
+      contents: write
+
+    steps:
+    - name: Checkout branch gh-pages-webinstaller
+      uses: actions/checkout@v4
+      with:
+        ref: gh-pages-webinstaller
+
+    - name: Pull artifact from latest release
+      id: pull_artifacts
+      uses: dsaltares/fetch-gh-release-asset@master
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        regex: true
+        file: "AI-on-the-edge-device__${{ matrix.plat }}__SLFork_.*.zip"
+        target: './artifacts/'
+
+    - name: Prepare data
+      run: |
+        echo "Updating files ..."
+
+        rm -rf "./firmware/${{ matrix.plat }}/"
+        mkdir -p "./firmware/${{ matrix.plat }}/"
+
+        unzip ./artifacts/AI-on-the-edge-device__${{ matrix.plat }}__SLFork_*.zip -d ./artifacts/
+
+        cp -f ./artifacts/firmware.bin ./firmware/${{ matrix.plat }}/bootloader.bin
+        cp -f ./artifacts/partitions.bin ./firmware/${{ matrix.plat }}/partitions.bin
+        cp -f ./artifacts/firmware.bin ./firmware/${{ matrix.plat }}/firmware.bin
+
+        echo "Updating version strings (index.html, manifest) ..."
+        sed -i -E 's/Firmware: .*./\Firmware: <b\>${{ steps.pull_artifacts.outputs.version }}\<\/b\>/g' index.html
+        sed -i -E 's/"version":.*.,/"version": "${{ steps.pull_artifacts.outputs.version }}",/g' manifest_${{ matrix.plat }}.json
+
+    - name: Commit data to branch gh-pages-webinstaller
+      shell: pwsh
+      run: |
+        & git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
+        & git config --local user.name "github-actions[bot]"
+        & git add .
+        & git diff HEAD --exit-code | Out-Null
+        if ($LASTEXITCODE -ne 0)
+        {
+          & git commit -m "${{ matrix.plat }}: Update firmware files to ${{ steps.pull_artifacts.outputs.version }}"
+          & git push
+        }
diff --git a/README.md b/README.md
@@ -1,10 +1,10 @@
 # AI-on-the-Edge device [SL Fork]
 <img src="images/icon/watermeter.svg" width="80px"> 
 
-Artificial intelligence based systems have become established in our everyday lives. Just think of speech or image recognition. Most of the systems rely on either powerful processors or a direct connection to the cloud for doing the calculations there. With the increasing power of modern processors, the AI systems are coming closer to the end user – which is usually called **edge computing**.
-Here, this edge computing is put into a practically oriented example, where an AI network is implemented on an ESP32 series based device so: **AI on the Edge**.
+Artificial intelligence is everywhere, from speech to image recognition. While most AI systems rely on powerful processors or cloud computing, **edge computing** brings AI closer to the end user by utilizing the capabilities of modern processors.  
+This project demonstrates edge computing using a low-cost, AI-capable Espressif SOC device (e.g. **ESP32**), to digitize your analog meters — whether water, gas or electricity. With affordable hardware and simple instructions, you can turn any standard meter into a smart device.
 
-This project allows you to digitize your **analog** water, gas, power and other meters using a low-cost system on a chip microcontroller.
+Let's explore how to make **AI on the Edge** a reality!
 
 
 ## Key features
@@ -25,16 +25,16 @@ This project allows you to digitize your **analog** water, gas, power and other
 The device takes an image of your meter at a defined interval. It extracts the Regions of Interest (ROIs) from the image and runs them through artificial intelligence. 
 As a result, you get the digitized value of your meter. There are several options for what to do with that value. Either send it to a MQTT broker, write it to InfluxDB or simply provide access to it via a REST API (JSON / HTML).
 
-<img src="https://raw.githubusercontent.com/Slider0007/AI-on-the-edge-device/develop/images/idea.jpg" width="800"> 
+<img src="images/idea.jpg" width="800"> 
 
 
 ## Impressions
 ### Hardware
-<img src="https://raw.githubusercontent.com/Slider0007/AI-on-the-edge-device/develop/images/watermeter_all.jpg" width="266"><img src="https://raw.githubusercontent.com/Slider0007/AI-on-the-edge-device/develop/images/main.jpg" width="266"><img src="https://raw.githubusercontent.com/Slider0007/AI-on-the-edge-device/develop/images/size.png" width="266"> 
+<img src="images/watermeter_all.jpg" width="266"><img src="images/main.jpg" width="266"><img src="images/size.png" width="266"> 
 
 
 ### Web Interface
-<img src="https://raw.githubusercontent.com/Slider0007/AI-on-the-edge-device/develop/images/webinterface_overview.png" width="800"> 
+<img src="images/webinterface_overview.png" width="800"> 
 
 
 ## Supported Hardware
@@ -44,20 +44,38 @@ As a result, you get the digitized value of your meter. There are several option
 | [XIAO ESP32 Sense](https://www.seeedstudio.com/XIAO-ESP32S3-Sense-p-5639.html) | ESP32S3  | $\ge$ v17.0.0 |- No onboard illumination: Separate illumination (PWM controlable LED / Intelligent LED) necessary<br>- Running quite hot, small heat sink recommended
 
 
-## Device Installation
-### 1. Inform Yourself
+## Inform Yourself
 There is growing [documentation](https://jomjol.github.io/AI-on-the-edge-device-docs/) which provides you with a lot of information. Head there to get a start, how to set it up and configure it.<br>
 ⚠️ Not every description is 100% suitable for this fork. Therefore please check `docs` folder of this repository for any fork specific documentation.
 
 Small selection of youtube videos which might give you an idea how to getting started:<br>[Video 1](https://www.youtube.com/watch?v=HKBofb1cnNc), [Video 2](https://www.youtube.com/watch?v=yyf0ORNLCk4), [Video 3](https://www.youtube.com/watch?v=XxmTubGek6M), [Video 4](https://www.youtube.com/watch?v=mDIJEyElkAU), [Video 5](https://www.youtube.com/watch?v=SssiPkyKVVs), [Video 6](https://www.youtube.com/watch?v=MAHE_QyHZFQ), [Video 7](https://www.youtube.com/watch?v=Uap_6bwtILQ)
 
 
-### 2. Download Firmware Package
+## Firmware installation
+
+There are multiple options to install the firmware and the SD card content.
+
+### Download Firmware Package
 Officially released firmware packages can be downloaded from [releases](https://github.com/slider0007/AI-on-the-edge-device/releases) page.<br>
 A possibly already available development version (upcoming release version) can be previewed [here](https://github.com/Slider0007/AI-on-the-edge-device/pulls?q=is%3Aopen+is%3Apr+label%3A%22autorelease%3A+pending%22).
 
+### Option 1: Web Installer (Only For Released Versions)
+
+#### Step 1: Installation Of MCU Part Of Firmware
+
+Follow the instructions listed at [Web Installer](https://slider0007.github.io/AI-on-the-edge-device/) page:
+
+<img src="images/webinstaller_home.jpg"> 
+
+#### Step 2: Installation Of SD Card Content
+
+Please follow the instructions in the following chapter ["Installation Of SD Card Content"](#step-2-installation-of-sd-card-content).
+
+---
+### Option 2: Manual Installation (MCU + SD Card)
+
+#### Step 1: Installation Of MCU Part Of Firmware
 
-### 3. Install MCU Part Of Firmware
 Initially the MCU of the device has to be flashed via a USB / serial connection.<br>
 Use content of `AI-on-the-edge-device__{Board Type}__*.zip`.
 
@@ -66,26 +84,26 @@ Use content of `AI-on-the-edge-device__{Board Type}__*.zip`.
 There are different ways to flash the microcontroller:
 - [Espressif Flash Tool](https://www.espressif.com/sites/default/files/tools/flash_download_tool_3.9.5.zip)<br>
 - [ESPtool (command-line tool)](https://docs.espressif.com/projects/esptool/en/latest/esp32/esptool/index.html)
-- Web installer is not yet supported by this fork
 
-Check readme file in firmware package and [documentation](https://jomjol.github.io/AI-on-the-edge-device-docs/Installation/) for more information.<br>
+Check readme file in firmware package and [documentation](https://jomjol.github.io/AI-on-the-edge-device-docs/Installation/#manual-flashing) for further details.
 
 
-### 4. Prepare SD Card Content
+#### Step 2: Installation Of SD Card Content
 A SD card is mandatory to operate the device because of internal device memory is insufficient to handle all necessary files. Therefore the SD card needs to be preloaded with some file content to be able to operate the device.<br>
 
 ⚠️ Make sure, SD card is formated properly (FAT or FAT32 file system).<br>
 
 Use firmware package `AI-on-the-edge-device__{Board Type}__*.zip` for installation process.<br>
 ⚠️ Do not use github source files, use only release related zip package. Otherwise functionality cannot be fully guaranteed or is limited!<br>
 
-#### Manual Installation
+##### Option 1: Manual SD Card Installation
 - Copy complete `config` and `html` folder of `AI-on-the-edge-device__{Board Type}__*.zip` to SD card root folder
-- Copy file `config/template/config.json` to `config` folder, configure WLAN and credentials
+- Copy file `config/template/config.json` to `config` folder
+- Configure WLAN and credentials
 - Insert SD-card to device and boot device
 
-#### Access Point --> See the [documentation](https://jomjol.github.io/AI-on-the-edge-device-docs/Installation/#remote-setup-using-the-built-in-access-point) for details.
-- Connect to device's WLAN hotspot [http://192.168.4.1](http://192.168.4.1). (Channel 11 | Open network)
+##### Option 2: Access Point --> See [documentation](https://jomjol.github.io/AI-on-the-edge-device-docs/Installation/#remote-setup-using-the-built-in-access-point) for details
+- Connect to device's WLAN hotspot [http://192.168.4.1](http://192.168.4.1) (Channel 11 | Open network)
 - Configure WLAN and credentials
 - Upload firmware package (Use `AI-on-the-edge-device__{Board Type}__*.zip`)
 - Reboot device
@@ -102,7 +120,7 @@ See [MQTT API Documentation](docs/API/MQTT/_OVERVIEW.md) in github repository or
 
 
 ## Build Yourself
-See [Build Instructions](code/README.md)
+See [Build / Debug Instructions](code/README.md)
 
 
 ## Support

diff --git a/code/README.md b/code/README.md
@@ -41,7 +41,7 @@ pio run --target upload --upload-port /dev/ttyUSB0
 
 Alternatively, UART device can be defined in `platformio.ini`, eg. `upload_port = /dev/ttyUSB0`
 
-#### Monitor UART Log
+#### Monitor Serial / UART Log
 ```
 pio device monitor -p /dev/ttyUSB0 -b 115200
 ```
@@ -84,9 +84,14 @@ pio device monitor -p /dev/ttyUSB0 -b 115200
 ## Debugging
 
 ### UART/Serial Log
+##### Using platformio IDE
 ```
 pio device monitor -p /dev/ttyUSB0 -b 115200
 ```
+##### Using [Web Installer](https://slider0007.github.io/AI-on-the-edge-device/)
+<img src="../images/webinstaller_console.jpg">
+
+
 ### Application Log File
 The device is logging lots of actions to SD card (`log/messages`). This log can be viewed using WebUI (`System > Log Viewer`) or directly by browsing the files on SD card. Verbosity is depended on log level which can be adapted in WebUI
 

diff --git a/images/webinstaller_console.jpg b/images/webinstaller_console.jpg
diff --git a/images/webinstaller_home.jpg b/images/webinstaller_home.jpg