SmartThings Integration¶

We provide the following capabilities to interact with SmartThings:

• On/Off
• Percentage (light)
• Color Temperature (light)
• Fan Speed (fan)

Prerequisites¶

Upload Corresponding Information Model¶

Before using your connector, please upload corresponding information model with Integration Schema filled in to the Admin Site.

• No device will be shown in the SmartThings app if there is no information model on the Admin Site.
• Make sure the content in your information model is correct. If your information model is incorrect, you cannot discover your device. For more details about the content of information models, you can refer to Using Information Models.
• We strongly suggest that you change the nickname for your device, not using a general name or device type as the device name.
• For more details about uploading information models to the Admin site, you can refer to Managing Information Models.

Create SmartThings Workspace Account and Enroll Your Company¶

Please create an account and login at Develop Workspace.

Once you've logged in, please enroll your organization for project distribution.

Ask Exosite to Provide the Needed Info¶

You will need Exosite to provide the ExoHome's client ID and client secret to setup your project.

We will use the Developer Workspace to demonstrate how to build a device profile. If you are using the Developer Console and Device Profile Builder, you can still use these instructions as a reference, as the required fields are the same.

Setup Cloud Connector¶

This section describes how to build up a connector between SmartThings and ExoHome. A connector could link your devices to SmartThings.

After completing the section, you could start to try testing your devices on the SmartThings mobile app.

Create New Project¶

• Go to Develop Workspace

• Click "Create a new project"

  Please choose the enrolled company workspace (on the top right drop-down selector) to create your project

• "What kind of project would you like to start?"

  • Choose "Device Integration"
• "How do you want to integrate the device?
  • Choose "SmartThings Cloud Connector"
• "Choose a type of Cloud Connector"
  • Choose "SmartThings Schema Connector"
• "Give this cloud-to-cloud device integration a name"
  • Fill in your desired project name

Create Connector¶

• Go to page "Cloud Connector | SmartThings Schema" under tab "Develop"
• "Where are you hosting your connector app?"
  • Choose "WebHook Endpoint"
• Target URL
  • https://YOUR-DOMAIN-NAME.apps.exosite.io/api:1/smartthings
• Client ID
  • Fill in the client id provided by Exosite
• Client Secret
  • Fill in client secret provided by Exosite
• Authorization URI
  • https://YOUR-DOMAIN-NAME.apps.exosite.io/oauth2/authorize/smartthings
• Token URL
  • https://YOUR-DOMAIN-NAME.apps.exosite.io/oauth2/token/smartthings
• OAuth 2.0 Scopes Required
  • Fill in "profile"
• App Display Name
  • Fill in your desired connector name that is friendly to the end user
• Logo
  • Upload a logo file to represent your brand
• Click "Save" and copy the Client ID and Client Secret provided by the pop-up window. Please provide the copied information to Exosite.

Create Custom Device Profile (Optional)¶

If your device type is not listed in the SmartThings categories, you may define your own device by adding device profile.

ExoHome supports various combination of fan and light capabilities. If your device includes multiple fan or light components, or uses custom capabilities instead of the default SmartThings ones, refer to the customization examples below.

3-speed Fan¶

For fan capability, SmartThings supports 4-speed fan as default. If your device is a 3-speed fan, please follow the steps below to customize the settings.

• Go to page "Device Profile" under the tab "Develop" and click "ADD A DEVICE PROFILE" in Option 2.
• Name your device profile and choose fan as your device type, then click "Next" to proceed.
• Add capabilities: Switch, fan speed, Health Check and Refresh to the "main" component and click "Next".
• Select "Use general UI display". Choose Switch to both "State" and "Action" then click "CREATE DEVICE PROFILE".
• Please copy the Device Profile ID which needs to be placed in the information model's deviceProfileId field.
• Click the ellipses(…) of the device profile you just created and choose "Download Device Configuration".
• Edit device configuration json file. In "detailView", "automation", and "action" section's fanSpeed capability, add fanspeed.value and range as below:

{
  "key": "fanSpeed.value",
  "range": [
    1.0,
    3.0
  ]
}

For example:

{
          "mnmn": "xxxx",
          "vid": "xxxxxxx-xxxxx-xxxxx",
          "version": "0.0.1",
          "type": "profile",
          "dashboard": {
            "states": [
              {
                "component": "main",
                "capability": "switch",
                "version": 1,
                "idx": 0,
                "group": "main",
                "composite": false
              }
            ],
            "actions": [
              {
                "component": "main",
                "capability": "switch",
                "version": 1,
                "idx": 0,
                "group": "main"
              }
            ],
            "basicPlus": []
          },
          "detailView": [
            {
              "component": "main",
              "capability": "refresh",
              "version": 1,
              "values": [],
              "patch": []
            },
            {
              "component": "main",
              "capability": "switch",
              "version": 1,
              "values": [],
              "patch": []
            },
            {
              "component": "main",
              "capability": "fanSpeed",
              "version": 1,
              "values": [
                {
                  "key": "fanSpeed.value",
                  "range": [
                    1.0,
                    3.0
                  ]
                }
              ],
              "patch": []
            }
          ],
          "automation": {
            "conditions": [
              {
                "component": "main",
                "capability": "switch",
                "version": 1,
                "values": [],
                "patch": [],
                "exclusion": []
              },
              {
                "component": "main",
                "capability": "fanSpeed",
                "version": 1,
                "values": [
                  {
                    "key": "fanSpeed.value",
                    "range": [
                      1.0,
                      3.0
                    ]
                  }
                ],
                "patch": [],
                "exclusion": []
              }
            ],
            "actions": [
              {
                "component": "main",
                "capability": "refresh",
                "version": 1,
                "values": [],
                "patch": [],
                "exclusion": []
              },
              {
                "component": "main",
                "capability": "switch",
                "version": 1,
                "values": [],
                "patch": [],
                "exclusion": []
              },
              {
                "component": "main",
                "capability": "fanSpeed",
                "version": 1,
                "values": [
                  {
                    "key": "fanSpeed.value",
                    "range": [
                      1.0,
                      3.0
                    ]
                  }
                ],
                "patch": [],
                "exclusion": []
              }
            ]
          },
          "migration": true
        }

• Click ellipses(…) of the device profile again and choose "Edit profile". Go to "UI Display" and click "Customize through device configuration file". Upload the modified json file and save.
• Make sure the information model has this device profile ID and you are good to go.

Ceiling fan with light¶

• Go to page "Device Profile" under the tab "Develop" and click "ADD A DEVICE PROFILE" in Option 2.
• Name your device profile and choose light as your device type, then click "Next" to proceed.
• Add capabilities: Health Check and Refresh to the "main" component.
• Click "ADD ANOTHER COMPONENT" and add capabilities: Switch and Switch Level to the "light" component.
• Click "ADD ANOTHER COMPONENT" and add capabilities: Switch and Fan Speed to the "fan" component.
• Click "Next" to proceed.
• Select "Use general UI display". Choose light's Switch to both "State" and "Action".
• Hit "CREATE DEVICE PROFILE" button.
• Copy the device profile ID and add it to information model's deviceProfileId field.

Ceiling fan with 2 lights and 1 switch control¶

• Go to page "Device Profile" under the tab "Develop" and click "ADD A DEVICE PROFILE" in Option 2.
• Name your device profile and choose fan as your device type, then click "Next" to proceed.
• Add capabilities: Health Check and Refresh to the "main" component and click "Next".
• Click "ADD ANOTHER COMPONENT" and add capabilities: Switch, Switch Level and Color Temperature to the "light1" component.
• Click "ADD ANOTHER COMPONENT" and add capabilities: Switch, Switch Level and Color Temperature to the "light2" component.
• Click "ADD ANOTHER COMPONENT" and add capabilities: Switch to the switch component.
• Select "Use general UI display". Choose Fan's Switch to both "State" and "Action" then click "CREATE DEVICE PROFILE".
• Please copy the Device Profile ID which needs to be placed in the information model's deviceProfileId field.
• Click the ellipses(…) of the device profile you just created and choose "Download Device Configuration".

• Edit device configuration json file. In "detailView" and "automation" section's colorTemperature capability, add "key" (colorTemperature.value) and "range" values. In "action" section's colorTemperature capability, add "key" (setColorTemperature) and "range" values. For example, if the light's color temperature can be adjusted between 3000K to 6500K, please put 3000 and 6500 in the range field.

  {
    "key": "colorTemperature.value",
    "range": [
      3000,
      6500
    ]
  }
  

  You may download an device profile example for reference.

  For devices with a color temperature setting, the key in the action (setColorTemperature) section differs from that in the detailView and automation (colorTemperature.value).

• Click ellipses(…) of the device profile again and choose "Edit profile". Go to "UI Display" and click "Customize through device configuration file". Upload the modified json file and save.

• Ensure the information model includes the correct device profile ID and matching component names before proceeding.

Deploy To Test¶

• Go to page "Overview"
• Click "Deploy to test"

Connect Your Device On Mobile to Test¶

You may follow this document for detailed instructions.

• Install app "SmartThings"

• Launch app and login to your SmartThings account

• You can follow Test your device App to:
  • Enable developer mode
  • Link your device
• Choose your testing connector
• Add device by clicking "+" on the upper right.
• Click "My testing device"
• Choose the project you set in SmartThings Developer Workspace from the list.
• Login ExoHome for authentication
• Authentication succeeds
• All linked devices will be listed
• You could refresh current status of devices and operate them

Publish¶

After completing your self-testing in developer mode, you can send the publish request by following SmartThings' instructions on the developer workspace.

Problem Shooting¶

If you run into any issues (e.g. not being able to control devices), try to do one of the following actions:

• Check the correctness of information model
• Delete original project and create another one again
• Unlink the connector and re-link it again
• There's no extra spaces in the fields you enter in the SmartThings Developer Workspace.