Skip to the content
4 layers78 × 58 mmEeg ads1299 lab, the printed circuit board in 3D

Eeg ads1299 lab

utof/eeg_ads1299_lab

It is not a finished EEG recorder, a validated PCB, or permission to attach a circuit to a person. The firmware is a board-dependent bench-only starter using the ADS1299's internal test/short circuits.

Size
78 × 58 mm
Copper layers
4
Thickness
1.6 mm
Parts
70
Nets
60
Pads
253
Tracks, vias
594, 122
Pours
1
Routed
Yes
KiCad
KiCad 9 (file 20241229)
Created
22 Sep 2026
Updated
15 Oct 2026

Overview

Eeg ads1299 lab is an open-source printed circuit board by utof, from the utof/eeg_ads1299_lab repository on GitHub. It is a 4-layer board of 78 × 58 mm with 70 parts on 60 nets, routed with 594 tracks and 122 vias.

It is built around the ADS1299-4PAGR, TPS7A2033PDBVR-TP and BAV199,215-JSM, with the RC0603FR-0710KL, RC0603FR-071ML and HTSW-110-07-T-D among its other parts. Its parts include 33 capacitors, 24 resistors, 8 diodes, 3 connectors and 2 ICs.

Main components

10

README

README.md

ADS1299 Learning Lab

Start without buying anything. This is a runnable Python learning environment for EEG-like signals, an illustrative electrode/input circuit, signed 24-bit conversion, data transport, signal quality, and a small machine-learning experiment.

It is not a finished EEG recorder, a validated PCB, or permission to attach a circuit to a person. The firmware is a board-dependent bench-only starter using the ADS1299's internal test/short circuits. Rev A selects an ADS1299-4 daughterboard plus ESP32-S3-DevKitC-1-N8R8 for simulation/schematic work; none of the hardware-review or body-connection gates are approved.

Open these first

FileWhat it does for you
START_HERE.htmlOffline visual walkthrough, provisional digital pin map, interactive gain/offset calculator. Open with the rest of the repository available.
Agent instructions / GitHub publication runbookFresh assistant starts here; working publication methods, review boundaries and recovery checks.
Development guideLocked installation, one quality command, test-first changes, strict typing, and enforced public interfaces.
DX validation recordA dated CI run with software tests, actual ngspice execution, native helper tests, and limitations.
Historical results reportOriginal measured outputs and evidence; retained rather than overwritten by routine CI.
Learning guideA beginner explanation of the electronics, simulations, signal processing, and small exercises.
Hardware guidePurchasing gate, $100 budget constraint, conditional wiring, bench tests, and the body-connection boundary.
Rev A hardware baselineSelected ADS1299-4 + ESP32-S3 components, machine-readable BOM/profile, fail-closed gates, and ordered next work.
Experiments guideFrom synthetic alpha to a future controlled meditation experiment, without confusing artifacts with consciousness.
Next-session handoffGive this to a future assistant together with the source and validation records.

The earlier uploaded reports are background, not software dependencies. This package does not depend on their old ZIP links or on an AD8232/ADS1115.

For assistant-run repository work: follow the hosted capability preflight before proposing downloads or local setup. The installation commands below are for people choosing to run the lab locally, not prerequisites for hosted editing or KiCad validation through the connected tools.

First run: Linux, macOS, or Windows

Use Python 3.11 or newer; Python 3.13 is the development default. CI exercises clean locked installations on Linux with Python 3.11 and 3.13. macOS and Windows are not currently covered by that CI matrix. pyproject.toml and uv.lock define the current dependencies; requirements-tested.txt is a historical validation record.

Clone or extract the repository, then open a terminal inside eeg_ads1299_lab:

bash
uv sync --locked --all-extras
uv run --locked python run_lab.py demo
uv run --locked python -m tools.check

Install uv 0.12.18 first using the official installation instructions. The standalone installer supports an explicit version in its URL. All project commands use uv; do not use a separately activated environment or bare Python/pip to run or modify this project. The editable installation makes imports work outside the checkout too.

The demo makes reports/demo/synthetic_recording.npz, event/quality CSVs, an analysis JSON, and four PNG figures. Live commands default to ignored reports/; committed results/ examples are historical evidence. Use --out reports/my_demo for a separate run. The seed is fixed, but numerical outputs can vary slightly across dependency versions.

The quality command checks formatting, Ruff lint, strict Pyrefly typing, cognitive complexity, Tach import boundaries, the hardware baseline, software tests, and measured branch coverage. It includes the hardware-baseline tests that formerly needed a separate discovery command. Logs and reports go under reports/check/, not over historical evidence.

