Introduction to a SmartThings SmartApp, Part 1


Intro

SmartThings is a great tool for home automation. The SmartThings app allows you to control many different smart devices in one place. This includes devices from many different brands. One of the more interesting things that SmartThings has is its SmartApps. With a SmartApp you can use the SmartThings API to create custom automation.

In this two-part series, we will first review setting up an example SmartApp. In part two, we will dig into the code to making your own custom SmartApp.

Prerequisites:

  • A SmartThings compatible color light.
  • Familiarity with APIs (Application Programming Interfaces).
  • Understanding of Node.js or JavaScript.
  • Samsung account.
  • SmartThings Developer Workspace account. You can use your Samsung account login for the Developer Workspace.
  • SmartThings mobile application, Android or iOS.
  • Node.js installed.
  • Npm installed.
  • Ngrok installed. Ngrok will create a secure tunnel to the local node server.

Setting up the Node.js application

If you want to follow along, I have an example repository used in this article. The example repository also outlines the steps for setting up the project.

In the example repository, run npm install to install the project dependencies.

To run the application, you first have to start the Node.js application npm run start.

After the Node.js application is running, you need to start ngrok in another terminal tab ngrok http 3000. Ngrok makes a secure public tunnel to our application. SmartThings will interact with this URL.

ngrok screenshot
ngrok screenshot

Now the application is running. Next, we can create a SmartApp in the Developer Workspace.

Creating a SmartApp in the Developer Workspace

Once logged in to the Developer Workspace, there is a button to create a new project. For this tutorial, select “Automation for the SmartThings App.”

Developer Workspace project creation
Developer Workspace project creation

After naming the project, we need to register the app. Registering the app creates a connection to the Node.js application.

When registering the SmartApp select “WebHook Endpoint” for this application.

For the Target URL, we will provide the ngrok URL. Remember this is for testing only, after closing ngrok the URL will not be accessible again.

Developer Workspace Hosting
Developer Workspace Hosting

On the next screen, provide the application name and description. This is what the SmartThings application will display.

On this screen, we need to provide device read and execution permissions.

  • r:devices:*
  • x:devices:*

Developer Workspace app details
Developer Workspace app details

Now save the SmartApp.

On the next screen, in the Automation Connector, there will be a link to verify your app registration. Click this link.

Developer Workspace verify link
Developer Workspace verify link

Visit the Node.js server logs and you will see a confirmation request with a link to visit to verify your app.

2021-05-21T21:05:49.453Z info: CONFIRMATION request for app e1b1a44a-4665-413c-9dfa-582713ab4944, to enable events visit https://api.smartthings.com/apps/e1b1a44a-4665-413c-9dfa-582713ab4944/confirm-registration?token=fd5ca5f6-6c7e-4877-ab25-fbfb1c31cdbf

Visiting this link will verify the app.

Visit the project overview page and click the “DEPLOY TO TEST” button.

This makes our SmartApp accessible in the SmartThings app. Note: this will be accessible after enabling developer mode.

Developer Workspace deploy
Developer Workspace deploy

Next, we will use the SmartApp to control a smart device.

Adding the SmartApp in the SmartThings app

First, in the SmartThings app, go to the settings. In the settings menu hold down “About SmartThings.” After holding around 5 seconds, enable the developer mode option.

SmartThings app developer mode screen
SmartThings app developer mode screen

The SmartThings app will restart to enable developer mode.

In the SmartThings menu, click SmartApp. Displayed is the screen for managing SmartApps.

SmartThings app add screen
SmartThings app add screen

After clicking the plus sign there will be a list of SmartApps presented. The “Custom” section lists any SmartApps deployed.

SmartThings app custom screen
SmartThings app custom screen

The details get fetched from the Node.js application. After filling out the details and approving the SmartApp, it should start operating.

SmartThings app details screen
SmartThings app details screen

You can verify that it’s operating by checking the Node.js logs. In SmartThings, you can see the history of your smart device.

SmartThings app history
SmartThings app history

In part two, we will take a look at some of the code that makes this all happen.

Conclusion

The SmartThings API allows developers to create IoT (Internet of Things) implementations using preexisting smart devices. This API allows for quick prototyping of ideas without worrying about hardware. Developers can focus on code and the end goal. SmartThings bridges the gap of working with hardware connectivity. Have fun and make cool things!

References


About the author

Written by Nicholas Diesslin Pizza acrobat 🍕, typographer, gardener, bicyclist, juggler, senior developer, web designer, all around whittler of the web.
Follow Nick on Twitter!