Start with the device, not a pile of flags

AERA keeps Android recovery plumbing underneath its native interface. A working TWRP or OrangeFox tree can be a starting point, but its old UI flags are not a specification for AERA. Check every inherited option against an actual consumer.

Use infiniti (OnePlus 15) and lighthouse (OPPO Find X9 Ultra) as the primary implementation examples. Their init sequencing, modules, graphics and service packaging are useful references, not interchangeable vendor files. Other public trees may still be experimental.

Keep hardware adaptation in the device tree: fstab, init RCs, module lists, firmware, vendor libraries and HAL services. Recovery source changes should solve a shared problem, not silently hard-code one device.

• Record the installed firmware, kernel version, boot header, partition layout and encryption scheme.
• Use vendor blobs and kernel modules from compatible firmware; preserve their licenses and redistribution restrictions.
• Keep a known-good boot/restore path and back up important data. Do not test partition changes on the only copy of your data.

Build configuration and a clean environment

Use BoardConfig.mk for hardware and early build/Soong settings. Product Make files such as device.mk or aera_<device>.mk also carry product configuration and supported AERA Make switches; the current reference trees place several AERA options there. Packaging options consumed by the vendor shell script need guarded exports in vendorsetup.sh. Set AERA_BUILD_DEVICE in the calling shell before sourcing envsetup, not inside that guard. The public namespace is AERA_; inherited backend symbols can still appear internally.

Values are not interchangeable. Some checks require true, some require 1, and some treat any non-empty value as enabled. For those last checks, false and 0 still enable the option. Follow each reference entry.

Use a fresh shell for each device. Set AERA_BUILD_DEVICE before sourcing envsetup so another tree cannot leak exports into your build. The current example products retain the twrp_ product prefix; this is not the UI branding.

cd /path/to/AERA_16.0
export AERA_BUILD_DEVICE=infiniti
source build/envsetup.sh
lunch twrp_infiniti-bp2a-eng
m -j16 recoveryimage

• Replace the target with twrp_lighthouse-bp2a-eng for the lighthouse example. Follow AndroidProducts.mk and the selected manifest branch for other devices.
• Choose parallel jobs for the actual host. No universal -j value improves every machine.
• Outputs are under out/target/product/<device>. Inspect the artifact produced for that device, not a ZIP left by an earlier build.

Boot image, partitions and image size

Match the real architecture: standalone recovery, recovery-as-boot or vendor_boot recovery; boot header version; embedded kernel/DTB requirements; A/B and Virtual A/B; and dynamic partitions. These choices must agree with the bootloader and installed ROM.

BOARD_RECOVERYIMAGE_PARTITION_SIZE is a physical budget, not a request to enlarge the device partition. AVB/footer overhead means the usable image budget is smaller than the raw partition size. Do not increase the configured size to hide an oversized image.

On devices requiring an embedded kernel, a tested compressed kernel can save space. Removing the kernel is not a universal optimization. Kernel decompression, DTB and header compatibility must be verified by an actual boot.

• Use a recovery fstab with correct block paths, slot suffixes, logical partition flags, userdata filesystem and encryption metadata.
• Inspect the built ramdisk for stale duplicate files after copy-rule changes; incremental output is not proof that obsolete files disappeared.
• Measure the finished image and packaged contents. Keep enough headroom for realistic vendor-driver growth.
• Validate fastbootd, slot handling and reboot paths without destructive test flashing. Never delete snapshot/COW data during an active merge.

Decryption and service ordering

AERA_INCLUDE_CRYPTO=true builds the decryption integration. Modern FBE and metadata decryption still need a correct fstab and compatible vendor KeyMint/Keymaster, gatekeeper and dependency libraries. A flag alone cannot decrypt userdata.

Load the actual installed ROM OS/security patch properties before starting services that consume them. Starting KeyMint with placeholder values can cause invalid keyblob upgrades. Follow the reference trees and their prepdecrypt/crypto.ready sequencing.

Kernel modules needed by crypto must be available at the correct stage. Some WLAN modules must remain post-decrypt on particular devices. Do not move them earlier merely to shorten connection time.

• Test a locked PIN/pattern device and a device with no passcode; both must reach the appropriate initialization path.
• Test skipping unlock, unlock failure, successful unlock and secondary Android users.
• Match fscrypt backup policy support to the actual filesystem policy.
• Do not write vendor keys, persist contents or encryption metadata as a speculative fix.

Graphics acceleration, panel and touch

AERA renders through its native graphics path. Package a compatible vendor EGL/GLES, allocator/gralloc and dependency stack for the running kernel. AERA has no magic GPU flag that substitutes for those drivers.

Verify the actual renderer in the recovery log. The native GPU path logs a zero-copy native-buffer GPU ready message with vendor/renderer information. A visible UI alone does not prove hardware acceleration or efficient scanout.

Use AERA_UI_ADAPTIVE_RESOLUTION and the status-bar insets for display geometry. AERA_DRM_FIXED_REFRESH_RATE selects a matching panel mode when available; it does not independently set application FPS.

• Check pixel format, orientation, framebuffer/panel dimensions, brightness node and hardware brightness range.
• Keep clock, battery and indicators away from rounded corners/cutouts; test 12-hour time and recording indicators.
• Verify touch coordinates, edge gestures, long presses, held keys and UI sizes. Use the compatible touch module/firmware, not a guessed newer driver.
• Test graphics and touch after a cold boot as well as after restarting the UI.

Wi-Fi: driver, firmware, MAC and supplicant

AERA_ENABLE_WLAN=1 enables the recovery WLAN integration. The device still needs its matching WLAN module and dependencies, firmware/configuration files, correct interface, init triggers and wpa_supplicant service. Android services are not automatically present in recovery.

On devices with decryption-sensitive WLAN modules, load them through the post-decrypt path and handle the no-passcode/already-unlocked path too. The infiniti helper supplies its MAC response without waiting for an unavailable modem service; this is device-specific, not a universal driver recipe.

Confirm that the MAC remains stable across recovery boots. Repeated random addresses can exhaust DHCP leases. Let DHCP allocate/renew addresses; a previous IP address is not proof that it remains valid.

• Test a saved-network auto-connect after reboot, manual connection, Wi-Fi off/on/off/on, and disconnect/reconnect.
• Check firmware lookup paths, loaded module state, supplicant control socket readiness, association and DHCP separately.
• Verify Unicode SSIDs and passwords containing symbols; keep logs free of passwords when sharing them.
• Boot Android after testing recovery: Wi-Fi must still work, with no incompatible configuration left behind.

Mobile data: internet through the SIM

Mobile data is an optional device bring-up, not a service supplied by Android while recovery is running. Set export AERA_ENABLE_MOBILE_DATA=1 inside the selected-device guard in vendorsetup.sh to expose the Network page, mobile-data controls and cellular indicators. Leaving the flag unset or using 0 keeps the Wi-Fi-only interface.

The tree must also package a compatible aera-cellular-provider and its dependencies. A flag is not a modem driver. Use infiniti and instantnoodlep as implementation examples, not interchangeable recipes: their modem transports, firmware services and startup sequences differ.

The shared interface covers SIM selection, APN settings, optional per-SIM PIN saving, automatic connection, signal strength and network type. Wi-Fi is preferred when available. Calls and SMS are not implemented; 4G/5G availability depends on the device, firmware, SIM, carrier and coverage.

• Match modem firmware, transport interfaces and OEM helper dependencies to the running kernel and installed ROM.
• Do not write physical EFS/NV, calibration or identity partitions as part of a bring-up. The reference implementations keep helper writes in volatile RAM and read required device metadata without modifying it.
• Verify real internet access and DNS, SIM changes, PIN prompts and Wi-Fi/mobile fallback; a registration label alone does not prove connectivity.
• Test disconnect/reconnect, orderly shutdown before storage operations, and normal Android connectivity after recovery use.

Audio is optional; broken dependencies are not

Audio bring-up requires the compatible vendor audio HAL, mixer paths, policy/configuration and firmware/amplifier dependencies. Copying a speaker configuration from another device can be unsafe.

AERA provides a no-audio compatibility path for supported runtime integrations. A device without working sound should not become unable to browse just because the audio stack is missing. That does not guarantee that every third-party plugin tolerates every missing hardware feature.

Working GPU rendering and hardware video decoding are different things. A smooth UI does not prove that a browser video is hardware-decoded.

• If audio is included, test playback, pause/resume, channel/rate handling and video synchronization.
• Check Android audio after booting out of recovery.
• Treat sound as an optional bring-up milestone; decryption, storage, flashing and input come first.

USB, fastbootd and PC Connection

Device init must configure the correct USB controller and gadget endpoints for recovery ADB, MTP, sideload and fastbootd. AERA_EXCLUDE_DEFAULT_USB_INIT is appropriate only when the tree supplies the required replacement.

