Skip to content

Commit 454a270

Browse files
committed
[green] Activate exact audited v0.4.2 beta
Signed-off-by: Viwat Vchirawongkwin <viwat.v@chula.ac.th>
1 parent 9924f71 commit 454a270

27 files changed

Lines changed: 541 additions & 220 deletions

‎README.md‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -62,14 +62,15 @@ BLE GATT peripheral. It supports:
6262
- board naming and identify support; and
6363
- upstream MicroPython’s standard `neopixel` module.
6464

65-
The public browser installer is currently unavailable pending v0.4.2 HIL on
66-
both exact current profiles:
65+
The public browser installer currently offers the exact v0.4.2 unqualified beta
66+
for both current profiles. The exact bytes pass the audited-candidate release
67+
gate, but full project HIL is pending:
6768

6869
| Installer profile | Exact target constraint | Public status |
6970
| ----------------- | ------------------------------------------------------------ | --------------------------------------------------- |
70-
| `esp32-4mb` | Classic ESP32, 4 MiB external SPI flash; no PSRAM assumed | v0.4.2 HIL pending; installer unavailable |
71-
| `esp32-s3-n16r8` | ESP32-S3, 16 MiB flash / 8 MiB Octal PSRAM; N16R8-class only | v0.4.2 HIL pending; installer unavailable |
72-
| `esp32-c3-4mb` | ESP32-C3, 4 MiB external SPI flash; no PSRAM assumed | Planned; no public image; exact-profile HIL pending |
71+
| `esp32-4mb` | Classic ESP32, 4 MiB external SPI flash; no PSRAM assumed | Unqualified v0.4.2 beta; HIL pending |
72+
| `esp32-s3-n16r8` | ESP32-S3, 16 MiB flash / 8 MiB Octal PSRAM; N16R8-class only | Unqualified v0.4.2 beta; HIL pending |
73+
| `esp32-c3-4mb` | ESP32-C3, 4 MiB external SPI flash; no PSRAM assumed | Planned; unavailable; no public image |
7374

