Skip to content

Commit c06fa99

Browse files
committed
[docs] Define exact unqualified firmware beta
Signed-off-by: Viwat Vchirawongkwin <viwat.v@chula.ac.th>
1 parent 6c23a49 commit c06fa99

2 files changed

Lines changed: 100 additions & 44 deletions

File tree

‎docs/specifications/firmware/browser-flashing.md‎

Lines changed: 33 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# PyBLE ESP32-Family Browser Flashing and Release Bundle
22

3-
Status: **FROZEN v1.27** · Owner: project maintainer · Frozen:
3+
Status: **FROZEN v1.28** · Owner: project maintainer · Frozen:
44
2026-07-31 (`[docs]`; pre-v1 two-profile release eligibility and explicit
55
C3 deferral; evidence-derived resource policy and exact HIL V2 records;
66
pre-policy two-root baseline-input staging and mechanical baseline/policy
@@ -20,7 +20,8 @@ component-owned linked outputs, lexical exact-path validation, nested-build
2020
logical paths, shell-free compiler/linker command receipts, executable
2121
version-matched recovery-command syntax, and the canonical pre-v1 same-origin
2222
publication channel with an optional byte-identical mirror, plus bounded
23-
completed-HIL report assembly, on the same date)
23+
completed-HIL report assembly, plus the exact one-version unqualified public
24+
beta exception, on the same date)
2425

2526
This document is the source of truth for the initial browser-provisioning
2627
release bundle. It refines
@@ -37,8 +38,10 @@ BLE and PBLE/1.
3738

3839
## 1. Release image profiles
3940

40-
The current pre-v1 public bundle contains exactly these two qualified
41-
**provisioning image profiles**:
41+
The current pre-v1 browser bundle contains exactly these two
42+
**provisioning image profiles**. The exact `v0.4.1` bytes may be offered only as
43+
the unqualified public beta defined in §10; they are not qualified profiles.
44+
A later qualified public bundle uses the same exact profile definitions:
4245

4346
| Profile ID | ESP Web Tools `chipFamily` | Required target configuration | ESP image silicon window (`min_chip_rev_full`…`max_chip_rev_full`) | Merge settings | Browser image and component map |
4447
|---|---|---|---|---|---|
@@ -394,7 +397,7 @@ beside their metadata:
394397
flash/PSRAM requirements, flash mode/frequency, required
395398
`silicon_revision.minimum_full` and `silicon_revision.maximum_full` integers
396399
matching the §1 image window, and HIL status (`pending` for a candidate or
397-
`passed` for a public bundle);
400+
the exact `v0.4.1` public beta, or `passed` for a qualified public bundle);
398401
- one `manifest` entry per profile with its relative path, exact byte size, and
399402
lowercase 64-hex SHA-256;
400403
- one `install` entry per profile for the merged image, with relative `path`,
@@ -408,7 +411,8 @@ beside their metadata:
408411

409412
All values are required; placeholders, `unknown`, and abbreviated commits fail
410413
any bundle. `pending` is accepted only on an access-controlled candidate used
411-
for HIL; an HIL status other than `passed` fails a public bundle.
414+
for HIL or the exact digest-bound `v0.4.1` `public-beta` exception in §10; an HIL
415+
status other than `passed` fails every ordinary public bundle.
412416
`release.schema.json`
413417
itself is versioned and immutable beside the metadata. `SHA256SUMS` MUST use the
414418
conventional lowercase-hex, two-space, relative-path format and cover every
@@ -1436,9 +1440,10 @@ requires the complete two-profile HIL matrix again.
14361440

14371441
## 10. Activation and rollback
14381442

1439-
The public action progresses through `candidate` → `verified` → `published` →
1440-
`active`. The public `pyble.dev/flash` action remains disabled while candidate
1441-
HIL runs on the access-controlled production-equivalent HTTPS deployment. It
1443+
The qualified public action progresses through `candidate` → `verified` →
1444+
`published` → `active`. The public `pyble.dev/flash` action remains disabled
1445+
while candidate HIL runs on the access-controlled production-equivalent HTTPS
1446+
deployment. It
14421447
is valid for that protected candidate deployment alone to expose the action
14431448
with `hil_status: pending` after every non-HIL automated/integrity gate is
14441449
green; the candidate-mode selection MUST be build-time explicit, inaccessible
@@ -1480,8 +1485,22 @@ separate reviewed operation requiring an explicit truth-valued disable flag
14801485
and a production smoke test of the disabled state; absence of staging input
14811486
alone is never authorization to disable it.
14821487

