build.yml

name: Build firmware

on:
  push:
    branches: [main]
    tags: ['v*']
  pull_request:
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Cache PlatformIO packages
        uses: actions/cache@v4
        with:
          path: ~/.platformio
          key: pio-${{ runner.os }}-${{ hashFiles('platformio.ini') }}
          restore-keys: pio-${{ runner.os }}-
      - name: Install PlatformIO and esptool
        run: pip install platformio "esptool~=4.8"
      - name: Build
        run: pio run -e seengreat_hub75_s3
      # Voice pack for the spoken announcements: rendered with Piper TTS only when the phrase list or the generator
      # changed (the pack is cached), and never allowed to break the firmware build.
      - name: Restore a previously built voice pack
        id: voice-cache
        uses: actions/cache@v4
        with:
          path: installer/voice-*.pack
          key: voice-pack-${{ hashFiles('tools/make_voice_pack.py', 'tools/nws_event_types.json') }}
      - name: Cache the Piper voice model
        if: steps.voice-cache.outputs.cache-hit != 'true'
        uses: actions/cache@v4
        with:
          path: ~/.cache/piper-voices
          key: piper-voice-en_US-ljspeech-medium
      - name: Build voice pack (Piper TTS)
        if: steps.voice-cache.outputs.cache-hit != 'true'
        continue-on-error: true
        run: |
          pip install "piper-tts>=1.3"
          python tools/make_voice_pack.py --voice en_US-ljspeech-medium --voices-dir ~/.cache/piper-voices --out installer
      - name: Build web installer (factory image, OTA image, manifest)
        run: python tools/make_installer.py --out installer
      - name: Upload firmware images
        uses: actions/upload-artifact@v4
        with:
          name: firmware-${{ github.sha }}
          path: |
            installer/*.bin
            installer/*.pack
            installer/manifest.json
      - name: Upload installer site for GitHub Pages
        uses: actions/upload-pages-artifact@v3
        with:
          path: installer

  # Publishes a GitHub release with the firmware images whenever a version tag (v1.2.3) is pushed.
  # The tag must match MWC_VERSION in platformio.ini; a tag with a suffix (v1.2.3-beta) becomes a pre-release.
  release:
    needs: build
    if: startsWith(github.ref, 'refs/tags/v')
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          name: firmware-${{ github.sha }}
          path: release
      - name: Check that the tag matches the firmware version
        run: |
          TAG="${GITHUB_REF_NAME#v}"; BASE="${TAG%%-*}"
          VER=$(sed -n 's/.*MWC_VERSION=\\"\([^"\\]*\)\\".*/\1/p' platformio.ini | head -1)
          echo "tag $TAG (version part $BASE), firmware $VER"
          if [ "$BASE" != "$VER" ]; then echo "::error::tag v$TAG does not match MWC_VERSION $VER in platformio.ini"; exit 1; fi
      - name: Write release notes
        run: |
          cd release
          F=$(ls matrix-weather-clock-*-factory.bin); O=$(ls matrix-weather-clock-*-ota.bin)
          MD5=$(python3 -c "import json;print(json.load(open('manifest.json'))['ota_md5'])")
          {
            echo "Firmware ${GITHUB_REF_NAME} for the Seengreat RGB Matrix HUB75 S3 controller with a 64x32 HUB75 panel."
            echo
            echo "## Installing"
            echo "- Easiest: open the [web installer](https://${GITHUB_REPOSITORY_OWNER,,}.github.io/${GITHUB_REPOSITORY#*/}/) in Chrome or Edge with the board on USB."
            echo "- With esptool: \`esptool.py --chip esp32s3 write_flash 0x0 $F\`"
            echo "- Already running the firmware: upload \`$O\` on the Update tab, or let the automatic update pick it up."
            echo
            echo "## Checksums"
            echo "| File | SHA-256 |"
            echo "|---|---|"
            echo "| $F | \`$(sha256sum $F | cut -c1-64)\` |"
            echo "| $O | \`$(sha256sum $O | cut -c1-64)\` (MD5 \`$MD5\`, as in manifest.json) |"
            for V in voice-*.pack; do
              [ -f "$V" ] || continue
              echo "| $V | \`$(sha256sum $V | cut -c1-64)\` (voice pack for spoken announcements; the clock downloads it by itself) |"
            done
            echo
          } > ../notes.md
      - name: Publish release
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          PRE=""; case "$GITHUB_REF_NAME" in *-*) PRE="--prerelease";; esac
          gh release create "$GITHUB_REF_NAME" release/*.bin $(ls release/*.pack 2>/dev/null) release/manifest.json \
            --title "$GITHUB_REF_NAME" --notes-file notes.md --generate-notes $PRE

  # Publishes the installer at https://<owner>.github.io/<repo>/ . GitHub Pages needs a public repository
  # (or a paid plan); on a private repository this job fails harmlessly and the firmware artifact above is still built.
  deploy-pages:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    continue-on-error: true
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/configure-pages@v5
        with:
          enablement: true
      - id: deployment
        uses: actions/deploy-pages@v4