Files
sunnypilot-byd/opendbc_repo/opendbc/sunnypilot/car/hyundai/longitudinal/README.md
T
github-actions[bot] de77c89cf6 sunnypilot v2026.002.000
version: sunnypilot v2026.002.000 (staging)
date: 2026-07-21T07:44:02
master commit: 2c334ede443d7391d27575af8c854a095ba702a8
2026-07-21 07:44:02 +00:00

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

  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.