Documentation — Phone Assistant Link

The basics

One device per app group

When you create an app group in Phone Assistant Link — say Social — the integration adds a Home Assistant device named <you> — Social with a handful of entities beneath it. Individual apps you track on their own appear under a second device, <you> — Screen Time.

How your entity IDs are built

Entity IDs follow <domain>.<you>_<group>_<suffix>, lower-cased with spaces turned into underscores. For the user greg and a group called Social, the usage sensor is:

sensor.greg_social_used_today

Replace greg and social in the examples below with your own name and group. The Dashboard tiles page fills these in for you automatically.

Where usage comes from

Usage is measured on your iPhone with Apple's Screen Time framework and delivered to your Home Assistant. The number is a grounded estimate that updates in roughly 15-minute steps (the precision_minutes attribute) and sharpens as it approaches a limit — reliable coarse minutes rather than an exact stopwatch. Exact minute-by-minute Screen Time detail never leaves the device.

Group entities

What each app group exposes

Using the user greg and a group named Social as the example:

Entity	What it holds
`sensor.greg_social_used_today`	Minutes used today across the apps in the group. Duration sensor; resets daily. Attribute: `precision_minutes`.
`binary_sensor.greg_social_limit_reached`	`on` once today's usage has hit the daily limit, otherwise `off`.
`sensor.greg_social_restriction_status`	A readable status for the group — see Restriction status below.
`sensor.greg_social_extensions_used_today`	How many time-extensions have been granted for the group today.
`switch.greg_social_blocked`	Controllable. Turn on to block the group's apps from Home Assistant; turn off to unblock.
`number.greg_social_daily_usage_limit`	Controllable. The daily limit in minutes (0–1440, in 15-minute steps).
`number.greg_social_extensions_allowed_per_day`	Controllable. How many extensions the group may use per day (0–20).

Controllable entities can be changed from Home Assistant — a dashboard toggle, a script or an automation — and the change is applied on the phone. The others are read-only reflections of what the app measured.

Restriction status

One sensor that says where a group stands

sensor.greg_social_restriction_status summarises the group in a single readable state, handy for dashboards and voice. Its possible values are:

AllowedNo block or limit in effect Daily Limit ReachedToday's usage hit the limit Blocked by Home AssistantThe Blocked switch is on ExtendedA time-extension is currently active Temporarily BlockedA temporary block override is running Temporarily AllowedA temporary allow override is running

Attributes

Attribute	What it contains
`effective_blocked`	Whether the apps are actually blocked right now, after limits and overrides are taken into account.
`temporary_until`	When a temporary override ends, as a timestamp — or empty when none is active.

{{ states('sensor.greg_social_restriction_status') }}
{{ state_attr('sensor.greg_social_restriction_status', 'effective_blocked') }}

Controls

Change limits and blocking from Home Assistant

Three entities per group can be driven from Home Assistant, so your smart home can shape phone access — not just watch it.

Block on demand

switch.greg_social_blocked — flip it on to block the group immediately (bedtime, homework, focus), off to release it.

Set the daily limit

number.greg_social_daily_usage_limit — set the day's allowance in minutes. Lower it on school nights, raise it at the weekend.

Allow extensions

number.greg_social_extensions_allowed_per_day — how many top-ups the group may earn in a day.

Home Assistant controlPhone Assistant LinkScreen Time on the phone

# Block the Social group from an automation or script
service: switch.turn_on
target:
  entity_id: switch.greg_social_blocked

# Tighten the limit to 30 minutes
service: number.set_value
target:
  entity_id: number.greg_social_daily_usage_limit
data:
  value: 30

Block modes

Choose how a block feels: Shield or Vanish

Every app group has a block mode, chosen per group in the app under Block mode. It decides what happens on the phone whenever the group is blocked — whether that block comes from the switch.<you>_<group>_blocked switch, a reached daily limit, a temporary override or a schedule.

Shield

The default. Apple's block screen covers the group's apps when you open them — the icons stay on your Home Screen, just behind a shield.

Vanish

The apps disappear from your Home Screen and App Library entirely while the group is blocked, then reappear the moment it's allowed again.

Good to know: Vanish can only hide individual apps — any whole categories or websites in a group still use the Shield screen. The block mode is a phone-side choice, not a Home Assistant entity, but it applies to every block, including ones triggered from Home Assistant. So a bedtime automation that turns on switch.greg_social_blocked makes a Vanish group's apps quietly disappear until morning.

Shortcuts & Siri

Block a group from Shortcuts

Phone Assistant Link ships an App Shortcut so you can block or unblock a specific group straight from the Shortcuts app, a Personal Automation or Siri — no Home Assistant round-trip needed.

The action

Block or Unblock a Group takes two choices: the action (Block or Unblock) and the group, picked from the groups you've created.

Runs in the background

The change is applied to Screen Time on the device without opening the app, so it's instant and works inside automations.

Respects the block mode

Blocking through a shortcut uses the group's own Shield or Vanish mode.

Ask Siri something like "Block a group in Phone Assistant Link," or add the action to a Personal Automation — for example, block your Social group automatically when a Focus turns on or when you arrive at work.

PAL Pro: controlling groups from Shortcuts is part of PAL Pro, alongside Home Assistant automation and unlimited groups. A shortcut-driven block takes effect on the phone immediately; the matching Home Assistant entity catches up the next time the app runs or wakes.

Screen Time items

Track individual apps too

Apps you follow on their own — outside of a group — appear under the <you> — Screen Time device as a single duration sensor each:

Example sensor.greg_instagram_time · 42 min

These are read-only minutes used today, with the same precision_minutes behaviour as group usage and a resets: daily attribute. They're perfect for a glance card of "where the day went".

Automations

Do something when a limit lands

Because the limit is a binary_sensor, automations are straightforward. Trigger on it turning on to notify, dim lights, pause the TV — whatever fits your home.

alias: Notify when Social limit is reached
triggers:
  - trigger: state
    entity_id: binary_sensor.greg_social_limit_reached
    to: "on"
conditions: []
actions:
  - action: notify.mobile_app_greg_iphone
    data:
      title: Screen Time
      message: "The Social daily limit has been reached."
mode: single

Tip: to enforce as well as notify, add a second action that turns on switch.greg_social_blocked. To automatically block a group every night, schedule a time trigger that turns the switch on and a morning one that turns it off.

Get ready-made dashboards Open the setup guide

Understand your Screen Time entities