Homebridge ADB and Shell Scripts

A HomeBridge plugin to control remote ADB enabled Android device. The idea is to make random Android based TV box can be controlled with Home App. It make any Android device appear as TV accesory. Where you can control on/off status, volume and dpad control via Control Center remote, and launch certain predefined app defined in the configuration.

This plugins register it self as external accesorries. Make sure after adding Homebridge bridge in Home App, manually "add accesories" to add the android device in the Home App.

||||| |----------|----------|----------|----------|

Prerequisite

1. Install Homebridge, Homebridge Config UI X (this plugin support web configuration over there), and this plugins

   sudo npm install -g --unsafe-perm homebridge homebridge-config-ui-x
   sudo npm install homebridge-adb

2. Install ADB tools inside Homebridge server. Open Homebridge Config UI X in your browser then navigate to terminal or ssh to your homebridge server, and then run this command:

   • If the homebridge server run inside Ubuntu, use this command:

     sudo apt-get install android-tools-adb android-tools-fastboot

   • Or, if the homebridge run inside Docker container like the one from oznu/docker-homebridge, please refer to Docker container section
   • Or, if you're using other OS, please refer this link to download the ADB tools: https://developer.android.com/studio/releases/platform-tools
   • Check if the ADB installed properly by running this command:

     adb --version

     This will output something like Android Debug Bridge version x.x.x

3. Enable remote developer mode in your Android device. Visit this documentation for more information https://developer.android.com/studio/debug/dev-options

4. IMPORTANT: Some Android device doesn't support "Remote ADB" by default. If your device is one of them, connect your device with USB cable to any computer with ADB installed. Open terminal and run this command:

   adb tcpip 5555

   if no error produced, disconnect unplug the USB cable from the computer.

5. OPTIONAL Run this command to make sure you can connect to device:

   adb connect your-device-ip

   If all goes well, there will be a popup window in your android device asking for debug permission. After you accept the request, you might want to do kill the adb server to make a fresh connection

   adb kill-server

   After that reconnect your device again with previous adb connect. Test your adb connection by running this command:

   adb -s your-device-ip shell "getprop ro.product.model"

   This command will output your device model.

Docker container based on oznu/docker-homebridge

• MANDATORY If you're using a container based on Alpine Linux (like oznu/docker-homebridge:latest), run this command in terminal to install adb

  # Install adb, required by the homebridge-adb plugin
  echo 'http://dl-cdn.alpinelinux.org/alpine/v3.14/main/' >> /etc/apk/repositories
  echo 'http://dl-cdn.alpinelinux.org/alpine/v3.14/community/' >> /etc/apk/repositories
  apk add android-tools

  You can use other version of repo, but I only tested the v3.14 repo, and it seems it's the only adb tools that work with oznu/docker-homebridge .

• MANDATORY If you're using a container based on Debian (like the oznu/docker-homebridge:ubuntu & oznu/docker-homebridge:debian docker image), run this command in terminal to install adb

  # Update apt package index
  apt-get update
  
  # Install adb, required by the homebridge-adb plugin
  apt-get install -y android-tools-adb android-tools-fastboot

• OPTIONAL Append the followings line to your config/startup.sh to install or update this plugin on every container restart:

  # Install the homebridge-adb plugin
  npm install homebridge-adb