7475
These are the initial port targets, not a chip-family allowlist. A future board
7576
is compatible when it has a maintained PyBLE agent port, BLE GATT
@@ -106,12 +107,13 @@ shared conformance corpus, documentation, and CI atomically.
106107
1. Install the iPad beta from
107108
[TestFlight](https://testflight.apple.com/join/yU4e8s6d), or build the
108109
Flutter app locally.
109-
2. Check [pyble.dev/flash](https://pyble.dev/flash) in desktop Chrome or Edge.
110-
The public installer is currently unavailable pending v0.4.2 HIL. Wait for
111-
that page to show an active release version, your exact profile, and an
112-
enabled install action.
113-
3. Only after that gate opens, back up the board, confirm its exact memory
114-
profile, and use the one-time wired installer. Flashing erases the board.
110+
2. Open [pyble.dev/flash](https://pyble.dev/flash) in desktop Chrome or Edge.
111+
The exact v0.4.2 unqualified beta is active while full HIL is pending; please
112+
use it at your own risk. Confirm the active version, your exact profile, and
113+
the enabled install action.
114+
3. Before flashing, back up the board, confirm its exact memory profile, and
115+
accept every safety acknowledgement before using the one-time wired
116+
installer. Flashing erases the board.
115117
4. Open PyBLE, scan for the provisioned board, connect, and run an example over
116118
BLE.
117119

‎docs/ROADMAP.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,14 @@ promising dates; accepted work is tracked through GitHub issues and milestones.
88
- iPad external beta through TestFlight
99
- PBLE/1 editing, run/stop, console, and file workflows over BLE
1010
- Offline Blockly with beginner GPIO and NeoPixel examples
11-
- Browser installation for qualified `esp32-4mb` and `esp32-s3-n16r8`
12-
profiles
11+
- Browser installation for the exact `esp32-4mb` and `esp32-s3-n16r8` profiles
12+
as the v0.4.2 unqualified beta; HIL pending
1313
- MIT-licensed app, agent firmware, protocol, website, tests, and release tools
1414

1515
## Near term
1616

17-
- Re-establish firmware release provenance from the canonical public history
17+
- Complete full HIL qualification for the exact `esp32-4mb` and
18+
`esp32-s3-n16r8` v0.4.2 bytes
1819
- Complete real-hardware qualification before enabling the ESP32-C3 installer
1920
- Expand user-facing setup, recovery, and board-specific wiring guidance
2021
- Open and document the Android beta distribution path

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

Lines changed: 37 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,9 @@ BLE and PBLE/1.
3939
## 1. Release image profiles
4040

4141
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.
42+
**provisioning image profiles**. The exact audited `v0.4.2` bytes may be offered
43+
only as the unqualified public beta defined in §10; they are not qualified
44+
profiles.
4445
A later qualified public bundle uses the same exact profile definitions:
4546

4647
| 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 |
@@ -397,7 +398,7 @@ beside their metadata:
397398
flash/PSRAM requirements, flash mode/frequency, required
398399
`silicon_revision.minimum_full` and `silicon_revision.maximum_full` integers
399400
matching the §1 image window, and HIL status (`pending` for a candidate or
400-
the exact `v0.4.1` public beta, or `passed` for a qualified public bundle);
401+
the exact `v0.4.2` public beta, or `passed` for a qualified public bundle);
401402
- one `manifest` entry per profile with its relative path, exact byte size, and
402403
lowercase 64-hex SHA-256;
403404
- one `install` entry per profile for the merged image, with relative `path`,
@@ -411,7 +412,8 @@ beside their metadata:
411412

412413
All values are required; placeholders, `unknown`, and abbreviated commits fail
413414
any bundle. `pending` is accepted only on an access-controlled candidate used
414-
for HIL or the exact digest-bound `v0.4.1` `public-beta` exception in §10; an HIL
415+
for HIL or the exact audited and digest-bound `v0.4.2` `public-beta` exception
416+
in §10; an HIL
415417
status other than `passed` fails every ordinary public bundle.
416418
`release.schema.json`
417419
itself is versioned and immutable beside the metadata. `SHA256SUMS` MUST use the
@@ -1469,38 +1471,50 @@ manifest. Rollback changes the website's selected-release descriptor to a
14691471
previous fully qualified immutable bundle and redeploys the site. It never
14701472
mutates or partially replaces the active version directory.
14711473

1472-
Once a fully qualified public release is active, later website-only
1473-
deployments MUST carry its exact selector and immutable firmware tree forward
1474+
Once a public release is active, later website-only deployments MUST carry its
1475+
exact selector and immutable firmware tree forward
14741476
through authenticated retrieval and the canonical staged-release validation
14751477
path. Each website release with an active installer retains an unserved
14761478
canonical selector marker for this purpose. The preserved-public validator
14771479
MUST repeat every self-contained public bundle, schema, HIL, profile, artifact,
14781480
path, size, digest, descriptor, and annotated-tag check. It MUST prove exact
14791481
selected-byte continuity and MUST NOT accept a different version or byte. It
1480-
does not repeat the source/build license audit whose passing evidence was
1481-
required for the original activation of those same immutable bytes. A
1482+
does not repeat the source/build license audit for a fully qualified release
1483+
whose passing evidence was required for the original activation of those same
1484+
immutable bytes. A preserved `v0.4.2` public beta MUST instead repeat canonical
1485+
`--audited-candidate` validation with the retained license-evidence directory
1486+
and exact release-build root, using the exact firmware-source checkout recorded
1487+
by the release as `--repo-root`, and MUST revalidate the annotated
1488+
`firmware-v0.4.2` tag. A
14821489
deployment MUST fail before the build if that state cannot be retrieved or
14831490
validated. Transitioning an active public installer to unavailable is a
14841491
separate reviewed operation requiring an explicit truth-valued disable flag
14851492
and a production smoke test of the disabled state; absence of staging input
14861493
alone is never authorization to disable it.
14871494

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
1495+
As a one-time transitional exception, the fresh audited `v0.4.2` candidate MAY
1496+
be published as an explicitly **unqualified public beta**. The selector deployment
14901497
mode MUST be `public-beta`, `accessControlled` MUST be `false`, both profile HIL
14911498
states and the aggregate `hilStatus` MUST remain `pending`, and the
14921499
`release.json` SHA-256 MUST equal
1493-
`8b84fbb65a0463d20369e1d86dac566ca7a2039ebc30f9186f55c05421962445`.
1500+
`5d1b0db8c4b90cccf054cd244530afb3b9112d489aa02f7c5da650e92161acde`.
14941501
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.
1502+
absent. Before staging or carrying the beta forward, the canonical release tool
1503+
MUST accept the exact bundle with `validate --audited-candidate`, its retained
1504+
license-evidence directory, its exact release-build root, and the exact
1505+
firmware-source checkout recorded by the release as `--repo-root`. The annotated
1506+
`firmware-v0.4.2` tag MUST exist and peel directly to the full PyBLE provenance
1507+
commit recorded in `release.json`, and deployment MUST bind the tag object
1508+
before and after the website build and before upload. Before the install control
1509+
appears, the website MUST say that the exact bytes passed the audited-candidate
1510+
release gate but have not passed the complete project HIL matrix, and that
1511+
installation is at the user's risk. It MUST NOT call the beta access-controlled,
1512+
protected, qualified, fully validated, or generally available.
1513+
1514+
The beta path MUST retain all existing audited-candidate, license, tag, schema,
1515+
checksum, manifest, image, same-origin, browser-capability,
1516+
profile-confirmation, consent, recovery, and production-smoke checks. The
1517+
exception changes only publication policy; it does not allow byte mutation,
1518+
substitute evidence, a different version/digest, or a new profile. A later
1519+
qualified public release therefore starts at a new immutable version and still
1520+
requires the complete gate above.

‎docs/specifications/website.md‎

Lines changed: 47 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -141,12 +141,13 @@ instructions.
141141

142142
Until the first firmware selector passes the complete qualified-release gate in
143143
§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
144+
or its browser image as qualified. The exact audited `v0.4.2` public-beta
145+
selector MAY make the `esp32-4mb` and `esp32-s3-n16r8` images available under
146+
the exception in §7, but every active installer state MUST visibly say
147+
**unqualified beta**, **HIL pending**, and **use at your own risk** before
148+
profile selection and again beside the install action. It MUST NOT say or imply
149+
that the beta is access-controlled. The home-page target cards MUST identify
150+
the constraints as
150151
`esp32-4mb` (classic ESP32, 4 MiB external SPI flash, no PSRAM assumed) and
151152
`esp32-s3-n16r8` (ESP32-S3, 16 MiB flash, 8 MiB **Octal** PSRAM), and give each
152153
the truthful public-beta/pending-HIL state while that selector is active.
@@ -156,14 +157,18 @@ recovery commands.
156157

157158
The repository README, home-page hero, provisioning workflow, exact-profile
158159
cards, TestFlight callout, support getting-started guide, and public roadmap
159-
MUST agree with that current state. Each current-profile status MUST name
160-
`v0.4.1`, **unqualified beta**, and **HIL pending**; installation instructions
161-
MUST direct users to the enabled `/flash` action while preserving the exact
162-
profile, backup, erase, cable/power, and port acknowledgements. The home and
163-
support surfaces MUST include **use at your own risk**. The roadmap MAY shorten
164-
the warning, but MUST put complete HIL qualification for the same two exact
165-
profiles in near-term work rather than claim they are qualified now. Every one
166-
of those surfaces MUST keep C3 explicitly unavailable.
160+
MUST agree with the build-selected installer state. While the exact beta
161+
selector is active, each current-profile status MUST name `v0.4.2`,
162+
**unqualified beta**, and **HIL pending**; installation instructions MUST direct
163+
users to the enabled `/flash` action while preserving the exact profile, backup,
164+
erase, cable/power, and port acknowledgements. The home and support surfaces
165+
MUST include **use at your own risk**. When no selector is active, including an
166+
explicit installer-disable deployment, the generated home and support pages
167+
MUST instead say that the installer is unavailable and MUST NOT claim that the
168+
beta is available. The roadmap MAY shorten the warning, but MUST put complete
169+
HIL qualification for the same two exact profiles in near-term work rather than
170+
claim they are qualified now. Every one of those surfaces MUST keep C3
171+
explicitly unavailable.
167172

168173
README getting-started instructions MUST gate destructive flashing on `/flash`
169174
showing an active version, exact profile, and enabled install action. While the
@@ -173,7 +178,7 @@ what is visible; it MUST NOT claim that a physical board is pictured when the
173178
capture shows only the app.
174179

175180
The wide social card MUST describe the workflow as one-time USB setup followed
176-
by everyday use over BLE. If it advertises the enabled `v0.4.1` web flasher, it
181+
by everyday use over BLE. If it advertises the enabled `v0.4.2` web flasher, it
177182
MUST visibly call it an unqualified beta with HIL pending. Its mechanically
178183
rendered PNG and authored SVG MUST remain paired by reviewed content and
179184
exact-dimension tests.
@@ -320,23 +325,30 @@ VPS origin. The origin MUST:
320325
firmware 4xx/5xx with `Cache-Control: no-store`, and use the selected
321326
`release.json` SHA-256 as the deterministic cache key for both verification
322327
and ESP Web Tools retrieval;
323-
- serve `/firmware/v0.4.1/` only while the exact attested public-beta selector
328+
- serve `/firmware/v0.4.2/` only while the exact audited public-beta selector
324329
defined in §7 is active; its successful immutable responses use the ordinary
325330
versioned-firmware cache policy, while every missing/error response remains
326331
`no-store`;
327332
- use a valid origin certificate with Cloudflare **Full (strict)** TLS, never
328333
Flexible mode; and
329334
- expose only the required web and key-authenticated administration ports.
330335

331-
After the first qualified public installer is activated, an ordinary
332-
website-only deployment MUST preserve that exact immutable selected release.
336+
After a public installer is activated, an ordinary website-only deployment MUST
337+
preserve that exact immutable selected release.
333338
The deployment obtains the selector and firmware tree from the current managed
334339
release over the authenticated deployment transport, validates them through
335340
the preserved-public staged-release and checksum gates, and embeds the selector
336341
at build time. That carry-forward gate repeats the self-contained bundle,
337-
schema, HIL, profile, artifact, path, size, digest, descriptor, and annotated-tag
338-
checks. It does not repeat the source/build license audit because the exact
339-
immutable bytes already passed that audit during their original activation.
342+
schema, HIL, profile, artifact, path, size, digest, descriptor, and
343+
annotated-tag checks. A preserved qualified release does not repeat the
344+
source/build license audit because the exact immutable bytes already passed that
345+
audit during its original activation. The exact `v0.4.2` public beta is a fresh
346+
pending candidate and MUST instead repeat canonical `--audited-candidate`
347+
validation with its retained license-evidence directory and exact build root on
348+
every deployment that carries it forward. That validation MUST receive the
349+
exact firmware-source checkout recorded by the release, rather than substituting
350+
the later website checkout. A preserved qualified release MUST NOT require
351+
those retained beta source/build/evidence inputs.
340352
It MUST NOT infer availability from the mere presence of a firmware directory
341353
or accept a caller-supplied selector.
342354

@@ -379,28 +391,34 @@ selector, release metadata, public firmware paths, or recovery commands.
379391
ESP Web Tools' family detection is necessary but not sufficient to establish
380392
memory-profile or silicon-revision compatibility.
381393

382-
One narrow pre-qualification exception exists for the already manually tested
383-
`v0.4.1` bytes. A build-time selector MAY use deployment mode `public-beta` only
394+
One narrow pre-qualification exception exists for the fresh audited `v0.4.2`
395+
candidate. A build-time selector MAY use deployment mode `public-beta` only
384396
when all of these facts are true:
385397

386-
- `version` is exactly `0.4.1`, `releaseJson.sha256` is exactly
387-
`8b84fbb65a0463d20369e1d86dac566ca7a2039ebc30f9186f55c05421962445`,
398+
- `version` is exactly `0.4.2`, `releaseJson.sha256` is exactly
399+
`5d1b0db8c4b90cccf054cd244530afb3b9112d489aa02f7c5da650e92161acde`,
388400
`hilStatus` is `pending`, and `accessControlled` is `false`;
389401
- the selector contains exactly `esp32-4mb` and `esp32-s3-n16r8` with the
390402
frozen paths, offsets, memory requirements, and silicon windows; C3 is absent;
391403
- the same-origin `release.json`, schema, manifests, firmware, documents, and
392404
`SHA256SUMS` pass the existing path, shape, size, and SHA-256 integrity checks;
393-
and
405+
- the canonical release tool accepts the exact bundle with
406+
`validate --audited-candidate`, the retained license-evidence directory, and
407+
the exact release-build root, using the exact firmware-source checkout
408+
recorded by the release as `--repo-root`; the annotated `firmware-v0.4.2` tag
409+
exists and peels directly to `release.json` provenance; and
394410
- `/flash` visibly labels the firmware an **unqualified beta**, says full HIL is
395411
pending and installation is at the user's risk, and never calls it protected,
396412
access-controlled, qualified, validated, or generally available.
397413

398-
This exception attests only the identity and integrity of the retained bytes;
399-
it does not manufacture HIL evidence. It MUST NOT accept another version or
414+
This exception attests the identity, integrity, provenance, and audited-candidate
415+
license state of the exact bytes; it does not manufacture HIL evidence. It MUST
416+
NOT accept another version or
400417
digest, broaden either profile, enable C3, or satisfy any qualified-release
401418
gate. Removing or replacing the beta requires an explicit deployment action and
402419
production smoke verification. A later website-only deployment MAY carry the
403-
same exact beta selector and byte tree forward through the same integrity gate.
420+
same exact beta selector and byte tree forward only by repeating the same
421+
audited-candidate, license-evidence, annotated-tag, and integrity gates.
404422

405423
Except for that exact transitional beta, the `/flash` action MUST fail closed
406424
and remain explicitly unavailable until all of the following are true for one

0 commit comments

Comments
 (0)