Home Assistant NFC Script

Home Assistant Automation in Depth: Multi-function NFC Tags

This post may contain affiliate links. Please see the disclaimer for more information.

This post is part of my “Home Assistant Automation in Depth” series. Here is the series index:

Welcome to the latest installment in my Home Assistant Automation in Depth series! In this article we’re going to explore how I’m using NFC tags with Home Assistant to control various aspects of my home automation. Specifically, I’m going to show my approach to making an NFC tag perform different actions depending on context.

I’m not going to dive headlong into an explanation of what NFC is. If you managed to somehow arrive at this page without knowing that, go and read the Wikipedia page! For our purposes it is sufficient to say that we can scan these little tags with our phone and some code will react to the scanning event.

How is NFC useful in Home Assistant?

Hopefully, you are already joining the dots in seeing how this is useful. Basically an NFC tag is a nice way to provide an input to a system. Think of it like a magic wireless button, that doesn’t need batteries! (assuming you charge your phone of course).

There is actually a little more to it than that. Since we won’t store anything sensitive on the tag itself we can safely leave them in public places. For example you could place one outside your front door. Only a phone which has been pre-configured with our setup will be able to execute the actions we have specified. Also, Android phones must be unlocked to scan the tags giving an extra layer of security.

There is a wrinkle with this, however. If someone knows the location of your tag they could potentially re-write it with some other (malicious?) data. There appears to be a way to write protect tags in the NFC Tools app I use below. However, I haven’t tried it yet. Make sure you do this if you want to place tags in areas where someone untrusted may have access!

Of course, the price of this is that you must have your phone on you which isn’t such a big deal. It may mean that you might not want to use these for tasks which need to be done very quickly or potentially with your hands full.

Connecting to HASS

There are at least two ways to connect NFC tags into Home Assistant. We can either use a dedicated app, or we can use Tasker with a plugin to accomplish the same thing. I’m going to describe the Tasker route, since I already had this in place before the HASS NFC app became available. Tasker is also allows you to do much more, so is a good app to have in any case.

The plugin we need for Tasker is called NFC Tasks and is free. In addition, we’ll need it’s companion app NFC Tools (also free) to configure our tags. You’ll also need Tasker and some NFC tags (obviously). I like the sticker variety (alternative link) for home automation purposes. However, they come in all kinds of shapes and sizes.

Once you have all the software installed it’s time to start connecting things up. First we’re going to want to setup Tasker to talk to Home Assistant via the REST API. This has got a little more complex if you want to use the new authentication system. However, there is a useful tutorial on the Home Assistant forum (thanks to @bokub for that!). This involves creating a specific task which can be re-used to talk to HASS. Go away and follow the instructions to do that now!

Welcome Back!

Once you’ve done that, you’ll need to set up another task (as detailed in the tutorial) which will be called when our NFC tag is scanned. I’m going to call a script, so mine looks like the screenshot below, but you can call any service in Home Assistant.

Home Assistant NFC
My task to be called when the tag is scanned

At this point you can test your task by executing it in Tasker and making sure it calls the right thing in HASS. You’ll then need to back right out of Tasker in order for it to apply the settings. If you don’t do this the task won’t show up later. Press the back button until you land back at the home screen, don’t just press the home button!

Writing the Tag

For the next part, we open the NFC Tools app and head to the tab called ‘Tasks’. Click the ‘Add a Task’ button, then navigate to ‘Various’ and ‘Tasker’. Hit the magnifier/search icon next to the task name input, then select the task you just created from the pop-up and press the ‘OK’ button. When you’re done, you should land at a screen like the one below. Hitting the write button will prompt you to scan the tag to write it.

Home Assistant NFC
Ready to write to the tag

If you now exit the NFC Tools app and scan the tag, you should see that your Tasker task is executed. This in turn performs your Home Assistant action.

At this point it should be noted that you can execute more than one task from a single tag. NFC Tool/Tasks also have a whole load of tasks built in, most of which I’ve not tried. Feel free to have a play around!

UPDATE: /u/databoy2k on reddit suggested an alternative way of doing this, which centralises more of the logic on the HASS server and so scales better to more tags/phones. I haven’t had time to try it fully yet, but I’ll probably switch over to it in future.

On the Home Assistant side

So now we have an NFC tag which can perform an action in Home Assistant. I’m now going to share how I’m using one particular tag as a multi-function switch for different modes in my house. I’ll start with an input_select to define the different modes I want:

I’ve placed my tag on the door frame of the door between our kitchen/living area and the rest of the house. This means I can scan the tag when I go through the door to select a different mode.

