Turn head movements from your EMOTIV headset into keys on your PC — so you can move in games or apps using W, A, S, D (or keys you choose) without touching the keyboard.
A small window shows what the app thinks you are doing (forward, back, left, right). The on-screen text is Italian; you do not need to change anything for that.
Motion reticle — Main canvas: fixed center cross, aim square frame, optional threshold tint bands, and the live head-tilt position marker (teal square); speech shorthand: reticle; legacy/doc synonym: crosshair.
Movement pad — Four directional tiles (forward, left, backward, right) that highlight when that movement is active; speech shorthand: pad; code already uses create_movement_pad / D-pad comments.
Synonyms (optional one-liners)
Tilt reticle — Same widget as motion reticle when you want to stress Cortex mot / pitch–roll rather than abstract “movement.”
Direction pad — Same as movement pad; slightly more generic label.
Aim HUD — Informal short label for the motion reticle; less precise than reticle.
Note: Pad highlighting follows active movement (tilt / mental-command mapping), not the user’s physical keyboard key events; simulated key output is separate.
- An EMOTIV headset that works with EMOTIV Cortex (Launcher + Cortex installed on your computer, headset paired and visible in Cortex).
- Windows is what this app is built for first. Other systems might work but are not the main focus.
- An EMOTIV developer account so you can get the Client ID and Client Secret Cortex asks for (the app needs these once to connect).
- Put the file somewhere you like (for example your Desktop or a folder you use for games).
- Run EMOTIV Launcher and Cortex, and connect your headset.
- Double-click the app. Enter your Client ID and Client Secret when the app asks (or in Settings), if you have not already.
- Follow the steps inside the app: wait until it says it is connected, then calibrate your “neutral” head position when prompted.
- Turn keyboard simulation on when you want keys to be sent to your game or app. You can turn it off anytime to test without sending keys.
Updates: If your build supports it, use Check for updates under Settings after releases are published.
You need Python 3 (3.10 through 3.13 recommended on Windows for the Toga WinForms stack; 3.14 may require a prerelease pythonnet). Open a terminal in the python folder, create a virtual environment, install dependencies, then start the app:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python run.pyThe window is built with BeeWare Toga (native controls on Windows). Always run commands from this python folder so it finds config.json (run.py adds src to the import path). Cortex connection fields (URL, streams, client id/secret, license, debit) live in config.json with the rest of your settings.
- Start Cortex first and make sure the headset is connected before or right after you open the bridge.
- Calibrate “neutral” while sitting comfortably straight — later movements are compared to that pose.
- If movement feels too sensitive or too weak, open Settings and adjust the sensitivity / thresholds until it feels right.
- Keyboard off is useful while you learn the app: you see the directions on screen, but no keys are pressed.
- Quick shortcut (Windows): Ctrl+Shift+K turns keyboard simulation on or off. If another program already uses that, try Ctrl+Alt+K.
| What you notice | What to try |
|---|---|
| Will not connect | Cortex and Launcher running? Headset on? Client ID and Secret correct? |
| No movement | Calibrate again; lower the sensitivity threshold a little. |
| Mental commands do nothing | They must be trained in Cortex and enabled in your stream/settings; if you only care about head motion, you can ignore mental commands. |
| Keys do not reach the game | Turn on keyboard simulation; on some PCs, security software may ask for permission to “control” the keyboard — allow it if you trust this app. |
| Odd behavior | Start the app from this python folder (same place as run.py and your config files) so nothing is “lost.” |
Tests, packaging with PyInstaller, release workflows, and deeper behavior are described in PRD.md and in scripts/build.sh (comments at the top). CI runs scripts/ci-test.sh (pytest on Linux). Release automation lives under .github/workflows/.