Edit Infobox Switch Homebrews: Switch Assistant

You do not have permission to edit this page, for the following reason:

The action you have requested is limited to users in one of the groups: Users, Administrators.

Title:
Image:	Upload file
Description:
Author(s):
Last Updated:
Contributor(s):
Ported by:
Type:
Version:
License:
Language(s):
Format:
Download:
Download Raw:
Website:
Source:
Discussion:
Donation:

Free text:

{{#seo: |title=Switch Homebrew Apps (System Tools) - GameBrew |title_mode=append |image=SwitchAssistant.png |image_alt=Switch Assistant }} Switch Assistant connects the Nintendo Switch to Home Assistant through MQTT. Once configured, it publishes console sensors to Home Assistant and shows Home Assistant popup notifications directly over the game, without opening Tesla Menu. The project installs three components: {| class="wikitable" ! Component ! Purpose |- | <code>switch-ha.nro</code> | Homebrew app used for configuration, connection tests, and automatic installation. |- | Atmosphere sysmodule | Background process that publishes sensors and receives MQTT commands. |- | Notification overlay | Shows Home Assistant popups over the currently running game. |} The <code>.nro</code> app is only used for setup and configuration. After rebooting, the sysmodule handles the background MQTT work. == Features == * Shows battery, charging state, temperature, brightness, volume, and connected controllers in Home Assistant. * Reports whether a game is running and publishes the current game Title ID. * Exposes reboot and shutdown buttons in Home Assistant. * Sends Home Assistant popup notifications to the Switch. * Provides a simple Homebrew configuration app on the console. * Uses MQTT Discovery so entities appear automatically in Home Assistant. * Live screen streaming to Home Assistant via RTSP. == Installation == === Requirements === * Nintendo Switch running Atmosphere. * Working Homebrew Menu. * Home Assistant already installed. * An MQTT broker reachable from the Switch, such as Mosquitto. * A network where the Switch and MQTT broker can communicate with each other. The sysmodule supports plain TCP MQTT, usually on port <code>1883</code>. It does not support TLS on <code>8883</code>, MQTT over WebSocket, or mDNS hostnames such as <code>homeassistant.local</code> for the MQTT broker. === Quick installation === # Download <code>switch-ha.nro</code> from the [https://github.com/ErSeraph/switch-assistant/releases latest release]. # Copy the file to the SD card: #:<syntaxhighlight lang="text">sdmc:/switch/switch-ha/switch-ha.nro</syntaxhighlight> # Launch <code>Switch Assistant</code> from the Homebrew Menu. # On first launch, the app creates the required folders and installs: #:<syntaxhighlight lang="text">sdmc:/atmosphere/contents/00FF000053484101 sdmc:/atmosphere/contents/00FF000053484102 sdmc:/switch/switch-ha/switch-ha-overlay.ovl sdmc:/switch/switch-ha/config.ini</syntaxhighlight> # Enter the Home Assistant and MQTT settings. # Press <code>Y</code> to test the connection. # Press <code>-</code> to reboot the console. After the reboot, Home Assistant should automatically discover the new MQTT entities. On the main screen, fill in the following fields: {| class="wikitable" ! Field ! Example ! Notes |- | <code>HA URL</code> | <code>http://192.168.1.10:8123</code> | Home Assistant URL. |- | <code>HA Token</code> | Long-lived token | Home Assistant long-lived access token. |- | <code>MQTT Host IP</code> | <code>192.168.1.10</code> | Use the broker IP address, not <code>homeassistant.local</code>. |- | <code>MQTT Port</code> | <code>1883</code> | Do not use <code>8123</code>; that is the Home Assistant web port. |- | <code>MQTT Username</code> | <code>mqtt_user</code> | MQTT broker username. |- | <code>MQTT Password</code> | <code>password</code> | MQTT broker password. |- | <code>Discovery</code> | <code>homeassistant</code> | Standard MQTT Discovery prefix. |- | <code>Name</code> | <code>Nintendo Switch</code> | Device name shown in Home Assistant. |- | <code>Client ID</code> | <code>switch-ha-xxxxxxxx</code> | Generated automatically, editable if needed. |- | <code>Boot Delay</code> | <code>0</code> | Seconds to wait before the sysmodule starts system services. Use only if the setup crashes during boot. |- | <code>Notifications</code> | <code>YES</code> | Enabled by default. Disable and reboot if the notification overlay crashes the console. |} If entering the Home Assistant token on the console is inconvenient, open the app once, then edit: <syntaxhighlight lang="text"> sdmc:/switch/switch-ha/config.ini </syntaxhighlight> After changing any configuration value, reboot the console so the sysmodule reloads the file. With MQTT Discovery enabled, Switch Assistant publishes discovery payloads under the configured prefix, usually: <syntaxhighlight lang="text"> homeassistant </syntaxhighlight> Console states are published under: <syntaxhighlight lang="text"> switch_ha//... </syntaxhighlight> Main entities: {| class="wikitable" ! Type ! Entities |- | Battery sensors | Level, charging state, charger type, voltage, temperature, battery health. |- | Console sensors | Brightness, screen, volume, audio output target. |- | Game | Game running, current Title ID. |- | Controllers | Player count, Player 1-8 controller type. |- | Commands | Reboot, shutdown. |- | Notifications | Home Assistant popup on the Switch. |} The console supports live streaming while in-game. To enable it, create a Generic Camera using the stream URL found in the entity Screen Stream URL. SSL verification should be disabled in the camera configuration for it to work correctly. Home Assistant creates a notify entity with a name similar to: <syntaxhighlight lang="text"> notify.nintendo_switch_popup_notification </syntaxhighlight> Example Home Assistant action: <syntaxhighlight lang="yaml"> action: notify.send_message target: entity_id: notify.nintendo_switch_popup_notification data: message: "Laundry finished" </syntaxhighlight> The MQTT notify integration currently forwards the message body to Switch Assistant. Home Assistant's <code>title</code> field is not included in that MQTT payload, so the popup title defaults to <code>Home Assistant</code> when using <code>notify.send_message</code>. To send a custom title, publish directly to the popup topic with JSON: <syntaxhighlight lang="yaml"> action: mqtt.publish data: topic: switch_ha//notify/popup payload: '{"title":"Laundry","message":"The washing machine has finished"}' </syntaxhighlight> Alternatively, use a two-line payload where the first line is the title and the second line is the message. The sysmodule writes the latest notification here: <syntaxhighlight lang="text"> sdmc:/switch/switch-ha/notification-current.ini </syntaxhighlight> It keeps a small log here: <syntaxhighlight lang="text"> sdmc:/switch/switch-ha/notifications.log </syntaxhighlight> The overlay reads these files and shows the popup automatically. == Controls == On the main screen: {| class="wikitable" ! Button ! Action |- | <code>D-Pad</code> | Select a field. |- | <code>A</code> | Edit the selected field. |- | <code>Y</code> | Test Home Assistant and MQTT. |- | <code>-</code> | Reboot the console to apply changes. |- | <code>+</code> | Exit the app. |} == Useful Paths == {| class="wikitable" ! Path ! Contents |- | <code>sdmc:/switch/switch-ha/switch-ha.nro</code> | Homebrew app. |- | <code>sdmc:/switch/switch-ha/config.ini</code> | Configuration. |- | <code>sdmc:/switch/switch-ha/switch-ha-overlay.ovl</code> | Notification overlay. |- | <code>sdmc:/switch/switch-ha/sysmodule.log</code> | Sysmodule log. |- | <code>sdmc:/switch/switch-ha/sysmodule-heartbeat.txt</code> | Sysmodule diagnostic state. |- | <code>sdmc:/switch/switch-ha/notifications.log</code> | Short notification history. |- | <code>sdmc:/atmosphere/contents/00FF000053484101</code> | Switch Assistant sysmodule. |- | <code>sdmc:/atmosphere/contents/00FF000053484102</code> | Switch Assistant overlay loader. |} == Troubleshooting == === Home Assistant does not show any entities === * Make sure the MQTT integration is enabled in Home Assistant. * Check that <code>Discovery</code> is set to <code>homeassistant</code>. * Press <code>Y</code> in the app and confirm that the MQTT test succeeds. * Reboot the console after saving the configuration. === Wrong MQTT port === If a message like the following appears: <syntaxhighlight lang="text"> Port 8123 is HA HTTP; MQTT is usually 1883 </syntaxhighlight> The Home Assistant web port is being used. MQTT usually runs on <code>1883</code>. === TCP failed or broker/port closed === The Switch reached the broker IP, but the MQTT port is closed or not exposed. Check that: * Mosquitto or the MQTT broker is running. * Port <code>1883</code> is exposed on the LAN. * Firewall, VLAN, or client isolation rules are not blocking the Switch. * The configured IP address is the MQTT broker address. === The test works, but sensors do not appear === The test runs from the <code>.nro</code> app. Sensors are published by the sysmodule only after rebooting. Press <code>-</code> in the app or reboot the console manually. === Console crashes during boot === Some custom Atmosphere packs may crash if boot2 sysmodules start system services too early or if the notification overlay is not compatible with the custom CFW. If the console fails to boot after installing Switch Assistant: # Power off the console. # Put the SD card in a PC. # Remove these folders if they exist: #:<syntaxhighlight lang="text">sdmc:/atmosphere/contents/00FF000053484101 sdmc:/atmosphere/contents/00FF000053484102</syntaxhighlight> # Put the SD card back in the console and boot normally. # Launch <code>Switch Assistant</code> from the Homebrew Menu. # Set <code>Notifications</code> to <code>NO</code>. # Press <code>-</code> in the app. If it works, the issue was caused by the notification overlay. Notifications will no longer be usable. If there are still issues, delay the startup of Switch Assistant so the console has enough time to finish its boot routine. Repeat the recovery steps above from 1 to 5, then: # Set <code>Boot Delay</code> to <code>30</code> seconds. # Press <code>-</code> in the app. If the console still crashes, repeat the recovery steps and try a higher value such as <code>60</code> seconds. <code>Boot Delay</code> is saved in: <syntaxhighlight lang="ini"> startup_delay_seconds=30 </syntaxhighlight> The default is <code>0</code>, which keeps startup immediate on standard Atmosphere setups. == Screenshots == {| style="max-width:80%; margin-left:0em;" | https://dlhb.gamebrew.org/switchhomebrews/images/SwitchAssistant-01.gif |} == Changelog == '''v1.5''' * Added a configurable Notifications option to disable notifications if a custom Atmosphere setup is not compatible. '''v1.4''' * Added live screen streaming to Home Assistant via RTSP. * Published a new MQTT entity with the console's RTSP stream URL for easy camera setup. '''v1.3''' * Fixed saved video recordings showing a green screen by excluding the notification overlay from the recording layer stack. * Resolved the current game name from a bundled title database. * Installed the bundled title database alongside the Switch Assistant config files. '''v1.2''' * Fixed Switch Assistant title IDs to avoid collisions with existing homebrew sysmodules. * Safely cleaned up old Switch Assistant installs only when identified by project markers. * Improved notification text handling for Unicode payloads. * Prevented old notifications from being shown again on boot. * Added a configurable Boot Delay option for custom Atmosphere packs that crash when boot2 sysmodules start system services too early. '''v1.1''' * Published active game Title ID and app running state sensors. * Added Home Assistant popup notifications. '''v1.0''' * Initial release. == Credits == The overlay loader is derived from the ISC-licensed <code>nx-ovlloader</code> project and chainloads the Switch Assistant overlay directly instead of Tesla Menu. == External links == * GitHub - https://github.com/ErSeraph/switch-assistant * HB-App - https://hb-app.store/switch/SwitchAssistant

Summary:

Cancel