homebridge-pushcutter v1.1.4

Homebridge-Pushcutter

With this plugin, you can create any number of fake switches that will trigger a Pushcut notification when turned ON. The notification is muted for a selectable time (indicated by the switch remaining in the ON position) to avoid multiple notifications.

The Pushcut notifications must be defined in Pushcut before they can be used, but the title, the text and the image of the notification can be updated in the switch configuration. The title and text can include the name of the switch, and the current time, date and week number.

The plugin supports Pushcut API keys, Webhook secrets and complete Webhooks. You can also use a custom URL, to trigger any type of URL based actions.

The plugin is designed as a platform to make it easier to create multiple switches using the same API key or Webhook secret. Also multiple platforms are supported, to allow different keys or secrets to be used.

How to install

• sudo npm install -g homebridge-pushcutter
• Create a platform and a notification switch in your config.json file, or use the Homebridge UI
• Restart homebridge

Example config.json:

   "platforms": [
     {
       "platform": "Pushcutter"
       "name": "Pushcutter",
       "api": {
         "selectApi": "apiKey",
         "apiCode": "<API key from Pushcut>",
         "locale": "sv"
       },
       "notifications": [
         {
           "switchName": "Evening",
           "notificationName": "Sunset",
           "useWebhook": false,
           "mute": 5,
           "pcTitle": "The sun is going down",
           "pcText": "Activated at {time}, {date} of week {week}.",
           "startOnReboot": true,
           "rebootTitle": "Homebridge restarted",
           "rebootText": "Restarted at {time} on {date}...",
           "sound": "vibrateOnly",
           "useConfig": true
         }
       ]
      }
    ]

This gives you a switch called "Evening" which will trigger the Pushcut notification "Sunset" when activated. The title and the text of the Pushcut notification is replaced by the values in the configuration file. The text will show the time, date and week number when the switch was activated. The switch is also used to send a notification when Homebridge restarts, with a separate message. The notification will only cause the receiving devices to vibrate. The title, text and sound will be restored after a restart.

How it works

Basically, all you need to do is: 1. Define a notification in Pushcut. 2. Get either the API key or the Webhook secret code from the Account page in the Pushcut app. 3. Select the type of key and enter the API key or Webhook secret in the config file. 4. For each notification, add a notification switch and enter the name of the Puchcut notification. 5. Add a new title, text and image for the notification, if desired. This makes it possible to create different notification switches using the same Pushcut notification, but with different contents. 6. Set the desired mute time in the config file (in seconds), to avoid additional activations within that time. 7. The plugin will create one switch for each notification. 8. Use this switch in any scene or automation to trigger the notification.

The characteristics of the switch are visible in the "EVE" app. These characteristics can be updated and used in automation conditions. The "Controller for Homekit" app is also a good way of controlling your automations, but it behaves a bit different when updating texts.

Configuration options

The possible configuration parameters are shown in the table below. Use the Config UI X for easy access to the configuration options and to generate a valid configuration in the config file.

Insert time and date

You can add the current time, date and week number to any new title or text for the notifications. Just add a {time}, {date} or {week} to the string and the plugin will replace them with the actual values. The plugin uses Luxon as the date wrapper. Luxon provides the time and date formatted for your country and language if the locale is set correctly. If the system default is not your preferred language, set the locale in the config file to the two-letter country code defined by ISO-639-1.

Why Pushcut

I tried a lot of apps to get notifications from HomeKit to my iPhone and iPad, but either they lacked possibilities to modify them to my liking, or they didn't work 100% on my devices. Finally I ended up using Pushcut, due to the easy use and possibility to do tweaking to the contents of the notifications. There are great examples on how to use Pushcut with IOS Shortcuts and to activate Pushcut notifications from HomeKit automations. So in theory, this plugin is not needed.

Why Pushcutter

I created this plugin because sometimes HomeKit looses the settings. Sometimes it is my own fault, but sometimes it just happens. And if you created a nice shortcut-based automation, that is lost. Controller for HomeKit has a nice backup and restore feature that has saved me from a lot of rework many times. But no 3rd party app can save your shortcuts, but your automation switches are saved by Controller for HomeKit. So this is my solution to get most of the features of Pushcut, that I use, in a format that can be backed up and restored in case of trouble.

Thanks

This plugin uses Homebridge-Lib by Eric Baauw for most of its features. I also peeked a lot at Eric's other excellent plugins that uses Homebridge-Lib. I'm rather new to Node.js, so developing plugins is my way of learning. This plugin uses the HttpClient of Homebridge-Lib, which was a new experience for me.

The Pushcut accesses was inspired by homebridge-smart-irrigation by Mayank, which was the only other plugin I found that uses Pushcut.