Skip to content
186 changes: 186 additions & 0 deletions docs/rgb10max2.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,186 @@
# the powkiddy rgb10 max 2

this is what it took to run andr36oid on the powkiddy rgb10 max 2, a 2021 rk3326
handheld that shares the odroid go super's board design but, unlike the og super,
ships with an internal wifi module. the port itself is small: a device tree, a
boot.ini line, a boot service. getting wifi to work was the interesting part and
needed something no device tree can express, explained further down.

status: every feature listed here was verified on hardware. wifi works with no
cables attached, on every cold boot.

## the console

- rockchip rk3326, 1 gb ram, no emmc (sd card only)
- 5 inch 854 x 480 ips, mipi dsi panel `elida,kd50t048a`, portrait panel used
landscape, 2 lanes
- buttons on the odroid go super map (amux adc), plus start/select on gpio2 and
l1/r1 on gpio3
- wifi + bluetooth: one realtek rtl8723bu combo module (`0bda:b720`),
usb, sitting behind a genesys `05e3:0608` hub on the dwc2 usb bus. 2.4 ghz
only: 802.11n, no 5 ghz, no wpa3 (see known limits)
- two usb-c ports: one marked power (charge only, no data lines), one marked
otg (data, wired to the same dwc2 bus as the internal hub)

## the profile

the flasher reads console profiles from `BOOT/andr36oid-profiles.txt`; nothing
in this repo needs a new console. add one line and the matching folder:

```text
Devices/RGB10MAX2|RGB10 Max 2|Powkiddy RGB10 Max 2|
```

`BOOT/Devices/RGB10MAX2/` holds the same file set every r36s-derived profile
uses, built for this console:

- `rk3326-r36s-android.dtb` - the device tree described below
- `logo.bmp` - the boot logo
- `rg351mp-uboot.dtb`, `rg351p-uboot.dtb`, `rg351v-uboot.dtb` and the matching
`*-kernel.dtb` files - the u-boot and kernel copies the bootloader picks from
by board revision; the og super family uses the same names

the console identifies as `hwrev=v10-go3`, so the bootloader boots the
`rk3326-odroidgo3` path. the top-level files on BOOT are replaced with the
profile's files as usual.

## boot.ini

two lines matter on this console:

```text
setenv android "... androidboot.sf_orientation=ORIENTATION_270"
setenv bootrootfs "... usbcore.autosuspend=-1"
```

the panel is portrait and mounted landscape, so surfaceflinger needs the
orientation hint. `usbcore.autosuspend=-1` keeps the internal hub's usb port
awake; with autosuspend left on, the hub can idle off and wifi drops for a
moment during boot.

## the device tree

`docs/rgb10max2/rk3326-rgb10max2-android.dts` is the full source. it includes
`rk3326-r36s-android.dtsi` from the kernel tree and changes only these things:

- panel to `elida,kd50t048a` with the init sequence and timing from the stock
go3 device tree, plus the 251 level backlight
- `invert-absrx` on the joypad and the amux channels made explicit
- leds: no vibrator, charge led on gpio0 pb5
- battery: design capacity 4000, charger values from the go3 tree
- the charger's dc detect (gpio0 pb3) stays exactly as in the base tree. it is
what lets the charger enable the charge path, and stock leaves it alone
- the dwc2 otg controller runs `dr_mode = "host"` with the phy port **disabled**
(see the wifi section for why). the otg connector still works as a plain
usb-c host port for devices; android's usb *device* modes need the phy port
enabled and are outside this configuration

build it exactly like the other andr36oid device trees:

```sh
cpp -nostdinc -I include -I arch/arm64/boot/dts/rockchip -undef -D__DTS__ \
-x assembler-with-cpp rk3326-rgb10max2-android.dts -o out.dts
dtc -@ -I dts -O dtb -o rk3326-r36s-android.dtb out.dts
```

the `-undef` matters: the kernel's `linux` builtin macro mangles `linux,code`.

## wifi power: the rk817 latch, and why the phy port stays disabled

the internal hub and the wifi dongle sit on the dwc2 bus, and their 5 v is the
otg port's vbus net, fed by the rk817 otg rail. on this board the rail behaves
as a pmic-side latch: kernel writes to the otg enable register (charger,
regulator, phy vbus supply) never reach it - the kernel register cache reads
back "on" (`reg_b4=47 otg5v=1`) while the hardware register reads `0x07` and no
power appears. a raw i2c write of `0xB4 = 0x47` from linux flips it, the hub
powers from the battery and the wifi module comes up. the latch survives warm
reboots but resets on a cold power-off, so the boot service writes it on every
cold boot.

the stock firmware ships the same topology: dwc2 runs phyless with the otg **phy
port disabled**. that one detail is load-bearing twice:

- dwc2: keeping `phys = <&u2phy_otg>` while the port is disabled makes the phy
lookup defer until the u2phy driver is up (utmi clock on) and then return
-ENODEV, so dwc2 probes phyless with the clock running. removing the `phys`
property outright instead makes dwc2 probe before that clock exists and its
core soft reset hangs with "GRSTCTL_CSFTRST timeout"
- charger: if the phy port is enabled it fires EXTCON_USB_VBUS_EN, the charger
sets `otg_in` and then **disables its own plug/plug-out interrupts**. a
charger plugged in afterwards is never detected and charging stops until
reboot. with the phy port disabled the charger never hears about otg, keeps
its plug detection, and charges normally

result, verified on hardware: charging and wifi run together. with a charger in
the power port its 5 v feeds the shared net, so the hub enumerates before the
latch is even needed; on battery the boot service arms the latch. a 30 s
watchdog re-arms the latch whenever the hub drops.

`docs/rgb10max2/service/` does this at boot, in this order:

1. preload `rtl8xxxu.ko` so the dongle binds the moment it enumerates
2. pin runtime pm on the usb controllers
3. if the hub is not enumerated: write `0xB4 = 0x47` with `rk817tool`. if that
does not take, unbind the charger, write again, rebind, and write once more if
rebinding killed it
4. after boot: disable wifi power save and set the ma regdomain with `wifitool`,
then open adb over tcp
5. keep a small root command loop alive (the flasher's servicing hook, optional
for a release build)

`docs/rgb10max2/tools/rk817tool.c` is a static aarch64 binary that reads and
writes rk817 registers over `/dev/i2c-0` (address 0x20).
`docs/rgb10max2/tools/wifitool.c` is a static aarch64 nl80211 helper (no libnl)
for power save and the regulatory domain, because the image ships no `iw`.

## the boot black screen, and the service fix

the kernel draws the boot logo, but when surfaceflinger/hwc take over the drm
master the crtc is never enabled for the android framebuffer: the panel stays
black while android keeps believing the screen is on (the display manager logs
no state change for the whole boot). a screencap shows the launcher fully
composed, so only the panel scanout is dead. the first vop modeset happens only
when a sleep/wake cycle forces displaypowercontroller to disable and re-enable
the display.

the service therefore runs that cycle automatically right after
`sys.boot_completed`: two `input keyevent KEYCODE_POWER` events 1.5 s apart.
verified on hardware: the wake fires (`WAKE_REASON_POWER_BUTTON`), the display
manager logs "built-in screen, on", and the launcher appears with no button
press. `fb0/blank` does not drive dpms on this kernel and the drm sysfs `dpms`
node is read-only, so the key-event cycle is the only working trigger from
userspace.

also set `debug.sf.nobootanimation=1` in `/vendor/build.prop` (the image ships
`0`; `/system` is erofs and not writable): the animation renders into the dead
panel anyway, and disabling it shortens boot by roughly 10 s
(enable_screen 52->48 s, boot-animation-done 63->51 s on measured boots).

## what works

- display, orientation, touch-less ui, all buttons and both sticks
- **screen comes up by itself after boot** (auto sleep/wake cycle; no button)
- wifi from battery on every cold boot (latch written by the boot service),
wpa2-psk networks including mixed wpa/wpa2 tkip ones
- bluetooth (the same combo module exposes hci0)
- **charging and wifi at the same time** - stock parity (verified live:
battery charging at +869 mA with wlan0 connected)
- the otg port as a plain usb-c host port; the power port charges
- battery percentage

## known limits

- 2.4 ghz only. no 5 ghz networks, by hardware
- wpa3-only and wpa2/wpa3 transition networks that require pmf do not connect:
the `rtl8xxxu` driver has no sae or management frame protection support. a
wpa2-only access point (or forcing a wpa2 psk config) works
- weak links: the module's antenna is small. the ap can drop the client with
"missing acks" below roughly -75 dbm; keeping wifi power save off helps

