Setting up your Android TV

This guide walks you through setting up an Android TV or streaming stick with the BetterSTR TV launcher. You’ll enable developer mode on the device, run the BetterSTR TV Setup tool on your computer, scan your network, provision the device, and pair it to one of your properties.

🧩 Requirements

Before you begin, make sure you have:

• An Android TV or Google TV device (smart TV, or a stick such as the Google TV Streamer or Xiaomi TV Stick)

• A Mac or Windows computer on the same network as the TV

• The BetterSTR TV Setup tool (download link below)

• A BetterSTR account with at least one property set up

🔧 Step 1: Put the Device into Developer Mode

The setup tool talks to the TV over ADB, which is only available once developer mode is on. On the TV:

1. Open Settings.

2. Go to System → About.

3. Scroll to Android TV OS build (or Build) and click it 7 times until you see “You are now a developer”.

4. Go back to Settings → System → Developer options.

5. Turn on both USB debugging and Wireless debugging (some sticks have no USB port, so turning both on covers every device). Note the device’s IP address shown under Wireless debugging — you’ll need it in Step 2, and once the Google account is removed the TV drops to the login screen and can’t show Settings again. (The setup tool / scripts can also scan the network for it.)

6. Make sure the TV is connected to the same Wi–Fi network as your computer.

🔓 Step 2: Remove the Google account

Removing the account is what lets the app install as a Device Owner — the full feature set (silent updates, a permanently locked Home screen, guest sign-out at checkout). You do not need to factory reset.

First, take note of the device’s IP address — Settings → System → Developer options → Wireless debugging (you saw it in Step 1). Once the account is removed the TV returns to the login screen and you can’t open Settings to find it again, so write it down now.

Then remove the account: Settings → Accounts (or Passwords & accounts) → tap the account → Remove account and go offline.

💾 Step 3: Download and Run BetterSTR TV Setup

• Download — macOS: BetterSTR-TV-Setup-macOS.zip

• Download — Windows: BetterSTR-TV-Setup-Windows.zip

• Extract the ZIP file.

• macOS: hold ⌘ Command and right-click the app, then choose “Open” (required the first time).

• Windows: open the extracted BetterSTR-TV-Setup folder and run BetterSTR-TV-Setup.exe. If a blue “Windows protected your PC” box appears, click More info → Run anyway (it’s an unsigned in-house tool).

The tool opens to a device list with a Scan Network button.

Prefer no GUI (or doing several devices)? The same ZIP also contains a script — windowsProvision.bat on Windows, macProvision.sh on Mac — that does the same install from the command line, and can scan the network to find the TV if you didn’t note its IP. See the included README.txt.

🔍 Step 4: Click “Scan Network”

Click Scan Network. The tool searches your local network for Android devices with ADB enabled and lists each one’s name, model, IP address, Android version and the currently installed app version.

📺 Step 5: Choose the Android Device

Select your TV from the list.

⚙️ Step 6: Click “Provision Selected Device”

With the device selected, click Provision selected device. With no account present (you removed it in Step 2) the tool installs the app, sets it as Device Owner, and configures everything — you’ll see each step tick off in the log, finishing with the home screen launching on the TV. Afterwards you can sign back in to Google if you wish (the Play Store keeps working; Device Owner stays in place).

If the log says Device Owner could not be set, an account is still on the device — remove it (Step 2 — remove & go offline, not reset) and provision again. The app still installs and works without Device Owner; you just won’t get silent updates / a locked Home until it’s set.

🔗 Step 7: Pair the TV to a Property

On the TV, the BetterSTR TV home screen shows a QR code. On your phone:

1. Scan the QR code — it opens the device’s setup page in BetterSTR.

2. Select the property this TV belongs to.

The TV will pick up the property’s guidebook, Wi–Fi details and branding on its next refresh.

✅ You’re all set!
Your Android TV is now running the BetterSTR TV launcher and paired to your property. Future app updates are delivered automatically over the air.

🛠️ Advanced setup — ADB (no desktop tool)

If you’re comfortable with ADB you can provision a TV by hand instead of using the BetterSTR TV Setup app — handy for scripting or for Linux users. First complete Step 1 above (developer mode + USB/Wireless debugging), make sure the TV is on your network, and install Android platform-tools (which provides adb) on your computer.

Then run the following (replace <TV-IP> with your TV’s IP address):

# Connect (accept the "Allow debugging?" prompt on the TV the first time)
adb connect <TV-IP>:5555
D=<TV-IP>:5555

# 1) Download + install the latest build.  -i + --update-ownership make it the
#    installer of record so it can update itself silently (OTA) on Android 12+.
VER=$(curl -s https://api.betterstr.com/device/firmware/android-tv/version.json | grep -o '"base_version"[^,]*' | cut -d'"' -f4)
curl -L -o betterstr-tv.apk https://api.betterstr.com/device/firmware/android-tv/$VER.apk
adb -s $D install -r --update-ownership -i nz.co.unix.iptv betterstr-tv.apk

# 2) Allow it to install future (OTA) updates, change settings, control standby, and power on at check-in
adb -s $D shell appops set nz.co.unix.iptv REQUEST_INSTALL_PACKAGES allow
adb -s $D shell appops set nz.co.unix.iptv WRITE_SETTINGS allow
# Android 14+ only: lets the app wake the TV for the auto power-on-at-check-in schedule.
# It is an appop (not a runtime permission), so Device Owner can't grant it automatically — set it here.
adb -s $D shell appops set nz.co.unix.iptv TURN_SCREEN_ON allow
adb -s $D shell pm grant nz.co.unix.iptv android.permission.WRITE_SECURE_SETTINGS

# (optional) Remote support: let the app stream its own logs to your dashboard for debugging
adb -s $D shell pm grant nz.co.unix.iptv android.permission.READ_LOGS

# 3) Make our app the Home screen.  set-home-activity sets it as the default Home
#    (so the HOME button returns here, even without Device Owner); the accessibility
#    service is the fallback on Google TV, which blocks normal launcher replacement.
adb -s $D shell cmd package set-home-activity nz.co.unix.iptv/.ChooserActivity
adb -s $D shell settings put secure enabled_accessibility_services nz.co.unix.iptv/nz.co.unix.iptv.HomeRedirectService
adb -s $D shell settings put secure accessibility_enabled 1

# 4) Set the custom BetterSTR screensaver
adb -s $D shell settings put secure screensaver_components nz.co.unix.iptv/nz.co.unix.iptv.ScreensaverDream
adb -s $D shell settings put secure screensaver_enabled 1
adb -s $D shell settings put secure screensaver_activate_on_sleep 1
adb -s $D shell settings put secure screensaver_activate_on_dock 1

# 5) (Optional) report the TV's real MAC to your dashboard
MAC=$(adb -s $D shell "cat /sys/class/net/wlan0/address 2>/dev/null || cat /sys/class/net/eth0/address 2>/dev/null" | tr -d '\r')
adb -s $D shell settings put global mybnb_mac "$MAC"

# 6) Launch the home screen
adb -s $D shell am start -n nz.co.unix.iptv/.ChooserActivity

Finally, on the TV, scan the QR code and pair it to a property (Step 7 above).