The question now is, how does the system know which mode to select? I’m doing this based on time of day, since my modes are mostly based around different events which fit within a rough timeframe. You can use pretty much any state or information from Home Assistant via a template. Here is my script which achieves this:

The keen eyed among you would have noticed that this is the script which is being called when my NFC tag is scanned. Here I simply set the value of the input select based on time of day. You’ll see that ‘Bedtime’ appears twice in order to handle the before and after midnight cases. With this setup:

  • Scanning the tag between 7am and 12pm will set the mode to ‘Coffee Time!’
  • A scan of the tag between 12pm and 6pm will set the mode to ‘Lunchtime’
  • Scanning at any other time will set the mode to ‘Bedtime’.

Handling the Modes

I handle each mode via an automation. Firstly, let’s go with the ones for my coffee and lunchtimes:

This basically implements some timed lighting for my break times during the day. I was always forgetting to turn off the kitchen lights when going back to work, so now I don’t have to. The timed lights also serve as a nice reminder that it is actually time to go back to work!

Since we already stored the state in the input_select we can use this as the timed trigger for the lighting off rule. This avoids the need for an external timer. Once we are done, we set the mode back to ‘None’

Next, we’ll tackle the bedtime mode. This is pretty simple, it just calls a script which turns off the lights and other appliances:

Conclusion

So there we have it – a multi-functional NFC tag which triggers different actions in Home Assistant, depending on the time of day. This approach has been working really well for me for quite some time. I’ve only recently upgraded it to the new authentication scheme, but it works flawlessly.

With the power of Home Assistant scripts, particularly the templating options, this approach could be taken a lot further than the simple examples I’ve shown here. One idea would be to turn on or off different appliances dependent on the state of other sensors. Another is to perform different actions depending on who is home at the time.

There are also probably further extensions, like doing different actions depending on the phone which scans the tag. I suspect the logic for this would have to be built into the Tasker task on the phone. For example each phone could call a different script on the server.

I’d also like to give these a try for outdoor use, with the write protect enabled of course. I think I might need to find some more durable tags for that experiment however, the stickers don’t feel very weather proof.

I’m interested to see what else people are doing with NFC and Home Assistant. Please get in touch via the comments and Twitter to let me know!

If you liked this post and want to see more, please consider subscribing to the mailing list (below) or the RSS feed. You can also follow me on Twitter. If you want to show your appreciation, feel free to buy me a coffee.

Self Hosted Push Notifications Server UI

Self Hosted Push Notifications with Gotify and Home Assistant

This post may contain affiliate links. Please see the disclaimer for more information.

Notifications, that bane of modern existence! Most people only have to deal with getting too many. However, if you’re running a smarthome or any other kind of moderately complex computer setup you need to decide how you are going to send and receive them too. Many notification systems rely on “trusted” third parties (a.k.a Apple or Google) to handle the delivery of notifications through to the current communications device of choice – the smartphone. Of course, this breaks my fully self hosted ethos and is to be avoided. Luckily it’s now possible to achieve self hosted push notifications with Gotify.

The Backstory

Pretty much since starting my smarthome journey (and really even before), I’ve had trouble with notifications. For a long time email was the goto solution – especially with my nicely self hosted email setup. Then I tried XMPP, then Rocket.Chat (I even wrote the Rocket.Chat notification platform for Home Assistant). There were probably a few more notification systems that I tried and definitely many more that I looked into. Nothing really stuck. Most were too complex to setup and maintain for the benefit that they provided. I mean, who really wants to run a whole chat server just for sending a few notifications?

Then Home Assistant implemented HTML5 notifications. These were cool, but not without downsides. For a start the full capabilities of the platform are only really supported by Chrome on Android. The notifications also go through – you guessed it – Google. However, the notification content is end-to-end encrypted between the HASS instance and the device. You can also do cool things like including images inline and having action buttons to press (actionable notifications).

If I’m honest, HTML5 notifications never really fit into the easy to set up basket either. The set up process is quite involved and requires creation of a project via Google Cloud Services and verification that you own the domain in question. However, once I got it working they worked well for quite some time.

Why can’t you get this right, Google?

After a while things started to have problems. First, I would quite often get delayed notifications. Sometimes to the point where the notification would not come through until you picked up and unlocked the phone. This negates the point of the notification entirely! Why is it that my self hosted email server can push messages in real time to k9mail running on the same phone, but Google’s own system has issues? I thought GCM/FCM was made of magic that simultaneously allowed it to be more reliable than anything else and consume no battery!?! /s

The next nail in the coffin was Google’s incessant pestering and breaking of things. First they wanted me to set up payment details, even though they weren’t going to charge me (why?). Then they said they were shutting down the GCM APIs used by my (admittedly somewhat outdated) version of HASS on May 29th this year. I assume that I could have fixed that by updating HASS (which I have since done). However, by this point I’d had enough and shut down the whole thing.

