@smj0x/homebridge-shortcuts-buttons v3.5.5

Features highlights

• Run your Apple Shortcuts directly from your native Home app (or any HomeKit compatible integration).
• Optionally, choose a custom callback command (even another shortcut) to execute once your shortcut completes (success/failure/cancel), leveraging an integrated x-callback-url server.
• Choose to display your shortcuts buttons as Outlets or Switches.
• All via UI plugin configuration, no other setup required.
• Super fast and light, zero runtime package dependencies.
• Execute shortcuts locally or on a remote macOS machine via SSH

How does it look like

The screenshots below give you an idea of how the end result may look like on an iOS Home app. The different variations of UI depend on the values you choose for the Display buttons as option in the plugin configuration form, and for the Show as single tile / Show as separate tiles option in the Accessory Settings on the Home app.

Bear in mind that in order to obtain a result similar to the screenshots above, you may have to add a few shortcuts buttons in the config first. E.g. by default Apple Home won't display the cute "power on" round button for a single outlet service, rather will display it instead as an actual outlet on the room view and as a switch on the accessory view.

How it works

1. When you tap the button/switch, the plugin executes a command on the machine where Homebridge is running which runs the relevant Apple Shortcut. The button/switch then automatically toggles back off after a moment.

   There are no restrictions on the content of the shortcuts to run, including ones running scripts over SSH on other hosts. The plugin has no role in this, as it only instructs Shortcuts to run them via native url schema.

2. If you left enabled the option Enable Callback Command (see description below), the plugin will inform Shortcuts to give a signal back once the shortcut execution is completed.

   This is done using the x-callback-url standard, which effectively appends to the shortcut execution request the instructions on what to do when it succeds, fails, or is canceled.

3. Once the shortcut has run, Shortcuts will invoke a callback in this plugin, indicating the status of the execution and the result if any. When the plugin receives the callback request it runs the relevant command (either the default callback command or a custom one if provided, see below).

   This is possible because the plugin includes a very light http server running locally within Homebridge, which receives the callback from Shortcuts and determines the next command to run. The two actors in the data flow are independent and communicate only via url schemas; this removes the need for any active polling or scheduled tasks. Also, the plugin's server issues a dedicated single-use authorization token for each interaction with Shortcuts, making it more difficult for things to get messy.

Configuration

Callback command

As mentioned in the configuration documentation above, there are three options available to handle the callback following a shortcut execution:

Default (display notification)

By default, a native notification with a brief summary on the shortcut result is displayed on the host machine running Homebrige (with sound effect Glass for success and Sosumi for failure). The handler for this behaviour is delivered as HomebridgeShortcutsButtons - Notify Shortcut Result.app (which is copied into the /bin directory of the distributed npm package).
For it to run you will have to approve a couple of permissions requests the first time it runs (one to display notifications, one to access shortcuts results in order to print the summary in the notification body).

Custom unix command

If you choose to manually write a custom callback script, everything you input in the command field will be passed over to node child_process.exec, which will try to execute it in a subshell. Your input can be directly some inline code, or it can be code that runs a file on your machine containing a more elaborate script.
The stdout/stderr generated by your command will be propagated onto the top shell (respectively with Logger.debug/error) which is buffered on your Homebridge UI.

Environment variables

In your command you have at your disposal the following environment variables which give you contextual information about the shortcut which triggered the callback:

Shortcut

For some it might be easier to just use another shortcut to handle the actions to perform on completion of the initial shortcuts configured to run on buttons press. You could even have the same shortcut handling its own error status, for example in case of operation that can be retried (and with the input variables provided - see below - it would be easy to distinguish a standard run from a retry one, for instance). Just be wary of infinite loops.
Remember to only insert in the custom command field the shortcut name as it appears in the Shortcuts app, same as for the shortcuts names configured for the homekit buttons above.

When it comes to passing relevant variables to the callback shortcut, the situation it's not as easy as the previous case. Shortcuts only accept one single text input when called via url schema. Luckily, we can encode a dictionary (base_64) of the variables on the server so it can be passed as a single input parameter to the shortcut. Then from there we can decode it and transform it back into a dictionary ready for consumption within the callback shortcut. Here is an example of shortcut with the mentioned steps:

The key point is to add first the Get text from input action, specifying Shortcut Input as source. This will automatically add the Receive block on top. Note that it is perfectly fine and expected to leave the instruction as Receive No input from Nowhere: the text input coming from url schema will still be passed in.
I included in the repository a copy of the same shortcut screenshotted above for your convenience, you can download it here: Demo callback shortcut with input.shortcut, and inspect it or import it into your Shortcuts to have a starting point.

Shortcut input variables

After the decoding of the dictionary, you'll have your clear variables to access within your shortcut actions; the typing is the following (similar to the environment variables provided to the custom callback command, except for having to replace undefined - unsupported by shortcuts dictionaries - with false):

Requirements

• Supports macOS 12+ (Monterey or more recent)
• The Apple Shortcuts you wish to control with this plugin must be executable from the machine where Homebridge is installed. I.e. the user running Homebridge must be logged into an iCloud account which has access to those Shortcuts.

Credits

This project is a fork of homebridge-shortcuts-buttons originally created by smj0x.

Special thanks to the original developer for creating the foundation of this plugin, which allows HomeKit buttons to trigger iOS shortcuts via Homebridge.

Development

Please feel free to open PRs from forked repo against the latest branch, I'll do my best to have a look asap. The plugin is pretty extensible and there are plenty of potential easy enhancements to make in case people find it useful.

Semantic release and conventional changelog

This repo uses semantic-release to publish github releases and npm packages. Among the other things, it perform commits analysis in order to determine when a new release is needed, so it's important that all commits messages follow the conventional-changelog syntax. To facilitate this, the repo enforces the use of commitizen locally, via husky prepare-commit-msg hook.