Skip to content

Commit 17c7266

Browse files
committed
[docs] Record v0.4.2 production browser HIL
Signed-off-by: Viwat Vchirawongkwin <viwat.v@chula.ac.th>
1 parent fa4b207 commit 17c7266

4 files changed

Lines changed: 161 additions & 65 deletions

File tree

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

Lines changed: 46 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -40,21 +40,21 @@ BLE and PBLE/1.
4040

4141
The current pre-v1 browser bundle contains exactly these two
4242
**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.
43+
only as the hardware-tested public beta defined in §10; that narrow validation
44+
does not make them qualified-release profiles.
4545
A later qualified public bundle uses the same exact profile definitions:
4646

47-
| 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 |
48-
|---|---|---|---|---|---|
49-
| `esp32-4mb` | `ESP32` | Classic ESP32 with 4 MiB external SPI flash; no PSRAM assumption | `0`…`399` | DIO, 40 MHz, 4 MiB | merged `firmware.bin` at `0x1000`; bootloader `0x1000`; partition table `0x8000`; application `0x10000` |
50-
| `esp32-s3-n16r8` | `ESP32-S3` | ESP32-S3 with 16 MiB flash and 8 MiB **Octal** PSRAM (N16R8-class) | `0`…`99` | DIO, 80 MHz, 16 MiB | merged `firmware.bin` at `0x0000`; bootloader `0x0000`; partition table `0x8000`; application `0x10000` |
47+
| 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 |
48+
| ---------------- | -------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------------------- |
49+
| `esp32-4mb` | `ESP32` | Classic ESP32 with 4 MiB external SPI flash; no PSRAM assumption | `0`…`399` | DIO, 40 MHz, 4 MiB | merged `firmware.bin` at `0x1000`; bootloader `0x1000`; partition table `0x8000`; application `0x10000` |
50+
| `esp32-s3-n16r8` | `ESP32-S3` | ESP32-S3 with 16 MiB flash and 8 MiB **Octal** PSRAM (N16R8-class) | `0`…`99` | DIO, 80 MHz, 16 MiB | merged `firmware.bin` at `0x0000`; bootloader `0x0000`; partition table `0x8000`; application `0x10000` |
5151

5252
`esp32-c3-4mb` remains a known provisioning profile and an initial v1
5353
firmware target, with this frozen future qualification:
5454

55-
| Deferred 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 |
56-
|---|---|---|---|---|---|
57-
| `esp32-c3-4mb` | `ESP32-C3` | ESP32-C3 revision v0.3 or newer with 4 MiB external flash; no PSRAM assumption | `3`…`199` | DIO, 80 MHz, 4 MiB | merged `firmware.bin` at `0x0000`; bootloader `0x0000`; partition table `0x8000`; application `0x10000` |
55+
| Deferred 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 |
56+
| ------------------- | -------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------- |
57+
| `esp32-c3-4mb` | `ESP32-C3` | ESP32-C3 revision v0.3 or newer with 4 MiB external flash; no PSRAM assumption | `3`…`199` | DIO, 80 MHz, 4 MiB | merged `firmware.bin` at `0x0000`; bootloader `0x0000`; partition table `0x8000`; application `0x10000` |
5858

5959
That deferred profile is **not** part of the current public release: it MUST
6060
NOT have an entry in `release.json`, a public manifest or binary directory, or
@@ -246,6 +246,7 @@ block same-origin publication.
246246
## 3. Same-origin, versioned layout
247247

