A robust Flask-based telemetry data processing API designed for motorsport and GPS tracking applications. Features integration with Traccar GPS server, real-time position processing, lap timing analysis, track management, and comprehensive session analytics with Docker deployment capabilities.
Note: This is V1.1 of the project and is designed to work specifically with V1.1 of the Telemetron WEB repository, available at: https://github.com/Santi-49/telemetron-web
Telemetron API (v1.1) is a production-ready telemetry data processing system that integrates with Traccar GPS tracking server to provide advanced motorsport analytics. The system processes GPS position data in real-time, calculates lap times, manages track configurations, and provides comprehensive session analysis. Built with Flask and featuring robust authentication, the API supports multiple racing tracks, device management, and detailed telemetry analytics.
- Real-time GPS Data Processing: Integration with Traccar GPS server for live position data
- Lap Time Analysis: Automatic lap detection and timing calculations
- Track Management: Create and manage racing track configurations with customizable checkpoints
- Session Analytics: Comprehensive session recording and analysis capabilities
- Multi-Device Support: Handle multiple GPS tracking devices simultaneously
- Position Data Storage: Efficient storage and retrieval of GPS coordinates, speed, and timing data
- JWT Authentication with token blacklisting for secure logout
- Role-based permission system (levels 0-5)
- User management capabilities (create, retrieve, update)
- Comprehensive logging system with IP tracking and country detection
- reCAPTCHA protection against brute force attacks
- Configurable theme preference for users (dark/light)
- Persistent database migrations using Docker volumes
- Checkpoint Detection: Automatic detection when vehicles cross track checkpoints
- Lap Classification: Categorize laps as Complete, Invalid, Outlap, Inlap, or Pitstop
- Speed Analysis: Track and analyze speed data throughout sessions
- Time Delta Calculations: Calculate sector times and lap time differences
- Background Job Processing: Asynchronous processing of large telemetry datasets
- Real-time Streaming: Server-sent events for live data updates
The application uses a modern, modular package structure optimized for telemetry data processing:
app/: Main application package__init__.py: Package initializationapi/: Core API modulesapp.py: Main Flask application entry point and route definitionsconfig.py: Configuration management with environment variable supportextensions.py: Shared extensions (SQLAlchemy, JWT, Redis) initializationcore/: Core functionality modulesauth.py: Authentication handlers (login, logout, identity verification)models.py: Core database models (User, Log)resources.py: Core API endpoint resourcesdecorators.py: Permission control decoratorsrecaptcha.py: reCAPTCHA integration for securityextra.py: Utility functions
web/: Telemetry-specific modulesmodels.py: Telemetry database models (Device, Session, Lap, Position, Track, etc.)resources.py: Telemetry API endpoint resources
jobs/: Background job processing systemmain.py: Job queue processor for telemetry dataextras.py: Utility functions for GPS calculations and track analysis
nginx/: Nginx reverse proxy configurationcertbot/: SSL certificate managemententrypoints/: Docker container entry point scriptsmigrations/: Database migration files for schema management
- User: User accounts and authentication
- Log: System activity logging and audit trails
- Device: GPS tracking devices (integrated with Traccar)
- Track: Racing track definitions with geographical boundaries
- TrackCheckpoint: Track sector/checkpoint definitions with GPS coordinates
- Session: Recording sessions linking users, devices, and tracks
- Position: GPS coordinate data points (latitude, longitude, speed, timestamp)
- Lap: Individual lap records with timing and classification
- Checkpoint: Checkpoint crossing events during laps
- LapPosition: Many-to-many relationship linking laps to position data
POST /api/login: Authenticate user and receive JWT tokenPOST /api/logout: Invalidate current JWT token (blacklist)GET /api/id: Get current authenticated user details
GET /api/get_users: List all users (requires permission level 3+)GET /api/get_user/<id>: Get specific user details (requires permission level 3+)POST /api/edit_user/<id>: Update user details (requires permission level 3+)POST /api/add_user: Create new user (requires permission level 3+)POST /api/change_password: Change user's passwordPOST /api/change_user_details: Update username or emailPOST /api/change_theme: Change user's theme preference
GET /api/track: List all available racing tracksPOST /api/track: Create new track (supports JSON data or file upload)GET /api/track/<id>: Get specific track details including checkpointsPUT /api/update_devices: Synchronize devices from Traccar serverPOST /api/session: Process telemetry data and create racing sessionGET /api/session/<id>: Get session details including laps and timing data
GET /api/status: Check API status and healthGET /api/hello: Simple hello world endpoint for testingGET /api/get_logs: Retrieve system logs (requires permission level 4+)DELETE /api/delete_log/<id>: Delete specific log (requires permission level 5)DELETE /api/delete_all_logs: Delete all logs (requires permission level 5)GET /api/get_usage: Get user activity logs (requires permission level 3+)
POST /api/db_populate: Populate database with sample track data (Montmelo circuit)
The system uses a numeric permission system:
- 0: Inactive user (minimal access)
- 1: Regular user (basic access)
- 2: Super user
- 3: Moderator (can manage users)
- 4: Super moderator (can view logs)
- 5: Administrator (full access)
- Python 3.10+
- Docker and Docker Compose (for production)
- Redis (required for job processing and session management)
- PostgreSQL (recommended for production)
- Traccar GPS Server (required for GPS data integration)
The system requires several environment variables for proper operation:
SECRET_KEY=your_secret_key
JWT_SECRET_KEY=your_jwt_secret
DEBUG=False
DATABASE_URL=postgresql://user:password@host:port/databaseTRACCAR_URL=http://your-traccar-server:8082/api
TRACCAR_TOKEN=your_traccar_api_tokenRECAPTCHA_SECRET_KEY=your_recaptcha_secret
RECAPTCHA_WEB_KEY=your_recaptcha_site_keyREDIS_HOST=redis
POSTGRES_USER=postgres
POSTGRES_PASSWORD=secure_password
POSTGRES_DB=telemetron-
Clone the repository
git clone <your-repo-url> cd telemetron-api
-
Set up Traccar GPS Server
Install and configure Traccar server (refer to Traccar documentation):
# Example Docker setup for Traccar docker run -d --name traccar --restart unless-stopped \ -p 8082:8082 -p 5000-5150:5000-5150 \ -v /opt/traccar/logs:/opt/traccar/logs \ -v /opt/traccar/data:/opt/traccar/data \ traccar/traccar:latest -
Create a virtual environment
python -m venv .venv .venv\Scripts\activate # On Windows # OR source .venv/bin/activate # On Linux/Mac
-
Install dependencies
pip install -r requirements.txt
-
Create a
.envfile with the required variablesSECRET_KEY=your_secret_key JWT_SECRET_KEY=your_jwt_secret RECAPTCHA_SECRET_KEY=your_recaptcha_secret RECAPTCHA_WEB_KEY=your_recaptcha_site_key DATABASE_URL=sqlite:///instance/database.db TRACCAR_URL=http://localhost:8082/api TRACCAR_TOKEN=your_traccar_api_token DEBUG=True
-
Initialize the database
flask db upgrade
-
Run the application
python -m app.api.app
-
Start the background job processor (in a separate terminal)
python -m app.jobs.main
The system is designed for containerized deployment with multiple services:
-
Create a
.env.prodfile with production settingsSECRET_KEY=your_production_secret_key JWT_SECRET_KEY=your_production_jwt_secret RECAPTCHA_SECRET_KEY=your_recaptcha_secret RECAPTCHA_WEB_KEY=your_recaptcha_site_key # Database configuration POSTGRES_USER=postgres POSTGRES_PASSWORD=secure_password POSTGRES_DB=telemetron DATABASE_URL=postgresql://postgres:secure_password@db:5432/telemetron # Traccar integration TRACCAR_URL=http://your-traccar-server:8082/api TRACCAR_TOKEN=your_traccar_api_token # Infrastructure DEBUG=False REDIS_HOST=redis # Docker Compose ports API_PORT=5000 DB_PORT=5432 REDIS_PORT=6379
-
Deploy the complete stack
# On Windows start-production.bat # On Linux/Mac docker compose --env-file .env.prod up -d
- API Service: Main Flask application serving the REST API
- Jobs Service: Background worker for processing telemetry data
- PostgreSQL Database: Primary data storage for all telemetry and user data
- Redis Cache: Job queue management and session storage
- Nginx Reverse Proxy: Load balancing and SSL termination
- Certbot: Automated SSL certificate management
This application uses Nginx as a reverse proxy and Certbot for managing SSL certificates with Let's Encrypt.
- A domain name pointing to your server's IP address
- Open ports 80 and 443 on your firewall/router
- Configure DNS A records for your domain (and www subdomain if needed)
-
Update the
nginx/conf.d/app.conffile forYOUR_DOMAIN_NAMEto match your domain name -
Start the Docker services:
docker compose --env-file .env.prod up -d
docker compose run --rm certbot certonly --webroot --webroot-path /var/www/certbot/ -d yourdomain.com -d www.yourdomain.com-
After successfully generating certificates, edit
nginx/conf.d/app.conf:- Uncomment the HTTPS server block
- Update the domain names and paths if necessary
-
Reload Nginx configuration:
docker compose exec nginx nginx -s reload
Certbot certificates expire after 90 days. Set up automatic renewal:
- Test the renewal process:
docker compose run --rm certbot renew --dry-run-
Set up a cron job to run renewal twice daily (recommended by Let's Encrypt):
0 0,12 * * * cd /path/to/your/project && docker compose run --rm certbot renew --quiet && docker compose exec nginx nginx -s reload
- Certificate issues: Check Certbot logs with
docker compose logs certbot - Nginx configuration: Validate with
docker compose exec nginx nginx -t - Connection refused: Ensure ports 80 and 443 are open and properly forwarded
- Authentication: Login to get JWT token
- Device Setup: Synchronize GPS devices from Traccar
- Track Management: Create or upload track configurations
- Session Processing: Process GPS data to generate lap times and analytics
# Login to get JWT token
curl -X POST http://localhost:5000/api/login \
-H "Content-Type: application/json" \
-d '{"username": "admin", "password": "password"}'# Update device list from Traccar server
curl -X PUT http://localhost:5000/api/update_devices \
-H "Authorization: Bearer your_jwt_token"# Create track with checkpoints
curl -X POST http://localhost:5000/api/track \
-H "Authorization: Bearer your_jwt_token" \
-H "Content-Type: application/json" \
-d '{
"track": {
"name": "Test Circuit",
"location": "Test Location"
},
"checkpoints": [
{
"number": 1,
"name": "Start/Finish",
"type": "start",
"points": [
{"lat": 41.571159, "lon": 2.262021},
{"lat": 41.571065, "lon": 2.262226}
]
}
]
}'# Create session and process GPS data
curl -X POST http://localhost:5000/api/session \
-H "Authorization: Bearer your_jwt_token" \
-H "Content-Type: application/json" \
-d '{
"deviceId": 1,
"trackId": 1,
"sessionName": "Practice Session",
"from": "2024-01-01T10:00:00Z",
"to": "2024-01-01T11:00:00Z"
}'Tracks can be uploaded as JSON files with the following structure:
{
"track": {
"name": "Circuit Name",
"location": "City, Country"
},
"checkpoints": [
{
"number": 1,
"name": "Start/Finish",
"type": "start",
"points": [
{"lat": 41.571159, "lon": 2.262021},
{"lat": 41.571065, "lon": 2.262226}
],
"previous": null
},
{
"number": 2,
"name": "Sector 1",
"type": "sector",
"points": [
{"lat": 41.568078, "lon": 2.253455},
{"lat": 41.567784, "lon": 2.254079}
],
"previous": [1]
}
]
}The system automatically processes GPS position data to detect and classify laps:
- Checkpoint Detection: Uses geometric algorithms to detect when vehicles cross track checkpoints
- Lap Timing: Calculates precise lap times based on checkpoint crossings
- Lap Classification: Automatically categorizes laps as:
- Complete: Full laps with all checkpoints crossed
- Invalid: Laps that don't meet completion criteria
- Outlap: First lap when leaving pits
- Inlap: Final lap when entering pits
- Pitstop: Time spent in pit area
- Background Jobs: Asynchronous processing using Redis job queues
- Server-Sent Events: Real-time updates during data processing
- Streaming API: Live updates for ongoing sessions
The system integrates seamlessly with Traccar GPS server:
- Device Synchronization: Automatic sync of GPS devices from Traccar
- Position Data Retrieval: Fetches historical and real-time GPS data
- Multi-device Support: Handle multiple vehicles simultaneously
- Data Validation: Ensures data integrity and handles missing data points
- Flask 3.1.0: Core web framework
- Flask-RESTful 0.3.10: REST API development
- Flask-SQLAlchemy 3.1.1: Database ORM
- Flask-Migrate 4.1.0: Database migration management
- Flask-JWT-Extended 4.7.1: JWT authentication
- Flask-Cors 5.0.1: Cross-origin resource sharing
- PostgreSQL: Primary database (SQLAlchemy 2.0.40)
- Redis 5.2.1: Job queuing and caching
- SQLite: Development database option
- Shapely 1.26.0: Geometric operations for track boundaries
- GeoPy 2.4.1: Geographic calculations and distance computations
- Docker & Docker Compose: Containerized deployment
- Nginx: Reverse proxy and load balancing
- Gunicorn 21.2.0: WSGI HTTP server
- Certbot: SSL certificate management
- Traccar GPS Server: GPS tracking system integration
- reCAPTCHA: Bot protection and security
┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐
│ Nginx │ │ Flask API │ │ Background │
│ (Port 80/443) │────│ (Port 5000) │ │ Jobs Worker │
└─────────────────┘ └──────────────┘ └─────────────────┘
│ │
│ │
┌──────────────┐ ┌─────────────────┐
│ PostgreSQL │ │ Redis │
│ (Port 5432) │ │ (Port 6379) │
└──────────────┘ └─────────────────┘
│ │
└───────────────────────┘
│
┌──────────────┐
│ Traccar │
│ GPS Server │
│ (Port 8082) │
└──────────────┘
When no users exist in the system, the first login attempt will create an administrator user with the credentials provided in the login request. This allows for easy initial setup of the system.
- Advanced Lap Detection: Sophisticated algorithms for accurate lap timing
- Multi-track Support: Ability to define and manage multiple racing circuits
- Real-time Data Processing: Background job system for processing large telemetry datasets
- Checkpoint Management: Flexible checkpoint system for track sector timing
- Session Analytics: Comprehensive session recording and analysis
- Traccar Integration: Seamless integration with Traccar GPS tracking server
- Enhanced Logging System: Added country detection and IP tracking in logs
- Database Migration Support: Switched to Flask-Migrate for better schema management
- Cloudflare Integration: Full compatibility with Cloudflare CDN and proper IP forwarding
- Improved Nginx Configuration: Enhanced SSL security settings and timeout handling
- Direct Database Initialization: Simplified database setup for reliable container startup
- Proper Timestamp Handling: Added timezone support with pytz for accurate logging
- Optimized Docker Build: Added
.dockerignoreto improve build efficiency and security - Real IP Tracking: Improved client IP detection through multiple proxies
- Hardened SSL Configuration: Updated cipher suites and protocol settings
- Refactored application structure for better modularity and maintainability
- Enhanced Docker setup with Nginx as a reverse proxy
- Added Certbot integration for automated SSL certificate management
- Improved configuration with
.env.examplefor better onboarding - Updated
.gitignoreto exclude sensitive configuration files and generated certificates - Redis integration for token blacklisting and rate limiting
- JWT tokens valid for 12 hours by default
- Failed login attempt tracking with reCAPTCHA protection
- Comprehensive activity logging with timestamps and IP addresses
- Docker Compose configuration with customizable ports
- Advanced Analytics Dashboard: Web-based interface for telemetry visualization
- Email Notification System: Alerts for session completion and system events
- Multi-format Data Export: Support for CSV, JSON, and motorsport-specific formats
- Advanced Lap Comparison: Side-by-side lap analysis and performance metrics
- Real-time Live Timing: WebSocket-based live timing displays
- Mobile API: Optimized endpoints for mobile applications
- Data Visualization: Built-in charting and graphing capabilities
- Weather Data Integration: Correlate telemetry with weather conditions
- Multi-user Session Sharing: Collaborative analysis features
- Advanced Permission System: Granular access control for different data types
telemetron-api/
├── app/ # Main application package
│ ├── __init__.py # Application package initialization
│ ├── api/ # Core API modules
│ │ ├── __init__.py
│ │ ├── app.py # Flask application entry point
│ │ ├── config.py # Configuration management
│ │ ├── extensions.py # SQLAlchemy, JWT, Redis initialization
│ │ ├── core/ # Core functionality
│ │ │ ├── __init__.py
│ │ │ ├── auth.py # Authentication handlers
│ │ │ ├── decorators.py # Permission decorators
│ │ │ ├── extra.py # Utility functions
│ │ │ ├── models.py # User and Log models
│ │ │ ├── recaptcha.py # reCAPTCHA integration
│ │ │ └── resources.py # Core API endpoints
│ │ └── web/ # Telemetry-specific modules
│ │ ├── __init__.py
│ │ ├── models.py # Telemetry database models
│ │ └── resources.py # Telemetry API endpoints
│ └── jobs/ # Background processing
│ ├── __init__.py
│ ├── extras.py # GPS calculation utilities
│ └── main.py # Job queue processor
├── migrations/ # Database migration files
│ ├── alembic.ini
│ ├── env.py
│ ├── script.py.mako
│ └── versions/ # Migration versions
├── nginx/ # Nginx configuration
│ ├── nginx.conf # Main Nginx config
│ └── conf.d/
│ └── app.conf # Application-specific config
├── certbot/ # SSL certificate management
│ ├── conf/ # Certificate storage
│ └── www/ # ACME challenge files
├── entrypoints/ # Docker entry scripts
│ ├── entrypoint-api.sh # API service startup
│ └── entrypoint-jobs.sh # Jobs service startup
├── instance/ # Instance-specific files
│ └── database_dev.db # Development SQLite database
├── cache/ # Application cache files
├── tests/ # Test files and utilities
│ ├── DbPopulate.py
│ ├── get_track.py
│ ├── post_track.py
│ └── Real_Test.py
├── docker-compose.yml # Multi-service deployment
├── Dockerfile # Container build instructions
├── requirements.txt # Python dependencies
├── track_Montmelo.json # Sample track configuration
├── start-production.bat # Windows deployment script
├── init_db.py # Database initialization
└── readme.md # This documentation
app/api/app.py: Main Flask application with all route definitionsapp/api/web/models.py: Telemetry database models (Device, Session, Lap, Position, Track, etc.)app/api/web/resources.py: Telemetry API endpoints for tracks, sessions, and devicesapp/jobs/main.py: Background worker that processes GPS data from Redis queuesdocker-compose.yml: Defines all services (API, jobs, database, Redis, Nginx)track_Montmelo.json: Example track configuration file for the Montmelo circuitmigrations/: Database schema evolution files managed by Flask-Migrate