From 4164e2a425bf999bbc236dd38c88fce2562a2e69 Mon Sep 17 00:00:00 2001 From: Casey Francis <> Date: Wed, 22 Jun 2022 14:34:28 -0700 Subject: [PATCH] Update README.md Co-Authored-By: Comma Device Co-Authored-By: Willem Melching --- README.md | 199 ++++++++++++++++++++++++++---------------------------- 1 file changed, 96 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index b012883d78428d..8d0cd357bdfe30 100755 --- a/README.md +++ b/README.md @@ -1,142 +1,135 @@ -![](https://i.imgur.com/b0ZyIx5.jpg) +![c2ui](https://user-images.githubusercontent.com/46506059/172867782-b1565062-12c8-40e0-bd4b-0a76bac90e4f.jpg) +*Based off of Keegans stuff* +*This 0.8.14 fork includes the following additions*: -Table of Contents -======================= +- 3 follow distances, 1.8, 1.45, 1.2 m/s (Toyota only) (Thanks @Keegan) +- Red mph when braking (Thanks @alexandresato) +- Legacy engage/disgage sounds +- NEOS 20 for bootloop fix (Thanks @Erich) +- *TORQUE CONTROLLER* +- Steering Fault Fix (Thanks @sshane) +- Device turns off 3 hours after shutting the car down +- Modded fw detection and tuning for eps mod, Civics / CRV. -* [What is openpilot?](#what-is-openpilot) -* [Running in a car](#running-in-a-car) -* [Running on PC](#running-on-pc) -* [Community and Contributing](#community-and-contributing) -* [User Data and comma Account](#user-data-and-comma-account) -* [Safety and Testing](#safety-and-testing) -* [Directory Structure](#directory-structure) -* [Licensing](#licensing) +- If this fork has helped you, please consider donating to my paypal: +- https://www.paypal.com/donate/?hosted_button_id=ZJQD2YEQEFVHY +- ![myqrcode](https://user-images.githubusercontent.com/46506059/172424461-c195174a-6450-4b84-ac25-e8632d49fceb.png) ---- -What is openpilot? ------- -[openpilot](http://github.com/commaai/openpilot) is an open source driver assistance system. Currently, openpilot performs the functions of Adaptive Cruise Control (ACC), Automated Lane Centering (ALC), Forward Collision Warning (FCW) and Lane Departure Warning (LDW) for a growing variety of [supported car makes, models and model years](docs/CARS.md). In addition, while openpilot is engaged, a camera based Driver Monitoring (DM) feature alerts distracted and asleep drivers. See more about [the vehicle integration](docs/INTEGRATION.md) and [limitations](docs/LIMITATIONS.md). - - - - - - - - - - - - - - -
- - -Running in a car +WARNING ------ -To use openpilot in a car, you need four things -* This software. It's free and available right here. -* One of [the 150+ supported cars](docs/CARS.md). We support Honda, Toyota, Hyundai, Nissan, Kia, Chrysler, Lexus, Acura, Audi, VW, and more. If your car is not supported, but has adaptive cruise control and lane keeping assist, it's likely able to run openpilot. -* A supported device to run this software. This can be a [comma two](https://comma.ai/shop/products/two), [comma three](https://comma.ai/shop/products/three), or if you like to experiment, a [Ubuntu computer with webcams](https://github.com/commaai/openpilot/tree/master/tools/webcam). -* A way to connect to your car. With a comma two or three, you need only a [car harness](https://comma.ai/shop/products/car-harness). With an EON Gold or PC, you also need a [black panda](https://comma.ai/shop/products/panda). +**USE OF ANY CODE IN THIS REPOSITORY IS AT YOUR OWN RISK. See Waiver Below** -We have detailed instructions for [how to install the device in a car](https://comma.ai/setup). +**I AM NOT A SOFTWARE ENGINEER AND HAVE NO FORMAL TRAINING OR EXPERIENCE WITH ANY OF THIS. THERE ARE BUGS AND ERRORS IN THIS CODE WHICH IS AT BEST ALPHA QUALITY SOFTWARE AND SHOULD ONLY BE USED FOR RESEARCH PURPOSES. THIS IS NOT A PRODUCT. YOU ARE RESPONSIBLE FOR COMPLYING WITH LOCAL LAWS AND REGULATIONS. NO WARRANTY EXPRESSED OR IMPLIED.** -Running on PC ------- +**You must keep your eyes on the road at all times and be ready to take control of the car at any point.** -All of openpilot's services can run as normal on a PC, even without special hardware or a car. To develop or experiment with openpilot you can run openpilot on recorded or simulated data. -With openpilot's tools you can plot logs, replay drives and watch the full-res camera streams. See [the tools README](tools/README.md) for more information. +--- -You can also run openpilot in simulation [with the CARLA simulator](tools/sim/README.md). This allows openpilot to drive around a virtual car on your Ubuntu machine. The whole setup should only take a few minutes, but does require a decent GPU. +- [WARNING](#warning) +- [What is openpilot?](#what-is-openpilot) +- [What is in this fork?](#what-is-in-this-fork) +- [Will you add something?](#will-you-add-something) +- [Distance Profiles](#distance-profiles) +- [Distance Profile Cost Adjustments](#distance-profile-cost-adjustments) +- [Improve Acceleration from Stop](#improve-acceleration-from-stop) +- [Development Process](#development-process) +- [Licensing](#licensing) +- [WAIVER](#waiver) +--- -Community and Contributing +What is openpilot? ------ -openpilot is developed by [comma](https://comma.ai/) and by users like you. We welcome both pull requests and issues on [GitHub](http://github.com/commaai/openpilot). Bug fixes and new car ports are encouraged. Check out [the contributing docs](docs/CONTRIBUTING.md). +[openpilot](http://github.com/commaai/openpilot) is an open source driver assistance system. + +What is in this fork? +------ +This is my personal fork of openpilot that includes modifications that I want and nothing else. I drive a __2019 Rav4 Hybrid (TSS2)__ most of the modifications were designed for my vehicle and my personal taste and may not work on other vehicles. + +I am publishing this work to help others understand how openpilot works. As such, __I am NOT providing support for installation or troubleshooting.__ If you are looking for a supported fork, I recommend [Shane's Stock Additions](https://github.com/sshane/openpilot) fork. It contains many of the same features. + +Currently this fork contains the following modifications: +* 3 Distance profiles that can be toggled using the distance follow button on the steering wheel. [Feature Toyota Distance Button](https://github.com/krkeegan/openpilot/tree/feature_toyota_distance_btn) + * These profiles are described below. + * There are no on screen messages regarding the distance profile selected, only the icons on the vehicle's HUD. +* Toggle disengage on gas from the settings->toggles screen [Feature Disengage on Gas](https://github.com/krkeegan/openpilot/tree/feature_disengage_on_gas) +* Updates are permanently disabled and must be performed using `ssh` and `git`. [Feature Disable Updates](https://github.com/krkeegan/openpilot/tree/feature_disable_updates_testing_msg) +* Raw toggle added back in to enable automatic log uploading. [Feature Raw Logs](https://github.com/krkeegan/openpilot/tree/feature_raw_logs_upload) +* Lower volume to 70% [Feature Lower Volume](https://github.com/krkeegan/openpilot/tree/feature_lower_volume) +* Improve the starting acceleration off the line. See below. [Feature Slow Start](https://github.com/krkeegan/openpilot/tree/feature_fix_slow_start) +* Specific tuning for my vehicle and my tastes. [Feature Toyota Tune](https://github.com/krkeegan/openpilot/tree/feature_toyota_tune) + * Tweaks deal with the laggy acceleration response on toyotas + * Higher acceleration limit at low speed, lower limit at high speed + * Decrease `a_change_cost` timescale to be closer to toyota lag values +* Other features from future versions of Openpilot as I see fit + +Previous Features that have been Merged into Comma Repo: +* Display blue barriers when openpilot is engaged. +* Use wide camera for light sensor, better night performance. + +Will you add something? +--- +You can certainly ask, but the criteria for adding it is: -Documentation related to openpilot development can be found on [docs.comma.ai](https://docs.comma.ai). Information about running openpilot (e.g. FAQ, fingerprinting, troubleshooting, custom forks, community hardware) should go on the [wiki](https://github.com/commaai/openpilot/wiki). +* Is it something I would use +* Is it something I consider safe? I am pretty cautious. +* Is it easy to maintain? I don't want this to be a chore to maintain. -You can add support for your car by following guides we have written for [Brand](https://blog.comma.ai/how-to-write-a-car-port-for-openpilot/) and [Model](https://blog.comma.ai/openpilot-port-guide-for-toyota-models/) ports. Generally, a car with adaptive cruise control and lane keep assist is a good candidate. [Join our Discord](https://discord.comma.ai) to discuss car ports: most car makes have a dedicated channel. +If the answer to any of those is __no__, then I probably won't add it. -Want to get paid to work on openpilot? [comma is hiring](https://comma.ai/jobs/). +Distance Profiles +--- +I extrapolated out the speeds, so that the distance is set about every ~5mph. This just makes it easier to edit. -And [follow us on Twitter](https://twitter.com/comma_ai). +* Stock - Unchanged, this uses the default settings in openpilot with follow time of 1.45s. +* Relaxed - This is set to 1.25s across the board. +* Traffic - At low speeds this is set to 1.25s and gradually drops down to 1.05s at freeway speeds. -User Data and comma Account ------- +Distance Profile Cost Adjustments +--- +As the following distance decreases I have decreased the `jerk` and `a_change` costs and increased the `danger` cost. This is to be expected, as the follow distance decreases the allowable rate of change in deceleration has to increase, this will make the acceleration more jerky. Below is an example of this, as you can see the relaxed and traffic profiles start off following the lead closer, and then when the lead starts to slow down, they increase their rate of deceleration much faster: + +![deceleration compared](https://user-images.githubusercontent.com/3046315/148848058-01d3b410-79c2-409a-ab5c-336f21ef8fd9.png) + +Improve Acceleration from Stop +--- +The new MPC introduced in 8.10 has a much slower acceleration profile from a standstill. This is caused by many things, but is largely driven by the `a_change_cost` which was introduced as part of the lag compensation. As you can see below, the rate of acceleration significantly lags behind 8.9: -By default, openpilot uploads the driving data to our servers. You can also access your data through [comma connect](https://connect.comma.ai/). We use your data to train better models and improve openpilot for everyone. +![8.9 v 8.12](https://user-images.githubusercontent.com/3046315/148848373-7737a46e-a547-48f2-88ec-c2861d42e1ee.png) -openpilot is open source software: the user is free to disable data collection if they wish to do so. +I have made adjustments to the `jerk` and `a_change` costs to allow for a faster change in acceleration at low speeds, this affects acceleration only and will not alter braking. I also reduced the `STOP_DISTANCE` dynamically so that when the lead car pulls away, the MPC is told to maintain a closer distance, this helps cause the an earlier initial acceleration request. The changes result in the improved profile seen below: -openpilot logs the road facing cameras, CAN, GPS, IMU, magnetometer, thermal sensors, crashes, and operating system logs. -The driver facing camera is only logged if you explicitly opt-in in settings. The microphone is not recorded. +![8.12 v KRK](https://user-images.githubusercontent.com/3046315/148849415-2212361b-4bde-43c2-8f12-bbcdf6d833dd.png) -By using openpilot, you agree to [our Privacy Policy](https://comma.ai/privacy). You understand that use of this software or its related services will generate certain types of user data, which may be logged and stored at the sole discretion of comma. By accepting this agreement, you grant an irrevocable, perpetual, worldwide right to comma for the use of this data. +Development Process +--- -Safety and Testing ----- +The comma.ai repository is a [complicated beast](https://blog.comma.ai/a-2020-theme-externalization/). The releases are are compiled stripped down repositories. I prefer to base my daily driver fork `Rav4-TSS2` off of the `commaai/devel` branch. However, this branch lacks the suite of automated tests. So I create my development branches off of `commaai/master`. I try to pick the commit that is closest to the release version and make a branch `master-x.xx` with x.xx being the release version number. -* openpilot observes ISO26262 guidelines, see [SAFETY.md](docs/SAFETY.md) for more details. -* openpilot has software in the loop [tests](.github/workflows/selfdrive_tests.yaml) that run on every commit. -* The code enforcing the safety model lives in panda and is written in C, see [code rigor](https://github.com/commaai/panda#code-rigor) for more details. -* panda has software in the loop [safety tests](https://github.com/commaai/panda/tree/master/tests/safety). -* Internally, we have a hardware in the loop Jenkins test suite that builds and unit tests the various processes. -* panda has additional hardware in the loop [tests](https://github.com/commaai/panda/blob/master/Jenkinsfile). -* We run the latest openpilot in a testing closet containing 10 comma devices continuously replaying routes. +To make merging with future versions of Openpilot easier, I try to keep each "feature" on its own branch. My branches that start with `feature_` contain additional features or tweaks that have not been upstreamed into `commaai/master`. My branches that start with `future_` contain commits that have been developed by `commaai` but were not included in the last release and are likely to be included in the next release. Branches prefixed with `research_` are test branches that are likely used for running simulations and may not be designed for use in the real-world. -Directory Structure ------- - . - ├── cereal # The messaging spec and libs used for all logs - ├── common # Library like functionality we've developed here - ├── docs # Documentation - ├── opendbc # Files showing how to interpret data from cars - ├── panda # Code used to communicate on CAN - ├── third_party # External libraries - ├── pyextra # Extra python packages - └── selfdrive # Code needed to drive the car - ├── assets # Fonts, images, and sounds for UI - ├── athena # Allows communication with the app - ├── boardd # Daemon to talk to the board - ├── camerad # Driver to capture images from the camera sensors - ├── car # Car specific code to read states and control actuators - ├── common # Shared C/C++ code for the daemons - ├── controls # Planning and controls - ├── debug # Tools to help you debug and do car ports - ├── locationd # Precise localization and vehicle parameter estimation - ├── logcatd # Android logcat as a service - ├── loggerd # Logger and uploader of car data - ├── modeld # Driving and monitoring model runners - ├── proclogd # Logs information from proc - ├── sensord # IMU interface code - ├── test # Unit tests, system tests, and a car simulator - └── ui # The UI +Once I am satisfied with a branch and it has passed the automated tests, or failed for understandable reasons, I cherry-pick the commits into `Rav4-TSS2`. Sometimed I may create a `Rav4-TSS2-____` branch if I want to test changes in the vehicle before commiting them to my daily driver branch. + +It is all a mess, and it would make working off of my branches difficult, but since this is primarily for personal use, it works for me. Licensing ------ openpilot is released under the MIT license. Some parts of the software are released under other licenses as specified. -Any user of this software shall indemnify and hold harmless Comma.ai, Inc. and its directors, officers, employees, agents, stockholders, affiliates, subcontractors and customers from and against all allegations, claims, actions, suits, demands, damages, liabilities, obligations, losses, settlements, judgments, costs and expenses (including without limitation attorneys’ fees and costs) which arise out of, relate to or result from any use of this software by user. +WAIVER +----- + +Any user of this software ("User") and anyone claiming on User's behalf releases and forever discharges the "Author" of this fork and its directors, officers, employees, agents, stockholders, affiliates, subcontractors, software contributors, and customers from any and all claims, liabilities, obligations, promises, agreements, disputes, demands, damages, causes of action of any nature and kind, known or unknown, which User has or ever had or may in the future have against Author or any of the related parties arising our of or relating to the use of any software in this Repository. + +User shall indemnify and hold harmless Author and its directors, officers, employees, agents, stockholders, affiliates, subcontractors, software contributors, and customers from and against all allegations, claims, actions, suits, demands, damages, liabilities, obligations, losses, settlements, judgments, costs and expenses (including without limitation attorneys’ fees and costs) which arise out of, relate to or result from any use of this software by user. **THIS IS ALPHA QUALITY SOFTWARE FOR RESEARCH PURPOSES ONLY. THIS IS NOT A PRODUCT. YOU ARE RESPONSIBLE FOR COMPLYING WITH LOCAL LAWS AND REGULATIONS. NO WARRANTY EXPRESSED OR IMPLIED.** ---- - - - -[![openpilot tests](https://github.com/commaai/openpilot/workflows/openpilot%20tests/badge.svg?event=push)](https://github.com/commaai/openpilot/actions) -[![Total alerts](https://img.shields.io/lgtm/alerts/g/commaai/openpilot.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/commaai/openpilot/alerts/) -[![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/commaai/openpilot.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/commaai/openpilot/context:python) -[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/commaai/openpilot.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/commaai/openpilot/context:cpp) -[![codecov](https://codecov.io/gh/commaai/openpilot/branch/master/graph/badge.svg)](https://codecov.io/gh/commaai/openpilot)