mawei/sunnypilot
1
0
Fork 0
mirror of https://github.com/sunnypilot/sunnypilot.git synced 2026-09-29 17:13:43 +08:00
Code Issues Packages Projects Releases Wiki Activity

more

Browse Source
This commit is contained in:
Jason Wen
2024-08-04 16:11:04 -04:00
parent fc8bf86599
commit a6582a9e31
14 changed files with 458 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs_sp/CONTRIBUTING.md
+65
View File
@@ -0,0 +1,65 @@
# How to contribute
Our software is open source so you can solve your own problems without needing help from others. And if you solve a problem and are so kind, you can upstream it for the rest of the world to use. Check out our [post about externalization](https://blog.comma.ai/a-2020-theme-externalization/). Development activity is coordinated through our GitHub Issues, [GitHub Discussions](https://github.com/commaai/openpilot/discussions), and [Discord](https://discord.comma.ai).
### Getting Started
* Setup your [development environment](https://github.com/sunnypilot/sunnypilot/tree/master/tools)
* Read about the [development workflow](WORKFLOW.md)
* Join our [Discord](https://discord.comma.ai)
* Docs are at https://docs.comma.ai and https://blog.comma.ai
## What contributions are we looking for?
**openpilot's priorities are [safety](SAFETY.md), stability, quality, and features, in that order.** openpilot is part of comma's mission to *solve self-driving cars while delivering shippable intermediaries*, and **all** development is towards that goal.
### What gets merged?
The probability of a pull request being merged is a function of its value to the project and the effort it will take us to get it merged.
If a PR offers *some* value but will take lots of time to get merged, it will be closed.
Simple, well-tested bug fixes are the easiest to merge, and new features are the hardest to get merged.
All of these are examples of good PRs:
* typo fix: https://github.com/commaai/openpilot/pull/30678
* removing unused code: https://github.com/commaai/openpilot/pull/30573
* simple car model port: https://github.com/commaai/openpilot/pull/30245
* car brand port: https://github.com/commaai/openpilot/pull/23331
### What doesn't get merged?
* **arbitrary style changes**: code is art, and it's up to the author to make it beautiful
* **500+ line PRs**: clean it up, break it up into smaller PRs, or both
* **PRs without a clear goal**: every PR must have a singular and clear goal
* **UI design changes**: we do not have a good review process for this yet
* **New features**: We believe openpilot is mostly feature-complete, and the rest is a matter of refinement and fixing bugs. As a result of this, most feature PRs will be immediately closed, however the beauty of open source is that forks can and do offer features that upstream openpilot doesn't.
### First contribution
Check out any [good first issue](https://github.com/commaai/openpilot/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) to get started.
### What do I need to contribute?
A lot of openpilot work requires only a PC, and some requires a comma device.
Most car-related contributions require access to that car, plus a comma device installed in the car.
## Pull Requests
Pull requests should be against the master branch. If you're unsure about a contribution, feel free to open a discussion, issue, or draft PR to discuss the problem you're trying to solve.
A good pull request has all of the following:
* a clearly stated purpose
* every line changed directly contributes to the stated purpose
* verification, i.e. how did you test your PR?
* justification
* if you've optimized something, post benchmarks to prove it's better
* if you've improved your car's tuning, post before and after plots
* passes the CI tests
## Contributing without Code
* Report bugs in GitHub issues.
* Report driving issues in the `#driving-feedback` Discord channel.
* Consider opting into driver camera uploads to improve the driver monitoring model.
* Connect your device to Wi-Fi regularly, so that we can pull data for training better driving models.
* Run the `nightly` branch and report issues. This branch is like `master` but it's built just like a release.
* Annotate images in the [comma10k dataset](https://github.com/commaai/comma10k).
docs_sp/SAFETY.md
+36
View File
@@ -0,0 +1,36 @@
# Safety
openpilot is an Adaptive Cruise Control (ACC) and Automated Lane Centering (ALC) system.
Like other ACC and ALC systems, openpilot is a failsafe passive system and it requires the
driver to be alert and to pay attention at all times.
In order to enforce driver alertness, openpilot includes a driver monitoring feature
that alerts the driver when distracted.
However, even with an attentive driver, we must make further efforts for the system to be
safe. We repeat, **driver alertness is necessary, but not sufficient, for openpilot to be
used safely** and openpilot is provided with no warranty of fitness for any purpose.
openpilot is developed in good faith to be compliant with FMVSS requirements and to follow
industry standards of safety for Level 2 Driver Assistance Systems. In particular, we observe
ISO26262 guidelines, including those from [pertinent documents](https://www.nhtsa.gov/sites/nhtsa.dot.gov/files/documents/13498a_812_573_alcsystemreport.pdf)
released by NHTSA. In addition, we impose strict coding guidelines (like [MISRA C : 2012](https://www.misra.org.uk/what-is-misra/))
on parts of openpilot that are safety relevant. We also perform software-in-the-loop,
hardware-in-the-loop and in-vehicle tests before each software release.
Following Hazard and Risk Analysis and FMEA, at a very high level, we have designed openpilot
ensuring two main safety requirements.
1. The driver must always be capable to immediately retake manual control of the vehicle,
by stepping on the brake pedal or by pressing the cancel button.
2. The vehicle must not alter its trajectory too quickly for the driver to safely
react. This means that while the system is engaged, the actuators are constrained
to operate within reasonable limits[^1].
For additional safety implementation details, refer to [panda safety model](https://github.com/commaai/panda#safety-model). For vehicle specific implementation of the safety concept, refer to [panda/board/safety/](https://github.com/commaai/panda/tree/master/board/safety).
**Extra note**: comma.ai strongly discourages the use of openpilot forks with safety code either missing or
not fully meeting the above requirements.
[^1]: For these actuator limits we observe ISO11270 and ISO15622. Lateral limits described there translate to 0.9 seconds of maximum actuation to achieve a 1m lateral deviation.
docs_sp/WORKFLOW.md
+43
View File
@@ -0,0 +1,43 @@
# openpilot development workflow
Aside from the ML models, most tools used for openpilot development are in this repo.
Most development happens on normal Ubuntu workstations, and not in cars or directly on comma devices. See the [setup guide](https://github.com/sunnypilot/sunnypilot/tree/master/tools) for getting your PC setup for openpilot development.
## Quick start
```bash
# get the latest stuff
git pull
git lfs pull
git submodule update --init --recursive
# update dependencies
tools/ubuntu_setup.sh
# build everything
scons -j$(nproc)
# build just the ui with either of these
scons -j8 selfdrive/ui/
cd selfdrive/ui/ && scons -u -j8
# test everything
pytest
# test just logging services
cd system/loggerd && pytest .
# run the linter
op lint
```
## Testing
### Automated Testing
All PRs and commits are automatically checked by GitHub Actions. Check out `.github/workflows/` for what GitHub Actions runs. Any new tests should be added to GitHub Actions.
### Code Style and Linting
Code is automatically checked for style by GitHub Actions as part of the automated tests. You can also run these tests yourself by running `pre-commit run --all`.
docs_sp/features/modified-assistive-driving-safety.md
+33
View File
@@ -0,0 +1,33 @@
# 🛡️ Modified Assistive Driving Safety (MADS)
!!! note
This feature aligns closely with comma.ai's safety rules.
Modified Assistive Driving Safety (MADS) aims to elevate the user's driving experience by modifying the behaviors of driving assist engagements.
## Independent Engagement
MADS allows users to engage sunnypilot Automatic Lane Centering (ALC) for lateral control and Adaptive Cruise Control (ACC) or Smart Cruise Control (SCC) for longitudinal control independently.
??? note "Why This Option Exists"
While newer car models allow for independent engagement of lateral (steering) and longitudinal (speed) control, many older models and stock openpilot enforce engaging both controls together. MADS introduces this modern convenience to older models, effectively backporting a feature found in newer cars and providing users more flexibility.
## Dedicated Buttons
**Toggle for sunnypilot ALC**:
- `CRUISE (MAIN)` button: Available on all supported cars on sunnypilot.
- `LFA` button: Available on newer HKG cars.
- `LKAS` button: Available on Honda, Toyota, and Global Subaru.
**Engagement**:
- `SET-` button: Enables ACC/SCC.
- `CANCEL` button: Disables ACC/SCC only.
- `CRUISE (MAIN)` must be `ON` to use ACC/SCC.
!!! warning
The `CRUISE (MAIN)` button disables sunnypilot completely when `OFF`. This is strictly enforced in the panda safety code.
## Lateral Control on Brake Pedal
Dedicated toggle to handle Lateral state on brake pedal press and release:
- **ON**: Pressing the `BRAKE pedal` will pause Automatic Lane Centering.
docs_sp/getting-started/develop-sunnypilot.md
+9
View File
@@ -0,0 +1,9 @@
# To start developing sunnypilot
sunnypilot is a fork of [commaai's openpilot](https://github.com/commaai/openpilot), developed by [sunnypilot](https://sunnypilot.ai) and by users like you. We welcome both pull requests and issues on [GitHub](http://github.com/sunnypilot/sunnypilot).
* Join the [community Discord](https://discord.sunnypilot.ai)
* Check out [the contributing docs](../CONTRIBUTING.md)
* Check out the [openpilot tools](https://github.com/sunnypilot/sunnypilot/tree/master/tools)
* Read about the [development workflow](../WORKFLOW.md)
* Information about running sunnypilot and code documentation lives on the [sunnypilot wiki](https://docs.sunnypilot.ai)
docs_sp/getting-started/use-sunnypilot-in-a-car.md
+16
View File
@@ -0,0 +1,16 @@
# To start using sunnypilot in a car
To use sunnypilot in a car, you need four things:
1. **Supported Device:** a comma 3/3X, available at [comma.ai/shop](https://comma.ai/shop/comma-3x).
2. **Software:** The setup procedure for the comma 3/3X allows users to enter a URL for custom software. Use the URL `release-c3.sunnypilot.ai` to install the release version.
3. **Supported Car:** Ensure that you have one of [the 275+ supported cars](https://github.com/sunnypilot/sunnypilot/blob/master/docs/CARS.md).
4. **Car Harness:** You will also need a [car harness](https://comma.ai/shop/car-harness) to connect your comma 3/3X to your car.
[comma.ai](https://comma.ai) have detailed instructions for [how to install the harness and device in a car](https://comma.ai/setup).
!!! note
It's possible to run sunnypilot on [other hardware](https://blog.comma.ai/self-driving-car-for-free/), although it's not plug-and-play.
docs_sp/getting-started/what-is-sunnypilot.md
+11
View File
@@ -0,0 +1,11 @@
# What is sunnypilot?
sunnypilot is a fork of [comma.ai's openpilot](https://github.com/commaai/openpilot), an open source driver assistance system. sunnypilot offers the user a unique driving experience for over 250+ supported car makes and models with modified behaviors of driving assist engagements. sunnypilot complies with comma.ai's safety rules as accurately as possible.
## How do I use it?
sunnypilot is designed to be used on the comma 3/3X.
## How does it work?
In short, sunnypilot uses the car's existing APIs for the built-in [ADAS](https://en.wikipedia.org/wiki/Advanced_driver-assistance_system) system and simply provides better acceleration, braking, and steering inputs than the stock system.
docs_sp/how-to/enable-mapbox-navigation.md
+41
View File
@@ -0,0 +1,41 @@
---
title: 🗺 Enable Mapbox Navigation
---
Enabling Mapbox Navigation on your sunnypilot 🚗 enhances your driving experience by providing accurate maps and directions. Follow the steps below to set up and enjoy this feature:
### **🛠 Setup Steps**
1. **Create a Free Mapbox Account**:
Sign up for a free Mapbox account. Although a credit card is required for verification, you will not be charged for the free tier.
2. **Generate Access Tokens**:
On the Dashboard, find the **Access Tokens** section and click `Create a Token`. Name it as you like and set the scopes to allow everything for both Public and Secret. Copy both keys. ⚠️ **Remember**: You won't be able to access the secret key after this window.
3. **Enable Mapbox Navigation on C3**:
Go to `SP - Visuals` on your C3 and toggle `Enable Mapbox Navigation*`. Accept the reboot prompt.
4. **Connect C3 to Network**:
Once rebooted, connect your C3 to a network with internet access and note the C3’s IP address.
5. **Configure Keys**:
In a browser, navigate to `C3_IP:8082` (e.g., 192.168.1.69:8082). You should see the Comma logo and an input field. Paste your Public token (pk.xx), press enter, paste your Secret key (sk.xx), and press enter again. This page lets you search for destinations.
6. **Set Home and Work Addresses**:
To set Home and Work addresses, search for a place, select Home/Work from the dropdown, and click Navigate. For other destinations, select Recent Places.
7. **Search on C3**:
At this time, it is not possible to search directly on the C3.
:::tip **TIPS:**
- If your C3 shows a "Map Loading" screen, a reboot via the UI should fix it.
- Connect the C3 to your phone's hotspot and use your phone browser to search for places.
- In the Navigation panel on the C3, select Home, Work, and Recent Places without needing a browser (assuming internet connection).
:::
:::warning **IMPORTANT NOTE:**
Your C3 requires an active internet connection to download map data, generate directions, and update ETA. Once data is downloaded, offline use is possible, but updates (like new directions after a missed turn) won't occur.
:::
:::info **NAVIGATION NOTE:**
Mapbox does not support alphanumeric addresses (e.g., W123N1234 Main St). There is currently no known workaround for this.
:::
docs_sp/how-to/radar-tracks.md
+51
View File
@@ -0,0 +1,51 @@
---
title: 📡 Radar Tracks
---
Unlock the potential of your sunnypilot 🚗 by enabling Radar Tracks manually on applicable cars. Thanks to [@greghogan](https://github.com/greghogan) and [@pd0wm](https://github.com/pd0wm), this feature is now accessible through SSH.
:::info
**How Radar Points Can Be Used Along With Vision:**
Current Openpilot policy is to identify with vision first and match it to a radar point. If vision sees nothing, you get a false negative and no lead car detection. (Source: [Hubblesphere#7894 from comma.ai community Discord](https://discord.com/channels/469524606043160576/872899198738104330/872913890793635872))
:::
### 🚨 Enable Radar Tracks (Experimental)
***(As of January 1st, 2022)***
***(Applicable to some Hyundai, Kia, and Genesis cars)***
***(Based on version 0.8.12 [`devel`](https://github.com/commaai/openpilot/tree/devel))***
:::caution
**USE AT YOUR OWN RISK!** Stock system safety features, like AEB and FCW, might be affected by these changes.
:::
#### **Steps to Enable Radar Tracks:**
1. **Preparation**:
Ensure the car is in the `OFF` ignition position and connect your compatible comma device (EON, C2, C3) to the car.
2. **SSH Connection**:
Connect to your comma device via SSH. (Instructions [HERE](https://github.com/commaai/openpilot/wiki/SSH))
3. **Execute Commands**:
In the SSH terminal, execute the following commands:
```bash
pkill -f openpilot
python /data/openpilot/selfdrive/debug/hyundai_enable_radar_points.py
```
Follow the script instructions and ensure no faults appear.
4. **Reboot**:
Reboot your comma device and start your car ensuring no faults.
5. **Test Drive**:
Go for a quick drive, drive behind a lead car, and allow the drive to upload its `rlogs` in [comma Connect](https://connect.comma.ai).
6. **Verify in Cabana**:
Open the drive in Cabana from [comma Connect](https://connect.comma.ai), load `hyundai_kia_mando_front_radar.dbc`, search `RADAR_TRACK_50x`, and check `LONG_DIST`.
7. **Confirmation**:
If the radar tracks data is relevant, you've successfully enabled radar tracks.
:::tip
Having issues or need assistance? Reach out to the community in [Sunnyhaibin's Openpilot Discord Server](https://discord.gg/wRW3meAgtx) or `#hyundai-kia-genesis channel` on [commaai community Discord Server](https://discord.comma.ai).
:::
docs_sp/how-to/turn-the-speed-blue.md
+98
View File
@@ -0,0 +1,98 @@
# Turn the speed blue
*A getting started guide for openpilot development*
In 30 minutes, we'll get an openpilot development environment setup on your computer and make some changes to openpilot's UI.
And if you have a comma 3/3X, we'll deploy the change to your device for testing.
## 1. Setup your development environment
Run this to clone openpilot and install all the dependencies:
```bash
curl -fsSL openpilot.comma.ai | bash
```
Navigate to openpilot folder & activate a Python virtual environment
```bash
cd openpilot
source .venv/bin/activate
```
Then, compile openpilot:
```bash
scons -j8
```
## 2. Run replay
We'll run the `replay` tool with the demo route to get data streaming for testing our UI changes.
```bash
# in terminal 1
tools/replay/replay --demo
# in terminal 2
selfdrive/ui/ui
```
The openpilot UI should launch and show a replay of the demo route.
If you have your own comma device, you can replace `--demo` with one of your own routes from comma connect.
## 3. Make the speed blue
Search for “mph” with git grep in the `ui` folder.
```bash
$ git grep "mph" selfdrive/ui/
paint.cc: ui_draw_text(s, s->fb_w/2, 290, s->scene.is_metric ? "km/h" : "mph", 36 * 2.5, COLOR_WHITE_ALPHA(200), "sans-regular");
```
The line right above contains the actual speed. Unfortunately, COLOR_BLUE isn’t defined, but a git grep of COLOR_WHITE shows it’s nvgRGBA(255, 255, 255, 255). Personally, I like a lighter blue, so I went with #8080FF.
```bash
$ git diff
diff --git a/selfdrive/ui/paint.cc b/selfdrive/ui/paint.cc
index 821d95115..cc996eaa1 100644
--- a/selfdrive/ui/paint.cc
+++ b/selfdrive/ui/paint.cc
@@ -175,8 +175,8 @@ static void ui_draw_vision_speed(UIState *s) {
const float speed = std::max(0.0, (*s->sm)["carState"].getCarState().getVEgo() * (s->scene.is_metric ? 3.6 : 2.2369363));
const std::string speed_str = std::to_string((int)std::nearbyint(speed));
nvgTextAlign(s->vg, NVG_ALIGN_CENTER | NVG_ALIGN_BASELINE);
- ui_draw_text(s, s->fb_w/2, 210, speed_str.c_str(), 96 * 2.5, COLOR_WHITE, "sans-bold");
- ui_draw_text(s, s->fb_w/2, 290, s->scene.is_metric ? "km/h" : "mph", 36 * 2.5, COLOR_WHITE_ALPHA(200), "sans-regular");
+ ui_draw_text(s, s->fb_w/2, 210, speed_str.c_str(), 96 * 2.5, nvgRGBA(128, 128, 255, 255), "sans-bold");
+ ui_draw_text(s, s->fb_w/2, 290, s->scene.is_metric ? "km/h" : "mph", 36 * 2.5, nvgRGBA(128, 128, 255, 200), "sans-regular");
}
static void ui_draw_vision_event(UIState *s) {
```
## 4. Rebuild UI, and admire your work
```
scons -j8 && selfdrive/ui/ui
```
![](https://blog.comma.ai/img/blue_speed_ui.png)
## 5. Push your fork to GitHub
Click fork on GitHub. Then, push with:
```bash
git remote rm origin
git remote add origin git@github.com:<your-github-username>/openpilot.git
git add .
git commit -m "Make the speed blue."
git push --set-upstream origin master
```
## 6. Run your fork on device in your car!
Uninstall openpilot from your device through the settings. Then, enter the URL for your very own installer:
```
installer.comma.ai/<your-github-username>/master
```
## 7. Admire your work IRL
![](https://blog.comma.ai/img/c3_blue_ui.jpg)
docs_sp/index.md
+12
View File
@@ -0,0 +1,12 @@
# 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](https://github.com/commaai/openpilot/blob/master/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](https://github.com/commaai/openpilot/blob/master/docs/INTEGRATION.md) and [limitations](https://github.com/commaai/openpilot/blob/master/docs/LIMITATIONS.md).
## How do I use it?
openpilot is designed to be used on the comma 3X.
## How does it work?
In short, openpilot uses the car's existing APIs for the built-in [ADAS](https://en.wikipedia.org/wiki/Advanced_driver-assistance_system) system and simply provides better acceleration, braking, and steering inputs than the stock system.
docs_sp/safety/prohibited-safety-modifications.md
+13
View File
@@ -0,0 +1,13 @@
# Prohibited Safety Modifications
All [official sunnypilot branches](https://github.com/sunnyhaibin/sunnypilot/branches) strictly adhere to [comma.ai's safety policy](https://github.com/commaai/openpilot/blob/master/docs/SAFETY.md). Any changes that go against this policy will result in your fork and your device being banned from both comma.ai and sunnypilot channels.
The following changes are a **VIOLATION** of this policy and **ARE NOT** included in any sunnypilot branches:
!!! danger "Driver Monitoring"
- "Nerfing" or reducing monitoring parameters.
!!! danger "Panda Safety"
- No preventing disengaging of <ins>**LONGITUDINAL CONTROL**</ins> (acceleration/brake) on brake pedal press.
- No auto re-engaging of <ins>**LONGITUDINAL CONTROL**</ins> (acceleration/brake) on brake pedal release.
- No disengaging on ACC MAIN in OFF state.
docs_sp/safety/read-before-installing.md
+8
View File
@@ -0,0 +1,8 @@
# 🚨 Read Before Installing 🚨
It is recommended to read the **entire wiki** before proceeding. This will ensure that you fully understand each added feature in sunnypilot. This also ensures that you are choosing the correct settings and branch for your car to have the best driving experience.
!!! warning
By installing this software, you accept all responsibility for anything that might occur while you use it. sunnypilot and all contributors to sunnypilot are not liable.
**Use at your own risk.**
mkdocs-sp.yml
+22 -8
View File
@@ -1,4 +1,4 @@
site_name: sunnypilot docs
site_name: sunnypilot wiki
repo_name: sunnypilot/sunnypilot
repo_url: https://github.com/sunnypilot/sunnypilot/
site_description: sunnypilot Documentation
@@ -19,37 +19,51 @@ theme:
view: material/eye
features:
- content.action.edit
- navigation.expand
- navigation.footer
- navigation.tabs
font:
text: Roboto
code: Roboto Mono
palette:
# Palette toggle for automatic mode
- media: "(prefers-color-scheme)"
toggle:
icon: material/brightness-auto
icon: material/link
name: Switch to light mode
# Palette toggle for light mode
- media: "(prefers-color-scheme: light)"
scheme: default
primary: indigo
accent: indigo
toggle:
icon: material/brightness-7
icon: material/toggle-switch
name: Switch to dark mode
# Palette toggle for dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: black
accent: indigo
toggle:
icon: material/brightness-4
icon: material/toggle-switch-off
name: Switch to system preference
navigation_depth: 3
markdown_extensions:
- admonition
- def_list
- pymdownx.details
- pymdownx.superfences
nav:
- Getting Started:
- What is sunnypilot?: getting-started/what-is-sunnypilot.md
- Use sunnypilot in a car: getting-started/use-sunnypilot-in-a-car.md
- Develop sunnypilot: getting-started/develop-sunnypilot.md
- Safety Information:
- 🚨 Read before installing 🚨: safety/read-before-installing.md
- Safety: SAFETY.md
- Prohibited safety modifications: safety/prohibited-safety-modifications.md
- Features:
- Modified Assistive Driving Safety (M.A.D.S.): features/modified-assistive-driving-safety.md
- how-to:
- How To:
- Enable Mapbox navigation: how-to/enable-mapbox-navigation.md
- Enable Radar Tracks: how-to/radar-tracks.md
- Turn the speed blue: how-to/turn-the-speed-blue.md