## evidence

the port was validated against the stock firmware's own kernel log from the same
unit (retrooz, kernel 4.4.189), which shows the same hub and dongle enumerating
on dwc2 in ~10 s, and against live adb sessions on android 11 where unplugging
the otg cable dropped the hub in under 3 s and plugging it back restored it. the
pmic behaviour above was measured with raw i2c reads on the running console.
171 changes: 171 additions & 0 deletions docs/rgb10max2/build-rgb10max2-image.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,171 @@
#!/bin/bash
# build-rgb10max2-image.sh — full reproducible builder for the Powkiddy
# RGB10 Max 2 andr36oid image. Takes ANY andr36oid base image (official
# release or a previous master) and applies EVERYTHING the port needs:
#
# BOOT (p1): RGB10MAX2 device profile (DTB, logo, u-boot/kernel dtbs),
# profiles.txt line, boot.ini orientation + autosuspend lines
# vendor (p8): diag.sh (current service), zz-diag.rc, rk817tool, wifitool,
# debug.sf.nobootanimation=1 in /vendor/build.prop
#
# Nothing else is touched: /data (Wi-Fi, apps, tailscale auth) is per-install
# and migrates via migrate-console-state.sh after first boot.
#
# Usage:
# build-rgb10max2-image.sh <base.img> [-o <output.img>]
# build-rgb10max2-image.sh --download [-o <output.img>] # fetch official release
#
# Idempotent: running it on an already-patched image just refreshes files.
set -euo pipefail

HERE="$(cd "$(dirname "$0")" && pwd)"
PROFILE_DIR="$(cd "$HERE/../device-work/boot-profile/RGB10MAX2" && pwd)"
SERVICE_DIR="$HERE/../device-work/diag-v11"
BIN_DIR="$HERE/../device-work/bin"
TOP_FILES="rk3326-r36s-android.dtb logo.bmp rg351mp-uboot.dtb rg351p-uboot.dtb rg351v-uboot.dtb rg351mp-kernel.dtb rg351p-kernel.dtb rg351v-kernel.dtb"
WORK="$(mktemp -d)"
LO=""

cleanup() {
umount "$WORK/boot" 2>/dev/null
umount "$WORK/vendor" 2>/dev/null
[ -n "${VLO:-}" ] && losetup -d "$VLO" 2>/dev/null
rm -rf "$WORK"
}
trap cleanup EXIT

die() { echo "build: $*" >&2; exit 1; }
need() { command -v "$1" >/dev/null || die "'$1' is required"; }

for f in $TOP_FILES; do [ -f "$PROFILE_DIR/$f" ] || die "profile file missing: $PROFILE_DIR/$f"
done
[ -f "$SERVICE_DIR/diag.sh" ] || die "diag.sh missing"
[ -f "$BIN_DIR/rk817tool" ] && [ -f "$BIN_DIR/wifitool" ] && [ -f "$BIN_DIR/zz-diag.rc" ] || \
die "compiled tools missing in device-work/bin/ (rk817tool, wifitool, zz-diag.rc)"

case "${1:-}" in
--download)
need curl
URL=$(curl -s https://api.github.com/repos/andr36oid/releases/releases/latest \
| grep -oE '"browser_download_url": *"[^"]*rk3326\.img\.xz"' | head -1 | cut -d'"' -f4)
[ -n "$URL" ] || die "no rk3326 release image found"
echo "Downloading $URL"
curl -L "$URL" -o "$WORK/base.img.xz"
BASE="$WORK/base.img.xz"
;;
*.img|*.img.xz) BASE="${1:?usage: $0 <base.img> [--download] [-o out.img]}"; [ -f "$BASE" ] || die "no such image: $BASE" ;;
*) die "usage: $0 <base.img> | --download [-o out.img]" ;;
esac
OUT="${3:-}"; [ "${2:-}" = "-o" ] && OUT="${3:-}"
OUT="${OUT:-${BASE%.*}-rgb10max2-master.img}"
OUT="${OUT%.img}.img"

# --- prepare a writable copy -------------------------------------------------
need xz; need losetup; need mount; need debugfs; need mkfs.vfat; need mdir; need mcopy
if [ "${BASE##*.}" = "xz" ]; then
echo "Decompressing base image…"
xz -dk -c "$BASE" > "$WORK/base.img"
else
cp --sparse=always "$BASE" "$WORK/base.img"
fi
IMG="$WORK/base.img"

