New-SmartApp

New-SmartApp is a sample ASP.Net Core application that explains how to write Samsung SmarThings hub automation using the new SmartThings API. The automation provides a very basic functionality. All it does is allows user to select a contact sensor to log open and close events.

This application is based on the Weather Color Light SmartApp Node.js sample referenced on the Getting Started documentation section of SmartThings Developers website.

The application is a webhook hosted in Azure that receives and sends requests to SmartThings cloud where the automation connector is registered.

The design of the application is kept simple. The intention here is to show the building blocks of establishing communication with SmartThings.

Specifics

• The application is written using Visual Studio ASP.Net Core Web API project template.
• The applicaiton is based on .Net Core 2.2.
• The application is based on strongly typed SmartThings lifecycle objects located in Models subfolder.
• The application is hosted in Azure App Service.
• Logs and telemetry are collected in Azure Application Insights.
• Requests received by the application from SmartThings are authenticated with signature authentication scheme RSA-SHA256.
• Public key the application uses to verify requests is stored in Azure Key Vault secret.
• Requests the application sends to SmartThings are protected with OAuth 2.0 bearer tokens.

Prerequisites

Here is what you need to run and deploy the application.

• Visual Studio with .Net Core and Azure SDKs
• Samsung SmartThings Hub (any version should work)
• SmartThings app (not the SmartThings Classic) installed on your phone
• One IOT device - this project uses a contact sensor but anything should work. You can use a virtual device if you do not have a physical one.
• Microsoft Azure account (free account should work)
• Samsung SmartThings developer account
• Ngrok application to expose your app to SmartThings cloud in development environment

Get the app

1. Type in the following in Bash

git clone https://github.com/steveage/New-SmartApp.git

2. Install Node dependencies

cd New-SmartApp/newsmartapp.smartappapi
npm install

Starting the app

1. Open the solution from Visual Studio and run the application (F5).
2. Create a tunnel that will expose your application to SmartThings for testing and debugging. Start Ngrok and enter the following command.

ngrok http 53869 -host-header="localhost:53869"

3. Copy the https address. You will need it in the next section.

Register the app as automation

At this point your application is up and running but SmartThings does not know about it. In this section we will change that by creating an automation in SmartThings. The process is explained in the Developer Workspace documentation.

1. Log in the Developer Workspace.
2. Create automation project and open it.
3. Click on Automation under Develop section on the right.
4. Select the Webhook Endpoint, paste the https address from Ngrok and click Next.
5. Select read and update device scopes and click Next.
6. Enter the name for your automation and click Save.
7. When the automation is being saved, SmartThings will send PING lifecycle POST request. Once the application responds properly, you should see connecton save confirmation with public key. Copy the key. You will need it to verify the incomming requests from SmartThings. The key will be securely stored in Azure Key Vault in the next section. When debugging the application locally with Ngrok you can use this key directly in the controller.

Install the automation

Now we are ready to add the automation in SmartThings app.

1. Enable developer mode that allows logging of any activity on the automation. This might be useful when troubleshooting or debugging.
2. Add the automation to SmartThings app.

Once the automation is successfully installed you should see POST requests containing device lifecycle every time the selected sensor gets opened or closed.

Azure Deployment

With the automation registered in SmartThings and tested locally on your computer, it is time to host it in the cloud. The process is the same as for any web application that is deployed to Azure. There are however several customizations and workarounds that need to be placed before successful communication between SmartThings cloud and Azure is established. This section will explain all that. (Comming soon)

Create AzureApp Service

Log in to your windows account in Visual Studio. With the solution open in Visual Studio, right click on the project file and select Publish. On the Pick a publish target window keep the default settings and click on Publish.

On the Create App Service window:

1. enter the name of your smart app in App Name
2. select your Azure subscription
3. Create resource group by clicking on New...
4. Create hosting plan by clicking on New....
5. Select Application Insights region.
6. Click on Create.

Log in to Azure Portal

Once the app service is created and the application is published, log in to Azure Portal to view the app service. Click on All Resources on the Home tab on the left and find your app service.

Add Application Insights

Once published, Application Insights service should be created and set up for the web service. The APPINSIGHTS_INSTRUMENTATIONKEY setting should exist in the app configuration and information about requests, dependencies, exceptions, etc. should be automatically logged. The topic is well described in Application Insights for ASP.NET Core applications.

Add Key Vault Secret

Publish

Deploy Node.js Dependencies

Change Node.js Settings

Update Webhook Address