macOS host tools for an eight-channel ADS1299/ESP32-S3 EEG device. The repository includes the hardware, manufacturing files, firmware, and a BLE-to-LSL workflow.
Built and maintained by Alex Teo (@agteo): macOS host tools, the BLE-to-LSL receiver, the alpha test, and the documentation. First result: eyes-open / eyes-closed alpha test, 1 Nov 2026.
Hardware and firmware design by Xavier Asghar.
Included:
- Hardware design files in
Hardware - Gerbers, drill files, enclosure STLs, and BOM in
Production_Files - Mac usage notes in
Documentation - The PlatformIO firmware project in
Software/Firmware_Platformio_Project - BLE receiver that publishes an eight-channel
Custom_ESP32_EEGLSL stream at 500 Hz - Alpha eyes-open / eyes-closed LSL marker session
- Daily Berger runner with an optional serial-7 block, a session log, and
recordings/index.csv - Fz focus, engagement, and theta/beta from that serial-7 minute, reviewed in an HTML report
- XDF alpha-band plotter
- Unit tests for the binary BLE-frame decoder, including sample loss separate from notification arrival spacing
Not included or validated:
- Medical or diagnostic use
- P300 and other latency-sensitive experiments
- Hardware-timestamped stimulus synchronisation
The target device sends eight samples in each BLE notification and does not supply a hardware event timestamp. At 500 Hz those notifications are expected about every 16 ms. A gap in the frame sequence means those samples never arrived. The receiver counts that gap and publishes NaN placeholders for the missing samples. Spacing between notifications is a separate check: they can reach the Mac late or bunched together while the sequence is still complete. The sequence number is a single byte, so a gap of exactly 256 samples looks like no gap. Treat P300 timing and similar latency-sensitive measurements as unvalidated until measured on your assembled setup.
This software is for educational, non-medical work. When electrodes are attached to a person, use a battery-powered device with USB-C physically disconnected. Do not charge it, attach a programmer, or connect grounded accessories during a recording. Uploading firmware and using USB serial monitoring are bench-only tasks, before electrodes are attached.
To order the DIY-EEG board, use Manufacturing/JLCPCB: the drill-aligned fabrication zip, the JLCPCB BOM and CPL, and ORDER_NOTES.md from a real October 2026 order.
Production_Files/NC Drill and Hardware/PCB_Altium_Project/Project Outputs for DIY-EEG/NC Drill Files are offset by about +60.4 mm in X and +50.4 mm in Y from the Gerbers. Do not upload those drill files as they are.
Enclosure STLs and the other fabrication outputs are in Production_Files. See production notes. The schematic-and-layout PDF is not in this repository.
Altium Designer, which edits the board, runs on Windows only. A Mac can still order and check this board, because the fabrication files are already exported.
On a Mac:
- Order from
Manufacturing/JLCPCB. That zip has the drill files aligned to the Gerbers. Do not uploadProduction_Files/NC DrillorHardware/PCB_Altium_Project/Project Outputs for DIY-EEG/NC Drill Filesas they are. Those holes are offset by about +60.4 mm in X and +50.4 mm in Y. - Open the Gerbers in JLCPCB's viewer, or on the Mac with
gerbv(brew install gerbv) or KiCad's GerbView. Confirm the holes sit on the pads before you pay. - Print the enclosure from the STL files in
Production_Fileswith any Mac slicer.
Changing the schematic or the layout still needs Altium on Windows. After exporting new fabrication files, set the drill output to the same origin as the Gerbers, then check the holes in a Gerber viewer.
The included firmware is a PlatformIO project. Follow the macOS firmware guide to install PlatformIO, build, flash, and monitor it. The target is esp32-s3-devkitc-1 and its firmware BLE stream is what the Mac host tools expect.
One-time setup is in Documentation/INSTALL.md. Use Python 3.11, 3.12, or 3.13. The pinned bleak release does not install on Python 3.14 or 3.15.
With the receiver already running, start the viewer:
mne-lsl viewer -s Custom_ESP32_EEGThe session steps and the Scope settings controls are in Documentation/VISUALIZE.md. Setup sheets and a live viewer capture are in Documentation/FIGURES.md.
This is the eyes-open / eyes-closed alpha session. Posterior alpha (about 8–12 Hz) should rise with the eyes closed and fall when they open. A closed/open ratio clearly above 1 on an occipital channel is the Berger effect. The file always contains eight channels, numbered 0–7. Read the ones that have electrodes. An open input sits at the converter limit and has no rhythm.
Run the receiver in one Terminal window, from the repository root:
source .venv/bin/activate
diy-eeg-receiverIn another, with the same environment:
diy-eeg-alphaPress Enter when asked. Each phase lasts 20 seconds. The session writes recordings/alpha-<timestamp>.xdf and a channel-0 summary in recordings/alpha-<timestamp>.txt when it finishes. diy-eeg-alpha --phase-duration 5 is a short dry run.
Sit still, with electrodes on the back of the head. The terminal names each phase, and a sound marks the start:
- Eyes open. One glass sound. Stare at a fixed point. Blink only if you have to. Stay there until the next sound.
- Eyes closed. Two pings. Close your eyes without squeezing, and keep your face and neck still. Stay there until the next sound.
- Eyes open. One glass sound. Open your eyes and stare at the same point. Stay there until the low sound.
The low sound means the EEG is saved. The script then asks where the sitting was. The wall supply leaks a steady tone into the electrodes, 50 Hz in some countries and 60 Hz in others, and the scores remove a narrow notch at that tone so it is not counted as brain rhythm. The saved recording is left as it was. It also asks about sleep, caffeine, exercise, and paste. The summary then prints the 8–12 Hz level for each phase on every channel, and the eyes-closed / eyes-open ratio. An input that never moves is reported as not moving. Whether O1 moved is taken from the recording. Plot one channel with:
diy-eeg-analyze-alpha recordings/alpha-<timestamp>.xdf --channel 0The top trace is the raw channel, including the electrode offset. The bottom trace is the 8–12 Hz band, after the mains notch. Pass --channel with another index, from 0 through 7, to plot a different input. The notch follows the location saved with that sitting. Pass --mains 60 or --mains 50 to choose it for this plot. The saved text summary lists all eight channels.
To see the Berger effect as a spectrum, save an eyes-open vs eyes-closed power spectrum for one channel:
diy-eeg-alpha-spectrum recordings/alpha-<timestamp>.xdf --channel 0 --label O1It writes recordings/alpha-<timestamp>-spectrum-ch0.png, with the 8–12 Hz band shaded, and prints the eyes-closed alpha peak. The eyes-open line is the mean of both eyes-open phases. The spectrum uses the same mains notch as the summary. Pass --mains 60 or --mains 50 to choose it for this plot. Use --out to choose the file name and --fmax to change the frequency range (default 30 Hz). An example from a real session is in this lab note.
diy-eeg-daily is the command to run on a repeated day. It uses the same receiver and the same marker stream as the Berger test. Each block starts with a sound, and the marker is written at that moment.
With the receiver already running:
diy-eeg-dailyChannel 0 is O1, 1 is Oz, 2 is O2, 3 is POz, and 4 is Fz on J3 pin 5+. Bias stays at Fpz. The reference stays on the left earlobe. After the low sound, once the EEG is already saved, the script asks where the sitting was, then about sleep, caffeine, exercise, and paste. The location chooses the 50 Hz or 60 Hz notch used for the scores and later drawings. Whether O1 moved is read from the recording. The blocks are:
- Settle, 5 seconds. No sound. Sit still, eyes open.
- Eyes open, 60 seconds. One glass sound. Stare at a fixed mark.
- Eyes closed, 60 seconds. Two pings. Close on the first ping, without squeezing.
- Eyes open, 60 seconds. One glass sound. Stare at the same mark.
Pass --task serial7 on a focus day. Two further blocks follow, and the terminal prints a three-digit seed before they start. The saved summary still scores 8–12 Hz alpha, including the Fz line. The focus score is separate: Fz 4–8 Hz during serial 7, divided by the eyes-open stare. See Focus and engagement.
- Serial 7, 60 seconds. Three pings. Eyes open. Subtract 7 from the seed, silently, until the next sound.
- Eyes open, 30 seconds. One glass sound. Stop calculating and stare at the mark.
The low sound means the files are saved. Scoring leaves out the first 2 seconds of each block, so the cue itself is not in the ratio. The eyes-open level is the mean of the first two eyes-open blocks. A ratio clearly above 1 on O1 is the Berger check for that day.
Each run writes three files and appends one row to the index:
recordings/alpha-<timestamp>.xdf— EEG and markersrecordings/alpha-<timestamp>.txt— alpha levels for each channel that moved, labeled O1, Oz, O2, POz, and Fzrecordings/alpha-<timestamp>.yaml— the answers from the start of the sessionrecordings/index.csv— one row per session
diy-eeg-daily --phase-duration 5 is a short recording. diy-eeg-daily --rehearse plays the sounds and writes nothing, so you can learn the cues before wearing the cap. diy-eeg-daily --task serial7 adds the subtraction blocks. To attach the same questions to a recording that was saved without them:
diy-eeg-daily --annotate recordings/alpha-<timestamp>.xdfA caffeine or exercise day is the same command twice. Use the same pair id on both runs, and fill in the minutes-since questions on the second one. Leave a session marked qc: fail out of plots. The XDF is still kept.
To review the saved days in a browser:
diy-eeg-reportThat writes recordings/report.html from your own index. Open it in a browser. The top reads the trend in words. The chart can switch between O1, Oz, O2, the Fz focus ratio, the Fz engagement index during serial 7, and Fz theta/beta during serial 7. It can hide runs shorter than 30 seconds. Pick one session to see its waveform or spectrum, and switch channels on and off. The stare and serial-7 levels for engagement and theta/beta sit under the picker, with sleep, caffeine, and paste. That file stays in recordings/ and is not part of this repository.
A focus day is diy-eeg-daily --task serial7. Three scores come from the Fz electrode during that minute of silent subtraction. Each one leaves out the first 2 seconds after the cue, and each one uses the mains notch chosen for that sitting. The eyes-open side is the mean of the first two eyes-open blocks. A day without serial 7, or a still Fz input, has no focus score.
- Fz focus is the 4–8 Hz level during serial 7, divided by the same level during the eyes-open stare. Above 1 means that slower frontal rhythm was stronger while subtracting than while staring. This number is stored on the session index as
fz_theta_ratio. - Engagement is beta (13–30 Hz) divided by alpha (8–12 Hz) plus theta (4–8 Hz), at Fz. The report shows it for the stare and for serial 7. On this task it usually falls when theta rises. It is a rhythm ratio, not a clinical measure of attention.
- Theta/beta is theta divided by beta at Fz, again for the stare and for serial 7. It usually rises on the same runs where Fz focus is above 1.
Engagement and theta/beta are calculated when diy-eeg-report is built beside the recording. The chart buttons draw the serial-7 level. The stare level for the selected session is written under the picker. The spectrum view shades the same three bands: theta 4–8 Hz, alpha 8–12 Hz, and beta 13–30 Hz. A dotted line is the serial-7 minute.
Documentation/session-report.html is the same page with made-up points and no waveform. To write it again:
diy-eeg-report --example --out Documentation/session-report.htmlThis repository is licensed under GNU GPL v3.0.