From cfa2c83b517136e01d8e7ed2e6f9613f05e78647 Mon Sep 17 00:00:00 2001 From: Justin Bunton <130115204+Bunton33@users.noreply.github.com> Date: Wed, 26 Aug 2026 12:24:45 -0400 Subject: [PATCH 1/8] Unify WiFi + Ethernet into one firmware with automatic switchover MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit One firmware now serves both connection types using ESPHome 2026.8's network: priority: multi-interface support — the community no longer has to pick a variant or reflash to switch (requested in ApolloAutomation/R_PRO-1#69). Behavior: - network: priority: [ethernet, wifi]; ESPHome arbitrates the default route when both are up. - ethernet.on_connect turns WiFi (and the fallback hotspot) off, shuts down the captive portal, and bounces ESP-NOW so the WizMote keeps working standalone on the radio (channel scan now guarded to run only while WiFi is disabled). - ethernet.on_disconnect re-enables WiFi (saved network or provisioning hotspot). - A persisted ethernet_expected global makes devices last seen on Ethernet boot with WiFi off entirely, so the open hotspot never broadcasts during the boot-to-DHCP window; a 20s boot fallback enables WiFi if the cable is gone. Safe mode skips on_boot, so WiFi always starts there for OTA recovery. Migration: - New canonical Integrations/ESPHome/CAST-1.yaml (ApolloAutomation.CAST-1, publishes to firmware/); the installer page offers this single build. - CAST-1_ETH.yaml / CAST-1_W.yaml are now thin shims (name, project, dashboard_import, manifest URLs) over the shared Core.yaml, so the deployed fleet OTAs into the unified firmware from its original manifest URLs with no reflash and no rename. - "Firmware Type" select removed; apply_ota_source only switches Stable/Beta via per-variant substitutions. "IP Address" sensor split into "Ethernet IP Address" + "WiFi IP Address" diagnostics. - improv_serial + esp32_improv + captive_portal now in every variant (Made for ESPHome requirement for WiFi-capable configs); explicit ids on all new components; min_version 2026.8.0. - Workflows build/publish all three yamls (stable Pages dirs firmware/, firmware-e/, firmware-w/; beta assets manifest.json, manifest-e.json, manifest-w.json). Note: the canonical Beta manifest 404s until the beta branch runs the new matrix once — merge to beta (or dispatch build-beta.yml) promptly after this lands. All three configs validate and the canonical firmware compiles clean on ESPHome 2026.8.1 (RAM 48.9%, Flash 49.2%). Co-Authored-By: Claude Fable 5 --- .github/workflows/build-beta.yml | 25 ++-- .github/workflows/build.yml | 3 +- .github/workflows/ci.yml | 1 + .github/workflows/weekly.yml | 1 + Integrations/ESPHome/CAST-1.yaml | 16 +++ Integrations/ESPHome/CAST-1_ETH.yaml | 108 ++-------------- Integrations/ESPHome/CAST-1_W.yaml | 92 ++------------ Integrations/ESPHome/Core.yaml | 176 ++++++++++++++++++++++++--- Integrations/ESPHome/wizmote.yaml | 28 +++++ README.md | 15 +++ static/index.html | 13 +- 11 files changed, 266 insertions(+), 212 deletions(-) create mode 100644 Integrations/ESPHome/CAST-1.yaml diff --git a/.github/workflows/build-beta.yml b/.github/workflows/build-beta.yml index 4dc1634..c50b628 100644 --- a/.github/workflows/build-beta.yml +++ b/.github/workflows/build-beta.yml @@ -4,6 +4,12 @@ name: Build and Publish Beta # rolling "beta" pre-release. The on-device "Firmware Channel" select points OTA # updates at these assets. Stable firmware is built/published separately by # build.yml (push to main -> GitHub Pages). +# +# NOTE: the canonical (unified) firmware's Beta manifest is the manifest.json +# asset, which only exists once this workflow has run with the three-entry +# matrix below. After the unified-firmware change lands on main, merge it to +# beta (or run this workflow manually) promptly — until then, canonical-build +# devices switched to the Beta channel get a 404 on their update manifest. on: push: @@ -37,6 +43,7 @@ jobs: strategy: matrix: include: + - { yaml: Integrations/ESPHome/CAST-1.yaml, name: firmware } - { yaml: Integrations/ESPHome/CAST-1_W.yaml, name: firmware-w } - { yaml: Integrations/ESPHome/CAST-1_ETH.yaml, name: firmware-e } uses: esphome/workflows/.github/workflows/build.yml@9f6577fd37b5cf773ab1b9be929714a0dcd15661 # 2026.7.0 @@ -73,22 +80,24 @@ jobs: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | BASE="https://github.com/${{ github.repository }}/releases/download/beta-fw" - for v in w e; do - man=$(find "fw/firmware-$v" -name manifest.json | head -1) + for pair in "firmware:manifest.json" "firmware-w:manifest-w.json" "firmware-e:manifest-e.json"; do + dir="${pair%%:*}" + asset="${pair##*:}" + man=$(find "fw/$dir" -name manifest.json | head -1) if [ -z "$man" ]; then - echo "::error::manifest.json not found for firmware-$v" + echo "::error::manifest.json not found for $dir" exit 1 fi - echo "Rewriting $man" + echo "Rewriting $man -> $asset" # Make ota.path and parts[].path absolute release-asset URLs so the # device never has to resolve a relative path against a redirected URL. jq --arg base "$BASE" ' .builds[0].ota.path = ($base + "/" + (.builds[0].ota.path | sub(".*/"; ""))) | .builds[0].parts |= map(.path = ($base + "/" + (.path | sub(".*/"; "")))) - ' "$man" > "manifest-$v.json" - cat "manifest-$v.json" - gh release upload beta-fw "manifest-$v.json" -R "${{ github.repository }}" --clobber - find "fw/firmware-$v" -name '*.bin' -print -exec \ + ' "$man" > "$asset" + cat "$asset" + gh release upload beta-fw "$asset" -R "${{ github.repository }}" --clobber + find "fw/$dir" -name '*.bin' -print -exec \ gh release upload beta-fw {} -R "${{ github.repository }}" --clobber \; done echo "Beta assets published." diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index c5fa440..acfda93 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -25,9 +25,10 @@ jobs: with: device-name: cast-1 yaml-files: | + Integrations/ESPHome/CAST-1.yaml Integrations/ESPHome/CAST-1_ETH.yaml Integrations/ESPHome/CAST-1_W.yaml - firmware-names: "1_ETH:firmware-e,1_W:firmware-w" + firmware-names: "1:firmware,1_ETH:firmware-e,1_W:firmware-w" core-yaml-path: Integrations/ESPHome/Core.yaml esphome-version: stable # Bypass check if manually triggered with bypass option diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 92a99e8..6c30623 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -14,6 +14,7 @@ jobs: uses: ApolloAutomation/Workflows/.github/workflows/esphome-ci.yml@main with: yaml-files: | + Integrations/ESPHome/CAST-1.yaml Integrations/ESPHome/CAST-1_ETH.yaml Integrations/ESPHome/CAST-1_W.yaml # dev excluded until the TemplateSelect .state incompatibility is fixed diff --git a/.github/workflows/weekly.yml b/.github/workflows/weekly.yml index 63891fc..8d45bd6 100644 --- a/.github/workflows/weekly.yml +++ b/.github/workflows/weekly.yml @@ -13,6 +13,7 @@ jobs: uses: ApolloAutomation/Workflows/.github/workflows/esphome-ci.yml@main with: yaml-files: | + Integrations/ESPHome/CAST-1.yaml Integrations/ESPHome/CAST-1_ETH.yaml Integrations/ESPHome/CAST-1_W.yaml # dev excluded until the TemplateSelect .state incompatibility is fixed diff --git a/Integrations/ESPHome/CAST-1.yaml b/Integrations/ESPHome/CAST-1.yaml new file mode 100644 index 0000000..96d0880 --- /dev/null +++ b/Integrations/ESPHome/CAST-1.yaml @@ -0,0 +1,16 @@ +# Apollo CAST-1 — unified firmware with WiFi + Ethernet in one image. +# Ethernet is preferred when plugged in; WiFi (and its provisioning hotspot) +# takes over automatically when it is not. See Core.yaml for all device config. + +esphome: + name: "apollo-cast-1" + project: + name: "ApolloAutomation.CAST-1" + version: ${version} + +dashboard_import: + package_import_url: github://ApolloAutomation/CAST-1/Integrations/ESPHome/CAST-1.yaml + import_full_config: false + +packages: + core: !include Core.yaml diff --git a/Integrations/ESPHome/CAST-1_ETH.yaml b/Integrations/ESPHome/CAST-1_ETH.yaml index 0ffabc5..2fb333a 100644 --- a/Integrations/ESPHome/CAST-1_ETH.yaml +++ b/Integrations/ESPHome/CAST-1_ETH.yaml @@ -1,112 +1,22 @@ +# Legacy Ethernet-variant shim. The firmware is identical to CAST-1.yaml +# (WiFi + Ethernet in one image); only the device/project name and the OTA +# manifest URLs differ, so devices originally flashed with the Ethernet +# firmware keep updating from their original manifest without a reflash. +# New installs should use CAST-1.yaml. + +substitutions: + stable_manifest_dir: "firmware-e" + beta_manifest_file: "manifest-e.json" esphome: name: "apollo-cast-1-eth" - friendly_name: Apollo CAST-1 - comment: Apollo CAST-1 - name_add_mac_suffix: true - platformio_options: - board_build.flash_mode: dio - project: name: "ApolloAutomation.CAST-1-ETH" version: ${version} - min_version: 2026.6.0 - - on_boot: - - priority: 800 - then: - - if: - condition: - - lambda: "return id(runTest);" - then: - - lambda: "id(testScript).execute();" - - priority: 500 - then: - - text_sensor.template.publish: - id: apollo_firmware_version - state: "${version}" - dashboard_import: package_import_url: github://ApolloAutomation/CAST-1/Integrations/ESPHome/CAST-1_ETH.yaml import_full_config: false -ota: - - platform: esphome - id: ota_esphome - - platform: http_request - id: ota_managed - -safe_mode: - id: safe_mode_1 - -update: - - platform: http_request - id: update_http_request - name: Firmware Update - source: https://apolloautomation.github.io/CAST-1/firmware-e/manifest.json - -logger: - id: logger_1 - -ethernet: - id: ethernet_1 - type: W5500 - clock_speed: 40MHz - clk_pin: GPIO7 - mosi_pin: GPIO12 - miso_pin: GPIO11 - cs_pin: GPIO6 - interrupt_pin: GPIO13 - reset_pin: GPIO21 - -select: - - platform: template - id: firmware_selector - name: Firmware Type - icon: "mdi:test-tube" - entity_category: config - optimistic: true - restore_value: true - options: - - "WiFi" - - "Ethernet" - initial_option: "Ethernet" - on_value: - then: - - script.execute: apply_ota_source - -text_sensor: - - platform: ethernet_info - ip_address: - name: "IP Address" - id: eth_ip - entity_category: "diagnostic" - -# No WiFi: scan channels until WizMote heard -espnow: - channel: 1 - -interval: - - id: wizmote_channel_scan - interval: 2s - then: - - if: - condition: - lambda: |- - std::string mac = id(wizmote_mac_address).state; - bool want = id(wizmote_discovery_mode).state || - (mac != "00:00:00:00:00:00" && mac != ""); - return want && (millis() - id(wizmote_last_packet_ms) > 30000); - then: - - lambda: |- - id(wizmote_scan_channel)++; - if (id(wizmote_scan_channel) > 13) id(wizmote_scan_channel) = 1; - - espnow.set_channel: - channel: !lambda 'return id(wizmote_scan_channel);' - - logger.log: - format: "WizMote channel scan: trying channel %d" - args: ['id(wizmote_scan_channel)'] - packages: core: !include Core.yaml diff --git a/Integrations/ESPHome/CAST-1_W.yaml b/Integrations/ESPHome/CAST-1_W.yaml index 511bebb..9313ae0 100644 --- a/Integrations/ESPHome/CAST-1_W.yaml +++ b/Integrations/ESPHome/CAST-1_W.yaml @@ -1,96 +1,22 @@ +# Legacy WiFi-variant shim. The firmware is identical to CAST-1.yaml +# (WiFi + Ethernet in one image); only the device/project name and the OTA +# manifest URLs differ, so devices originally flashed with the WiFi firmware +# keep updating from their original manifest without a reflash. +# New installs should use CAST-1.yaml. + +substitutions: + stable_manifest_dir: "firmware-w" + beta_manifest_file: "manifest-w.json" esphome: name: "apollo-cast-1-w" - friendly_name: Apollo CAST-1 - comment: Apollo CAST-1 - name_add_mac_suffix: true - platformio_options: - board_build.flash_mode: dio - project: name: "ApolloAutomation.CAST-1-W" version: ${version} - min_version: 2026.6.0 - - on_boot: - - priority: 800 - then: - - if: - condition: - - lambda: "return id(runTest);" - then: - - lambda: "id(testScript).execute();" - - priority: 500 - then: - - text_sensor.template.publish: - id: apollo_firmware_version - state: "${version}" - dashboard_import: package_import_url: github://ApolloAutomation/CAST-1/Integrations/ESPHome/CAST-1_W.yaml import_full_config: false -ota: - - platform: esphome - id: ota_esphome - - platform: http_request - id: ota_managed - -safe_mode: - id: safe_mode_1 - -improv_serial: - id: improv_serial_1 - -esp32_improv: - id: esp32_improv_1 - authorizer: none - -update: - - platform: http_request - id: update_http_request - name: Firmware Update - source: https://apolloautomation.github.io/CAST-1/firmware-w/manifest.json - -logger: - id: logger_1 - -wifi: - on_connect: - - component.update: update_http_request - id: wifi_1 - # Workaround: roam scans drop active audio - post_connect_roaming: false - ap: - ssid: "Apollo CAST 1 Hotspot" - power_save_mode: none - -captive_portal: - id: captive_portal_1 - -select: - - platform: template - id: firmware_selector - name: Firmware Type - icon: "mdi:test-tube" - entity_category: config - optimistic: true - restore_value: true - options: - - "WiFi" - - "Ethernet" - initial_option: "WiFi" - on_value: - then: - - script.execute: apply_ota_source - -text_sensor: - - platform: wifi_info - ip_address: - name: "IP Address" - id: wifi_ip - entity_category: "diagnostic" - packages: core: !include Core.yaml diff --git a/Integrations/ESPHome/Core.yaml b/Integrations/ESPHome/Core.yaml index fa4ae74..a4a16c9 100644 --- a/Integrations/ESPHome/Core.yaml +++ b/Integrations/ESPHome/Core.yaml @@ -1,20 +1,77 @@ substitutions: - version: "26.8.25.1" + version: "26.8.26.1" # Manifest bases: stable=Pages, beta=release assets stable_manifest_base: "https://apolloautomation.github.io/CAST-1" beta_manifest_base: "https://github.com/ApolloAutomation/CAST-1/releases/download/beta-fw" + # Manifest targets for this build; legacy variant files override these so + # already-deployed devices keep updating from their original URLs. + stable_manifest_dir: "firmware" + beta_manifest_file: "manifest.json" packages: wizmote: !include wizmote.yaml esphome: - # List form so variant on_boot entries merge + friendly_name: Apollo CAST-1 + comment: Apollo CAST-1 + name_add_mac_suffix: true + # network: priority: (WiFi + Ethernet in one firmware) needs 2026.8 + min_version: 2026.8.0 + platformio_options: + board_build.flash_mode: dio + # List form so package on_boot entries (wizmote.yaml) merge on_boot: + - priority: 800 + then: + - if: + condition: + - lambda: "return id(runTest);" + then: + - lambda: "id(testScript).execute();" + # A device last seen on Ethernet boots with WiFi (and its hotspot) off: + # with no STA credentials the fallback AP would otherwise broadcast + # until Ethernet gets its DHCP lease. Runs after globals restore (800), + # before wifi setup (245). Safe mode skips on_boot entirely, so WiFi + # always starts there for recovery. ESP-NOW self-inits on channel 1 + # (legacy Ethernet-firmware default) when WiFi is off at setup. + - priority: 600 + then: + - if: + condition: + lambda: "return id(ethernet_expected);" + then: + - lambda: |- + id(wifi_1).set_enable_on_boot(false); + id(espnow_component).set_wifi_channel(1); + - priority: 500 + then: + - text_sensor.template.publish: + id: apollo_firmware_version + state: "${version}" # Point update entity at selected manifest - priority: -100 then: - script.execute: apply_ota_source + # Ethernet was expected but never came up: bring WiFi back so the + # device can rejoin a network or open the provisioning hotspot. + - priority: -100 + then: + - if: + condition: + lambda: "return id(ethernet_expected);" + then: + - wait_until: + condition: + ethernet.connected: + timeout: 20s + - if: + condition: + not: + ethernet.connected: + then: + - lambda: "id(ethernet_expected) = false;" + - wifi.enable: # Re-apply persisted Bluetooth Proxy state - priority: -300 then: @@ -27,6 +84,85 @@ esphome: else: - esp32_ble_tracker.stop_scan: +ota: + - platform: esphome + id: ota_esphome + - platform: http_request + id: ota_managed + +safe_mode: + id: safe_mode_1 + +logger: + id: logger_1 + +update: + - platform: http_request + id: update_http_request + name: Firmware Update + source: ${stable_manifest_base}/${stable_manifest_dir}/manifest.json + +# Both interfaces live in one firmware (ESPHome 2026.8+); Ethernet is +# preferred whenever connected and ESPHome arbitrates the default route. +network: + id: network_1 + priority: + - ethernet + - wifi + +ethernet: + id: ethernet_1 + type: W5500 + clock_speed: 40MHz + clk_pin: GPIO7 + mosi_pin: GPIO12 + miso_pin: GPIO11 + cs_pin: GPIO6 + interrupt_pin: GPIO13 + reset_pin: GPIO21 + on_connect: + # Ethernet is up: turn WiFi (and the fallback hotspot) off. ESP-NOW rides + # the WiFi driver, so bounce it to re-init standalone; it re-adds the + # paired WizMote peer and the channel scan in wizmote.yaml takes over. + # ethernet_expected persists so the next boot starts with WiFi off. + - lambda: "id(ethernet_expected) = true;" + - wifi.disable: + - lambda: |- + // wifi.disable() tears down the AP but not the captive portal; + // left running it would keep answering DNS and /wifisave on the + // Ethernet IP until the next reboot. + if (id(captive_portal_1).is_active()) { + id(captive_portal_1).end(); + } + id(espnow_component).disable(); + id(espnow_component).enable(); + - component.update: update_http_request + on_disconnect: + # Cable gone: bring WiFi back so the device rejoins a saved network or, + # with none configured, opens the provisioning hotspot. + - lambda: "id(ethernet_expected) = false;" + - wifi.enable: + +wifi: + id: wifi_1 + on_connect: + - component.update: update_http_request + # Workaround: roam scans drop active audio + post_connect_roaming: false + ap: + ssid: "Apollo CAST 1 Hotspot" + power_save_mode: none + +captive_portal: + id: captive_portal_1 + +improv_serial: + id: improv_serial_1 + +esp32_improv: + id: esp32_improv_1 + authorizer: none + esp32: variant: ESP32S3 flash_size: 8MB @@ -81,6 +217,12 @@ globals: - id: announcement_triggered type: bool initial_value: 'false' + # True once Ethernet has connected; cleared when the cable is lost or + # Ethernet fails to appear at boot. Gates the WiFi-off-at-boot path. + - id: ethernet_expected + type: bool + restore_value: yes + initial_value: 'false' psram: id: psram_1 @@ -118,7 +260,7 @@ button: icon: mdi:cloud-download entity_category: config on_press: - - logger.log: "Applying firmware update for the selected type and channel" + - logger.log: "Applying firmware update for the selected channel" - delay: 3s - script.execute: apply_ota_source - script.wait: apply_ota_source @@ -194,6 +336,18 @@ switch: - esp32_ble_tracker.stop_scan: text_sensor: + - platform: ethernet_info + ip_address: + name: "Ethernet IP Address" + id: eth_ip + entity_category: "diagnostic" + + - platform: wifi_info + ip_address: + name: "WiFi IP Address" + id: wifi_ip + entity_category: "diagnostic" + - platform: sendspin id: sendspin_track_title type: title @@ -404,21 +558,13 @@ media_player: script: - id: apply_ota_source - # Set OTA manifest from type + channel selectors + # Set OTA manifest from the channel selector then: - lambda: |- - const bool eth = id(firmware_selector).current_option() == "Ethernet"; const bool beta = id(firmware_channel).current_option() == "Beta"; - std::string url; - if (beta) { - url = eth - ? "${beta_manifest_base}/manifest-e.json" - : "${beta_manifest_base}/manifest-w.json"; - } else { - url = eth - ? "${stable_manifest_base}/firmware-e/manifest.json" - : "${stable_manifest_base}/firmware-w/manifest.json"; - } + std::string url = beta + ? "${beta_manifest_base}/${beta_manifest_file}" + : "${stable_manifest_base}/${stable_manifest_dir}/manifest.json"; ESP_LOGI("firmware", "OTA manifest set to: %s", url.c_str()); id(update_http_request).set_source_url(url); - component.update: update_http_request diff --git a/Integrations/ESPHome/wizmote.yaml b/Integrations/ESPHome/wizmote.yaml index 287df37..51cfd3c 100644 --- a/Integrations/ESPHome/wizmote.yaml +++ b/Integrations/ESPHome/wizmote.yaml @@ -388,6 +388,34 @@ script: format: "unmapped button %d" args: ['button'] +# While Ethernet carries the network, WiFi is disabled and ESP-NOW owns the +# radio: scan channels until the WizMote is heard. With WiFi enabled the +# channel is pinned by the WiFi connection, so scanning is skipped (and +# espnow.set_channel would be refused anyway). +interval: + - id: wizmote_channel_scan + interval: 2s + then: + - if: + condition: + and: + - not: + wifi.enabled: + - lambda: |- + std::string mac = id(wizmote_mac_address).state; + bool want = id(wizmote_discovery_mode).state || + (mac != "00:00:00:00:00:00" && mac != ""); + return want && (millis() - id(wizmote_last_packet_ms) > 30000); + then: + - lambda: |- + id(wizmote_scan_channel)++; + if (id(wizmote_scan_channel) > 13) id(wizmote_scan_channel) = 1; + - espnow.set_channel: + channel: !lambda 'return id(wizmote_scan_channel);' + - logger.log: + format: "WizMote channel scan: trying channel %d" + args: ['id(wizmote_scan_channel)'] + espnow: id: espnow_component auto_add_peer: false diff --git a/README.md b/README.md index 9077424..a7c4aa3 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,21 @@ Easily make your speakers smart and cast to multiple devices using Music Assistant and Sendspin! +## Connectivity + +One firmware covers both WiFi and Ethernet — there is no need to pick a +variant or reflash to switch: + +- **Ethernet plugged in:** the device uses Ethernet and turns WiFi (including + the setup hotspot) off. +- **No Ethernet:** WiFi turns on automatically. The device rejoins its saved + network, or opens the "Apollo CAST 1 Hotspot" for setup if none is + configured (Improv via Bluetooth or USB works too). + +Devices flashed with the older WiFi-only or Ethernet-only firmware receive +this unified behavior automatically through their normal firmware update — no +reflash needed. + ## WizMote The CAST-1 gives you full Home Assistant control over a paired Wiz WizMote. Each of the nine buttons (On, Off, Night, Brightness Up/Down, and 1–4) is a configurable select on the device — assign it Play, Pause, Play / Pause, Next/Previous Track, Volume Up/Down, Toggle Light, or Send HA Event. The defaults give you media controls out of the box. diff --git a/static/index.html b/static/index.html index a6a7aae..fecb974 100644 --- a/static/index.html +++ b/static/index.html @@ -84,14 +84,15 @@

