Versions and migration

Check BUILD_INFO.json and SHA256SUMS before replacing dependencies. “SDK 1.0.0” alone does not establish that two ZIP packages can be mixed.

Four version fields

CPU, compiler ABI, IDF/FreeRTOS and Mbed TLS configuration must also match. A shared ABI number does not permit mixing core structures across arbitrary package revisions. Use headers, both archives and component configuration from one package. The _v8 symbols for config_init/create/next_event prevent some mismatches; they are not a runtime compatibility guarantee for every core API.

Integration changes

The current APP uses the r25 road-vector path. Image-map firmware from r24 or earlier needs commit_vector integration before receiving it. Do not update headers alone or send a phone RVS1 regional archive directly to the instrument. FreeRTOS ABI remains 8, but the Core moto_map_port layout has changed.

Power uses capability bit 12 and state field 12. Proximity uses capability bit 11; state field 11 remains range in metres. The map port predates this ABI 8 change and still uses core APIs; ABI 8 does not imply a managed map port.

Current connection baseline

Revision 16 requires the APP to read PROFILE key34 after authentication and declare its known uint32 capability bits in CAPS_GET key0. The SDK returns the intersection with currently available capabilities. Signed configuration and licenses are verified unchanged before unknown optional bits are ignored; client declarations cannot expand authorization. APP and SDK use this single flow. Missing required fields are protocol errors, with no old-message fallback. Future optional capabilities follow this negotiation without changing existing bit meanings.

Extending Managed or moving to Core

Managed (moto_freertos/terminal.h) wraps Core (moto/sdk.h) with one primary session, an SDK owner task, command queues and copied events. Core supports full-instrument integration with application-owned scheduling across channels. Core can also use moto_network for discovery, listeners, backpressure and connection cleanup; choosing Core does not require rebuilding those network policies.

Choose the extension scope

post copies up to 256 payload bytes and calls job(moto_sdk *, payload, size) outside callbacks. Nonzero sessions are checked at admission and execution; zero is only for local setup/cleanup. Never retain or destroy the supplied SDK or block the task. Pointed-to data is not deep-copied, and jobs are not automatically retried. This is not an instance-attachment, reconfiguration or shared-owner API; it is not a complete recipe for starting a Core BLE/mirror instance beside a Managed primary.

Work that can be reused

Migration steps

1. Retain the BSP, UI, vehicle and media drivers, and create a separate build target with one Core primary. Reuse the real License, random source, clock and network primitives; configure moto_tls, moto_config and moto_network. Do not start both complete projects against the same primary listener and drivers.
2. Establish one owner task for Core instances and the shared owner snapshot. moto_network_poll already drives its bound primary/mirror instances; do not poll them again separately. Route BLE input and polling to the same task.
3. Copy Core callback data into bounded application queues. moto_event pointers are borrowed until callback return; moto_terminal_event is an owned managed-queue value. Never cast between them. Use moto_event_get_notification for notification snapshots. UI/vehicle tasks execute once and preserve the source and session for completion.
4. Validate primary business, then add BLE, map ports or mirror instances individually. Update the shared owner only after durable commit. Keep separate TLS contexts and connection generations. Closing notification BLE must not tear down primary navigation; mirror cleanup follows its scoped grant and revocation rules.
5. Before switching, stop input producers, event consumers and asynchronous driver completions. Retry Managed stop until OK, then destroy. Start the Core build target with fresh sessions and no pending work from the old sessions.

Binding storage needs a separate decision: Managed currently uses a 72-byte opaque record and the P4 Core example uses 67 bytes. There is no public bidirectional converter. For development units, confirm both cloud unbinding and physical-device revocation before using a validated storage-initialization procedure and pairing on the target firmware. Preserving an installed owner’s binding requires an explicit, validated storage conversion plan; do not infer formats from their lengths or erase NVS to force migration. See persistence.

Validate primary reconnection, independent BLE notification/ANCS readiness, channel-isolated cleanup, stale completions, queue backpressure/retries, owner revocation and storage failures. For mirroring, also test unexpected primary loss and explicit stop. Reusable work depends on driver/scheduler coupling; there is no fixed rework percentage.

Migrating ABI 7 to ABI 8

1. Retain the old package, firmware, project configuration and controlled storage backups. Record binary/documentation revisions and validate on development hardware first.
2. Remove old SDK dependencies from the build search path. Import all new headers, libmoto_sdk.a, libmoto_freertos.a, components and configuration checks together, rather than replacing only .h files.
3. Initialize with moto_terminal_config_init. Size event, state and configuration buffers using the new types’ sizeof and public constants. Remove hard-coded old array lengths and explicit _v7 references.
4. For power, dispatch MOTO_POWER_SET explicitly. For proximity, configure the separate BLE core instance and calibration storage, completing work on its original instance. Leave unwired features disabled.
5. Copy core notifications with moto_event_get_notification inside the callback. Managed events already own their values. Retain origin, session and receipt time.
6. Clean old build caches and rebuild/link. ESP-IDF uses idf.py fullclean followed by idf.py build. Build cleanup does not erase device Flash.
7. Validate first pairing, upgraded reconnection with the owner preserved, complete vehicle state, stale-session cancellation and target features. Report incompatible versions/capabilities rather than bypassing package checks.

Match the public P4 project to the package required by docs/VALIDATION.md and import checks at the selected commit. This guide’s revision 26 baseline does not establish that the default branch has migrated. See reference application; vector-map, audio and mirror APIs require both matching integration code and a matching package.

Persistence and rollback

The managed record is currently 72 bytes, already used by the corresponding ABI 7 version. It is not a new ABI 8 storage layout. Reading legacy 35/67-byte records does not mean every old firmware can read current records, or that the P4 core adapter can switch directly to managed storage.

For rollback, restore matching dependencies and firmware, first checking the old version’s record parser, capability configuration and feature support. Disabling newly enabled features or restoring storage requires a validated product procedure. Preserve the current owner state; do not restore a revoked user’s access from an old backup. See persistence.