/homebridge-xbox-tv

Homebridge plugin for Microsoft Game Console, publish as independent external platform accessory.

Primary LanguageJavaScriptMIT LicenseMIT

Xbox and controller

Homebridge Xbox TV

verified-by-homebridge npm npm GitHub pull requests GitHub issues

Homebridge plugin for Microsoft game Consoles. Tested with Xbox One X/S and Xbox Series X.

Package Requirements

Package Installation Role Required
Homebridge Homebridge Wiki HomeKit Bridge Required
Config UI X Config UI X Wiki Web User Interface Recommended
Xbox TV npm install -g homebridge-xbox-tv Plug-In Required

Note

  • For v1.4.0 and above the required version of Homebridge >= 1.3.x.
  • For v2.0.0 and above the required version of Node.js >= 14.x.x.
  • If upgrade from 1.x.x to 2.x.x the xboxLiveId need to be set again.

Know Issues

  • Console connected to WLAN network some times lose its connection to the network after Power OFF and the Power ON command may not work.

Troubleshooting

  • If for some reason the device is not displayed in HomeKit app try this procedure:
    • Go to ./homebridge/persist.
    • Remove AccessoryInfo.xxx file which contain Your device data: {"displayName":"Xbox"}.
    • Next remove IdentifierCashe.xxx file with same name as AccessoryInfo.xxx.
    • Restart Homebridge and try add it to the HomeKit app again.

Features and How To Use Them

  • Power ON/OFF short press tile in HomeKit app.
  • Reboot Console with additional button, rquired webApiControl enabled.
  • RC/Media control is possible after you go to the RC app on iPhone/iPad.
  • Speaker control is possible after you go to RC app on iPhone/iPad Speaker Service.
  • Legacy Volume and Mute control is possible throught extra lightbulb/fan (slider).
  • Apps, Inputs, Games can be switched if webApiControl is enabled and console is authorized.
  • Siri can be used for all functions, some times need create legacy buttons/switches/sensors.
  • Automations can be used for all functions, some times need create legacy buttons/switches/sensors.
  • Record Game DVR with additional button.
  • MQTT Client publisch all available data from device.

Accessory tile in the HomeKit app Changing the accessory input Arrow pointing to the remote control icon in the control center Remote control interface

Configuration Console

  • Device must have Instant-on power mode enabled
    • Profile & System > Settings > General > Power mode & startup
  • Console need to allow connect from any 3rd app. Allow Connections from any device should be enabled.
    • Profile & System > Settings > Devices & Connections > Remote features > Xbox app preferences.

Authorization Manager

  • First of all please use built in Authorization Manager.
  • Start new authorization need remove old token first, to clear token use Authorization Manager GUI.
  • Make sure Your web browser do not block pop-up window, if Yes allow pop-up window for this app.
  • If for some reason you cannot use Authorization Manager, please use Authorization Manual Mode (removed ab v2.0.13).

Authentication Manager

Authorization Manual Mode (removed ab v2.0.13)

  • After enable webApiControl option, restart the plugin and go to Homebridge console log.
  • Follow the instructions in the console log.
  • Start new authorization need remove old token first, go to ./homebridge/xboxTv/ and remove token file.

Configuration

Install and use Homebridge Config UI X plugin to configure this plugin (Highly Recommended). The sample configuration can be edited and used manually as an alternative. See the sample-config.json file in this repository for an example or copy the example below into your config.json file, making the apporpriate changes before saving it. Be sure to always make a backup copy of your config.json file before making any changes to it.

