Proximity unlock uses the core BLE companion and RSSI measured at the vehicle. Provide an authenticated BLE connection, calibration storage and a working lock actuator.
Enable the model capability
Enable vehicle.proximity.unlock (bit 11, MOTO_PROXIMITY_UNLOCK) in the model; it takes effect after signed CONFIG. The user must also complete calibration. Manual locking, MOTO_LOCK (bit 3), has separate authorization but operates the same lock. Use matching ABI 8 headers and archives.
Calibration in the APP
The vehicle home screen’s proximity-unlock action opens a radar guide. Each opening starts a new calibration:
- Stand about two metres from the vehicle and tap Start.
- Hold position while the radar shows sampling progress and relative signal strength.
- Once the vehicle saves the profile successfully, the APP shows completion and enables proximity unlock.
Calibration collects one stable signal at the approximate two-metre boundary, without a separate outside-range sample. The radar does not show precise metres. Cancellation, disconnection or failure preserves the last successful profile; an incomplete first calibration leaves the feature disabled. The APP retains its installation identifier to restore the corresponding vehicle record after reconnecting.
BLE RSSI estimates proximity. Bodies, phones, antennas and parking environments affect the trigger position, so it cannot guarantee an exact two-metre boundary.
Connect vehicle sampling and storage
Use the core headers moto/sdk.h and moto/proximity.h. Configure moto_config.proximity on the authenticated BLE companion instance. It is not a moto_terminal_config field; do not pass a moto_terminal * to core APIs.
| Interface | Requirement |
|---|---|
proximity.load |
Load by authenticated owner and APP installation identifier; return a zero profile and MOTO_OK if absent |
proximity.save |
Atomically persist moto_proximity_profile; return MOTO_OK only after durable storage, or an error on failure |
moto_proximity_sample(sdk, connection_id, rssi_dbm) |
Submit fresh RSSI from this BLE connection about every 500 ms, using its moto_connect connection ID |
moto_proximity_reset(sdk) |
Call after confirmed manual locking or a safety-interlock change to require departure before another unlock |
Serialize these core calls on the SDK owner thread, outside callbacks. Storage callback arguments are borrowed only until return; do not retain pointers or log owner credentials. The installation UUID scopes records and is not an authentication credential. After reconnecting, complete owner authentication and signed CONFIG before querying this installation’s record.
Measure RSSI at the vehicle receiver; do not copy thresholds measured by the phone. Submit 127 for unavailable readings to reset the decision, and never resubmit stale cached samples. Calibration requires stable readings for three seconds after filling the sampling window. Accepted calibration values range from −90 to −30 dBm. The near threshold is the calibrated value; the far threshold is 8 dB lower.
Three seconds below the far threshold arms the detector. Reaching the near threshold for 1.5 seconds triggers once. Enabling, reconnecting, calibrating, invalid readings or sample gaps over two seconds require departure again. The SDK does not automatically lock, repeatedly unlock while the phone remains nearby, or retry a failed actuator operation.
Execute the unlock and synchronize lock state
The BLE companion SDK emits a local MOTO_EVENT_VEHICLE_COMMAND with message=56, target=0 and value=0. The phone cannot send this trigger command.
Before operating the real actuator, check the deadline, vehicle speed and controller interlocks. When queuing work, retain the event session/request and the host-tracked BLE connection ID, then verify that connection is still valid before execution. Core events have no separate connection-generation field. Use the event’s original session and request with moto_complete_command on the same SDK instance that emitted it. Do not complete a BLE operation on the Wi-Fi instance; loss of Wi-Fi must not cancel an otherwise valid BLE operation.
Local requests time out after three seconds with MOTO_UNKNOWN. Sending a CAN frame does not establish physical success. After controller confirmation, report observed lock state in field 3. The home-screen lock icon follows that state for both manual and proximity unlock. See vehicle state reporting.
Connection and background operation
Vehicle-side sampling and triggering work only while the authenticated BLE link remains valid. Reconnect and authenticate after disconnection, then leave and approach again. Automatic reconnection after the user force-quits the APP is not guaranteed.
Troubleshooting
- Missing control: check model capability, signed CONFIG, BLE authentication and PROFILE key 33.
- Failed calibration: check fresh RSSI from the current connection, accepted range and storage callbacks.
- No unlock: leave before approaching; check vehicle interlocks, event origin and execution result.
- Stale lock icon: report field 3 after controller confirmation.
The APP and SDK handle calibration requests; the BSP does not construct wire messages. See docs/PROXIMITY_UNLOCK.md in the package for full fields.