We now have a public URL to access our server and we have our server ready to respond to various lifecycle messages from SmartThings. Now it’s time to create our SmartApp configuration within the SmartThings Developer Workspace.
Creating the SmartApp Configuration
- The first step is to start your server to make sure it is running, and then start your ngrok tunnel.
python3 /home/pi/st_webhook/st_webhook.py
./ngrok http 5000Make a note of your Forwarding HTTPS URL. I also recommend you go ahead and start your local Ngrok Dashboard in your browser (localhost:4040).
- Login to the SmartThings Developer Workspace using your SmartThings (Samsung) account.
- Click on the New Project button.
- Click on the Automation for the SmartThings App button.
- Enter a name for your project (i.e. ST Test Webhook) and click Create Project.
- Click Register App.
- Click WebHook Endpoint and then click Next.
- Enter your public HTTPS URL that you noted in Step 1 in the Target URL field and click Next. (It must be the HTTPS URL)
- Enter an App Display Name, Description, and for this project we will just click the Scope checkbox to select all permissions. It’s not needed, but you can come back and eliminate permissions later. It’s easier when troubleshooting to not spend time adding new permissions to see if it resolves your problem. As you become more familiar, you can select the right permissions for your SmartApp.
Click Next.
- You can leave the Advanced Settings blank and just click Save. This is when SmartThings will make its first call to your server. You should see a brief message that says Connection Saved and then it shows you this screen.
Copy the Client ID and Client Secret and save them somewhere safe in case you need them in the future. Then click Go To Project Overview.
At this point you can go back to your Raspberry Pi and check your Ngrok Dashboard. You should see a POST message with a CONFIRMATION Lifecycle and hopefully a 200 OK Response. If not, then you should have some debug logging displayed from your server to indicate what went wrong.
If something went wrong and you had to correct it, you can go back to your SmartThings Developer Workspace and you will probably see a message similar to this:
After you correct the issue and make sure your server is running, click the Verify App Registration link and it will attempt to make another CONFIRMATION call to your server. You might have to wait 10-15 seconds while the whole process takes place, but once it’s complete it should take you back to the Project Overview page.
- Now, back on the Project Overview page, click on the View Details button.
- This is the screen where we will get our AppID. Copy this value and insert it into the ST_WEBHOOK constant we defined in our server. Make sure you restart your server if necessary after saving that value.
- Click on the Overview link to get back to the Project Overview window.
- Now it’s time to click on the Deploy to Test button.
You should see the following confirmation message.
Click Got It and you’ll be taken back to the Project Overview page. Now your SmartApp should say Deployed to test.
- Now you need to open the SmartThings App on your mobile device so we can enable Developer Mode. Here’s the official link on how to do it, but I summarize it below.
- Once there, click on Menu, then click on Settings (the gear) in the upper right.
- Scroll down towards the bottom to find About SmartThings.
- Press and Hold the About SmartThings item for about 5 seconds. You should get a pop-up telling you to restart the App or it will just appear at the very bottom, but if not try closing the App and restarting it. You might have to try a few times.
- Return to the Settings menu and scroll down to the bottom. You should now see a Developer Mode option. Make sure it is turned on.
- While still in the SmartThings App, click on the Automations tab. Once there, click on the + symbol on the upper right of the screen and select Add SmartApp. Scroll down until you see the Custom section. This is where you should see your ST Test Webhook SmartApp listed. Click on it.
- You should see your Configuration Page display in the SmartThings App. You will also notice, if you check your Ngrok Dashboard on your Pi, that there were two more calls to your server. One for the lifecycle Configuration and the Phase Initialize, and the second for the lifecycle Configuration and the Phase Page. If your Configuration Page didn’t display, check to see if any errors occurred on your server and that your public URL hasn’t changed.
In this example, you should select a Contact Sensor and a Switch. Click Done once you have made your selections.
You will then be prompted to Deny or Allow the SmartApp to have the permissions you requested. Click Allow. You should be taken back to the Automations tab and your SmartApp should now be listed at the bottom in the SmartApps section. If you look at your Ngrok Dashboard, you should see a lifecycle Install call.
NOTE: At the time of this writing, there is a known SmartThings glitch on iOS devices with some WebHook SmartApps not displaying in the SmarApps section of the Automations tab after being installed. In my case, I always have to click on the + symbol and choose Add SmartApp. I can then scroll back down to my app and select it again, then it shows my current configuration and lets me make updates. Hopefully this issue will be resolved soon.
- Now you should be able to open and close your contact sensor and see the switch turn on and off, respectively.
- Anytime you have to start a new Ngrok tunnel and you get a new public URL, you will need to go back to the SmartThings Developer Workspace, select your project, click on View Details, edit your App Details, enter the new Target URL and click Next, then click Next on the Name & Scope page, and then click Save on the Advanced Settings page. That will make another call to your server with the Confirmation lifecycle to validate the connection. After that, everything should continue to work as usual.
- In the next post, we’ll start collecting much more information so we can display a live event page.