docs: CARS.md 2.0

opendbc/car/CARS_template.md

@@ -0,0 +1,65 @@
+{% set footnote_tag = '[<sup>{}</sup>](#footnotes)' %}
+{% set star_icon = '[![star](assets/icon-star-{}.svg)](##)' %}
+{% set video_icon = '<a href="{}" target="_blank"><img height="18px" src="assets/icon-youtube.svg"></img></a>' %}
+{# Force hardware column wider by using a blank image with max width. #}
+{% set width_tag = '<a href="##"><img width=2000></a>%s<br>&nbsp;' %}
+{% set hardware_col_name = 'Hardware Needed' %}
+{% set wide_hardware_col_name = width_tag|format(hardware_col_name) -%}
+
+<!--- AUTOGENERATED FROM selfdrive/car/CARS_template.md, DO NOT EDIT. --->
+
+# Car Info
+
+A supported vehicle is one that just works when you install a comma device. All supported cars provide a better experience than any stock system. Supported vehicles reference the US market unless otherwise specified.
+
+# {{all_car_docs | length}} Known Cars with Supportability Info
+
+<div style="width: 1500px">
+
+|{{Column | map(attribute='value') | join('|') | replace(hardware_col_name, wide_hardware_col_name)}}|
+|---|---|---|{% for _ in range((Column | length) - 3) %}{{':---:|'}}{% endfor +%}
+{% for car_docs in all_car_docs %}
+|{% for column in Column %}{{car_docs.get_column(column, star_icon, video_icon, footnote_tag)}}|{% endfor %}
+
+{% endfor %}
+
+</div>
+
+### Footnotes
+{% for footnote in footnotes %}
+<sup>{{loop.index}}</sup>{{footnote}} <br />
+{% endfor %}
+
+## Community Maintained Cars
+Although they're not upstream, the community has openpilot running on other makes and models. See the 'Community Supported Models' section of each make [on our wiki](https://wiki.comma.ai/).
+
+# Don't see your car here?
+
+**openpilot can support many more cars than it currently does.** There are a few reasons your car may not be supported.
+If your car doesn't fit into any of the incompatibility criteria here, then there's a good chance it can be supported! We're adding support for new cars all the time. **We don't have a roadmap for car support**, and in fact, most car support comes from users like you!
+
+### Which cars are able to be supported?
+
+openpilot uses the existing steering, gas, and brake interfaces in your car. If your car lacks any one of these interfaces, openpilot will not be able to control the car. If your car has [ACC](https://en.wikipedia.org/wiki/Adaptive_cruise_control) and any form of [LKAS](https://en.wikipedia.org/wiki/Automated_Lane_Keeping_Systems)/[LCA](https://en.wikipedia.org/wiki/Lane_centering), then it almost certainly has these interfaces. These features generally started shipping on cars around 2016. Note that manufacturers will often make their own [marketing terms](https://en.wikipedia.org/wiki/Adaptive_cruise_control#Vehicle_models_supporting_adaptive_cruise_control) for these features, such as Hyundai's "Smart Cruise Control" branding of Adaptive Cruise Control.
+
+If your car has the following packages or features, then it's a good candidate for support.
+
+| Make | Required Package/Features |
+| ---- | ------------------------- |
+| Acura | Any car with AcuraWatch Plus will work. AcuraWatch Plus comes standard on many newer models. |
+| Ford | Any car with Lane Centering will likely work. |
+| Honda | Any car with Honda Sensing will work. Honda Sensing comes standard on many newer models. |
+| Subaru | Any car with EyeSight will work. EyeSight comes standard on many newer models. |
+| Nissan | Any car with ProPILOT will likely work. |
+| Toyota & Lexus | Any car that has Toyota/Lexus Safety Sense with "Lane Departure Alert with Steering Assist (LDA w/SA)" and/or "Lane Tracing Assist (LTA)" will work. Note that LDA without Steering Assist will not work. These features come standard on most newer models. |
+| Hyundai, Kia, & Genesis | Any car with Smart Cruise Control (SCC) and Lane Following Assist (LFA) or Lane Keeping Assist (LKAS) will work. LKAS/LFA comes standard on most newer models. Any form of SCC will work, such as NSCC. |
+| Chrysler, Jeep, & Ram | Any car with LaneSense and Adaptive Cruise Control will likely work. These come standard on many newer models. |
+
+### FlexRay
+
+All the cars that openpilot supports use a [CAN bus](https://en.wikipedia.org/wiki/CAN_bus) for communication between all the car's computers, however a CAN bus isn't the only way that the computers in your car can communicate. Most, if not all, vehicles from the following manufacturers use [FlexRay](https://en.wikipedia.org/wiki/FlexRay) instead of a CAN bus: **BMW, Mercedes, Audi, Land Rover, and some Volvo**. These cars may one day be supported, but we have no immediate plans to support FlexRay.
+
+### Toyota Security
+
+openpilot does not yet support these Toyota models due to a new message authentication method.
+[Vote](https://comma.ai/shop#toyota-security) if you'd like to see openpilot support on these models.

opendbc/car/__init__.py

@@ -3,12 +3,12 @@
 from collections import namedtuple
 from dataclasses import dataclass
 from enum import IntFlag, ReprEnum, EnumType
-from dataclasses import replace
+from dataclasses import replace, field
 
 from panda import uds
 from opendbc.car import structs
 from opendbc.car.can_definitions import CanData
-from opendbc.car.docs_definitions import CarDocs
+from opendbc.car.docs_definitions import CarDocs, OtherCarDocs
 from opendbc.car.common.numpy_fast import clip, interp
 
 # set up logging
@@ -321,3 +321,10 @@ def create_dbc_map(cls) -> dict[str, DbcDict]:
   @classmethod
   def with_flags(cls, flags: IntFlag) -> set['Platforms']:
     return {p for p in cls if p.config.flags & flags}
+
+
+@dataclass(order=True)
+class OtherPlatformConfig(PlatformConfig):
+  car_docs: list[OtherCarDocs]
+  specs: CarSpecs | None = None
+  dbc_dict: DbcDict = field(default_factory=lambda: dbc_dict('unknown', None))

opendbc/car/docs.py

@@ -1,13 +1,23 @@
+#!/usr/bin/env python3
+import argparse
 from collections import defaultdict
 import jinja2
 from enum import Enum
 from natsort import natsorted
+import os
 
 from opendbc.car import gen_empty_fingerprint
 from opendbc.car.structs import CarParams
 from opendbc.car.docs_definitions import CarDocs, Column, CommonFootnote, PartType
 from opendbc.car.car_helpers import interfaces, get_interface_attr
-from opendbc.car.values import PLATFORMS
+from opendbc.car.values import DOC_PLATFORMS
+from opendbc.car.mock.values import CAR as MOCK
+
+
+# TODO: does opendbc need its own version of openpilot.common.basedir?
+BASEDIR = os.path.abspath(os.path.join(os.path.dirname(os.path.realpath(__file__)), "../../"))
+CARS_MD_OUT = os.path.join(BASEDIR, "opendbc", "car", "docs", "CARS.md")
+CARS_MD_TEMPLATE = os.path.join(BASEDIR, "opendbc", "car", "CARS_template.md")
 
 
 def get_all_footnotes() -> dict[Enum, int]:
@@ -20,14 +30,14 @@ def get_all_footnotes() -> dict[Enum, int]:
 def get_all_car_docs() -> list[CarDocs]:
   all_car_docs: list[CarDocs] = []
   footnotes = get_all_footnotes()
-  for model, platform in PLATFORMS.items():
+  for model, platform in DOC_PLATFORMS.items():
     car_docs = platform.config.car_docs
-    # If available, uses experimental longitudinal limits for the docs
-    CP = interfaces[model][0].get_params(platform, fingerprint=gen_empty_fingerprint(),
-                                         car_fw=[CarParams.CarFw(ecu=CarParams.Ecu.unknown)], experimental_long=True, docs=True)
-
-    if CP.dashcamOnly or not len(car_docs):
+    if not len(car_docs):
       continue
+    cp_model, cp_platform = (model, platform) if model in interfaces else ("MOCK", MOCK.MOCK)
+    # If available, uses experimental longitudinal limits for the docs
+    CP = interfaces[cp_model][0].get_params(cp_platform, fingerprint=gen_empty_fingerprint(),
+                                             car_fw=[CarParams.CarFw(ecu=CarParams.Ecu.unknown)], experimental_long=True, docs=True)
 
     # A platform can include multiple car models
     for _car_docs in car_docs:
@@ -57,3 +67,16 @@ def generate_cars_md(all_car_docs: list[CarDocs], template_fn: str) -> str:
                                  group_by_make=group_by_make, footnotes=footnotes,
                                  Column=Column)
   return cars_md
+
+
+if __name__ == "__main__":
+  parser = argparse.ArgumentParser(description="Auto generates supported cars documentation",
+                                   formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+
+  parser.add_argument("--template", default=CARS_MD_TEMPLATE, help="Override default template filename")
+  parser.add_argument("--out", default=CARS_MD_OUT, help="Override default generated filename")
+  args = parser.parse_args()
+
+  with open(args.out, 'w') as f:
+    f.write(generate_cars_md(get_all_car_docs(), args.template))
+  print(f"Generated and written to {args.out}")