1483-
The pre-public `v0.4.1` candidate path was exposed without the required access
1484-
control and is permanently burned. The origin MUST quarantine
1485-
`/firmware/v0.4.1/` with a non-cacheable not-found response, MUST NOT select or
1486-
promote those bytes, and MUST retain any forensic copy outside public routing.
1487-
A qualified public release therefore starts at a new immutable version.
1488+
As a one-time transitional exception, the retained `v0.4.1` bundle MAY be
1489+
published as an explicitly **unqualified public beta**. The selector deployment
1490+
mode MUST be `public-beta`, `accessControlled` MUST be `false`, both profile HIL
1491+
states and the aggregate `hilStatus` MUST remain `pending`, and the
1492+
`release.json` SHA-256 MUST equal
1493+
`8b84fbb65a0463d20369e1d86dac566ca7a2039ebc30f9186f55c05421962445`.
1494+
The exact profile set is `esp32-4mb` plus `esp32-s3-n16r8`; C3 MUST remain
1495+
absent. Before the install control appears, the website MUST say that these
1496+
bytes were manually exercised on the maintainer's two boards but have not
1497+
passed the complete project HIL matrix, and that installation is at the user's
1498+
risk. It MUST NOT call the beta access-controlled, protected, qualified,
1499+
validated, or generally available.
1500+
1501+
The beta path MUST retain all existing schema, checksum, manifest, image,
1502+
same-origin, browser-capability, profile-confirmation, consent, recovery, and
1503+
production-smoke checks. The exception changes only publication policy; it does
1504+
not allow byte mutation, substitute evidence, a different version/digest, or a
1505+
new profile. A later qualified public release therefore starts at a new
1506+
immutable version and still requires the complete gate above.

‎docs/specifications/website.md‎

Lines changed: 67 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,9 @@ firmware remain governed by their own specifications.
1111

1212
The website MUST explain PyBLE accurately, help a beta user get started or ask
1313
for support, publish the app's privacy posture, and provide a gated browser
14-
firmware installer for the qualified initial ESP32-family image profiles.
14+
firmware installer for the exact initial ESP32-family image profiles. The
15+
installer MUST distinguish an explicitly unqualified public beta from a
16+
fully HIL-qualified public release.
1517

1618
It MUST NOT imply that:
1719

@@ -71,12 +73,14 @@ Compatibility copy MUST distinguish platform scope from current support:
7173

7274
- hardware eligibility requires MicroPython, a PBLE/1-capable BLE peripheral
7375
stack, sufficient resources, and a conforming agent port;
74-
- actual support requires a released, validated firmware image for the target;
75-
- the current pre-v1 release list is the exact `esp32-4mb` and
76+
- actual support requires a published firmware image for the exact target and a
77+
truthful release state; an unqualified beta is not a validated release;
78+
- the current public-beta list is the exact `esp32-4mb` and
7679
`esp32-s3-n16r8` profiles; ESP32-C3 remains an initial firmware target but
7780
is planned/unavailable until its exact profile passes real-hardware HIL;
78-
- browser provisioning is offered only for the exact qualified memory profiles
79-
in §7, including N16R8-class hardware for the initial ESP32-S3 image;
81+
- browser provisioning is offered only for the exact memory profiles in §7,
82+
including N16R8-class hardware for the initial ESP32-S3 image, and MUST show
83+
whether those bytes are an unqualified beta or a qualified release;
8084
- users select pins for their exact board and wiring.
8185