Apollo CAST-1 Installer

-

CAST-1 Wifi Firmware

- -
-
-

CAST-1 Ethernet Firmware

- +

CAST-1 Firmware (WiFi & Ethernet)

+
+

+ One firmware for both connection types: Ethernet is used whenever a + cable is plugged in, and WiFi (with its setup hotspot) takes over + automatically when it is not. +

Date: Wed, 26 Aug 2026 14:29:17 -0400 Subject: [PATCH 2/8] Keep WiFi connected alongside Ethernet (dual-home) so HA never loses the device MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Field testing showed the WiFi-off-on-ethernet design forces Home Assistant to rediscover the device at its new Ethernet IP via mDNS on every cable change — which fails on networks where HA lacks mDNS visibility of the wired segment, stranding the device as unavailable. Customers cannot be expected to make network changes. New behavior: - ethernet.on_connect: if WiFi is connected (or associates within a 30s grace window), keep it — the device runs dual-homed. ESPHome's network-priority route arbitration carries traffic over Ethernet while HA's connection to the WiFi address survives every plug/unplug. - WiFi is released (wifi_release_radio script: disable + captive-portal teardown + ESP-NOW standalone bounce) only when it has nothing to offer: fallback hotspot active at connect time, failure to associate within the grace window, or (new wifi.on_disconnect guard) losing its network for 60s while Ethernet is up — decided before the 90s hotspot timer can fire, so the hotspot is still never active while on Ethernet. - ethernet_expected now means "run Ethernet-only with WiFi silent" and is only set on the release paths; WiFi-silent boots and the cable-out recovery are unchanged. Bench-validated on hardware (ESP32-S3 + W5500, HA connected to the WiFi address): cable pull -> route to WiFi in 16 ms, replug -> route back in 16 ms, WiFi connection continuous, HA online state never dropped in either direction. Version 26.8.26.2. Co-Authored-By: Claude Fable 5 --- Integrations/ESPHome/Core.yaml | 98 +++++++++++++++++++++++++++------- README.md | 9 ++-- 2 files changed, 86 insertions(+), 21 deletions(-) diff --git a/Integrations/ESPHome/Core.yaml b/Integrations/ESPHome/Core.yaml index a4a16c9..7b52eee 100644 --- a/Integrations/ESPHome/Core.yaml +++ b/Integrations/ESPHome/Core.yaml @@ -1,5 +1,5 @@ substitutions: - version: "26.8.26.1" + version: "26.8.26.2" # Manifest bases: stable=Pages, beta=release assets stable_manifest_base: "https://apolloautomation.github.io/CAST-1" beta_manifest_base: "https://github.com/ApolloAutomation/CAST-1/releases/download/beta-fw" @@ -121,25 +121,48 @@ ethernet: interrupt_pin: GPIO13 reset_pin: GPIO21 on_connect: - # Ethernet is up: turn WiFi (and the fallback hotspot) off. ESP-NOW rides - # the WiFi driver, so bounce it to re-init standalone; it re-adds the - # paired WizMote peer and the channel scan in wizmote.yaml takes over. - # ethernet_expected persists so the next boot starts with WiFi off. - - lambda: "id(ethernet_expected) = true;" - - wifi.disable: - - lambda: |- - // wifi.disable() tears down the AP but not the captive portal; - // left running it would keep answering DNS and /wifisave on the - // Ethernet IP until the next reboot. - if (id(captive_portal_1).is_active()) { - id(captive_portal_1).end(); - } - id(espnow_component).disable(); - id(espnow_component).enable(); + # Ethernet is up. If WiFi is (or is about to be) connected to a network, + # keep it: the device runs dual-homed — Ethernet carries the routed + # traffic (network: priority:) while Home Assistant's connection to the + # WiFi address survives, so no rediscovery is ever needed. WiFi is turned + # off only when it has nothing to offer (hotspot active or nothing to + # join), which also guarantees the hotspot is never up while on Ethernet. + - if: + condition: + wifi.enabled: + then: + - if: + condition: + wifi.ap_active: + then: + # Fallback hotspot is broadcasting: WiFi has no network. + - script.execute: wifi_release_radio + else: + # Boot race: WiFi may still be associating; give it a moment. + - wait_until: + condition: + wifi.connected: + timeout: 30s + - if: + condition: + wifi.connected: + then: + - lambda: "id(ethernet_expected) = false;" + else: + # Guard: if the cable vanished during the wait, leave + # WiFi alone — it is the only path left. + - if: + condition: + ethernet.connected: + then: + - script.execute: wifi_release_radio + else: + # WiFi-silent boot (ethernet_expected): stays off. + - lambda: "id(ethernet_expected) = true;" - component.update: update_http_request on_disconnect: - # Cable gone: bring WiFi back so the device rejoins a saved network or, - # with none configured, opens the provisioning hotspot. + # Cable gone: make sure WiFi is up so the device rejoins a saved network + # or, with none configured, opens the provisioning hotspot. - lambda: "id(ethernet_expected) = false;" - wifi.enable: @@ -147,6 +170,29 @@ wifi: id: wifi_1 on_connect: - component.update: update_http_request + on_disconnect: + # WiFi lost its network while Ethernet carries the device: after a grace + # period for reassociation, turn WiFi off rather than let the fallback + # hotspot appear (ap_timeout is 90s; deciding at 60s keeps it from ever + # starting). Harmless when triggered by wifi.disable itself — the + # wifi.enabled check below skips the release then. + - if: + condition: + ethernet.connected: + then: + - wait_until: + condition: + wifi.connected: + timeout: 60s + - if: + condition: + and: + - wifi.enabled: + - not: + wifi.connected: + - ethernet.connected: + then: + - script.execute: wifi_release_radio # Workaround: roam scans drop active audio post_connect_roaming: false ap: @@ -557,6 +603,22 @@ media_player: script: + - id: wifi_release_radio + # Turn WiFi off while Ethernet carries the device: ends AP+STA, shuts + # down the captive portal (wifi.disable leaves it answering DNS and + # /wifisave on the Ethernet IP), and bounces ESP-NOW so it re-inits + # standalone for the WizMote (the channel scan in wizmote.yaml takes + # over). ethernet_expected persists so the next boot starts WiFi-silent. + then: + - lambda: "id(ethernet_expected) = true;" + - wifi.disable: + - lambda: |- + if (id(captive_portal_1).is_active()) { + id(captive_portal_1).end(); + } + id(espnow_component).disable(); + id(espnow_component).enable(); + - id: apply_ota_source # Set OTA manifest from the channel selector then: diff --git a/README.md b/README.md index a7c4aa3..f0cad25 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,12 @@ Easily make your speakers smart and cast to multiple devices using Music Assista One firmware covers both WiFi and Ethernet — there is no need to pick a variant or reflash to switch: -- **Ethernet plugged in:** the device uses Ethernet and turns WiFi (including - the setup hotspot) off. -- **No Ethernet:** WiFi turns on automatically. The device rejoins its saved +- **Ethernet plugged in:** traffic moves to Ethernet. If the device is also + joined to your WiFi, that connection stays up alongside, so Home Assistant + never loses the device when you plug or unplug the cable. If WiFi has no + network to join, it turns off entirely — the setup hotspot is never active + while Ethernet is connected. +- **No Ethernet:** WiFi works as usual. The device rejoins its saved network, or opens the "Apollo CAST 1 Hotspot" for setup if none is configured (Improv via Bluetooth or USB works too). From d221ff01b7e995f6030162e5e31714b9ca06ec66 Mon Sep 17 00:00:00 2001 From: Justin Bunton <130115204+Bunton33@users.noreply.github.com> Date: Wed, 26 Aug 2026 14:48:50 -0400 Subject: [PATCH 3/8] Fix HAT-less crash loop, hotspot race, and WiFi-release ratchet Three fixes from hardware soak testing and adversarial review of the dual-home state machine: 1. CRITICAL - HAT-less crash loop: on boards without the Ethernet HAT, the IDF W5500 driver's helper task (created before chip verification) survives the failed driver install; it polls the floating SPI bus, spams "received frame was truncated", and corrupts memory - observed as a Cache-error Guru Meditation every ~100s on hardware, which safe mode never catches (crashes land past the 60s boot-is-good window). Fix: when ethernet setup has failed, look up "w5500_tsk" and suspend it at boot (on_boot priority 200). Soak-verified: zero spam and zero crashes, where the prior build crashed twice in ten minutes. (Upstream ESPHome should delete the mac on install failure.) 2. Hotspot race: plugging the cable 60-90s after WiFi loss let the fallback AP start mid-wait and broadcast up to 30s while on Ethernet. The on_connect wait now also completes on wifi.ap_active and releases immediately, closing the window to about one loop pass. 3. One-way ratchet: a >60s router outage (or slow association at cable-connect) released WiFi permanently until a cable pull, recreating the HA-loses-device failure this design exists to prevent. A 10-minute recovery probe now re-tries WiFi while on Ethernet - gated on a persisted wifi_provisioned flag (set on first successful connect, cleared by factory reset) so never-provisioned devices can never pop the hotspot; the 60s probe bound stays under the 90s AP timer, which restarts at wifi.enable. Also rewords stale comments to the dual-home semantics. Known inherited limitation (upstream, pre-existing): once the fallback AP has started in a boot, ESPHome's ap_setup_ latch prevents it from starting again that boot for a credentialed device; BLE Improv remains the recovery path. Hardware-validated on ESP32-S3: HAT-less boot clean with HA connected, and HAT-present boot goes dual-homed (eth .207 + wifi .204, route on eth, HA online). Version 26.8.26.3. Co-Authored-By: Claude Fable 5 --- Integrations/ESPHome/Core.yaml | 96 +++++++++++++++++++++++++++---- Integrations/ESPHome/wizmote.yaml | 8 +-- 2 files changed, 90 insertions(+), 14 deletions(-) diff --git a/Integrations/ESPHome/Core.yaml b/Integrations/ESPHome/Core.yaml index 7b52eee..dccaaae 100644 --- a/Integrations/ESPHome/Core.yaml +++ b/Integrations/ESPHome/Core.yaml @@ -1,5 +1,5 @@ substitutions: - version: "26.8.26.2" + version: "26.8.26.3" # Manifest bases: stable=Pages, beta=release assets stable_manifest_base: "https://apolloautomation.github.io/CAST-1" beta_manifest_base: "https://github.com/ApolloAutomation/CAST-1/releases/download/beta-fw" @@ -29,12 +29,13 @@ esphome: - lambda: "return id(runTest);" then: - lambda: "id(testScript).execute();" - # A device last seen on Ethernet boots with WiFi (and its hotspot) off: - # with no STA credentials the fallback AP would otherwise broadcast - # until Ethernet gets its DHCP lease. Runs after globals restore (800), - # before wifi setup (245). Safe mode skips on_boot entirely, so WiFi - # always starts there for recovery. ESP-NOW self-inits on channel 1 - # (legacy Ethernet-firmware default) when WiFi is off at setup. + # A device whose WiFi was released while on Ethernet boots with WiFi + # (and its hotspot) off: with no STA credentials the fallback AP would + # otherwise broadcast until Ethernet gets its DHCP lease. Runs after + # globals restore (800), before wifi setup (245). Safe mode skips + # on_boot entirely, so WiFi always starts there for recovery. ESP-NOW + # self-inits on channel 1 (legacy Ethernet-firmware default) when WiFi + # is off at setup. - priority: 600 then: - if: @@ -44,6 +45,23 @@ esphome: - lambda: |- id(wifi_1).set_enable_on_boot(false); id(espnow_component).set_wifi_channel(1); + # No Ethernet HAT: the W5500 driver's helper task is created before chip + # verification and survives the failed install; left running it polls + # the floating SPI bus and eventually corrupts memory (Cache error + # panics every ~100s, observed on hardware). Park it. Runs right after + # ethernet's setup (250). + - priority: 200 + then: + - if: + condition: + lambda: "return id(ethernet_1).is_failed();" + then: + - lambda: |- + TaskHandle_t orphan = xTaskGetHandle("w5500_tsk"); + if (orphan != nullptr) { + vTaskSuspend(orphan); + ESP_LOGW("ethernet", "No Ethernet HAT detected; parked the W5500 helper task"); + } - priority: 500 then: - text_sensor.template.publish: @@ -139,9 +157,15 @@ ethernet: - script.execute: wifi_release_radio else: # Boot race: WiFi may still be associating; give it a moment. + # The wait also ends the instant the fallback AP starts (WiFi + # lost 60-90s before the cable arrived), so the hotspot is + # torn down within a loop pass instead of broadcasting for + # the rest of the window. - wait_until: condition: - wifi.connected: + or: + - wifi.connected: + - wifi.ap_active: timeout: 30s - if: condition: @@ -169,6 +193,10 @@ ethernet: wifi: id: wifi_1 on_connect: + # Remember that working credentials exist: gates the recovery probe + # below so it never runs (and can never pop the hotspot) on a device + # that was never provisioned. Survives reboots; factory reset clears it. + - lambda: "id(wifi_provisioned) = true;" - component.update: update_http_request on_disconnect: # WiFi lost its network while Ethernet carries the device: after a grace @@ -263,12 +291,20 @@ globals: - id: announcement_triggered type: bool initial_value: 'false' - # True once Ethernet has connected; cleared when the cable is lost or - # Ethernet fails to appear at boot. Gates the WiFi-off-at-boot path. + # True when WiFi was released while Ethernet carried the device (WiFi had + # nothing to offer); the next boot then starts WiFi-silent. Cleared when + # the cable is lost, Ethernet fails to appear at boot, or the device goes + # dual-homed. - id: ethernet_expected type: bool restore_value: yes initial_value: 'false' + # True once WiFi has ever connected (credentials known-good). Gates the + # WiFi recovery probe. Cleared only by factory reset. + - id: wifi_provisioned + type: bool + restore_value: yes + initial_value: 'false' psram: id: psram_1 @@ -602,7 +638,47 @@ media_player: +# A released WiFi (router outage while dual-homed, or slow association at +# cable-connect) must not stay silent until the next cable pull: while +# Ethernet is up and the device has known-good credentials, retry WiFi +# periodically. The 60s bound stays under the 90s hotspot timer (which +# restarts at wifi.enable), so the probe can never broadcast the AP. +interval: + - id: wifi_recovery_interval + interval: 10min + then: + - if: + condition: + and: + - ethernet.connected: + - not: + wifi.enabled: + - lambda: "return id(wifi_provisioned);" + then: + - script.execute: wifi_recovery_probe + script: + - id: wifi_recovery_probe + # Re-attempt WiFi while Ethernet carries the device; rejoin restores + # dual-home, failure releases the radio again for ESP-NOW. + then: + - wifi.enable: + - wait_until: + condition: + wifi.connected: + timeout: 60s + - if: + condition: + wifi.connected: + then: + - lambda: "id(ethernet_expected) = false;" + else: + - if: + condition: + ethernet.connected: + then: + - script.execute: wifi_release_radio + - id: wifi_release_radio # Turn WiFi off while Ethernet carries the device: ends AP+STA, shuts # down the captive portal (wifi.disable leaves it answering DNS and diff --git a/Integrations/ESPHome/wizmote.yaml b/Integrations/ESPHome/wizmote.yaml index 51cfd3c..dbf4765 100644 --- a/Integrations/ESPHome/wizmote.yaml +++ b/Integrations/ESPHome/wizmote.yaml @@ -388,10 +388,10 @@ script: format: "unmapped button %d" args: ['button'] -# While Ethernet carries the network, WiFi is disabled and ESP-NOW owns the -# radio: scan channels until the WizMote is heard. With WiFi enabled the -# channel is pinned by the WiFi connection, so scanning is skipped (and -# espnow.set_channel would be refused anyway). +# When WiFi has been released (device on Ethernet with no WiFi network), +# ESP-NOW owns the radio: scan channels until the WizMote is heard. While +# WiFi is enabled the channel is pinned by the WiFi connection, so scanning +# is skipped (and espnow.set_channel would be refused anyway). interval: - id: wizmote_channel_scan interval: 2s From 6fb62a7679d7a28e0db5d0c773af4c798efcc8cd Mon Sep 17 00:00:00 2001 From: Justin Bunton <130115204+Bunton33@users.noreply.github.com> Date: Wed, 26 Aug 2026 16:17:28 -0400 Subject: [PATCH 4/8] Reboot once when Ethernet must kill a live hotspot (AP relaunch latch) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Field-tested fresh-device flow exposed the inherited ESPHome limitation in earnest: once the fallback AP has started in a boot, it cannot fully relaunch in that same boot (ap_setup_ latch). Our Ethernet-first release makes that sequence routine — fresh device boots, hotspot appears, Ethernet takes over and releases WiFi — after which a later cable-out left a half-dead hotspot: SSID joinable, but nothing at 192.168.4.1 (observed on hardware; it also poisons the client that touches it, since phones cache the failed-DHCP state per-network). wifi_release_radio now reboots instead of disabling when the hotspot is live at release time: the device comes back Ethernet-only in seconds with the latch cleared, so every future cable-out provisioning attempt gets a fully working hotspot. The reboot happens at most once per setup (fresh device, first cable connect, before adoption); the persisted ethernet_expected flag makes the follow-up boot WiFi-silent so it cannot loop, with safe mode's boot counter as backstop. All other release paths (association timeout, 60s WiFi-loss guard, failed recovery probe) act before the 90s AP timer and keep the plain disable. Bench-validated end-to-end on hardware: full-wipe fresh device -> Ethernet-first boot and adoption -> cable-out provisioning (portal verified working on a clean boot) -> WiFi + HA -> replug -> dual-home with route flip in 1 ms and zero HA interruption. Version 26.8.26.4. Co-Authored-By: Claude Fable 5 --- Integrations/ESPHome/Core.yaml | 32 ++++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/Integrations/ESPHome/Core.yaml b/Integrations/ESPHome/Core.yaml index dccaaae..ed20636 100644 --- a/Integrations/ESPHome/Core.yaml +++ b/Integrations/ESPHome/Core.yaml @@ -1,5 +1,5 @@ substitutions: - version: "26.8.26.3" + version: "26.8.26.4" # Manifest bases: stable=Pages, beta=release assets stable_manifest_base: "https://apolloautomation.github.io/CAST-1" beta_manifest_base: "https://github.com/ApolloAutomation/CAST-1/releases/download/beta-fw" @@ -685,15 +685,31 @@ script: # /wifisave on the Ethernet IP), and bounces ESP-NOW so it re-inits # standalone for the WizMote (the channel scan in wizmote.yaml takes # over). ethernet_expected persists so the next boot starts WiFi-silent. + # + # If the fallback hotspot is LIVE, reboot instead: ESPHome cannot + # relaunch a once-started AP within the same boot (ap_setup_ latch), so + # merely disabling WiFi would leave the next cable-out provisioning + # attempt with a half-dead hotspot (SSID joins, but 192.168.4.1 serves + # nothing — observed on hardware). The reboot lands Ethernet-only in + # seconds with the latch cleared, and happens at most once per setup. then: - lambda: "id(ethernet_expected) = true;" - - wifi.disable: - - lambda: |- - if (id(captive_portal_1).is_active()) { - id(captive_portal_1).end(); - } - id(espnow_component).disable(); - id(espnow_component).enable(); + - if: + condition: + wifi.ap_active: + then: + - lambda: |- + ESP_LOGW("network", "Rebooting to fully release the active hotspot (one-time)"); + - delay: 500ms + - lambda: "App.safe_reboot();" + else: + - wifi.disable: + - lambda: |- + if (id(captive_portal_1).is_active()) { + id(captive_portal_1).end(); + } + id(espnow_component).disable(); + id(espnow_component).enable(); - id: apply_ota_source # Set OTA manifest from the channel selector From 017bb6339e3173b64b2c1b27caa6d690e8110f5d Mon Sep 17 00:00:00 2001 From: Justin Bunton <130115204+Bunton33@users.noreply.github.com> Date: Wed, 26 Aug 2026 16:49:01 -0400 Subject: [PATCH 5/8] Add Network Connection sensor for troubleshooting and notifications New diagnostic text sensor reporting which path carries the device: "Ethernet + WiFi" (dual-home), "Ethernet", "WiFi", "Hotspot", or "Connecting". Evaluated every 10s with immediate updates on ethernet connect/disconnect, so HA automations can alert the moment a wired device falls back to WiFi. Verified on hardware (reads "Ethernet + WiFi" in dual-home). Version 26.8.26.5. Co-Authored-By: Claude Fable 5 --- Integrations/ESPHome/Core.yaml | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/Integrations/ESPHome/Core.yaml b/Integrations/ESPHome/Core.yaml index ed20636..f8a4f34 100644 --- a/Integrations/ESPHome/Core.yaml +++ b/Integrations/ESPHome/Core.yaml @@ -1,5 +1,5 @@ substitutions: - version: "26.8.26.4" + version: "26.8.26.5" # Manifest bases: stable=Pages, beta=release assets stable_manifest_base: "https://apolloautomation.github.io/CAST-1" beta_manifest_base: "https://github.com/ApolloAutomation/CAST-1/releases/download/beta-fw" @@ -184,11 +184,13 @@ ethernet: # WiFi-silent boot (ethernet_expected): stays off. - lambda: "id(ethernet_expected) = true;" - component.update: update_http_request + - component.update: network_connection on_disconnect: # Cable gone: make sure WiFi is up so the device rejoins a saved network # or, with none configured, opens the provisioning hotspot. - lambda: "id(ethernet_expected) = false;" - wifi.enable: + - component.update: network_connection wifi: id: wifi_1 @@ -418,6 +420,26 @@ switch: - esp32_ble_tracker.stop_scan: text_sensor: + # Which path is carrying the device right now — for troubleshooting and + # HA notifications (e.g. alert when a wired device falls back to WiFi). + # Ethernet + WiFi = dual-home: traffic on the wire, WiFi held so Home + # Assistant never loses the device. + - platform: template + name: "Network Connection" + id: network_connection + icon: "mdi:network" + entity_category: "diagnostic" + update_interval: 10s + lambda: |- + const bool eth = id(ethernet_1).is_connected(); + const bool sta = !id(wifi_1).is_disabled() && id(wifi_1).is_connected(); + const bool ap = !id(wifi_1).is_disabled() && id(wifi_1).is_ap_active(); + if (eth && sta) return std::string("Ethernet + WiFi"); + if (eth) return std::string("Ethernet"); + if (sta) return std::string("WiFi"); + if (ap) return std::string("Hotspot"); + return std::string("Connecting"); + - platform: ethernet_info ip_address: name: "Ethernet IP Address" From 9254392f67206007372552b9f8d53c5e18fe37a3 Mon Sep 17 00:00:00 2001 From: Justin Bunton <130115204+Bunton33@users.noreply.github.com> Date: Wed, 26 Aug 2026 17:01:57 -0400 Subject: [PATCH 6/8] Retire the WiFi/Ethernet firmware variants; converge the fleet on canonical MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The variant firmwares are gone: CAST-1_ETH.yaml and CAST-1_W.yaml are now transitional one-line includes of the canonical CAST-1.yaml, so all three published builds are byte-identical unified firmware. A fielded device on the old WiFi or Ethernet firmware OTAs from its existing legacy manifest straight into apollo-cast-1 (one-time rename in HA) and from then on updates from the canonical manifest — permanently converged. Why the legacy files/paths are kept for now: GitHub Pages deploys replace the whole site, so dropping firmware-e/ and firmware-w/ today would 404 every not-yet-updated device forever. The build workflows keep publishing them (with comments marking exactly what to delete once the fleet has had a release cycle or two), while CI and the weekly build drop to just the canonical config since the shims add nothing to validate. Version 26.8.26.6 so the legacy fleet sees the convergence update. Co-Authored-By: Claude Fable 5 --- .github/workflows/build-beta.yml | 4 ++++ .github/workflows/build.yml | 6 ++++++ .github/workflows/ci.yml | 8 +++++--- .github/workflows/weekly.yml | 5 ++--- Integrations/ESPHome/CAST-1_ETH.yaml | 29 +++++++++------------------- Integrations/ESPHome/CAST-1_W.yaml | 29 +++++++++------------------- Integrations/ESPHome/Core.yaml | 2 +- README.md | 3 ++- 8 files changed, 38 insertions(+), 48 deletions(-) diff --git a/.github/workflows/build-beta.yml b/.github/workflows/build-beta.yml index c50b628..f13baf3 100644 --- a/.github/workflows/build-beta.yml +++ b/.github/workflows/build-beta.yml @@ -43,6 +43,10 @@ jobs: strategy: matrix: include: + # The _W/_ETH entries are transitional: those files are one-line + # includes of CAST-1.yaml, kept only so the legacy beta manifest + # assets (manifest-w.json / manifest-e.json) keep updating for + # fielded devices. Remove once the fleet has converged. - { yaml: Integrations/ESPHome/CAST-1.yaml, name: firmware } - { yaml: Integrations/ESPHome/CAST-1_W.yaml, name: firmware-w } - { yaml: Integrations/ESPHome/CAST-1_ETH.yaml, name: firmware-e } diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index acfda93..0bd68d2 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -24,6 +24,12 @@ jobs: pull-requests: write with: device-name: cast-1 + # CAST-1_ETH.yaml / CAST-1_W.yaml are transitional includes of the + # canonical CAST-1.yaml: all three builds are the same unified firmware. + # The legacy files stay listed ONLY so firmware-e/ and firmware-w/ keep + # publishing on Pages — fielded devices on the old variants poll those + # manifests, and a Pages deploy replaces the whole site. Remove the two + # legacy lines (and files) once the fleet has converged. yaml-files: | Integrations/ESPHome/CAST-1.yaml Integrations/ESPHome/CAST-1_ETH.yaml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6c30623..388203d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -8,6 +8,11 @@ permissions: # Label check lives in label-check.yml on pull_request_target so it can # label fork-submitted PRs; plain pull_request tokens are read-only there. +# +# Only the canonical unified config is built: CAST-1_ETH.yaml and +# CAST-1_W.yaml are transitional one-line includes of CAST-1.yaml (kept so +# the legacy manifest paths keep publishing), so building them here would +# just compile the same firmware three times. jobs: ci: name: CI @@ -15,10 +20,7 @@ jobs: with: yaml-files: | Integrations/ESPHome/CAST-1.yaml - Integrations/ESPHome/CAST-1_ETH.yaml - Integrations/ESPHome/CAST-1_W.yaml # dev excluded until the TemplateSelect .state incompatibility is fixed esphome-versions: | stable beta - diff --git a/.github/workflows/weekly.yml b/.github/workflows/weekly.yml index 8d45bd6..4903967 100644 --- a/.github/workflows/weekly.yml +++ b/.github/workflows/weekly.yml @@ -7,6 +7,8 @@ on: permissions: contents: read +# Only the canonical unified config is built; the legacy variant files are +# transitional one-line includes of it (see ci.yml). jobs: build: name: Weekly Build @@ -14,10 +16,7 @@ jobs: with: yaml-files: | Integrations/ESPHome/CAST-1.yaml - Integrations/ESPHome/CAST-1_ETH.yaml - Integrations/ESPHome/CAST-1_W.yaml # dev excluded until the TemplateSelect .state incompatibility is fixed esphome-versions: | stable beta - diff --git a/Integrations/ESPHome/CAST-1_ETH.yaml b/Integrations/ESPHome/CAST-1_ETH.yaml index 2fb333a..00af06b 100644 --- a/Integrations/ESPHome/CAST-1_ETH.yaml +++ b/Integrations/ESPHome/CAST-1_ETH.yaml @@ -1,22 +1,11 @@ -# Legacy Ethernet-variant shim. The firmware is identical to CAST-1.yaml -# (WiFi + Ethernet in one image); only the device/project name and the OTA -# manifest URLs differ, so devices originally flashed with the Ethernet -# firmware keep updating from their original manifest without a reflash. -# New installs should use CAST-1.yaml. - -substitutions: - stable_manifest_dir: "firmware-e" - beta_manifest_file: "manifest-e.json" - -esphome: - name: "apollo-cast-1-eth" - project: - name: "ApolloAutomation.CAST-1-ETH" - version: ${version} - -dashboard_import: - package_import_url: github://ApolloAutomation/CAST-1/Integrations/ESPHome/CAST-1_ETH.yaml - import_full_config: false +# TRANSITIONAL — this file exists only so the legacy Ethernet-firmware +# manifest path (firmware-e/) keeps publishing while the fielded fleet +# converges. It builds the canonical unified firmware verbatim, so a device +# still on the old Ethernet firmware OTAs straight into apollo-cast-1 and +# from then on updates from the canonical manifest. +# +# Delete this file (and its entries in .github/workflows/build.yml and +# build-beta.yml) once the fleet has had a release cycle or two to update. packages: - core: !include Core.yaml + unified: !include CAST-1.yaml diff --git a/Integrations/ESPHome/CAST-1_W.yaml b/Integrations/ESPHome/CAST-1_W.yaml index 9313ae0..0d08904 100644 --- a/Integrations/ESPHome/CAST-1_W.yaml +++ b/Integrations/ESPHome/CAST-1_W.yaml @@ -1,22 +1,11 @@ -# Legacy WiFi-variant shim. The firmware is identical to CAST-1.yaml -# (WiFi + Ethernet in one image); only the device/project name and the OTA -# manifest URLs differ, so devices originally flashed with the WiFi firmware -# keep updating from their original manifest without a reflash. -# New installs should use CAST-1.yaml. - -substitutions: - stable_manifest_dir: "firmware-w" - beta_manifest_file: "manifest-w.json" - -esphome: - name: "apollo-cast-1-w" - project: - name: "ApolloAutomation.CAST-1-W" - version: ${version} - -dashboard_import: - package_import_url: github://ApolloAutomation/CAST-1/Integrations/ESPHome/CAST-1_W.yaml - import_full_config: false +# TRANSITIONAL — this file exists only so the legacy WiFi-firmware manifest +# path (firmware-w/) keeps publishing while the fielded fleet converges. It +# builds the canonical unified firmware verbatim, so a device still on the +# old WiFi firmware OTAs straight into apollo-cast-1 and from then on +# updates from the canonical manifest. +# +# Delete this file (and its entries in .github/workflows/build.yml and +# build-beta.yml) once the fleet has had a release cycle or two to update. packages: - core: !include Core.yaml + unified: !include CAST-1.yaml diff --git a/Integrations/ESPHome/Core.yaml b/Integrations/ESPHome/Core.yaml index f8a4f34..3a0ab16 100644 --- a/Integrations/ESPHome/Core.yaml +++ b/Integrations/ESPHome/Core.yaml @@ -1,5 +1,5 @@ substitutions: - version: "26.8.26.5" + version: "26.8.26.6" # Manifest bases: stable=Pages, beta=release assets stable_manifest_base: "https://apolloautomation.github.io/CAST-1" beta_manifest_base: "https://github.com/ApolloAutomation/CAST-1/releases/download/beta-fw" diff --git a/README.md b/README.md index f0cad25..238897f 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,8 @@ variant or reflash to switch: Devices flashed with the older WiFi-only or Ethernet-only firmware receive this unified behavior automatically through their normal firmware update — no -reflash needed. +reflash needed. As part of that update the device adopts the unified name +(`apollo-cast-1-xxxxxx`), so it may show a one-time rename in Home Assistant. ## WizMote From 5726c0aa50ff80f7522d344d7345de3771c316c7 Mon Sep 17 00:00:00 2001 From: Justin Bunton <130115204+Bunton33@users.noreply.github.com> Date: Wed, 26 Aug 2026 17:13:54 -0400 Subject: [PATCH 7/8] Fully remove the legacy WiFi/Ethernet firmware paths (pre-launch clean cut) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit No CAST-1 units have shipped to customers, so there is no fielded fleet to migrate: delete CAST-1_ETH.yaml and CAST-1_W.yaml outright, publish a single firmware/ path, and drop all workflows to one build. build-beta now uploads a single manifest.json; CI/weekly/build each carry exactly one yaml. README loses the migration note (nothing to migrate) and gains a pointer to the Network Connection sensor. Version 26.8.26.7. Bench/dev units on old variant firmware will 404 on their old manifests after the next Pages deploy — reflash those over USB or the installer. Also verified against the wifi component source (2026.8.1) after review feedback: wifi's reboot_timeout cannot fire in wired steady state — loop() returns at WIFI_COMPONENT_STATE_DISABLED before any timeout check, and the reboot path is additionally gated on !has_ap(), which is always true for this config. No 15-minute reboot landmine; no reboot_timeout override needed. Co-Authored-By: Claude Fable 5 --- .github/workflows/build-beta.yml | 54 ++++++++++++---------------- .github/workflows/build.yml | 12 ++----- .github/workflows/ci.yml | 5 --- .github/workflows/weekly.yml | 2 -- Integrations/ESPHome/CAST-1_ETH.yaml | 11 ------ Integrations/ESPHome/CAST-1_W.yaml | 11 ------ Integrations/ESPHome/Core.yaml | 4 +-- README.md | 6 ++-- 8 files changed, 28 insertions(+), 77 deletions(-) delete mode 100644 Integrations/ESPHome/CAST-1_ETH.yaml delete mode 100644 Integrations/ESPHome/CAST-1_W.yaml diff --git a/.github/workflows/build-beta.yml b/.github/workflows/build-beta.yml index f13baf3..c71b8c7 100644 --- a/.github/workflows/build-beta.yml +++ b/.github/workflows/build-beta.yml @@ -5,11 +5,11 @@ name: Build and Publish Beta # updates at these assets. Stable firmware is built/published separately by # build.yml (push to main -> GitHub Pages). # -# NOTE: the canonical (unified) firmware's Beta manifest is the manifest.json -# asset, which only exists once this workflow has run with the three-entry -# matrix below. After the unified-firmware change lands on main, merge it to -# beta (or run this workflow manually) promptly — until then, canonical-build -# devices switched to the Beta channel get a 404 on their update manifest. +# NOTE: the unified firmware's Beta manifest is the manifest.json asset, +# which only exists once this workflow has run after the unified-firmware +# change. Merge to beta (or run this workflow manually) promptly after it +# lands on main — until then, devices switched to the Beta channel get a +# 404 on their update manifest. on: push: @@ -43,13 +43,7 @@ jobs: strategy: matrix: include: - # The _W/_ETH entries are transitional: those files are one-line - # includes of CAST-1.yaml, kept only so the legacy beta manifest - # assets (manifest-w.json / manifest-e.json) keep updating for - # fielded devices. Remove once the fleet has converged. - - { yaml: Integrations/ESPHome/CAST-1.yaml, name: firmware } - - { yaml: Integrations/ESPHome/CAST-1_W.yaml, name: firmware-w } - - { yaml: Integrations/ESPHome/CAST-1_ETH.yaml, name: firmware-e } + - { yaml: Integrations/ESPHome/CAST-1.yaml, name: firmware } uses: esphome/workflows/.github/workflows/build.yml@9f6577fd37b5cf773ab1b9be929714a0dcd15661 # 2026.7.0 with: files: ${{ matrix.yaml }} @@ -84,26 +78,22 @@ jobs: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | BASE="https://github.com/${{ github.repository }}/releases/download/beta-fw" - for pair in "firmware:manifest.json" "firmware-w:manifest-w.json" "firmware-e:manifest-e.json"; do - dir="${pair%%:*}" - asset="${pair##*:}" - man=$(find "fw/$dir" -name manifest.json | head -1) - if [ -z "$man" ]; then - echo "::error::manifest.json not found for $dir" - exit 1 - fi - echo "Rewriting $man -> $asset" - # Make ota.path and parts[].path absolute release-asset URLs so the - # device never has to resolve a relative path against a redirected URL. - jq --arg base "$BASE" ' - .builds[0].ota.path = ($base + "/" + (.builds[0].ota.path | sub(".*/"; ""))) - | .builds[0].parts |= map(.path = ($base + "/" + (.path | sub(".*/"; "")))) - ' "$man" > "$asset" - cat "$asset" - gh release upload beta-fw "$asset" -R "${{ github.repository }}" --clobber - find "fw/$dir" -name '*.bin' -print -exec \ - gh release upload beta-fw {} -R "${{ github.repository }}" --clobber \; - done + man=$(find "fw/firmware" -name manifest.json | head -1) + if [ -z "$man" ]; then + echo "::error::manifest.json not found" + exit 1 + fi + echo "Rewriting $man -> manifest.json" + # Make ota.path and parts[].path absolute release-asset URLs so the + # device never has to resolve a relative path against a redirected URL. + jq --arg base "$BASE" ' + .builds[0].ota.path = ($base + "/" + (.builds[0].ota.path | sub(".*/"; ""))) + | .builds[0].parts |= map(.path = ($base + "/" + (.path | sub(".*/"; "")))) + ' "$man" > "manifest.json" + cat "manifest.json" + gh release upload beta-fw "manifest.json" -R "${{ github.repository }}" --clobber + find "fw/firmware" -name '*.bin' -print -exec \ + gh release upload beta-fw {} -R "${{ github.repository }}" --clobber \; echo "Beta assets published." - name: Point beta-fw tag at the built commit diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 0bd68d2..37655f3 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -24,17 +24,11 @@ jobs: pull-requests: write with: device-name: cast-1 - # CAST-1_ETH.yaml / CAST-1_W.yaml are transitional includes of the - # canonical CAST-1.yaml: all three builds are the same unified firmware. - # The legacy files stay listed ONLY so firmware-e/ and firmware-w/ keep - # publishing on Pages — fielded devices on the old variants poll those - # manifests, and a Pages deploy replaces the whole site. Remove the two - # legacy lines (and files) once the fleet has converged. yaml-files: | Integrations/ESPHome/CAST-1.yaml - Integrations/ESPHome/CAST-1_ETH.yaml - Integrations/ESPHome/CAST-1_W.yaml - firmware-names: "1:firmware,1_ETH:firmware-e,1_W:firmware-w" + # Maps CAST-1.yaml to the firmware/ output dir (the shared workflow's + # pattern key is everything after the last dash of the filename). + firmware-names: "1:firmware" core-yaml-path: Integrations/ESPHome/Core.yaml esphome-version: stable # Bypass check if manually triggered with bypass option diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 388203d..06ae52e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -8,11 +8,6 @@ permissions: # Label check lives in label-check.yml on pull_request_target so it can # label fork-submitted PRs; plain pull_request tokens are read-only there. -# -# Only the canonical unified config is built: CAST-1_ETH.yaml and -# CAST-1_W.yaml are transitional one-line includes of CAST-1.yaml (kept so -# the legacy manifest paths keep publishing), so building them here would -# just compile the same firmware three times. jobs: ci: name: CI diff --git a/.github/workflows/weekly.yml b/.github/workflows/weekly.yml index 4903967..c0dadaa 100644 --- a/.github/workflows/weekly.yml +++ b/.github/workflows/weekly.yml @@ -7,8 +7,6 @@ on: permissions: contents: read -# Only the canonical unified config is built; the legacy variant files are -# transitional one-line includes of it (see ci.yml). jobs: build: name: Weekly Build diff --git a/Integrations/ESPHome/CAST-1_ETH.yaml b/Integrations/ESPHome/CAST-1_ETH.yaml deleted file mode 100644 index 00af06b..0000000 --- a/Integrations/ESPHome/CAST-1_ETH.yaml +++ /dev/null @@ -1,11 +0,0 @@ -# TRANSITIONAL — this file exists only so the legacy Ethernet-firmware -# manifest path (firmware-e/) keeps publishing while the fielded fleet -# converges. It builds the canonical unified firmware verbatim, so a device -# still on the old Ethernet firmware OTAs straight into apollo-cast-1 and -# from then on updates from the canonical manifest. -# -# Delete this file (and its entries in .github/workflows/build.yml and -# build-beta.yml) once the fleet has had a release cycle or two to update. - -packages: - unified: !include CAST-1.yaml diff --git a/Integrations/ESPHome/CAST-1_W.yaml b/Integrations/ESPHome/CAST-1_W.yaml deleted file mode 100644 index 0d08904..0000000 --- a/Integrations/ESPHome/CAST-1_W.yaml +++ /dev/null @@ -1,11 +0,0 @@ -# TRANSITIONAL — this file exists only so the legacy WiFi-firmware manifest -# path (firmware-w/) keeps publishing while the fielded fleet converges. It -# builds the canonical unified firmware verbatim, so a device still on the -# old WiFi firmware OTAs straight into apollo-cast-1 and from then on -# updates from the canonical manifest. -# -# Delete this file (and its entries in .github/workflows/build.yml and -# build-beta.yml) once the fleet has had a release cycle or two to update. - -packages: - unified: !include CAST-1.yaml diff --git a/Integrations/ESPHome/Core.yaml b/Integrations/ESPHome/Core.yaml index 3a0ab16..8bcc055 100644 --- a/Integrations/ESPHome/Core.yaml +++ b/Integrations/ESPHome/Core.yaml @@ -1,10 +1,8 @@ substitutions: - version: "26.8.26.6" + version: "26.8.26.7" # Manifest bases: stable=Pages, beta=release assets stable_manifest_base: "https://apolloautomation.github.io/CAST-1" beta_manifest_base: "https://github.com/ApolloAutomation/CAST-1/releases/download/beta-fw" - # Manifest targets for this build; legacy variant files override these so - # already-deployed devices keep updating from their original URLs. stable_manifest_dir: "firmware" beta_manifest_file: "manifest.json" diff --git a/README.md b/README.md index 238897f..8cd99c7 100644 --- a/README.md +++ b/README.md @@ -19,10 +19,8 @@ variant or reflash to switch: network, or opens the "Apollo CAST 1 Hotspot" for setup if none is configured (Improv via Bluetooth or USB works too). -Devices flashed with the older WiFi-only or Ethernet-only firmware receive -this unified behavior automatically through their normal firmware update — no -reflash needed. As part of that update the device adopts the unified name -(`apollo-cast-1-xxxxxx`), so it may show a one-time rename in Home Assistant. +Use the on-device **Network Connection** sensor (Diagnostics) to see which +connection is active at a glance. ## WizMote From 9fc5ce00d95e15ad74430d4cab4436625f1d017a Mon Sep 17 00:00:00 2001 From: Justin Bunton <130115204+Bunton33@users.noreply.github.com> Date: Wed, 26 Aug 2026 20:20:06 -0400 Subject: [PATCH 8/8] Make the release-path comments match observed behavior (review round 3) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A third adversarial review confirmed every engineering claim against the 2026.8.1 source and IDF 5.5.4 with no surviving blockers, and caught two comments overstating themselves: - The hotspot-release reboot is once per live-hotspot kill, not once per setup: an unprovisioned wired device repeats it on every cable outage longer than the 90s AP timer. Documented, and kept in preference to gating the cable-out hotspot on wifi_provisioned — that would break the documented "unplug the cable to set up WiFi" provisioning path, while the reboot can never interrupt playback (no network existed during the outage). - The wifi-loss 60s grace can end early on a reconnect-then-drop during the wait; the 10-minute recovery probe covers that case. Also cleaned at release level (not in-repo): the stale legacy assets on the beta-fw release (26.8.25.x manifest-w/e.json and binaries) are deleted so nothing can ever fetch a pre-unified image. Co-Authored-By: Claude Fable 5 --- Integrations/ESPHome/Core.yaml | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/Integrations/ESPHome/Core.yaml b/Integrations/ESPHome/Core.yaml index 8bcc055..ea5a923 100644 --- a/Integrations/ESPHome/Core.yaml +++ b/Integrations/ESPHome/Core.yaml @@ -199,10 +199,12 @@ wifi: - lambda: "id(wifi_provisioned) = true;" - component.update: update_http_request on_disconnect: - # WiFi lost its network while Ethernet carries the device: after a grace - # period for reassociation, turn WiFi off rather than let the fallback - # hotspot appear (ap_timeout is 90s; deciding at 60s keeps it from ever - # starting). Harmless when triggered by wifi.disable itself — the + # WiFi lost its network while Ethernet carries the device: after up to + # 60s for reassociation, turn WiFi off rather than let the fallback + # hotspot appear (ap_timeout is 90s; deciding by 60s keeps it from ever + # starting). A reconnect-then-drop during the wait can release earlier + # than the full 60s — the 10-minute recovery probe restores dual-home in + # that case. Harmless when triggered by wifi.disable itself — the # wifi.enabled check below skips the release then. - if: condition: @@ -711,7 +713,13 @@ script: # merely disabling WiFi would leave the next cable-out provisioning # attempt with a half-dead hotspot (SSID joins, but 192.168.4.1 serves # nothing — observed on hardware). The reboot lands Ethernet-only in - # seconds with the latch cleared, and happens at most once per setup. + # seconds with the latch cleared. It fires only when a live hotspot must + # be killed: a fresh device's first cable-connect, or an unprovisioned + # wired device whose cable was out long enough (>90s) for the hotspot to + # appear — in both cases the device had no network, so no playback is + # interrupted. A device on a regularly-failing switch repeats this per + # outage cycle; kept in preference to suppressing the cable-out hotspot, + # which is a documented provisioning path. then: - lambda: "id(ethernet_expected) = true;" - if: