An open-source closed-loop biosignal research instrument that preserves the evidence between measurement, decision, intervention, and observed response.
ENGINEERING REVIEW ONLY — Experimental research hardware. This repository is not approved for fabrication or human connection and does not establish medical-device, electrical-safety, EMC, or measurement-performance claims.
Most sensing systems stop at measurement. CIRCLE asks what happens next: can a system detect a changing relationship among physiological signals, make a bounded decision using only what it knew at that moment, issue an intervention, independently observe whether the intervention physically happened, and let another researcher replay the whole thing from the raw data?
sense → preserve → infer → decide → intervene → observe → verify
The evidence chain is the product. Point at any closed-loop event and ask why did CIRCLE do that? The record leads back to the exact samples that caused the decision, and forward to the independent observation of what actually occurred.
| Status | |
|---|---|
| Signal pipeline, closed-loop controller, evidence export, audit and replay | Implemented, validated only against a simulated physiology twin |
| Adversarial scenario suite and experiment-protocol boundary | Implemented, simulation only |
Rev B hardware (circle-main, circle-ppg) |
Designed, not built. Schematics pass ERC; PCBs are not routed (DRC passes only with an open allowlist) |
| Firmware | Not implemented. The twin encodes the timing behavior firmware must meet |
| Bench, phantom, electrical-safety, EMC, physiological, or human validation | None performed |
| Resonance, emergence, PNT modules | Bounded research extensions with explicit status (capabilities.json) |
pip install -r requirements.txt
python tools/run_physiology_twin.py --output outputs/physiology --auditAbout ten seconds later you have a six-minute closed-loop session (rest, breath hold, stressor, recovery with haptic guidance), scored against hidden truth and independently audited:
SESSION: TWIN-CLEAN-S7-ACTIVE
MODE: SIMULATED
HARDWARE: Rev B forward model (no hardware built)
CONTROLLER: 1.1.0
INPUT: 4 streams (imu, ppg, eda, sync)
GAPS: 1 declared
EVALUATIONS: 59 (2 decisions, 9 failed a quality gate, 0 held an action)
INTERVENTIONS: 1 program(s), 7/7 cues physically observed
HUMAN DATA: NONE
HARDWARE DRIVEN: NONE
audit replay status: REPLAY_MATCH
Open outputs/physiology/report.html (an example is committed at diagrams/circle-physiology-session.html). Click any row of the decision ledger to follow it down the evidence stack: formula → components → input cutoff → quality gates → exact sample ranges. The execution table shows, per cue, whether the command was followed by an electrical onset and by vibration the wrist IMU independently observed.
Under known simulated truth, the software's measurement, timing, decision, and evidence logic behave as specified:
| Recovered from raw Rev B codes (held-out seeds 100–149) | Result |
|---|---|
| Heartbeats from PPG (±50 ms, motion-free) | F1 0.9999 |
| Heart rate · HRV (RMSSD) | MAE 0.39 bpm · 1.5 ms |
| Breathing rate · breath hold | MAE 0.36 /min · IoU 0.98 |
| Skin conductance responses | sensitivity 0.98 · PPV 1.00 |
| SpO₂ during hand movement | 0 false desaturations after gating |
| PPG timestamps across a FIFO overflow | worst 39 µs (spec ≤ 1 ms); loss declared exactly |
| Haptic command → IMU-observed vibration | within 3 ms of truth |
999 of 1000 checks pass; the failure (seed 147, SCR sensitivity) is retained and explained in the pipeline methods. Adversarial scenarios on never-examined seeds 500–529: 199/210 runs pass; all 11 failures are one documented limitation (after long motion, the controller acts on a lagging proxy of a resolving state). See closed-loop evidence.
Hardware safety, electrical performance, physiological accuracy, or any effect on people. The twin is phenomenological; its paced-breathing response is assumed. The matched sham arm shows the evidence chain can resolve an effect under that assumption, not that the effect exists. Simulation success is not hardware validation, and repository verification is not permission for fabrication or human connection.
- Decision ≠ command ≠ actuation ≠ effect ≠ interpretation. Each is a different record. Every cue earns an execution stage (
COMMAND_ONLY→ELECTRICAL_ONSET_OBSERVED→PHYSICALLY_OBSERVED) only from its own evidence; the contract rejects a stage the evidence does not earn. No record asserts that physiology changed. - Every decision obeys time. Each sample carries when it was taken and when firmware held it in memory. Decisions record
decision_time_usandinput_cutoff_us; the audit fails any decision that used evidence from its future, whatever produced it. - Replay has an explicit status:
REPLAY_MATCH,REPLAY_DIVERGENCE,TIMING_VIOLATION,VERSION_MISMATCH,EVIDENCE_INTEGRITY_FAILURE,MISSING_SOURCE, orINSUFFICIENT_EVIDENCE. Divergence is surfaced, never reconciled. - Quality gates have teeth. Stale data, saturation, electrode contact loss, optical coupling change, low beat coverage, motion (including at the cutoff), and single-system signals all produce recorded holds. A loop that cannot observe its effect stops.
- The twin tries to break the loop: motion, poor contact, timing faults, sensor loss, feedback artifact, and ambiguous physiology, judged against hidden truth rather than the controller's own gates.
- Provenance classes stay distinct:
RAW_MEASURED,DERIVED,MODEL_INFERRED,SIMULATED,TEST,INTERVENTION(contracts/session-record.schema.json). CRC-32C and SHA-256 detect accidental change; they are not authentication.
python tools/audit_physiology_run.py outputs/physiology # re-derive, replay, check time and execution
python tools/run_physiology_twin.py --sham --output outputs/sham # matched arm: decisions logged, cues not actuated
python tools/run_physiology_twin.py --scenarios # adversarial suite
python tools/run_physiology_twin.py --benchmark 50 # held-out physiology benchmarkBetter models should gain analytical resolution, not authority. A proposed experiment (from a person or a model) is compiled into a structured protocol, validated deterministically (simulation target only, mandatory sham arm, gates may only tighten, causality margin untouchable, held-out seeds, Holm correction), then authorized by a named human bound to the protocol's SHA-256, then executed against the twin.
python tools/run_protocol.py validate experiments/protocols/paced-breathing-arousal.json
python tools/run_protocol.py authorize experiments/protocols/paced-breathing-arousal.json --reviewer "Your Name" --output outputs/auth.json
python tools/run_protocol.py run experiments/protocols/paced-breathing-arousal.json --authorization outputs/auth.json --output outputs/protocol-result.jsoncircle-main(85 × 55 mm, 4-layer): ESP32-S3-WROOM-1-N16R8; ADS1220 EDA front end with REF5020 and OPA2192; ICM-42688-P IMU; 4-bit SDMMC with PSRAM buffering; DRV2605L haptics with a TLV3201 current-edge detector so actuation leaves electrical evidence; BQ24074 + TPS63070 power; MCP23017 observability.circle-ppg(25 × 18 mm): MAX30102 raw red/IR, LP5907, TXS0102, AT24CS02 ID.- Domains: human-connected
BAT_HUMANseparated fromLAB_ISOby an ISOW7742 isolator (component rating 5.0 kVrms reinforced; the assembled barrier is untested) and an 8.0 mm board slot. Hardware interlocks are designed to remove electrode drive when USB, debug, or expansion cables are attached; the calculated single-fault electrode current is ≤ 27.5 µA (unreviewed calculation).
Numbers above are datasheet ratings, calculations, or design targets unless stated otherwise (where numbers come from). Before any body contact, evidence must climb the physical evidence ladder: electronic and optical phantoms, bench sensors, isolated system tests, hardware loopback, and only then, after independent safety review and ethics approval, any human-connected session.
Review artifacts: architecture · system diagram · safety analysis · safety boundaries · main schematic · optical schematic · bring-up plan · 3D viewer
The 3D viewer and animation show intended geometry. They display no telemetry; nothing in them is simulated or measured.
Each module attaches through contracts, preserves provenance and simulation status, and can be removed without breaking the instrument (tools/check_module_registry.py enforces that no core module imports one).
| Module | Implemented | Status | Not claimed |
|---|---|---|---|
| Resonance (docs, hypotheses) | Coupled-cavity simulator; blinded factorial scheduling; autocorrelation-aware permutation tests; phantom discrimination; multiplicity-adjusted statuses | EXPERIMENTAL (simulation) |
No chamber exists (SPECULATIVE); no geometry effect measured. Visualization is not evidence. |
| Emergence (docs) | ATOM correlation search, now reported against a circular-shift surrogate null with family-wise correction and a known-truth score | EXPERIMENTAL |
Discoveries are exploratory correlations; no causal, nonlocal, or consciousness claim |
| PNT (docs) | Translation-only 15-state estimator vs unaided baseline on shared simulated IMU samples with known truth | SIMULATION_VALIDATED |
Quantum sensing, atom interferometry, gradiometry, clock fusion: SPECULATIVE, not implemented |
| R.A.I.N. protocol (docs) | Manifest/result/analysis contracts | CONTRACT_ONLY |
The executor lives in another repository |
The stranger the hypothesis, the more ordinary the measurement discipline: identical measurement logic across conditions, predefined comparisons, blinding, preserved null results, and correction for every configuration searched.
python tools/verify_release.py --software-only # software scopes; never implies hardware
python tools/verify_release.py # also fresh ERC/DRC with the pinned KiCad (toolchain.json)
python tools/check_review_gates.py # what the open gates do not authorize| Scope | State |
|---|---|
| Software contracts · simulation benchmark · generated artifacts | Pass |
| Schematic ERC | Archived KiCad 10.0.5 reports pass; fresh run requires the pinned toolchain |
| PCB DRC | Zero rule violations with an open allowlist of 52 unrouted nets |
| Bench validation · electrical-safety review · isolation withstand · EMC · measurement chain | Not performed |
| Fabrication · human use | Not authorized (18 open gates in hardware/review-gates.json) |
Missing KiCad reports INCOMPLETE, never success. See verification scopes.
circle/
├── capabilities.json # every module's status and what it does not claim
├── contracts/ # session records, experiment protocols, review gates, research-module schemas
├── models/
│ ├── physiology/ # twin, Rev B sensor models, pipeline, controller, evidence, audit, ledger, scenarios
│ ├── protocols.py # proposal → validation → authorization → simulated execution
│ ├── session_records.py # contract validation, lineage, CRC-32C
│ └── resonance_response/, emergence/, pnt/ # research extensions
├── tools/ # runners, auditors, verifiers, PCB and schematic generators
├── tests/ # contracts, adversarial evidence tests, frozen scenario corpus
├── docs/ # closed-loop evidence, verification scopes, evidence ladder, hardware and safety docs
├── experiments/ # research protocols and example experiment protocols
├── hardware/ # KiCad sources, design manifest, interfaces, review gates, generated reports
└── diagrams/ # rendered diagrams, session report example, 3D viewer
- All physiological data in this repository are simulated. No person has been measured.
- No hardware has been fabricated, powered, or measured; PCBs are unrouted; no firmware exists.
- Automated KiCad checks are not an independent electrical-safety review.
- Physiological signals are observables, not readings of emotion, stress as a diagnosis, intent, or consciousness. The arousal index is an engineering trigger.
A human state is rarely one signal. The body produces many imperfect signals, and understanding begins in the relationships among them. CIRCLE tries to be humble about what sensors can reveal: it preserves ambiguity, lets different physiological pathways produce similar observations without collapsing them into one score, distinguishes signal from interpretation, and treats an intervention as something that creates new evidence, not as proof that a model was right.
CIRCLE is an open-source research project by Vers3Dynamics. Built by one researcher. Held in common. Free to explore.