I initially fell back to SMTP/email notifications from HASS, which I still had running for a few lower priority things. However, I was on the look out for a replacement. I’d already heard of Gotify via /r/selfhosted, so I decided to give it a try. Since some of my other projects are starting to pay off and my smarthome is getting smarter, having a reliable notification system is becoming more pressing for me.

Deploying the Server

My ideal notification system would just use MQTT to push notifications to an app running on my phone. This wouldn’t require me to set up anything else but the app since I have everything else to support that. However, the designers of Gotify decided to use Websockets so an extra piece of server software is required.

Luckily, this software is written in Go (hence the project name). It also comes in a handy Docker container for easy deployment. Being written in Go makes it both fast and means it consumes barely any resources.

One consideration when deploying this is that you probably want it to be somewhere externally accessible, so that your phone can connect to it when not on your wifi. I installed it on an already accessible host that runs a few other dockerised services. I followed the official instructions, but came up with this to add to my docker-compose file for that server:

Well, that was easy.

Further configuration can be accomplished via config file or environment variables. However, I found the default settings to be fine for me.

Further Setup

I also needed to set up my reverse proxy to route requests through and set up TLS via Let’s Encrypt. I’m not going to go through that here. There are instructions (for the Gotify part) for nginx and apache available. Also, if you’ve already set up TLS for HASS then you can follow the same process. The Gotify app will show large warnings if you don’t use TLS. However, it will allow it so you don’t need to do this if you are only doing a bit of local testing.

Self Hosted Push Notifications Server UI
Gotify has a nice web interface, for configuration and receiving/viewing notifications on the desktop

After that I installed the app from F-Droid and added an exception in the battery optimisation page of my Android phone settings. This is different on every phone, but you need to make sure Gotify is listed as “Not optimised”. If you don’t do this Android will kill the app during sleep and you won’t receive notifications. For those that are going to bang on about how this will give you horrible battery life, I haven’t noticed a difference. Admittedly, I was already running a few apps unoptimised, such as k9mail and OwnTracks.

Setting up an Application

Before we can send notifications we need to create an application on the Gotify server. Applications map to individual streams of notifications on the recipient devices. One minor issue is that (as of the time of writing) applications are user specific, there is no way to share an application between users. This isn’t such an issue for us since we will need to set up individual notification platforms in HASS for each user anyway.

Self Hosted Push Notifications Application Setup
Our Application Screen

I set up my application as “Home Assistant” (surprise, surprise). I also uploaded the HASS logo which will be displayed in the notifications. Once the application is configured you will be given a secret token/key that can be used to send notifications via the REST API. You’ll need to copy this for use later.

Configuring Home Assistant

I played around for quite a while sending notifications with cURL as per the documentation and also some more complex messages via the RESTED Firfox addon. However, I’m going to skip straight to how to integrate this will Home Assistant, since that’s probably why you’re here!

Gotify has a simple REST api for sending notifications. Therefore we can use the REST notification platform in HASS to integrate it without a custom component:

This goes wherever you have your other notification platforms set up, for me this is in my notify.yaml file. After restarting HASS you should have the notify.gotify_1 service available. The reason for numbering it is that we will need more notification services to extend this to other users. You’ll need to update the resource key to the URL of your Gotify server and the X-Gotify-Key header value to the key you generated for your application earlier (which I recommend keeping in your secrets.yaml file, as I’m doing).

Sending Notifications

Sending self hosted push notifications
Sending a notification from Home Assistant

We should now be able to send notifications via the services developer tool in Home Assistant. It should be noted that you need to encode the data to send in JSON here for it to work. The data should contain ‘title’ and ‘message’ fields, exactly the same as any other notification platform. For example:

Once you hit the ‘CALL SERVICE’ button, you should immediately see a notification on your phone from Gotify:

Self hosted push notification received
Receiving our first notification

Again, that was easy (wasn’t it?).

Advanced Notifications

So far, we can send simple text notifications from Home Assistant via Gotify. However, Gotify also supports sending markdown formatted notifications, which opens up many more options.

To configure this, we edit our REST notification platform to the following:

Don’t forget to update the resource and X-Gotify-Key values as before. This updated configuration adds some extra data as per the Gotify documentation to indicate that the message payload should be rendered as markdown.

So let’s send a markdown formatted message. In the services dev tool again, select your notification service and use the following data:

And you should get:

Self hosted push notifications with markdown
Yay markdown!

Neat.

Using that for Something Useful

Markdown formatting is all well and good, but not all that useful just for making silly (but well formatted) messages. We’d like to actually put it to good use.

