LEADS is a lightweight embedded assisted driving system. It is designed to simplify the development of instrumentation, control, and analysis systems for racing cars. It is written in well-organized Python and C/C++ and has impressive performance.It is not only out-of-the-box but also fully customizable. It provides multiple abstract layers that allow users to pull out the components and rearrange them into a new project. You can either configure the existing executable modules (LEADS VeC) simply through a JSON file or write your own codes based on the framework as easily as building a LEGO.

The hardware components chosen for this project are geared towards amateur developers. It uses neither a CAN bus (although it is supported) nor any dedicated circuit board, but generic development kits such as Raspberry Pi and Arduino instead. However, as it is a high-level system running on a host computer, the software framework has the ability to adapt to any type of hardware component with extra effort.

This document will guide you through LEADS VeC. You will find a detailed version here.

🔗 Home

🔗 News

🔗 Docs

🔗 LEADS VeC Remote Analyst Online Dashboard

Should you find our work helpful to you, please cite our publication.

@misc{fu2024leadslightweightembeddedassisted,
    title = {LEADS: Lightweight Embedded Assisted Driving System},
    author = {Tianhao Fu and Querobin Mascarenhas and Andrew Forti},
    year = {2024},
    eprint = {2410.17554},
    archivePrefix = {arXiv},
    primaryClass = {cs.SE},
    url = {https://arxiv.org/abs/2410.17554},
}

Note that LEADS requires Python >= 3.12. To set up the environment on Ubuntu by only a single line of command, see Environment Setup.

pip install "leads[standard]"

If you only want the framework, run the following.

pip install leads

This table lists all installation profiles.

You can install LEADS Arduino from Arduino Library Manager. Note that it is named "LEADS", not "LEADS-Arduino", in the index.

See Read the Docs for the documentation of how to customize and make use of the framework in your project.

leads-vec run

leads-vec info

leads-vec replay

Replaying requires "main.csv" under the data directory. It as well accepts all optional arguments listed below.

leads-vec benchmark

Run the following to get a list of all the supported arguments.

leads-vec -h

leads-vec -c path/to/the/config/file.json run

You can use ":INTERNAL" to replace the path to leads_vec. For example, instead of typing ".../site-packages/leads_vec/devices_jarvis.py", simply use ":INTERNAL/devices_jarvis.py".

If not specified, all configurations will be default values.

To learn about the configuration file, read Configurations.

leads-vec -d path/to/the/devices.py run

You can use ":INTERNAL" to replace the path to leads_vec. For example, instead of typing ".../site-packages/leads_vec/devices_jarvis.py", simply use ":INTERNAL/devices_jarvis.py".

To learn about the devices module, read Devices Module.

leads-vec -m path/to/the/main.py run

You can use ":INTERNAL" to replace the path to leads_vec. For example, instead of typing ".../site-packages/leads_vec/devices_jarvis.py", simply use ":INTERNAL/devices_jarvis.py".

Function main() must exist in the main module, otherwise an ImportError will be raised.

It needs to have the identical signature as the following.

def main() -> int:
    """
    :return: 0: success; 1: error
    """
    ...

leads-vec -r config run

This will generate a default "config.json" file under the current directory.

leads-vec -r systemd run

This will register a user Systemd service to start the program. The service script is usually located at "/usr/local/leads/venv/python3.12/site-packages/leads_vec/_bootloader/leads-vec.service.sh". Edit the file to customize the arguments.

To enable auto-start at boot, run the following.

systemctl --user daemon-reload
systemctl --user enable leads-vec

You will have to stop the service by this command otherwise it will automatically restart when it exits.

systemctl --user stop leads-vec

Use the following to disable the service.

systemctl --user disable leads-vec

leads-vec -r reverse_proxy run

This will start the corresponding reverse proxy program as a subprocess in the background.

leads-vec -r splash_screen run

This will replace the splash and lock screen with LEADS' logo.

leads-vec -mfs 1.5 run

This will magnify all font sizes by 1.5.

leads-vec --emu run

This will force the program to use emulation even if the environment is available.

leads-vec --auto-mfs run

Similar to Magnify Font Sizes, but instead of manually deciding the factor, the program will automatically calculate the best factor to keep the original proportion as designed.

leads-vec-rc

Go to the online dashboard at https://leads-vec-rc.projectneura.org.

Run the following to get a list of all the supported arguments.

leads-vec-rc -h

leads-vec-rc -p 80

If not specified, the port is 8000 by default.

leads-vec-rc -c path/to/the/config/file.json

If not specified, all configurations will be default values.

To learn about the configuration file, read Configurations.

leads-vec-dp path/to/the/workflow.yml

To learn more about workflows, read Workflows.

This section helps you set up the identical environment we have for the VeC project. A more detailed guide of reproduction is available here. After the OS is set up, just run the one-line commands listed below. You may also choose to clone the repository or download the scripts from releases (only stable releases provide scripts).

These scripts currently only support apt as the package manager.

If you install Python using the scripts, you will not find python ..., python3 ..., pip ..., or pip3 ... working because you have to specify the Python interpreter such that python-leads ... and pip-leads ....

You can simply run "setup.sh" and it will install everything including Python 3.12 all the optional dependencies of LEADS for you.

bash "setup.sh$(wget -O setup.sh https://raw.githubusercontent.com/ProjectNeura/LEADS/main/scripts/setup.sh)" && rm setup.sh || rm setup.sh

If you are using a GPIO board that is not a Raspberry Pi, you need to set the environment variable GPIOZERO_PIN_FACTORY to mock.

export GPIOZERO_PIN_FACTORY=mock

If you have registered the Systemd service, this line should be added to the service script as well like shown.

# adjust the arguments according to your needs
export GPIOZERO_PIN_FACTORY=mock
leads-vec -c /usr/local/leads/config.json run

python-install.sh will only install Python 3.12 and Tcl/Tk.

bash "python-install.sh$(wget -O python-install.sh https://raw.githubusercontent.com/ProjectNeura/LEADS/main/scripts/python-install.sh)" && rm python-install.sh || rm python-install.sh

We use FRP for reverse proxy. This is optional if you do not need public connections. If you want, install it through "frp-install.sh".

bash "frp-install.sh$(wget -O frp-install.sh https://raw.githubusercontent.com/ProjectNeura/LEADS/main/scripts/frp-install.sh)" && rm frp-install.sh || rm frp-install.sh

To configure FRP, use "frp-config.sh".

bash "frp-config.sh$(wget -O frp-config.sh https://raw.githubusercontent.com/ProjectNeura/LEADS/main/scripts/frp-config.sh)" && rm frp-config.sh || rm frp-config.sh

There are 4 arguments for this script, of which the first 2 are required.

bash "frp-config.sh$(...)" {frp_server_ip} {frp_token} {frp_port} {comm_port} && rm frp-config.sh || rm frp-config.sh

To uninstall LEADS, we provide an easy solution as well. However, it uninstalls a component only if it is installed through the way listed in Environment Setup.

bash "uninstall.sh$(wget -O uninstall.sh https://raw.githubusercontent.com/ProjectNeura/LEADS/main/scripts/uninstall.sh)" && rm uninstall.sh || rm uninstall.sh

The configuration file is a JSON file that has the following settings. You can have an empty configuration file like the following as all the settings are optional.

{}

Note that a purely empty file could cause an error.

For device-related implicit configurations, please see the devices module.

This only applies to LEADS VeC Data Processor. Please find a more detailed version here.

dataset: "data/main.csv"
inferences:
  repeat: 100  # default: 1
  enhanced: true  # default: false
  assume_initial_zeros: true  # default: false
  methods:
    - safe-speed
    - speed-by-acceleration
    - speed-by-mileage
    - speed-by-gps-ground-speed
    - speed-by-gps-position
    - forward-acceleration-by-speed
    - mileage-by-speed
    - mileage-by-gps-position
    - visual-data-realignment-by-latency

jobs:
  - name: Task 1
    uses: bake
  - name: Task 2
    uses: process
    with:
      lap_time_assertions: # default: []
        - 120  # lap 1 duration (seconds)
        - 180  # lap 2 duration (seconds)
      vehicle_hit_box: 5  # default: 3
      min_lap_time: 60  # default: 30 (seconds)
  - name: Draw Lap 5
    uses: draw-lap
    with:
      lap_index: 4  # default: -1
  - name: Suggest on Lap 5
    uses: suggest-on-lap
    with:
      lap_index: 4
  - name: Draw Comparison of Laps
    uses: draw-comparison-of-laps
    with:
      width: 0.5  # default: 0.3
  - name: Extract Video
    uses: extract-video
    with:
      file: rear-view.mp4  # destination to save the video
      tag: rear  # front, left, right, or rear
  - name: Save
    uses: save-as
    with:
      file: data/new.csv

from leads import controller, MAIN_CONTROLLER
from leads_emulation import RandomController


@controller(MAIN_CONTROLLER)
class MainController(RandomController):
    pass

The devices module will be executed after configuration registration. Register your devices in this module using AOP paradigm. A more detailed explanation can be found here.

These versions were used in practical races:

1. 0.9.5 (Villeneuve) - 2024-10-05 University of Waterloo EV Challenge

Our team management completely relies on GitHub. Tasks are published and assigned as issues. You will be notified if you are assigned to certain tasks. However, you may also join other discussions for which you are not responsible.

You can have a look at the whole schedule of each project in a timeline using the projects feature.

See CONTRIBUTING.md.