🎵 XL2 Web Server

A modern Node.js web application that provides a real-time web interface for the NTI Audio XL2 Sound Level Meter. Monitor sound measurements, GPS location tracking, and data logging through an intuitive web dashboard with automatic path tracking.

✨ Features

🎯 Core Functionality

Real-time Sound Monitoring: Live FFT spectrum measurements with dynamic frequency bands
GPS Integration: Position tracking with VK-162 or compatible GPS modules
FFT Spectrum Analysis: Real-time frequency spectrum visualization (12.5-64.5 Hz)
XL2 CSV Format: German-format CSV logging with exact XL2 frequency bands
Automatic Path Tracking: GPS path tracking starts/stops automatically with logging
Interactive Maps: Real-time GPS tracking with Leaflet maps
Multi-client Support: Multiple users can connect simultaneously

🖥️ Cross-Platform Support

Windows: Native COM port handling with auto-detection
Raspberry Pi: Optimized for Pi 3B+, Pi 4, and Pi 5
Linux: Full Unix serial port compatibility
macOS: Compatible with USB-to-serial adapters

🔧 Advanced Features

Auto-device Detection: Automatically finds XL2 and GPS devices
Dynamic Frequency Bands: Uses actual frequency bands from XL2 device (MEAS:FFT:F?)
Server-Sent Events: Low-latency real-time updates via SSE
German CSV Format: Semicolon-separated values with comma decimal points
Security: CORS protection, rate limiting, and helmet security
Service Installation: Run as Windows Service or Linux daemon

🚀 Quick Start

Windows (Recommended)

# Clone the repository
git clone <repository-url>
cd XL2ParseNew

# Run automated installation
.\install-windows.ps1

# Start the server
npm start

Raspberry Pi (Automated)

# Clone the repository
git clone <repository-url>
cd XL2ParseNew

# Run automated installation
chmod +x install-raspberry-pi.sh
./install-raspberry-pi.sh

# Optional: Install as system service
./install-raspberry-pi.sh --install-as-service

Raspberry Pi (Manual)

# Install Node.js 18.x
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install dependencies
npm install

# Start the server
npm start

Manual Installation (All Platforms)

# Install dependencies
npm install

# Start development server
npm run dev

# Or start production server
npm start

📋 Prerequisites

Software Requirements

Node.js 18.x or later (Download)
npm (included with Node.js)

Dependencies

express: ^4.18.2 - Web server framework
serialport: ^12.0.0 - Serial device communication
gps: ^0.6.1 - GPS data parsing
csv-writer: ^1.6.0 - CSV file generation
compression: ^1.7.4 - HTTP response compression
helmet: ^7.0.0 - Security middleware
cors: ^2.8.5 - Cross-origin resource sharing
express-rate-limit: ^7.5.1 - API rate limiting
dotenv: ^17.2.1 - Environment variable management

Hardware Requirements

NTI Audio XL2 Sound Level Meter with USB connection
GPS Module (optional): VK-162 or compatible USB GPS receiver
Computer: Windows 10+, Raspberry Pi 3B+, or Linux system
USB Ports: For XL2 device and GPS module

Minimum System Specs

RAM: 4GB (8GB recommended)
CPU: 2 cores (4 cores recommended)
Storage: 1GB free space
Network: For web interface access

⚙️ Configuration

Environment Variables

Create a .env file in the project root:

# Server Configuration
PORT=3000
NODE_ENV=development

# GPS Serial Port Configuration
GPS_SERIAL_PORT=COM4          # Windows: COM1, COM2, etc.
GPS_AUTO_CONNECT=true         # Auto-detect GPS device

# XL2 Serial Port Configuration
XL2_SERIAL_PORT=COM3          # Windows: COM1, COM2, etc.
XL2_AUTO_DETECT=true          # Auto-detect XL2 device

# System Monitoring
SYSTEM_MONITORING_ENABLED=true
FILE_LOGGING_ENABLED=true

Device Detection

The application automatically detects connected devices:

Windows: Scans COM1-COM20 for XL2 and GPS devices
Linux/Pi: Scans /dev/ttyUSB* and /dev/ttyACM* ports
Manual Override: Specify exact ports in .env file

