onepilot/cereal/custom.capnp

using Cxx = import "./include/c++.capnp";
$Cxx.namespace("cereal");

@0xb526ba661d550a59;

# custom.capnp: a home for empty structs reserved for custom forks
# These structs are guaranteed to remain reserved and empty in mainline
# cereal, so use these if you want custom events in your fork.

# DO rename the structs
# DON'T change the identifier (e.g. @0x81c2f05a394cf4af)

struct AlwaysOnLateral {
  state @0 :AlwaysOnLateralState;
  enabled @1 :Bool;
  active @2 :Bool;
  available @3 :Bool;

  enum AlwaysOnLateralState {
    disabled @0;
    paused @1;
    enabled @2;
    softDisabling @3;
    overriding @4;
  }
}

# Same struct as Log.RadarState.LeadData
struct LeadData {
  dRel @0 :Float32;
  yRel @1 :Float32;
  vRel @2 :Float32;
  aRel @3 :Float32;
  vLead @4 :Float32;
  dPath @6 :Float32;
  vLat @7 :Float32;
  vLeadK @8 :Float32;
  aLeadK @9 :Float32;
  fcw @10 :Bool;
  status @11 :Bool;
  aLeadTau @12 :Float32;
  modelProb @13 :Float32;
  radar @14 :Bool;
  radarTrackId @15 :Int32 = -1;

  aLeadDEPRECATED @5 :Float32;
}

struct IQState @0x81c2f05a394cf4af {
  aol @0 :AlwaysOnLateral;

  enum AudibleAlert {
    none @0;

    engage @1;
    disengage @2;
    refuse @3;

    warningSoft @4;
    warningImmediate @5;

    prompt @6;
    promptRepeat @7;
    promptDistracted @8;

    # unused, these are reserved for upstream events so we don't collide
    reserved9 @9;
    reserved10 @10;
    reserved11 @11;
    reserved12 @12;
    reserved13 @13;
    reserved14 @14;
    reserved15 @15;
    reserved16 @16;
    reserved17 @17;
    reserved18 @18;
    reserved19 @19;
    reserved20 @20;
    reserved21 @21;
    reserved22 @22;
    reserved23 @23;
    reserved24 @24;
    reserved25 @25;
    reserved26 @26;
    reserved27 @27;
    reserved28 @28;
    reserved29 @29;
    reserved30 @30;

    promptSingleLow @31;
    promptSingleHigh @32;
  }
}

struct IQModelManager @0xaedffd8f31e7b55d {
  activeBundle @0 :ModelBundle;
  selectedBundle @1 :ModelBundle;
  availableBundles @2 :List(ModelBundle);

  struct DownloadUri {
    uri @0 :Text;
    sha256 @1 :Text;
  }

  enum DownloadStatus {
    notDownloading @0;
    downloading @1;
    downloaded @2;
    cached @3;
    failed @4;
  }

  struct DownloadProgress {
    status @0 :DownloadStatus;
    progress @1 :Float32;
    eta @2 :UInt32;
  }

  struct Artifact {
    fileName @0 :Text;
    downloadUri @1 :DownloadUri;
    downloadProgress @2 :DownloadProgress;
  }

  struct Model {
    type @0 :Type;
    artifact @1 :Artifact;  # Main artifact
    metadata @2 :Artifact;  # Metadata artifact

    enum Type {
      supercombo @0;
      navigation @1;
      vision @2;
      policy @3;
      offPolicy @4;
    }
  }

  enum Runner {
    snpe @0;
    tinygrad @1;
    stock @2;
  }

  struct Override {
    key @0 :Text;
    value @1 :Text;
  }

  struct ModelBundle {
    index @0 :UInt32;
    internalName @1 :Text;
    displayName @2 :Text;
    models @3 :List(Model);
    status @4 :DownloadStatus;
    generation @5 :UInt32;
    environment @6 :Text;
    runner @7 :Runner;
    is20hz @8 :Bool;
    ref @9 :Text;
    minimumSelectorVersion @10 :UInt32;
    overrides @11 :List(Override);
  }
}