Key Description
name Here set the accessory Name to be displayed in Homebridge/HomeKit.
host Here set the Hsostname or Address IP of Console.
xboxLiveId On your console select Profile > Settings > System > Console info, listed as Xbox network device ID. You can only find the Xbox network device ID in Settings on your console, this is different from your console serial number.
clientId If You create app on Azure AD then You can use your own Client Id.
clientSecret If You create app on Azure AD then You can use own Client Secret.
userToken Alternate authorization method.
userUhs Alternate authorization method.
webApiControl If enabled, the console can be controlled using Web Api and additional functions are available in Advanced Settings section.
xboxWebApiToken Required if webApiControl enabled.
disableLogInfo If enabled, disable log info, all values and state will not be displayed in Homebridge log console.
disableLogDeviceInfo If enabled, add ability to disable log device info by every connections device to the network.
enableDebugMode If enabled, deep log will be present in homebridge console.
volumeControl Here select what a additional volume control mode You want to use (None, Slider, Fan), not yet implemented.
infoButtonCommand Here select the function of I button in RC app.
getInputsFromDevice If enabled, apps will be loaded from device, only available if webApiControl enabled.
filterGames If enabled, Games will be hidden and not displayed in the inputs list, only available if webApiControl enabled.
filterApps If enabled, Apps will be hidden and not displayed in the inputs list, only available if webApiControl enabled.
filterSystemApps If enabled, System Apps (Accessory, Microsoft Store, Television) will be hidden and not displayed in the inputs list, only available if webApiControl enabled.
filterDlc If enabled, Dlc will be hidden and not displayed in the inputs list, only available if webApiControl enabled.
inputs.name Here set Input Name which You want expose to the Homebridge/HomeKit, Screensaver, Television, TV Settings, Dashboard, Accessory, Settings, Network Troubleshooter, Microsoft Store are created by default.
inputs.reference Required to identify current running app.
inputs.oneStoreProductId Required to switch apps.
inputs.type Here select from available types.
buttons.name Here set Button Name which You want expose to the Homebridge/HomeKit.
buttons.command Here select button control mode or command, Reboot and Switch App/Game- only possible if webApiControl enabled.
buttons.oneStoreProductId Here set Input oneStoreProductId, only possible if webApiControl enabled.
buttons.displayType Here select display type in HomeKit app, possible Switch, Button - selectable in HomeKit app as Light, Fan, Outlet.
enableMqtt If enabled, MQTT Broker will start automatically and publish all awailable PV installation data.
mqttHost Here set the IP Address or Hostname for MQTT Broker.)
mqttPort Here set the Port for MQTT Broker, default 1883.)
mqttPrefix Here set the Prefix for Topic or leave empty.)
mqttAuth If enabled, MQTT Broker will use authorization credentials.
mqttUser Here set the MQTT Broker user.
mqttPasswd Here set the MQTT Broker password.
mqttDebug If enabled, deep log will be present in homebridge console for MQTT.
reference, oneStoreProductId If web Api enabled then all available in ./homebridge/xboxTv/inputs_xxxxxx file.

*Example Config:

{
	"platform": "XboxTv",
	"devices": [
		{
			"name": "Xbox One",
			"host": "192.168.1.6",
			"xboxLiveId": "FD0000000000",
			"clientId": "",
			"clientSecret": "",
			"userToken": "",
			"userUhs": "",
			"xboxWebApiToken": "",
			"webApiControl": false,
			"disableLogInfo": false,
			"disableLogDeviceInfo": false,
			"enableDebugMode": false,
			"volumeControl": 0,
			"infoButtonCommand": "nexus",
			"getInputsFromDevice": false,
			"filterGames": false,
			"filterApps": false,
			"filterSystemApps": false,
			"filterDlc": false,
			"inputs": [
						{
							"name": "A Way Out",
							"reference": "AWayOut_zwks512sysnyr!AppAWayOut",
							"oneStoreProductId": "",
							"type": "APPLICATION"
						},
						{
							"name": "Apple TV",
							"reference": "AppleInc.AppleTV_nzyj5cx40ttqa!App",
							"oneStoreProductId": "",
							"type": "APPLICATION"
						}
					],
			"buttons": [
						{
							"name": "Play",
                            "command": "play",
							"displayType": 0,
						},
						{
					        "name": "Record Game DVR",
					        "command": "recordGameDvr",
							"displayType": 0
				        },
				        {
					        "name": "Reboot",
					        "command": "reboot",
							"displayType": 0
				        },
						{
							"name": "A Way Out",
							"command": "switchAppGame",
							"oneStoreProductId": "oneStoreProductId",
							"displayType": 0
						},
					],
            "enableMqtt": false,
            "mqttHost": "192.168.1.33",
            "mqttPort": 1883,
            "mqttPrefix": "home/xbox",
            "mqttAuth": false,
            "mqttUser": "user",
            "mqttPass": "password",
             "mqttDebug": false
		}
	]
}

Adding to HomeKit

Each accessory needs to be manually paired.

  1. Open the Home app on your device.
  2. Tap the .
  3. Tap Add Accessory, and select I Don't Have a Code or Cannot Scan or More Options.
  4. Select your Your accessory.
  5. Enter the Homebridge PIN or scan the QR code, this can be found in Homebridge UI or Homebridge logs.
  6. Complete the accessory setup.

Limitations

  • That maximum Services for 1 accessory is 100. If Services > 100, accessory stop responding.
  • To solve this problem the plugin counts the number of Services and not allow add more as 100.
  • If You have configured more as 100 Services some inputs or buttons will not be available in the HomeKit app.
  • The Services in this accessory are:
    • Information.
    • Speaker.
    • Lightbulb.
    • Fan.
    • Television.
    • Inputs, which may range from 6 to 100 as each input is 1 service.
    • Buttons, which may range from 6 to 100 as each button is 1 service.

What's New

Development

  • Pull request and help in development highly appreciated.