SmartThings Automations

Overview

SmartThings IoT Ecosystem overview - from SmartThings Automations feature to Developer Workspace
  • SmartThings adds a little smartness to your things at home. You can add devices to your App and manage devices by phone. Controlling lights, setting the thermostat, running robot vacuum cleaner has not been easier. Especially when creating your automation by setting rules like opening kitchen door that turns the light on.

  • It helps users to program their home according to their preferences.

  • Moreover, it is not only about life convenience but how your home protects you. Installing fire alarm, water leak, that notifies you when danger occurs, can set action that triggers appropriate actions like notification, turning device off, closing valve.

  • SmartThings Ecosystem allows developing custom automations via Developer portal called Developer Workspace. Integration devices with external web services in few lines of code is getting relatively easy step to develop.

  • Automation can be a Webhook endpoint or a Lambda function.

Figure 1 SmartThings IoT Overview

Figure 1 SmartThings IoT Overview

Objective

Enable automation of obtaining data from the air quality web service to inform you of alerts in your location.

Setup

Requirement for Automation development
  • Access to Developer Workspace https://smartthings.developer.samsung.com/

  • Node.js 8 installed

  • Ngrok installed

  • Mobile Phone Samsung S8 or S9 with SmartThings App

  • Devices like bulb, open close sensor, siren, outlet

Setup
  • Access prepared automation code

  • On desktop find “SDC2018-AutomationCode” directory

Application Development

Task 1: Air quality monitoring service

Attendants of this lab will discover easy and friendly way to connect home devices with each other and with external web services. To achieve this goal, we will cover the topics of SmartThings ecosystem, Device Capabilities, SmartThings API, Automations Life Cycle Events. We will go through the Automation code written in JavaScript. Also publishing Automation in Developer Workspace account and installing Automation App on the phone will be performed. During Code Lab the example of Automation will be presented. Automation will handle changing the color of a light depends on the air quality condition in selected city. Selection of the city is made on the basics of few predefined cities e.g. Tokyo, London. We will use API that is described under the link: https://breezometer.com/air-quality-api/

Based on information of poor air quality we will be able to turn the siren on, change color of the bulb to red, turn the outlet on (outlet will turn the fan on). If window will be open and city will get alert, automation will let you know to close window. Also user will get little information on Slack! For further analysis we will save air quality data to the file.

Step 1: Automation Code Presentation. What should be implemented?

  1. 1. Entry point for callbacks by SmartThings in “server.js” file and method app.post(‘/’). File to keep data is created. First event that Automation will receive is request with ‘PING’ live cycle. This request is send before generating public key as signature. Later on, method signatureIsVerified(req) is used.

    app.post('/', function (req, response) {
       
       file.createFile();
       
       if (req.body && req.body.lifecycle === 'PING' || signatureIsVerified(req)) {
          handleRequest(req, response);
       } else {
          response.status(401).send('Forbidden');
       }
    });
    
  2. 2. HandleRequest(req, response) function for handling life cycle requests:

    • Ping and Configuration

    • Install and Uninstall

    • Update and Event

  3. 3. In “Configuration” request automation settings should:

    • Contain user data input (e.g. select devices, select city)

      Defined JSON will be transformed to layout. The result of configuration page is picture below. Also see “config.js” file for reference.:

      Figure 2 Configuration Page

      Figure 2 Configuration Page

  4. 4. Set the scenario:

    • Get air quality from external web service by selected city

    • Calculate color

    • Use commands.actuate(deviceId, token, command) function to make SmartThings API call with command

    • See “air.js” and “commands.js” file and example code snippet below

      airCondition.getAirConditionsInfo(selectedCity)
         .then(function (airState) {
            
            let color = airCondition.getColorForAirCondition(airState);
            commands.actuate(deviceIdBulb, token, [
               {
                  command: 'on',
                  capability: 'switch',
                  component: 'main',
                  arguments: []
               },
               {
                  command: 'setLevel',
                  capability: 'switchLevel',
                  component: 'main',
                  arguments: [20]
               },
               {
                  command: 'setColor',
                  capability: 'colorControl',
                  component: 'main',
                  arguments: [color]
               }
            ]);
      
      if (color === colorType.RED) {
         console.log('Turn the siren and the outlet on');
         commands.actuate(deviceIdSiren, token, [
            {
               command: 'on',
               capability: 'switch',
               component: 'main',
               arguments: []
            }
         ]);
         
         commands.actuate(deviceIdFan, token, [
            {
               command: 'on',
               capability: 'switch',
               component: 'main',
               arguments: []
            }
         ]);
      }
      
  5. 5. Run Automation

    • Install project dependencies - npm install

    • Start server - npm start

    • Start ngrok - ngrok http 3005 – secure URL to your localhost server

    • Copy https link from ngrok console

  6. 6. Open the browser and Slack https://stautomations.slack.com/. Password will be provided.

Step 2: Register your automation with Developer Workspace

  1. 1. Visit https://devworkspace.developer.samsung.com/

  2. 2. Go to Developer portal section and log in (account will be provided for Code Lab)

  3. 3. Select tab “Automation” on left side menu

  4. 4. Type :

    • Display name

    • Automation name

    • Description

    • Select Webhook endpoint

    • ype target URL from previous step (from ngrok)

  5. 5. Add privileges to your automation (in scope area). For purpose of this example select all.

  6. 6. Save

    Figure 3 Fill in Details

    Figure 3 Fill in Details

    Figure 4 Save Public key

    Figure 4 Save Public key

  7. 7. Copy public key and save public key to “Smarthings_rsa.pub” file

Step 3: Working with SmartThings mobile App
  1. 1. Sign in with provided login and password

  2. 2. Tab “Devices” shows all available device on your account

    • Samsung Cell is paired with user account

    • Bulb that handle capabilities:

      • setLevel – dimmer handles light intensity
      • switch – turn the bulb on/off
      • colorTemperature – controls color of the light
    • Open close sensor (capability contact)

    • SmartThings siren (capability switch)

    • Outlet (capability switch)

    Figure 5 SmartThings App

    Figure 5 SmartThings App

  3. 3. To work on Automation go to tab “Automations

  4. 4. On “Automations” page your Automation should be published

  5. 5. Select your automation. In this example it is “sdcautomation2018

  6. 6. Configure your automation

  7. 7. Select city

  8. 8. Select devices and schedule time interval

Follow below graphics to install and configure Automation App.

Figure 4 Save Public key
Step 4: Test it on SmartThings App

Look how devices responded. Also Slack should get message, when open sensor was opened.

Figure 6 Message on Slack

Figure 6 Message on Slack