Skip to main content

​
Getting Started

This guide walks you through setting up NeuroFocus V4 from scratch.

​
Prerequisites

​
Hardware

  • Seeed Studio Xiao ESP32-S3
  • NeuroFocus V4 PCB
  • USB-C cable
  • EEG electrodes (Ag/AgCl recommended)

​
Software

  • PlatformIO IDE (VS Code extension) or PlatformIO CLI
  • Git (for cloning the repository)

​
Installation Steps

​
1. Install PlatformIO

Option A: VS Code (Recommended)
  1. Install VS Code
  2. Open VS Code Extensions (Ctrl+Shift+X)
  3. Search for “PlatformIO IDE”
  4. Click Install
Option B: Command Line 
pip install platformio

​
2. Clone the Repository

git clone https://github.com/da-bigbrain/neurofocus.git
cd neurofocus/firmware/v4

​
3. Configure Communication Mode

Open src/config.h and set your communication mode: 
// For BLE mode (default)
#define ENABLE_BLE 1

// For Serial-only mode
#define ENABLE_BLE 0
BLE Mode is best for:
  • Wireless data collection
  • Mobile app integration
  • Remote monitoring
Serial Mode is best for:
  • Development and debugging
  • Direct USB connection
  • Smaller firmware size

​
4. Build the Firmware

pio run
This compiles the code. Look for “SUCCESS” in the output.

​
5. Connect Your Device

  1. Connect ESP32-S3 to your computer via USB-C
  2. The device should appear as a serial port
Check connection: 
pio device list

​
6. Upload Firmware

pio run --target upload
Wait for the upload to complete. The LED will blink during the process.

​
7. Monitor Serial Output

pio device monitor
You should see: 
EEG Interface - Initializing...
BLE initialized as NEUROFOCUS_V4
BLE advertising started
Ready. Commands: 'b'=start, 's'=stop, 'v'=reset
BLE: NEUROFOCUS_V4

​
Using the System

​
Serial Commands

Send these commands via Serial Monitor:
CommandAction
bStart streaming
sStop streaming
vReset device

​
BLE Connection

On Computer (Linux): 
# Scan for devices
bluetoothctl scan on

# Connect to NEUROFOCUS_V4
bluetoothctl connect XX:XX:XX:XX:XX:XX
On Mobile: Use a BLE scanner app to find “NEUROFOCUS_V4” and connect.

​
Start Streaming

  1. Attach electrodes to your scalp
  2. Send command b via Serial or BLE
  3. Data will stream as raw ADC values
Example output: 
12543221
12545009
12543891
Each line is a 24-bit signed integer from the ADS1220.

​
Hardware Setup

​
Electrode Placement

For basic testing:
  • Channel+: Forehead (Fp1 or Fp2 position)
  • Channel-: Behind ear (mastoid)
  • Reference: Opposite mastoid or forehead
Clean skin with alcohol before applying electrodes.

​
Power

The board can run from:
  • USB power (5V)
  • Battery connected to BAT pins (3.7V LiPo)

​
Troubleshooting

​
ADS1220 Init Failed

Problem: “ADS1220 init failed! Check connections.” Solutions:
  • Check SPI wiring between ESP32 and ADS1220
  • Verify 3.3V power supply
  • Try power cycling the board

​
BLE Not Advertising

Problem: Can’t find NEUROFOCUS_V4 in BLE scan Solutions:
  • Check ENABLE_BLE is set to 1 in config.h
  • Rebuild and upload firmware
  • ESP32-S3 must support BLE (some clones don’t)

​
No Serial Output

Problem: Serial monitor shows nothing Solutions:
  • Check baud rate is set to 115200
  • Try different USB cable
  • Press reset button on ESP32

​
Noisy Signal

Problem: Data values jump around a lot Solutions:
  • Check electrode contact (use conductive gel)
  • Keep away from AC power lines
  • Use shorter electrode wires
  • Enable 50/60Hz filter in firmware

​
Next Steps

Now that your system is running:

​
Communication Modes

​
Switching Modes

Edit src/config.h: 
#define ENABLE_BLE 1  // Change to 0 for Serial only
Then rebuild and upload: 
pio run --target upload

​
BLE Auto-Start

When BLE is enabled, streaming starts automatically when a client connects. It stops when the client disconnects.

​
Serial Manual Control

In Serial mode, you control streaming with commands. Nothing happens automatically.

​
Building from Source

​
Project Structure

firmware/v4/
├── src/
│   ├── main.cpp              # Entry point
│   ├── config.h              # Configuration
│   ├── ads1220_driver.*      # ADC driver
│   ├── ble_manager.*         # BLE communication
│   ├── eeg_streamer.*        # Data streaming
│   ├── command_handler.*     # Command processing
│   └── led_controller.*      # LED control
├── platformio.ini            # PlatformIO config
└── README.md

​
Dependencies

All dependencies install automatically through PlatformIO:
  • ESP32 Arduino framework
  • ADS1220_WE library
  • ESP32 BLE Arduino library

​
Custom Board Configuration

If using a different ESP32 board, edit platformio.ini: 
[env:seeed_xiao_esp32s3]
platform = espressif32
board = seeed_xiao_esp32s3
framework = arduino
Change board to match your hardware.