struct IQPlan @0xf35cc4560bbf6ec2 {
  iqDynamic @0 :IQDynamicControl;
  longitudinalPlanSource @1 :LongitudinalPlanSource;
  smartCruiseControl @2 :SmartCruiseControl;
  speedLimit @3 :SpeedLimit;
  vTarget @4 :Float32;
  aTarget @5 :Float32;
  events @6 :List(IQOnroadEvent.Event);
  e2eAlerts @7 :E2eAlerts;

  struct IQDynamicControl {
    state @0 :IQDynamicControlState;
    enabled @1 :Bool;
    active @2 :Bool;

    enum IQDynamicControlState {
      acc @0;
      blended @1;
    }
  }

  struct SmartCruiseControl {
    vision @0 :Vision;
    map @1 :Map;

    struct Vision {
      state @0 :VisionState;
      vTarget @1 :Float32;
      aTarget @2 :Float32;
      currentLateralAccel @3 :Float32;
      maxPredictedLateralAccel @4 :Float32;
      enabled @5 :Bool;
      active @6 :Bool;
    }

    struct Map {
      state @0 :MapState;
      vTarget @1 :Float32;
      aTarget @2 :Float32;
      enabled @3 :Bool;
      active @4 :Bool;
    }

    enum VisionState {
      disabled @0; # System disabled or inactive.
      enabled @1; # No predicted substantial turn on vision range.
      entering @2; # A substantial turn is predicted ahead, adapting speed to turn comfort levels.
      turning @3; # Actively turning. Managing acceleration to provide a roll on turn feeling.
      leaving @4; # Road ahead straightens. Start to allow positive acceleration.
      overriding @5; # System overriding with manual control.
    }

    enum MapState {
      disabled @0; # System disabled or inactive.
      enabled @1; # No predicted substantial turn on map range.
      turning @2; # Actively turning. Managing acceleration to provide a roll on turn feeling.
      overriding @3; # System overriding with manual control.
    }
  }

  struct SpeedLimit {
    resolver @0 :Resolver;
    assist @1 :Assist;

    struct Resolver {
      speedLimit @0 :Float32;
      distToSpeedLimit @1 :Float32;
      source @2 :Source;
      speedLimitOffset @3 :Float32;
      speedLimitLast @4 :Float32;
      speedLimitFinal @5 :Float32;
      speedLimitFinalLast @6 :Float32;
      speedLimitValid @7 :Bool;
      speedLimitLastValid @8 :Bool;
    }

    struct Assist {
      state @0 :AssistState;
      enabled @1 :Bool;
      active @2 :Bool;
      vTarget @3 :Float32;
      aTarget @4 :Float32;
    }

    enum Source {
      none @0;
      car @1;
      map @2;
    }

    enum AssistState {
      disabled @0;
      inactive @1; # No speed limit set or not enabled by parameter.
      preActive @2;
      pending @3; # Awaiting new speed limit.
      adapting @4; # Reducing speed to match new speed limit.
      active @5; # Cruising at speed limit.
    }
  }

  enum LongitudinalPlanSource {
    cruise @0;
    sccVision @1;
    sccMap @2;
    speedLimitAssist @3;
  }

  struct E2eAlerts {
    greenLightAlert @0 :Bool;
    leadDepartAlert @1 :Bool;
  }
}

struct IQOnroadEvent @0xda96579883444c35 {
  events @0 :List(Event);

  struct Event {
    name @0 :EventName;

    # event types
    enable @1 :Bool;
    noEntry @2 :Bool;
    warning @3 :Bool;   # alerts presented only when  enabled or soft disabling
    userDisable @4 :Bool;
    softDisable @5 :Bool;
    immediateDisable @6 :Bool;
    preEnable @7 :Bool;
    permanent @8 :Bool; # alerts presented regardless of openpilot state
    overrideLateral @10 :Bool;
    overrideLongitudinal @9 :Bool;
  }

  enum EventName {
    lkasEnable @0;
    lkasDisable @1;
    manualSteeringRequired @2;
    manualLongitudinalRequired @3;
    silentLkasEnable @4;
    silentLkasDisable @5;
    silentBrakeHold @6;
    silentWrongGear @7;
    silentReverseGear @8;
    silentDoorOpen @9;
    silentSeatbeltNotLatched @10;
    silentParkBrake @11;
    controlsMismatchLateral @12;
    hyundaiRadarTracksConfirmed @13;
    experimentalModeSwitched @14;
    wrongCarModeAlertOnly @15;
    pedalPressedAlertOnly @16;
    laneTurnLeft @17;
    laneTurnRight @18;
    speedLimitPreActive @19;
    speedLimitActive @20;
    speedLimitChanged @21;
    speedLimitPending @22;
    e2eChime @23;
  }
}