A successful software check is not a native-simulator, firmware-target, or hardware pass. Run the explicit native command below for native integration. uv run --locked python run_lab.py verify is now a compatibility entry point to the same tools.check gate. Add --native for native integration; --require-ngspice remains an alias. There is no competing historical-report verifier.

Before making changes, read AGENTS.md and install both the pre-commit and commit-message hooks:

bash
uv run --locked pre-commit install

Run a circuit simulation

bash
uv run --locked python run_lab.py circuits --out reports/circuits

This solves the existing illustrative passive circuit using Python's linear algebra, writes response/tolerance CSVs, and exports two .cir files. The numerical solver is not ngspice. There is no transistor-level ADS1299 model, and the next Rev A-specific input-network model is separate work.

For a real ngspice cross-check and the full native gate on Debian/Ubuntu/Linux Mint:

bash
sudo apt update
sudo apt install --no-install-recommends ngspice g++ nodejs
uv run --locked python run_lab.py circuits --require-ngspice --out reports/circuits
uv run --locked python -m tools.check --native

The strict commands fail when required tools are absent. The DX CI run recorded in DX_VALIDATION.md actually executed ngspice and compared both educational circuits with the independent numerical solution. That newer CI evidence does not change what ran in the original historical validation environment. Simulator logs remain under the output folder.

Three useful changes

bash
# Negative control: remove the planted condition difference.
uv run --locked python run_lab.py demo --null-effect --out reports/my_null

# Eight physical channels and 60-Hz residual line interference.
uv run --locked python run_lab.py demo --channels 8 --line-hz 60 --out reports/eight_channels

# Edit a copy of this JSON to change gain, offset, or artifact size.
uv run --locked python run_lab.py demo --config configs/demo.json --out reports/custom

Changing a JSON changes the simulation, not a physical board. The firmware does not read configs/demo.json or the board-review worksheet.

Test the recording path with no electronics

bash
uv run --locked python -m tools.check --native

The native gate includes the real localhost UDP loopback: nine seconds of synthetic packets with samples 1000 and 2000 deliberately omitted, CSV decoding, and a gap-safe quality report. It checks 2,248 accepted packets and two missing samples. Unexpected extra loss causes a failure rather than a reassuring-looking plot. To run only the loopback, use uv run --locked python -m tools.run_loopback --out reports/loopback.

For manual control, use two terminals:

bash
# Terminal A
uv run --locked python run_lab.py receive --seconds 15 --out reports/practice.bin
bash
# Terminal B, while A is listening
uv run --locked python run_lab.py replay --seconds 8 --drop-every 1000

Then:

bash
uv run --locked python run_lab.py decode reports/practice.bin --out reports/practice.csv
uv run --locked python run_lab.py inspect reports/practice.csv --out reports/practice_quality

Keep the .json metadata beside the decoded CSV. New captures include a SHA-256 binding the pair; inspection rejects a mismatched generation. Legacy captures without a digest remain readable with an explicit caution. The inspector analyzes only uninterrupted four-second windows. It reports DC offset separately and never fills gaps to manufacture a continuous spectrum. The receiver defaults to localhost; actual LAN use requires --host 0.0.0.0, private-network firewall permission, and the computer's LAN address in the firmware. UDP is unencrypted; never expose the port to the public internet.

What is in the source?

text
lab/adc.py              Ideal code scaling, range/headroom checks, sinc³ model
lab/analog/            Public analog facade; internal solver, SPICE, and report modules
lab/data_types.py      Typed numerical arrays and data/report contracts
lab/validation.py      Runtime validation at external-data boundaries
lab/signals.py          Deterministic, explicitly synthetic recordings
lab/dsp.py              Quality screens, band power, session-held-out classifier
lab/protocol.py         ADS frame decoding, custom packets, CRC and counters
lab/acquisition.py      UDP/optional bench serial logging and CSV decoding
lab/inspect_capture.py  Gap-safe bench spectra and quality reports
lab/recording.py        Synthetic recording validation and atomic NPZ persistence
lab/pipeline.py         Demo outputs and figures; compatibility persistence re-exports
hardware/rev_a/         Hardware-contract facade, checker, data, and tests
firmware/              Original-ESP32 bench starter; NOT target-compiled by the DX gate
configs/               Editable demo settings and hardware-review worksheet
results/               Historical example recordings, figures, logs, and reports
reports/               Ignored outputs from current quality/simulation runs
tests/                 Regression, property, architecture, and workflow tests
tools/check.py         Shared local/CI quality command
tools/commit_messages.py Conventional Commit hook and actual-history validation
tach.toml              Enforced public interfaces and dependency direction

