Nintendo Parental Controls smart home integration, free and open source
Nintendo Switch play time: daily limit, bonus time, current game, alerts and buttons.
Published by guim31
- Devices
- Version 1.0.1
- Requires Gladys >=5.1.0
- ★ 0
Overview
This integration brings the Nintendo Switch Parental Controls into Gladys, like the "Nintendo Switch Parental Controls" smartphone app: for each console linked to your Nintendo account, today's play time, the daily limit, the time remaining, the bonus time, the current or last game, whether someone is playing, and what happens at the limit (an alarm only, or the software suspended).
It also acts like the app: change the daily limit, add bonus time for today, suspend the software at the limit. Scene triggers let Gladys react when a child starts playing, when the limit is almost reached or when it is exceeded, and a dashboard widget shows the consoles with "+15 min" and "Suspend" buttons.
It works for the Nintendo Switch, the Nintendo Switch Lite, the Nintendo Switch OLED and the Nintendo Switch 2, through Nintendo's servers (the console needs Internet access). It uses the same private API as the app, documented by the pynintendoparental library that Home Assistant uses. This integration is not affiliated with Nintendo: Nintendo Switch is a trademark of Nintendo.
Developed without the hardware: no console and no Nintendo account were at hand, everything was built on real answers published with pynintendoparental. Feedback welcome, on the forum or in the GitHub issues.
Prerequisites
- Gladys Assistant 5.1.0 or later.
- A Nintendo account (the parent's), with the console(s) already paired in the Nintendo Switch Parental Controls app (set it up).
- A computer browser for the sign-in step (the link to copy is easier to get there than on a phone).
Configuration
In Gladys, Integrations, Nintendo Parental Controls, Configuration:
- Click Connect next to "Nintendo account": the Nintendo sign-in page opens in a new tab.
- Sign in with the parent account used in the Parental Controls app. Your password is typed on nintendo.com only and never goes through Gladys.
- Nintendo shows the account and a red Select this person button. Do not click it: right-click it and choose Copy link address (on a phone: long press, Copy link). The link starts with
npf54789befb391a838://auth#. - Paste it in Link of "Select this person" and save. The badge turns to connected within a few seconds. The link works once and only a few minutes: if it is refused, click Connect again and paste the new link quickly.
| Field | Content |
|---|---|
| Nintendo account | The Connect button. |
| Link of "Select this person" | The copied link. Used once: the integration then keeps its own Nintendo session in its data volume, never in the logs. |
| Refresh interval | 1, 2 or 5 minutes (1 minute by default). |
| Language of the feature names | English, French (default), German or Spanish: the names of the features, the limit list and the texts sent to scenes. |
Then open the Discovery tab and add the consoles you want as devices.
Devices
One device per console, named after its name in the app and its model, for example "Living room (Nintendo Switch 2)".
| Feature | Type | Content |
|---|---|---|
| Play time today | Duration (minutes) | Total play time of the console today, every player added up. |
| Time remaining | Duration (minutes) | What the limit plus the bonus leaves, or the time until the bedtime alarm if it comes first. Without limit nor bedtime: the time until midnight, like in the app. |
| Daily limit | List (command) | "No limit", or 15 minutes to 6 hours by 15 minutes, the choices of the app. In the "same every day" mode, it changes every day; in the "per day" mode, only this day of the week, like the app. |
| Bonus time today | Duration (minutes) | Extra time granted today, 0 without. "No limit today" shows as 1440. |
| Current or last game | Text | The game whose play time grew last, or the last game played. |
| Playing | Binary | 1 while the play time keeps growing. See "Limits": known a few minutes late. |
| Online | Binary | 1 when the console sent its play data in the last 20 minutes, or is playing. |
| Suspend software at limit | Switch (command) | On: the software is suspended when the limit is reached. Off: an alarm only. |
The two commands are parental settings, like in the app: they never unlock anything a parent did not choose. Note that any Gladys user allowed to control devices (or a voice assistant linked to Gladys) can use them: keep the console devices out of the rooms shared with children if needed.
Widget
The Nintendo Switch widget shows, for the console chosen in its settings (or the only one of the account): the play time, the time remaining and the limit, the current or last game, the mode at the limit, and three buttons, each asking for a confirmation:
- +15 min: 15 minutes of bonus for today;
- Alarm only and Suspend: what happens at the limit, the current one marked by a check.
Once a bonus is granted for the day, Nintendo refuses any change of the mode or of the limit until the next day: the widget says so instead of the mode buttons. Without a console chosen and with several consoles, the widget lists them all (play time / limit), without buttons.
Scene triggers
Each one can be narrowed to one console, and passes the console name and the game to the scene.
- Starts playing: the play time of the console starts growing again (a new session after a break of more than 20 minutes). An optional filter keeps one game (exact name, as in the app). Known a few minutes late (see "Limits").
- Limit almost reached: while someone plays, the time remaining before the limit or the bedtime alarm drops to 30, 15, 10 or 5 minutes (chosen in the trigger). Fires once per crossing; a bonus or a higher limit re-arms it.
- Limit exceeded: the play time of the day reaches the daily limit plus the bonus. Once per day, again after a bonus is used up.
The first reading after a start of the integration, and the start of a new day, only set the reference: no event.
Scene actions
- Add bonus time: 5, 10, 15 or 30 minutes for today, like the app. Gives the bonus of the day and the time remaining to the next steps. Nintendo refuses it past bedtime or when the day cannot be extended any more: the scene action then fails with the reason.
- Set the daily limit: "No limit" or 15 minutes to 6 hours, written where the app writes it (every day, or this day of the week in the per-day mode).
Once a bonus is granted for the day, Nintendo refuses a new limit until the next day: the scene action then fails with the reason.
Configuration actions
- Check the connection: reads the consoles of the account now and lists them, or says what is wrong.
- Sign out of Nintendo: deletes the Nintendo session kept by the integration. Connect again to use it.
Scene examples
- Warn before the end: trigger "Limit almost reached", 10 minutes, the living room console → announce "10 minutes left on the Switch" on the speaker of the living room.
- The limit is over: trigger "Limit exceeded" → send a message to the parents, and set "Suspend software at limit" to on for the next days.
- Homework first: trigger "Starts playing" on a weekday before 17:00 → send a notification to the parents with the game (
console_name,gamevariables). - Reward: when a chore is marked done in Gladys → scene action "Add bonus time", 15 minutes.
Refresh and Nintendo quotas
The integration asks Nintendo by itself at the chosen interval (it does not depend on the Gladys poll): per console, two requests per refresh (today's summaries and the settings), plus the list of consoles every 30 minutes and a new access token about every 10 minutes. With one console and the default interval, about 2 requests per minute, the pace of the Home Assistant integration.
Nintendo publishes no quota for this private API; when it answers "too many requests" (HTTP 429), the integration pauses 5 minutes. The data are only as fresh as the console's own reports: a console uploads its play time every few minutes, so a faster interval does not bring faster data.
The API is the one of the official app, used here the same way, for your own account only. Nintendo may change it at any time: if it asks for a newer app version, the Configuration screen says so and an update of the integration is needed.
Troubleshooting
- "The pasted text is not the link…": copy the link address of the red "Select this person" button, not the address of the page.
- "Nintendo refused the link": the link was already used or is too old (a few minutes). Click Connect again and paste the new link quickly.
- "This link comes from another sign-in": the link was copied after another click on Connect, or from another tool. Click Connect again and use the new page.
- "Nintendo ended the session": the password was changed, or the account was signed out of every device. Connect again.
- "No console is linked": pair the console in the Nintendo Switch Parental Controls app first.
- Playing time does not move: the console must be connected to the Internet; it reports its play time every few minutes.
- Logs: in Gladys, the integration page, Logs. Set the
LOG_LEVELvariable todebugto see each refresh. No token is ever written there.
Limits
- Developed without the hardware: every answer of Nintendo comes from the published tests of pynintendoparental. Feedback welcome.
- Playing, Starts playing and the current game are deduced from the play time growing: Nintendo publishes no "playing now" information. They are known a few minutes late, and a game played less than a minute may not show.
- Online means "sent play data in the last 20 minutes": Nintendo gives no live presence of the console.
- The bedtime alarm and its end, the per-day settings, the content restrictions, the PIN and the monthly reports are not exposed: change them in the app.
- When a bonus is granted for the day, Nintendo refuses any change of the limit or of the mode until the next day.
- One Nintendo account per integration.
Configuration settings
These are the settings Nintendo Parental Controls asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Connect your Nintendo account | section | No | Click Connect and sign in with the parent account of the Parental Controls app. Then right-click the red "Select this person" button, copy the link address and paste it below. Your password never goes through Gladys. |
| Nintendo account | account_link | No | Opens the Nintendo sign-in page. |
| Link of "Select this person" | secret | No | Starts with npf54789befb391a838://auth. Used once: the integration then keeps its own session. |
| Refresh interval | select | No | How often Nintendo is asked for the play time. The console itself reports every few minutes. |
| Language of the feature names | select | No | Also used for the game titles and the texts sent to scenes. |
How to install Nintendo Parental Controls in Gladys
- In Gladys, open Integrations: Nintendo Parental Controls appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/guim31/gladys-nintendo-parental:1.0.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/guim31/gladys-nintendo-parental.
Nintendo Parental Controls requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Nintendo Parental Controls is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation