Firmware must store the device license, owner pairing record and feature records separately. Do not erase storage as recovery for ordinary reboot, network loss or firmware upgrade.
Record sizes and boundaries
| Record | Current size/location | Handling |
|---|---|---|
| Device license | 512 bytes | Separate storage; preserve on ordinary unbind and OTA |
Managed read_pairing/write_pairing |
Currently 72 bytes, MOTO_TERMINAL_STORAGE_SIZE |
Opaque SDK record; allocate to the current header’s limit and preserve bytes |
| P4 core example pairing adapter | 67 bytes, NVS license_auth |
Example implementation of the core port; not the managed format |
| Proximity calibration and ad receipts | Defined by their respective ports | Separate scopes and retention rules, outside the pairing record |
The managed interface reads legacy 35/67-byte records and writes the 72-byte format on the next successful save. ESP-IDF defaults to namespace moto_sdk, key owner. Custom ports preserve the actual length without truncating or editing fields. Copying raw NVS values does not migrate between the P4 core adapter and managed interface.
The public P4 NVS partition is 0x6000 (24 KiB), shared by license, wireless and other records. This is a reference allocation, not a 72-byte Flash requirement or a universal minimum. Include storage-engine pages, metadata, updates and garbage-collection space. Size custom partitions for the storage engine and enabled features.
Callbacks and power-loss consistency
With no record, read_pairing succeeds with length 0. Corruption, read failure or insufficient capacity returns an error. write_pairing returns 0 only after the complete durable commit. A Flash write without a completed commit is not success.
Initialize storage before creating the SDK. Report a read fault and stop pairing/business rather than silently restoring an empty owner. Use atomic platform key-value commits, or a dual-copy design with versioning, integrity checks and commit markers. CRC detects corruption; it does not enforce access control.
Serialize primary Wi-Fi and BLE companion instances on one owner thread, sharing the durable owner snapshot. Update that snapshot only after a successful commit. Storage callbacks must not reenter the SDK or wait for the application event loop to finish the commit.
Write triggers and endurance
Pairing writes follow authentication state changes, not telemetry or RSSI sampling frequency:
- Before checking a PIN, persist the attempt-budget deduction. On success, persist the owner and reset the failure count.
- When the terminal completes trusted local revocation, persist owner removal and the associated release state. An APP cloud-unbind response alone cannot write to an offline terminal.
- Commit cooldown/authentication changes when the SDK calls the port. Reconnection and invalid input may affect counts; do not assume one write per day.
Do not defer these security-state commits or acknowledge success before background persistence. Use wear-levelled storage and measure actual commits/erases during normal pairing, repeated invalid PINs, reboot and unbind. Base endurance estimates on chip erase ratings, partition pages and measured erase amplification. An API write is not necessarily a sector erase.
Recovery and reset
Users can remove their vehicles in the APP. Cloud unbinding revokes cloud relationships and credentials, but does not prove that an offline terminal cleared its local owner. Removing only the phone entry, cloud binding or one NVS key does not establish complete revocation of physical-device access. When the previous owner cannot participate, follow service recovery for physical-device and cloud steps.
Target firmware needs a controlled local owner-reset path: stop business and invalidate old sessions, durably clear owner state and relevant authorization caches, then recreate instances or reboot and verify rejection of the old phone. P4’s factory_license_clear_owner() only clears persistence; it does not clear every running instance. The reference provisioning tool currently has no universal service-reset command. If the product lacks this path, do not confirm that local authorization was cleared in the console.
Preserve the license and durable ad receipts that must survive unbinding. Before upgrading, retain recoverable old firmware and controlled storage backups. Validate rollback against the actual record format accepted by the old version. Do not erase NVS to resolve an ABI or format mismatch. Test power loss during save, corrupt records, legacy reads, shared-instance synchronization, old-owner rejection after reboot and new-owner pairing.