diff --git a/README.md b/README.md index b181657..c0e7ce2 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ OpenAthan is an open-source, low-cost DIY Athan and Quran smart speaker project. It supports an ordinary-user reference build and a reusable ESPHome integration for people who already have compatible hardware. The reference experience is intended to work without soldering, PCB design, Home Assistant, or embedded-development experience. -> **Project status:** [v0.4.0](https://github.com/OpenAthan-Project/openathan/releases/tag/v0.4.0) is available for AtomS3R C126 + Pyramid A167, with standalone scheduled Athan, a display, phone-friendly setup and settings, USB Wi-Fi/password recovery and owner-requested updates. [v0.5.0 preparation](docs/development/v0.5.0-preparation-2026-10-10.md) adds Waveshare Box V2 production firmware and browser installation. That candidate has not been published; its physical production installation and update qualification remain pending. Newer Atom ST7735 display revisions remain unqualified. +> **Project status:** [v0.5.0](https://github.com/OpenAthan-Project/openathan/releases/tag/v0.5.0) is available for AtomS3R C126 + Voice Pyramid A167 and Waveshare ESP32-S3-Touch-LCD-1.85C-BOX V2. Both support standalone scheduled Athan, a display, phone-friendly setup and settings, USB Wi-Fi/password recovery and owner-requested signed updates. See the [release notes](docs/releases/v0.5.0.md) and [qualification results](docs/development/release-validation-2026-10-10.md). Waveshare V1 is not supported; newer Atom ST7735 display revisions remain unqualified. Use the [public setup guide](https://openathan.com/docs/getting-started/) for a new speaker and the [firmware update guide](docs/development/firmware-upgrades.md) @@ -20,14 +20,14 @@ builds exact source commits and packages the [approved normal and Fajr recording ### Ordinary users 1. Buy the documented reference hardware. -2. Plug the pre-assembled modules together. +2. Assemble the Atom + Pyramid modules, or use the pre-assembled Waveshare Box V2. 3. Connect the device over USB. 4. Visit [openathan.com/install](https://openathan.com/install). 5. Install OpenAthan and enter Wi-Fi credentials. 6. Complete the phone-friendly local setup wizard. 7. Use the device standalone. -Precompiled reference releases are available through [openathan.com/install](https://openathan.com/install). This path requires neither YAML nor ESPHome knowledge. Use only the Atom USB-C data connection during setup, then disconnect it and use only Pyramid bottom power for normal playback. After a cold boot, the current reference firmware needs internet time synchronization before automatic playback can resume. +Precompiled releases are available through [openathan.com/install](https://openathan.com/install). This path requires neither YAML nor ESPHome knowledge. For Atom, use only its USB-C data connection during setup, then disconnect it and use only Pyramid bottom power for normal playback. Waveshare Box V2 uses its rear USB-C data port. First setup requires internet time synchronization. Atom also needs internet time after a cold boot; Waveshare can restore initialized RTC time after a powered restart. RTC battery-backed retention while unplugged has not yet been verified. ### ESPHome users @@ -37,15 +37,17 @@ The reusable package treats hardware as capabilities. An audio playback endpoint Home Assistant may eventually be supported as an optional integration on either path, but it will not be required for core operation. -## Initial reference hardware +## Supported reference hardware -The first official precompiled reference build targets: +The original precompiled reference build uses: - **M5Stack AtomS3R C126** — ESP32-S3, 8 MB flash, 8 MB PSRAM, and a 0.85-inch display. - **M5Stack Voice Pyramid A167** — speaker and audio hardware, microphone, RGB LEDs, capacitive touch controls, and enclosure. SKU A167 has also been called **Echo Pyramid**; verify the SKU when purchasing. See the [AtomS3R documentation](https://docs.m5stack.com/en/core/AtomS3R), [Voice Pyramid documentation](https://docs.m5stack.com/en/atom/Voice_Pyramid), and [reference bill of materials](hardware/reference-builds/voice-pyramid/bom.md). +The second supported build is **Waveshare ESP32-S3-Touch-LCD-1.85C-BOX V2**: a pre-assembled ESP32-S3 speaker with a round display, 16 MiB flash, 8 MiB PSRAM and onboard RTC. See the [Waveshare profile and hardware mappings](docs/development/waveshare-box-v2.md). V1 has different audio hardware and is not supported. Touch input, microphones and SD storage are not yet supported by OpenAthan. + This C126 + A167 combination is the designated reference target, not a requirement of the reusable OpenAthan package. RTC, removable storage, larger external speakers, and other modules are optional capabilities rather than core requirements. ## Architecture @@ -62,10 +64,12 @@ OpenAthan │ └── required and optional capability interfaces ├── hardware integrations │ ├── Voice Pyramid A167 adapter +│ ├── Waveshare Box V2 audio, display and RTC adapters │ └── user-supplied ESPHome components ├── official reference firmware │ ├── validated AtomS3R C126 board configuration │ ├── C126 + A167 capability mapping +│ ├── Waveshare Box V2 production configuration │ └── provisioning, networking, OTA, and release configuration └── local OpenAthan device UI ``` @@ -99,15 +103,15 @@ Settings can be changed through the authenticated local interface. The reference build includes phone-friendly setup, local configuration, USB Wi-Fi/password recovery, explicit first-run activation, prayer-status LEDs and signed application updates. The [roadmap](docs/development/roadmap.md) -separates shipped features from remaining work and validation limits. Touch -and display controls remain future optional adapters; neither is required by -the reusable scheduler. +separates shipped features from remaining work and validation limits. Displays +and their saved brightness/time-format controls are optional capabilities; +touch controls remain future work. None is required by the reusable scheduler. -Quran streaming, reciter and passage selection, resume position, adhkar, offline Quran storage, RTC expansion, and optional Home Assistant integration are later work. Streaming audio should use PSRAM for buffering; Quran audio is not expected to fit in the AtomS3R's flash. +Quran streaming, reciter and passage selection, resume position, adhkar, offline Quran storage, RTC expansion for other hardware, and optional Home Assistant integration are later work. Streaming audio should use PSRAM for buffering; Quran audio is not expected to fit in the AtomS3R's flash. ## Development safety -- Do not add hardware pin mappings until they have been verified against official M5Stack documentation or source and physical hardware. +- Do not add hardware pin mappings until they have been verified against the manufacturer's documentation or source and physical hardware. - Do not present scaffold files as installable firmware. - Do not commit Wi-Fi credentials or signing secrets. - Do not bundle third-party Athan or Quran recordings without explicit, compatible redistribution rights. diff --git a/docs/development/architecture.md b/docs/development/architecture.md index 7a52161..83e1fc5 100644 --- a/docs/development/architecture.md +++ b/docs/development/architecture.md @@ -162,7 +162,7 @@ acceptance or release readiness. Core Athan scheduling must not require Home Assistant or a cloud service. Internet may be used for initial/periodic time sync, Quran streaming, firmware downloads, or optional services. -The generic ESPHome package does not configure Wi-Fi. Reference firmware provides USB provisioning, while ESPHome integrators keep their existing network configuration. The current reference build needs internet time synchronization after a cold boot; saved settings cannot establish the current time. The [Waveshare development profile](waveshare-box-v2.md#rtc-and-offline-restart) can restore previously initialized RTC time after a powered reset; physical qualification is pending. With a valid clock, prayer calculation and stored-recording playback remain local. +The generic ESPHome package does not configure Wi-Fi. Reference firmware provides USB provisioning, while ESPHome integrators keep their existing network configuration. Atom needs internet time synchronization after a cold boot; saved settings cannot establish the current time. The [Waveshare profile](waveshare-box-v2.md#rtc-and-offline-restart) can restore previously initialized RTC time after a powered reset. [Attended RTC RESET validation](waveshare-rtc-validation-2026-10-10.md#attended-powered-reset-validation) passed; retention while unplugged remains unverified. With a valid clock, prayer calculation and stored-recording playback remain local. ## Public website boundary diff --git a/docs/development/feasibility-report.md b/docs/development/feasibility-report.md index 3fd69fa..f33f03d 100644 --- a/docs/development/feasibility-report.md +++ b/docs/development/feasibility-report.md @@ -2,8 +2,8 @@ This report preserves the dated development measurements and device observations below. They are not current release sizes or a statement of today's pending work. -For v0.3.0 production, media and public-installer status, see the -[2026-10-04 release summary](release-validation-2026-10-04.md). +For v0.5.0 production sizes, hardware qualification and public-installer status, +see the [2026-10-10 release summary](release-validation-2026-10-10.md). **The compile-time capacity target passed.** ESPHome, released Adhan C++, and the shared audio adapter fit comfortably in each 2 MiB OTA slot. Both supplied diff --git a/docs/development/firmware-upgrades.md b/docs/development/firmware-upgrades.md index e8acef3..e09076e 100644 --- a/docs/development/firmware-upgrades.md +++ b/docs/development/firmware-upgrades.md @@ -165,7 +165,7 @@ new transport-specific physical qualification and a capable release are availabl ## Hardware-specific releases -v0.5.0 preparation adds the Waveshare Box V2 production profile. Atom retains +Published v0.5.0 adds the Waveshare Box V2 production profile. Atom retains `upgrade.json` and `firmware.ota.bin`; Waveshare uses `waveshare-box-v2.upgrade.json` and `waveshare-box-v2.firmware.ota.bin`. Each signed payload binds its hardware identity, and each device discovers only its @@ -175,4 +175,9 @@ USB firmware INFO accepts the legacy nine fields and appends hardware as a tenth field in new builds. USB status also appends `hardware=` after the existing fields/URLs; older website clients ignore it as a non-URL. The new installer validates the identity and uses Atom compatibility for older responses. -Physical Waveshare production update qualification remains pending. +Attended Waveshare signed-update, pre-selection power-cut recovery and +failed-startup rollback checks passed using isolated qualification builds. +Exact production restoration, preserved production records/audio and the real +public signed-descriptor check also passed. See the +[release qualification report](release-validation-2026-10-10.md) for the scope; +these results do not qualify the separate browser USB update transport. diff --git a/docs/development/release-validation-2026-10-10.md b/docs/development/release-validation-2026-10-10.md new file mode 100644 index 0000000..37412a0 --- /dev/null +++ b/docs/development/release-validation-2026-10-10.md @@ -0,0 +1,94 @@ +# v0.5.0 release qualification — 2026-10-10 Toronto + +[v0.5.0](../releases/v0.5.0.md) is published as stable/latest from +`9e47867facd06164ede96a77859a77896cdb4123`. It adds Waveshare Box V2 alongside +AtomS3R C126 + Voice Pyramid A167. The [public installer](https://openathan.com/install/) +serves both hardware bundles. Qualification below covers one attended Waveshare +V2 unit with 16 MiB flash and 8 MiB PSRAM; earlier Atom evidence retains its +original scope. + +## Production artifacts and automated checks + +Exact-source [firmware CI](https://github.com/OpenAthan-Project/openathan/actions/runs/38067247571) +passed all 12 jobs. Both production builds passed pinned ESPHome 2026.9.0 / +ESP-IDF 5.5.5 dependency, image, partition, recording-exclusion and capacity +checks. Each actual OTA image remains below the 1,572,864-byte application limit. +Both 2 MiB slots and the separate 3.5 MiB shared audio partition are retained. + +| Production board | OTA bytes | Application budget remaining | Free bytes per 2 MiB slot | +| --- | ---: | ---: | ---: | +| AtomS3R + Voice Pyramid | 1,277,392 | 295,472 | 819,760 | +| Waveshare Box V2 | 1,284,784 | 288,080 | 812,368 | + +These exact version/source-identified images are each 32 bytes larger than the +corresponding [prepared production build](v0.5.0-preparation-2026-10-10.md#matched-ota-measurements). +The private qualification applications are separate images with isolated records, +private update trust and test controls; none enters the public release. + +## Attended Waveshare results + +| Check | Observed result | +| --- | --- | +| Fresh installation | Browser erase/install completed; complete 16 MiB readback verified production firmware and approved audio. Physical RESET showed setup needed. | +| Local setup and USB identity | Owner completed Wi-Fi, password and settings setup. Compatible OpenAthan reported Waveshare Box V2 and Chrome recognized it automatically. Unknown firmware required explicit model selection. | +| Invalid signature | Private-feed descriptor was rejected without queuing an installation or erasing/writing an application. | +| Signed Wi-Fi update | Healthy private v0.0.2 transferred, switched slots and moved from PENDING to VALID; the queue cleared. | +| Power cut before selection | After the full target was finalized but before selection, attended power removal/reconnection retained the old VALID image and durable queue. A controlled truncated retry remained unselected and cancellation cleared the queue. | +| Failed startup | Private v0.0.3 remained unconfirmed and automatically rolled back to the previous VALID v0.0.2; the rejected request cleared. | +| Production preservation and restoration | Fresh paired reads verified production records and complete shared audio. One application-only restoration installed the exact v0.5.0 application; independent readback protected the other flash regions. Production startup and saved-state reconciliation passed. | + +After installation was verified, the browser could not reconnect automatically +for setup. Physical RESET and USB reconnection completed the setup flow without +reinstalling. BOOT-held download mode was used during installation preparation. + +Fresh installation deliberately erased the previous device data. Subsequent +preservation checks use the newly configured production baseline: settings, +credentials, preferences and audio were preserved through isolated OTA testing. +Prayer consumption did not regress; the one naturally elapsed production prayer +advanced its watermark. Historical NVS/full-flash restoration was not used. + +The bounded power observer did not capture the exact unplugged duration or screen +darkness. The owner response and fresh power-on reset state support the recovery +result. These cases are a focused Waveshare extension, not a repeat of the entire +earlier [Atom interruption matrix](upgrade-qualification-2026-10-01.md). + +212 quiet isolated OTA samples recorded internal free/largest-block minima of +194,676 / 143,360 bytes, internal low-water 192,640 bytes, PSRAM free/largest-block +minima of 8,031,200 / 7,995,392 bytes and updater unused-stack minimum 3,952 bytes. +Announcements were disabled; these observations do not establish concurrent +audio/network/display headroom or clean-production runtime memory. + +## Reused hardware evidence and limits + +The release RTC adapter files match tested source `1378dc2`, and the audio adapter +files match tested source `96670c1`, byte for byte. Reuse covers +[powered offline RTC RESET](waveshare-rtc-validation-2026-10-10.md#attended-powered-reset-validation), +[volume/listening and cold restart](waveshare-volume-build-2026-10-10.md), and +the separately dated [BOOT controls](waveshare-buttons-validation-2026-10-09.md) +and [development playback/scheduling/soak](waveshare-validation-2026-10-09.md). +Those results retain their tested images and observation gaps; no new full +listening session, real scheduled announcement or hour-long soak is claimed here. + +RTC battery-backed unplugged retention, long-term drift and audible scheduled +playback using RTC-only time remain unqualified. Other display-panel lots and +broader hardware/browser/network coverage need separate validation. Earlier +intermittent HTTP timeouts remain unresolved. Touch, microphones and SD storage +remain deferred. Preserving browser USB updates require separate transport +qualification; public USB application writes remain disabled. + +## Public delivery + +All 13 unauthenticated GitHub downloads matched the immutable validated bundle; +both board signatures and the combined artifact contract passed. The +[website deployment](https://github.com/OpenAthan-Project/website/actions/runs/38098999421) +at source `358079bdac8b9d045c2dd50b6d58021548a3fd56` passed 180 unit tests, +369 development browser tests, 171 built-site browser tests and the release +freshness gate. Live metadata selected the correct manifests for both boards, +and all nine website-imported assets matched the release bytes. + +The restored production Waveshare checked the real public signed descriptor and +reported v0.5.0 current, with no error or installation queued. Settings, history +and preferences matched the before-check state; clock and automatic readiness +were true. This establishes the device's public descriptor path, not a new +public-feed application-transfer test. Raw diagnostics, snapshots, credentials +and private qualification material remain outside Git. diff --git a/docs/development/releases.md b/docs/development/releases.md index 49c5633..55d6f51 100644 --- a/docs/development/releases.md +++ b/docs/development/releases.md @@ -1,8 +1,9 @@ # Firmware release preparation -[v0.4.0](../releases/v0.4.0.md) is the published stable reference release. -The v0.5.0 candidate adds Waveshare Box V2 alongside Atom. Candidate preparation -does not establish physical installer/update qualification or publication. +[v0.5.0](../releases/v0.5.0.md) is the published stable release for Atom and +Waveshare Box V2. The [release qualification report](release-validation-2026-10-10.md) +records exact production images, attended Waveshare installation/update results, +public delivery and remaining limits. The [v0.4.0 preparation record](v0.4.0-preparation-2026-10-07.md) records its automated builds and physical-validation limits. The earlier [release evidence](release-validation-2026-10-04.md) records reference-device @@ -28,7 +29,7 @@ revision containing that approval and the exact approved MP3 files. Other privat test recordings, CI audio fixtures and historical recovery images are not release inputs. This tooling never flashes or publishes. Once a qualified release is explicitly published as stable latest, the website's automatic policy can adopt -it after validation. See the [current release evidence](release-validation-2026-10-04.md). +it after validation. See the [current release evidence](release-validation-2026-10-10.md). ## Prerequisites diff --git a/docs/development/roadmap.md b/docs/development/roadmap.md index d555ee1..cb20cf3 100644 --- a/docs/development/roadmap.md +++ b/docs/development/roadmap.md @@ -1,24 +1,25 @@ # Roadmap -Status as of **2026-10-04**, following the v0.3.0 reference release and verified +Status as of **2026-10-10 Toronto**, following the v0.5.0 release and verified website adoption. Checked items describe implemented or published capabilities, not blanket physical qualification. See the -[current release evidence and limits](release-validation-2026-10-04.md), [earlier device results](feasibility-report.md) +[current release evidence and limits](release-validation-2026-10-10.md), [earlier device results](feasibility-report.md) and [upgrade qualification](upgrade-qualification-2026-10-01.md). ## Current milestone -The standalone Athan reference experience is available on AtomS3R C126 + -Voice Pyramid A167: precompiled USB installation, local setup/settings, +The standalone Athan experience is available on AtomS3R C126 + Voice Pyramid A167 +and Waveshare Box V2: precompiled USB installation, local setup/settings, scheduled stored normal/Fajr audio, durable skip/replay protection, optional -prayer lights, an optional GC9107 clock/prayer/playback display, USB credential +Atom prayer lights, hardware-specific clock/prayer/playback displays, USB credential recovery and owner-requested signed application updates. The website verifies and adopts approved stable releases; it never compiles firmware or updates a speaker on its owner's behalf. -The reference firmware needs internet time synchronization after a cold boot. -Waveshare development firmware includes RTC restoration after a powered reset; -[physical RTC acceptance](waveshare-rtc-validation-2026-10-10.md) is pending. +Atom firmware needs internet time synchronization after a cold boot. Waveshare +production firmware includes RTC restoration after a powered reset, following +initial internet time synchronization. [Attended powered RESET validation](waveshare-rtc-validation-2026-10-10.md#attended-powered-reset-validation) +passed; unplugged retention and RTC-only scheduled listening remain unqualified. Once the clock is valid, calculations and stored-recording playback operate without the public website or Home Assistant. Compatible firmware updates preserve installed audio; replacing recordings is separate from application OTA. @@ -35,7 +36,8 @@ preserve installed audio; replacing recordings is separate from application OTA. - [ ] Qualify broader hardware/browser/network coverage and longer runtime operation. Measurements and physical results remain tied to their tested images. The -linked v0.3.0 evidence does not include a new physical fresh-install test or a +[earlier v0.3.0 evidence](release-validation-2026-10-04.md) does not include a new +physical fresh-install test or a public OTA application-transfer/slot-switch test. Its focused instrumented display/audio memory run contains a 13m50s observation gap and does not establish maximum-load production headroom or overnight stability. Earlier accepted @@ -55,6 +57,7 @@ evidence is retained within its source limits. - [ ] Optional touch playback/volume/dismiss adapter. - [x] Optional GC9107 AtomS3R display-status adapter (published in v0.3.0; [production orientation and bounded memory results](release-validation-2026-10-04.md)). +- [x] Waveshare Box V2 production audio, round display and BOOT controls (published in v0.5.0). Audio is fundamental; optional peripherals do not gate the reusable scheduler. @@ -68,12 +71,13 @@ Audio is fundamental; optional peripherals do not gate the reusable scheduler. - [x] Startup health confirmation, compatible bootloader checks and automatic rollback. - [x] Document preserving USB transitions for older firmware/bootloaders. - [x] Automatic website adoption of published stable latest releases after validation. +- [ ] Qualify and enable browser USB firmware updates that preserve saved data. The fresh installer erases settings, credentials and prayer history. Existing -speakers use compatible device-page updates or a reviewed preserving USB -transition. Older partition layouts need a deliberate migration; ordinary -application OTA cannot change them. Historical NVS restores old consumption -history and is not routine recovery. +speakers use compatible device-page updates or a reviewed maintainer USB +transition; preserving browser USB update writes remain disabled. Older partition +layouts need a deliberate migration; ordinary application OTA cannot change them. +Historical NVS restores old consumption history and is not routine recovery. The signed updater's interruption, handoff and rollback tests use a separate maintainer qualification build. Production excludes its private feed, isolated @@ -90,8 +94,9 @@ discovery is separate from public OTA application-transfer acceptance. ## Phase 4 — Offline resilience and expansion -- [x] Implement onboard RTC restoration for Waveshare V2 development firmware. -- [ ] Qualify Waveshare RTC offline restart; backup-power retention remains deferred. +- [x] Implement onboard RTC restoration for Waveshare V2 production and development firmware. +- [x] Qualify Waveshare clock restoration after offline physical RESET with RTC power retained. +- [ ] Qualify RTC-only scheduled playback, backup-power retention and long-term drift. - [ ] Evaluate RTC expansion for other hardware. - [ ] Evaluate microSD or USB mass storage. - [ ] Optional offline Quran library. diff --git a/docs/development/v0.5.0-preparation-2026-10-10.md b/docs/development/v0.5.0-preparation-2026-10-10.md index 422c357..45619d3 100644 --- a/docs/development/v0.5.0-preparation-2026-10-10.md +++ b/docs/development/v0.5.0-preparation-2026-10-10.md @@ -1,9 +1,15 @@ # v0.5.0 preparation — 2026-10-10 -This prepares Atom and Waveshare Box V2 production profiles, combined release +**Historical preparation checkpoint:** v0.5.0 was subsequently published as +stable/latest on 2026-10-10 Toronto. See the +[release qualification report](release-validation-2026-10-10.md) for completed +hardware checks, public delivery and remaining limits. The measurements and +pending list below describe the earlier preparation stage. + +This prepared Atom and Waveshare Box V2 production profiles, combined release packaging and browser hardware selection. It does not publish a release or establish new physical acceptance. No hardware access or flashing occurred. -See the [candidate release notes](../releases/v0.5.0.md). +See the [published release notes](../releases/v0.5.0.md). ## Configuration and artifact contract diff --git a/docs/development/waveshare-box-v2.md b/docs/development/waveshare-box-v2.md index 39adccd..ba741c1 100644 --- a/docs/development/waveshare-box-v2.md +++ b/docs/development/waveshare-box-v2.md @@ -1,11 +1,13 @@ # Waveshare Box V2 profiles -The ESP32-S3-Touch-LCD-1.85C-BOX **V2** development profile reuses standalone -prayer calculations, scheduling, stored recordings, USB provisioning and the +The ESP32-S3-Touch-LCD-1.85C-BOX **V2** production and development profiles reuse +standalone prayer calculations, scheduling, stored recordings, USB provisioning and the authenticated device-local phone controls. V1 uses different audio hardware and is not supported by this profile. Touch, microphones and SD storage are -deferred. Physical acceptance is recorded in the -[dated validation report](waveshare-validation-2026-10-09.md). +deferred. Production is available in [v0.5.0](../releases/v0.5.0.md). +See the [release qualification report](release-validation-2026-10-10.md) and +[earlier development validation](waveshare-validation-2026-10-09.md) for physical +results and their limits. ## Build and storage @@ -62,7 +64,7 @@ session. | Backlight | GPIO5, 5 kHz PWM, saved 1–100%, default 50% | | Panel reset | TCA9554 `0x20`, zero-based P1, vendor's one-based EXIO2 | | Shared I²C | SCL 10, SDA 11; confirmed on the attended unit | -| PCF85063A RTC | I²C `0x51` on the shared bus; RTC physical acceptance pending | +| PCF85063A RTC | I²C `0x51` on the shared bus; powered offline RESET restoration observed on one V2 unit | | BOOT button | GPIO0, active-low input with pull-up; stop/skip/cancel observed on the attended V2 unit | The mappings follow the [manufacturer's V2 audio example](https://github.com/waveshareteam/ESP32-S3-Touch-LCD-1.85C/blob/8ead4a96bf3a278fc4ebd8ef4768657e17fa2880/Arduino/examples/03_audio_out_no_tf/03_audio_out_no_tf.ino), @@ -101,8 +103,9 @@ after cold restart. Saved settings/history were preserved, and the clean development application was restored at 80%. See the [volume build and attended validation report](waveshare-volume-build-2026-10-10.md) for exact images, size comparisons, diagnostic runtime measurements and remaining -limits. Clean-image runtime memory, a new real scheduled announcement and the -later production candidate remain separately unqualified by this session. +limits. Clean-image runtime memory and a new real scheduled announcement remain +unmeasured by that session. Later production installation/update qualification +is recorded separately in the [release report](release-validation-2026-10-10.md). ### RTC and offline restart @@ -129,10 +132,11 @@ invalid BCD/calendar fields and bus errors leave automatic Athan waiting for SNT Writes invalidate the marker first and preserve offset, alarms and timers. RTC failures do not invalidate synchronized system time or block audio. -Offline restart support requires the RTC to remain powered. Retention after -unplugging, battery behavior and drift are not qualified. Hardware acceptance and -runtime memory checks remain pending; see the -[RTC implementation report and procedure](waveshare-rtc-validation-2026-10-10.md). +Offline restart support requires the RTC to remain powered. Attended offline +RESET restored the clock and automatic readiness without network time on one +V2 unit. Retention after unplugging, battery behavior, drift and audible +scheduled playback using RTC-only time remain unqualified. See the +[RTC implementation and attended validation](waveshare-rtc-validation-2026-10-10.md). Existing activation, skip and consumed-prayer records remain authoritative: startup and clock corrections do not play missed or consumed occurrences. @@ -152,10 +156,11 @@ BOOT's GPIO0 connection follows the linked V2 schematic; holding it during reset or power-on still enters ROM download mode. RESET is wired to the chip reset input and retains its hardware restart function. Attended stop, skip, cancel-skip and RESET skip-persistence checks passed on one V2 unit, preserving settings, -history and shared audio. Exact timing boundaries, unassigned gaps and the -BOOT-held physical download-mode sequence remain untested. See the +history and shared audio. BOOT-held download mode was subsequently used for +production installation; +exact timing boundaries and unassigned gaps remain untested. See the [automated and attended validation](waveshare-buttons-validation-2026-10-09.md) -for source/image identities, capacity and remaining limits. +and [release report](release-validation-2026-10-10.md) for their separate scopes. ### Display @@ -212,9 +217,9 @@ cycling from software restart, and queued playback from audible acceptance. Prefer compatible application-only recovery after initial partition migration; a full-flash restore also restores historical settings and prayer consumption. -## Production release candidate +## Production release -`firmware/esphome/waveshare/production.yaml` is the v0.5.0 production candidate. +`firmware/esphome/waveshare/production.yaml` is the published v0.5.0 production profile. It uses `openathan` with a MAC suffix, production settings/setup/network/upgrade storage, round display, BOOT controls and signed updates. It omits diagnostic and isolated-storage components. Existing isolated development records are not migrated. @@ -226,6 +231,8 @@ approved audio partition with Atom. The website selects matching firmware from reported OpenAthan USB hardware identity; unknown firmware requires explicit model and erase confirmation. See [release preparation](releases.md). -The [v0.5.0 preparation report](v0.5.0-preparation-2026-10-10.md) separates -automated evidence from pending production installation, update/recovery and -new volume-mapping listening qualification. No new physical acceptance is claimed. +The [v0.5.0 release report](release-validation-2026-10-10.md) records production +installation, signed-update/interruption/rollback qualification, exact restoration +and public delivery. Earlier audio, volume, BOOT and powered RTC results are +reused within their source limits. Preserving browser USB update writes remain +disabled pending separate transport qualification. diff --git a/docs/development/waveshare-rtc-validation-2026-10-10.md b/docs/development/waveshare-rtc-validation-2026-10-10.md index 7f9fcf4..b0ab6e4 100644 --- a/docs/development/waveshare-rtc-validation-2026-10-10.md +++ b/docs/development/waveshare-rtc-validation-2026-10-10.md @@ -1,10 +1,13 @@ -# Waveshare V2 RTC implementation — 2026-10-10 +# Waveshare V2 RTC implementation and powered RESET validation — 2026-10-10 The isolated Waveshare profiles include startup restoration from a previously initialized PCF85063A and verified UTC writes after SNTP synchronization. The [profile](waveshare-box-v2.md#rtc-and-offline-restart) records the protocol, -source references and fallback behavior. This is development implementation; -offline restart and RTC operation on physical hardware remain unqualified. +source references and fallback behavior. Attended offline RESET restoration +passed on one V2 unit with RTC power retained. Battery-backed retention while +unplugged, drift and audible scheduled playback using RTC-only time remain +unqualified. The [v0.5.0 release report](release-validation-2026-10-10.md) records +reuse of this source-bound evidence in the published production profile. ## Automated validation @@ -68,28 +71,40 @@ limit remains 1,572,864 bytes; both 2 MiB slots and separate shared audio are unchanged. Atom profiles do not include the RTC adapter; no new Atom build or browser/hardware acceptance is claimed by these measurements. -## Pending attended acceptance - -1. Follow the [preservation runbook](../../firmware/esphome/provisioning/HARDWARE_TEST.md). - Reidentify the V2 unit, retain current settings/history/audio and compatible - application recovery. Verify the RTC model, `0x51` responder and register layout - on GPIO10/11 before allowing the first RTC write; an address response alone - does not identify the chip. Stop if the hardware differs from the vendor source. -2. Prepare a reviewed application-only candidate with real approved recordings, - isolated storage and disabled public updates. Retain candidate/source hashes, - baseline RTC bytes and the preservation/readback procedure before installation. -3. With internet available, verify `rtc_save=verified`. Confirm saved settings, - consumption history, skip and shared audio remain intact. -4. Block internet time access while retaining local control connectivity and RTC - power. Press RESET; verify `rtc_restore=restored`, correct UTC/local display and - automatic readiness before any network time synchronization. -5. Observe one upcoming scheduled prayer, audible playback and exactly one - consumption advance while offline. Reconnect internet and verify RTC refresh - without replay. Exercise saved-skip persistence in an agreed isolated scenario. -6. Record memory/fragmentation/PSRAM during the focused diagnostic run. Restore the - reviewed clean candidate, confirm preserved state and record clean-image limits. - -Do not inject destructive RTC faults on the attended unit or restore historical -NVS to repeat an occurrence. Backup-power removal, battery retention, drift, -public release/update qualification and the intermittent HTTP defect are separate -work. No physical result or runtime-headroom claim is established by host tests. +## Attended powered RESET validation + +Source `1378dc2f043adaae108059a000e7e54b120f6d3c` includes the network-synchronization +guard. The verified V2 board and pinned vendor source identify the PCF85063A; +registers at `0x51` on GPIO10/11 matched its layout and advanced. An address +response alone was not treated as chip identification. + +Genuine internet synchronization initialized the RTC and verified readback. +Private test controls then blocked network time while retaining local Wi-Fi and +USB power. The owner briefly pressed physical RESET and confirmed the correct +local clock. A fresh boot reported `rtc_restore=restored`, with network time still +disabled and automatic readiness recovered without SNTP. Fresh clock samples +differed from the host by at most 1.508 seconds; cached responses were excluded. +The earlier USB-JTAG restart retained system time and was not counted as RTC +restoration. + +Re-enabling genuine network time verified RTC refresh without replay or changes +to settings, history, skip, setup or display preferences. Fresh paired reads and +independent complete-flash readback preserved saved records and shared audio +through the application-only test installations. The final clean development +application was 1,262,784 bytes, SHA-256 +`5fb0e90263f6dcaf380da6809d86b3ce59e3531bc87f80b2811b0665333571a3`; +normal SNTP was enabled and the temporary diagnostic controls were excluded. +These are dated development results, not the later production application's identity. + +## Remaining limits + +No scheduled prayer was due during the RTC test, so audible playback using +RTC-only time and restart with a nonempty saved skip remain untested. The test +did not remove RTC power, inspect a backup battery, measure long-term drift or +inject destructive hardware faults. Idle diagnostic measurements do not establish +clean-production concurrent audio/network headroom or a new long soak. The +earlier intermittent HTTP issue remains unresolved. + +Further hardware work follows the +[preservation runbook](../../firmware/esphome/provisioning/HARDWARE_TEST.md). +Historical NVS restoration is not a way to repeat a consumed occurrence. diff --git a/docs/development/waveshare-volume-build-2026-10-10.md b/docs/development/waveshare-volume-build-2026-10-10.md index ed6b20d..aa65a5f 100644 --- a/docs/development/waveshare-volume-build-2026-10-10.md +++ b/docs/development/waveshare-volume-build-2026-10-10.md @@ -83,5 +83,6 @@ and a new long soak were not repeated in this focused volume session. Clean-imag runtime heap/fragmentation/PSRAM remains unmeasured. Earlier button and scheduled playback evidence remains separate, as do unresolved intermittent HTTP timeouts. These results establish focused development acceptance; they do not qualify the -later [v0.5.0 production candidate](v0.5.0-preparation-2026-10-10.md), its production -storage, signed updates or recovery. +later v0.5.0 production storage, signed updates or recovery. Those separate +checks are recorded in the [release qualification report](release-validation-2026-10-10.md), +which reuses this listening evidence within its tested source and scope. diff --git a/docs/releases/v0.5.0.md b/docs/releases/v0.5.0.md index 54c9320..71dc6e5 100644 --- a/docs/releases/v0.5.0.md +++ b/docs/releases/v0.5.0.md @@ -1,30 +1,34 @@ # OpenAthan v0.5.0 -Release candidate; not published. - -Waveshare **ESP32-S3-Touch-LCD-1.85C-BOX V2** joins the AtomS3R C126 + Voice -Pyramid A167 reference build. V1 is not supported. - -- Standalone scheduled Athan, approved stored recordings and local phone setup. -- Round display with saved brightness and 12/24-hour formatting. -- BOOT controls to stop playback, skip the next Athan or cancel that skip; - RESET restarts the device. -- Onboard RTC startup recovery after internet synchronization, when RTC power - is retained. Battery retention, unplugged retention and drift are unqualified. -- Board-specific signed application updates preserve production settings, - credentials, playback history and shared audio. -- Browser setup recognizes hardware reported by compatible OpenAthan. Blank or - vendor firmware requires model selection and full-erasure confirmation. - USB preserving update writes remain disabled pending physical qualification. - -Touch, microphones and SD storage remain deferred. The Waveshare volume mapping -now uses the full software volume range; retained settings can sound louder. -Start at a low volume. Listening with this mapping remains pending. - -**Fresh installation erases existing firmware and saved data.** Isolated -development storage is not migrated into production. Existing production -speakers should use the [preserving update guidance](../development/firmware-upgrades.md). -Atom filenames and its existing update compatibility remain supported. - -See [preparation and validation](../development/v0.5.0-preparation-2026-10-10.md) -for automated results, prior hardware evidence and remaining qualification. +Published stable release: [v0.5.0](https://github.com/OpenAthan-Project/openathan/releases/tag/v0.5.0). + +OpenAthan now supports **Waveshare ESP32-S3-Touch-LCD-1.85C-BOX V2**, alongside the AtomS3R C126 + Voice Pyramid A167. **Waveshare V1 is not supported.** + +## What’s included + +- Standalone scheduled Athan with stored normal and Fajr recordings, plus setup and settings from your phone. +- Waveshare’s round display with saved brightness and a 12- or 24-hour clock. +- BOOT button controls to stop playback, skip the next Athan or cancel a skip. +- Clock recovery after a restart using the onboard RTC, after initial internet time synchronization and while RTC power is retained. +- Signed Wi-Fi firmware updates for each supported board, preserving settings, Wi-Fi credentials, prayer history and recordings. +- USB setup that recognizes hardware running compatible OpenAthan. For a blank device or other firmware, you select the model before installation. + +## Install and update + +**[Install and set up OpenAthan](https://openathan.com/install/)** using desktop Chrome or Edge. For Waveshare Box V2, connect a USB data cable to the rear USB-C port. + +**Fresh installation erases existing firmware, Wi-Fi credentials, settings and prayer history.** To preserve saved data, use the Wi-Fi updater in your existing production device’s settings. USB firmware updates that preserve saved data are not yet available through the public installer. + +**Start at a low volume.** Waveshare now uses its full software volume range, so saved volume settings can sound louder than before. + +## Current limitations + +Touch input, microphones and SD card storage are not yet supported. RTC backup-battery operation, time retention while unplugged and long-term clock drift have not yet been verified. + +Waveshare Box V2 installation, setup, signed updates, recovery from a power interruption before the update takes effect, and rollback when an update fails to start passed hardware testing. + +For technical details, see the [firmware update documentation](https://github.com/OpenAthan-Project/openathan/blob/v0.5.0/docs/development/firmware-upgrades.md) and the manifests, build reports and checksums in the [published release assets](https://github.com/OpenAthan-Project/openathan/releases/tag/v0.5.0). + +Recordings: Mishary Rashid Alafasy, via AlAdhan.com / Islamic Network. See [audio attribution and permissions](https://github.com/OpenAthan-Project/openathan/blob/v0.5.0/AUDIO-LICENSES.md). + +See the [release qualification report](../development/release-validation-2026-10-10.md) for production image measurements and the exact scope of hardware testing.