Skip to content

integration.md

Latest commit

 

History

History
99 lines (90 loc) · 5.32 KB

integration.md

File metadata and controls

99 lines (90 loc) · 5.32 KB

openpilot Integration

Minimal

  1. Add capnp definitions to cereal.
    • In openpilot cereal/custom.capnp replace CustomReserved17-19 with the Mapd types and structs in cereal/custom/custom.capnp line 65 to the end.
    • In openpilot cereal/log.capnp replace customReserved17-19 in the Event struct with the mapd types. 
      mapdExtendedOut @143 :Custom.MapdExtendedOut;
mapdIn @144 :Custom.MapdIn;
mapdOut @145 :Custom.MapdOut;
  2. Add mapdOut as a service in openpilot cereal/services.py 
    "mapdOut": (True, 20., 20, QueueSize.MEDIUM),
  3. Add MapdSettings to openpilot common/params_keys.h 
     {"MapdSettings", {PERSISTENT, JSON}},
  4. Add mapd binary to openpilot selfdrive directory
  5. Add mapd to openpilot system/manager/process_config.py 
    NativeProcess("mapd", "selfdrive", ["./mapd"], always_run),
  6. In openpilot selfdrive/controls/plannerd.py add mapdOut to SubMaster
  7. In openpilot selfdrive/controls/lib/longitudinal_planner.py add the following code right before the force_slow_decel if statement: 
    if sm.valid['mapdOut']:
  if sm['mapdOut'].suggestedSpeed > 0 and v_cruise > sm['mapdOut'].suggestedSpeed:
    v_cruise = sm['mapdOut'].suggestedSpeed
  8. ssh into the comma device with a running mapd instance and run ./selfdrive/mapd i to download maps and configure mapd.

Advanced

mapd offers a lot more data and options to allow for customization of behavior outside of the basic example above as well as outputs for use in the openpilot ui. The outputs are described in detail in outputs.md. Inputs for controlling mapd behavior are described in detail in inputs.md. There are also built in defaults, including settings and map download areas, that can be overriden as described in overriding-internal-defaults.md.

In general I'd suggest integrating mapd into your openpilot fork in the way you desire your fork to work, and not exposing many of the options available in mapd. However, if you extend mapd functionality I suggest always having a way to enable mapd in the simple integration described above that allows for advanced users to set the mapd options and use the built in mapd behavior if they so wish. mapd provides a terminal ui that allows a user to configure all of its advanced settings, so an advanced user can ssh in and use that to configure mapd in ways not provided or officially supported by your openpilot fork. This also means that if you have additional toggles for map features outside of the mapd settings that I would suggest trying to ensure your ui still displays mapd outputs when those additional toggles are disabled, this allows for those advanced user to still see at least some basic information about how mapd is operating if they choose to use the built in options as opposed to the fork options. But, don't sacrifice your fork functionality in pursuit of this so that there's still variety in the ideas and operation of various forks.

If you have a feature for different map behavior than what mapd provides built-in, please consider reaching out to see if it can be added directly to mapd. One goal with this version of mapd is to provide many different behavior options for its users, so adding additional options is welcome.

Some core things most forks will want to implement in their UI include: A download menu with download progress, toggles for enabling functionality, display of mapd outputs including speed limits, suggested speed, and road name.

For the download menu, I suggest making your ui dynamic based off of the download areas json. Ideally make a copy of settings/download_menu.json and place it in the root of your openpilot fork with the name mapd_download_menu.json. mapd will then use your copy and any modifications you make to it when you trigger downloads as long as you follow the schema described in ovverriding-internal-defaults.md. One thing I don't want to personally support is updates to the default download menu, so if you want additional areas to be included the best way is to maintain your own override file as described, and you can generally expect there to not be any updates to the file included in this mapd repo. The download progress output is part of the mapdExtendedOut cereal message and is described in outputs.md.

For toggles, if the functionality is built-in to mapd you can control the mapdSettings through mapdIn messages as described in inputs.md. Each setting also has a corresponding key in the MapdSettings param json that is described in settings.md. You can change the defaults for the mapd settings by providing a custom defaults json as described in overriding-internal-defaults.md.

Common outputs for use in the openpilot ui will be part of the MapdOut cereal message as described in outputs.md. The most common values used for the ui will likely be speedLimit, roadName, and suggestedSpeed which are explained in more detail in outputs.md. Some other outputs that are often of interest would be nextSpeedLimit, nextSpeedLimitDistance, and speedLimitAccepted which are also further described in outputs.md.

If you want to have completely custom trigger logic for upcoming curves, mapd still outputs the suggested velocities/estimated curvature paths. The path output for those values is part of the MapdExtendedOut cereal message and is described in detail in outputs.md.