The firmware's default BOARD_PROFILE_REVIEWED = false intentionally prevents acquisition startup. Changing that setting acknowledges bench digital wiring only, not body-use approval. Do not bypass it just to see a waveform.

Rev A input-network study

The selected Rev A input components now feed a reproducible passive-network study, rather than remaining isolated hardware JSON. Start with the numerical calculation; then run the independent simulator comparison when ngspice is installed:

bash
uv run --locked python -m lab.rev_a --out reports/rev_a_input
uv run --locked python -m lab.rev_a --require-ngspice --out reports/rev_a_input_native

The study validates and loads the locked 4.99 kOhm / 4.7 nF component values and BOM tolerances, checks an ideal-source reference, compares balanced and mismatched source impedances, evaluates eight tolerance corners per case, and reports 50/60 Hz common-mode conversion plus hypothetical DC leakage sensitivity. The native command actually runs six ngspice comparisons. uv run --locked python -m tools.check --native includes this study and retains its evidence under reports/check/rev_a_input/.

All source/load/parasitic assumptions appear in the report. Clamps remain DNP. This is not an ADS1299 silicon, distributed-cable, BIAS-loop, physical-hardware or human-use safety model. Read the Rev A study guide before interpreting the numbers.

Contributing: uv and Conventional Commits

Use uv sync --locked --all-extras and uv run --locked ... for project work. Child processes launched with sys.executable inherit that locked interpreter; they do not create a second environment. CI bootstraps uv itself separately, then uses the same locked commands.

Commit subjects follow Conventional Commits 1.0.0:

text
feat(simulation): add a Rev A input-network sweep
fix(recording): reject discontinuous sample times
refactor(acquisition): stream decoded packets
chore(dx): synchronize issue labels

Use lowercase feat, fix, docs, style, refactor, perf, test, build, ci, chore, or revert; an optional lowercase scope describes the affected component. A breaking change uses ! after the type/scope and should explain the incompatibility in a BREAKING CHANGE: footer. Subjects must have a nonempty description and no trailing whitespace.

The installed commit-msg hook checks the subject. CI checks actual commits introduced by the PR, not just its title. Old history is grandfathered. Actual merge commits are exempt, but writing “Merge” on a single-parent commit is not a bypass. Merge PRs with merge commits: no squash and no history rewriting. Validate a range locally with:

bash
uv run --locked python -m tools.commit_messages --base origin/main --head HEAD
uv run --locked python -m tools.check --native

