# 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.

## 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.

## 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. |
| 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`:

```
adb shell appops set me.jxl.kiosk_satellite REQUEST_INSTALL_PACKAGES allow
```

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`:

```
adb shell appops set me.jxl.kiosk_satellite SYSTEM_ALERT_WINDOW allow
```

## 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:

```
adb shell settings put global package_verifier_enable 0
```

After running this command, updates proceed through Android's confirmation screen. The optional [update helper](#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](portal.md) guide.

## Amazon Fire Tablets

Updates on Amazon Fire tablets require manual confirmation unless the optional [update helper](#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](fire.md) guide.

## 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:

```sh
adb shell "content read --uri content://me.jxl.kiosk_satellite.update-helper/start | sh"
```

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](kiosk.md#going-further-device-ownership)).

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`:

```
adb shell dpm set-device-owner me.jxl.kiosk_satellite/.KioskAdminReceiver
adb shell dpm list-owners
```

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:

```
adb install -r kiosk-satellite.apk
```

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. |
| 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. |