# --- mount BOOT (p1) and vendor (p8) via offsets (no partition scan needed) ---
fdisk -l "$IMG" > "$WORK/fdisk.txt" || die "fdisk failed on the image"
START1=$(awk '/^'[[:space:]]*'?img1|img1/' "$WORK/fdisk.txt" | awk '{print $2}')
# robust parse: find lines with p1..p8 (sfdisk-style numbering by position)
get_start() { awk -v n="$1" '$1 ~ ("img" n "$") {print $2}' "$WORK/fdisk.txt" | head -1; }
get_size() { awk -v n="$1" '$1 ~ ("img" n "$") {print $4}' "$WORK/fdisk.txt" | head -1; }
S1=$(get_start 1); SZ8=$(get_size 8)
[ -n "$S1" ] || { grep -n "img1\b" "$WORK/fdisk.txt" | head -3; die "could not parse p1 start from fdisk output"; }
OFF1=$((S1 * 512))
mkdir -p "$WORK/boot" "$WORK/vendor"
mount -t vfat -o loop,offset=$OFF1 "$IMG" "$WORK/boot" || die "p1 vfat mount failed"
[ -f "$WORK/boot/boot.ini" ] || die "p1 has no boot.ini — not an andr36oid image?"
if [ -n "$SZ8" ]; then
OFF8=$(get_start 8); OFF8=$((OFF8 * 512)); SZ8B=$((SZ8 * 512))
LO8=$(losetup -f --show -o $OFF8 --sizelimit $SZ8B "$IMG")
e2fsck -fp "$LO8" >/dev/null 2>&1 || true # fresh images carry a dirty ext4 journal
mount -t ext4 "$LO8" "$WORK/vendor" 2>/dev/null || { losetup -d "$LO8"; die "p8 ext4 mount failed — partition layout differs"; }
VLO="$LO8"
else
die "could not parse p8 from fdisk output"
fi

# --- BOOT: rebuild via mtools (kernel vfat writes proved flaky on sparse backing) ---
mkdir -p "$WORK/boot-orig"
MIDX="$IMG@@$OFF1"
# 1. pull the entire official BOOT content out (mtools = no kernel involvement)
mcopy -s -i "$MIDX" ::/ "$WORK/boot-orig"/ || die "mtools read of official BOOT failed"
[ -f "$WORK/boot-orig/boot.ini" ] || die "official BOOT extraction incomplete"

# 2. apply our changes on the local copy
mkdir -p "$WORK/boot-orig/Backup-stock"
for f in $TOP_FILES; do
[ -f "$WORK/boot-orig/$f" ] && cp "$WORK/boot-orig/$f" "$WORK/boot-orig/Backup-stock/"
cp "$PROFILE_DIR/$f" "$WORK/boot-orig/$f"
done
mkdir -p "$WORK/boot-orig/Devices/RGB10MAX2"
rm -rf "$WORK/boot-orig/Devices/RGB10MAX2"; mkdir -p "$WORK/boot-orig/Devices/RGB10MAX2"
for f in $TOP_FILES; do cp "$PROFILE_DIR/$f" "$WORK/boot-orig/Devices/RGB10MAX2/$f"; done
cp "$WORK/boot-orig/boot.ini" "$WORK/boot-orig/Devices/RGB10MAX2/boot.ini"
grep -q "^Devices/RGB10MAX2|" "$WORK/boot-orig/andr36oid-profiles.txt" 2>/dev/null || \
printf 'Devices/RGB10MAX2|RGB10 Max 2|Powkiddy RGB10 Max 2|\n' >> "$WORK/boot-orig/andr36oid-profiles.txt"
grep -q "sf_orientation=ORIENTATION_270" "$WORK/boot-orig/boot.ini" || \
sed -i 's/setenv bootargs /setenv bootargs androidboot.sf_orientation=ORIENTATION_270 usbcore.autosuspend=-1 /' "$WORK/boot-orig/boot.ini"
grep -q "ORIENTATION_270" "$WORK/boot-orig/boot.ini" || die "boot.ini orientation edit failed"

