SDK v1 App Compatibility

DC32 SDK v1: independent firmware and app releases

DC32 firmware and native .DC32 apps now match by a stable SDK ABI, not by build time or a whole-firmware hash. An app built for SDK ABI 1 runs on any firmware release that supports SDK ABI 1.

For badge users

1. Flash an SDK-v1 firmware release to the badge.
2. Extract the release's SD-apps.zip to the root of the microSD card, or copy a compatible .DC32 file directly into /APPS.
3. Eject/unmount the card before leaving USB Storage mode.

You can upgrade firmware without replacing every SDK-v1 app. You can also add a newly released SDK-v1 app without reflashing firmware.

Apps from the previous ABI-8 format must be rebuilt for SDK v1; they embed old firmware addresses and cannot be made safe by matching timestamps.

Installing an app by itself

Copy the app's .DC32 artifact (and any companion data it documents) into the SD card's /APPS directory. The firmware reads the app header, validates its integrity and SDK ABI, and launches it without a compiled-in catalog entry.

Apps appear in the menu from their embedded category:

Category	Menu location
games	Games → Apps
ports	Games → Ports
demos	Media → Demos
media	Media
infrared	Tools → Infrared
usb	Tools → USB

The launcher sorts discovered apps by display name and accepts up to 32 dynamic apps. Unknown categories, malformed files, duplicate names, failed CRCs, and unsupported SDK ABIs are ignored with a diagnostic. A valid app can also be opened from the file browser.

Compatibility and troubleshooting

• SDK ABI 1 matches: install or run the app normally.
• Unsupported SDK ABI: install firmware that supports the app's ABI, or obtain a build for the firmware's ABI.
• App not listed: confirm the file is a valid SDK-v1 .DC32 app in /APPS, uses a supported category, and is not a duplicate or beyond the discovery limit.
• Integrity error: copy the app again from a trusted release artifact.

The app payload build ID and CRC are diagnostics/integrity data only. They never pair an app to a specific firmware build.

For app developers

Build against the versioned DC32-App-SDK-v1.zip package. It contains public headers, the SDK CMake integration, linker scripts, the app packer, and build instructions.

Use the SDK's CMake helper rather than importing firmware symbols or firmware ELF addresses:

include(path/to/DC32App.cmake)
dc32_add_app(my_app My_App 0x80000001 games main.c)

The SDK links apps through the frozen DcAppHostApi service interface and fixed SDK veneers for graphics, input, timing, audio, storage, saves, settings, LEDs, workspace, and badge hardware services. An app must have no unresolved firmware imports; the build fails otherwise.

Ordinary firmware refactors and changes outside the public SDK keep ABI 1. The SDK ABI changes only for an intentional incompatible public-interface, memory-layout, or loader-model change; that is when apps must be rebuilt.

Release checklist

• Firmware releases state their supported SDK ABI and build ID for troubleshooting.
• App artifacts and manifests state sdk_abi: 1.
• Package the firmware, SDK archive, and SD-app bundle independently.
• Treat native .DC32 apps as trusted code: SDK compatibility is not a sandbox or signing model.