HA Control Logo

HA Control Documentation

Get started

Topics

Automatic Token Setup

Seamlessly connect HA Control to your Home Assistant with our streamlined token setup process. No more typing long access tokens on your TV!

  • 1

    Generate a Long-Lived Access Token

    Log in to your Home Assistant instance and click your user profile (located in the lower left corner).

    Go to the Security tab in your profile and scroll down to the "Long-Lived Access Tokens" section.

    Click on "Create Token", provide a descriptive name (e.g., "HA Control"), and confirm.

    Copy the generated token as it won't be shown again.

  • 2

    Create Token File

    Create a file in your Home Assistant's www folder (or in /config/ if the www folder doesn't exist).

    In the app settings, the required filename will be displayed; it will look something like 12DA-S93H.json.

    Create this file and paste the following JSON structure, replacing YOUR_TOKEN with your generated token:

    copy 
    {"ha-token": "YOUR_TOKEN"}
  • 3

    Retrieve Token in the App

    Press "Retrieve Token" in the app, and the token will be automatically loaded.

    IMPORTANT: For security reasons, delete the token file from your www folder after the app has imported it.

Groups Configuration

Organize your smart home devices into intuitive groups for effortless control on your TV. Create custom tabs that perfectly match your home's layout and your daily routines.

copy 
group:
  hacontrol_01:
    name: Living Room
    icon: sf:sofa.fill
    entities:
      - light.living_room_ceiling
      - light.living_room_floor_lamp
      - switch.tv_power
      - media_player.living_room_tv
      - cover.living_room_blinds
      - climate.living_room_thermostat

  hacontrol_02:
    name: Kitchen & Dining
    icon: sf:fork.knife
    entities:
      - light.kitchen_main
      - light.dining_table
      - switch.coffee_machine
      - fan.kitchen_hood
      - sensor.kitchen_temperature
      - binary_sensor.kitchen_door

  hacontrol_03:
    name: Scenes & Automations
    icon: sf:wand.and.stars
    entities:
      - scene.movie_night
      - scene.dinner_time
      - scene.good_morning
      - scene.good_night
      - input_boolean.vacation_mode
      - automation.turn_off_lights
  • 1

    Create Groups in configuration.yaml

    Add the group configuration to your configuration.yaml file or to a separate groups.yaml file (if you're using split configuration).

  • 2

    Restart Home Assistant

    NOTICE:If you have never created any groups before, Home Assistant must be restarted for the changes to take effect.

    You can check whether the groups are recognized by navigating to Developer Tools → States in Home Assistant and searching for the group entity IDs (e.g., group.hacontrol_01).

  • 3

    Configure in the App

    Once your groups are set up and recognized by Home Assistant, they will automatically appear in the HA Control app.

Supported Domains

Control your entire smart home right from your couch using the Apple TV Remote – lights, switch, sensor, and more, all on your big screen.

Domain Supported Features
light On/Off
switch On/Off
input_boolean On/Off
scene Activation
script Execution
automation Activation
climate Mode
fan On/Off
cover Open/Close
media_player Play/Pause
sensor Value, History View
binary_sensor State
input_select Select next (more in develeopment)
select Select next (more in develeopment)
input_number State
number State
input_text State
text State
button Press
input_button Press
alarm_control_panel Arm/Disarm/Away/Night/Vacation/Trigger/Bypass & Status
lock Lock/Unlock
weather Condition, Temperature
datetime State
siren On/Off
person State
device_tracker State

Troubleshooting

Smart fixes for smart homes. Troubleshoot quickly and get back to what matters

  • Connection Issues

    NOTICE: Your Apple TV must be able to reach your Home Assistant instance – via local network, Nabu Casa, VPN, or another connection method.

    • Double-check your URL format: Include the protocol (http:// or https://) and correct port number
    • Test Home Assistant access from another device like your smartphone to confirm server availability

  • Token Authentication Problems

    NOTICE:If you just created the www folder for the first time, restart Home Assistant before attempting to use the token file.

    • Create a fresh long-lived access token in Home Assistant (Profile → Long-Lived Access Tokens)
    • Verify your JSON syntax is exactly: {"ha-token": "YOUR_TOKEN"} with no extra spaces or characters

  • Groups Not Appearing

    • Double-check spelling and formatting - group names must match hacontrol_01 to hacontrol_03 exactly
    • After editing groups.yaml, use the “Reload Groups” function in Home Assistant’s Developer Tools. A full restart is only needed if reloading doesn’t apply the changes.

Nice to Know

Helpful tips and background info to make your Home Assistant experience even smoother.

  • Dynamic Groups

    • You can create dynamic groups based on conditions like time of day, presence, or other states. This keeps your dashboard clean and perfectly tailored to your current needs.