├── .DS_Store ├── Guides └── Hyundai_MDPS_Comma_Harness.pdf ├── LICENSE ├── PICS ├── MDPS ECU view 1.png ├── MDPS ECU view 2.png └── SPAS thumbnail.png └── README.md /.DS_Store: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Circuit-Pro/openpilot/1b86f1997e10f4e4734a43d507b50993933d8474/.DS_Store -------------------------------------------------------------------------------- /Guides/Hyundai_MDPS_Comma_Harness.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Circuit-Pro/openpilot/1b86f1997e10f4e4734a43d507b50993933d8474/Guides/Hyundai_MDPS_Comma_Harness.pdf -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2018, Comma.ai, Inc. 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 4 | 5 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 6 | 7 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 8 | -------------------------------------------------------------------------------- /PICS/MDPS ECU view 1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Circuit-Pro/openpilot/1b86f1997e10f4e4734a43d507b50993933d8474/PICS/MDPS ECU view 1.png -------------------------------------------------------------------------------- /PICS/MDPS ECU view 2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Circuit-Pro/openpilot/1b86f1997e10f4e4734a43d507b50993933d8474/PICS/MDPS ECU view 2.png -------------------------------------------------------------------------------- /PICS/SPAS thumbnail.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Circuit-Pro/openpilot/1b86f1997e10f4e4734a43d507b50993933d8474/PICS/SPAS thumbnail.png -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | **OpenPilot 0.8.14 Community Fork for Hyundai, Kia, and Genesis!** 2 | ------------------ 3 | 4 | **The software sources are after the install section.** 5 | 6 | **This fork is Community Supported!** 7 | ------------------------ 8 | 9 | We **appreciate** all help! Anywhere we get it! 10 | To get involved join us on discord or Contribute to the project with code or help support the project by donating. 11 | 12 | - https://discord.gg/zWSnqJ6rKD 13 | 14 | - Donating helps me dedicate more time and effort into this project. It also gives me more time to make for helping people. 15 | 16 | - https://www.patreon.com/Circuit_Pro 17 | 18 | 20 | PayPal this 22 | 23 | 24 | **Liability** 25 | ------------ 26 | 27 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE 28 | 29 | **DO NOT USE SPAS WITHOUT UNDERSTANDING, HOW IT WORKS AND WHAT IT DOES, YOU ACCEPT ALL LIABILITY.** 30 | 31 | **It is open source and inherits MIT license. By installing this software you accept all responsibility for anything that might occur while you use it. All contributors to this fork are not liable.** Use at your own risk. 32 | 33 | **By using this software you are responsible for anything that occurs while OpenPilot is engaged or disengaged. Be ready to take over at any moment. Fork contributers assumes no liability for your use of this software and any hardware.** 34 | 35 | **Please join our Discord!** 36 | --------------- 37 | 38 | https://discord.gg/zWSnqJ6rKD 39 | 40 | **Submit issues on the issues page or in a detailed report on GitHub issues page. For quick help post in issues channel on our discord server.** 41 | 42 | **Longitudinal Info** 43 | ---------------------- 44 | 45 | This fork uses the SCC Gap Setting on cluster to display how far a lead is when a lead is there. When there is no lead a "driving" animation will display on screen with scrolling gap bars that change in speed with vehicle speed. 46 | 47 | This fork has full long control for all HKG with radar harness(AEB should work for FCA11 and FCA12 cars) and Radar Disable(NO AEB OR FCA!!!). All other cars should require scc to be moved to bus 2 from bus 0 for full long control. 48 | 49 | - Reach out to **oricalworks#5623** on discord to buy a radar harness. 1 & 1/2 week lead time depending on location of parts. 50 | - SCC ECU / Radar Harness **SHOULD** preserve Automatic Emergency Braking(FCA) and Evasive Manuver Assist on **MOST** vehicles. Tested on 2018 Kia Stinger 2.0L Premium. 51 | 52 | **Radar Disable** 53 | ---------------------- 54 | 55 | **!!NO AEB OR FCA!!** 56 | 57 | Make sure the car is OFF. 58 | 59 | Under `Community` set the `Radar Disable` and `HKG Long` toggle to the ON position and reboot device and restart car. 60 | 61 | **Enable Radar Tracks** 62 | ----------------------- 63 | 64 | Make sure the car is OFF. 65 | 66 | Then run this from SSH. 67 | 68 | `killall boardd; python /data/openpilot/selfdrive/debug/hyundai_enable_radar_points.py` 69 | 70 | Follow instrucions from script. Reboot and restart car; make sure no errors on dash. 71 | 72 | Turn on `Are Radar Tracks Enabled?` Toggle. 73 | 74 | Then reboot and restart car. 75 | 76 | For a more detailed look at this, take a look at this great write up by Sunnyhaibin - https://github.com/sunnyhaibin/openpilot/blob/(!)README/HOW-TOS.md#radar-tracks 77 | 78 | **HKG MAD Mode** 79 | ----------------- 80 | 81 | HKG Modified Assistive Driving Mode (MAD) allows openpilot's Automatic Lane Centering (ALC) and Adaptive Cruise Control (ACC) / Smart Cruise Control (SCC) to be engaged independently of each other. 82 | 83 | openpilot's ALC and ACC/SCC can be engaged independently of each other. 84 | 85 | Dedicated button to toggle openpilot ALC: 86 | 87 | `CRUISE (MAIN)`: Toggle ALC 88 | 89 | `SET`: engage ACC/SCC 90 | 91 | `CANCEL`: only disengage ACC/SCC 92 | 93 | BRAKE pedal press will disengage openpilot ACC/SCC 94 | 95 | BRAKE pedal press will **NOT** disengage openpilot ALC 96 | 97 | GAS pedal press will **NOT** disengage openpilot ALC or ACC/SCC 98 | 99 | 100 | **RSPA** 101 | ------------- 102 | 103 | !! WIP !! 104 | 105 | **SPAS** 106 | ------------- 107 | Before! testing SPAS steering, ↓↑ !BE SURE TO READ ALL OF THE SPAS SECTION AND UNDERSTAND HOW IT WORKS! ↑↓; Be aware of all the safety concerns with USING ALL OF THE TORQUE that the MDPS/EPS motor can provide! ! KEEP HANDS ON WHEEL AND EYES ON ROAD AT ALL TIMES ! You are responsible for actions of car engaged or not engaged! 108 | 109 | 110 | 111 | SPAS stands for Smart Parking Assist System. Your vehicle does not need to be equiped with this feature to use it. To use this an MDPS harness is required! 112 | Most H.K.G. MDPS will accept these messages. This is currently reported to be working on vehicles 2019 and under, with newer vehicles needing more work due to tighter tolerances on logic, more checks, and new checksums on RSPA. To get a new vehicle working you need to set the `ret.emsType = _` for your vehicle if one is not set. 113 | 114 | **Which EMS am I?** 115 | 116 | Register your device to RetroPilot. Then go for a short drive and grab a cabana for your car, Then use the "Kia_Hyundai_Generic" DBC. Search for EMS and see which EMS your vehicle uses. Then set `ret.emsType = ` : N/A = 0 : EMS366 = 1 : EMS11 = 2 : E_EMS11 = 3 : 117 | Reach out with any questions or to get help with EMS types not listed, join our discord and ask in the spas channel. 118 | 119 | - To use this an MDPS harness is required. 120 | - MDPS stands for Motor Driven Power Steering. 121 | - Panda safety is in a working state and needs more testing and edge case tuning, I.E. The rate limit's for the steering wheel SPAS is set conservatively and may need some increasing. 122 | - Just because there is panda safety code **PLEASE** do not ever fully assume it is safe, especially since this is so new! Remember this is using the **ENTIRE** force of the MDPS/EPS Motor! 123 | - This works by faking the vehicle speed **ONLY** to the MDPS when it's in state 5 (SPAS Steer/Assist) and sending an angle to MDPS to execute. 124 | - OpenPilot currently switches to LKAS steering at 30MPH automatically. If the tune of LKAS steering is not good and stable there can be a noticeable transition on a curve. Although if your vehicle is properly tuned you should have no issues, In all of my testing. 125 | - Dynamic SPAS Activates SPAS on certain driving conditions under 60MPH. 126 | - When LKAS is not active, the controlers are being reset to prevent upwind or unwind issues. 127 | - OpenPilot and Panda are monitoring driver torque from MDPS11. The correct one for use with SPAS. When OpenPilot detects a force being applied to wheel that's greater than the set limit of 2.85Nm. Panda will call a violation and controls not allowed if this higher limit is reached. Panda's limit is set greater than OpenPilots so it won't cause controls mismatch and interference due to it blocking signals when this is violated. - PANDA DRIVER TORQUE MONITORING TEMPORARILY DISABLED - Need to send MDPS into state 7 first before tx = 0 from panda not Openpilot 128 | - OpenPilot is appying a rate limit up and down to the sent steering angles and Panda is enforcing this. NOTE Panda's SPAS up and down rate limits are set conservatively and may require some adjusting. The result of panda calling a violation, will cause a controls mismatch. 129 | - Panda is enforcing that SPAS is off when controls not allowed or not engaged. 130 | - If driver torque is detected above set limit with SPAS on and under 38Mph, OpenPilot will disengage unless dynamic SPAS is active with the LKAS switch toggle. 131 | - **! KEEP HANDS ON WHEEL AND EYES ON ROAD AT ALL TIMES !** 132 | 133 | **Before!** testing SPAS steering, **↓↑ !BE SURE TO READ ALL OF THE SPAS SECTION AND UNDERSTAND HOW IT WORKS! ↑↓**; Be aware of all the safety concerns with **USING ALL OF THE TORQUE** that the MDPS/EPS motor can provide! **! KEEP HANDS ON WHEEL AND EYES ON ROAD AT ALL TIMES !** You are **responsible** for actions of car engaged or not engaged! 134 | 135 | ***Open Street Maps!*** 136 | --------------------- 137 | - Speed limit wrong or missing? Contribute to Open Street Maps in your area! https://www.openstreetmap.org 138 | - Special Thanks to the Move-Fast Team for all the help and hard work with OSM! 139 | - With an active internet connection, and HKG Long, OpenPilot can plan ahead using vision and map data to slow for curves and adjust the longitudinal plan for speed limit and other factors. 140 | - Cruise speed does not adjust SCC max set speed, OSM instead adjusts longitudinal plan. So for it to work set max SCC speed higher than speed limit. To override speed limit tap on speed limit symbol on screen in top left corner next to max speed. 141 | - All Settings are under `Toggles` in `Settings`. 142 | - We have the correct DBC for newer Hyundais; 2019+ with built in navigation. To pull the speed limit information from head unit over can bus. Toggle `Pull Hyundai Navigation Speed Limit` to the ON position and OSM will use both the OSM API and the cars Head Unit GPS/Navigation reported speed limit information to decide the speed limit. 143 | - https://www.youtube.com/watch?v=hTuvA6o6gjY 144 | 145 | ***HKG Long control toggle. (radar + vision)*** 146 | ----------------------------------------------- 147 | - When toggled on, replaces the default Hyundai / Kia / Genesis factory longitudinal control system (SCC) with the openpilot system. 148 | - Lead markers are not available unless you have HKG long toggle on; this is not a method to determine if longitudinal is working. 149 | - Radar harness or mod is needed. 150 | - Move SCC ECU / RADAR to bus 2. 151 | - Radar Off CAN but expected from car. 152 | - Radar Disable (Diagnostics Mode) !**Vision only**! **!AEB and FWC DISABLED!** 153 | 154 | ***RetroPilot*** 155 | ---------------- 156 | 157 | This fork uses RetroPilot for logging and online services. https://api.retropilot.org/useradmin 158 | 159 | Make sure "Upload Raw Logs" and "Enable Logger / Uploader" are both ON for this to work. 160 | 161 | **Performance** 162 | --------------- 163 | 164 | The Comma 3 has great performance with this fork. 165 | 166 | The **Comma 2** has **POOR** performance with logging and uploader enabled so it's disabled by default. You can change that in `Settings` under `Community`. 167 | 168 | **Hardware** 169 | ------------ 170 | 171 | **MDPS Harness** are available if you have the newer style plug and or 2015 - 2016 Genesis. Contact johnpr#5623 on discord for more information. 172 | 173 | - 2015 - 2016 Genesis requires some work to install please review this guide from Ahmed Barnawi. This guide is centered around SMDPS but from page (2 - 7) is no different for MDPS harness installation. If you have a MDPS Harness kit skip right on past step 1, 2, & 3 of "Execution" on page 2 and start from there. The MDPS harness connects between comma power and RJ45 from the Car Harness Box. https://github.com/Circuit-Pro/openpilot/blob/main/Guides/Hyundai_MDPS_Comma_Harness.pdf 174 | 175 | - Newer style plug for MDPS ECU located in cabin (Most likely up under the steering wheel.) is plug and play. MDPS harness connects between comma power and RJ45 from the Car Harness Box. The MDPS ECU data connector(CAN L, H, and IGN) gets unplugged from MDPS ECU and this connector that just got unplugged gets plugged into female of harness and the male MDPS harness connector will replace where the MDPS ECU data connector(CAN L, H, and IGN) **originally** was. I.E. MDPS ECU Data female socket. Avoid touching MDPS ECU Power connector and any others. 176 | - 177 | 178 | **Radar Harness** for Kia Stinger, G70, Niro, and Ioniq are available. Varying lead time based on location of radar connector. Contact johnpr#5623 on discord for more information. 179 | 180 | **Notes** 181 | --------- 182 | 183 | Make sure to **shut off** auto start stop or you will get steering temporarily unavailable if the engine shuts off. 184 | 185 | **Screen Recordings** 186 | 187 | - Comma 3 Storage Location. `/storage/emulated/0/videos` 188 | 189 | - Comma 2 Storage Location. `/data/media/0/videos` 190 | 191 | **Features** 192 | ------------ 193 | 194 | **Click** any of the settings to get a breif description in OpenPilot settings. 195 | 196 | **Loading Logo** 197 | 198 | The loading logo is automatically set to your HKG cars brand after the first boot, first car start, first reboot, and resets on update. 199 | 200 | ***nTune*** 201 | 202 | - nTune Auto Tunes lateral LQR steering and some SCC/Long settings like accuation delay upper and lower bounds, gas factor, and brake factor.= 203 | 204 | Run **nTune** in middle of drive: Use this command `cd selfdrive && python ntune.py` or use the button in `Settings` under `Device`. (make sure your not driving!) 205 | 206 | **Delete UI Screen Recordings button in `Settings` under `Device`.** 207 | 208 | **Toggles** 209 | 210 | - Toggles are in `Settings` under `Community` & `Device`. 211 | 212 | ***Cluster Speed*** 213 | 214 | - Uses the speed of the gauge cluster instead Wheel speeds. 215 | 216 | ***LDWS toggle*** 217 | 218 | - under `Community` in `Settings`. For cars with LDWS but not SCC. 219 | 220 | ***Show Debug UI*** 221 | 222 | - I feel like you should understand what “debugging” and a “UI” are before you can use openpilot 223 | 224 | ***Use SMDPS Harness*** 225 | 226 | - Use of MDPS Harness to enable openpilot steering down to 0 MPH 227 | 228 | ***On screen blinkers and blind spot alerts.*** 229 | 230 | - Your choice of Neokii or Crwusiz on screen blinkers with Crwusiz on-screen Blind Spot Monitoring indicators. 231 | 232 | ***Enable Lane Change Assist*** 233 | 234 | - allows openpilot to change lanes. Driver is responsible for ensuring that it is SAFE to change lanes. Requires signal, and steering wheel nudge. 235 | 236 | ***Auto Lane Change with Blind spot monitoring toggle (No Nudge).*** 237 | 238 | - Same as the original, now with 100% less nudge. 239 | 240 | ***Sync Speed on Gas Press*** 241 | 242 | - openpilot will sync cruise control set speed to match last attained speed automatically 243 | 244 | ***Make sure to reboot with toggle changes.*** 245 | 246 | Then give it a spin. 247 | 248 | ***Behavior Notes*** 249 | -------------------- 250 | 251 | OpenPilot HKG Long will not see totally stopped cars yet until E2E comes in 0.9 so do not trust it to see and stop for a COMPLETLY stopped car. 252 | 253 | If Collision Warning is beeping at you OpenPilot has calculated it can't stop quick enough due to safety limitations on unintentional braking. Please apply brakes to avoid collision. 254 | 255 | ***Install*** 256 | ------------ 257 | 258 | **Comma 3** 259 | 260 | Put this url during setup for Stable `https://smiskol.com/fork/Circuit-Pro/stable` 261 | 262 | Put this url during setup for Stable Open Street Maps `https://smiskol.com/fork/Circuit-Pro/stable_OSM` 263 | 264 | **Comma 2** 265 | 266 | Put this url during setup for Stable `https://smiskol.com/fork/Circuit-Pro/stable` 267 | 268 | ***If you installed from SSH*** 269 | 270 | - make sure too run `rm /data/params/d/DongleId` to reset your dongle ID. 271 | 272 | **Panda Issues** 273 | ---------------- 274 | Make sure to run the `./recover.sh` while car is off, otherwise it won't find the device. If it still can't find the device, unplug comma for 5 min and plug it back in and run `./recover.sh` again. 275 | 276 | **Comma 3** 277 | 278 | Try this first; refer to instructions above, if this does not work. - `pkill -f openpilot; cd panda/board; ./recover.sh; sudo reboot` 279 | 280 | `pkill -f openpilot; cd panda/board; ./flash.sh; sudo reboot` 281 | 282 | **Comma 2** 283 | 284 | Try this first; refer to instructions above, if this does not work. - `pkill -f openpilot; cd panda/board; ./recover.sh; reboot` 285 | 286 | `pkill -f openpilot; cd panda/board; ./flash.sh; reboot` 287 | 288 | **xx979xx's Debugging Tools:** 289 | -------------------------- 290 | To print debug info for Panda and Harness issue: 291 | 292 | `python panda/tests/debug_console.py` 293 | To print Opentpilot live data: 294 | 295 | `python selfdrive/debug/dump.py ` 296 | replace with any one of these: `health carState carControl controlsState carParams sendcan can` 297 | 298 | **This is based on xx979xx & Neokii's & crwusiz's fork and is tuned best 2.0L Kia Stinger, and works on others... Please submit a tune to our discord if you find a better one.** 299 | 300 | **Software Sources!** 301 | ---------------------------- 302 | 303 | https://github.com/neokii/op4 304 | 305 | https://github.com/xx979xx/openpilot 306 | 307 | https://github.com/crwusiz/openpilot 308 | 309 | https://github.com/move-fast/openpilot 310 | 311 | https://github.com/xps-genesis/openpilot 312 | 313 | https://github.com/dragonpilot-community/dragonpilot 314 | 315 | **Extras** 316 | --------------- 317 | 318 | **Unlimited data, data only simcard compatible with C2.** 319 | 320 | https://www.amazon.com/dp/B07JCTZ3BF/ref=cm_sw_r_u_apa_glt_fabc_SNA9EVB27NT0DPRMEY3Q?psc=1 321 | 322 | Run `adb shell am start -a android.settings.SETTINGS` and go too `"SIM cards"` and under `Cellular network settings` choose either "SIM 1 settings" or "SIM 2 settings" (based on which slot you have your non comma sim installed in.) Then go to `Access Point Names` add and set APN name correctly for sim provider(for the one i'm using and linked above the APN username is `m2mglobal` leave everything else default or blank. (MCC 310, MNC 260) 323 | 324 | **Parts** 325 | ---------- 326 | 327 | Kia Niro MDPS ECU - http://www.kniro.net/schematic_diagrams-1321.html 328 | 329 | MDPS Connectors 330 | 331 | Male 332 | - https://www.mouser.com/ProductDetail/aptiv/15420151/?qs=WTe5OP3w0Koiy%252bx6KqjpIQ%3D%3D&countrycode=CA¤cycode=CAD&bm-verify=AAQAAAAD_____xGvBoTAT_yusRfcDbPOvmmaN_N4VgvTUsLpnvbpGb1zClm2LRJZFYrTQaCWy30sxMrw5LMiUOXCn06a49I1B8zA96meyl7U7I8EteiPj05-qHB8w3slUdlaiAvam3Y96_Xsl81g3qPzp08LwevFanhLa8jvAmcmYyFsMkQVmB5o-bjjk2E3sWqFDi3jINO2kCMPiDZ2BYdawKzl7yPNrkc_dq8iwl-oyNoa242w_dFKI5z1ucS22Etf-_dT-L09e7XFLzVQ307lPqcZrR0mu1gqEY94MN4p9yj71EYVH8SrUJAFu9UOAa0l9ATl01niGRC6afmOr91rzh087B1Bj6RXGml62nkMWgBDkGsiWU7DRkPUjfVJZu00hioYwl-A758CMrxFB3GHEQm-V7oT8kdHI7i-9TH5oxRgrArVhcDlAGasgzhKrWwJ0CXP9okjrQbhlcFZeVPvfQW4RP3WJkHUJnUna-wRSzX2J4Fr7jJBRKDsu7oGqJNSIbsioIlbHsb5-B5Zoi_bLnA0 333 | 334 | Female 335 | - https://www.mouser.com/ProductDetail/aptiv/15406142/?qs=xyz6lfZ1ktKtmezTNc3DLw%3D%3D&countrycode=CA¤cycode=CAD 336 | - https://www.mouser.com/ProductDetail/aptiv/15401440-l/?qs=NKHyz0HolODmWpNAvMSDSg%3D%3D&countrycode=CA¤cycode=CAD 337 | 338 | Black Panda 339 | - https://github.com/Circuit-Pro/openpilot/blob/main/648E3090-698D-4568-BCEE-E723442B3C00.jpeg 340 | 341 | RJ45 female connectors 342 | - https://www.amazon.com/dp/B07JRD69V6/ref=cm_sw_r_cp_api_glt_fabc_WTRZRMNRG20KSPHKRQSX?_encoding=UTF8&psc=1 343 | 344 | RJ45 black panda and comma power adapter 345 | - https://github.com/Circuit-Pro/openpilot/blob/main/C50DC3FD-B803-4B67-A435-AA857EF2396B.png 346 | 347 | 348 | It is open source and inherits MIT license. By installing this software you accept all responsibility for anything that might occur while you use it. All contributors to this fork are not liable. Use at your own risk. 349 | ------------------------------------------------------ 350 | 351 | 352 | 353 | 354 | ![](https://user-images.githubusercontent.com/37757984/127420744-89ca219c-8f8e-46d3-bccf-c1cb53b81bb1.png) 355 | 356 | Table of Contents 357 | ======================= 358 | 359 | * [What is openpilot?](#what-is-openpilot) 360 | * [Running in a car](#running-in-a-car) 361 | * [Running on PC](#running-on-pc) 362 | * [Community and Contributing](#community-and-contributing) 363 | * [User Data and comma Account](#user-data-and-comma-account) 364 | * [Safety and Testing](#safety-and-testing) 365 | * [Directory Structure](#directory-structure) 366 | * [Licensing](#licensing) 367 | 368 | --- 369 | 370 | What is openpilot? 371 | ------ 372 | 373 | [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). 374 | 375 | 376 | 377 | 378 | 379 | 380 | 381 | 382 | 383 | 384 | 385 | 386 | 387 | 388 |
389 | 390 | 391 | Running in a car 392 | ------ 393 | 394 | To use openpilot in a car, you need four things 395 | * This software. It's free and available right here. 396 | * One of [the 140+ 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. 397 | * 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). 398 | * 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). 399 | 400 | We have detailed instructions for [how to install the device in a car](https://comma.ai/setup). 401 | 402 | Running on PC 403 | ------ 404 | 405 | 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. 406 | 407 | 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. 408 | 409 | 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. 410 | 411 | 412 | Community and Contributing 413 | ------ 414 | 415 | 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). 416 | 417 | 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). 418 | 419 | 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. 420 | 421 | Want to get paid to work on openpilot? [comma is hiring](https://comma.ai/jobs/). 422 | 423 | And [follow us on Twitter](https://twitter.com/comma_ai). 424 | 425 | User Data and comma Account 426 | ------ 427 | 428 | 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. 429 | 430 | openpilot is open source software: the user is free to disable data collection if they wish to do so. 431 | 432 | openpilot logs the road facing cameras, CAN, GPS, IMU, magnetometer, thermal sensors, crashes, and operating system logs. 433 | The driver facing camera is only logged if you explicitly opt-in in settings. The microphone is not recorded. 434 | 435 | 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. 436 | 437 | Safety and Testing 438 | ---- 439 | 440 | * openpilot observes ISO26262 guidelines, see [SAFETY.md](docs/SAFETY.md) for more details. 441 | * openpilot has software in the loop [tests](.github/workflows/selfdrive_tests.yaml) that run on every commit. 442 | * 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. 443 | * panda has software in the loop [safety tests](https://github.com/commaai/panda/tree/master/tests/safety). 444 | * Internally, we have a hardware in the loop Jenkins test suite that builds and unit tests the various processes. 445 | * panda has additional hardware in the loop [tests](https://github.com/commaai/panda/blob/master/Jenkinsfile). 446 | * We run the latest openpilot in a testing closet containing 10 comma devices continuously replaying routes. 447 | 448 | Directory Structure 449 | ------ 450 | . 451 | ├── cereal # The messaging spec and libs used for all logs 452 | ├── common # Library like functionality we've developed here 453 | ├── docs # Documentation 454 | ├── opendbc # Files showing how to interpret data from cars 455 | ├── panda # Code used to communicate on CAN 456 | ├── third_party # External libraries 457 | ├── pyextra # Extra python packages 458 | └── selfdrive # Code needed to drive the car 459 | ├── assets # Fonts, images, and sounds for UI 460 | ├── athena # Allows communication with the app 461 | ├── boardd # Daemon to talk to the board 462 | ├── camerad # Driver to capture images from the camera sensors 463 | ├── car # Car specific code to read states and control actuators 464 | ├── common # Shared C/C++ code for the daemons 465 | ├── controls # Planning and controls 466 | ├── debug # Tools to help you debug and do car ports 467 | ├── locationd # Precise localization and vehicle parameter estimation 468 | ├── logcatd # Android logcat as a service 469 | ├── loggerd # Logger and uploader of car data 470 | ├── modeld # Driving and monitoring model runners 471 | ├── proclogd # Logs information from proc 472 | ├── sensord # IMU interface code 473 | ├── test # Unit tests, system tests, and a car simulator 474 | └── ui # The UI 475 | 476 | Licensing 477 | ------ 478 | 479 | openpilot is released under the MIT license. Some parts of the software are released under other licenses as specified. 480 | 481 | 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. 482 | 483 | **THIS IS ALPHA QUALITY SOFTWARE FOR RESEARCH PURPOSES ONLY. THIS IS NOT A PRODUCT. 484 | YOU ARE RESPONSIBLE FOR COMPLYING WITH LOCAL LAWS AND REGULATIONS. 485 | NO WARRANTY EXPRESSED OR IMPLIED.** 486 | 487 | --- 488 | 489 | 490 | 491 | [![openpilot tests](https://github.com/commaai/openpilot/workflows/openpilot%20tests/badge.svg?event=push)](https://github.com/commaai/openpilot/actions) 492 | [![Total alerts](https://img.shields.io/lgtm/alerts/g/commaai/openpilot.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/commaai/openpilot/alerts/) 493 | [![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) 494 | [![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) 495 | [![codecov](https://codecov.io/gh/commaai/openpilot/branch/master/graph/badge.svg)](https://codecov.io/gh/commaai/openpilot) 496 | --------------------------------------------------------------------------------