Skip to content

Commit 509e7a4

Browse files
ZeroBitsTechZeroBitsTech
committed
add repo automation and beta docs
1 parent 31cd0ba commit 509e7a4

11 files changed

Lines changed: 180 additions & 0 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: ci
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
9+
jobs:
10+
desktop:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- name: Checkout
15+
uses: actions/checkout@v4
16+
17+
- name: Run desktop tests
18+
run: bash scripts/run_desktop_tests.sh
19+
20+
- name: Run lean smoke
21+
run: bash scripts/run_desktop_lean_smoke.sh
22+
23+
- name: Run benchmark gate
24+
run: bash scripts/run_desktop_benchmark.sh --enforce-performance
25+
26+
- name: Build desktop simulation
27+
run: bash scripts/build_desktop_sim.sh

‎.github/workflows/release.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: release
2+
3+
on:
4+
push:
5+
tags:
6+
- "v*"
7+
8+
jobs:
9+
release:
10+
runs-on: ubuntu-latest
11+
12+
permissions:
13+
contents: write
14+
15+
steps:
16+
- name: Checkout
17+
uses: actions/checkout@v4
18+
19+
- name: Run desktop tests
20+
run: bash scripts/run_desktop_tests.sh
21+
22+
- name: Run benchmark gate
23+
run: bash scripts/run_desktop_benchmark.sh --enforce-performance
24+
25+
- name: Package source
26+
run: |
27+
mkdir -p dist
28+
git archive --format=tar.gz --output=dist/zerokernel-${GITHUB_REF_NAME}.tar.gz HEAD
29+
30+
- name: Publish GitHub release
31+
uses: softprops/action-gh-release@v2
32+
with:
33+
files: |
34+
dist/zerokernel-${{ github.ref_name }}.tar.gz
35+
zerokernel.manifest.json
36+
CHANGELOG.md

‎CHANGELOG.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Changelog
2+
3+
## Unreleased
4+
5+
- Added GitHub Actions CI and tag-driven release workflow.
6+
- Added wiki-ready documentation pages under `docs/wiki/`.
7+
- Added `RealProjectNode` as a more realistic network workload example.
8+
- Added fairer ESP32 module compare tooling and improved serial capture.
9+
- Reduced optional network module footprint via lean transport metrics and smaller default queues.
10+
- Improved `ZeroHttpPump` and `ZeroMqttPump` throughput by allowing bounded intra-tick progress.
11+
12+
## 1.3.x
13+
14+
- Added capability-aware runtime supervision.
15+
- Added optional network modules (`ZeroWiFiMaintainer`, `ZeroHttpPump`, `ZeroMqttPump`, `ZeroTransportMetrics`).
16+
- Added cross-target examples and hardware validation on ESP8266 and ESP32.

‎README.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,21 @@ The intended position is simple:
3131
- Runtime identity, ABI version, manifest, timing reports, diagnostics hooks, and task-scoped capability gating
3232
- Low-level internal helpers for cycle counting and idle hints, including C and assembly where it actually helps
3333

34+
## Repo Health
35+
36+
The repository now ships with project-level release and validation scaffolding:
37+
38+
- GitHub Actions CI on every push to `main` and on pull requests
39+
- Tag-driven release packaging on `v*` tags
40+
- A local `CHANGELOG.md` for release notes and regression history
41+
- Wiki-ready documentation pages under `docs/wiki/`
42+
43+
Start points:
44+
45+
- `docs/wiki/Home.md`
46+
- `docs/wiki/Validation.md`
47+
- `docs/wiki/Beta-Modules.md`
48+
3449
## Current Runtime Snapshot
3550

3651
Latest measured references:
@@ -81,6 +96,17 @@ Tradeoff summary:
8196

8297
The ESP32 tradeoff is also healthy: the footprint increase is small relative to total headroom, while the scheduling result is materially better under the same workload.
8398

99+
## Optional Network Modules (BETA)
100+
101+
The optional network helpers are currently marked **BETA**:
102+
103+
- `ZeroTransportMetrics`
104+
- `ZeroHttpPump`
105+
- `ZeroMqttPump`
106+
- `ZeroWiFiMaintainer`
107+
108+
They are already useful and validated on desktop plus ESP32 hardware, but they are still under active tuning for footprint, retry behavior, and cross-board transport quirks. The core runtime is the stable layer; the network helpers should be treated as add-on modules that are ready for evaluation and controlled deployments.
109+
84110
## Field Validation: ESP8266 Seismic Node
85111