PC Connection uses the recovery service and can be reached through Wi-Fi or an ADB port forward over USB. Its pairing, certificate, transfer and operation handling are recovery functionality, not a separate desktop application.

Test fastbootd independently of bootloader fastboot. A successful command response is not enough: verify actual slot/partition state where safe. Do not assume all devices expose the same flash targets.

• Verify ADB before and after decryption; a brief reconnect can be expected when device init changes USB configuration.
• Use a harmless sideload test package before installing real firmware.
• Test MTP when included, USB reconnection and authorized PC Connection through both supported transports.

Settings before unlock and install protection

Native full preferences are stored at /data/media/0/AERA/preferences.conf. AERA_SETTINGS_ROOT_DIRECTORY controls inherited settings-root handling and the root used for the early caches; it does not relocate every native settings file.

With AERA_ALLOW_EARLY_SETTINGS_LOAD=1, the UI cache is <root>/AERA/early-ui.conf. The native fallback root is /data/media/0 if no explicit root is compiled. That fallback normally cannot provide settings before encrypted userdata is unlocked. Choose an actually readable location when pre-unlock settings are needed, and verify it before entering a passcode.

early-ui.conf contains selected appearance, language, clock, install-protection and saved Developer Settings overrides. It does not contain WLAN passwords. When WLAN support is enabled, a separate <root>/AERA/early-wifi.json cache stores auto-connect settings and encrypted saved-network credentials. Early Wi-Fi still requires working drivers, firmware and services at that boot stage; these flags do not move modules out of post-decrypt loading.

Full preferences and the primary WLAN configuration become authoritative when available and refresh their early caches. Hold Volume Down during startup to skip saved Developer Settings tuning. Missing or unreadable early storage uses defaults without blocking recovery. PC Connection still starts only after unlocking, including when auto-enable is selected.

Keep AERA installed is a normal recovery preference. AERA_ENABLE_ABL_PRESERVATION additionally exposes the device-supported keep-current-ABL setting. Do not enable it on an unverified device just because it exists in a reference tree.

• Test settings persistence, unlock-screen language/theme and unavailable userdata.
• Review ZIP installer paths and experimental payload selection separately; explicit manual partition flashing remains a distinct operation.
• Do not change boot-chain partitions as a documentation test.

Packaging, updates and release checks

Build status (Official/Unofficial) and build type are metadata, not OTA channel selection. Stable and nightly catalogs are selected at runtime. The audited update code uses project catalog URLs; there is no documented per-device catalog-URL flag in this snapshot.

AERA ZIP publishing must use the built artifact for the correct device, with its real build timestamp, size and SHA-256. Version text can remain unchanged while build time identifies a newer build. Calculate the digest of the finished ZIP; do not reuse a value from a previous build.

AERA_ENABLE_ROOT_MANAGER=1 enables the Root Manager page, PC Connection Root tools, ksud and modern offline assets for all three providers. A value of 0, or leaving it unset, disables them. This replaces the three old per-provider flags and their installer ZIPs. Use matching recovery and vendor/recovery sources.

• Test a fresh boot, no-passcode boot and successful decryption on the firmware you intend to support.
• Check storage mounting, format-data behavior on a sacrificial setup, backup/restore, sideload and ordinary ZIP installation.
• Check installed plugins, update detection, root target inspection and PC Connection without destructive operations.
• Publish limitations honestly; a repository being public does not make its device officially supported.

Collect evidence before changing the tree

Use recovery.log for recovery operations and renderer/init diagnostics; use logcat for vendor services and Android subsystem messages. Kernel messages and read-only sysfs/properties help separate firmware, module, USB and hardware failures.

Read first. Do not format, flash, remove snapshots, change persistent calibration or replace firmware while investigating a generic boot or Wi-Fi failure. Reproduce one change at a time and keep the original evidence.

adb devices
adb pull /tmp/recovery.log recovery.log
adb logcat -d -b all > logcat.txt
adb shell dmesg > dmesg.txt
adb shell getprop > properties.txt

• Record device, firmware, AERA build, whether userdata is unlocked and exact reproduction steps.
• Check shared logs for credentials, serial numbers and other personal information before posting them.
• Missing log output can mean logd/logcat was not packaged. Inspect AERA_INCLUDE_LOGCAT and TARGET_USES_LOGD rather than inventing an unrelated fix.