Persistent root: Magisk + the S1 Kiosk root helper
On this page
Status (2026-11-09): working on the reference panel.
bootis Magisk v31.1 plus ouroverlay.d/s1kiosk_radio.rc.- It was flashed from the FEL U-Boot with
fastboot flash boot. - After a cold reboot with no manual steps:
- Magisk is live;
- the root helper (
init.svc.s1kiosk_radio) runs and reportsok off; - Aqara's radio and cloud services stay stopped;
- the kiosk and Home Assistant (ESPHome) are unaffected.
Why Magisk, and why this shape
- What the stock image allows:
buildvariant=usermeans noadb root.- Aqara's
/system/xbin/su(-rwsr-x--- root shell) only works from the UART console; under adbd it fails withsetgid failed, because adbd drops those capabilities. - The boot ramdisk is first-stage only (two-stage init), so a plain
.rcthere is never read by the real init. - Changing
vendor/systemwould mean rebuildingsuper.
- What Magisk changes: only
boot. Itsoverlay.d/*.rcfiles are injected into the second-stage init, which is exactly what the helper's init service needs. - What we deliberately don't do:
- grant
suto the app or to the adb shell. The app only sets properties (persist.s1kiosk.radio_mode,ctl.restart s1kiosk_radio), and the init service does the root work; - ship Magisk. It is GPLv3, so
frames/aqara-s1-plus/tools/root/patch-boot-magisk.shdownloads the official release and checks the SHA-256 GitHub publishes for it.
- grant
- AVB is not a problem on this firmware:
- the panel already runs a
vbmetawith flags = 3 (hashtree and verification disabled); - it boots normally while reporting
vbmeta.device_state=locked; - so stock U-Boot does not enforce AVB, and a modified
bootboots.
- the panel already runs a
Steps (no UART, no adb)
- Enter FEL and boot our U-Boot:
NO_BL31=1 frames/aqara-s1-plus/tools/fel/fel-boot.sh. It starts fastboot on its own. - Back up over USB:
frames/aqara-s1-plus/tools/install/fb-read-partition.sh boot stock-boot.img, and the same forvbmetaand the other small partitions.- This uses U-Boot
oem runplus our fastbootupload(patch 0002). - It reads 32 MiB in about 1.6 s.
- On the reference panel the read-back was byte-identical to a known image.
- This uses U-Boot
- Patch on the host:
frames/aqara-s1-plus/tools/root/patch-boot-magisk.sh stock-boot.img s1-boot.img.- Runs in Docker (arm64 Linux): Magisk's own
boot_patch.shwith the arm64magiskboot, and the panel's armeabi-v7amagiskinit/magisk/init-ldas payload. - Flags:
KEEPVERITY=true KEEPFORCEENCRYPT=true PREINITDEVICE=cache. That is exactly what Magisk computes on the panel, and the config matches an on-device patch. - Bundles the helper:
overlay.d/s1kiosk_radio.rc, pluss1kiosk_radio.sh,otbr-agentandot-ctlinoverlay.d/sbin. At runtime those are${MAGISKTMP}=/sbin.
- Runs in Docker (arm64 Linux): Magisk's own
- Flash and verify:
fastboot flash boot s1-boot.img.- Read
bootback with step 2's tool and compare hashes. fastboot reboot.
On first boot the helper creates /data/s1kiosk/radio itself (root 0700), so nothing else needs
installing. Verified on the reference panel on 2026-11-09, after deleting /data/s1kiosk to
simulate a fresh panel:
- the helper runs from
/sbinand reportsok off; - switching
select.s1_panel_radio_modein HA to Thread border router started the bundledotbr-agentonwpan0, andot-ctlanswers; - switching back to Off stopped it.
Since helper v4, binaries and a newer helper come from a signed radio bundle installed by the app
(below); copies left in /data/s1kiosk/radio are only used with a root-made dev-override marker.
Undo: fastboot flash boot stock-boot.img through the same FEL path.
Root shell for maintenance:
- No
sugrants exist by default. - For a debugging session, a time-limited Magisk policy for the adb shell (uid 2000) can be added
with an
untiltimestamp, so it expires by itself:magisk --sqlite "REPLACE INTO policies (uid,policy,until,logging,notification) VALUES(2000,2,<epoch>,1,0)". - Revoke it with
DELETE FROM policies WHERE uid=2000.
One command: fel-install.sh
frames/aqara-s1-plus/tools/install/fel-install.sh [backup-dir] does everything above, plus two more things.
- Steps:
- Waits for FEL and checks the SoC id.
- Boots our U-Boot. If our U-Boot is already in fastboot, it resumes from there instead.
- Checks the partition layout.
- Backs up
boot vbmeta vbmeta_system vbmeta_vendor dtbo misc recovery env bootloader.bootis read twice and compared, and aSHA256SUMSfile is written. - Patches
boot. - Sets
vbmetaflags to 3 if they aren't already, verified by read-back. - Flashes
boot, verifies it by read-back, then reboots. - Waits for adb.
- Extra in the boot image: first-boot provisioning.
frames/aqara-s1-plus/tools/root/s1kiosk_firstboot.{sh,rc}is a one-shot root service. It authorizes the installing computer's adb key, which is baked into the image (ADB_PUBKEY, default~/.android/adbkey.pub), and turns USB adb on. It runs once and leaves a marker in/data/s1kiosk. - Extra in the boot image: the app update service.
frames/aqara-s1-plus/tools/root/s1kiosk_update.{sh,rc}is a disabled one-shot root service. At boot init setssys.s1kiosk.update.version=1, so the app knows it exists. Details under App update service. - Extra in the boot image: the radio bundle loader (helper v4).
s1kiosk_bundle.{sh,rc},s1kiosk_verify(static ARM Ed25519 checker) ands1kiosk_bundle.pub(the project's public key). After this boot image, helper fixes, new radio stacks and radio firmware images come with app updates; see Radio bundle service.
Undo: frames/aqara-s1-plus/tools/install/fel-install.sh --undo <backup-dir>.
- It verifies the backup against its
SHA256SUMSand refuses aboot.imgthat is already Magisk-patched. That happens with a re-run's backup; use the first install's backup instead. - It flashes stock
bootandvbmetathrough FEL and verifies both by read-back. /datais not touched, so the kiosk app keeps working without root.
Factory simulation on the reference panel (2026-11-09), passed:
- Starting state: adb turned off, the adb key list emptied, stock
bootand factoryvbmeta(flags 0) flashed. fel-install.shthen:- backed up the stock partitions;
- changed
vbmetaflags 0 → 3. The result is byte-identical to the flags-3vbmetathe panel had run on before; - flashed and verified
boot.
- Without touching the screen, adb was back after the reboot:
s1kiosk_firstboot: authorized 1 new adb key(s)at 21 s. Magisk and the helper were live. - Re-running on an already-patched panel produces the same image as patching stock (deterministic output). Magisk restores the stock ramdisk first.
Gotcha: fastboot also honours ANDROID_SERIAL, and our U-Boot's fastboot serial is not the
panel's adb serial. The scripts keep ANDROID_SERIAL for adb only.
App update service
s1kiosk_update installs app updates that the app downloaded and verified (esphome.md).
- App side:
- write
/data/data/sh.edm.s1kiosk/files/update/pending.apk; setprop sys.s1kiosk.update.status requested;setprop ctl.start s1kiosk_update.
- write
- Service side:
sys.s1kiosk.update.status=running: …, thenok: sh.edm.s1kiosk <old> -> <new>orerror: <why>. - Threat model. SELinux is permissive, so other apps may be able to start init services and
set properties. The service therefore takes no input except that one file, and checks:
- the kiosk's uid from
pm list packages -U, which must match the owner of/data/data/sh.edm.s1kiosk; files,files/updateandpending.apk: no symlinks, all owned by that uid (only the kiosk can write its private dir), andpending.apkis a single-link regular file of at most 256 MiB;- it copies the file into root-only
/data/s1kiosk/update(withs1kiosk_verify --copyon boot images that have it, so a path swapped for a symlink or FIFO after the checks can't redirect or hang the copy) and installs the copy over stdin withpm install -r -S <size>, without-d. Android refuses another signing key for the same package, and refuses downgrades; - afterwards, the kiosk's versionCode must have gone up, and no other package may have changed.
A package that appeared is uninstalled again, and the status says
refused. - At worst, another app can make it install what the kiosk itself staged, or spoof the status property the app displays.
- the kiosk's uid from
- Afterwards: the old process is gone. The kiosk is HOME and restarts on
MY_PACKAGE_REPLACED; the service also runsam startof MainActivity if it isn't running after 3 s. - No service (boot images from before it): the app falls back to a PackageInstaller session with an on-screen confirmation.
Radio bundle service
s1kiosk_bundle installs the signed radio bundle the app ships (radio.md).
Same shape and threat model as s1kiosk_update:
- App side: stage
/data/data/sh.edm.s1kiosk/files/radio/bundle-in/(manifest,manifest.sig, the files),setprop sys.s1kiosk.bundle.status requested,setprop ctl.start s1kiosk_bundle. At boot init setssys.s1kiosk.bundle.loader=1, so the app knows the boot image has it. - Service side: finds the kiosk's uid (pm and the data dir owner must agree); copies manifest and
signature into a fresh root-only
/data/s1kiosk/radio/bundle/stage; checks the Ed25519 signature with the key in the boot image before reading anything else; refuses a version below the floor (bundle/version, the highest ever installed, and at least the installed one); copies only the listed files withs1kiosk_verify --copy(anopenat(O_NOFOLLOW)walk, kiosk-owned all the way, the file openedO_NONBLOCKand checked on the fd: regular, one link, the listed size; exactly that many bytes copied) and checks the copy's SHA-256; records the new floor; renames the result intobundle/current; writes the app-readable/data/s1kiosk-pub/radio-bundle; restarts the radio helper. Status:sys.s1kiosk.bundle.status=running: …/ok: radio bundle <v> installed …/error: …. - At worst another app makes it reinstall a bundle we signed (same or newer version) or spoofs the status property. Running its own root code would need the private key, which is not on the panel.
- The helper's loader re-checks
bundle/current(s1kiosk_bundle.sh --check) at every start and falls back to the boot image's helper if it fails or the bundle's helper keeps exiting.
Next
- Browser installer (WebUSB): built, in
kiln/; design in web-installer.md, user guide in docs/install.md. - After
fel-install.sh,frames/aqara-s1-plus/tools/install.shinstalls and configures the kiosk app over adb.