Updating Kiosk Satellite¶
Kiosk Satellite manages its own updates directly from GitHub releases: it detects a new release, downloads it onto the device, and passes the file to the Android installer. How much of this process happens automatically depends on your Android version and whether the app is configured as the device owner. Kiosks on a network without internet access can read releases from a custom repository on your own web server instead.
How the App Finds an Update¶
The app checks GitHub 20 seconds after launch and continues checking every 12 hours. When a new release is available, it appears in three places:
- On the device: An Update available notification appears at the bottom of the kiosk drawer menu (this is hidden in the restricted quick-actions menu).
- In the remote admin: An Install version x button displays in the Updates card on the Device page.
- In Home Assistant: The Update entity generated by the ESPHome integration displays release notes along with an Install button. This requires Expose kiosk entities to be enabled in app settings.
Home Assistant cannot force a check, so a newly published release may take a few hours to appear automatically. To check for updates manually: * On the device, tap the app version line at the bottom of the kiosk menu. * In the remote admin interface, tap the app version displayed on the Device page.
Installing¶
Triggering an update from any interface starts the same local download on the device. Before downloading, the app queries GitHub to confirm the latest release, ensuring it always fetches the newest version available. Download progress displays on the device, in the remote admin, and via the Home Assistant update entity. You can cancel active downloads from either the device or the remote admin interface.
APK Downloads¶
Releases include a universal APK and smaller APKs for armeabi-v7a, arm64-v8a and x86_64. Each architecture APK is a complete app that installs on its own. It does not need the universal APK alongside it.
The updater selects an APK using Android's supported architectures in preference order. If a compatible architecture APK is missing or the architecture cannot be detected, it uses the universal APK. A 64-bit processor running a 32-bit Android installation receives the 32-bit APK.
APK selection happens before choosing an installer. Regular updates, the optional update helper and Shizuku all receive the same architecture-specific download. The helper does not select or download a separate APK.
The universal filename remains kiosk-satellite-<tag>.apk. Architecture downloads use kiosk-satellite-<tag>.<abi>.apk. Older app versions continue to download universal because it remains the first APK asset. The release workflow preserves this order during reruns and checks it after uploading. Every APK in a release uses the same signing key and version code so an installed app can move between universal and architecture downloads.
Custom Repository¶
Kiosks on a Wi-Fi network without internet access cannot reach GitHub. Settings > Device > Updates has an Update source picker. Pick Custom Repository and enter a Repository URL: a folder on any web server the kiosk can reach, such as a NAS. The kiosk then checks that folder instead of GitHub, on the same schedule, and downloads the APK from it. Everything after the download is unchanged: the installer, Shizuku, the update helper, the Home Assistant Update entity and fleet updates all work as before. The same page is available in the remote admin.
The folder holds two kinds of files:
| File | What it is |
|---|---|
releases.json |
GitHub's releases list for Kiosk Satellite, saved as is. The kiosk reads it exactly as it reads GitHub's answer: newest release, release notes, APK names and sizes. |
kiosk-satellite-<version>.apk and kiosk-satellite-<version>.<abi>.apk |
The release APKs, kept under the names GitHub gives them. Only the ones your devices need are required. The kiosk picks the same file it would pick on GitHub. |
To mirror the latest release from a computer with internet access, run this inside the folder the web server publishes:
curl -sL "https://api.github.com/repos/jxlarrea/kiosk-satellite/releases?per_page=30" -o releases.json
TAG=$(grep -m1 '"tag_name"' releases.json | sed 's/.*: "\(.*\)".*/\1/')
for FILE in "kiosk-satellite-$TAG.apk" "kiosk-satellite-$TAG.arm64-v8a.apk" "kiosk-satellite-$TAG.armeabi-v7a.apk" "kiosk-satellite-$TAG.x86_64.apk"; do
curl -sLO "https://github.com/jxlarrea/kiosk-satellite/releases/download/$TAG/$FILE"
done
Repeat it for each new release. The kiosk notices at its next check, or right away when you tap the version line in the kiosk menu or the remote admin.
How the custom source behaves:
- Plain
http://works. Anhttps://server with a self-signed certificate needs Ignore SSL errors on the Home Assistant page, the same setting the dashboard uses. GitHub downloads always verify certificates and ignore that setting. - The URL may end in
/releases.json. The kiosk keeps the folder. - While Custom Repository is picked, the kiosk never falls back to GitHub. An unreachable folder keeps whatever the kiosk last knew and the app log names the host and the HTTP status.
- A folder holding only the running version, or an older one, reports up to date. Android verifies the signing certificate at install, so the folder can only ever serve a real Kiosk Satellite release.
- Both settings sync with the fleet, so a leader points every follower at the same folder and Update fleet works unchanged. Each kiosk downloads its own APK from the folder.
System Permission Requirements¶
Here is how Android handles installation prompts based on your system version:
| Device | Installation Behavior |
|---|---|
| Android 12 and newer | The initial in-app update displays Android's system installation confirmation on the screen. Subsequent updates install silently in the background. |
| Android 11 and older | Every update requires manual confirmation unless the optional update helper is running. |
| Device Owner Provisioned | Every update installs silently across all Android versions. |
| Shizuku updates enabled and authorized | Updates install through Shizuku without on-device confirmation. |
| Update helper running | Updates install silently through the helper when Android's native silent path is unavailable. |
On Android 12 and newer, silent updating relies on installer package tracking. Completing the initial in-app update registers Kiosk Satellite as its own installer, enabling silent background updates for future releases. Performing an adb install in between resets the installer role back to adb, requiring you to confirm one in-app update again.
The Install Unknown Apps Grant¶
Android 8 and newer requires the Install unknown apps permission before system confirmation prompts can display. On the first update attempt, the system installer stops and displays a Settings button leading directly to the toggle. Flipping this switch once grants the permission permanently. You can also find this option in Android system settings under Settings > Apps > Special app access > Install unknown apps.
To grant this permission via adb:
On custom ROMs that omit this system settings screen, device ownership is required to proceed with updates, as a device owner requires neither the grant nor manual confirmation. Meta Portal devices do display the settings screen, but require disabling a separate package verifier (detailed below).
Temporary Lockdown Release¶
Because Android's system confirmation dialogs would otherwise be hidden by screen pinning and foreground application protection, Kiosk Satellite temporarily releases lockdown mode before displaying the confirmation screen. It automatically re-arms kiosk protections once the installation completes, fails, or is cancelled.
Relaunching After Installation¶
Android terminates the running process during package updates. On Android 10 and newer, relaunching the app automatically after an update requires the Display over other apps permission. Without it, the update completes but the app remains closed until opened manually.
The setup wizard requests this permission automatically. You can also grant it via adb:
Meta Portal¶
Meta Portal devices include a built-in package verifier service that blocks app-initiated installations unless the APK contains a Meta system signature. As a result, the update downloads and displays the confirmation screen, but fails at the end with an INSTALL_FAILED_VERIFICATION_FAILURE error.
You can disable this package verifier using a single adb command:
After running this command, updates proceed through Android's confirmation screen. The optional update helper enables installation without that tap. Full device ownership is not supported on Meta Portals because their built-in system accounts (com.facebook.aloha.*) cannot be removed, causing the dpm set-device-owner command to fail.
Full setup details for these devices are available in the Meta Portal guide.
Amazon Fire Tablets¶
Updates on Amazon Fire tablets require manual confirmation unless the optional update helper is running. Fire OS 8 is based on Android 11, which requires confirmation for ordinary app installations. Device ownership cannot be applied to Fire OS: Amazon hardwires Parental Controls as a profile owner during initial system setup, causing dpm set-device-owner to fail with a "the user already has a profile owner" error.
To update a Fire tablet: start the update from the device, Home Assistant, or the remote admin, then tap the confirmation prompt when it appears on the screen. The kiosk automatically re-arms itself afterward.
The Install unknown apps grant works identically to standard Android devices, available via adb or under Settings > Security & Privacy > Apps from Unknown Sources.
Full setup details for Fire OS devices are available in the Amazon Fire tablets guide.
Shizuku updates¶
Enable Install updates through Shizuku below the Connection group in Settings > Device > Shizuku. The same toggle is available in Remote Admin. It is off by default, saves immediately and stays local to this device during fleet sync.
Set up and authorize Shizuku first. When enabled, every KS self-update uses Shizuku, including updates started from the kiosk, Remote Admin, Home Assistant or fleet management. You still choose when to install an update. The toggle does not enable automatic installation.
KS checks the connection before downloading and again before installing. If Shizuku is unavailable, unauthorized or fails to install, KS reports the error without opening Android's confirmation installer. Start Shizuku and retry or turn off the toggle to return to the existing update paths. A Shizuku service started through ADB must be restarted after a device reboot.
A separate Shizuku process stages the downloaded APK and asks Android to replace KS. It survives KS being stopped during replacement and exits after the attempt. Android checks the signing certificate. The installer accepts only KS APKs and rejects version code downgrades. It does not grant additional permissions or disable Android's package verifier. Device restrictions can still reject an installation.
The existing relaunch requirements apply. If contact is lost after installation starts, check the installed version before retrying because Android may have completed the update.
Optional Update Helper¶
The update helper lets devices such as Meta Portals and Amazon Fire tablets install Kiosk Satellite updates without an on-screen confirmation. It is included in the APK and needs one ADB command to start:
Add -s <device address> after adb when multiple devices are connected. Wait for the command to report that the helper started. The computer can then disconnect. Repeating the command while the helper is ready leaves it running.
Open Settings > Device > Optional update helper on the device or Device > Optional update helper in the remote admin. This subpage appears only when Android's native silent installation path is unavailable. It shows the helper's status with a Refresh action, a copyable startup command and a link to this guide.
Detection uses the device's current installation permissions and installer tracking rather than its model. On Android 12 and newer, the group can disappear after the first confirmed in-app update makes Kiosk Satellite its own installer.
The helper stops after every reboot. Enable ADB again if the device requires it and rerun the command. It continues running across Kiosk Satellite restarts and self-updates. No root access, device ownership or accessibility permission is needed.
Kiosk Satellite checks Android's native silent installation path first. If that path is available, it uses Android directly even when the helper is running. Otherwise it checks the helper through an authenticated connection on the device. An unavailable helper falls back to the normal confirmation screen after releasing kiosk protections. A connection lost after an installation has been committed reports an uncertain result instead of automatically starting a second installation.
The helper accepts only Kiosk Satellite APKs at the installed version or newer. Android verifies the signing certificate during installation. The helper has no network-facing endpoint and cannot run arbitrary commands or install unrelated apps. Its startup secret is available only to ADB and Kiosk Satellite.
This changes how an update installs. Checks still run every 12 hours and an update still starts from the device, remote admin or Home Assistant.
Hands-Free Updates on Android 11 and Older via Device Ownership¶
Configuring Kiosk Satellite as the device owner enables silent, hands-free updates across every Android version. It also resolves installation issues on custom ROMs that lack the "Install unknown apps" settings screen. Additionally, device ownership unlocks advanced security protections (detailed in Kiosk and Lockdown).
Note: Device ownership can only be removed by performing a full factory reset. While assigned as the device owner, Kiosk Satellite cannot be uninstalled and its device administrator status cannot be revoked. Apply this configuration exclusively to dedicated wall panels.
Android rejects device ownership if any user accounts are active on the tablet (such as Google, Samsung, Meta, or Amazon accounts). Remove all accounts or perform a factory reset before proceeding. Device ownership is also rejected if another profile owner exists (such as Fire OS Parental Controls).
To assign device ownership via adb:
The second command verifies that ownership was assigned successfully. Once enabled, future updates install silently without prompting for confirmation.
Sideloading via ADB¶
You can continue updating the app manually at any time using standard adb commands:
Manual updates preserve all local settings, Home Assistant connections, and ESPHome pairings. On Android 12 and newer, sideloading sets adb as the installer of record, meaning the next in-app update will prompt for manual confirmation once before resuming silent background updates.
Troubleshooting¶
| Symptom | Cause and Solution |
|---|---|
| Triggering install in Home Assistant does nothing | The app has not fetched the update release information yet. Manually check for updates by tapping the version text in the kiosk menu or the remote admin. |
| The Update entity displays the old version after updating | The entity state refreshes when the app reconnects to Home Assistant following a relaunch. If the app failed to relaunch, see the next row. |
| The update completed but the app remained closed | The Display over other apps permission is missing. Launch the app manually and grant this permission so future updates can relaunch automatically. |
| Nothing happens after the download completes on Android 11 or older | The system confirmation dialog could not be displayed. This usually indicates the OS lacks the "Install unknown apps" configuration screen. Grant the permission via adb or configure the app as the device owner. On Meta Portals, see the verifier fix above. On Fire tablets, see the Fire OS section above. |
| The update download fails or stalls | The device cannot reach GitHub or the connection timed out. Check the app logs in the remote admin interface for detailed error messaging. |
| A custom repository shows no update | releases.json is missing or stale, the APK it names is not in the folder, or the newest release is no newer than the running version. The app log names the host and the HTTP status of the check. |
| An update on Android 12 or newer prompted for confirmation unexpectedly | An external tool (such as adb) was used to install an intermediate update, resetting the installer role. Confirming one in-app update restores silent updating for subsequent releases. |
| Updates ask for confirmation after a reboot | The optional update helper stopped at reboot. Restore ADB access and rerun its startup command. |
| The helper connection was lost after committing an update | Check the installed version and app logs before trying again. Kiosk Satellite does not automatically retry an installation whose outcome is uncertain. |