How ashwin-nat/pits-n-giggles works
Project Type & Purpose
• This is a full-stack telemetry visualization tool that ingests live F1 race data (from UDP packets) and provides both in-app live updates and stream overlay capabilities.
• The README describes both a direct “executable” option and a start-from-source configuration. It also details advanced features like post race data autosaving, packet capture/replay, and a rich web UI for telemetry display.
• It is clearly designed to be extended—other applications can build on the telemetry manager module.
File Structure
• Top-Level Files and Directories:
• app.py is the main entry point.
• “lib” contains various modules for processing telemetry data like packet parsing, collision analysis, and data forwarding. It includes a dedicated f1_types subdirectory with modules for each F1 telemetry packet type.
• “src” holds configuration (src/config.py), several telemetry handlers, the web API, and UI-related resources (static CSS/JS, HTML templates).
• “tests” contains a comprehensive suite testing modules from telemetry packet parsing to data-related functionalities.
• “utils” provides additional utility scripts for logging, data replay, and viewing post-race telemetry.
• Configuration and build scripts (run.bat, run.sh) indicate cross-platform command-line launch support.
• The architecture appears to follow modular design principles where distinct concerns (data collection, processing, UI, and testing) are clearly separated.
Key Components
a. Data Capture & Ingestion:
• Telemetry Input Listener: A UDP packet receiver (see lib/socket_receiver.py) listens on the default port (20777) for F1 telemetry packets.
• Packet Capture Module (packet_cap.py) and Packet Forwarder (packet_forwarder.py) are responsible for handling raw data and optionally saving or forwarding it.
b. Data Processing:
• Telemetry Manager (located in src/telemetry_manager.py and the telemetry_manager module referenced in the README) orchestrates the registration of callbacks and processing of different packet types.
• Specialized analyzers (collisions_analyzer.py, overtake_analyzer.py, race_analyzer.py, fuel_rate_recommender.py, tyre_wear_extrapolator.py) process specific aspects of the telemetry.
• The “lib/f1_types” folder and corresponding tests in “tests/f1_types” encapsulate parsing logic for every kind of telemetry packet.
c. Data Distribution & API:
• Telemetry Web API (src/telemetry_web_api.py) and the HTTP server (default port 5000) serve processed data to the UI.
• An inter-thread communicator (lib/inter_thread_communicator.py) likely handles data flow between background processes and the UI thread.
d. User Interface (UI):
• The web UI is built using static HTML templates (src/templates) combined with CSS (src/static/css) and JavaScript (src/static/js) to update live data.
• There is support for rich UI overlays (for stream integration as well as detailed driver info) as evident from both the detailed README and the screenshots folder.
e. Additional Utilities:
• Utilities for post-race data (dummy_data.json, telemetry_post_race_data_viewer.py) and logs, as well as packet replay and recording functions (telemetry_recorder.py, telemetry_replayer.py).
Relationships & Interactions
• Data flows from the F1 telemetry source (UDP packets) into the Telemetry Input Listener.
• Input data is passed to the Telemetry Manager, which routes data to specialized analyzers and parsers in the lib modules.
• Processed telemetry data is then served to the front-end: the HTTP server (running in app.py and via src/telemetry_web_api.py) feeds the UI updates.
• Optional interactions include packet capture/replay (triggered by command line flags in app.py) and data forwarding.
• Interactions between the UI’s frontend assets (JavaScript/CSS) and the backend API that pushes live race updates.
Architectural Patterns & Design Principles
• Modular design: Each component (data capture, processing, presentation) is isolated in its own module or package.
• Callback registration and event-driven processing via the telemetry manager indicate a decoupled, extensible design.
• A clear separation between processing (lib, src) and presentation (static assets and templates under src/templates and src/static) following an MVC-like separation.