A unified, high-performance desktop application for bridging HyperStudy web experiments with research hardware devices.
| Platform | Download |
|---|---|
| macOS (Apple Silicon) | Apple Silicon |
| macOS (Intel) | Intel |
| Windows | Windows Installer |
| Linux | Linux AppImage |
macOS builds are signed and notarized by Apple. Windows builds are unsigned (see note below).
HyperStudy Bridge provides a reliable, low-latency communication layer between the HyperStudy web application and various research devices including fNIRS, eye trackers, physiological sensors, and TTL pulse generators. Built with Tauri and Rust for maximum performance and minimal resource usage.
- High Performance: Sub-millisecond latency for time-critical operations
- Multi-Device Support: Simultaneous connection to multiple device types
- Auto-Reconnection: Resilient connection management with automatic recovery
- Real-Time Monitoring: Live status dashboard for all connected devices
- Secure: Local-only connections with sandboxed architecture
- Cross-Platform: macOS (primary), Windows, and Linux support
| Device | Type | Connection | Status |
|---|---|---|---|
| hyperstudy-ttl | TTL Pulse Generator | USB Serial | Supported |
| Kernel Flow2 | fNIRS | TCP Socket | Supported |
| Pupil Labs Neon | Eye Tracker | WebSocket | Supported |
| EyeLink 1000 Plus | Eye Tracker | Ethernet (TCP) | Supported* |
| Lab Streaming Layer | Various | LSL Protocol | Supported |
*Requires the SR Research EyeLink Developers Kit installed on the host machine.
- Download the appropriate
.dmgfor your Mac from the Download section above - Open the DMG and drag HyperStudy Bridge to Applications
- Launch from Applications folder
- Download the
.msiinstaller from the Download section above - Run the installer and follow the prompts
- Launch from the Start Menu
Note: Windows may show a SmartScreen warning on first run since the app is not signed. Click "More info" → "Run anyway" to proceed.
- Download the
.AppImagefrom the Download section above - Make it executable and run:
chmod +x HyperStudy-Bridge-*.AppImage ./HyperStudy-Bridge-*.AppImage
The EyeLink 1000 Plus integration requires the SR Research EyeLink Developers Kit:
- Download and install the EyeLink Developers Kit for your platform
- The bridge auto-detects the SDK at runtime — no special build flags needed
- If the SDK is not installed, the app runs normally; EyeLink operations return a clear error message
- Launch the Bridge: Start HyperStudy Bridge before your experiment
- Connect Devices: Click "Connect All" or configure individual devices
- Verify Status: Ensure all required devices show green status
- Start Experiment: The bridge will handle all device communication
# Clone the repository
git clone https://github.com/yourusername/hyperstudy-bridge.git
cd hyperstudy-bridge
# Install dependencies
npm install
# Install Rust dependencies
cd src-tauri
cargo build
cd ..# Run in development mode with hot-reload
npm run tauri dev# Run all tests
npm test
# Backend tests only
cd src-tauri && cargo test
# Frontend tests only
npm run test:frontend
# E2E tests
npm run test:e2e# Build for current platform
npm run tauri build
# Build for specific platform
npm run tauri build -- --target x86_64-apple-darwin┌─────────────────┐ WebSocket ┌──────────────┐
│ HyperStudy │◄──────:9000───────►│ Bridge │
│ Web App │ │ Server │
└─────────────────┘ └──────┬───────┘
│
┌─────────────────────┼─────────────────────┐
│ │ │
┌─────▼─────┐ ┌────▼────┐ ┌─────▼─────┐
│ TTL │ │ Kernel │ │ Pupil │
│ Serial │ │ TCP │ │ WS │
└─────┬─────┘ └────┬────┘ └─────┬─────┘
│ │ │
┌─────▼─────┐ ┌────▼────┐ ┌─────▼─────┐
│ TTL Device│ │ Flow2 │ │ Neon │
└───────────┘ └─────────┘ └───────────┘
Connect to ws://localhost:9000 and send JSON messages:
// Connect to device
{
"type": "command",
"device": "ttl",
"action": "connect",
"payload": { "port": "/dev/tty.usbmodem1234" }
}
// Send command
{
"type": "command",
"device": "ttl",
"action": "send",
"payload": { "command": "PULSE" }
}
// Receive data
{
"type": "data",
"device": "kernel",
"payload": { /* device-specific data */ },
"timestamp": 1634567890123
}See API Documentation for complete protocol specification.
Settings are stored in:
- macOS:
~/Library/Application Support/hyperstudy-bridge/ - Windows:
%APPDATA%\hyperstudy-bridge\ - Linux:
~/.config/hyperstudy-bridge/
Example configuration:
{
"bridge": {
"port": 9000,
"autoConnect": true
},
"devices": {
"ttl": {
"port": "/dev/tty.usbmodem1234",
"baudRate": 115200
},
"kernel": {
"ip": "192.168.1.100",
"port": 6767
}
}
}# Add user to dialout group (Linux)
sudo usermod -a -G dialout $USER
# Check port permissions (macOS)
ls -la /dev/tty.*# Find process using port 9000
lsof -i :9000
# Kill process if needed
kill -9 <PID>- Check device is powered on and connected
- Verify drivers are installed
- Try unplugging and reconnecting
- Check device appears in system (Device Manager/System Information)
See Troubleshooting Guide for more solutions.
| Metric | Target | Typical |
|---|---|---|
| TTL Latency | <1ms | 0.5ms |
| Message Throughput | >1000/sec | 1500/sec |
| Memory Usage | <100MB | 45MB |
| CPU Usage (idle) | <5% | 2% |
| Startup Time | <2sec | 1.2sec |
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
MIT License - see LICENSE file for details.
- Documentation: docs/
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- HyperStudy team for the core platform
- Tauri team for the excellent framework
- Device manufacturers for their APIs and documentation
- Core bridge architecture
- TTL pulse generator support
- Kernel Flow2 integration
- Pupil Labs Neon support
- Lab Streaming Layer support
- Auto-update system
- Device profiles and presets
- Data recording and playback
- Advanced diagnostics tools
Built for the research community