homebridge-xbox-tv 4.1.25 → 4.2.0

package/CHANGELOG.md

@@ -18,6 +18,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - For plugin < v4.1.0 use Homebridge UI <= v5.5.0
 - For plugin >= v4.1.0 use Homebridge UI >= v5.13.0
 
+## [4.2.0] - (23.09.2026)
+
+### Changes
+
+- added: Home Assistant discovery (`HA Discovery` option in the MQTT section). The device appears in Home Assistant as one media player (class `receiver`) with power, volume, mute, source selection and more. Requires the [MQTT Universal Media Player](https://github.com/grzegorz914/homeassistant-mqtt-media-player) integration
+- added: MQTT availability topic (`<prefix>/Availability`, retained `online` / `offline` last will) when HA Discovery is enabled
+- fix: MQTT/RESTFul `App` command now switches built-in inputs (Dashboard, Settings, Television, Xbox Guide...) the same way as HomeKit
+- readme update
+- sample config update
+
 ## [4.1.25] - (23.09.2026)
 
 ### Changes

package/README.md

@@ -41,7 +41,7 @@
 * Apps, Inputs, Games can be switched if `webApiControl` is enabled and console is authorized.
 * Siri can be used for all functions, some times need to be created legacy buttons/switches/sensors.
 * Automations can be used for all functions, some times need to be created legacy buttons/switches/sensors.
-* Support external integrations, [RESTFul](https://github.com/grzegorz914/homebridge-xbox-tv?tab=readme-ov-file#restful-integration), [MQTT](https://github.com/grzegorz914/homebridge-xbox-tv?tab=readme-ov-file#mqtt-integration).
+* Support external integrations, [RESTFul](https://github.com/grzegorz914/homebridge-xbox-tv?tab=readme-ov-file#restful-integration), [MQTT](https://github.com/grzegorz914/homebridge-xbox-tv?tab=readme-ov-file#mqtt-integration), [HA Discovery](https://github.com/grzegorz914/homeassistant-mqtt-media-player).
 
 <p align="center">
  <a href="https://github.com/grzegorz914/homebridge-xbox-tv"><img alt="Accessory tile in the HomeKit app" src="https://raw.githubusercontent.com/grzegorz914/homebridge-xbox-tv/master/graphics/homekit.png" width="382" /></a>
@@ -138,6 +138,7 @@
 | `mqtt.clientId` | Here optional set the `Client Id` of MQTT Broker. |
 | `mqtt.prefix` | Here set the `Prefix` for `Topic` or leave empty. |
 | `mqtt.protocolVersion` | Here select the MQTT protocol version, `5.0` (default) or `3.1.1` for brokers that only support 3.1.1 (e.g. ioBroker MQTT adapter). |
+| `mqtt.haDiscovery` | If enabled, the device is published to Home Assistant as one media player (class `receiver`) with power, volume, mute, source selection and more. Requires the [MQTT Universal Media Player](https://github.com/grzegorz914/homeassistant-mqtt-media-player) integration. |
 | `mqtt.auth{}` | MQTT authorization object. |
 | `mqtt.auth.enable` | Here enable authorization for MQTT Broker. |
 | `mqtt.auth.user` | Here set the MQTT Broker user. |
@@ -178,6 +179,10 @@
 ### MQTT Integration
 
 * Subscribe data as a JSON Object `{App: "Xbox.Dashboard_8wekyb3d8bbwe!Xbox.Dashboard.Application"}`
+* HA Discovery - if enabled, the device is published to Home Assistant as one media player (class `receiver`) with power, volume, mute, source selection and more. Games and apps are available as sources, volume can be changed only up and down. Requires the [MQTT Universal Media Player](https://github.com/grzegorz914/homeassistant-mqtt-media-player) integration. Additional retained topics:
+  * `homeassistant/media_player/<id>/config` - discovery message.
+  * `HA State` - `{"power": true, "state": "playing", "muted": false, "source": "9WZDNCRFJ3TJ", "app_name": "Netflix"}`.
+  * `Availability` - `online`, `offline` (last will).
 
 | Method | Topic | Message | Type |
 | --- | --- | --- | --- |

package/config.schema.json

@@ -1238,6 +1238,15 @@
 										"functionBody": "return model.devices[arrayIndices].mqtt.enable === true;"
 									}
 								},
+								"haDiscovery": {
+									"title": "HA Discovery",
+									"type": "boolean",
+									"default": false,
+									"description": "Publish a Home Assistant MQTT discovery message so the device appears as one media player (class receiver). Requires the MQTT Universal Media Player integration in Home Assistant: https://github.com/grzegorz914/homeassistant-mqtt-media-player",
+									"condition": {
+										"functionBody": "return model.devices[arrayIndices].mqtt.enable === true;"
+									}
+								},
 								"auth": {
 									"title": "Authorization",
 									"type": "object",
@@ -1492,6 +1501,7 @@
 														"devices[].mqtt.clientId",
 														"devices[].mqtt.prefix",
 														"devices[].mqtt.protocolVersion",
+														"devices[].mqtt.haDiscovery",
 														{
 															"key": "devices[].mqtt.auth",
 															"title": "Authorization",

package/index.js

@@ -157,6 +157,7 @@ class XboxPlatform {
 						clientId: device.mqtt.clientId ? `microsoft_${device.mqtt.clientId}_${Math.random().toString(16).slice(3)}` : `microsoft_${Math.random().toString(16).slice(3)}`,
 						prefix: device.mqtt.prefix ? `microsoft/${device.mqtt.prefix}/${name}` : `microsoft/${name}`,
 						protocolVersion: device.mqtt.protocolVersion,
+						haDiscovery: device.mqtt.haDiscovery,
 						user: device.mqtt.auth?.user,
 						passwd: device.mqtt.auth?.passwd,
 						logWarn: logLevel.warn,

package/package.json

@@ -1,7 +1,7 @@
 {
   "displayName": "Xbox TV",
   "name": "homebridge-xbox-tv",
-  "version": "4.1.25",
+  "version": "4.2.0",
   "description": "Homebridge plugin to control Xbox game consoles.",
   "license": "MIT",
   "author": "grzegorz914",

package/src/hadiscovery.js

@@ -0,0 +1,89 @@
+// Home Assistant discovery for the MQTT Universal Media Player integration
+// https://github.com/grzegorz914/homeassistant-mqtt-media-player
+const PLATFORM = 'mqtt_universal_media_player';
+
+class HaDiscovery {
+    constructor(mqtt, config) {
+        // + and # are MQTT wildcards, Home Assistant would subscribe to a pattern instead of the device topic
+        if (/[+#]/.test(mqtt.config.prefix)) {
+            throw new Error(`MQTT prefix ${mqtt.config.prefix} must not contain + or #, rename the device or set a prefix`);
+        }
+
+        this.mqtt = mqtt;
+        this.objectId = String(config.objectId).replace(/[^a-zA-Z0-9_-]/g, '_');
+        this.uniqueId = this.objectId;
+        this.name = config.name;
+        this.deviceClass = config.deviceClass;
+        this.device = config.device ?? {};
+        this.commands = config.commands ?? {};
+
+        this.configTopic = `${mqtt.haPrefix}/media_player/${this.objectId}/config`;
+        this.stateTopic = `${mqtt.config.prefix}/HA State`;
+        this.commandTopic = `${mqtt.config.prefix}/Set`;
+
+        this.sources = [];
+        this.soundModes = [];
+        this.state = {};
+        this.lastConfig = '';
+        this.lastState = '';
+    }
+
+    // Publish (or republish when changed) the retained discovery message
+    async publishConfig({ sources = this.sources, soundModes = this.soundModes } = {}) {
+        this.sources = uniqueByName(sources);
+        this.soundModes = uniqueByName(soundModes);
+
+        const device = { identifiers: [this.uniqueId], name: this.name };
+        for (const [key, value] of Object.entries(this.device)) {
+            if (value !== undefined && value !== null && value !== '') device[key] = String(value);
+        }
+
+        const config = {
+            platform: PLATFORM,
+            unique_id: this.uniqueId,
+            device_class: this.deviceClass,
+            state_topic: this.stateTopic,
+            command_topic: this.commandTopic,
+            availability_topic: this.mqtt.availabilityTopic,
+            device,
+            commands: this.commands,
+            sources: this.sources,
+            sound_modes: this.soundModes
+        };
+
+        const payload = JSON.stringify(config);
+        if (payload === this.lastConfig) return false;
+        this.lastConfig = payload;
+        await this.mqtt.publishRetained(this.configTopic, payload);
+        return true;
+    }
+
+    // Merge a partial state and publish it retained when something changed
+    async updateState(partial) {
+        for (const [key, value] of Object.entries(partial)) {
+            if (value === undefined) continue;
+            this.state[key] = value;
+        }
+
+        const payload = JSON.stringify(this.state);
+        if (payload === this.lastState) return false;
+        this.lastState = payload;
+        await this.mqtt.publishRetained(this.stateTopic, payload);
+        return true;
+    }
+}
+
+// Home Assistant needs unique names, keep the first item for a duplicated name
+function uniqueByName(items) {
+    const seen = new Set();
+    const result = [];
+    for (const item of items) {
+        const name = String(item.name ?? '').trim();
+        if (!name || item.id === undefined || item.id === null || seen.has(name)) continue;
+        seen.add(name);
+        result.push({ ...item, name });
+    }
+    return result;
+}
+
+export default HaDiscovery;

package/src/mqtt.js

@@ -12,12 +12,20 @@ class Mqtt extends EventEmitter {
         const isV5 = protocolVersion === 5;
         this.isV5 = isV5;
 
+        // Home Assistant discovery, availability is reported with a retained last will
+        this.haDiscovery = config.haDiscovery === true;
+        this.haPrefix = config.haPrefix || 'homeassistant';
+        this.availabilityTopic = `${config.prefix}/Availability`;
+
         const options = {
             clientId: config.clientId,
             username: config.user,
             password: config.passwd,
             protocolVersion,
             clean: !isV5,
+            ...(this.haDiscovery ? {
+                will: { topic: this.availabilityTopic, payload: 'offline', qos: 1, retain: true }
+            } : {}),
             ...(isV5 ? {
                 properties: {
                     sessionExpiryInterval: 60 * 60,
@@ -36,6 +44,7 @@ class Mqtt extends EventEmitter {
             .on('connect', async () => {
                 hasConnected = true;
                 this.emit('connected', `MQTT v${protocolVersion} connected.`);
+                if (this.haDiscovery) this.publishRetained(this.availabilityTopic, 'online').catch(() => { });
 
                 try {
                     await new Promise((resolve, reject) => {
@@ -95,6 +104,24 @@ class Mqtt extends EventEmitter {
         });
     }
 
+    publishRetained(fullTopic, payload) {
+        return new Promise((resolve, reject) => {
+            // + and # are wildcards, the client would never complete such a publish
+            if (/[+#]/.test(fullTopic)) {
+                return reject(new Error(`Invalid topic ${fullTopic}, the name or prefix must not contain + or #`));
+            }
+
+            this.mqttClient.publish(fullTopic, payload, { qos: 1, retain: true }, (error) => {
+                if (error) {
+                    if (this.config.logWarn) this.emit('warn', `MQTT Publish error: ${error.message}`);
+                    return reject(error);
+                }
+                if (this.config.logDebug) this.emit('debug', `MQTT Publish retained Topic: ${fullTopic}, Payload: ${payload}`);
+                resolve();
+            });
+        });
+    }
+
     publish(topic, message) {
         return new Promise((resolve, reject) => {
             const fullTopic = `${this.config.prefix}/${topic}`;

package/src/xboxdevice.js

@@ -2,6 +2,7 @@ import EventEmitter from 'events';
 import XboxWebApi from './webApi/xboxwebapi.js';
 import XboxLocalApi from './localApi/xboxlocalapi.js';
 import Functions from './functions.js';
+import HaDiscovery from './hadiscovery.js';
 import { DefaultInputs, WebApi } from './constants.js';
 
 let Accessory, Characteristic, Service, Categories, Encode, AccessoryUUID;
@@ -100,10 +101,18 @@ class XboxDevice extends EventEmitter {
                             break;
                     }
                     break;
-                case 'App':
+                case 'App': {
+                    // Known inputs (also Dashboard, Settings, Television...) are switched the same way as from HomeKit
+                    const input = this.inputsServices?.find(i => i.oneStoreProductId === value);
+                    if (input) {
+                        await this.setInput(input);
+                        set = true;
+                        break;
+                    }
                     const payload = [{ 'oneStoreProductId': value }];
                     set = await this.xboxWebApi.send('Shell', 'ActivateApplicationWithOneStoreProductId', payload);
                     break;
+                }
                 case 'Volume':
                     switch (value) {
                         case 'up':
@@ -316,6 +325,7 @@ class XboxDevice extends EventEmitter {
 
             // Only one time run
             if (updated) await this.displayOrder();
+            if (updated) this.haPublishConfig();
 
             return true;
         } catch (error) {
@@ -991,6 +1001,64 @@ class XboxDevice extends EventEmitter {
         };
     }
 
+    //home assistant discovery
+    async setupHaDiscovery() {
+        if (!this.mqttConnected || !this.mqtt.haDiscovery) return;
+
+        try {
+            this.ha = new HaDiscovery(this.mqtt1, {
+                objectId: `xbox_${this.liveId}`,
+                name: this.name,
+                deviceClass: 'receiver',
+                device: {
+                    manufacturer: 'Microsoft',
+                    model: this.modelName ?? this.savedInfo?.modelName,
+                    sw_version: this.savedInfo?.firmwareRevision
+                },
+                commands: {
+                    power: { key: 'Power' },
+                    // The console can only step the volume
+                    volume_step: { key: 'Volume', up: 'up', down: 'down' },
+                    mute: { key: 'Mute' },
+                    source: { key: 'App' },
+                    play_pause: { key: 'RcControl', value: 'playPause' }
+                }
+            });
+            await this.haPublishConfig();
+        } catch (error) {
+            if (this.logWarn) this.emit('warn', `HA Discovery setup error: ${error}`);
+        }
+    }
+
+    async haPublishConfig() {
+        if (!this.ha) return;
+
+        try {
+            const sources = (this.inputsServices ?? []).map(input => ({ id: input.oneStoreProductId, name: input.name }));
+            await this.ha.publishConfig({ sources });
+            await this.haUpdateState();
+        } catch (error) {
+            if (this.logWarn) this.emit('warn', `HA Discovery publish error: ${error}`);
+        }
+    }
+
+    async haUpdateState() {
+        if (!this.ha) return;
+
+        try {
+            const input = this.inputsServices?.find(input => input.identifier === this.inputIdentifier);
+            await this.ha.updateState({
+                power: this.power,
+                state: this.power ? (this.playState ? 'playing' : 'on') : 'off',
+                muted: typeof this.mute === 'boolean' ? this.mute : undefined,
+                source: input?.oneStoreProductId,
+                app_name: input?.name ?? ''
+            });
+        } catch (error) {
+            if (this.logWarn) this.emit('warn', `HA Discovery state error: ${error}`);
+        }
+    }
+
     //start
     async start() {
         try {
@@ -1022,6 +1090,7 @@ class XboxDevice extends EventEmitter {
                         })
                         .on('stateChanged', (power) => {
                             this.power = power;
+                            this.haUpdateState();
 
                             this.televisionService?.updateCharacteristic(Characteristic.Active, power);
 
@@ -1179,6 +1248,7 @@ class XboxDevice extends EventEmitter {
                     this.mute = mute;
                     this.screenSaver = screenSaver;
                     this.playState = playState;
+                    this.haUpdateState();
                     if (this.logInfo) {
                         const name = input ? input.name : reference;
                         const productId = input ? input.oneStoreProductId : reference;
@@ -1213,6 +1283,7 @@ class XboxDevice extends EventEmitter {
 
             // Prepare accessory
             const accessory = await this.prepareAccessory();
+            this.setupHaDiscovery();
             return accessory;
         } catch (error) {
             throw new Error(`Start error: ${error}`);