onepilot/dragonpilot/settings_management.md

Dragonpilot Settings Management

Problem

When merging feature branches into full branch, conflicts in settings.py and params_keys.h are repetitive and manual despite being trivial (additive entries).

Root cause: Both files are additive-only structures. Multiple branches adding entries to the same arrays causes git merge conflicts on every feature merge.

Solution

Each feature branch has its own YAML file. A generator script scans all YAMLs and produces settings.py and params_keys.h.

dragonpilot/settings/           # directory for YAML files (one per feature branch)
  min-feat-lat-alka.yaml       # from min-feat/lat/alka
  min-feat-ui-torque-bar.yaml  # from min-feat/ui/torque-bar
  brands-toyota.yaml           # from brands/toyota

generate_settings.py           # generator script

Note: Each YAML file is named after the branch, and can contain settings for ANY section (Lateral, Longitudinal, UI, Device, etc.). One feature branch may need settings in multiple sections - all are defined in that branch's single YAML file.

When building, the generator scans dragonpilot/settings/*.yaml and outputs:

dragonpilot/settings.py        # generated
common/params_keys.h           # generated

Why No Conflicts

• Each branch has its own YAML file
• Git auto-merges separate files trivially
• Generator reads ALL YAMLs and combines them
• No two branches editing the same file = no conflicts

Architecture

core-feat/panel Branch

core-feat/panel provides:

• dragonpilot/settings/ directory (placeholder, YAMLs come from feature branches)
• generate_settings.py script
• dragonpilot/settings.py with empty section structure
• SConstruct integration

Feature Branches

Each feature branch adds:

• dragonpilot/settings/<feature>.yaml - settings for this feature
• Any feature-specific code

Full Branch

When merging features into full:

1. YAML files merge automatically (git handles)
2. Build runs generator → produces settings.py + params_keys.h
3. No manual conflict resolution needed for settings

YAML Schema

A single YAML file (named after the branch) can define settings in ANY number of sections.

Complete Example

# min-feat-lat-alka.yaml - One YAML per branch, can have items in multiple sections

settings:
  # Lateral settings
  - title: "Lateral"
    items:
      - key: dp_lat_alka
        type: toggle_item
        title: "Always-on Lane Keeping Assist (ALKA)"
        description: "Enable lateral control even when ACC/cruise is disengaged."
        brands: ["toyota", "hyundai", "honda"]

  # UI settings (same YAML, different section)
  - title: "UI"
    condition: "not MICI"
    items:
      - key: dp_ui_rainbow
        type: toggle_item
        title: "Rainbow Driving Path"
        description: "Like Tesla's rainbow road."

  # Longitudinal settings
  - title: "Longitudinal"
    condition: "openpilotLongitudinalControl"
    items:
      - key: dp_lon_acm
        type: toggle_item
        title: "Adaptive Coasting Mode"
        description: "Reduce braking for smoother coasting."

params_keys:
  - key: dp_lat_alka
    flags: PERSISTENT
    type: BOOL
    default: "0"

  - key: dp_ui_rainbow
    flags: PERSISTENT
    type: BOOL
    default: "0"

  - key: dp_lon_acm
    flags: PERSISTENT
    type: BOOL
    default: "0"

settings Section

settings:
  - title: "Section Name"
    condition: "brand == 'honda'"  # optional, section-level condition
    items:
      - key: dp_something
        type: toggle_item
        title: "My Setting"
        description: "Description text"
        brands: ["toyota", "honda"]  # optional, limit to specific brands
        condition: "LITE"  # optional, item-level condition
        default: 0  # for spin items
        min_val: 0  # for spin items
        max_val: 100  # for spin items
        step: 5  # for spin items
        suffix: "mph"  # for spin items
        special_value_text: "Off"  # for spin items, text for min_val
        options: ["Option1", "Option2"]  # for text_spin_button_item
        on_change:
          - target: dp_other_param
            action: set_enabled
            condition: "value > 0"
        initially_enabled_by:
          param: dp_other_param
          condition: "value > 0"
          default: 20

params_keys Section

params_keys:
  - key: dp_something
    flags: PERSISTENT  # PERSISTENT, CLEAR_ON_MANAGER_START, CLEAR_ON_OFFROAD_TRANSITION, etc.
    type: BOOL  # BOOL, INT, FLOAT, STRING, JSON, BYTES, TIME
    default: "0"  # string representation of default

Note: A params_keys entry does not require a corresponding settings entry (for internal params without UI).

Item Types

Type	Description	Additional Fields
toggle_item	On/off toggle	brands, condition
spin_button_item	Integer spinner	default, min_val, max_val, step, suffix, special_value_text
double_spin_button_item	Float spinner	Same as spin_button_item
text_spin_button_item	Dropdown/text selector	default, options

Conditions

Conditions use Python-like syntax:

Condition	Meaning
brand == 'honda'	Only show for Honda brand
brand == 'toyota'	Only show for Toyota brand
LITE	Only show on LITE hardware
not LITE	Hide on LITE hardware
not MICI	Hide when using MICI UI
openpilotLongitudinalControl	When openpilot controls longitudinal

on_change

Used to enable/disable another setting based on the current value:

on_change:
  - target: dp_lat_lca_auto_sec
    action: set_enabled
    condition: "value > 0"

Actions: set_enabled, set_visible, set_value

initially_enabled_by

Controls whether an item starts enabled based on another param's value:

initially_enabled_by:
  param: dp_lat_lca_speed
  condition: "value > 0"
  default: 20

Generator

Scans dragonpilot/settings/*.yaml, merges all entries, outputs settings.py and params_keys.h.

python generate_settings.py

SConstruct Integration

The generator should run automatically during builds:

# In SConstruct
Command(
    target=['dragonpilot/settings.py', 'common/params_keys.h'],
    source=['generate_settings.py'] + Glob('dragonpilot/settings/*.yaml'),
    action='python generate_settings.py'
)

Workflow

Development (Feature Branch)

1. Add/edit settings in dragonpilot/settings/<feature>.yaml
2. Build/test - SConstruct auto-runs the generator
3. Commit YAML file + any feature code changes

Creating Full Branch

# Start from core-feat/panel
git checkout core-feat/panel
git merge min-feat/lat/alka
git merge min-feat/ui/torque-bar
git merge brands/toyota
# ... merge all feature branches

# Resolve code conflicts normally (YAML files merge automatically)

# Build - generator runs automatically via SConstruct
scons

Generated Files

settings.py and params_keys.h are build artifacts:

• Do not edit manually - changes will be overwritten
• Optionally not committed to git - regenerated on build
• Or commit them if you want reproducible builds without rebuilding

Section Ordering

Generator defines fixed section order. Each YAML contributes to its section:

SECTION_ORDER = [
    "Toyota / Lexus",
    "VAG",
    "Mazda",
    "Lateral",
    "Longitudinal",
    "UI",
    "Device",
]

Generator scans all YAMLs, collects items by section title, outputs in fixed order.