[ambd] Add Realtek AmebaD family (RTL8720DN / BW16)

[Bl00d-B0b]

Adds the realtek-ambd family (UF2 id 0x3379CFE2, reserved in families.json) with the BW16 board. Closes the RTL8720DN part of #1.

Approach

• KM4 (Cortex-M33) application core only; the KM0 low-power image and both bootloaders ship prebuilt in the framework package and are never rebuilt.
• Framework: framework-realtek-ambd — a GCC-only AmebaD SDK package (based on the pruned OpenRTL8720D tree used by OpenBeken). Currently pinned to Bl00d-B0b/framework-realtek-ambd; transfer to libretiny-eu before merge.
• The WiFi glue reuses the shared realtek-amb core; AmebaD differences are gated with LT_RTL8720D.
• BSSID-hinted connects (fast-connect) keep the partial-scan channel hint but associate with plain wifi_connect(): on this SDK wifi_connect_bssid() associates at L2 with a dead data path — the netif never passes traffic (bench: every saved-fast-connect boot came up unreachable, every plain connect worked). AmebaZ keeps its working BSSID path.
• OTA: AmebaD selects the boot slot by the 81958711 image signature (OTA2 preferred when valid), not a system-data flag. cores/realtek-ambd/base/api/lt_ota.c implements the switch with signature-verify-before-invalidate ordering; the active slot's signature is invalidated with a zero-write (FLASH_TxData12BXIP), never FLASH_EreaseDwordsXIP — the sector backup/erase/rewrite that function performs on the sector holding the active KM0 header hard-faults at runtime (bench-reproduced).

Flash layout (4 MB)

partition	range	notes
boot	0x000000+0x4000	KM4 bootloader, SDK backup sector (0x2000), SDK system-data slot (0x3000)
boot_km0	0x004000+0x1000	KM0 bootloader
system	0x005000+0x1000	device-written system records (observed on hardware)
ota1	0x006000+0x1FA000
ftl	0x200000+0x6000	vendor region: factory littlefs + Realtek FTL (BT pairing storage) — reserved, never written
ota2	0x206000+0x1E2000
kvs	0x3E8000+0x8000	FlashDB
userdata	0x3F0000+0x10000

Hardware verification (BW16 KIT, RTL8720DX die)

