sunnypilot v2026.002.000
version: sunnypilot v2026.002.000 (staging) date: 2026-07-21T07:44:02 master commit: 2c334ede443d7391d27575af8c854a095ba702a8
This commit is contained in:
commit
de77c89cf6
3995 files changed
+1260688
No files matched your search
@@ -0,0 +1,54 @@
|
||||
# **How custom longitudinal tuning works for Hyundai/Kia/Genesis vehicles in sunnypilot.**
|
||||
|
||||
This document explains the custom longitudinal control tuning implemented in sunnypilot for Hyundai, Kia, and Genesis vehicles.
|
||||
|
||||
**Safety First: ISO 15622:2018**
|
||||
|
||||
Our primary safety guideline is [ISO 15622:2018](https://www.iso.org/obp/ui/en/#iso:std:iso:15622:ed-3:v1:en).
|
||||
This standard provides the foundation for the safety limits enforced by this tuning, particularly concerning maximum allowable jerk based on speed.
|
||||
|
||||
**Core Concepts**
|
||||
|
||||
1. **Jerk-Limited Acceleration:** Instead of directly applying the planner's target acceleration (`CC.actuators.accel`), we use a jerk-limited integrator. This ensures smoother transitions by limiting the rate of change of acceleration (jerk).
|
||||
* `desired_accel`: The target acceleration from the planner, clipped within safe limits (`CarControllerParams.ACCEL_MIN`, `CarControllerParams.ACCEL_MAX`). During stopping, this is forced to 0.
|
||||
* `actual_accel`: The acceleration command sent to the car. It's calculated by integrating `desired_accel` but limiting the change from the previous step (`state.accel_last`) based on calculated `jerk_upper` and `jerk_lower` limits.
|
||||
* `jerk_limited_integrator(desired_accel, last_accel, jerk_upper, jerk_lower)`: This function calculates the maximum allowable acceleration change per control step (`DT_CTRL * 2`) based on the upper and lower jerk limits and applies it using `rate_limit`.
|
||||
|
||||
2. **Predictive Jerk Limits:** The upper and lower jerk limits (`jerk_upper`, `jerk_lower`) are not fixed but calculated dynamically based on several factors:
|
||||
* **Actual Acceleration (`aego`):** The car's current acceleration (`CS.out.aEgo`, potentially blended with `CS.aBasis` at low speeds) is smoothed using a `FirstOrderFilter` (`self.aego`).
|
||||
* **Acceleration Error:** The difference between the *commanded* acceleration (`self.accel_cmd`) and the *actual* smoothed acceleration (`self.aego.x`).
|
||||
* **Lookahead Jerk:** We estimate the jerk required to reach the target acceleration (`accel_cmd`) within a future time window. This window (`future_t_upper`, `future_t_lower`) varies with speed, defined in `config.py` (`lookahead_jerk_bp`, `lookahead_jerk_upper_v`, `lookahead_jerk_lower_v`).
|
||||
* `j_ego_upper = accel_error / future_t_upper`
|
||||
* `j_ego_lower = accel_error / future_t_lower`
|
||||
* **ISO 15622 Speed Factors:** Maximum allowed jerk decreases with speed according to ISO 15622. We interpolate values based on current velocity (`CS.out.vEgo`) to get `upper_speed_factor` and `lower_speed_factor`.
|
||||
* **Minimum Jerk (`MIN_JERK`):** A baseline minimum jerk (currently 0.5 m/s³) is enforced to ensure responsiveness.
|
||||
* **Combining Factors:**
|
||||
* `desired_jerk_upper = min(max(j_ego_upper, MIN_JERK), upper_speed_factor)`
|
||||
* `desired_jerk_lower = min(max(-j_ego_lower, MIN_JERK), lower_speed_factor)` (Note: `j_ego_lower` is negated for the lower limit calculation).
|
||||
|
||||
3. **Dynamic Braking Tune:** For use of the tune without the `LONG_TUNING_PREDICTIVE` flag, a specific negative jerk profile is applied during braking (`gen1_accel_error < 0`).
|
||||
* `gen1_accel_error = a_ego_blended - self.state.accel_last`
|
||||
* A dynamic lower jerk limit (`gen1_lower_jerk`) is interpolated based on this error using `DYNAMIC_LOWER_JERK_BP` and a dynamically scaled `DYNAMIC_LOWER_JERK_V` (scaled by `car_config.jerk_limits`).
|
||||
* `gen1_desired_jerk_lower = min(gen1_lower_jerk, lower_speed_factor)`
|
||||
|
||||
4. **Applying Jerk Limits:**
|
||||
* The `jerk_upper` limit is always smoothed using `ramp_update` to prevent abrupt changes.
|
||||
* The `jerk_lower` limit is applied differently based on the `LONG_TUNING_PREDICTIVE` flag:
|
||||
* **If Flag Set (predictive tune):** `jerk_lower` is set directly to `desired_jerk_lower`.
|
||||
* **If Flag Not Set (dynamic tune):** `jerk_lower` is smoothed using `ramp_update` towards `gen1_desired_jerk_lower`.
|
||||
|
||||
**Configuration (`config.py`)**
|
||||
|
||||
* The `CarTuningConfig` dataclass holds tuning parameters like stopping/starting speeds, lookahead jerk profiles, actuator delay, and base jerk limits.
|
||||
* `TUNING_CONFIGS` provides default configurations based on car type (CANFD, EV, HYBRID, DEFAULT).
|
||||
* `CAR_SPECIFIC_CONFIGS` allows overriding defaults for specific car models (e.g., `KIA_NIRO_EV`, `HYUNDAI_IONIQ`).
|
||||
* The `get_car_config` helper function selects the appropriate configuration based on the car fingerprint and flags.
|
||||
* `get_longitudinal_tune` applies relevant config values (like stopping/starting speeds, delay) to the main `CarParams` (CP).
|
||||
|
||||
**Summary**
|
||||
|
||||
This tuning aims for smoother and more responsive longitudinal control by:
|
||||
* Using a jerk-limited integrator for acceleration commands.
|
||||
* Dynamically calculating jerk limits based on lookahead predictions, actual acceleration, and ISO 15622 speed constraints.
|
||||
* Providing specific tuning profiles via a configuration system based on car type and model.
|
||||
* Applying special braking logic for use of predictive or dynamic tune.
|
||||
Reference in new issue
Block a user