AskaEth/TurboSu

Fork 0

Files

T

Yei.J. (AskaEth) d61bb61a83 feat: TurboSu initial release - racing telemetry dashboard

2026-07-25 15:23:40 +08:00

5.7 KiB

Raw Blame History

TurboSu

赛车遥测仪表盘 — 基于 Web 的 B/S 架构外置仪表盘，支持多种赛车游戏遥测数据实时显示。

功能特性

多游戏支持 —— 插件化架构，内置支持 Forza Horizon 4/5、Forza Motorsport、Assetto Corsa/ACC、F1、iRacing
社区扩展 —— 游戏插件可独立导入导出，方便社区贡献小众游戏支持
实时仪表盘 —— 速度表、转速表、档位指示器、圈速计时器等
场景模式 —— 多仪表盘布局组合，支持多比例画布切换
局域网共享 —— 仪表盘/场景生成独立链接，手机/平板/笔记本均可全屏访问
跨端自适应 —— 响应式布局，桌面侧边栏 / 平板折叠 / 手机底部导航
比例约束渲染 —— 每个仪表盘可指定渲染比例(auto/16:9/4:3/1:1)和渲染模式
主题切换 —— Xiaomi HyperOS (Miuix) 风格，支持日间/夜间模式
导出导入 —— 仪表盘主题和场景独立配置文件，社区友好

快速开始

环境要求

Python 3.10+
pip

安装运行

# 克隆/下载项目
cd Project/TurboSu

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 启动服务
python app.py

浏览器访问 http://localhost:9527

一键启动

chmod +x run.sh
./run.sh

使用指南

1. 选择游戏

侧边栏 → "选择游戏" 下拉 → 点击你要玩的游戏。

游戏列表来自 games/builtin/ (内置) 和 games/user/ (社区插件)。

2. 配置游戏遥测输出

在各游戏中设置 UDP 数据输出：

游戏	设置位置	端口
Forza Horizon 4/5	设置 → HUD与游戏 → 数据输出	20777
Forza Motorsport	设置 → 游戏玩法 → UDP 数据输出	20777
Assetto Corsa	内容管理器 → 设置 → 自定义UDP	9996
ACC	设置 → 电子设备 → UDP	20777
F1 24	设置 → 遥测设置 → UDP	20777
iRacing	选项 → 杂项 → 数据记录	20777

3. 浏览仪表盘

点击侧边栏 "仪表盘" → 浏览/筛选 → 点击卡片在新标签打开。

链接会自动复制，可在局域网设备(手机/平板)打开全屏显示。

4. 创建场景

侧边栏 → "场景" → 新建 → 编辑添加多个仪表盘 → 渲染。

场景支持多个画布比例(16:9/4:3等)，渲染前选择。

5. 数据调试

侧边栏 → "数据测试" → 查看解析后的实时数据和原始数据流。

开发指南

创建自定义游戏插件

在 games/user/ 下创建文件夹，如 games/user/my_game/
创建 manifest.json:

{
    "id": "my_game",
    "name": "我的游戏",
    "parser_type": "forza",
    "description": "自定义游戏遥测",
    "author": "你的名字",
    "version": "1.0.0",
    "default_port": 20777
}

创建 parser.py:

import struct
import time
from server.telemetry.data import TelemetryData


def get_parser():
    return MyGameParser()


class MyGameParser:
    def game_id(self) -> str:
        return "my_game"

    def parse(self, data: bytes, addr: tuple) -> TelemetryData:
        td = TelemetryData(game_id="my_game", timestamp=time.time())
        td.raw = {"raw_hex": data.hex(), "length": len(data)}

        # 解析你的游戏数据
        # td.speed_kmh = ...
        # td.rpm = ...
        # td.gear = ...

        return td

重启 TurboSu 或点击设置 → 重新加载插件

创建自定义仪表盘主题

在设置页面的仪表盘管理中创建，或直接编写配置文件。

项目结构

TurboSu/
├── app.py                    # FastAPI 主入口
├── config/settings.py        # 全局配置管理
├── server/
│   ├── api.py                # REST API 路由
│   ├── websocket.py          # WebSocket 实时推送
│   ├── game_manager.py       # 游戏插件管理器
│   └── telemetry/
│       ├── data.py           # 遥测数据结构
│       ├── listener.py       # UDP 监听器
│       └── parsers/          # 内置解析器
├── games/
│   ├── builtin/              # 内置游戏插件 (7款)
│   └── user/                 # 用户/社区插件
├── models/
│   ├── dashboard.py          # 仪表盘数据模型
│   └── scene.py              # 场景数据模型
├── dashboards/               # 内置仪表盘主题 (4款)
├── templates/
│   ├── index.html            # 主 SPA 页面
│   ├── dashboard.html        # 仪表盘渲染页
│   └── scene.html            # 场景渲染页
├── static/
│   ├── css/
│   │   ├── miuix.css         # HyperOS 样式框架
│   │   └── main.css          # 布局样式
│   └── js/                   # 前端 JavaScript 模块
├── utils/logger.py           # 日志系统
├── data/                     # 运行时数据存储
├── logs/                     # 日志文件
├── requirements.txt
└── run.sh

仪表盘配置说明

每个仪表盘主题的 config.json 支持以下渲染配置：

{
    "aspect_ratio": "auto",     // auto | 16:9 | 4:3 | 1:1 | 21:9
    "render_mode": "contain",   // contain(留黑边) | cover(裁切) | fill(拉伸) | center(居中)
    "max_width": 1920,          // center 模式最大宽度
    "max_height": 1080          // center 模式最大高度
}

作者

Yei.J. (AskaEth)

许可证

Apache License 2.0

5.7 KiB Raw Blame History