# 3. fresh vfat, everything copied back in with mtools (proven sequence)
rm -f "$WORK/boot-vfat.img"
mkfs.vfat -n BOOT -C "$WORK/boot-vfat.img" 262144 # 256 MiB in 1KB blocks
for D in Devices Experimental Image Panels Backup-stock; do mmd -i "$WORK/boot-vfat.img" "::$D"; done
mcopy -s -i "$WORK/boot-vfat.img" "$WORK/boot-orig/Devices/"* ::/Devices/
for D in Experimental Panels Backup-stock; do mcopy -s -i "$WORK/boot-vfat.img" "$WORK/boot-orig/$D/"* "::/$D/"; done
if ls "$WORK/boot-orig/Image/"* >/dev/null 2>&1; then mcopy -s -i "$WORK/boot-vfat.img" "$WORK/boot-orig/Image/"* ::/Image/; fi
mcopy -i "$WORK/boot-vfat.img" "$WORK/boot-orig/"*.txt ::/
for f in $TOP_FILES boot.ini boot.ini-android logo.bmp logo_kernel.bmp make-report.txt; do
[ -f "$WORK/boot-orig/$f" ] && mcopy -i "$WORK/boot-vfat.img" "$WORK/boot-orig/$f" ::/
done
mdir -i "$WORK/boot-vfat.img" ::/ >/dev/null || die "fresh vfat verification failed"

# 4. splice the fresh vfat into the image at p1
dd if="$WORK/boot-vfat.img" of="$IMG" bs=512 seek=$S1 conv=notrunc status=none
grep -q "ORIENTATION_270" "$IMG" || die "boot.ini orientation did not reach the image"
grep -q "usbcore.autosuspend=-1" "$IMG" || die "boot.ini autosuspend did not reach the image"
grep -q "RGB10MAX2" "$IMG" || die "profile files did not reach the image"
mdir -i "$IMG@@$OFF1" ::/boot.ini >/dev/null 2>&1 || die "mtools post-verify failed"
echo "BOOT: rebuilt via mtools, verified."

# --- vendor: service + tools + build.prop ------------------------------------
install -m 750 "$SERVICE_DIR/diag.sh" "$WORK/vendor/etc/diag.sh"
install -m 644 "$BIN_DIR/zz-diag.rc" "$WORK/vendor/etc/init/zz-diag.rc"
install -m 755 "$BIN_DIR/rk817tool" "$WORK/vendor/etc/rk817tool"
install -m 755 "$BIN_DIR/wifitool" "$WORK/vendor/etc/wifitool"
grep -q "nobootanimation" "$WORK/vendor/build.prop" && \
sed -i 's/^debug.sf.nobootanimation=.*/debug.sf.nobootanimation=1/' "$WORK/vendor/build.prop" || \
echo "debug.sf.nobootanimation=1" >> "$WORK/vendor/build.prop"
grep -q "debug.sf.nobootanimation=1" "$WORK/vendor/build.prop" || die "build.prop knob failed"
echo "vendor: diag.sh + tools + build.prop installed."

sync -f "$WORK/boot" 2>/dev/null || sync
umount "$WORK/boot" || die "BOOT unmount failed (busy) — aborting instead of losing writes"
sync -f "$WORK/vendor" 2>/dev/null || sync
umount "$WORK/vendor" || die "vendor unmount failed (busy) — aborting instead of losing writes"
losetup -d "$VLO" 2>/dev/null || true

# --- verify the writes are IN THE IMAGE FILE (raw grep, no mount games) ------
grep -q "ORIENTATION_270" "$IMG" || die "boot.ini orientation did not reach the image"
grep -q "usbcore.autosuspend=-1" "$IMG" || die "boot.ini autosuspend did not reach the image"
grep -q "RGB10MAX2" "$IMG" || die "profile files did not reach the image"
grep -q "nobootanimation=1" "$IMG" || die "vendor build.prop did not reach the image"
echo "image-level verification passed."

# --- finalize -----------------------------------------------------------------
mv "$IMG" "$OUT"
sync
echo
echo "DONE: $OUT (apparent $(du -h --apparent-size "$OUT" | cut -f1))"
echo "md5: $(md5sum "$OUT" | cut -d' ' -f1)"
echo
echo "Flash to the new card, boot once, then migrate state:"
echo " migrate-console-state.sh --adb <console-ip> (tailscale auth, no re-login)"
Loading