I’ve thought about including links in various notifications which could be used to trigger a Home Assistant webhook. This could then perform some action, but I’m still not convinced on the usability of it and haven’t had a chance to try it out.

One very useful option is including an image in the notification. This is particularly interesting if this image could come from a camera in Home Assistant. As it turns out this is relatively easy thanks to some minor templating:

Here I’m including the latest image from a local beach webcam that I have set up in HASS as a generic IP camera. All we need to do is use the entity_picture attribute to get the path of the image on the HASS server and join it to the base URL to build our image source. The resulting message is shown below:

Self Hosted Push Notifications with images
Looks like a nice day down at the beach (even though it’s winter down here)

Obviously, this could be very useful for security alerts, etc.

Conclusion

Overall, I’m pretty impressed with Gotify. Although the project is still young, it works as advertised and I haven’t had any functional issues. There are a few rough edges, but no showstoppers. I’m looking forward to seeing the feature set improve over time. I’d particularly like to see actionable notifications, which would set it up as a full alternative to HTML5 notifications in HASS.

I’ve been able to integrate Gotify into HASS up to the level of it’s current feature set. This is thanks to the well thought out REST API and the flexibility of the REST notification platform in HASS. So far I haven’t needed a custom/official component. As the Gotify API becomes more featureful, it’s likely that a component will be needed in order to unlock it’s full potential. However, as it stands the REST notification platform works just fine.

I’ve had no problems so far with delayed or missed notifications – which is better than Google can do! That in itself is an achievement the Gotify developers should be proud of.

If you liked this post and want to see more, please consider subscribing to the mailing list (below) or the RSS feed. You can also follow me on Twitter. If you want to show your appreciation, feel free to buy me a coffee.

SwallowCatcher 0.2.0 Released

Download SwallowCatcher 0.2.0

Download SwallowCatcher 0.2.0

After what seems like ages I’m proud to release a new version of SwallowCatcher – version 0.2.0, codenamed “The Black Knight (Come On Ya Pansy!)”. The reason behind the version number jump is twofold: 1. Bigger numbers are better, 2. I think the new features in this version and improved stability warrant a new version. Notable new features in this release include support for more URL schemes, cover art support and the ability to browse show notes from directly within the app.

I’ve had several contributions to this release both in the form of  bug fixes and in code and artwork. In particular I’d like to thank Nick Clark (@nrlucre on identi.ca) for contributing a great icon and Luke (~nobugs on Gitorious) for contributing bug fixes and adding itpc:// and pcast:// URL scheme support. Also, thanks to everyone who’s given me feedback and sent me bug reports.
As always, please check out the project page and the gitorious page where you can download the source code. Feedback and bug reports can again be submitted via identi.ca, email or via the comments on this post.

SwallowCatcher 0.1.3 Released

Download SwallowCatcher 0.1.3

Download SwallowCatcher 0.1.3

I’m again proud to announce a new release of SwallowCatcher. This is a small maintenance update which fixes some of the backwards compatibility issues which people have been experiencing with pre-Froyo versions of Android. Thanks to @diabalomarcus, @fdroid and Henrik Tunedal for their help with this issue.

As always, please check out the project page and the gitorious page where you can download the source code. Feedback and bug reports can again be submitted via identi.ca, email or via the comments on this post.

Using Android WebViews

Recently I’ve been working on show notes support for SwallowCatcher. Since most podcast feeds include their show notes in the feed as embedded HTML I decided to render this HTML to display the show notes. This turned out to be ridiculously simple thanks to Android’s WebView class. The API for rendering arbitrary HTML within your app is almost Pythonic in its simplicity. However, there are a couple of gotchas which caught me out, so I decided to cover them here.

I started out by creating a new Activity class and a layout XML file for it. The layout XML was taken almost directly from the Android WebView Tutorial page:

In my Activity class the XML is loaded as normal. We also need to import the WebView class and the URLEncoder class. Additionally, the UnsupportedEncodingException class is required:

Next, we need to encode the text in the correct format. Weirdly, WebView requires that the text is URL escaped, but without spaces converted to ‘+’ symbols. I used URLEncoder to encode my content then replaced the ‘+’ symbols with spaces. This probably isn’t perfect, but for my purposes it works.

Finally, we find the WebView from the XML and tell it to load the string as its content:

All the above is encased in a try..catch statement for UnsupportedEncodingException, just in case the URLEncoder has a fit. That’s pretty much it. In SwallowCatcher the ShowNotesActivity is 56 lines, including all the verbose Java imports and bootstrapping and loading the content from the database via ORMLite.

As a wise action hero (and ex-Jedi) once said, “I love it when a plan comes together”.