8286
It MUST NOT imply that Bluetooth hardware or stock MicroPython alone is enough,
@@ -123,7 +127,8 @@ metadata suitable for the external beta announcement. The image MUST use the
123127
canonical prompt-chip mark and a privacy-reviewed capture of the real app
124128
described in §4. It MAY add authored brand text and framing, but MUST NOT
125129
retouch or generate the pictured app interface. Its claims MUST be limited to
126-
the current iPad external beta and the exact qualified installer profiles.
130+
the current iPad external beta and the exact installer profiles and release
131+
state actually available.
127132

128133
The social image MUST have useful alternative text, remain legible under
129134
common center crops, and make no third-party runtime request. A QR code MUST
@@ -132,17 +137,22 @@ platform cropping can make it unreliable. A separate local square TestFlight
132137
card MAY include the exact invitation QR, visible destination, and plain-text
133138
instructions.
134139

135-
### 3.4 Pre-activation release claims and support intake
136-
137-
Until the first v0.4.2 public firmware selector passes the complete gate in §7,
138-
the repository README and home page MUST say that the browser installer is
139-
unavailable pending v0.4.2 HIL on both exact current profiles. They MUST NOT
140-
describe either profile or its browser image as released, available, or
141-
qualified. The home-page target cards MUST identify the profiles and constraints
142-
as `esp32-4mb` (classic ESP32, 4 MiB external SPI flash, no PSRAM assumed) and
140+
### 3.4 Transitional firmware beta claims and support intake
141+
142+
Until the first firmware selector passes the complete qualified-release gate in
143+
§7, the repository README and home page MUST NOT describe either current profile
144+
or its browser image as qualified. The one-time `v0.4.1` public-beta selector MAY
145+
make the exact `esp32-4mb` and `esp32-s3-n16r8` images available under the
146+
exception in §7, but every active installer state MUST visibly say **unqualified
147+
beta**, **HIL pending**, and **use at your own risk** before profile selection and
148+
again beside the install action. It MUST NOT say or imply that the beta is
149+
access-controlled. The home-page target cards MUST identify the constraints as
150+
`esp32-4mb` (classic ESP32, 4 MiB external SPI flash, no PSRAM assumed) and
143151
`esp32-s3-n16r8` (ESP32-S3, 16 MiB flash, 8 MiB **Octal** PSRAM), and give each
144-
the truthful pending-HIL/unavailable state. `esp32-c3-4mb` remains a separate
145-
planned, unavailable profile.
152+
the truthful public-beta/pending-HIL state while that selector is active.
153+
`esp32-c3-4mb` remains a separate planned, unavailable profile and MUST NOT be
154+
present in the beta selector, release metadata, public firmware tree, or
155+
recovery commands.
146156

147157
README getting-started instructions MUST gate destructive flashing on `/flash`
148158
showing an active version, exact profile, and enabled install action. While the
@@ -151,11 +161,11 @@ supposedly qualified public image. A real-app capture caption MUST describe only
151161
what is visible; it MUST NOT claim that a physical board is pictured when the
152162
capture shows only the app.
153163

154-
While the installer is unavailable, the wide social card MUST describe the
155-
workflow as one-time USB setup followed by everyday use over BLE. It MUST NOT
156-
advertise an enabled web flasher; it MAY explicitly label firmware HIL as
157-
pending. Its mechanically rendered PNG and authored SVG MUST remain paired by
158-
reviewed content and exact-dimension tests.
164+
The wide social card MUST describe the workflow as one-time USB setup followed
165+
by everyday use over BLE. If it advertises the enabled `v0.4.1` web flasher, it
166+
MUST visibly call it an unqualified beta with HIL pending. Its mechanically
167+
rendered PNG and authored SVG MUST remain paired by reviewed content and
168+
exact-dimension tests.
159169

