homebridge-xbox-tv 4.1.24 → 4.2.0

package/CHANGELOG.md

@@ -18,6 +18,24 @@ 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
+
+- fix: MQTT client had `protocolVersion: 5` hardcoded, so brokers that only support MQTT 3.1.1 (e.g. the ioBroker MQTT adapter) accepted the TCP connection, failed the handshake, and got disconnected every second forever, with nothing published and no error logged. Added a `Protocol Version` option (5.0 / 3.1.1) in the MQTT section, and a one-time warning if no successful connection is established within 30 seconds
+- readme update
+- sample config update
+
 ## [4.1.24] - (23.09.2026)
 
 ### Added
@@ -25,6 +43,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - optional RESTful access `Token`. When set, every request (GET and POST) must send the header `Authorization: Bearer <token>`, otherwise the server responds `401`. Leaving it empty keeps the previous behaviour, so existing configs keep working
 - readme update
 
+## [4.1.23] - (13.09.2026)
+
+### Changes
+
+- bump dependencies
+
 ## [4.1.22] - (18.07.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>
@@ -137,6 +137,8 @@
 | `mqtt.port` | Here set the `Port` for MQTT Broker, default 1883. |
 | `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. |
@@ -177,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

@@ -1219,6 +1219,34 @@
 										"functionBody": "return model.devices[arrayIndices].mqtt.enable === true;"
 									}
 								},
+								"protocolVersion": {
+									"title": "Protocol Version",
+									"type": "integer",
+									"default": 5,
+									"oneOf": [
+										{
+											"title": "5.0",
+											"enum": [5]
+										},
+										{
+											"title": "3.1.1",
+											"enum": [4]
+										}
+									],
+									"description": "MQTT protocol version used to connect to the broker. Some brokers (e.g. the ioBroker MQTT adapter) only support 3.1.1 and will silently reject 5.0 connections.",
+									"condition": {
+										"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",
@@ -1472,6 +1500,8 @@
 														"devices[].mqtt.port",
 														"devices[].mqtt.clientId",
 														"devices[].mqtt.prefix",
+														"devices[].mqtt.protocolVersion",
+														"devices[].mqtt.haDiscovery",
 														{
 															"key": "devices[].mqtt.auth",
 															"title": "Authorization",

package/index.js

@@ -156,6 +156,8 @@ class XboxPlatform {
 						port: device.mqtt.port || 1883,
 						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.24",
+  "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

@@ -8,35 +8,56 @@ class Mqtt extends EventEmitter {
 
         const url = `mqtt://${config.host}:${config.port}`;
         const subscribeTopic = `${config.prefix}/Set`;
+        const protocolVersion = config.protocolVersion === 4 ? 4 : 5;
+        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: 5,
-            clean: false,
-            properties: {
-                sessionExpiryInterval: 60 * 60,
-                userProperties: {
-                    source: 'node-client'
+            protocolVersion,
+            clean: !isV5,
+            ...(this.haDiscovery ? {
+                will: { topic: this.availabilityTopic, payload: 'offline', qos: 1, retain: true }
+            } : {}),
+            ...(isV5 ? {
+                properties: {
+                    sessionExpiryInterval: 60 * 60,
+                    userProperties: {
+                        source: 'node-client'
+                    }
                 }
-            }
+            } : {})
         };
 
+        const startTime = Date.now();
+        let hasConnected = false;
+        let warnedStalled = false;
+
         this.mqttClient = connect(url, options)
             .on('connect', async () => {
-                this.emit('connected', 'MQTT v5 connected.');
+                hasConnected = true;
+                this.emit('connected', `MQTT v${protocolVersion} connected.`);
+                if (this.haDiscovery) this.publishRetained(this.availabilityTopic, 'online').catch(() => { });
 
                 try {
                     await new Promise((resolve, reject) => {
                         this.mqttClient.subscribe(subscribeTopic,
                             {
                                 qos: 1,
-                                properties: {
-                                    userProperties: {
-                                        type: 'subscription'
+                                ...(isV5 ? {
+                                    properties: {
+                                        userProperties: {
+                                            type: 'subscription'
+                                        }
                                     }
-                                }
+                                } : {})
                             },
                             (error) => {
                                 if (error) return reject(error);
@@ -69,6 +90,10 @@ class Mqtt extends EventEmitter {
                 if (config.logDebug) this.emit('debug', 'MQTT Reconnecting...');
             })
             .on('close', () => {
+                if (!hasConnected && !warnedStalled && Date.now() - startTime > 30000) {
+                    warnedStalled = true;
+                    this.emit('warn', `MQTT has not connected after 30s of retries using protocol v${protocolVersion}. Check broker address, credentials, and whether the broker supports this MQTT protocol version.`);
+                }
                 if (config.logDebug) this.emit('debug', 'MQTT Connection closed.');
             });
     }
@@ -79,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}`;
@@ -87,13 +130,15 @@ class Mqtt extends EventEmitter {
             this.mqttClient.publish(fullTopic, publishMessage,
                 {
                     qos: 1,
-                    properties: {
-                        contentType: 'application/json',
-                        userProperties: {
-                            source: 'node',
-                            action: 'set'
+                    ...(this.isV5 ? {
+                        properties: {
+                            contentType: 'application/json',
+                            userProperties: {
+                                source: 'node',
+                                action: 'set'
+                            }
                         }
-                    }
+                    } : {})
                 },
                 (error) => {
                     if (error) {

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}`);