{"id":16360087,"url":"https://github.com/frgfm/sdcnd-pid-control","last_synced_at":"2025-12-31T19:30:24.834Z","repository":{"id":110056651,"uuid":"254396807","full_name":"frgfm/sdcnd-pid-control","owner":"frgfm","description":"PID Control project of Udacity Self-Driving Car Nanodegree","archived":false,"fork":false,"pushed_at":"2020-04-09T18:29:47.000Z","size":1776,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-12-29T17:41:35.306Z","etag":null,"topics":["catch2","clang-format","cpp","pid-control","self-driving-car","spdlog"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/frgfm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-09T14:38:59.000Z","updated_at":"2020-04-09T18:23:17.000Z","dependencies_parsed_at":"2023-05-20T21:00:32.408Z","dependency_job_id":null,"html_url":"https://github.com/frgfm/sdcnd-pid-control","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frgfm%2Fsdcnd-pid-control","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frgfm%2Fsdcnd-pid-control/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frgfm%2Fsdcnd-pid-control/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frgfm%2Fsdcnd-pid-control/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frgfm","download_url":"https://codeload.github.com/frgfm/sdcnd-pid-control/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239727059,"owners_count":19687096,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["catch2","clang-format","cpp","pid-control","self-driving-car","spdlog"],"created_at":"2024-10-11T02:10:31.212Z","updated_at":"2025-12-31T19:30:24.432Z","avatar_url":"https://github.com/frgfm.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PID Control\n[![License](https://img.shields.io/badge/License-MIT-brightgreen.svg)](LICENSE) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/7c96f65f3e2f42cbb15de23938e084a4)](https://www.codacy.com/manual/frgfm/sdcnd-pid-control?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=frgfm/sdcnd-pid-control\u0026amp;utm_campaign=Badge_Grade) ![Ubuntu build](https://github.com/frgfm/sdcnd-pid-control/workflows/cpp-build/badge.svg) \n\nPID Control project of Udacity Self-Driving Car Nanodegree (cf. [repo](https://github.com/udacity/CarND-PID-Control)).\n\n![sim-result](static/images/result.gif)\n\n\n\n## Table of Contents\n\n- [Getting Started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n- [Usage](#usage)\n- [Approach](#Approach)\n- [Credits](#credits)\n- [License](#license)\n\n\n\n## Getting started\n\n### Prerequisites\n\n- [Unity3D](https://unity3d.com/get-unity/download): 3D game engine used for our simulation.\n- make (\u003e= 4.1 on Linux, Mac, \u003e= 3.81 on Windows): the buildsystem of the project.\n  - Linux: make is installed by default on most Linux distros\n  - Mac: [install Xcode command line tools to get make](https://developer.apple.com/xcode/features/)\n  - Windows: [Click here for installation instructions](http://gnuwin32.sourceforge.net/packages/make.htm)\n- [cmake](https://cmake.org/install/) 3.5 (or newer): buildsystem generator.\n  - Any OS: [click here for installation instructions](https://cmake.org/install/)\n- [gcc](https://gcc.gnu.org/)/g++ 5.4 (or newer): to compile the C++ code.\n  - Linux: gcc / g++ is installed by default on most Linux distros\n  - Mac: same deal as make - [install Xcode command line tools](https://developer.apple.com/xcode/features/)\n  - Windows: recommend using [MinGW](http://www.mingw.org/)\n- [uWebSockets 0.13.0](https://github.com/uNetworking/uWebSockets/archive/v0.13.0.tar.gz): to handle our web-server.\n  - Linux/Mac: [click here for installation instructions](https://github.com/uWebSockets/uWebSockets)\n  - Windows: use either Docker, VMware, or even [Windows 10 Bash on Ubuntu](https://www.howtogeek.com/249966/how-to-install-and-use-the-linux-bash-shell-on-windows-10/) to install uWebSocketIO\n- [json](https://github.com/nlohmann/json): to interact with JSON files *(header-only)*.\n  - Any OS: place the [file](https://github.com/nlohmann/json/releases/download/v3.7.3/json.hpp) in the  `include/` folder\n- [Catch](https://github.com/catchorg/Catch2): for unittests *(header-only)*\n  - Any OS: place the [file](https://github.com/catchorg/Catch2/releases/download/v2.11.3/catch.hpp) in the `lib/` folder\n- [spdlog](https://github.com/gabime/spdlog): for console logging *(header-only)*\n  - Any OS: extract the [archive](https://github.com/gabime/spdlog/archive/v1.5.0.tar.gz) and place the `include/spdlog` directory in the  `include/` folder\n\n*Note: If you are running a Unix system, the installation scripts in the folder `scripts/` will install all the requirements apart from Unity3D. From the repository's main directory, run `bash scripts/install-linux.sh` for Linux or run `bash scripts/install-mac.sh` for MacOS to install those dependencies.*\n\n### Installation\n\n#### C++\n\nYour folder hierarchy should look like below:\n\n```\n.\n├── CMakeLists.txt\n├── include\n│   ├── json.hpp\n│   └── spdlog\n├── lib\n│   └── catch.hpp\n├── LICENSE\n├── README.md\n├── scripts\n│   ├── format-project.sh\n│   ├── install-cppdeps.sh\n│   ├── install-linux.sh\n│   └── install-mac.sh\n├── src\n│   ├── helpers.cpp\n│   ├── helpers.h\n│   ├── main.cpp\n│   ├── PID.cpp\n│   └── PID.h\n├── static\n│   └── images\n└── test\n    ├── helpers_test.cpp\n    └── main_test.cpp\n```\n\nNow you can build the project:\n\n```bash\nmkdir build \u0026\u0026 cd build\ncmake .. \u0026\u0026 make \u0026\u0026 cd ..\n```\n\n\n\n#### Unity\n\nAfter installing Unity3D, you will need an environment build to run the simulation. Download the appropriate build for your OS and extract it:\n\n- [Linux](https://github.com/udacity/self-driving-car-sim/releases/download/v1.45/term2_sim_linux.zip)\n- [Mac](https://github.com/udacity/self-driving-car-sim/releases/download/v1.45/term2_sim_mac.zip)\n- [Windows](https://github.com/udacity/self-driving-car-sim/releases/download/v1.45/term2_sim_windows.zip)\n\nIf you encounter an issue with the above builds, please refer to the \"Available Game Builds\" section of this [readme](https://github.com/udacity/self-driving-car-sim).\n\n\n\n## Usage\n\n### Unittests\n\nBy compiling the project previously, you created 2 executables. One of them is here to run unittests using [Catch2](https://github.com/catchorg/Catch2). In order to run the tests, use the following command:\n\n```bash\nbuild/tests\n```\n\nwhich should yield something similar to:\n\n```shell\n===============================================================================\nAll tests passed (4 assertions in 2 test cases)\n```\n\n\n\n### Project build\n\nRun the recently built project using the following command:\n\n```\nbuild/pid\n```\n\nThe compiled program is now listening to events on port `4567` using a web server. We just need to run our Unity3D environment to see the results.\n\n- Run the `term2_sim` executable after extracting the environment archive *(you might have to make it executable on Unix systems)*.\n- Select the Resolution and Graphics settings for your setup.\n- Click on `Next` until you reach `Project 4: PID Controller`\n- Click on `SELECT`\n\n\n\n## Approach\n\nThis project involves an agent (vehicle on a highway) exposed to continuous state and action spaces. The environment is not interactive for the user, the only accepted input is the predicted steering angle of the vehicle.\n\n### Environment\n\nThis Unity environment offers a car driving experience on a single track. \n\n![track_env](static/images/track_env.png)\n\nThe autonomous mode lets the developer plug a C++ program through a web server that handles the car controls.\n\nPlease refer to this [repository](https://github.com/udacity/self-driving-car-sim) for further details.\n\n\n\n### Implementing a PID controller\n\nWe follow the description of a PID control unit\n\n![PID control](https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/PID_en.svg/800px-PID_en.svg.png)\n\nHere we consider mainly the cross-track error (CTE) for our controller. The PID controller works as follows:\n\n- the `Kp` coefficient scales the steering proportional to CTE. If this is only a P-controller, we would get strong oscillations.\n- the `Kd` coefficient adds a component scaling with the variations of CTE, which smooths the proportional correction. If this is only a PD controller, our system would easily be disturbed by imperfect control.\n- the `Ki` coefficient adds the last component that scales with the primitive of CTE (sum of CTE values for discrete signals), which normalizes our error in regards to control noise.\n\n\n\nIn the `src` folder, you will find:\n\n- `main`: reads measurement data from Unity3D and runs the PID controller.\n- `PID`: handles the PID error computation.\n- `Monitor`: handles performance evaluation.\n- `helpers`: unit conversion and data reading.\n\nAfter a few manual iterations, by tweaking the coefficients to reduce oscillations, the following values were selected:\n\n- `Kp = 0.15`\n- `Ki = 0.004`\n- `Kd = 3.0`\n\n\n\n### Results\n\nThe previously mentioned implementation yields an acceptable driving behaviour in regards to lane keeping as shown below.\n\n![sim-result](static/images/result.gif)\n\nThe implementation is evaluated using two metrics: the CTE to make sure the vehicle stays on target, and the mean angular acceleration that reflects the passenger comfort.\n\n| avg CTE   | avg angular acceleration |\n| --------- | ------------------------ |\n| 0.5777326 | 0.11831327               |\n\n\n\nThe full-length lap recording in third-person view is available for download in the release attachments:\n\n- [Full lap recording](https://github.com/frgfm/sdcnd-pid-control/releases/download/v0.1.0/lap_recording.mp4)\n\n\n\n## Limitations and improvements\n\nCurrently, the implementation feels a bit shaky and could be improved further. Here are a few leads to investigate:\n\n1. Automatic hyperparameter tuning: run on a different track to tune gains in regards to average CTE.\n2. Further than PID: taking a step back to proportional correction, the CTE might not be the best error to look at. If we aim at getting a CTE of zero within 5m, then the interesting value would be `atan(cte / 5)`. While for small values, the first order Taylor expansion makes it equivalent to CTE near 0, it is not true for the entire range of values.\n\n\n\n## Credits\n\nThis implementation is vastly based on the following methods:\n\n- [PID Control](https://en.wikipedia.org/wiki/PID_controller)\n\n\n\n## License\n\nDistributed under the MIT License. See `LICENSE` for more information.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrgfm%2Fsdcnd-pid-control","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrgfm%2Fsdcnd-pid-control","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrgfm%2Fsdcnd-pid-control/lists"}