StarPilot/openpilot/starpilot/speed_limits/README.md

# Speed Limit Controller

SLC uses the ordinary cruise set speed as its only vehicle-speed target. A qualified
limit from the selected Dashboard, Maps, or Vision source is an input to adoption.
Acceptance applies the configured offset within the existing 8–145 km/h cruise
bounds and sends a qualified command to card,
which owns `vCruise` and `vCruiseCluster`. SLC supplies no separate planner ceiling.
Lead, curve, stop and actuator safety constraints retain their existing owners.

## New limits and adoption

A different numeric limit from the selected source starts a new decision, including
while a set-speed override is active. A source/road identity change at the same
numeric limit does not start another decision. A decline remains effective across
a source gap or same-value provider change; a later different limit starts a new
window, including when an earlier numeric limit returns.

While StarPilot owns speed control, a proposed limit whose adjusted, rounded target
already matches both current SET values is recorded without another confirmation
or cruise command. The comparison uses the same mph/km/h rounding as Card, not
actual traveling speed. A presented Accept or Decline takes priority, and a decline
remains effective for that proposal. If SET reaches the target during a prompt,
the prompt closes without changing speed. An earlier command must first settle,
and SET must be observed after its receipt or expiry, before alignment is trusted.
Received-limit memory still manages proposal changes and declined choices.
An expired confirmation stays declined even if SET now matches. Changing only
display units renews pending actions while preserving accepted limits, declines, manual
overrides and the already applied SET.

With Automatic adoption on, qualified new limits are adopted immediately.
With it off, the stationary confirmation card gives two gentle purple pulses
(700 ms each, separated by 200 ms), then rests until the 3.2-second cycle repeats.
Only the lower part of the card pulses; the speed and source remain steady.
The arrow remains relative to vehicle speed.
Outside manual confirmation, large UI uses the same US or Vienna sign at 1.25×
scale beside SET speed.
US signs share a cached antialiased white outline with a transparent interior;
the offset fits inside the fixed sign height on both screens.
Both sign styles identify the displayed source: DASH for Dashboard, OSM for offline
Maps, and VISION for the vision model. Explicit Mapbox readings in historical
replay use NAV; unidentified sources keep SPEED. Retained readings use LAST.
Both styles place only this source above the number, beside any pending arrow.
The source and arrow share a centered row; all sign contents use the same geometry
on both screens. Small arrows are baked at double resolution and text is aligned
to final pixels for clear native rendering.
Steering-wheel + accepts and − declines. Tapping the sign opens the same
Accept / Reject choices on either native screen. A pending manual choice expires
after ten monotonic seconds, including time without active longitudinal control.
Decline and timeout leave set speed unchanged. An action at the exact deadline
can still complete its presented decision; a later action cannot accept it.

The existing saved `SLCConfirmation` bit is retained: `0` means Automatic adoption
on and `1` means off. Both native settings layouts show the inverse as Automatic
adoption. Legacy directional confirmation and override preferences do not change
this policy. No new saved preference or dependency is needed.

Only a finite positive source observation can propose a limit. Missing, stale and
unknown observations stay distinct. Source loss clears a pending choice; it cannot
change set speed. While the publisher remains fresh, the widget retains the latest
received limit and offset with an unavailable status, independently of accepted
history and the previous-limit fallback preference. A LAST marker identifies the
retained reading on either screen. Offset-only edits preserve accepted and
rejected state and renew action identities. A changed offset can update the set
speed of the accepted current limit; source loss defers this command until that
limit is qualified again.

## Set speed and accelerator

A qualified manual change to a different set speed marks an override, for increases
and decreases. An X crosses the sign while override is active. Returning to the
applied set speed clears it, using card's receipt to account for whole-unit rounding. Adopting
a new limit also clears it. Adoption retains the ordinary buttons' 0.1 km/h internal
precision, including for mph targets. New-limit decisions continue during override.

Ordinary software SET adjustments use the saved short-press and held-press intervals
on every make, including PCM vehicles while SLC owns SET. Toyota uses Swap Toyota
Cruise Steps for both native cruise and software SET: off selects short 1 / hold 5,
and on selects short 5 / hold 1. Other makes use CustomCruise and CustomCruiseLong.
Confirmation presses and native resume keep their existing meanings; they do not
also apply an interval step. Toyota's native cruise ceiling still limits software SET.

The accelerator temporarily allows higher vehicle speed without changing set speed
or creating an SLC override. Adoption and confirmation can update software set
speed while accelerator override temporarily suspends actuator output. On release the ordinary planner approaches set speed
using the currently selected braking profile. Existing lead and stopping constraints
continue to apply.

With SLC enabled and system longitudinal control available, card owns software set
speed even on PCM vehicles; PCM still owns engagement. Native PCM setpoint changes
cannot overwrite an adopted software set speed. When SLC is off, the original PCM
set-speed path is restored. Stock longitudinal control never gains SLC commands.

## Source and command qualification

Source selection, registered vehicle capabilities, strict saved-setting decoding,
Dashboard parser freshness, Maps road qualification, and Vision clock/inference
checks remain in their source adapters. Vision still requires its separate display
and control qualification. Online providers are not connected as live control
sources. See [selection](SELECTION.md), [Maps](MAP_SOURCE.md), and the pinned camera
[model provenance](vision/assets/PROVENANCE.md).

Every action binds the current session, decision and presentation. The causal ledger
keeps consumed confirmation presses out of the ordinary cruise-button path, through
held repeats and release. Accept and Reject cannot follow a replaced source
candidate, including a replacement at the same numeric speed in the action's
planner cycle. Such a replacement preserves the decision and its deadline but
renews its presentation. Card checks active system-longitudinal authority, command
and state age, matching presentation and source, expected current set speed, legal
speed bounds, and intervening buttons before applying a command once. Dashboard
commands also match the local OEM episode. Maps and Vision commands bind the fresh
qualified planner presentation. A command receipt distinguishes application from
limit acceptance. Rejected or expired commands may retry with current evidence
while the accepted limit and expected set speed remain current, with no pending
decision or manual override. Applied commands are not repeated.
Declining or timing out a returned limit never revives an earlier adoption command;
the historical adoption remains recorded independently of the new rejection.

Transport changes append to reserved custom messages. `SlcState` retains automatic
pending metadata at ordinals 51–52 and latest-received display metadata at 53–55.
`SlcCruiseCommand` appends its source at 14 and
a bidirectional adoption kind; historical fields and enum ordinals remain reserved.
Official vehicle schemas are unchanged. Historical SLC ceiling fields stay empty.

Host tests cover decisions, source validation, commands, cruise buttons, profile
selection and both UI layouts. Synthetic captures and host tests do not establish
camera accuracy, device timing under load, or onroad behavior.