With our URL Scheme, you can create links to content in Controller for HomeKit. It’s also possible to execute Scenes and Workflows with a link.
After installing Controller for HomeKit on a device, all links starting with
controllerforhomekit:// will open the app.
You can open specific screens from the main menu like this:
controllerforhomekit://v1/cameras controllerforhomekit://v1/accessories controllerforhomekit://v1/scenes
By default, all links refer to the currently selected Home in Controller. However, you can append a URL parameter ‘home’ to open a specific Home:
You can open specific detail views, like one particular Scene, by appending its name and including a Home name:
You can open a view with a Smart Folder pre-selected by using the URL parameter ‘folder’:
For Scenes and Workflows, you can use the parameter ‘action’ to make the app execute them.
Tip: When you create a Widget in Controller for HomeKit, you can touch and hold an action to copy the URL it uses to the clipboard.
The general pattern for links to Controller looks like this:
Currently, the only valid value for api-version is ‘v1’.
The view parameter allows you to specify the views you can access from the app’s main menu and zones. Valid values are:
cameras, accessories, scenes, automations, workflows, rooms, zones, backups, logs, maintenance, serviceGroups, widgets, watchScreens, nfcTags, settings
The target parameter lets you specify a particular detail view in one of the main views. E.g., a specific Scene. You can set a target for the following views:
cameras, accessories, scenes, automations, workflows, rooms, zones, widgets
The value for the target is the name of the object you want to open. If the name contains a space or special characters, you need to percent-encode them. See Special Characters.
When you specify a target, you always need to provide a home.
To open the workflow “Check Windows” in the Home “My Home” the URL needs to look like this:
The home parameter is optional, but it becomes mandatory when a target or folder is specified. It defines what Home Controller will select. If you provide no Home, the currently selected Home remains selected.
You need to percent-encode spaces and special characters in the Home name. See Special Characters.
The folder parameter lets you open a main view with a selected Smart Folder. You can specify a folder for the following views:
accessories, scenes, automations, logs
You need to percent-encode spaces and special characters in the folder name. See Special Characters.
When you specify a folder, you always need to provide a home.
To open the Smart Folder “Motion Sensors” in the Home “My Home” the URL needs to look like this:
The action parameter allows you to tell Controller for HomKit what action the URL should trigger. The app will open the URL target if no action is specified.
There are currently two options supported:
The action execute can only be used if the target parameter is a Scene or a Workflow. It will apply the Scene or run the Workflow immediately instead of opening its detail view.
URLs cannot contain spaces or special characters like exclamation marks, question marks, or ampersands. If your target, folder, or Home includes a special character, you must percent-encode it.
For example, you must replace each space with %20. That means if you want to open a Scene ‘Late Night’ in your Home ‘My Home’, the URL needs to look like this:
You can learn more about percent-encoding and the codes for different characters here: https://www.w3schools.com/tags/ref_urlencode.ASP