160170
Every changed social-card byte set MUST use a new content-versioned public
161171
pathname before its metadata is deployed. Replacing a PNG or SVG at an existing
@@ -299,9 +309,10 @@ VPS origin. The origin MUST:
299309
firmware 4xx/5xx with `Cache-Control: no-store`, and use the selected
300310
`release.json` SHA-256 as the deterministic cache key for both verification
301311
and ESP Web Tools retrieval;
302-
- quarantine the burned pre-public `/firmware/v0.4.1/` candidate path with a
303-
non-cacheable not-found response, without deleting the retained forensic
304-
copy or allowing it to enter any active selector;
312+
- serve `/firmware/v0.4.1/` only while the exact attested public-beta selector
313+
defined in §7 is active; its successful immutable responses use the ordinary
314+
versioned-firmware cache policy, while every missing/error response remains
315+
`no-store`;
305316
- use a valid origin certificate with Cloudflare **Full (strict)** TLS, never
306317
Flexible mode; and
307318
- expose only the required web and key-authenticated administration ports.
@@ -357,8 +368,32 @@ selector, release metadata, public firmware paths, or recovery commands.
357368
ESP Web Tools' family detection is necessary but not sufficient to establish
358369
memory-profile or silicon-revision compatibility.
359370

360-
The `/flash` action MUST fail closed and remain explicitly unavailable until
361-
all of the following are true for one exact immutable version:
371+
One narrow pre-qualification exception exists for the already manually tested
372+
`v0.4.1` bytes. A build-time selector MAY use deployment mode `public-beta` only
373+
when all of these facts are true:
374+
375+
- `version` is exactly `0.4.1`, `releaseJson.sha256` is exactly
376+
`8b84fbb65a0463d20369e1d86dac566ca7a2039ebc30f9186f55c05421962445`,
377+
`hilStatus` is `pending`, and `accessControlled` is `false`;
378+
- the selector contains exactly `esp32-4mb` and `esp32-s3-n16r8` with the
379+
frozen paths, offsets, memory requirements, and silicon windows; C3 is absent;
380+
- the same-origin `release.json`, schema, manifests, firmware, documents, and
381+
`SHA256SUMS` pass the existing path, shape, size, and SHA-256 integrity checks;
382+
and
383+
- `/flash` visibly labels the firmware an **unqualified beta**, says full HIL is
384+
pending and installation is at the user's risk, and never calls it protected,
385+
access-controlled, qualified, validated, or generally available.
386+
387+
This exception attests only the identity and integrity of the retained bytes;
388+
it does not manufacture HIL evidence. It MUST NOT accept another version or
389+
digest, broaden either profile, enable C3, or satisfy any qualified-release
390+
gate. Removing or replacing the beta requires an explicit deployment action and
391+
production smoke verification. A later website-only deployment MAY carry the
392+
same exact beta selector and byte tree forward through the same integrity gate.
393+
394+
Except for that exact transitional beta, the `/flash` action MUST fail closed
395+
and remain explicitly unavailable until all of the following are true for one
396+
exact immutable version:
362397

363398
1. two clean, provenance-recorded, reproducible builds produced
364399
byte-identical current release-profile artifact sets from the frozen
@@ -385,7 +420,8 @@ all of the following are true for one exact immutable version:
385420
6. the activation deployment passes a non-destructive production-origin
386421
retrieval, redirect, size, SHA-256, CSP, and render smoke test.
387422

388-
Once the gate is green, `/flash` MUST render an active action only after:
423+
For either the exact public beta above or a release whose gate is green,
424+
`/flash` MUST render an active action only after:
389425

390426
- secure-context, `navigator.serial`, and Web Crypto capability detection;
391427
- exact profile selection and the compatibility/backup/erase/cable/power
@@ -444,9 +480,10 @@ The v1 site is releasable when:
444480
sitemap, and web manifest are static client files;
445481
- an unknown pathname returns the generated not-found page with status 404;
446482
- generated output contains no unsupported third-party runtime request;
447-
- the active flasher, when selected, names an exact qualified profile; verifies
448-
the embedded release-metadata root plus every manifest part; requires
449-
compatibility/backup/erase consent; and links the matching recovery guide;
483+
- the active flasher, when selected, names an exact profile and its truthful
484+
beta-or-qualified state; verifies the embedded release-metadata root plus
485+
every manifest part; requires compatibility/backup/erase consent; and links
486+
the matching recovery guide;
450487
- all versioned firmware files are same-origin, immutable, byte-identical to
451488
the reviewed release, and retrievable from the public production origin;
452489
- browser verification and the subsequent ESP Web Tools fetches use the same

0 commit comments

Comments
 (0)