[Legal Mode] Apply MCCONF ERPM limits

[KozakBartosz]

Parent

• [Legal Mode] Add UI and speed alert #221

What to build

Implement the board-enforced part of Legal Mode using the real VESC motor ERPM limits, not Refloat tiltback/pushback.

The goal: if the board is placed on a testing device and pushed/throttled, the controller itself should enforce the Legal Speed Limit through VESC ERPM limits. Legal Mode's sound warning from #221 still warns before the hard limit: Legal Warning Speed = Legal Speed Limit - 5 km/h by default.

This issue deliberately replaces any tiltback-based plan. Do not implement this by changing Refloat tiltback fields such as tiltback_constant_erpm or tiltback_variable_erpm.

This issue is blocked by #223, which should add the reusable safe MCCONF read/edit/write/verify capability. This issue should consume that capability for Legal Mode.

Expected behavior:

• When the rider enables optional Board Speed Limit, derive ERPM from the selected Legal Speed Limit.
• Write real VESC motor configuration ERPM limits, likely l_max_erpm and l_min_erpm, through the MCCONF path from [Board] Add MCCONF editor #223.
• Apply both forward and reverse limits coherently, e.g. l_max_erpm = +targetErpm and l_min_erpm = -targetErpm, unless VESC semantics or board direction require a different signed mapping.
• Capture previous ERPM limit values only when Board Speed Limit transitions from disabled to enabled.
• Do not overwrite the captured restore baseline while Board Speed Limit is already enabled, even if the rider changes Legal Speed Limit from one value to another.
• When Board Speed Limit is disabled, restore the original captured ERPM limits and then clear the captured baseline.
• Keep [Legal Mode] Add UI and speed alert #221's generated geiger speed alert active while Legal Mode is active, with warning sound starting before the real ERPM limit.
• Never show Board Speed Limit as applied unless readback/verification confirms the controller has the intended ERPM limits.

VESC source references to verify during implementation:

• mc_configuration contains l_min_erpm, l_max_erpm, l_max_erpm_fbrake, and related motor config fields.
• VESC Tool packet parsing reads l_min_erpm and l_max_erpm from MCCONF payloads with scale 1000.0.
• Commands to investigate: COMM_GET_MCCONF, COMM_SET_MCCONF, and possibly temporary variants if supported by the connected firmware.

Likely files

• src/screens/center/TuneDrawer.tsx - Legal Mode UI from [Legal Mode] Add UI and speed alert #221; connect optional Board Speed Limit to apply/restore flow.
• src/store/boardStore.ts or a new Legal Mode store under src/store/ - persist applied state and restore baseline carefully.
• src/lib/tune/tunePreview.ts - existing ERPM conversion logic; extract to a pure shared helper before using it for real board writes.
• modules/vesc-ble/src/index.ts - JS/native API surface from [Board] Add MCCONF editor #223 for applying/restoring MCCONF ERPM limits.
• modules/vesc-ble/android/src/main/java/expo/modules/vescble/VescProtocol.kt - MCCONF command ids/packet helpers from [Board] Add MCCONF editor #223.
• modules/vesc-ble/ios/VescProtocol.swift - iOS MCCONF parity from [Board] Add MCCONF editor #223.
• docs/legal-mode-speed-limits.md - Legal Speed Limit and warning-speed defaults.

Implementation hints

• This is a Firmware-Dependent Command. Require a connected Board Session and trusted Board Link before reading or writing MCCONF.
• Use the MCCONF read/edit/write/verify capability from [Board] Add MCCONF editor #223. Do not add a second ad hoc MCCONF writer here.
• Preserve baseline values as a Legal Mode restore snapshot. This snapshot represents the board values before Legal Mode changed anything.
• If rider changes Legal Speed Limit while Board Speed Limit is already enabled, apply the new ERPM target but keep the old restore snapshot unchanged.
• Only clear or replace the restore snapshot after Board Speed Limit is disabled and restore succeeds, or when the rider explicitly chooses to accept the current limited values as the new normal.
• Decide explicitly whether l_max_erpm_fbrake / l_max_erpm_fbrake_cc must also change for the legal test scenario. Do not change them by guesswork; document the decision in the PR.
• If motor direction/board direction means positive ERPM is not always forward, verify sign behavior against live telemetry before writing symmetric limits.
• Use [Legal Mode] Add UI and speed alert #221's alert behavior for warning sounds. This issue should not create a separate warning system.
• Emit native Diagnostic Events for read/write/verify/restore failures. JS should not duplicate native failures.
• Android and iOS protocol/API surfaces must stay aligned through [Board] Add MCCONF editor #223. Add Legal Mode-specific parity tags only if this issue adds new durable native entry points.

Acceptance criteria

• Board Speed Limit writes real VESC MCCONF ERPM limit fields, not Refloat tiltback fields.
• Enabling Board Speed Limit derives target ERPM from current Legal Speed Limit and applies it to the controller through [Board] Add MCCONF editor #223's MCCONF capability.
• The implementation captures previous ERPM limit values only on disabled -> enabled transition.
• Changing Legal Speed Limit while Board Speed Limit remains enabled updates the active ERPM limit without overwriting the original restore baseline.
• Disabling Board Speed Limit restores the original captured ERPM limit values and clears the restore baseline only after successful restore.
• Apply and restore both verify by reading MCCONF back and checking the intended ERPM fields.
• UI never claims the real board limit is active when read/write/verify failed.
• [Legal Mode] Add UI and speed alert #221's sound alert remains the warning mechanism, with warning speed defaulting to limit - 5 km/h.
• Tests cover ERPM conversion, baseline capture, active-limit update without baseline overwrite, restore baseline clearing, readback verification failure, and blocked untrusted-link writes.
• No jurisdiction/GPS lookup work is added here; that belongs to [Legal Mode] Add UI and speed alert #221.

Blocked by

• [Legal Mode] Add UI and speed alert #221
• [Board] Add MCCONF editor #223

Related

• [Legal Mode] Add UI and speed alert #221
• [Board] Add MCCONF editor #223