Issues use one type/*, one priority/*, and applicable area/* labels. Examples: type/bug + priority/high + area/acquisition, or type/refactor + priority/medium + area/dx. The label manifest owns names, colors, and descriptions; trusted-main housekeeping synchronizes it without deleting unrelated labels. Merged same-repository PR branches are removed only after ancestry and exact-head checks. Active or changed branches are retained.

Read the adversarial review for the architecture verdict, reproduced failures, corrections, and remaining limits.

Troubleshooting

SymptomFirst action
ModuleNotFoundErrorRun uv sync --locked --all-extras and use uv run --locked with the repository environment.
Missing ngspice or native compilerInstall the required tool; do not count numerical Python tests as native execution.
Quality gate failedRead the named log and reports/check/CHECK_REPORT.json; do not bypass the check.
All epochs rejectedInspect gain, differential DC offset, and quality flags. An overrange input is an expected negative test.
No UDP packetsFirst repeat localhost loopback. Then inspect the private LAN address, firewall, and UDP port.
No four-second spectral windowsThe capture is too short or fragmented. Fix acquisition before interpreting spectra.
Unexpected ESP32 or board pinsStop; the supplied firmware pin map is not generic to every ESP32/ADS1299 module.
Matplotlib cache permission warningSet MPLCONFIGDIR to a writable directory; no special font installation is required.

Read SOURCES.md for primary references and MODEL_SCOPE.md for model boundaries.

Bounded BIAS overload hypothesis

uv run --locked python -m lab.rev_a_bias_overload --require-ngspice compares a stated one-pole rail/slew hypothesis with ngspice while preserving feedback capacitor charge. It is not measured ADS1299 overload recovery. Read the scope, source limits and numerical checks.

Shared-source analog-feed hypothesis

Run uv run --locked python -m lab.rev_a_supply for five independently checked startup/burst cases of the selected analog-feed path. See the study and its assumptions. A completed numerical comparison may expose a modeled rail-margin breach; neither outcome qualifies the board or the separate TPS7A20 model.

Parts

70
QtyValueFootprintReferences
151uCapacitor_SMD:C_0603_1608MetricC8, C9, C10, C11, C12, C13, C14, C15, C16, C17, C18, C19, C20, C21, C22
84.99kResistor_SMD:R_0603_1608MetricR1, R2, R3, R4, R5, R6, R7, R8
8BAV199,215Package_TO_SOT_SMD:SOT-23D1, D2, D3, D4, D5, D6, D7, D8
7100nCapacitor_SMD:C_0603_1608MetricC23, C24, C25, C26, C27, C28, C29
742.2kResistor_SMD:R_0603_1608MetricR12, R13, R15, R16, R17, R18, R19
510kResistor_SMD:R_0603_1608MetricR14, R20, R21, R22, R23
410uCapacitor_SMD:C_0805_2012MetricC30, C31, C32, C33
44.7nCapacitor_SMD:C_0603_1608MetricC1, C2, C3, C4
21MResistor_SMD:R_0603_1608MetricR9, R10
2HTSW-110-07-T-DConnector_PinHeader_2.54mm:PinHeader_2x10_P2.54mm_VerticalJ1, J2
11.5nCapacitor_SMD:C_0603_1608MetricC5
110Resistor_SMD:R_0603_1608MetricR11
1100uRevA_Passives:T491D_7343_DensityBC6
122uRevA_Passives:T491B_3528_DensityBC7
1ADS1299-4PAGRPackage_QFP:TQFP-64_10x10mm_P0.5mmU1
1B6B-XH-A(LF)(SN)Connector_JST:JST_XH_B6B-XH-A_1x06_P2.50mm_VerticalJ3
1NOT_SELECTEDResistor_SMD:R_0603_1608MetricR24
1TPS7A2033PDBVRPackage_TO_SOT_SMD:SOT-23-5U2

More from utof/eeg_ads1299_lab

1
  • 4 layers90 × 75 mmAuxiliary, the printed circuit board in 3D

    Auxiliary

    utof/eeg_ads1299_lab

    It is not a finished EEG recorder, a validated PCB, or permission to attach a circuit to a person. The firmware is a board-dependent bench-only starter using the ADS1299's internal test/short circuits.

    56 parts

Similar boards

  • 6 layers91.6 × 50.6 mmSmokebreak, the printed circuit board in 3D

    Smokebreak

    offgridevices/offgrid-hardware

    Open hardware from OffGrid Devices. One folder per board. CERN-OHL-S.

    208 partsCERN-OHL-S-2.0
  • 4 layers94.3 × 65 mmHPM5300 ADC EVK RevA, the printed circuit board in 3D

    HPM5300 ADC EVK RevA

    hpmicro/hpm_apps

    hpm apps for hpm sdk

    221 parts35BSD-3-Clause
  • 4 layers116 × 112 mmBldc esc, the printed circuit board in 3D

    Bldc esc

    EwoudVV/bldc-esc

    A custom STM32 motor controller for BLDC and PMSM motors.

    453 parts2
  • 4 layers275 × 240 mmSupervisor, the printed circuit board in 3D

    Supervisor

    BennetLeff/temper

    a breville control freak ++

    440 parts1
  • 4 layers165 × 100 mmUsb scoring platform, the printed circuit board in 3D

    Usb scoring platform

    AndrewCraswell/agency

    Native KiCad engineering prototype, separate from the earlier ESP32/tscircuit board. Open usb-scoring-platform.kicadpro in KiCad 10; schematic and PCB are the editable source, with no generator required.

    224 partsMIT
  • 4 layers99.8 × 94.6 mmOresat proto card, the printed circuit board in 3D

    Oresat proto card

    oresat/oresat-proto-card

    Prototype card for the OreSat bus. Requires the OreSat Backplane.

    128 parts9
  • 4 layers99.8 × 94.6 mmOresat adcs card, the printed circuit board in 3D

    Oresat adcs card

    kitspace-test-repos/kicad6-file-collection

    563 partsMIT

Questions

How big is the Eeg ads1299 lab PCB?

It measures 78 × 58 mm and has 4 copper layers, 1.6 mm thick.

What parts does the Eeg ads1299 lab use?

70 parts, built around the ADS1299-4PAGR, TPS7A2033PDBVR-TP, BAV199,215-JSM and RC0603FR-0710KL. The full list of its parts is on this page, with links to each part's symbol and footprint where PCBKit's library has them.

Where can I download the Eeg ads1299 lab KiCad files?

From the utof/eeg_ads1299_lab repository on GitHub, at the commit this page was made from: the board is hardware/rev_a/layout/rev_a.kicad_pcb and its schematic hardware/rev_a/auxiliary/arming.kicad_sch. PCBKit opens the board in the browser, with nothing to install.

Can I use the Eeg ads1299 lab design in my own project?

Its repository states no licence, so its author keeps all rights: ask utof before reusing the design.