248248
The canonical public files are static and use this exact layout:
249+
249250
```text
250251
https://pyble.dev/firmware/v<version>/
251252
release.json
@@ -330,9 +331,7 @@ one build for its owning profile. For example,
330331
"builds": [
331332
{
332333
"chipFamily": "ESP32-S3",
333-
"parts": [
334-
{ "path": "firmware.bin", "offset": 0 }
335-
]
334+
"parts": [{ "path": "firmware.bin", "offset": 0 }]
336335
}
337336
]
338337
}
@@ -567,6 +566,7 @@ The following resolution rules are part of that fail-closed mapping:
567566
A missing file, unexpected basename, alternate or sibling retained tree,
568567
escaped path, near-match root, nonzero generated ELF anchor, or symlinked
569568
input is fatal.
569+
570570
5. A generated component archive has only a stable topology matcher in
571571
committed policy. An ordinary matcher contains exactly its ESP-IDF
572572
component name. A nested CMake archive produced below a `CONFIG_ONLY`
@@ -683,6 +683,7 @@ The following resolution rules are part of that fail-closed mapping:
683683
observations. Rechecking only archive/tree digests is insufficient:
684684
project/compile/map/link documents, metadata inputs, archive sources, direct
685685
outputs, and direct sources are all race-sensitive release inputs.
686+
686687
6. An archive outside the repository and build roots is admitted only below
687688
one versioned toolchain root proven by the exact compile-command
688689
executables and the locked ESP-IDF `tools/tools.json` entry. The policy
@@ -732,6 +733,7 @@ The following resolution rules are part of that fail-closed mapping:
732733
only logical metadata, semantic hashes, constrained relative frontend/member
733734
paths, and distribution identity; they MUST NOT contain a host-absolute
734735
tools-home, cache, frontend, installed-root, or runtime path.
736+
735737
7. Each raw package is matched exactly once by profile/role and its complete
736738
raw property set, including name, version state, download-location state,
737739
copyright state, declared/concluded license states, checksums, annotations,
@@ -773,6 +775,7 @@ The following resolution rules are part of that fail-closed mapping:
773775
share the same SPDX ID in different profiles; a union expression MUST NOT
774776
be invented to make unlike occurrences share one review. Any unexpected
775777
property, value, package, relationship, resolution, or ambiguity is fatal.
778+
776779
8. A raw package that the pinned tool reports but that contributes no linked
777780
archive, compiled source, or aggregate project identity may be excluded
778781
from the redistribution notice only through an explicit `not-shipped`
@@ -815,6 +818,7 @@ The following resolution rules are part of that fail-closed mapping:
815818
independent ledger says `allow-aggregate`. The receipt binds both the
816819
`shipment_review` policy record and the normalized occurrence
817820
classifications.
821+
818822
9. A redistributed dependency absent from the raw ESP-IDF package graph is a
819823
deterministic supplemental SPDX package, not misrepresented as raw tool
820824
output. In this release the exact frozen NeoPixel tree and the three linked
@@ -900,15 +904,16 @@ The following resolution rules are part of that fail-closed mapping:
900904
host-absolute path is retained. A source, metadata version, optimization
901905
level, module order, qstr header, `.mpy`, generator, compiler, architecture,
902906
copied-board byte, or frozen C mismatch is fatal.
903-
9. Coverage is exact without asserting false package/archive cardinality.
904-
Every observed raw package, linked archive, compiled source, frozen
905-
destination, frozen source tree,
906-
prebuilt blob, and compiler/runtime input is consumed by exactly one
907-
resolution record; each record declares its complete many-to-many
908-
package/input attribution, and aggregate packages may own no archive
909-
directly only through rule 7. Every expected relationship is present, every
910-
declared stable matcher is observed exactly where applicable, and no
911-
unexpected record is accepted.
907+
908+
10. Coverage is exact without asserting false package/archive cardinality.
909+
Every observed raw package, linked archive, compiled source, frozen
910+
destination, frozen source tree,
911+
prebuilt blob, and compiler/runtime input is consumed by exactly one
912+
resolution record; each record declares its complete many-to-many
913+
package/input attribution, and aggregate packages may own no archive
914+
directly only through rule 7. Every expected relationship is present, every
915+
declared stable matcher is observed exactly where applicable, and no
916+
unexpected record is accepted.
912917

913918
The initial runtime/input review explicitly includes `libgcc.a` and
914919
`libstdc++.a` under `GPL-3.0-or-later WITH GCC-exception-3.1`;
@@ -1114,16 +1119,16 @@ Candidate generation MUST read
11141119
both its parsed JSON object and the lowercase SHA-256 of its exact source
11151120
bytes. The policy object has exactly these keys:
11161121

1117-
| Key | Exact value/type |
1118-
|---|---|
1119-
| `schema_version` | integer `1` |
1120-
| `qualification_scope` | string `"pre-v1"` |
1121-
| `profile_order` | exact string array `["esp32-4mb", "esp32-s3-n16r8"]` |
1122-
| `deferred_profiles` | exact string array `["esp32-c3-4mb"]` |
1123-
| `workload` | exact object defined below |
1124-
| `derivation` | exact object defined below |
1125-
| `baseline_evidence` | exact object `{path, sha256}` |
1126-
| `profiles` | two policy-entry objects, in `profile_order` |
1122+
| Key | Exact value/type |
1123+
| --------------------- | ---------------------------------------------------- |
1124+
| `schema_version` | integer `1` |
1125+
| `qualification_scope` | string `"pre-v1"` |
1126+
| `profile_order` | exact string array `["esp32-4mb", "esp32-s3-n16r8"]` |
1127+
| `deferred_profiles` | exact string array `["esp32-c3-4mb"]` |
1128+
| `workload` | exact object defined below |
1129+
| `derivation` | exact object defined below |
1130+
| `baseline_evidence` | exact object `{path, sha256}` |
1131+
| `profiles` | two policy-entry objects, in `profile_order` |
11271132

11281133
`workload` has exactly these integer/string keys and values:
11291134

@@ -1493,7 +1498,7 @@ and a production smoke test of the disabled state; absence of staging input
14931498
alone is never authorization to disable it.
14941499

14951500
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
1501+
be published as a **hardware-tested public beta**. The selector deployment
14971502
mode MUST be `public-beta`, `accessControlled` MUST be `false`, both profile HIL
14981503
states and the aggregate `hilStatus` MUST remain `pending`, and the
14991504
`release.json` SHA-256 MUST equal
@@ -1505,11 +1510,15 @@ license-evidence directory, its exact release-build root, and the exact
15051510
firmware-source checkout recorded by the release as `--repo-root`. The annotated
15061511
`firmware-v0.4.2` tag MUST exist and peel directly to the full PyBLE provenance
15071512
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+
before and after the website build and before upload. The exact production
1514+
browser-flashing validation recorded in
1515+
`docs/validation/browser-flashing/v0.4.2-production.json` supports the narrower
1516+
claim that real-board Chrome installation, interruption, recovery, and reset
1517+
passed for both enabled exact profiles. Before the install control appears, the
1518+
website MUST state that completed scope and MUST separately say that complete
1519+
release qualification remains pending. It MUST NOT call the beta
1520+
access-controlled, protected, a qualified release, fully validated,
1521+
production-ready, or generally available.
15131522

15141523
The beta path MUST retain all existing audited-candidate, license, tag, schema,
15151524
checksum, manifest, image, same-origin, browser-capability,

‎docs/specifications/website.md‎

Lines changed: 38 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ firmware remain governed by their own specifications.
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
1414
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.
15+
installer MUST distinguish a hardware-tested public beta from a fully
16+
qualified public release.
1717

1818
It MUST NOT imply that:
1919

@@ -74,13 +74,14 @@ Compatibility copy MUST distinguish platform scope from current support:
7474
- hardware eligibility requires MicroPython, a PBLE/1-capable BLE peripheral
7575
stack, sufficient resources, and a conforming agent port;
7676
- 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;
77+
truthful release state; browser-installation validation for a beta is
78+
narrower than complete release qualification;
7879
- the current public-beta list is the exact `esp32-4mb` and
7980
`esp32-s3-n16r8` profiles; ESP32-C3 remains an initial firmware target but
8081
is planned/unavailable until its exact profile passes real-hardware HIL;
8182
- browser provisioning is offered only for the exact memory profiles in §7,
8283
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;
84+
whether those bytes are a hardware-tested beta or a qualified release;
8485
- users select pins for their exact board and wiring.
8586

8687
It MUST NOT imply that Bluetooth hardware or stock MicroPython alone is enough,
@@ -141,16 +142,22 @@ instructions.
141142

142143
Until the first firmware selector passes the complete qualified-release gate in
143144
§7, the repository README and home page MUST NOT describe either current profile
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
145+
or its browser image as a qualified release. The exact audited `v0.4.2`
146+
public-beta selector MAY make the `esp32-4mb` and `esp32-s3-n16r8` images
147+
available under the exception in §7. Following the production browser-flashing
148+
validation recorded in
149+
`docs/validation/browser-flashing/v0.4.2-production.json`, every active
150+
installer state MUST instead identify these exact bytes as a
151+
**hardware-tested firmware beta** and say that real-board browser installation
152+
and interrupted-flash recovery passed for both enabled exact profiles. It MUST
153+
also distinguish that narrow result from complete release qualification and
154+
MUST NOT say or imply that the beta is access-controlled, a qualified release,
155+
fully validated, production-ready, or generally available. The home-page target
156+
cards MUST identify the constraints as
151157
`esp32-4mb` (classic ESP32, 4 MiB external SPI flash, no PSRAM assumed) and
152158
`esp32-s3-n16r8` (ESP32-S3, 16 MiB flash, 8 MiB **Octal** PSRAM), and give each
153-
the truthful public-beta/pending-HIL state while that selector is active.
159+
the truthful hardware-tested-beta/release-qualification-pending state while
160+
that selector is active.
154161
`esp32-c3-4mb` remains a separate planned, unavailable profile and MUST NOT be
155162
present in the beta selector, release metadata, public firmware tree, or
156163
recovery commands.
@@ -159,16 +166,17 @@ The repository README, home-page hero, provisioning workflow, exact-profile
159166
cards, TestFlight callout, support getting-started guide, and public roadmap
160167
MUST agree with the build-selected installer state. While the exact beta
161168
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.
169+
**hardware-tested beta**, and **release qualification pending**; installation
170+
instructions MUST direct users to the enabled `/flash` action while preserving
171+
the exact profile, backup, erase, cable/power, and port acknowledgements. They
172+
MUST name the completed browser installation and interrupted-flash recovery
173+
scope rather than the stale blanket phrase **full HIL pending**. When no selector
174+
is active, including an explicit installer-disable deployment, the generated
175+
home and support pages MUST instead say that the installer is unavailable and
176+
MUST NOT claim that the beta is available. The roadmap MUST mark two-profile
177+
browser-flashing validation complete while retaining the broader app, PBLE/1,
178+
resource, and release-qualification work. Every one of those surfaces MUST keep
179+
C3 explicitly unavailable.
172180

173181
README getting-started instructions MUST gate destructive flashing on `/flash`
174182
showing an active version, exact profile, and enabled install action. While the
@@ -179,9 +187,9 @@ capture shows only the app.
179187

180188
The wide social card MUST describe the workflow as one-time USB setup followed
181189
by everyday use over BLE. If it advertises the enabled `v0.4.2` web flasher, it
182-
MUST visibly call it an unqualified beta with HIL pending. Its mechanically
183-
rendered PNG and authored SVG MUST remain paired by reviewed content and
184-
exact-dimension tests.
190+
MUST use the narrow claim **web flashing validated** and MUST NOT imply complete
191+
release qualification. Its mechanically rendered PNG and authored SVG MUST
192+
remain paired by reviewed content and exact-dimension tests.
185193

186194
Every changed social-card byte set MUST use a new content-versioned public
187195
pathname before its metadata is deployed. Replacing a PNG or SVG at an existing
@@ -407,9 +415,11 @@ when all of these facts are true:
407415
the exact release-build root, using the exact firmware-source checkout
408416
recorded by the release as `--repo-root`; the annotated `firmware-v0.4.2` tag
409417
exists and peels directly to `release.json` provenance; and
410-
- `/flash` visibly labels the firmware an **unqualified beta**, says full HIL is
411-
pending and installation is at the user's risk, and never calls it protected,
412-
access-controlled, qualified, validated, or generally available.
418+
- `/flash` visibly labels the firmware a **hardware-tested firmware beta**,
419+
names the completed real-board browser installation and interrupted-flash
420+
recovery scope for both enabled profiles, says complete release qualification
421+
remains pending, and never calls it protected, access-controlled, a qualified
422+
release, fully validated, production-ready, or generally available.
413423

414424
This exception attests the identity, integrity, provenance, and audited-candidate
415425
license state of the exact bytes; it does not manufacture HIL evidence. It MUST

0 commit comments

Comments
 (0)