🔌 Device Connections

XL2 Audio Analyzer

Connect XL2 device via USB cable
Install drivers if prompted (usually automatic)
Device appears as serial port (COM port on Windows)
Application auto-detects and connects
FFT Configuration: Application automatically configures XL2 for FFT mode:
- MEAS:FUNC FFT - Set to FFT measurement mode
- MEAS:FFT:ZOOM 9 - Set zoom level
- MEAS:FFT:FSTART 12.5 - Set start frequency to 12.5 Hz
- MEAS:FFT:F? - Query actual frequency bands (145 bands: 12.50-64.50 Hz)

GPS Module (Optional)

Connect VK-162 or compatible GPS module
Install drivers if needed
Application auto-detects GPS NMEA data
Position tracking begins automatically

Troubleshooting Connections

# Check available ports
npm run port-info

# Test GPS connection
node tools/test-gps.js

# View device information
# Windows: Device Manager → Ports (COM & LPT)
# Linux: ls -la /dev/ttyUSB*

🌐 Web Interface

Access the web dashboard at: http://localhost:3000

Dashboard Features

Live Measurements: Real-time FFT spectrum display with 145 frequency bands
GPS Map: Interactive Leaflet map with automatic path tracking
FFT Spectrum: Real-time frequency analysis visualization (12.5-64.5 Hz)
Data Export: Download XL2-compatible CSV files with German formatting
System Status: Device connection and system health monitoring
Automatic Logging: Path tracking starts/stops automatically with data logging

Multi-Device Access

Local Network: http://YOUR-IP:3000
Mobile Devices: Responsive design for tablets/phones
Multiple Clients: Support for concurrent users via Server-Sent Events

📊 Data Logging

XL2-Compatible CSV Format

The application generates CSV files in the exact format used by the XL2 device:

Datum Zeit;Lat;Long;At;Sat;Fix;12.50 Hz;12.87 Hz;13.23 Hz;...;64.50 Hz
12.08.2025 23:14:14;54,160031;9,852432833;25,6;6;1;36,1;36,4;39,1;...

Key Features

German Format: Semicolon separators, comma decimal points
Dynamic Frequency Bands: Uses actual frequency bands from XL2 device (MEAS:FFT:F?)
145 Frequency Columns: Complete spectrum from 12.50 Hz to 64.50 Hz
GPS Integration: Latitude, longitude, altitude, satellites, and fix quality
Automatic Path Tracking: GPS path recording tied to logging status

Logging Features

Automatic Logging: Continuous data capture when logging is active
XL2 Compatibility: Files can be imported into XL2 analysis software
GPS Integration: Location data synchronized with measurements
Real-time Updates: Live path tracking on interactive map
File Management: Single log file with append functionality

🛠️ Development

Project Structure

XL2ParseNew/
├── src/
│   ├── config/          # Configuration management
│   ├── devices/         # XL2 and GPS device handlers
│   ├── routes/          # Express API routes
│   ├── services/        # Business logic services (SSE, CSV)
│   └── utils/           # Utility functions
├── public/              # Web interface files
│   ├── js/              # Client-side JavaScript
│   ├── css/             # Stylesheets
│   └── index.html       # Main web interface
├── tools/               # Development and testing tools
├── server.js            # Main application entry point
└── package.json         # Project dependencies

Available Scripts

npm start                    # Start production server
npm run dev                  # Start with auto-reload (nodemon)
npm run port-info           # List available serial ports
npm run install-windows     # Windows installation script
npm run install-windows-service # Install as Windows service

API Endpoints

GET /api/status - System and device status
GET /api/xl2/fft-frequencies - Get XL2 frequency bands
GET /api/gps/location - Current GPS position
GET /api/csv/export - Download CSV data
GET /events - Server-Sent Events stream for real-time updates

🔧 Platform-Specific Setup

Windows

Automated Setup: Use install-windows.ps1
Service Installation: Run as Windows Service
COM Port Detection: Automatic scanning
Firewall: Configure for network access
Detailed Guide: See README-Windows.md