• OPTIONAL If you run into issues when connecting your android device (sometimes adb can't create the $HOME/.android/adbkey), add this line to your config/startup.sh:

  # Fix connection issues for the homebridge-adb plugin
  adb connect YOUR_ANDROID_DEVICE_IP

Configuration

Here an example of configuration that you can use.

"platforms": [
	{
		"platform": "HomebridgeADB",
		"accessories": [
			{
				"name": "NVIDIA Shield",
				"interval": 1000,
				"ip": "192.168.1.1",
				"path": "/usr/bin/adb",
				"timeout": 1000,
				"playbacksensor": true,
				"playpauseobutton": "KEYCODE_MEDIA_PLAY_PAUSE",
				"backbutton": "shell sh ./myscript.sh",
				"infobutton": "KEYCODE_HOME KEYCODE_HOME",
				"category": "TV_STREAMING_STICK",
				"hidenumber": true,
				"hidehome": true,
				"hideother": true,
				"debug": true,
				"skipSpeaker": false,
				"inputs": [
					{
						"name": "HBO Max",
						"id": "com.hbo.hbonow"
					},
					{
						"name": "Apple Music",
						"id": "com.apple.android.music"
					}
				]
			},
			{
				"name": "Meizu",
				"ip": "192.168.1.2",
				"playbacksensor": false,
				"mac": "97:b6:e8:46:9f:cb",
				"inputs": [
					{
						"name": "Termux",
						"id": "com.termux",
						"adb": "monkey -p com.termux 1"
					}
				]
			}
		]
	}
]

• platform (mandatory): the name of this plugin.
• accessories (mandatory): JSON object of your devices.
  • name (mandatory): the name of the accessory.
  • ip (mandatory): the IP address of the accessory.
  • mac (optional): the MAC address of the accessory. When provided and your accessory support Wake On LAN, this plugin will try to use Wake On LAN to Turn On your accessory. Useful if your accessory disconnect ADB connection after it turned off.
  • path (optional): if you prefer using direct path to access ADB instead of setting up in your global path, you can type the path here including the executable filename.
  • interval (optional): if not set, the plugin will check accessory statuses every 1000 miliseconds. The minimum interval value is 500. Lower then that, the plugin will flood your network.
  • timeout (optional): if not set, the plugin will limit ADB execution timeout to 3000 miliseconds. The minimum timeout value is 1000. Smaller value can make plugins more responsive but will prone to time out especially when your network is slow.
  • inputs (optional): by default the plugins will create Home for launcher shortcut and Other for previous app shortcut as input. If set, the plugins will add more input based on the config. To know your app id, please see your Homebridge log. When you leave this blank, and set hidehhome and hideother to true, the plugins will hide inputs in Home App.
    • name (mandatory): the name of the input.
    • id (mandatory): the application id. The id will be use for input switcher in Home app. If you put random id, the input will move to "other".
    • adb (optional): you can run your own ADB shell command here, such as: monkey -p com.app.id 1. This is an ADB shell command, so you doesn't need to type "adb -s ipaddress shell ...".
  • playbacksensor (optional): if set to true, plugin will create a motion sensor based on playback activity (either video or music).
  • category (optional): you can choose from this categories: APPLE_TV, TELEVISION, TV_STREAMING_STICK, TV_SET_TOP_BOX, AUDIO_RECEIVER, or SPEAKER. Home app will display different icon based on the category you choose.
  • volumeup, volumedown, upbutton, leftbutton, rightbutton, leftbutton, infobutton, playpauseobutton, backbutton, poweron, poweroff (optional): assign custom ADB keycode for Remote control action in iOS Control Center.
    • You can put one or more keycodes by seperating them with space, eg: volumeup: "KEYCODE_VOLUME_UP KEYCODE_VOLUME_DOWN". See https://developer.android.com/reference/android/view/KeyEvent for the keycode list. Or,
    • You can put a ADB shell script to run a shell script inside your device, eg: leftbutton: "monkey -p com.termux 1". Or,
    • You can also put a shell script. Put shell identifier to let the plugins know it's a shell script, eg: volumeup: "shell sh ./myscript.sh".
    • You can also put app id to run app, because why not?, eg: infobutton: "com.google.android.youtube.tv".
  • hidenumber (optional): if set to true, plugin will hide number inputs in Home App.
  • hidehome (optional): if set to true, plugin will hide "Home" input in Home App.
  • hideother (optional): if set to true, plugin will hide "Other" input in Home App.
  • debug (optional): if set to true, plugin will output more debug info in homebridge log.
  • skipSpeaker (optional): if set to true, an accompanying speaker will not be initialized for the device and will disable volume control in Control Center Remote.
  • launcherid (optional): Some launcher like projectivy (which is a nice launcher if you tired looking at forced ads from Google) can't be detected as the default launcher for the "Home" input. Write the app id so the plugins can recognize the launcher as the "Home" input.
  • stateAdbCommand (optional): Some android device, seem to have different dumpsys power value to determine its state. Define your own adb shell command based on your device. eg: dumpsys power | grep mWakefulness=
  • stateAdbOutputAwake (optional): Related to stateAdbCommand, define the output value that the command will output, remember it's case sensitive. eg: Awake

If you're using Homebridge Config UI X, you can configure your device there, but there's a small hiccup with Inputs. It only display one input, but if you press add, it will display the rest of the inputs.

Questions and Support

If your have any question, refer to FAQ.md first before sending GitHub issues.

If want to support this plugin, you can buy me an Ice cream by follow this link. Or feel free to share and stared this repo.

Sidenote

There is currently an Android TV homebridge plugins that work with "Android TV remote control protocol version 2", it should have simpler setup. You can check the plugin here and see if it's work with your device. However, it will only work with Android TV devices, not every Android devices. Note: I'm not the contributor of the that plugin.