Aesop Player: setting up full kiosk mode

(If you're looking for the "Full Kiosk Mode, QR Install" page, see here.)

This section is first about making a fully-informed decision about which of the various Kiosk Modes you want to use, and then implementing that decision if you decide on "Full Kiosk" mode.

If you've tried the other Kiosk Modes (as described here) and they don't work for you, then you can proceed as described in this section. If you haven't tried the other modes, they are worth considering because setting up Full Kiosk mode is considerably more work than the other modes. In theory Full Kiosk is more effective than the other modes, but as a practical matter you may never encounter the difference.

If you expect to install the Aesop Player on multiple devices, much of the effort of setting up Full Kiosk is one-time setup or learning, so Full Kiosk may be more attractive.

Kiosk Mode Selection

Below is a description of the various choices of Kiosk Mode, with trade-off information. You can use that to decide if Full Kiosk is worth the effort. If you choose not to use Full Kiosk, and change your mind later, it may require starting over, but it's not an irrevocable decision.

As noted in the main section on dedicated players, the goal of a dedicated player is to prevent accidentally pushing the system buttons. To prevent that, we provide three choices, each with advantages and disadvantages that fit different circumstances.

All three Kiosk Modes protect against accidental button presses, work nicely with Maintenance Mode, and if the device shuts down while displaying or playing a book (for example if the battery dies), it will return to Aesop when restarted.

Simple Kiosk mode:
Advantages:
- Works on older Androids (4.4/Kit Kat/API-19 up), We have not recently tested with the Kindle Fire. It has worked in the past, but be sure to test it thoroughly before committing to it. including possibly the Kindle Fire.
- Doesn't require any setup outside the app. (Does require granting permissions when selecting this mode for the first time. It will guide you.)
- Doesn't interfere with the phone's normal use when Aesop is not running.
Disadvantages:
- Can be ugly and slow at times.
- The folks at Google mostly rightly see disabling the system buttons, as discussed above, as a potential system security problem.
  On Android Q, further changes make Simple Kiosk barely possible, and even less attractive. You will need to restart Aesop Player at the point it asks to enable the Home Application, and it takes several seconds to return to Aesop's display after hitting the Home button (circle). (The audio will continue uninterrupted.) Works poorly on Android 10 (Q) or above. (Use Application Pinning (or Full Kiosk) instead.)
- Not guaranteed to be always effective. (99.9%, but there are probably ways around it.)
Simple mode is the only choice for There isn't a kiosk-like solution for really early versions of Android, although Aesop will run on API 17 and up. older devices. On newer devices where Full Kiosk mode or Application Pinning is available, that is strongly preferred. Simple Kiosk can be useful when the device cannot be dedicated to a single use full-time, and for some reason Application Pinning We currently know of no reason that Application Pinning would not work well. Please contact us if you run into any problems. is a problem.
Application Pinning:
There are two ways of accessing Android's "Application Pinning" feature, externally to the Aesop Player, and internally. This discusses the internal mode, since it is far simpler to use with Aesop than the external one. (We don't even test the external mode with Aesop... it's not really that convenient. Look it up on the Internet to see how it's used externally to an application.)
Advantages:
- Works well and smoothly.
- Highly reliable.
- Doesn't interfere with the phone's normal use when not running.
- Doesn't require any setup outside the app. (Does require granting permissions when selecting this mode for the first time. It will guide you.)
Disadvantages:
- Requires Android 5.0 or above.
- Isn't designed to be as resistant to intentional misuse as Full Kiosk mode.
Application pinning is preferred if you have an appropriate device unless actual use shows you need Full Kiosk mode for its stricter controls.
Full Kiosk mode:

Advantages:

Works well and smoothly.
Highly reliable once app and device is fully configured.
Requires very little care-giver expertise.

Disadvantages:

It requires Android 5.0 or later.
Leaves device in a state where it's not very usable for any other purpose.
Upgrading to a new version of the player should be done with great care (see box below).
Requires technical expertise on a one-time basis for setup.

To make Full Kiosk work, you must use the BIND_DEVICE_ADMIN privilege to enable the Aesop Player as the "Device Owner". This is a very strong privilege, and the folks at Google want us to be sure you can't do that unknowingly, so we're telling you about that here, with a some more details below. The actual step that does it is either the 'adb' command below, or in a slightly different way if you install using 'QR provisioning', also discussed below. You can stop using the privilege either by choosing another Kiosk Mode or using Maintenance Mode. If you don't use Full Kiosk mode, the privilege will remain unused and you can safely ignore its existence.

There is a Settings option on the Kiosk Mode selection screen to "Drop the privilege required for the Full Kiosk mode", which is only available if Aesop Player is the device owner. This is for expert use, clicking it will require completely redoing the Full Kiosk process to restore the permission.

Caution: Normal use and automatic app and system upgrades will be fine with Full Kiosk mode, but if you will be doing anything unusual with the Aesop Player (specifically, running any private versions of the player), be sure to both disable Full Kiosk mode and also click on "Drop the privilege required for the full kiosk mode" before changing the software. And at that there is a slight risk that you will be stuck in a halfway state that can only be fixed by a factory reset.