Raspberry Pi

Optimized Performance: Pi-specific configurations
USB Permissions: Automatic setup for serial devices
System Service: Auto-start on boot
Hardware Support: Pi 3B+, Pi 4, Pi 5, Pi Zero 2W
Detailed Guide: See raspberry-pi-setup.md

Linux/Unix

Serial Permissions: Add user to dialout group
Device Detection: /dev/ttyUSB* and /dev/ttyACM*
Service Installation: systemd service files
Package Management: Standard npm installation

🔐 Security

Built-in Security Features

CORS Protection: Configurable origin restrictions
Rate Limiting: Prevent API abuse (express-rate-limit)
Helmet Security: HTTP security headers
Input Validation: Sanitized user inputs
Error Handling: Secure error responses
Compression: HTTP response compression for performance

Network Security

# Restrict to localhost only
HOST=127.0.0.1

# Allow specific origins
CORS_ORIGINS=http://localhost:*,http://192.168.1.*

# Enable HTTPS (production)
HTTPS_ENABLED=true
SSL_CERT_PATH=/path/to/cert.pem
SSL_KEY_PATH=/path/to/key.pem

📈 Performance

System Requirements by Usage

Light Usage (1-2 clients)

RAM: 4GB
CPU: 2 cores
Network: Basic home network

Medium Usage (3-10 clients)

RAM: 8GB
CPU: 4 cores
Network: Gigabit recommended

Heavy Usage (10+ clients)

RAM: 16GB+
CPU: 8+ cores
Network: Enterprise network

Optimization Tips

Raspberry Pi: Use Pi 4 with 4GB+ RAM for best performance
Windows: Set power plan to "High Performance"
Network: Use wired connection for stable GPS/XL2 data
Storage: SSD recommended for data logging

🐛 Troubleshooting

Common Issues

Device Not Found

# Check connected devices
npm run port-info

# Verify USB connections
# Windows: Device Manager
# Linux: lsusb && ls -la /dev/ttyUSB*

Permission Denied

# Linux: Add user to dialout group
sudo usermod -a -G dialout $USER
# Logout and login again

# Windows: Run as Administrator if needed

Port Already in Use

# Change port in .env file
PORT=3001

# Or find and stop conflicting process
# Windows: netstat -ano | findstr :3000
# Linux: lsof -i :3000

Debug Mode

# Enable verbose logging
DEBUG=xl2:* npm start

# Check log files
tail -f logs/xl2-server.log

📚 Documentation

Windows Setup Guide - Detailed Windows installation
Raspberry Pi Setup - Pi-specific configuration
API Documentation - REST API reference
Server-Sent Events - Real-time communication via SSE

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Development Setup

# Clone your fork
git clone <your-fork-url>
cd XL2ParseNew

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests (if available)
npm test

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

NTI Audio for the XL2 Sound Level Meter
Node.js Community for excellent serial port libraries
Open Source Contributors who made this project possible

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Check the docs/ directory
Email: [Your contact email]

🎯 Quick Start Checklist

Node.js 18.x installed
Project cloned/downloaded
Dependencies installed (npm install)
XL2 device connected via USB
GPS module connected (optional)
Environment configured (.env file)
Server started (npm start)
Web interface accessed (http://localhost:3000)
Device connections verified

🎉 Ready to monitor sound levels with XL2 Web Server!

For platform-specific instructions, see the detailed setup guides for Windows and Raspberry Pi.

Name		Name	Last commit message	Last commit date
.zencoder/rules		.zencoder/rules
public		public
src		src
tools		tools
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
INSTALL.md		INSTALL.md
LICENSE		LICENSE
README-Windows.md		README-Windows.md
README.md		README.md
install-raspberry-pi.sh		install-raspberry-pi.sh
install-service.js		install-service.js
install-windows.ps1		install-windows.ps1
jsconfig.json		jsconfig.json
package-lock.json		package-lock.json
package.json		package.json
raspberry-pi-setup.md		raspberry-pi-setup.md
server.js		server.js

Latest commit

History

Folders and files

Repository files navigation