struct IQCarParams @0x80ae746ee2596b11 {
  flags @0 :UInt32;        # flags for car specific quirks in iqpilot
  safetyParam @1 : Int16;  # flags for iqpilot's custom safety flags
  pcmCruiseSpeed @3 :Bool;
  enableGasInterceptor @4 :Bool;

  neuralNetworkLateralControl @2 :NeuralNetworkLateralControl;

  struct NeuralNetworkLateralControl {
    model @0 :Model;
    fuzzyFingerprint @1 :Bool;

    struct Model {
      path @0 :Text;
      name @1 :Text;
    }
  }
}

struct IQCarControl @0xa5cd762cd951a455 {
  aol @0 :AlwaysOnLateral;
  params @1 :List(Param);
  leadOne @2 :LeadData;
  leadTwo @3 :LeadData;

  struct Param {
    key @0 :Text;
    type @2 :ParamType;
    value @3 :Data;

    valueDEPRECATED @1 :Text; # The data type change may cause issues with backwards compatibility.
  }

  enum ParamType {
    string @0;
    bool @1;
    int @2;
    float @3;
    time @4;
    json @5;
    bytes @6;
  }
}

struct IQBackupManager @0xf98d843bfd7004a3 {
  backupStatus @0 :Status;
  restoreStatus @1 :Status;
  backupProgress @2 :Float32;
  restoreProgress @3 :Float32;
  lastError @4 :Text;
  currentBackup @5 :BackupInfo;
  backupHistory @6 :List(BackupInfo);

  enum Status {
    idle @0;
    inProgress @1;
    completed @2;
    failed @3;
  }

  struct Version {
    major @0 :UInt16;
    minor @1 :UInt16;
    patch @2 :UInt16;
    build @3 :UInt16;
    branch @4 :Text;
  }

  struct MetadataEntry {
    key @0 :Text;
    value @1 :Text;
    tags @2 :List(Text);
  }

  struct BackupInfo {
    deviceId @0 :Text;
    version @1 :UInt32;
    config @2 :Text;
    isEncrypted @3 :Bool;
    createdAt @4 :Text;  # ISO timestamp
    updatedAt @5 :Text;  # ISO timestamp
    iqpilotVersion @6 :Version;
    backupMetadata @7 :List(MetadataEntry);
  }
}

struct IQCarState @0xb86e6369214c01c8 {
  speedLimit @0 :Float32;
  accelPressed @1 :Bool;
  decelPressed @2 :Bool;
}

struct IQLiveMapData @0xf416ec09499d9d19 {
  speedLimitValid @0 :Bool;
  speedLimit @1 :Float32;
  speedLimitAheadValid @2 :Bool;
  speedLimitAhead @3 :Float32;
  speedLimitAheadDistance @4 :Float32;
  roadName @5 :Text;
}

struct IQModelDataV2 @0xa1680744031fdb2d {
  laneTurnDirection @0 :TurnDirection;

  enum TurnDirection {
    none @0;
    turnLeft @1;
    turnRight @2;
  }
}

enum NavDirection {
  none @0;
  left @1;
  right @2;
}

struct IQNavState @0xcb9fd56c7057593a {
  # Navigation state and guidance information
  active @0 :Bool;                          # Whether navigation is currently active
  destinationValid @1 :Bool;                # Whether we have a valid destination

  # Current position and route info
  distanceRemaining @2 :Float32;            # Total distance remaining to destination (m)
  timeRemaining @3 :Float32;                # Estimated time remaining to destination (s)
  currentSegmentIndex @4 :UInt32;           # Index of current route segment
  totalSegments @5 :UInt32;                 # Total number of segments in route

  # Next maneuver information
  nextManeuverValid @6 :Bool;               # Whether next maneuver data is valid
  nextManeuverDistance @7 :Float32;         # Distance to next maneuver (m)
  nextManeuverType @8 :ManeuverType;        # Type of next maneuver
  nextManeuverDirection @9 :IQModelDataV2.TurnDirection;  # Direction for next maneuver
  nextManeuverDescription @10 :Text;        # Human-readable maneuver description
  nextManeuverAngle @21 :Float32;           # Turn angle in degrees (for angle-adaptive enforcement)

