Proposed Car Abstraction Layer

[geohot]

Anything obvious I'm forgetting?

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

@0x8e2af1e708af8b8d;

# ******* main car state @ 100hz *******
# all speeds in m/s

struct CarState {
  errors @0: List(Error);

  # car speed
  vEgo @1 :Float32;       # best estimate of speed
  wheelSpeeds @2 :WheelSpeeds;

  # gas pedal, 0.0-1.0
  gas @3 :Float32;        # this is user + computer
  gasPressed @4 :Bool;    # this is user pedal only

  # brake pedal, 0.0-1.0
  brake @5 :Float32;      # this is user pedal only
  brakePressed @6 :Bool;  # this is user pedal only

  # steering wheel
  steeringAngle @7 :Float32;   # deg
  steeringTorque @8 :Float32;  # TODO: standardize units
  steeringPressed @9 :Bool;    # if the user is using the steering wheel

  # cruise state
  cruiseState @10 :CruiseState;

  # button presses
  buttonEvents @11 :List(ButtonEvent);

  # which packets this state came from
  canMonoTimes @12: List(UInt64);

  struct WheelSpeeds {
    # optional wheel speeds
    fl @0 :Float32;
    fr @1 :Float32;
    rl @2 :Float32;
    rr @3 :Float32;
  }

  struct CruiseState {
    enabled @0: Bool;
    speed @1: Float32;
  }

  enum Error {
    # TODO: copy from error list
    commIssue @0;
    steerUnavailable @1;
    brakeUnavailable @2;
    gasUnavailable @3;
    wrongGear @4;
    doorOpen @5;
    seatbeltNotLatched @6;
    espDisabled @7;
    wrongCarMode @8;
    steerTemporarilyUnavailable @9;
    reverseGear @10;
    # ...
  }

  # send on change
  struct ButtonEvent {
    pressed @0: Bool;
    type @1: Type;

    enum Type {
      unknown @0;
      leftBlinker @1;
      rightBlinker @2;
      accelCruise @3;
      decelCruise @4;
      cancel @5;
      altButton1 @6;
      altButton2 @7;
      altButton3 @8;
    }
  }
}

# ******* radar state @ 20hz *******

struct RadarState {
  errors @0: List(Error);
  points @1: List(RadarPoint);

  # which packets this state came from
  canMonoTimes @2: List(UInt64);

  enum Error {
    notValid @0;
  }

  # similar to LiveTracks
  # is one timestamp valid for all? I think so
  struct RadarPoint {
    trackId @0: UInt64;  # no trackId reuse

    # these 3 are the minimum required
    dRel @1: Float32; # m from the front bumper of the car
    yRel @2: Float32; # m
    vRel @3: Float32; # m/s

    # these are optional and valid if they are not NaN
    aRel @4: Float32; # m/s^2
    yvRel @5: Float32; # m/s
  }
}

# ******* car controls @ 100hz *******

struct CarControl {
  # must be true for any actuator commands to work
  enabled @0: Bool;

  # range from 0.0 - 1.0
  gas @1: Float32;
  brake @2: Float32;

  # range from -1.0 - 1.0
  steeringTorque @3 :Float32;

  cruiseControl @4: CruiseControl;
  hudControl @5: HUDControl;

  struct CruiseControl {
    cancel @0: Bool;
    override @1: Bool;
    speedOverride @2: Float32;
    accelOverride @3: Float32;
  }

  struct HUDControl {
    speedVisible @0: Bool;
    setSpeed @1: Float32;
    lanesVisible @2: Bool;
    leadVisible @3: Bool;
    visualAlert @4: VisualAlert;
    audibleAlert @5: AudibleAlert;

    enum VisualAlert {
      # these are the choices from the Honda
      # map as good as you can for your car
      none @0;
      fcw @1;
      steerRequired @2;
      brakePressed @3;
      wrongGear @4;
      seatbeltUnbuckled @5;
      speedTooHigh @6;
    }

    enum AudibleAlert {
      # these are the choices from the Honda
      # map as good as you can for your car
      none @0;
      beepSingle @1;
      beepTriple @2;
      beepRepeated @3;
      chimeSingle @4;
      chimeDouble @5;
      chimeRepeated @6;
      chimeContinuous @7;
    }
  }
}

[TheMutley]

• Think about EV : braking is part regen and part hydraulic , no RPM, no gear ratio, etc..
• Radar you can probably add angle of detection and direction of TrackID
• Plausible to broadcast to radio with Bluetooth for any audible Sound ?
• Might be interested in the stock LKA status and front cam information since some integration will leave it "running" ?

[geohot]

• Good point about EVs, the controls software doesn't really need gearRatio and RPM, so I'll remove them and replace with bool gearReverse
• angle = atan2(yRel, dRel)
• The NEO itself can do sound, but it's not as reliable and doesn't lower the volume when it plays.
• We remove the stock front cam, and that's how openpilot will be supported. Soon we will have support for cars that don't have stock cams.
• Though along these lines we should probably add support for blind spot detection on cars that have it, that way we can do automatic lane change. Will add once we find such a car.

update: Updated, reverseGear is now an error and RPM and gearRatio are removed. Controls didn't use them, and humans drive totally fine without them. Our software should treat automatic transmissions as black boxes.

[TheMutley]

Thanks.

• Could you bring us some clarifications on how the radar report it's trackIDs on the Honda/Acura? Does dRel represent the D and yRel represent the R like on this drawing :
  

• Also , how the TrackIDs are sequenced? For example, on mine Track ID 1 is the obstacle in front of the vehicle, Track ID 2 is the obstacle in front of Track ID 1, Track ID 3 / 5 is an obstacle on the left lane , Track ID 4/6 is an obstacle on the right lane. Are they reported somewhat like this on the Honda ?

• For the sound from the NEO, if you could do it like Waze does, at least on my car, it lower the music sound level and bring the Waze's notifications at the same level the music was. Pretty much like the alert sound does with the stock collision warning.

• As for blind spot detection , I do have them on mine although I never looked for the CAN information. If they're supported , I will hunt the CAN data for sure!

• One other thing you could add is the gap distance setting that some ACC has, usually 3-4 settings possible. Handy sometime to be able to change the gap.

[geohot]

dRel is the adjacent and yRel is the opposite on the right triangle to the car. The trackIds are sequential counting up.

That works if the NEO is playing the music only. Coming soon!

Yea, let me know re: BSI.

I don't like choices, more to qualify. I also feel the really short following distances supported on some cars are dangerous, since the user doesn't have time to react if the car messes up following closely.

[ingenieroariel]

I don't like choices, more to qualify. I also feel the really short following distances supported on some cars are dangerous, since the user doesn't have time to react if the car messes up following closely.

I agree with this thinking too. That said, with the stock Ford functionality at lower speeds cars behind me try to overtake me and then my car ends up leaving another big gap and it happens again. If it is not optional, hopefully openpilot maintains a safe distance in time units instead of meter units.

[geohot]

It's time units, yea.