https://github.com/TinyPedal/TinyPedal
Free and Open Source telemetry overlay application for racing simulation
https://github.com/TinyPedal/TinyPedal
overlay python qt racing racing-game telemetry
Last synced: 3 months ago
JSON representation
Free and Open Source telemetry overlay application for racing simulation
- Host: GitHub
- URL: https://github.com/TinyPedal/TinyPedal
- Owner: TinyPedal
- License: gpl-3.0
- Created: 2022-03-14T08:54:48.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2026-04-15T07:11:55.000Z (3 months ago)
- Last Synced: 2026-04-15T08:24:02.520Z (3 months ago)
- Topics: overlay, python, qt, racing, racing-game, telemetry
- Language: Python
- Homepage:
- Size: 5.83 MB
- Stars: 298
- Watchers: 12
- Forks: 35
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-car-simulation - TinyPedal
- awesome-f1 - TinyPedal - Free open-source telemetry overlay for rFactor 2 and Le Mans Ultimate. (Sim Racing / Media and Analysis)
README
# TinyPedal - racing simulation overlay
TinyPedal is a Free and Open Source telemetry overlay application for racing simulation.
Focuses on minimalist design, light-weight and efficiency, extensive customization and data analysis. Features a large collection of highly configurable overlay widgets and data modules, advanced fuel calculator and editing tools.
Currently supports `rFactor 2` and `Le Mans Ultimate`, and runs on `Windows` and `Linux`.
[Download](https://github.com/TinyPedal/TinyPedal/releases) -
[Quick Start](#quick-start) -
[FAQ](https://github.com/TinyPedal/TinyPedal/wiki/Frequently-Asked-Questions) -
[User Guide](https://github.com/TinyPedal/TinyPedal/wiki/User-Guide) -
[Run on Linux](#running-on-linux) -
[License](#license)
---
## Requirements
### Supported Sims
| API | Windows | Linux |
|:-:|:-:|:-:|
| Le Mans Ultimate | No plugin required | Requires third-party plugin |
| rFactor 2 | rF2SharedMemoryMapPlugin | rF2SharedMemoryMapPlugin(Wine) |
### Display Mode
Game display mode must be set to `Borderless` or `Windowed` to show overlay. `Fullscreen` mode is not supported.
### Setup for Le Mans Ultimate
#### Windows
* There is no plugin required for accessing LMU's built-in API on Windows. However, make sure `Enable Plugins` option is turned `ON` from in game `Settings` -> `Gameplay` page.
#### Linux
* LMU's built-in API can be selected on Linux, but may require third-party plugin to access, see [discussion #9](https://github.com/TinyPedal/TinyPedal/issues/9) for info.
### Setup for rFactor 2
TheIronWolf's [rF2 Shared Memory Map Plugin](https://github.com/TheIronWolfModding/rF2SharedMemoryMapPlugin) is required for accessing `rFactor 2` API.
#### Windows
* Download the plugin from:\
https://github.com/TheIronWolfModding/rF2SharedMemoryMapPlugin#download
#### Linux
* Download the forked plugin for Wine from:\
https://github.com/schlegp/rF2SharedMemoryMapPlugin_Wine/blob/master/build
#### Install plugin
The plugin file is named `rFactor2SharedMemoryMapPlugin64.dll` and should be placed in `rFactor 2\Bin64\Plugins` folder.
Note, manually create this `Plugins` folder if it is missing.
#### Enable plugin in game
In game `Settings` -> `Gameplay` page, find `Plugins` section and toggle on `rFactor2SharedMemoryMapPlugin64.dll`.
After plugin enabled, must `restart game` to take effect.
Note, if game cannot generate `rFactor2SharedMemoryMapPlugin64.dll` entry in `CustomPluginVariables.JSON` file, make sure `VC12 (Visual C++ 2013) runtime` is installed, which can be found in game's `Support\Runtimes` folder.
## Quick Start
> [!IMPORTANT]
> Make sure required plugins for specific game are installed according to [Requirements](#requirements).
>
> DO NOT extract TinyPedal into `system` or `game` folder, such as `Program Files` or `rFactor 2` folder, otherwise it may fail to run.
>
> See [Frequently Asked Questions](https://github.com/TinyPedal/TinyPedal/wiki/Frequently-Asked-Questions) for common issues, and [User Guide](https://github.com/TinyPedal/TinyPedal/wiki/User-Guide) for usage info.
>
> For Linux user, please follow [Running on Linux](#running-on-linux) section for instruction.
1. Download latest TinyPedal version from [Releases](https://github.com/TinyPedal/TinyPedal/releases) page, extract it into a clean folder, and run `tinypedal.exe`.
2. A tray icon will appear at system tray. If not shown, check hidden tray icon. `Right Click` on tray icon will bring up context menu.
3. Launch game, overlay will appear once vehicle is on track, and auto-hide otherwise. Auto-hide can be toggled On and Off by clicking `Auto Hide` from tray menu.
4. Overlay can be Locked or Unlocked by clicking `Lock Overlay` from tray menu. While Unlocked, click on overlay to drag around.
5. Widgets can be Enabled or Disabled from `Widget` panel in main window. `Right Click` on tray icon and select `Config` to show main window if it is hidden.
6. To quit APP, `Right Click` on tray icon and select `Quit`; or, click `Overlay` menu from main window and select `Quit`.
## Run from Source
### Dependencies:
* [Python](https://www.python.org/) 3.8, 3.9, or 3.10
* PySide2
* pyLMUSharedMemory
* pyRfactor2SharedMemory
* psutil
> [!IMPORTANT]
> Make sure to check Python version before installing additional dependencies.
>
> PySide2 may not be available for Python version higher than 3.10; or requires PySide6 instead for running with newer Python version. PySide6 is currently supported only via command line argument, see [Command Line Arguments](https://github.com/TinyPedal/TinyPedal/wiki/User-Guide#command-line-arguments) in User Guide for details.
### Download source code
#### Method 1
Download TinyPedal source code from [Releases](https://github.com/TinyPedal/TinyPedal/releases) page; or click `Code` button at the top of repository and select `Download ZIP`.
Download submodule source code from following links:
- pyLMUSharedMemory: https://github.com/TinyPedal/pyLMUSharedMemory
- pyRfactor2SharedMemory: https://github.com/TinyPedal/pyRfactor2SharedMemory
Extract TinyPedal source code ZIP file. Then extract submodule ZIP files and put them in corresponding folder in the root folder of TinyPedal.
#### Method 2
Use [Git](https://git-scm.com/) tool and run following command to clone TinyPedal source code alongside required submodules:
```
git clone --recursive https://github.com/TinyPedal/TinyPedal.git
```
To update submodules, run command:
```
git submodule update --init
```
Since `master` branch is the development branch, it may not be stable for normal use. You may switch to specific released version instead, such as `v2.45.0`, run command:
```
git checkout tags/v2.45.0
```
And to switch back to development branch, run:
```
git checkout master
```
### Setup development environment
It is recommended to setup an isolated development environment for running and testing code, especially useful if multiple different versions of Python are installed.
To start, make sure required Python version was installed. Currently the primary supported Python version is `3.8`, which is used in this example.
First, we need to create a [Python virtual environment](https://docs.python.org/3/library/venv.html). On windows, run following command in `Powershell` (replace the last part to your preferred path, either relative or absolute path):
```
py -3.8 -m venv '.virtualenvs\tinypedal_py38'
```
Then run following command to activate this virtual environment:
```
.virtualenvs\tinypedal_py38\Scripts\activate.ps1
```
Once activated, you can continue with [Install dependencies](#install-dependencies) section to install required package for this virtual environment, and running or building TinyPedal inside this virtual environment.
Finally, remember to activate this virtual environment (if haven't already) before installing packages or running the code.
### Install dependencies
Install additional dependencies by using command:
```
pip3 install PySide2 psutil
```
To start TinyPedal, type command from project root folder:
```
python run.py
```
## Build Executable for Windows
Executable file can be built with [py2exe](http://www.py2exe.org).
To install py2exe, run command:
```
pip3 install py2exe
```
To build executable file, run command:
```
python freeze_py2exe.py
```
After building completed, executable file can be found in `dist\TinyPedal` folder.
> [!NOTE]
> The build script only supports py2exe `v0.12.0.0` or higher. The build script does not support PySide6.
## Running on Linux
The procedure described in the [Run from Source](#run-from-source) section is mostly valid,
except some differences in the dependencies, and that no executable can be
built. The differences are explained here.
Configuration and data files will be stored in the defined user-specific
directories, default to:
```
$HOME/.config/TinyPedal/
$HOME/.local/share/TinyPedal/
```
The required Python packages are `PySide2`, `psutil` and `pyxdg`. Most distros
name the package with a prefix, like `python3-pyside2`, `python3-psutil` and
`python3-pyxdg`.
Some distros split `PySide2` in subpackages. If you don't find
`python3-pyside2` then you should install `python3-pyside2.qtgui`,
`python3-pyside2.qtwidgets` and `python3-pyside2.qtmultimedia`.
Alternatively, you can install them using `pip3` but this will bypass your
system package manager and it isn't the recommended option. The command to
install the dependencies with this method is:
```
pip3 install PySide2 psutil pyxdg
```
To start TinyPedal type the following command:
```
./run.py
```
### Installation
Once you have a working instance of TinyPedal, created using the git command or
by unpacking the Linux release file, you can run the install script to install
or update TinyPedal on your system.
The install script will create a desktop launcher and will make `TinyPedal`
available as a command from the terminal.
The files will be installed at the `/usr/local/` prefix. You'll need
appropriate permissions to write there, for example, by using `sudo`.
You can run the script as (it doesn't support any arguments or options):
```sh
sudo ./install.sh
```
If you need persistent launch arguments (for example, to force PySide6), create
`~/.config/TinyPedal/launcher.conf` with:
```sh
TINYPEDAL_RUN_ARGS="--pyside 6"
```
The installed launcher and desktop entry will read this file automatically. This is mainly useful for ArchLinux where `PySide2` is deprecated.
### Known issues
- Some features may not be available on Linux currently.
- Widgets don't appear over the game window in KDE. Workaround: enable `Bypass Window Manager` option in `Compatibility` dialog from `Config` menu in main window.
- Transparency of widgets doesn't work when desktop compositing is disabled. Workaround: enable `window manager compositing` in your Desktop Environment.
## Contributing
Please follow [Contributing Guidelines](CONTRIBUTING.md) for how to report issue, request feature, or contribute code.
## License
Copyright (C) 2022-2026 TinyPedal developers
TinyPedal is free software and licensed under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. TinyPedal is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY. See [LICENSE.txt](./LICENSE.txt) for more info.
TinyPedal icon, as well as image files located in `images` folder, are licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
Licenses and notices file for third-party software are located in `docs\licenses` folder, see [THIRDPARTYNOTICES.txt](./docs/licenses/THIRDPARTYNOTICES.txt) file for details.
## Credits
See [docs\contributors.md](./docs/contributors.md) file for full list of developers and contributors.