Open Source Headunit Interface for Automotive Systems
A modern, minimalist car headunit interface built with React and Node.js. Control your car's hardware, connect your phone via Bluetooth, stream music, and more - all through a beautiful, touch-friendly interface.
- Full Audio Streaming: Stream music from your phone to your car's speakers via A2DP
- Media Controls: Play, pause, skip tracks directly from the interface
- Live Metadata: View song title, artist, album, and playback progress in real-time
- AVRCP Support: Full integration with your phone's media apps (Spotify, Apple Music, etc.)
- Linux Focused: Built and optimized for Linux-based systems (via BlueZ).
- Device Discovery: Scan for nearby Bluetooth devices with live updates
- Pairing & Connection: Easy device pairing and connection management directly from the app
- Native Platform Support: BlueZ/D-Bus on Linux.
- Device Information: View connection status, device type, signal strength, and last seen
- Smart Device Detection: Automatically identifies phones, headphones, speakers, and more
- History Tracking: Monitor all Bluetooth operations with detailed logs
- No System Settings Required: Complete device management without leaving the app!
- Hardware Pin Control: Control GPIO pins on Raspberry Pi and similar devices
- Multiple Modes: Support for INPUT, OUTPUT, and PWM modes
- Real-time Monitoring: Live status updates for all configured pins
- PWM Support: Control LED brightness, motor speeds, and more
- Command History: Track all GPIO operations for debugging
- Minimalist Black Theme: High-contrast design optimized for automotive use
- Touch-Friendly: Large buttons and controls designed for gloves and on-the-go use
- Responsive Layout: Adapts to different screen sizes and orientations
- Bottom Navigation: Quick access to all major features
- No Scrolling: All content fits on screen for safe driving
Clean, organized home screen with quick access cards for all major features.
Beautiful media player with album art placeholder, progress bar, and playback controls.
Comprehensive Bluetooth management with device scanning, pairing, and connection.
Intuitive GPIO pin control with real-time status indicators.
- Node.js v16 or higher
- npm v7 or higher
- Bluetooth adapter (built-in or USB)
- Optional: Raspberry Pi or similar for GPIO functionality
# Clone the repository
git clone https://github.com/yourusername/NodeNav.git
cd NodeNav
# Install dependencies
npm install
# Start the backend server
cd src
node server.js
# In another terminal, start the frontend
npm run devThe application will be available at http://localhost:5173
On Windows and macOS, the application runs in a GUI-only testing mode. Hardware-related features like Bluetooth and GPIO control are disabled. This is useful for developing and testing the user interface without requiring a Linux environment.
NEW: Full native Bluetooth device management! Connect to devices directly from the app using BlueZ/D-Bus - no system settings required!
- Ensure BlueZ is running:
sudo systemctl start bluetooth
sudo systemctl enable bluetooth- Set up D-Bus permissions (choose one):
Option A: Quick testing (run with sudo)
sudo npm run electron-devOption B: Production setup (recommended)
# Add yourself to bluetooth group
sudo usermod -a -G bluetooth $USER
# Or create D-Bus policy file (see LINUX_BLUETOOTH_GUIDE.md)- For Bluetooth audio streaming, run the automated setup:
chmod +x setup-bluetooth-audio.sh
./setup-bluetooth-audio.sh-
Log out and back in for permissions to take effect
-
Start NodeNav and discover/pair/connect devices in Settings → Bluetooth
Requirements:
- BlueZ 5.50+ (pre-installed on most distros)
- D-Bus (pre-installed)
- PulseAudio 10.0+ or PipeWire 0.3+ (for audio streaming)
Detailed Guides:
- LINUX_BLUETOOTH_GUIDE.md - Device management (NEW!)
- BLUETOOTH_AUDIO_SETUP.md - Audio streaming setup
For GPIO functionality on Raspberry Pi:
# The backend will automatically detect GPIO availability
# No additional setup requiredNote: GPIO functionality requires running on compatible hardware.
-
Pair Device (one-time setup):
- Navigate to Settings → Bluetooth
- Click Start Scanning
- Select your phone from the list
- Click Pair and accept on your phone
- Click Connect
-
Stream Music:
- Navigate to Media Player
- Play music on your phone
- Audio will stream to your computer/car speakers
- Control playback from NodeNav
- Navigate to GPIO Control
- Select a pin to configure
- Choose mode (INPUT, OUTPUT, PWM)
- Toggle or set values as needed
- View command history in the log panel
Use the bottom navigation bar to quickly switch between:
- Home: Quick access to all features
- GPIO Control: Hardware pin management
- Navigation: GPS routing (coming soon)
- Media: Bluetooth audio player
- Settings: System configuration
┌─────────────────────────────────────────────────────────┐
│ Frontend (React) │
│ ┌──────────────┬──────────────┬──────────────┐ │
│ │ MediaPlayer │ BluetoothUI │ GPIOControl │ │
│ └──────┬───────┴──────┬───────┴──────┬───────┘ │
│ └──────────────┼──────────────┘ │
│ │ API Service │
└────────────────────────┼─────────────────────────────────┘
│ HTTP/REST API
┌────────────────────────┼─────────────────────────────────┐
│ Backend (Express + Node.js) │
│ ┌──────────────┬──────────────┬──────────────┐ │
│ │ Bluetooth │ GPIO │ API │ │
│ │ Audio │ Service │ Endpoints │ │
│ │ Service │ │ │ │
│ └──────┬───────┴──────┬───────┴──────┬───────┘ │
└─────────┼──────────────┼──────────────┼─────────────────┘
│ │ │
┌─────────┼──────────────┼──────────────┼─────────────────┐
│ │ │ │ │
│ Bluetooth GPIO Pins System APIs │
│ Hardware │
│ │
└──────────────────────────────────────────────────────────┘
Frontend:
- React 19
- Vite (build tool)
- Tailwind CSS 4 + @tailwindcss/vite
- HeroUI React components
- Lucide React icons
Backend:
- Node.js
- Express (REST API)
- CORS middleware
Platform Integration:
- Linux: BlueZ (D-Bus API) + PulseAudio/PipeWire
- GPIO: Native GPIO libraries (Raspberry Pi)
NodeNav/
├── src/
│ ├── App.jsx # Main application component
│ ├── main.jsx # Entry point
│ ├── style.css # Global styles
│ ├── styles.js # Centralized style definitions
│ │
│ ├── components/ # Reusable UI components
│ │ ├── HomeScreenCard.jsx
│ │ ├── NavigationItem.jsx
│ │ └── SettingsButton.jsx
│ │
│ ├── pages/ # Main page components
│ │ ├── BluetoothSettings.jsx
│ │ ├── GPIOControl.jsx
│ │ └── MediaPlayer.jsx
│ │
│ ├── services/ # Backend services
│ │ ├── api.js # Frontend API client
│ │ ├── bluetooth-service.js # Bluetooth device management (platform router)
│ │ ├── bluetooth-device-linux.js # Linux Bluetooth (BlueZ/D-Bus) - NEW!
│ │ ├── bluetooth-audio-service.js # Audio streaming (platform router)
│ │ ├── gpio-service.js # GPIO control
│ │ └── server.js # Express backend server
│ │
├── docs/ # Documentation
│ ├── BLUETOOTH_AUDIO_SETUP.md
│ ├── BLUETOOTH_AUDIO_IMPLEMENTATION.md
│ ├── LINUX_BLUETOOTH_GUIDE.md
│ └── LINUX_BLUETOOTH_IMPLEMENTATION.md
│
├── setup-bluetooth-audio.sh # Linux setup script
├── package.json
├── vite.config.js
├── tailwind.config.js
└── README.md
# Terminal 1: Backend server with hot reload
cd src
node server.js
# Terminal 2: Frontend with hot reload
npm run dev# Build frontend
npm run build
# Preview production build
npm run preview
# Start production server
npm run startnpm run dev- Start Vite dev servernpm run build- Build for productionnpm run preview- Preview production buildnpm run electron- Run Electron appnpm run electron-dev- Run Electron in dev modenpm start- Build and run Electron app
Audio doesn't stream to computer:
- Ensure device is connected (not just paired)
- Check system audio output settings
- Verify Bluetooth audio profile is set to A2DP sink
Controls don't work:
- Some apps have limited AVRCP support
- Try Spotify or Apple Music (excellent support)
- YouTube has limited Bluetooth control support
No metadata showing:
- Ensure music is actively playing
- Try a different music app
- Some streaming apps don't broadcast metadata
Pins not responding:
- Check if running on compatible hardware
- Verify GPIO permissions (user in
gpiogroup on Linux) - Ensure no other process is using the pins
- Linux Bluetooth: See LINUX_BLUETOOTH_GUIDE.md - NEW! Complete device management
- Linux Audio: See BLUETOOTH_AUDIO_SETUP.md
- Implementation Details:
- Bluetooth device management
- Bluetooth audio streaming (A2DP)
- Media playback control (AVRCP)
- Live track metadata
- GPIO pin control
- Minimalist UI theme
- Cross-platform support (Linux-first)
- Album artwork display
- Playlist/queue management
- Audio equalizer
- Volume control integration
- Podcast-specific features
- GPS integration
- Turn-by-turn navigation
- OpenStreetMap integration
- Route planning
- Traffic updates
- Multiple Bluetooth device support
- Automatic device reconnection
- Phone call integration
- SMS/notification display
- Voice assistant integration
- Backup camera integration
- OBD-II diagnostics
- Steering wheel control support
- Theme customization
- Screen brightness control
- Gesture controls
- Widget system
- Multi-language support
Contributions are welcome! Here's how you can help:
- Fork the repository
- Create a feature branch:
git checkout -b feature/AmazingFeature - Commit your changes:
git commit -m 'Add some AmazingFeature' - Push to the branch:
git push origin feature/AmazingFeature - Open a Pull Request
- Follow existing code style and conventions
- Add comments for complex logic
- Update documentation for new features
- Test on both Windows and Linux if possible
- Keep the UI minimalist and touch-friendly
This project is licensed under the ISC License. See the LICENSE file for details.
AJ Frio
- GitHub: @AJFrio
- BlueZ Project - Linux Bluetooth stack
- PulseAudio/PipeWire - Audio routing on Linux
- React Team - Amazing UI framework
- Vite Team - Lightning-fast build tool
- Tailwind CSS - Utility-first CSS framework
- Lucide - Beautiful icon set
- Electron - Cross-platform desktop apps
- Main README - This file
- Linux Bluetooth Guide - NEW! Device management on Linux
- Linux Bluetooth Implementation - NEW! Technical details
- Bluetooth Audio Setup (Linux)
- Bluetooth Audio Implementation Details
- Report a Bug: GitHub Issues
- Request a Feature: GitHub Issues
- Discussions: GitHub Discussions
- DIY Car Headunit: Replace factory headunit with Raspberry Pi
- Classic Car Modernization: Add modern features to older vehicles
- Development/Testing: Test automotive applications
- Learning Platform: Learn automotive software development
- Home Automation Hub: Repurpose as a control center
- Startup Time: < 3 seconds
- UI Response: Instant (React optimizations)
- Bluetooth Commands: 20-50ms on Linux
- Metadata Updates: Every 2 seconds
- Audio Latency: 100-300ms (Bluetooth standard)
- No external API calls for media streaming
- Local-only Bluetooth connections
- No cloud services required
- All data stays on your device
- Open source - audit the code yourself
| Feature | Linux | macOS | Raspberry Pi | Windows 10/11 |
|---|---|---|---|---|
| Media Player | Full | GUI Only | Full | GUI Only |
| Bluetooth Device Mgmt | Native (NEW!) | GUI Only | Native | GUI Only |
| Bluetooth Audio | Full | GUI Only | Full | GUI Only |
| GPIO | Full | N/A | Full | N/A |
| UI | Full | Full | Full | Full |
Need help? Here's how to get support:
- Check the documentation in the
docs/folder - Search existing issues on GitHub
- Ask in discussions for general questions
- Open an issue for bugs or feature requests
Made with love for the automotive community
Star this repo if you find it useful!