  # Turn desire control for lateral planning
  shouldSendTurnDesire @11 :Bool;           # Whether to send turn desires to model
  turnDesireDirection @12 :IQModelDataV2.TurnDirection;   # Direction for turn desire

  # Lane change desire control for highway exits/ramps (>45 mph)
  shouldSendLaneChangeDesire @22 :Bool;     # Whether to send lane change desires for high-speed exits
  laneChangeDesireDirection @23 :IQModelDataV2.TurnDirection;  # Direction for lane change desire

  # Speed guidance for longitudinal planning
  targetSpeed @13 :Float32;                 # Target speed for upcoming maneuver (m/s)
  targetSpeedValid @14 :Bool;               # Whether target speed is valid

  # Destination info
  destinationLatitude @15 :Float64;
  destinationLongitude @16 :Float64;
  destinationName @17 :Text;

  # Lane positioning guidance for exits/turns
  shouldSendLanePositioning @18 :Bool;      # Whether to send lane positioning desires (keepLeft/keepRight)
  lanePositioningDirection @19 :IQModelDataV2.TurnDirection;  # Direction for lane positioning

  # Lane tracking debug info (model vs GPS comparison for testing)
  laneDebugInfo @20 :LaneDebugInfo;

  # Navigation-specific UI event fields (separate from model/desire system)
  navTurnDesireDirection @24 :NavDirection;           # For "Navigation: Turning Left/Right" UI alerts
  navLaneChangeDesireDirection @25 :NavDirection;     # For "Navigation: Initiating Lane Change" UI alerts
  navLanePositioningDirection @26 :NavDirection;      # For future lane positioning UI alerts
  navSpeedTargetActive @27 :Bool;                     # For "Navigation: Reducing Speed" UI alert

  # Second next maneuver information (for "Then" section in navigation banner UI)
  secondNextManeuverValid @28 :Bool;                  # Whether second next maneuver data is valid
  secondNextManeuverType @29 :ManeuverType;           # Type of second next maneuver
  secondNextManeuverDirection @30 :NavDirection;      # Direction for second next maneuver
  secondNextManeuverDistance @31 :Float32;            # Distance to second next maneuver (m)
  nextManeuverModifier @32 :Text;                     # Raw Mapbox modifier for next maneuver (slight_left, sharp_right, etc.)
  secondNextManeuverModifier @33 :Text;               # Raw Mapbox modifier for second next maneuver

  enum ManeuverType {
    none @0;
    turn @1;              # Regular turn at intersection
    exit @2;              # Highway exit
    merge @3;             # Merge onto highway
    fork @4;              # Road fork
    continueStraight @5;  # Continue straight
    arrive @6;            # Arrive at destination
    roundabout @7;        # Enter/exit roundabout
  }

  struct LaneDebugInfo {
    modelLane @0 :Text;             # "left", "middle", "right", "unknown"
    modelConfidence @1 :Float32;     # 0.0-1.0
    gpsLane @2 :Text;                # "left", "middle", "right", "unknown"
    gpsConfidence @3 :Float32;       # 0.0-1.0
    lateralOffset @4 :Float32;       # Meters from road centerline (negative=left, positive=right)
    gpsAccuracy @5 :Float32;         # GPS position accuracy (meters)
    agreement @6 :Bool;              # Do model and GPS agree?
  }
}

struct CustomReserved10 @0xa8e2e4a8c6f4d3b2 {
}

struct CustomReserved11 @0xc2243c65e0340384 {
}

struct CustomReserved12 @0x9ccdc8676701b412 {
}

struct CustomReserved13 @0xcd96dafb67a082d0 {
}

struct CustomReserved14 @0xb057204d7deadf3f {
}

struct CustomReserved15 @0xbd443b539493bc68 {
}

struct CustomReserved16 @0xfc6241ed8877b611 {
}

struct CustomReserved17 @0xa30662f84033036c {
}

struct CustomReserved18 @0xc86a3d38d13eb3ef {
}

struct CustomReserved19 @0xa4f1eb3323f5f582 {
}