GT7 Nanoleaf Sync

中文版 / Chinese | English

A real-time telemetry translation system that maps Gran Turismo 7 (PS5) race data directly onto Nanoleaf Lightstrips. Using Nanoleaf's ExtControl v2 UDP streaming protocol and GT7's telemetry UDP broadcast, this project provides a zero-lag, highly immersive lighting experience for your sim racing setup.

Features

• 🏎 Real-time Telemetry Processing: Smooth parsing of RPM, speed, gear, throttle, and brake data.
• 🌈 Zero-lag Light Streaming: Uses UDP stream control for ultra-fast, per-zone LED updates.
• 🚥 Pre-built Visual Effects:
  • rpm_bar: Maps the RPM progressively across the length of the lightstrip (Green → Yellow → Red).
  • shift_alert: Includes the RPM bar, adding bright flashing patterns when you hit the rev limit or optimal shifting points.
  • brake_zone_alert: Includes the RPM bar, adding a powerful red flash before corners if the system suggests aggressive downshifting (braking zone).
  • brake_alert: Simulates brake lights, mapping braking pressure to brightness and rapidly flashing red under heavy braking.
  • g_force: Visualizes lateral G-force as a moving light dot on the strip. The dot moves from center toward the edges based on cornering force, with brightness increasing proportionally. Triggers rapid flashing when tire slip or traction loss is detected (via TCS/ASM flags or wheel speed analysis).
• 🔌 Extensible Architecture: Easy to create your own custom lighting scenarios.

Prerequisites

1. PlayStation 5 with Gran Turismo 7
   • You MUST enable Telemetry Data in the game settings: Options -> Global -> Network -> Telemetry Data -> On.
2. Nanoleaf Device
   • Fully compatible with Nanoleaf Essentials WiFi Lightstrips (e.g., NL72K1 HD).
   • Ensure the lightstrip is turned on and connected to the same local network as the script.
3. Python Environment
   • Python 3.10 or higher.

Installation

1. Clone or download the repository.
2. Navigate to the project directory and create a virtual environment (recommended):

   python3 -m venv .venv
   source .venv/bin/activate

3. Install the required dependencies:

   pip install -r requirements.txt

Configuration & Pairing

Before running the engine, you need to pair the script with your Nanoleaf device to acquire an authorization token.

1. Find your device IP addresses:
   • For PS5: Go to Network Settings on your console.
   • For Nanoleaf, use the built-in discovery tool:

     python main.py discover

2. Setup config.yaml: Copy config.example.yaml to config.yaml and enter your IPs:

   ps5:
     ip: "192.168.1.100" # Your PS5 IP
   
   nanoleaf:
     ip: "192.168.1.50"  # Your Nanoleaf IP
     auth_token: ""      # Leave empty for now

3. Pair the Device: Run the pairing wizard:

   python main.py pair

   Follow the on-screen instructions. You will need to open the Nanoleaf App, go to Device Settings, and tap Connect to API (or hold the physical power button on the controller for 5-7 seconds). The obtained auth_token will be automatically saved to your config.yaml.

Usage

Test your lightstrip connection and verify that UDP streaming works properly:

python main.py test-strip

Running the Engine

Start the main telemetry engine:

python main.py run

To run a specific effect mode, use the --effect flag (you can find all supported modes using python main.py list-effects):

python main.py run --effect shift_alert
python main.py run --effect brake_zone_alert
python main.py run --effect brake_alert
python main.py run --effect g_force

Important Notes

• Network Stability: Since both GT7 and Nanoleaf ExtControl rely heavily on high-frequency UDP packets, a stable Wi-Fi/wired connection minimizes lag and lost frames.
• Port Requirements: Ensure ports 33740 (GT7 UDP) and 60222 (Nanoleaf UDP) are not blocked by the firewall of the machine running the script.