Overview
This guide includes 4 parts skip to whatever items are of interest to you:
-
Summary of what the device is
-
Setting up the SmartThings platform to bridge events from the device to our HA instance, for free without requiring any existing smartthings hardware or devices.
-
Setup of a proper incoming web hook/push url briefly one of 3 different ways and make sure it is SmartThings compatible. (mostly linking to other information)
-
Testing (without installing the ST app) & Reacting to events
What is it
So recently I started with this cool device: Smart Remote, Smart Fob + Key Finder | OmniFob by Keyport it is a tiny rechargeable device with an LCD screen and two buttons (one small easier to push and one larger more force required button, to prevent accidental press). It communicates with your phone (and their app) over bluetooth. It supports controlling devices and scenes and aside from having navigable menus they have “quick control” gesture/pattern actions. Quick Controls mean rather than having to navigate to a device or scene to control you can create instant triggers like: “If I hit the big button 3 times rapidly toggle the lights” or “If I long press the small button unlock my front door”, it seems to natively support up to 6 press sequences. It charges on USB-C but I have only charged it a week ago and haven’t had to since.
The app is pretty easy to use (and nicely allows renaming of devices/scenes to better fit the small screen) the downside is it has limited integrations given all the different SH platforms (see site for details). I only have mostly local only integrations so none of their platforms did I have integrations with. Given the interesting premise of the device I wanted to find a way to test it in daily life. I had a smartthings hub in some drawer I figured I could find to use. Shortly there after I figured out that one can use the SmartThings platform/cloud infrastructure without needing any SmartThings devices/hubs. Combining this with the home assistant SmartThings bridge gave me exactly (almost) what I wanted in the OmniFob communicating to home assistant. I say almost as I would prefer something local whenever possible. I hope they do adopt the upcoming Matter SDK given its local first focus. As an added bonus it includes a BT Chipolo One chip which I think works with iBeacon Tracker - Home Assistant (I don’t need tracking so didn’t try this).
Finally, there are some great benefits to a user triggered prox device vs passive proximity. Opening a lock when you are near it without having to use a key or enter a code is nice, but not super secure. Sometimes that “near” requirement can be simulated for example. If you have to push (or hold) a button for an action though far less opportunity for something to go wrong. It also has the nice feature you can activate automations without unlocking a phone or even look anything just reaching into your pocket blindly. I do some construction work and being able to turn off the shopvac and fan with my hands full and not getting down is real nice. Granted I am fairly new to it, so I am sure I will find more fun applications.
Guide
Setting up Virtual Devices in SmartThings
-
At sign in prompt create an account (or login with an existing one)
-
You should be on the “My Locations” page, if this is a new account or you don’t have any locations click “New Location” in the upper right. Name it whatever you want, you just need something.
-
Next lets create our fake switches go to: SmartThings. Add a little smartness to your things. (or click My Devices) then click “New Device” in upper right.
-
For the
Namefield put whatever you want, say STOutsideLight, put the same thing in for the device network ID. For type selectVirtual Switchthis gives you a standard two position switch, even if you just want a stateless button switch you can use this. There are some other devices likeMomentary Button Tilebut I am not sure of the application that Virtual Switch would not work for, as we really just want to signal HA. Dimmer might be useful if you want some sort of scale control. -
Leave
versiononPublishedselect your Location under Location and leave the rest blank.
Home Assistant Setup
-
Now go to home assistant and navigate to
settings→device / services→add integrationand search forsmart things. It will confirm the push URL that must be correctly setup (see details below for The Incoming Web Hook / Push URL for setting this up if needed). Next follow the instructions to obtain a smartthings token (go to: SmartThings. Add a little smartness to your things. and generate a token with all boxes checked). -
Check and if all goes well you should see your virtual switches under the new smartthings.
-
Next trigger your switch in ST if you have ST already use whatever you use to control it, if you setup an account just for this go to: https://my.smartthings.com/ and toggle your device there. Look at the home assistant logbook do you see the event generated there? Fantastic. I recommend not just using the OmniFob app upfront so there are fewer possible sources of failure if something is not working.
-
Final thing to do is add automations or triggers based on the ST device events. For stateless actions like toggle the lights on/off I just ignore the ST item state and say if turned on or off do X in HA.
Setup the OmniFob Itself
To complete the loop and start having fun we just need to setup the OmniFob with their SmartThings integration. This is pretty straightforward at this point so I will just refer to one of the YT guides or their online guide for that: https://www.youtube.com/playlist?list=PLGuZCsVNrmtS14YhIhPhEBGpPal69Yz_u / OmniFob Support, FAQs, and How-To's | Keyport it will also need a ST token you can use the same one from HA or generate a new one (as it will guide you to do). Note it will tell you to install the ST app first, there is no need to do this as we already have tested ST and it is working, and the OmniFob doesn’t talk to the ST app it talks to the ST api directly.
Future Hopes
I do hope in the future they include Matter support, given the wide array of IOT devices promising support would be fantastic to see and easy to add random things into the app with just sharing. It also seems to have some cool multi-color LEDs built in, exposing this to be able to use it as a notification target. ]6
Troubleshooting
General
The incoming webhook is probably the most likely source of difficulty in this setup if you don’t use HA cloud and haven’t already set one up. HA has some decent documentation on. For debugging failures turn on some logging under the logs config section:
homeassistant.components.smartthings: debug
homeassistant.components.http: debug
and restart home assistant.
When things are working you should see two entries on any smartthings event:
DEBUG (MainThread) [homeassistant.components.http.view] Serving /api/webhook/mBa0SsnSxCNo6PEtCUUvmBamBa0SsnSxCNo6PEtCUUv0SsnSxCNo6PEtCUUv
DEBUG (MainThread) [homeassistant.components.smartthings] Push update received: {'location_id': 'oBhMXI74vIFKLwJSjV57-asdasd-asdasd-viaES1plDch0g9dObdtC', 'device_id': 'NHPBkxo0r1loe1thiCve-asd2-aer-zsdf-iRGWmuViiWYejsKe0SGh', 'component_id': 'main', 'capability': 'switch', 'attribute': 'switch', 'value': 'off', 'data': {}}
First is the incoming web request, the second is smartthings parsing the update. Note I did find some more exotic smartthings devices did generate push events to HA but I didn’t see any equivalent events generated in HA. As all I really cared about was signaling when the OmniFob had an action taken I didn’t debug ST to see what was happening to that data.
The Incoming Web Hook / Push URL
The HA Cloud / Nabu Casa Option
If you are using the home assistant cloud (paid) this is already setup for you. If you have never setup/used the webhook or have a publicly accessible domain I recommend following the Cloudflare notes below, it is free and easy to get right.
Manual Web Hook URL Setup
If you have any other webhook incoming you may also have already set this up (but smartthings is somewhat particular about ssl settings per below). You do not have to run this webhook on a standard port, you can for example, run it port 32932 and use a url like https://MyHAInstance.something.com:32932/.
Now the push URL must be publicly accessible and use a valid certificate (ie letscrypt) AND does not offer TLS 1.3. A known nginx config for example is:
ssl_protocols TLSv1.2;
ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH';
ssl_prefer_server_ciphers on;
ssl_ecdh_curve secp384r1;
ssl_session_timeout 10m;
ssl_session_cache shared:SSL:10m;
ssl_session_tickets off;
Keep in mind if you do any proxying you cannot change the URL smartthings hits vs the path it actually comes in on to HA. This is because the SmartThings HA module verifies a checksum that includes that path and will discard invalid events otherwise.
Cloudflare Public URL through Free Tunnel
Cloudflare is large company not going anywhere, highly reliable, and not going to snoop on your data. Doing this setup creates a “tunnel” from your home assistant instance into the cloudflare network that then gives you a public domain you can access HA from (and optionally other things on your network). You need to have a parent domain name for this to work. You can register one with cloudflare for ~$5 a year. Sample domains that are that cheap are .uk at $4.75 and .racing at $5.16. Many other cloudflare services (including tunnel) are completely free. So get started create yourself a free cloudflare account and then register a domain at: https://dash.cloudflare.com/?account=domains
For the rest of setup follow this great tutorial by @mostlychris EVEN EASIER way to use Cloudflare Tunnels to access Home Assistant and remote network access. - YouTube or a written version at: addon-cloudflared/DOCS.md at b175eb7650128a0cc2eb6f65531e1f1d5a7da028 · brenner-tobias/addon-cloudflared · GitHub (just follow the 5 steps in “Local tunnel add-on setup”). If you run home assistant core or in docker you can do this fairly easily as well. Follow the instructions ONLY to step 10 at addon-cloudflared/remote-tunnel.md at b175eb7650128a0cc2eb6f65531e1f1d5a7da028 · brenner-tobias/addon-cloudflared · GitHub to create a remote tunnel in cloudflare itself, copy that token. Now on your home assistant machine have it run this command before starting home asssistant:
TUNNEL_TOKEN="YOUR_COPIED_TOKEN_HERE" cloudflared --no-autoupdate tunnel run &
make sure you do the step about enabling proxies in your home assistant configuration.xaml ie:
http:
use_x_forwarded_for: true
trusted_proxies:
- 172.17.0.0/16
- 127.0.0.1/32
Verify if you pull up your subdomain you get the home assistant login.
It doesn’t seem to need TLS 1.3 disabled with cloudflare but if you run into issues you can do so:
- edit the domain go to the lock icon on left side for SSL/TLS then go to edge certificates
- Turn off TLS 1.3 toggle lower on that page