SmartThings SDK

SmartThings SDK is an add-on package for the Atom IDE editor. With it, you use GUI editors to define an IoT device’s capabilities and its UI within the SmartThings app. Capabilities can include actions such as adjusting the brightness of a light bulb or changing the speed of a fan.

With the GUI editor, the generation of an IoT device’s plugin package is simplified so you can make web apps quickly. If you need to fully customize the device plugin UI or behavior, you can use the Atom IDE editor to edit the plugin’s underlying HTML, CSS, JavaScript, and JSON code.

How to install

Prerequisites

Before you can use SmartThings SDK, you must have all of the following installed:

  • Node.js
  • Java SE
  • Atom IDE
  • Google Chrome Browser

Review this page for details.

Node.js

Node.js provides a JavaScript engine as well as a web server framework for the IDE and CLI. You need Node.js version 6.0 or later. To check if you have right version installed, use the command:

C:\> node –v
v6.11.2

If you don’t already have the right version of Node.js:

  1. Download the software from the Node.js download site.
  2. Set the PATH variable to include the executable folder, for example, C:\Program Files\nodejs.

Java SE

To install and use SmartThings SDK, you need Java SE v1.8 or later. To check if you have the right version installed, use the command:

C:\> java –version
java version "1.8.0_144"
Java(TM) SE Runtime Environment (build 1.8.0_144-b01)
Java HotSpot(TM) 64-Bit Server VM (build 25.144-b01, mixed mode)

If you don’t already have the right version of Java:

  1. Download the software from the Oracle Java SE download site.
  2. Set the PATH variable to include the executable folders, for example, C:\Program Files\Java\jdk1.8.0_92\bin and C:\Program Files\Java\jre1.8.0_92\bin.

Atom IDE

This IDE provides the platform for SmartThings SDK GUI and code editing.

  1. Download the software from atom.io.
  2. Install the software.

Google Chrome browser

The simulators are launched as browser popups using the localhost port number 5680. To enable the popups, either:

  • Allow all popups: In Chrome Settings > Advanced > Privacy & Security > Content Settings > Popups > Move the slider to the Allowed position.

  • Whitelist popups from port 5680: In Chrome Settings > Advanced > Privacy & Security > Content Settings > Popups > next to Allow, click Add and enter localhost:5680.

Download the SDK package

To download SmartThings SDK:

  1. Go to the Developer Workspace.
  2. In the upper right corner, click Log in and sign in using your Samsung Account.
  3. Go to Tools > Downloading the SDK.
  4. Select Windows or Mac as OS and download the SDK package that includes Atom plugin, CLI (Command Line Interface), virtual device, and device plugin simulator. If you do not need SmartThings SDK, you can download the basic SmartThings CLI only.

Install SmartThings SDK

Windows

To install SmartThings SDK on Windows, proceed as follows:

  1. Double-click to launch the .exe file.
  2. Follow the setup wizard in SmartThings SDK and install the SDK packages.
  3. SmartThings SDK is installed by default in C:\Users\\.atom\packages\smartthings.

MacOS

To install SmartThings SDK on MacOS, proceed as follows:

  1. Double-click to launch the .pkg file.
  2. Drag and drop SmartThings from the .pkg popup window to your /Applications folder.
  3. Link the executables to your computer’s program folder.

Uninstall SmartThings SDK

Use the Atom IDE editor’s package manager.

  1. Launch the Atom IDE.
  2. From the File menu, select Settings > Packages > Community Packages > smartthings > Uninstall.

To re-install SmartThings SDK, see Install SmartThings SDK.

How to create a project

Launch the SDK

  1. Double-click the desktop icon SmartThings. This launches the Atom editor.
  2. Access the SmartThings functions through either the:
    • Packages menu > SmartThings sub-menu
    • toolbar menu

Log in

By logging in to Samsung Account, the SDK can associate your project info with your identity, so that you can access your projects on Developer Workspace on the web and the SmartThings app on a mobile device.

  1. In the Atom IDE, select Packages > SmartThings > Log in.
  2. Log in to your Samsung Account. When you log in successfully, Samsung Account issues an authentication token, which SmartThings SDK stores for you. This token is good for the duration of the SDK session or until you log out.

Create a project

A project stores all the files associated with the SmartThings plugin for an IoT device, including JSON files storing project, catalog, UI, and voice data.

You first define a profile, which identifies device features and can be used by multiple devices.

  1. In the Atom IDE, select Packages > SmartThings > New Project.
  2. Provide general information about the project:
    • Project Directory: The path to and name of the folder holding your IoT projects.
    • Project Name: A unique name for the project, used in project listings and the OS folder containing this project’s files.
  3. Click Next.

You can now do either of the following:

  • Select one of the predefined device templates: networkAudio, airConditioner, airPurifier, dishWasher, light.
  • Add and define a new device profile, which can be used by multiple IoT devices:
    1. Click +.
    2. Complete these fields:
    • Device Profile Name: The name of the profile.
    • Vendor ID: The name of your organization.
    • Capabilities: The device features that will appear in the SmartThings plugin. Use the dropdown menu to select a feature. You must select at least one feature with a state (for example, a switch, which can have the state on or off) and at least one feature with an action (for example, a switch, which can be turned on or off). Click + to add a feature to the capabilities list.
    1. In the upper right corner, click Add and review the device profile information.

The final step is to click Next and specify the type of SmartThings plugin package (.PPK file) to generate.

  • Custom: With this option, you can fully customize the plugin UI and behavior, by coding the web app from scratch and generating a custom plugin package.

    1. Dashboard Main State: For Capability, select the most important device state (for example, power switch on or off), which will appear in the main device card in the SmartThings Dashboard.
    2. Dashboard Main Action: For Capability, select the most important device control (for example, turning the power switch on or off), which will appear in the main device card in the SmartThings Dashboard.
    3. Custom Plugin Package Name: Enter a name for plugin package (.PPK file).
    4. Click Finish.
  • Default: You will use the default plugin, which defines predefined UI widgets and behavior for selected device features.

    1. Dashboard Main State: For Capability, select the most important device state (for example, power switch on or off), which will appear in the main device card in the SmartThings Dashboard.
    2. Dashboard Main Action: For Capability, select the most important device control (for example, turning the power switch on or off), which will appear in the main device card in the SmartThings Dashboard.
    3. Click Finish.
  • Template: This applies only if you had earlier selected one of the predefined device templates: networkAudio, airConditioner, airPurifier, dishWasher, light. With this option, you are using a pre-designed template for a device.

    1. Template List: Select one of the available templates. If the list is empty, click Back and select one of the predefined device templates from the left pane.
    2. Click Finish.