URL Scheme
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.
Quick Start
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:
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.
URL Pattern
The general pattern for links to Controller looks like this:
API Version
Currently, the only valid value for api-version is 'v1'.
View
The view parameter allows you to specify the views you can access from the app's main menu and zones. Valid values are:
Target
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:
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:
Home
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.
Folder
The folder parameter lets you open a main view with a selected Smart Folder. You can specify a folder for the following views:
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:
Action
The action parameter allows you to tell Controller for HomeKit 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.
Special Characters
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