86112
Measured on a real `ESP8266` direct-AP seismic node using:
@@ -351,6 +377,11 @@ void loop() {
351377

352378
## Higher-Intent Demo Projects
353379

380+
Recommended realistic network workload:
381+
382+
- `examples/RealProjectNode`:
383+
a portable node-style workload that simulates sensor sampling, WiFi link maintenance, HTTP delivery, MQTT delivery, queue pressure, and realistic intermittent transport failures.
384+
354385
- `examples/ESP32TelemetryNode`:
355386
a richer ESP32 node example with WiFi maintenance, capability-gated diagnostics, heartbeat events, and periodic runtime summaries.
356387
- `examples/ESP32TelemetryBaseline`:
@@ -362,6 +393,7 @@ void loop() {
362393

363394
Quick runners:
364395

396+
- `scripts/run_esp32_real_project_demo.sh /dev/ttyUSB1`
365397
- `scripts/run_esp32_telemetry_demo.sh /dev/ttyUSB1`
366398
- `scripts/run_esp32_telemetry_compare.sh /dev/ttyUSB1`
367399
- `scripts/run_fault_injection_demo.sh /dev/ttyUSB0`

‎docs/wiki/Beta-Modules.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Beta Modules
2+
3+
The following optional modules are currently marked **BETA**:
4+
5+
- `ZeroWiFiMaintainer`
6+
- `ZeroHttpPump`
7+
- `ZeroMqttPump`
8+
- `ZeroTransportMetrics`
9+
10+
They are already useful and validated on desktop plus ESP32 smoke tests, but they are not yet considered fully field-proven across all transport stacks and all board families.
11+
12+
## What BETA Means Here
13+
14+
- API shape is usable, but may still tighten as real-world patterns accumulate.
15+
- Performance and footprint are measured and improving, but still under active tuning.
16+
- The modules are suitable for evaluation, prototypes, and controlled deployments.
17+
- For production, validate them against your actual transport stack and retry policy.
18+
19+
## Not BETA
20+
21+
The core runtime (`scheduler`, `task registry`, `events`, `watchdog`, `state`, `panic`, `timing`) is the stable part of the project and is not flagged as BETA.

‎docs/wiki/Home.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# ZeroKernel Wiki
2+
3+
ZeroKernel is an embedded execution runtime for deterministic microcontroller firmware.
4+
5+
## Start Here
6+
7+
- Read the main [README](../../README.md) for installation, positioning, and before/after metrics.
8+
- Read [API](../api.md) for the public runtime surface.
9+
- Read [Architecture](../architecture.md) for the core design.
10+
- Read [Validation](./Validation.md) for the current test strategy and hardware notes.
11+
- Read [Beta Modules](./Beta-Modules.md) before adopting the optional network modules in production.
12+
13+
## Current Focus
14+
15+
- Keep the core runtime lean and deterministic.
16+
- Treat optional network helpers as add-on modules with bounded, measurable cost.
17+
- Preserve cross-target portability across ESP8266, ESP32, RP2040, and STM32-class boards.

‎docs/wiki/Validation.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Validation
2+
3+
## Automated Gates
4+
5+
- Desktop tests: `scripts/run_desktop_tests.sh`
6+
- Lean smoke: `scripts/run_desktop_lean_smoke.sh`
7+
- Desktop benchmark: `scripts/run_desktop_benchmark.sh --enforce-performance`
8+
- Resource matrix: `scripts/run_resource_matrix.sh --enforce-budget`
9+
10+
## Hardware Validation
11+
12+
Current active field validation is strongest on:
13+
14+
- ESP8266 (`Wemos D1 mini`) for compare, stress, and seismic-node validation
15+
- ESP32 for module smoke tests, telemetry compare, and real-project network simulation
16+
17+
## Known Tooling Limits
18+
19+
- `arduino-cli` compile jobs should run sequentially. Parallel compile runs can collide in cache paths.
20+
- ESP32 upload can occasionally fail mid-flash due to `esptool` transport instability; retrying the upload usually succeeds.
21+
- Serial capture on ESP32 is valid but can truncate if capture starts mid-stream; the provided capture helper reduces this but does not eliminate it entirely.
22+
23+
## Reading Performance Results
24+
25+
- Favor deterministic metrics first: `fast_miss`, average lag, max lag.
26+
- Compare `success rate` and queue depth, not just raw `ok/fail` counts, when failure injection is part of the workload.
27+
- Treat synthetic fail-injection examples as throughput/stability checks, not as production success-rate claims.

‎src/modules/net/ZeroHttpPump.h‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ namespace modules {
99
namespace net {
1010

1111
// Optional cooperative HTTP request pump. Header-only and only linked when included.
12+
// BETA: suitable for evaluation, but still under active transport and retry tuning.
1213
class ZeroHttpPump {
1314
public:
1415
enum StepResult : int8_t {

‎src/modules/net/ZeroMqttPump.h‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ namespace modules {
99
namespace net {
1010

1111
// Optional cooperative MQTT pump. Header-only and only linked when included.
12+
// BETA: suitable for evaluation, but still under active transport and retry tuning.
1213
class ZeroMqttPump {
1314
public:
1415
struct Message {

‎src/modules/net/ZeroTransportMetrics.h‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ namespace modules {
66
namespace net {
77

88
// Optional transport metrics helper. Header-only and only linked when included.
9+
// BETA: validated on desktop and ESP32 smoke tests, still under active tuning.
910
class ZeroTransportMetrics {
1011
public:
1112
struct Snapshot {

0 commit comments

Comments
 (0)