mawei/sunnypilot
1
0
Fork 0
mirror of https://github.com/sunnypilot/sunnypilot.git synced 2026-06-25 03:22:07 +08:00
Code Issues Packages Projects Releases Wiki Activity

more

Browse Source
This commit is contained in:
Jason Wen
2026-03-11 21:03:32 -04:00
parent 7d225a1e33
commit 83a84ba4bc
17 changed files with 239 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs_sp/README.md
+4 -1
View File
@@ -6,8 +6,11 @@ Source files for [docs.sunnypilot.ai](https://docs.sunnypilot.ai).
### Install dependencies
Install docs dependencies only - do **not** use `uv pip install .[docs]` as it will
reinstall the full sunnypilot package and break the development environment.
```bash
uv pip install .[docs]
uv pip install Jinja2 mkdocs zensical
```
### Build
docs_sp/assets/favicon.png
+3
View File
@@ -0,0 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:f64cd24ccac9a73100f206909639424421db1fce74dc77c386cdeefa9d16df9c
size 1959
docs_sp/community/contributing.md
+1 -1
View File
@@ -11,7 +11,7 @@ We welcome contributions from the community! Here's how you can help.
- **Report bugs** — See [Reporting a Bug](reporting-a-bug.md)
- **Submit code** — Follow the [Workflow](workflow.md) guide
- **Improve documentation** — Submit PRs to the `docs` branch
- **Help others** — Join the [Discord Community](https://discord.sunnypilot.ai)
- **Help others** — Join the [sunnypilot community forum](https://community.sunnypilot.ai)
## Code of Conduct
docs_sp/community/reporting-a-bug.md
+1 -1
View File
@@ -13,7 +13,7 @@ Help us improve sunnypilot by reporting issues you encounter.
1. **Upgrade** to the latest version — the bug may already be fixed
2. **Remove customizations** — reproduce on a stock official branch
3. **Search** [GitHub Issues](https://github.com/sunnypilot/sunnypilot/issues) and the [Discord Community](https://discord.sunnypilot.ai) for known reports
3. **Search** [GitHub Issues](https://github.com/sunnypilot/sunnypilot/issues) and the [sunnypilot community forum](https://community.sunnypilot.ai) for known reports
4. **Preserve the route** — upload raw logs via [Comma Connect](https://connect.comma.ai) and keep the route available
## What to Include
docs_sp/features/alpha-longitudinal.md
+14
View File
@@ -17,16 +17,27 @@ Alpha Longitudinal uses the vehicle's existing communication interfaces to send
- Reads vehicle speed, pedal position, and other sensor data through the car's CAN bus
- Calculates desired acceleration based on the driving model's output
- Sends throttle and brake commands directly to the vehicle's powertrain controllers
- Sets `pcmCruise=False`, meaning sunnypilot takes full control of longitudinal behavior instead of relying on the vehicle's built-in cruise control module
Because this operates outside the vehicle manufacturer's intended cruise control pathway, the tuning is less refined than on officially supported platforms.
!!! danger "AEB Is Disabled"
Enabling Alpha Longitudinal **disables your vehicle's Automatic Emergency Braking (AEB)**. This is a significant safety trade-off. Without AEB, the vehicle will not automatically apply emergency braking in imminent collision scenarios. Drive with extra caution and maintain safe following distances at all times.
## Requirements
!!! info "Requirements"
- Vehicle must be openpilot-compatible (listed on the [comma.ai vehicle compatibility list](https://comma.ai/vehicles))
- Vehicle does not have official sunnypilot longitudinal support
- Vehicle must report `CP.alphaLongitudinalAvailable = True` — availability is determined per vehicle in the car interface code
- Feature is experimental and under active development
!!! warning "Development Branches Only"
Alpha Longitudinal is flagged as `DEVELOPMENT_ONLY`. It is **only available on development and staging branches**, not on release branches. This is intentional — the feature is not considered stable enough for general release.
!!! warning "Mutually Exclusive with ICBM"
Alpha Longitudinal and [ICBM](icbm.md) cannot be active at the same time. Enabling Alpha Longitudinal disables ICBM, and vice versa. Alpha Longitudinal provides direct throttle/brake control, while ICBM works through the stock cruise control system — these two approaches are fundamentally incompatible.
!!! warning "Alpha Quality Software"
This feature is **alpha quality**. Expect rough edges, less smooth acceleration and braking behavior, and less refined stop-and-go performance compared to officially supported vehicles. Longitudinal behavior may vary significantly between vehicle models and driving conditions.
@@ -34,6 +45,9 @@ Because this operates outside the vehicle manufacturer's intended cruise control
**Settings** → **sunnypilot** → **Cruise Control** → **Alpha Longitudinal**
!!! note
This toggle only appears on development branches and only for vehicles where `alphaLongitudinalAvailable` is `True`.
## Settings Reference
See [Cruise Control Settings](../settings/cruise.md) for configuration details.
docs_sp/features/auto-lane-change.md
+11 -8
View File
@@ -17,7 +17,7 @@ Automatically executes lane changes when you activate the turn signal. You can c
- **Nudge:** Give a light steering nudge to confirm the lane change
- **Nudgeless:** The lane change begins immediately
- **Timed (0.5s–3s):** The lane change begins after the configured delay
5. If BSM Delay is enabled and a vehicle is detected in your blind spot, the lane change waits until the path is clear
5. If BSM Delay is enabled and a vehicle is detected in your blind spot, the lane change is delayed by an additional 1 second beyond the configured timer
## Requirements
@@ -33,16 +33,19 @@ Automatically executes lane changes when you activate the turn signal. You can c
## Modes
| Mode | Behavior |
|------|----------|
| **Off** | Auto lane change is disabled |
| **Nudge** | Requires a light steering nudge to confirm |
| **Nudgeless** | Lane change begins as soon as you signal |
| **0.5s – 3s** | Lane change begins after a set delay |
| Mode | Value | Behavior |
|------|-------|----------|
| **Off** | -1 | Auto lane change is disabled |
| **Nudge** | 0 | Requires a light steering nudge to confirm the lane change |
| **Nudgeless** | 1 | Lane change begins as soon as you signal |
| **0.5 second** | 2 | Lane change begins after 0.5s delay |
| **1 second** | 3 | Lane change begins after 1s delay |
| **2 seconds** | 4 | Lane change begins after 2s delay |
| **3 seconds** | 5 | Lane change begins after 3s delay |
## Blind Spot Monitoring Integration
If your vehicle supports BSM and the BSM Delay option is enabled, the system checks for vehicles in your blind spot before executing the lane change. The lane change is delayed until the adjacent lane is clear.
If your vehicle supports BSM and the BSM Delay option is enabled, the system checks for vehicles in your blind spot before executing the lane change. When a vehicle is detected in the blind spot, the lane change is delayed by an additional **1 second** on top of the configured timer until the adjacent lane is clear.
!!! info "BSM Requirements"
- Vehicle must support Blind Spot Monitoring
docs_sp/features/dynamic-experimental-control.md
+28 -16
View File
@@ -6,33 +6,45 @@ title: Dynamic Experimental Control
## What It Does
DEC automatically switches between openpilot's standard and experimental driving modes based on real-time road conditions. Instead of manually toggling between modes, the system chooses the most appropriate mode for the current situation.
DEC automatically switches between openpilot's two longitudinal modes based on real-time road conditions. Instead of manually toggling between modes, the system dynamically selects the most appropriate mode for the current situation.
To understand DEC, it helps to know the three driving modes in the system:
To understand DEC, it helps to know the two driving modes it switches between:
| Mode | Description |
|------|-------------|
| **Chill Mode** (Standard) | The default openpilot driving mode. Follows the lead car and stays in lane at a steady speed. Best suited for highway and open-road driving where stops and complex maneuvers are rare. |
| **Experimental Mode** | An enhanced mode that can handle stops at traffic lights and stop signs, navigate turns, and respond to more complex urban scenarios. Designed for city driving. |
| **DEC** | Not a driving mode itself, but a dynamic switcher that automatically selects between Chill and Experimental modes in real time based on road conditions. |
| Mode | Internal Name | Description |
|------|---------------|-------------|
| **Chill / Standard** | `acc` | The default openpilot driving mode. Follows the lead car and stays in lane at a steady speed. Best suited for highway and open-road driving where stops and complex maneuvers are rare. |
| **Experimental** | `blended` | An enhanced mode that uses the end-to-end (E2E) driving model. Can handle stops at traffic lights and stop signs, navigate turns, and respond to more complex urban scenarios. Designed for city driving. |
!!! note "DEC is a switcher, not a mode"
DEC is not a third driving mode — it is a dynamic switcher that automatically selects between `acc` (Chill/Standard) and `blended` (Experimental) in real time based on road conditions.
## How It Works
DEC monitors multiple driving signals and conditions to decide which mode is most appropriate at any given moment:
DEC uses a confidence-based switching system with specific probability thresholds and hysteresis to prevent rapid mode toggling:
- **Current speed** — Lower speeds suggest city driving, favoring Experimental Mode
- **Turn detection** — Upcoming turns trigger a switch to Experimental Mode for better handling
- **Stop signs and traffic lights** — Intersections benefit from Experimental Mode's ability to stop and respond to signals
- **Road type** — Highway vs. urban driving informs the mode selection
### Detection Signals
| Signal | Threshold | Effect |
|--------|-----------|--------|
| **Lead vehicle probability** | ≥ 0.45 | Favors `acc` mode (standard following) |
| **Slow-down probability** | ≥ 0.3 | Favors `blended` mode (E2E for stops/turns) |
| **Stop sign / traffic light** | Detected by vision model | Triggers switch to `blended` mode |
| **Turn detection** | Upcoming turns | Triggers switch to `blended` mode |
| **Current speed** | Speed-dependent | Lower speeds favor `blended` mode |
### Switching Logic
- DEC uses **Kalman filters** to smooth probability signals and reduce noise
- A **minimum hold time of 10 frames** prevents rapid oscillation between modes
- A **confidence threshold of 0.6** must be met before switching to a new mode
- The system continuously evaluates conditions and transitions seamlessly without driver input
Based on these signals, DEC switches between:
| Mode | When DEC Activates It |
|------|----------|
| **Chill Mode** | Highway driving with steady speeds, clear lanes, and no upcoming stops or complex intersections |
| **Experimental Mode** | City driving with stops, turns, traffic lights, and complex intersections where the vehicle needs to slow down or stop |
The switching happens seamlessly — DEC continuously evaluates conditions and transitions between modes without requiring any driver input.
| **Chill / Standard** (`acc`) | Highway driving with steady speeds, lead vehicle following, clear lanes, and no upcoming stops or complex intersections |
| **Experimental** (`blended`) | City driving with stops, turns, traffic lights, and complex intersections where the vehicle needs to slow down or stop |
## Requirements
docs_sp/features/icbm.md
+28 -1
View File
@@ -23,14 +23,41 @@ ICBM is designed specifically for vehicles where sunnypilot cannot directly cont
This happens transparently — from your perspective, the buttons work normally but with smarter behavior. Under the hood, ICBM is communicating with the vehicle's cruise control module by simulating physical button presses on the CAN bus, which is why it works even on vehicles without direct throttle/brake control.
### State Machine
ICBM operates through a 5-state machine:
| State | Description |
|-------|-------------|
| **Inactive** | ICBM is idle — no button simulation is in progress |
| **Pre-Active** | A speed change has been requested; ICBM is preparing to simulate button presses |
| **Increasing** | ICBM is sending "speed up" button presses to reach the target speed |
| **Decreasing** | ICBM is sending "speed down" button presses to reach the target speed |
| **Holding** | Target speed has been reached; ICBM is holding the current setting |
!!! tip "Safety"
ICBM preserves all of your vehicle's stock safety systems. Forward Collision Avoidance (FCA), Automatic Emergency Braking (AEB), and other factory safety features remain fully active and unaffected, since the vehicle's own cruise control system is still performing the actual speed control.
ICBM preserves all of your vehicle's stock safety systems. Forward Collision Avoidance (FCA), Automatic Emergency Braking (AEB), and other factory safety features remain fully active and unaffected, since the vehicle's own cruise control system is still performing the actual speed control. ICBM operates purely at the CAN bus button simulation level and does not interact with FCA or AEB message pathways.
## Supported Vehicles
ICBM support varies by vehicle brand. The feature toggle only appears in settings if your vehicle is supported.
| Brand | Notes |
|-------|-------|
| **Hyundai / Kia / Genesis** | Supported on most models with stock cruise control |
| **Honda / Acura** | Supported on compatible models |
| **Chrysler / Dodge / Jeep / RAM** | Supported on compatible models |
| **Mazda** | Supported on compatible models |
!!! info "Not Listed?"
If your brand or model is not listed above and the ICBM toggle does not appear in your settings, your vehicle is not currently supported. Support depends on the vehicle's CAN bus protocol and button command structure.
## Requirements
!!! info "Requirements"
- Your vehicle must support ICBM — not all vehicles are compatible
- If the ICBM toggle does not appear in settings, your vehicle is not supported
- **Mutually exclusive with [Alpha Longitudinal](alpha-longitudinal.md)** — only one can be active at a time
## How to Enable
docs_sp/features/mads.md
+22 -6
View File
@@ -21,14 +21,26 @@ With MADS enabled, Automatic Lane Centering (ALC) and Adaptive Cruise Control (A
### Engagement States
MADS introduces distinct states that reflect how the driver and system interact:
MADS has five internal states:
| State | Description |
|-------|-------------|
| **Active** | Steering assistance is fully engaged and actively providing lane centering |
| **Paused** | Steering assistance is temporarily paused (e.g., due to certain conditions) but can resume without re-engaging |
| **Disabled** | MADS is off — no steering assistance is provided |
| **Enabled** | Steering assistance is fully engaged and actively providing lane centering |
| **Paused** | Steering assistance is temporarily paused (e.g., due to braking, depending on your Steering Mode on Brake setting) but can resume without re-engaging |
| **Soft Disabling** | The system is transitioning from enabled to disabled due to a safety condition (e.g., driver inattention alert escalation) |
| **Overriding** | The driver is actively steering, temporarily overriding the system's lateral input. Steering assistance resumes when the driver releases the wheel |
### Steering Mode on Brake
This setting controls what happens to steering assistance when the brake pedal is pressed:
| Option | Value | Behavior |
|--------|-------|----------|
| **Remain Active** | 0 | Steering stays fully active while braking |
| **Pause** | 1 | Steering pauses while braking, resumes on release |
| **Disengage** | 2 | Steering fully disengages on brake — must re-engage manually |
## Requirements
!!! info "Requirements"
@@ -46,21 +58,25 @@ Then configure the sub-settings in **MADS Settings**.
|---------|-----------------|
| **Main Cruise Allowed** | Whether the cruise on/off button can activate MADS |
| **Unified Engagement Mode** | Whether engaging cruise also engages MADS automatically |
| **Steering Mode on Brake** | What happens to steering when the brake is pressed (Remain Active / Pause / Disengage) |
| **Steering Mode on Disengage** | What happens to steering when cruise disengages |
## Vehicle-Specific Behavior
Some vehicles operate in **limited MADS mode** where certain settings are locked:
Some vehicles operate in **limited MADS mode** where certain settings are locked due to platform constraints (e.g., no vehicle bus access):
=== "Tesla (without vehicle bus)"
- Main Cruise Allowed: forced OFF
- Unified Engagement Mode: forced ON
- Steering Mode: forced to Disengage
- Steering Mode on Brake: forced to **Disengage**
=== "Rivian"
- Main Cruise Allowed: forced OFF
- Unified Engagement Mode: forced ON
- Steering Mode: forced to Disengage
- Steering Mode on Brake: forced to **Disengage**
!!! note "Why these restrictions?"
Vehicles without a full vehicle bus connection (like Tesla without the vehicle bus harness and Rivian) cannot reliably detect certain driver inputs. To maintain safety, MADS defaults to the most conservative behavior on these platforms.
## Settings Reference
docs_sp/features/nnlc.md
+11 -1
View File
@@ -16,7 +16,17 @@ Instead of using fixed mathematical formulas (PID controller), NNLC uses a machi
NNLC evolved from **Neural Network FeedForward (NNFF)**, an earlier approach that used a neural network as a feedforward component alongside traditional controllers. NNLC builds on this foundation by giving the neural network full lateral control authority, resulting in improved steering smoothness and adaptability.
!!! info "Vehicle-Specific Training Data"
The neural network models are trained on real driving data collected from specific vehicles. Because each vehicle has unique steering characteristics, a dedicated model must be trained for each supported make/model. **Not all vehicles have trained models available** — if no model exists for your vehicle, the NNLC toggle will not appear in settings.
The neural network models are trained on real driving data collected from specific vehicles. Because each vehicle has unique steering characteristics, a dedicated model must be trained for each supported make/model. Over **70 vehicle models** currently have trained NNLC models available. If no model exists for your vehicle, the NNLC toggle will not appear in settings.
### Model Matching
When NNLC is enabled, the system matches your vehicle to the best available model using a 3-tier fallback:
| Tier | Match Criteria | Confidence | Description |
|------|---------------|------------|-------------|
| **1. Exact** | Fingerprint + firmware version | ≥ 0.99 | Best match — a model trained on your exact vehicle and firmware combination |
| **2. Valid** | Fingerprint only | ≥ 0.9 | Good match — a model trained on your vehicle platform, regardless of firmware version |
| **3. Substitute** | Substitute table lookup | Fallback | A model from a similar vehicle platform is used as a substitute (configured in `substitute.toml`) |
## Requirements
docs_sp/features/speed-limit.md
+35 -28
View File
@@ -6,28 +6,51 @@ title: Speed Limit Assist
## What It Does
Speed Limit Assist detects the current speed limit using map data and can automatically adjust your cruise speed to match. It offers four operating modes ranging from passive information display to active speed management.
Speed Limit Assist detects the current speed limit and can automatically adjust your cruise speed to match. It offers four operating modes ranging from passive information display to active speed management.
## How It Works
1. sunnypilot reads speed limit data from one or more configured sources (see below)
2. Based on your chosen mode, it displays, warns, or actively adjusts your set speed
3. When a speed limit change is detected, the system either applies it automatically or prompts you to confirm, depending on the confirmation mode
1. sunnypilot reads speed limit data from two sources (see below)
2. A configurable **Speed Limit Policy** determines how the sources are combined when both are available
3. Based on your chosen mode, the system displays, warns, or actively adjusts your set speed
4. An optional offset (fixed or percentage) lets you cruise slightly above or below the limit
## Speed Limit Sources
Speed Limit Assist can pull speed limit data from multiple sources. You can configure which source takes priority via the **Speed Limit Policy** setting.
Speed Limit Assist pulls speed limit data from **two sources**:
| Source | Description |
|--------|-------------|
| **OSM Map Data** | Speed limits from downloaded OpenStreetMap data. Requires [OSM Maps](osm-maps.md) to be configured and downloaded. |
| **Car's Stock Speed Limit Data** | Some vehicles provide speed limit information from their built-in sensors (e.g., Traffic Sign Recognition cameras). Availability depends on the vehicle. |
| **Navigation Data** | Speed limits embedded in navigation route data, when a navigation destination is active. |
| **Camera Vision** | Speed limit signs detected by the device's road-facing camera using the vision model. |
| **Car State** | Speed limit information provided by the vehicle's built-in sensors (e.g., Traffic Sign Recognition cameras). Availability depends on the vehicle. |
| **Map Data** | Speed limits from downloaded OpenStreetMap data. Requires [OSM Maps](osm-maps.md) to be configured and downloaded. |
!!! tip "Source Priority"
When multiple sources detect different speed limits, the **Speed Limit Policy** setting determines which source is used. Configure this under **Settings** → **sunnypilot** → **Cruise Control** → **Speed Limit Policy**.
### Speed Limit Policy
When both sources are available and report different values, the **Speed Limit Policy** setting determines which source is used:
| Policy | Behavior |
|--------|----------|
| **Car State Only** | Uses only the vehicle's built-in speed limit data; ignores map data |
| **Map Data Only** | Uses only OSM map speed limit data; ignores car state |
| **Car State Priority** | Uses car state data when available; falls back to map data |
| **Map Data Priority** | Uses map data when available; falls back to car state |
| **Combined** | Uses the highest-confidence value from either source |
## Operating Modes
| Mode | Behavior |
|------|----------|
| **Off** | Speed limit data is not used |
| **Information** | Shows the current speed limit on the driving display |
| **Warning** | Shows the speed limit and alerts you when you're exceeding it |
| **Assist** | Automatically adjusts cruise speed to match the speed limit |
## Speed Offset
You can set an offset so your cruise speed differs from the exact limit:
- **Fixed offset:** Add or subtract a set number of km/h or mph (range: -30 to +30)
- **Percentage offset:** Apply a percentage above or below the limit
## Confirmation Modes
@@ -56,26 +79,10 @@ Speed Limit Assist provides visual indicators on the driving HUD:
**Settings** → **sunnypilot** → **Cruise Control** → **Speed Limit Assist**
## Operating Modes
| Mode | Behavior |
|------|----------|
| **Off** | Speed limit data is not used |
| **Info** | Shows the current speed limit on the driving display |
| **Warning** | Shows the speed limit and alerts you when you're exceeding it |
| **Assist** | Automatically adjusts cruise speed to match the speed limit |
## Speed Offset
You can set an offset so your cruise speed differs from the exact limit:
- **Fixed offset:** Add or subtract a set number of km/h or mph (range: -30 to +30)
- **Percentage offset:** Apply a percentage above or below the limit
## Vehicle Restrictions
!!! warning "Vehicle Restrictions"
- **Tesla:** Assist mode is disabled on release branches (Info and Warning still work)
- **Tesla:** Assist mode is disabled on release branches (Information and Warning still work)
- **Rivian:** Assist mode is always disabled
## Settings Reference
docs_sp/how-to/preserve-local-changes.md
+4 -1
View File
@@ -25,11 +25,14 @@ Navigate to **Settings** → **Software** → **Disable Updates** and toggle it
This prevents the device from automatically pulling and applying updates from the remote branch.
!!! note "Offroad Only"
The Disable Updates toggle can only be changed while the device is **offroad** (not actively driving). If you are in a drive, complete the drive first and return to the home screen before changing this setting.
### 3. Reboot the Device
Navigate to **Settings** → **Device** → **Reboot** to restart the device.
The reboot applies the settings change and ensures the update service is fully stopped.
The reboot applies the settings change and ensures the update service is fully stopped. A confirmation dialog will appear before the reboot proceeds.
### 4. Verify
docs_sp/safety/prohibited-modifications.md
+23
View File
@@ -19,10 +19,33 @@ The following modifications to panda safety logic are strictly prohibited:
- **Removing steering torque limits** — Modifying or removing the safety-enforced steering torque limits is prohibited.
- **Bypassing vehicle safety interlocks** — Disabling or circumventing any vehicle-level safety interlock is prohibited.
### Panda Safety Limits (Example: Hyundai/Kia/Genesis)
The panda enforces hard acceleration limits that cannot be overridden by software:
| Parameter | Limit |
|-----------|-------|
| **Maximum acceleration** | +2.0 m/s² |
| **Maximum deceleration** | -3.5 m/s² |
These limits are enforced at the hardware level by the panda safety firmware. Any attempt to exceed these limits is blocked regardless of what the software commands.
## Driver Monitoring Violations
- **Reducing or weakening driver monitoring parameters** — Any modification that lowers the sensitivity, delays the response, or otherwise weakens the driver monitoring system is prohibited. This includes increasing allowed distraction time, reducing alert thresholds, or disabling monitoring entirely.
### Driver Monitoring Escalation Timeline
The driver monitoring system follows a strict escalation timeline:
| Phase | Timeout | Description |
|-------|---------|-------------|
| **Active monitoring** | 11 seconds | Time before the first distraction alert when the driver is not looking at the road |
| **Passive monitoring** | 30 seconds | Time before an alert when the driver's face is not detected (e.g., face covered or camera obstructed) |
| **Terminal alerts** | 3 strikes | After 3 terminal-level alerts (driver unresponsive), the system locks out and requires a full restart |
Modifying any of these thresholds to be more permissive is strictly prohibited.
## General Prohibitions
- Disabling or bypassing driver monitoring
docs_sp/setup/read-before-installing.md
+1 -1
View File
@@ -38,5 +38,5 @@ Before installing sunnypilot, please review the following important information.
If you run into issues:
- Join the [Discord Community](https://discord.sunnypilot.ai)
- Visit the [sunnypilot community forum](https://community.sunnypilot.ai)
- Check [Reporting a Bug](../community/reporting-a-bug.md) for how to submit issues
docs_sp/stylesheets/style.css
+11
View File
@@ -4,3 +4,14 @@
* This file is part of sunnypilot and is licensed under the MIT License.
* See the LICENSE.md file in the root directory for more details.
*/
/* Make the header logo larger */
.md-header__button.md-logo img {
height: 2.4rem;
width: auto;
}
/* Invert the white logo to dark on light mode */
[data-md-color-scheme="default"] .md-header__button.md-logo img {
filter: brightness(0);
}
docs_sp/technical/hyundai-longitudinal-tuning.md
+38 -3
View File
@@ -25,7 +25,7 @@ The longitudinal tuning for HKG vehicles targets the following objectives:
## Standards Reference
The tuning implementation references **ISO 15622** (Intelligent Transport Systems — Adaptive Cruise Control Systems — Performance Requirements and Test Procedures). This standard defines:
The tuning implementation references **ISO 15622:2018** (Intelligent Transport Systems — Adaptive Cruise Control Systems — Performance Requirements and Test Procedures). This standard defines:
- Maximum and minimum acceleration/deceleration rates for ACC systems
- Response time requirements for speed changes
@@ -36,14 +36,38 @@ The tuning implementation references **ISO 15622** (Intelligent Transport System
### Jerk Limiting
**Jerk** is the rate of change of acceleration (m/s^3). High jerk values produce the "jerky" feeling passengers experience during abrupt speed changes.
**Jerk** is the rate of change of acceleration (m/s³). High jerk values produce the "jerky" feeling passengers experience during abrupt speed changes.
The tuning system limits jerk to keep acceleration transitions smooth:
| Parameter | Value | Description |
|-----------|-------|-------------|
| **Minimum jerk** | 0.5 m/s³ | Floor value — jerk is never reduced below this to maintain responsiveness |
| **Default jerk limit** | 4.0 m/s³ | Standard upper bound for jerk across most driving scenarios |
- Acceleration onset is ramped gradually rather than applied instantly
- Deceleration transitions are similarly smoothed to avoid sudden braking sensations
- Different jerk limits apply to different driving scenarios (e.g., following vs. stopping)
#### Per-Vehicle Jerk Overrides
Some vehicle models have custom jerk limits tuned to their specific powertrain characteristics:
| Vehicle | Jerk Limit (m/s³) | Reason |
|---------|-------------------|--------|
| **Kia Niro EV** | 3.3 | EV powertrain delivers instant torque; lower jerk limit prevents harsh acceleration onset |
| **Kia Niro PHEV (2022+)** | 5.0 | Hybrid powertrain benefits from slightly higher jerk allowance for smoother transitions between electric and ICE modes |
#### Type-Specific Overrides
Jerk limits and acceleration profiles are also adjusted by vehicle communication type:
| Type | Adjustment |
|------|------------|
| **CAN-FD** | Tuning adapted for CAN-FD protocol timing and message rates |
| **EV** | Lower default jerk limits to account for instant torque delivery |
| **Hybrid** | Adjusted profiles to handle transitions between electric and combustion modes |
### Parabolic Approach
When decelerating to a stop or approaching a slower lead vehicle, the system uses **parabolic deceleration profiles** rather than constant-rate braking. This means:
@@ -74,12 +98,23 @@ The system adapts its behavior based on the lead vehicle's actions:
- **Lead cut-in**: Timely but smooth deceleration to establish safe following distance
- **Lead cut-out**: Controlled acceleration to resume set speed
## Panda Safety Limits
The panda enforces hard acceleration limits at the firmware level that cannot be overridden:
| Parameter | Limit |
|-----------|-------|
| **Maximum acceleration** | +2.0 m/s² |
| **Maximum deceleration** | -3.5 m/s² |
All tuning parameters must produce acceleration commands within these bounds. Any command exceeding these limits is clamped by the panda safety layer.
## Technical Parameters
The tuning system uses several categories of parameters:
- **Acceleration bounds**: Maximum and minimum acceleration values at different speeds
- **Jerk limits**: Rate-of-change constraints for both positive and negative acceleration
- **Jerk limits**: Rate-of-change constraints for both positive and negative acceleration (min: 0.5, default max: 4.0 m/s³)
- **Time constants**: Filtering and smoothing time constants for acceleration commands
- **Following distance gains**: Speed-dependent proportional and derivative gains for gap control
- **Stopping parameters**: Deceleration profiles and creep behavior for stop-and-go
mkdocs-sp.yml
+4 -4
View File
@@ -36,7 +36,7 @@ theme:
text: Open Sans
code: Fira Code
logo: assets/logo.png
favicon: assets/logo.png
favicon: assets/favicon.png
features:
- content.code.copy
- navigation.tabs
@@ -136,7 +136,7 @@ nav:
- Contributing: community/contributing.md
- Workflow: community/workflow.md
- Reporting a Bug: community/reporting-a-bug.md
- Discord Community: https://discord.sunnypilot.ai
- Community Forum: https://community.sunnypilot.ai
- How-To Guides:
- Share a Route: how-to/share-a-route.md
- Preserve Local File Changes: how-to/preserve-local-changes.md
@@ -154,5 +154,5 @@ extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/sunnypilot/sunnypilot
- icon: fontawesome/brands/discord
link: https://discord.sunnypilot.ai
- icon: fontawesome/solid/comments
link: https://community.sunnypilot.ai