Development

Air quality monitoring service

In this tutorial, you 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, and 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. Automation will handle changing the color of a light depending on the air quality condition in selected city. Selection of the city is made on the basics of few predefined cities e.g. Tokyo and 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, and 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

  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 has been sent 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. HandleRequest(req, response) function for handling life cycle requests:

    • Ping and Configuration

    • Install and Uninstall

    • Update and Event

  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:

  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. 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. Open the browser and Slack https://stautomations.slack.com/. Password will be provided.

Step 2: Register your automation with Developer Workspace

  1. Visit https://smartthings.developer.samsung.com/workspace/.

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

  3. Select tab Automation on left side menu.

  4. Type :

    • Display name

    • Automation name

    • Description

    • Select Webhook endpoint

    • ype target URL from previous step (from ngrok)

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

  6. Save

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

Step 3: Working with SmartThings mobile app

  1. Sign in with provided login and password.

  2. Devices tab 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)

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

  4. Your Automation should be published On Automations page.

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

  6. Configure your automation.

  7. Select city.

  8. Select devices and schedule time interval.

Follow below graphics to install and configure Automation App.

Step 4: Test it on SmartThings app

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


You're done!

Congratulations! You have successfully achieved the goal of this Code Lab activity. Now, you do automation with SmartThings by yourself!