Emmanuel

God with us. Neurofeedback that trains the stillness where prayer begins.

Emmanuel (Hebrew ʿImmanu-El, "God with us", Isaiah 7:14) is about becoming still before God. It pairs a consumer brain headband, Mendi (fNIRS) or BrainAccess HALO (EEG), with practices that settle and steady attention, the kind that meditation and contemplative prayer cultivate, and gives honest live feedback on them. God is already with us; the practice helps us notice. Emmanuel trains attention and calm. It does not promise spiritual experiences, and it is not a medical device.

This repository holds the app and the desktop server it grew from.

The app (web/)

Emmanuel runs in the browser as an installable Progressive Web App for both headbands, each over Web Bluetooth and each with a simulator, with no server needed. You choose the band at the top of the app. Inside it:

• a focus training modelled on Mendi's default one (an orb riding the activity curve, points, control, day score and streak);
• the hemispheric balance trainer;
• exercise cards: 32 printable brain-training cards (checked against the original photos) to do on paper with the band recording, and 10 games made from them for two screens — the board shows the cue, a phone or tablet is the touch pad — with speed, accuracy, levels and every session kept (design);
• three training games for either band — Geode (a Block Blast-style puzzle whose crystals grow with steady focus), Lighthouse Keeper (a one-tap lighthouse game: focus stretches the beam, calm lights the sea) and Butterfly House (a caterpillar's path becomes a unique butterfly) — each session a full neurofeedback session (design and research);
• two Christian games, run inside the app on the band that is already connected (in Polish);
• live signal views, sessions in IndexedDB or a local folder, and where to get each headband.

It speaks Polish, English, German and Swedish, works offline, and keeps everything on the device. It runs in Chrome/Edge/Opera on Windows, macOS, Android and ChromeOS, and on iOS through the Bluefy browser. See web/README.md and web/DESIGN.md (§10 languages, §11 the name and its message).

cd web && npm ci && npm run dev

HolyHolyHoly (web/game/) is a Christian action game that can use the Mendi band for prefrontal-cortex training — see web/game/DESIGN.md. HolyHolyHoly 3D: Archaniołowie (web/game3d/) is its 3D reinterpretation made with the GDevelop engine: seven archangels, a man's or a woman's story in today's Poland, Christ in the healing scenes, and real CBT skills — see web/game3d/README.md.

Desktop server

A self-contained desktop application that processes BrainAccess HALO EEG data and Mendi fNIRS data (or simulated data for either) and exposes game-ready brain metrics in real time over WebSocket and a REST API. Its dashboards (/ for HALO, /fnirs for Mendi) share a HALO · EEG | Mendi · fNIRS switch in their top bar. The Python package keeps the project's first name, brainlink.

Emmanuel-brain-bluetooth-integration/
├── run.py              ← One-command launcher (creates venv, installs deps, starts server)
├── server.py           ← FastAPI app — routes + background EEG loop
├── brainlink/          ← Core pipeline package
│   ├── constants.py    ← Shared constants (sample rate, bands, channels, …)
│   ├── simulator.py    ← EEG simulator with mental-state scenarios
│   ├── dsp.py          ← Ring buffers + band-power extraction (Welch PSD)
│   ├── features.py     ← Metric engine + combo detector
│   ├── calibration.py  ← Guided calibration session
│   ├── recorder.py     ← CSV + JSON session recorder
│   ├── halo_ble.py     ← macOS BLE adapter (bleak / CoreBluetooth)
│   ├── halo_sdk.py     ← Official SDK adapter (Windows / Linux)
│   ├── mendi_proto.py  ← Mendi V4 protobuf codec (no protobuf dependency)
│   ├── mendi_ble.py    ← Mendi fNIRS BLE adapter (bleak)
│   ├── fnirs.py        ← fNIRS pipeline: ambient → ΔOD → MBLL → ΔHbO/ΔHbR, HR, SCI
│   ├── fnirs_simulator.py ← Mendi-like frame simulator (block-design scenarios)
│   ├── fnirs_balance.py   ← Hemispheric balance tracker (trainer view)
│   ├── fnirs_recorder.py  ← fNIRS CSV recorder with event markers
│   ├── fnirs_api.py    ← /api/v1/fnirs/* router + WebSocket + loop
│   └── duo_api.py      ← /api/v1/duo/* LAN relay for two-screen games + the /app/ web app route
├── dashboard/
│   ├── index.html      ← Real-time EEG dashboard
│   ├── fnirs.html      ← Real-time fNIRS dashboard (/fnirs, /fnirs#balance)
│   └── fnirs-balance.js ← Balance trainer view + task bank
├── tests/              ← pytest suite (no hardware needed)
├── web/                ← Emmanuel, the web app (PWA) for Mendi + HALO: Web Bluetooth, offline, no server needed
├── recordings/         ← Saved EEG sessions (gitignored)
├── requirements.txt
├── requirements-dev.txt ← pytest, httpx, protobuf (tests only)
└── LICENSE

Quick start

python run.py

The launcher will:

1. Create a Python virtual environment (.venv/)
2. Install all dependencies from requirements.txt
3. Start the server on port 8420
4. Open your browser to the dashboard

python run.py --port 9000    # custom port
python run.py --no-open      # skip auto-opening browser
python run.py --install      # install deps only

Requirements

• Python 3.10+
• No other manual setup required — everything is installed automatically

This is the beginning of the README. Read the rest at the original. Read the full README ↗