Refresh project documentation

Red Bear OS Team
2026-04-16 12:46:07 +01:00
parent aeac5a6d92
commit 90fa45c545
32 changed files with 1659 additions and 167 deletions
@@ -0,0 +1,96 @@
+# Red Bear OS Bluetooth Validation Runbook
+
+This runbook is the canonical operator path for exercising the current bounded Bluetooth Battery
+Level slice on Red Bear OS.
+
+It does **not** claim that Bluetooth is broadly solved. Its job is to make the current
+profile-scoped, QEMU-validated Battery Level workload reproducible and honest.
+
+## Goal
+
+Produce one or both of the following:
+
+- a successful bounded Bluetooth validation run via `redbear-bluetooth-battery-check`
+- a repeatable QEMU/UEFI validation log via `./local/scripts/test-bluetooth-qemu.sh --check`
+
+## Path A - Host-side QEMU validation
+
+Use this when the host supports the repo's normal x86_64 QEMU/UEFI flow.
+
+### On the host
+
+Build the tracked Bluetooth profile first:
+
+```bash
+./local/scripts/build-redbear.sh redbear-bluetooth-experimental
+```
+
+Then run the automated QEMU harness:
+
+```bash
+./local/scripts/test-bluetooth-qemu.sh --check
+```
+
+What that harness does today:
+
+1. boots `redbear-bluetooth-experimental` in QEMU with `qemu-xhci`
+2. logs in automatically on the serial console
+3. runs `redbear-bluetooth-battery-check` twice in one boot
+4. reboots the guest
+5. runs `redbear-bluetooth-battery-check` again after the clean reboot
+
+### Artifact to preserve
+
+- the full terminal log from `./local/scripts/test-bluetooth-qemu.sh --check`
+- any serial or CI log captured around the run
+
+## Path B - Interactive guest validation
+
+Use this when you want to inspect the runtime manually inside the guest.
+
+### On the host
+
+```bash
+./local/scripts/test-bluetooth-qemu.sh
+```
+
+### Inside the guest
+
+Run the packaged checker directly:
+
+```bash
+redbear-bluetooth-battery-check
+```
+
+The legacy guest helper remains as a compatibility wrapper:
+
+```bash
+test-bluetooth-runtime.sh
+```
+
+Useful supporting commands inside the guest:
+
+```bash
+redbear-btusb --status
+redbear-btctl --status
+redbear-info --verbose
+```
+
+## What success means today
+
+Current success is still **bounded** success:
+
+- the explicit-startup `redbear-btusb` and `redbear-btctl` path can be exercised in QEMU
+- the packaged checker can be rerun repeatedly in one boot
+- the checker covers daemon restart cleanup and disconnect stale-state cleanup within the current
+  Battery Level slice
+- the exact Battery Service / Battery Level UUID pair can be read through the bounded read-only
+  workload and reported conservatively by `redbear-info`
+
+This is **not yet** the same as:
+
+- real controller bring-up proof
+- generic BLE or generic GATT maturity
+- write support or notify support
+- real pairing or broad reconnect semantics
+- desktop Bluetooth parity, HID, audio, or passthrough-backed hardware claims