version: sunnypilot v2026.002.000 (staging) date: 2026-07-21T07:44:02 master commit: 2c334ede443d7391d27575af8c854a095ba702a8
5.0 KiB
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. This standard provides the foundation for the safety limits enforced by this tuning, particularly concerning maximum allowable jerk based on speed.
Core Concepts
-
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 integratingdesired_accelbut limiting the change from the previous step (state.accel_last) based on calculatedjerk_upperandjerk_lowerlimits.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 usingrate_limit.
-
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 withCS.aBasisat low speeds) is smoothed using aFirstOrderFilter(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 inconfig.py(lookahead_jerk_bp,lookahead_jerk_upper_v,lookahead_jerk_lower_v).j_ego_upper = accel_error / future_t_upperj_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 getupper_speed_factorandlower_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_loweris negated for the lower limit calculation).
- Actual Acceleration (
-
Dynamic Braking Tune: For use of the tune without the
LONG_TUNING_PREDICTIVEflag, 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 usingDYNAMIC_LOWER_JERK_BPand a dynamically scaledDYNAMIC_LOWER_JERK_V(scaled bycar_config.jerk_limits). gen1_desired_jerk_lower = min(gen1_lower_jerk, lower_speed_factor)
-
Applying Jerk Limits:
- The
jerk_upperlimit is always smoothed usingramp_updateto prevent abrupt changes. - The
jerk_lowerlimit is applied differently based on theLONG_TUNING_PREDICTIVEflag:- If Flag Set (predictive tune):
jerk_loweris set directly todesired_jerk_lower. - If Flag Not Set (dynamic tune):
jerk_loweris smoothed usingramp_updatetowardsgen1_desired_jerk_lower.
- If Flag Set (predictive tune):
- The
Configuration (config.py)
- The
CarTuningConfigdataclass holds tuning parameters like stopping/starting speeds, lookahead jerk profiles, actuator delay, and base jerk limits. TUNING_CONFIGSprovides default configurations based on car type (CANFD, EV, HYBRID, DEFAULT).CAR_SPECIFIC_CONFIGSallows overriding defaults for specific car models (e.g.,KIA_NIRO_EV,HYUNDAI_IONIQ).- The
get_car_confighelper function selects the appropriate configuration based on the car fingerprint and flags. get_longitudinal_tuneapplies relevant config values (like stopping/starting speeds, delay) to the mainCarParams(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.