Full Kiosk Mode and Application Pinning are closely related in Android. The consequence of that to Aesop is that only one of the two is possible at any given time. If you have the privilege for Full Kiosk Mode, you cannot use Application Pinning; if you don't, then of course you can't use Full mode. If you are using Full Kiosk Mode, Application Pinning offers no additional benefit.

If you have not chosen Full Kiosk mode (at this time), you need not read further here. Continue with Kiosk Mode to install without Full Kiosk.

Initial Installation

If you are here, you presumably have chosen to use Full Kiosk mode. There are two ways to set that up, depending on which you find more convenient, and whether your device is new enough.

If your device is:

Android 7.0 or later.
Supports QR Code provisioning. Not all 7.0 and later devices do, depending on the vendor. (It won't hurt to try it if you decide you'd like to use it. You can use the 'adb' method if it fails, which it will do almost immediately.)
Has a functioning camera. (Apparently it can use either camera, but we've only tested with the back ("scene") camera.)

If so, you can consider using 'QR Code Provisioning'.

The 'adb' method requires that you remove all accounts from the device, and you have to use a PC and a cable (which you may already have). It does NOT require you to do a Factory Reset, but removing all accounts is similar in effect.

QR provisioning doesn't require any cables but cannot be done without doing a Factory Reset, per Google.

If you can't use QR code provisioning, or don't want to do the required Factory Reset, then proceed with the 'adb' method below. Otherwise follow the steps for QR code provisioning here.

'adb' stands for "Android Debug Bridge", and is a software tool allowing you to do things that can't be done from an Android Screen. adb Install Initial Device Setup

Preparation

You will need:

A tablet or smartphone with Aesop Player already installed and configured for use as a dedicated player, but you can skip the step of setting the Kiosk Mode if you wish.
A PC or Mac computer with Internet access.
A USB cable to connect the Aesop Player device to your computer. Your charging cable, if it unplugs from the transformer, is likely to suffice.

1. Remove all accounts

In order for step 4 to succeed, you need to remove all the accounts registered in the system. Google requires this. If you've recently done a factory reset or are using a brand new device, and have not created any accounts, that's already done and you can skip to step 2.

Here's How

Go to Settings → Accounts and remove all the accounts.

Since at this point you've decided to use the device as a completely dedicated player, if you have correctly set up your device there should be no personally identifiable information on it.

2. Enable USB debugging

You need to enable USB debugging on the device so that it accepts commands from your computer.

Here's How

Go to Settings → About device and tap on the Build number 7 times.
Go back, enter the newly added Developer options and activate USB debugging.

You are a hacker now ;)

3. Install ADB

The adb command is needed on your computer to perform the next step. The software installed here can be uninstalled later.

Here's How

Download and install the (unofficial) package from this post.

If you prefer, you can of course install the Android SDK Tools or even Android Studio but it's a bigger download and more work.

Install adb with the following command:

sudo apt-get install android-tools-adb

Open the Terminal app.
Copy and execute the following command to install Homebrew (on one line):
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Copy and execute the following command to install the adb command:
brew cask install android-platform-tools

4. Make Aesop Player a privileged application

In order for Aesop Player to take full control of the UI it needs to be given special privilege — it needs to be made a so-called device owner. This uses the BIND_DEVICE_ADMIN privilege discussed above. This doesn't change the software in any way, it does not void the warranty and it can be easily reversed or temporarily suspended.

Here's How

Attach the device with a USB cable to your computer.
On your computer start a terminal (Linux/Mac) or the command prompt (Windows).
Execute the following command (on one line):
adb shell dpm set-device-owner github.io.donnKey.aesopPlayer/com.donnKey.aesopPlayer.AesopPlayerDeviceAdmin

You should On recent (Android 9 and above) devices, if you go to Android Settings->Security&location->Device Admin Apps you'll find a long and scary-sounding message about what Aesop Player could in theory do to the system. We only use the privilege for this one purpose. see:

Success: Device owner set to package com.donnKey.aesopPlayer

If Aesop was set to Application Pinning Kiosk Mode, it will be changed to None.

In case of errors see troubleshooting.

5. Enable the full kiosk mode

Now you can enable and disable the full kiosk mode at will.

Here's How

Start Aesop Player.
Enter (Aesop) settings via the "gear" icon.
Click Prevent from exiting the application (kiosk mode).
Click Preferred Kiosk Mode.
Click the radio button for Full Kiosk (It will be enabled if you have done the above correctly.)
Go back to leave the settings screen.

Now it's impossible to leave the player application without going through Settings, which should have one of the Settings Interlock modes set.
You can change the Kiosk Mode by selecting one of the other available types.

You can give up the permission completely by tapping Drop the privilege required for the full kiosk mode; you would need to repeat the step using adb above to restore it.

Dropping the privilege while in Full Kiosk Mode will cause the Kiosk Mode to be changed to None.

If you want to temporarily leave Full Kiosk mode to do other work on the device, put Aesop into Maintenance Mode.

6. Finish Up The Install

If you did a Factory Reset or started with a device that did not have Aesop Player installed, there are a number of settings you should adjust as well:

The instructions for creating a Dedicated Device starting here describe what should be done for a dedicated device — follow them up to the point of setting the Kiosk Mode, since you've already done that.
Also adjust the other Aesop Player settings, such as the sleep timer, here.