• Boot, WiFi STA (including recovery from assoc-reject status 30), full ESPHome device: API + OTA + sensors, multi-hour uptime — on ESPHome dev and on stock ESPHome 2026.8.0 stable, including its saved-fast-connect reboot path (12-minute zero-loss watches after OTA reboots)
• OTA both directions across 20+ firmware revisions: OTA1→OTA2 and OTA2→OTA1, upload → signature switch → reboot → correct slot confirmed over serial and API
• Crash-safe switch ordering exercised: a reset between target-signature write and old-signature invalidation leaves the old image bootable
• FlashDB preferences init and persistence on the kvs partition
• Digital outputs: every header GPIO verified by wiring it to the (working) ADC and toggling from Home Assistant - including PA27/PB3, which need Pinmux_Swdoff() before GPIO writes reach the pad (SWD claims them by default)
• PWM: duty cycle measured via ADC averaging matches the gamma-corrected setpoint within 1 %
• ADC: PB1/PB2/PB3 (the SDK's CH4-CH6) through the efuse-calibrated ADC_GetVoltage() - a 3.3 V reference reads 3.26 V; the AmebaZ-named AD_1..AD_3 channels land on pins not bonded out on BW16, and PA27 has no ADC (the TypeC pinout tables claim otherwise)

Known limitations

• BLE is not ported yet (SDK BLE stack present in the framework package; OpenBeken's hal_bt_proxy_rtl8720d.c is the reference)
• SERIAL2 (PB1/PB2, the BW16 KIT's USB-C bridge) does not output yet: the UART_DEV_TABLE index mapping is fixed (SERIAL0/PA7-PA8 is the LOGUART at index 2, SERIAL2 is the luart at index 3 - indexing by port number sent SERIAL2 writes to the LOGUART registers), but the luart is a KM0-domain peripheral and still needs the LP-side clock/function enable and clock-source select from KM4 (it idles on the low-power oscillator); TX stays low after init (verified by ADC probe)
• Reboot reason decodes BOOT_Reason() - the ROM's latched backup of the BKUP_REG0 reason bits, taken by the boot chain before it clears the live register (bits 16-23, "software backup from BITn" in rtl8721dlp_sysreg.h). Distinguishes software / watchdog / brown-out / deep-sleep wake / power-on; hardware-verified: a software restart reports SW Reboot. Note for future work: the live BKUP registers are shared state with the ROM chain and the running KM0 - app-time access destabilizes WiFi (bench-reproduced three ways); BOOT_Reason() is the sanctioned read
• TODO(bench) markers: efuse chip-id bytes for RTL8720DN/DM (test unit reports RTL8720DX) and the efuse MAC offset — need an efuse dump to confirm
• Driver emits WIFI_EVENT_BEACON_AFTER_DHCP at ~10 Hz while connected; handled silently, follow-up planned with realtek-amb: fix double free and truncated copy of Arduino WiFi event data #401

Dependencies

• Includes the WiFiEvents.cpp fixes from realtek-amb: fix double free and truncated copy of Arduino WiFi event data #401 (file content identical); rebasing after realtek-amb: fix double free and truncated copy of Arduino WiFi event data #401 merges drops it from this diff.

Open questions (carried over from #402)

1. Framework package. The SDK currently comes from a personal fork (framework-realtek-ambd). Would you host it under libretiny-eu, as with the other Realtek families?
2. KM0 image. The KM4 half is compiled, but the KM0 half is a prebuilt blob, currently extracted from a device dump — not shippable. Is building it from the SDK's project_lp the expected route, or would a prebuilt ship in the framework package?
3. ltchiptool flashing. [ambd] Add AmebaD (RTL8720D) SoC support ltchiptool#98 implements the ROM protocol (draft until the native write path has a bench pass); flashing today works with external tools. Is ltchiptool support a prerequisite for merging the family, or can it land after?

[Bl00d-B0b]

@kuba2k2 ready for review — tested on an Ai-Thinker BW16 (RTL8720DX die): 18 firmware revisions flashed during bring-up, OTA verified in both slot directions (upload → signature switch → reboot → running slot confirmed over serial and the ESPHome native API), FlashDB preferences on the kvs partition, WiFi STA including assoc-reject recovery. CI is green. libretiny-eu/ltchiptool#98 carries the matching flasher support.

[Bl00d-B0b]

Bench round on the BW16 KIT closed two more hardware gaps, both amended into the single commit (ee94b21):

• ADC now works: the shared wiring_analog.c silently returned 0 on AmebaD — the AmebaZ-named channels land on pins not bonded out on BW16, and the variant macros never matched. New LT_RTL8720D arm maps PB1/PB2/PB3 to the SDK's CH4-CH6 with the efuse-calibrated ADC_GetVoltage(). A 3.3 V reference reads 3.26-3.32 V on every channel.
• PA27/PB3 as GPIO need Pinmux_Swdoff(): SWD claims them by default and GPIO writes never reach the pad (bench: flat 0 V). wiring_digital.c releases SWD when either pin is configured.

Verification methodology worth noting: each output pin was jumpered to the (already-proven) PB1 ADC and driven from Home Assistant — every header GPIO shows a clean 3.3/0 V swing, and PWM duty measured by ADC averaging matches the gamma-corrected setpoint within 1 %. Full matrix in the PR body.

[Bl00d-B0b]

One more bench finding folded into the commit (85c50c6): the SerialClass indexed UART_DEV_TABLE by the variant port number, but the AmebaD table order is UART0 / UART1-BT / LOGUART / luart — so SERIAL0 (PA7/PA8) must map to index 2 and SERIAL2 (PB1/PB2) to index 3. With the old indexing, SERIAL2 writes landed in the LOGUART registers and PB1 never emitted a byte.

The mapping alone is not enough for a working SERIAL2, and the body now documents why: the luart is a KM0-domain peripheral (hal_platform.h calls it the 'KM0 luart'); from KM4 it still needs the LP-domain clock/function enables and a clock-source switch off the low-power oscillator — the reason stock AT firmware serves that UART from the KM0 image. TX measurably stays low after init (probed by jumpering PB1 to the now-working PB3 ADC). Scoped as a known limitation rather than blocking the family.