SmartThings CLI

SmartThings SDK includes a Command Line Interface (CLI) that developers can use instead of the Atom-based GUI and code editor to develop SmartThings applications. With it, you can run through the entire SmartThings development process from creating a project to running the plugin.

For a comparison of the features provided in each tool, see the SmartThings Overview. For details about command syntax, either use the command-line help (–help) or see the CLI Reference.

The CLI connects all of the required SmartThings assets with a common library and into a single interface. These assets include SmartThings Cloud, Samsung Account, Developers Portal and Developer Workspace. It can also directly launch commands from the SmartThings IDE, simulator, and virtual device.

Accessing the SmartThings SDK with CLI Reference is easy. Simply open command line and type st followed by an applicable command.

Here is an example of a SmartThings CLI command.

CLI example

How to install

To use the CLI, you need to understand how the underlying SmartThings SDK operates. This guide does not cover all of this information.

You can download the SmartThings CLI standalone or as part of SmartThings SDK, which includes the CLI, virtual device, and device plugin simulator. To download the SmartThings CLI, go to the Developer Workspace and go to Tools > Downloading the SDK. Select Windows or Mac as OS and download the CLI or SDK package.

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

  • Node.js
  • Java SE

For more information on prerequisites, see here.

How to use the CLI

This section describes how to use the SmartThings Command Line Interface (CLI) to access the SmartThings SDK.

The following is the typical development process using the CLI.

  1. Authentication: Log in to your Samsung Account and get an Access Token to link to your project.
  2. Create project: Select or create a project with your required parameters.
  3. Build project: Build the project into a .ppk file.
  4. Test application: Launch a virtual device with the device profile or connect a real device to SmartThings Cloud. Install the plugin into the SmartThings app or the use the simulator built into the SDK.
  5. Submit application: Submit your application to the SmartThings Developers Portal.

Authentication

Get an access token

You need an Access Token to interact with SmartThings Cloud. To get an Access token, you login with your Samsung Account.

By logging in to Samsung Account, the SDK associates your project info with your identity. Projects can be accessed through Developer Workspace and in the SmartThings app (on a mobile device).

There are two ways to get an Access Token.

  • Use the Samsung Account login page.
  • Use a Samsung Account Authcode.

Samsung Account login page

The easiest way to get the Access Token is to use the st request-token command. This opens a login prompt for your Samsung Account. Once you do this, your token is automatically generated.

st request-token --show-ui

Samsung Account Authcode

You can also get an access token with a Samsung Account authcode. An authcode is a unique string of letters and numbers – generated by Samsung – that is assigned to your account. This is useful when you don’t have a dedicated UI set up on your environment.

To generate an authcode from Samsung.

  1. Open the Samsung Account authorization token page.
  2. Log in with your Samsung account.
  3. You receive a message similar to this :
{"code":"By2F0HGGPE","code_expires_in":300,"client_id":"3694457r8f","api_server_url":"us-auth2.samsungosp.com","auth_server_url":"us-auth2.samsungosp.com","close":"true","closedAction":"signInSuccess"}st request-token --show-ui
  1. Copy the second string in the message. In the example above, it is By2F0HGGPE.
  2. Use the following command.
st set config --key authCode --value {authCode}

Reference

  • --value {authCode}: Replace {authCode} with your generated authcode from Samsung.

Create a project

A project stores all the files associated with the SmartThings plugin for an IoT device, including JSON files, catalog, UI, and voice data. Within this project, you define a device profile, which identifies device capabilities and can be used by multiple devices.

These devices are manually controlled and monitored through the SmartThings app through a plugin. The plugin is just a web app that uses HTML, CSS, JavaScript, and JSON to define the device UI and behavior.

There are 2 ways to generate a project with the CLI.

  • Use a template

    • If you start with a template, all of your project files are generated for you automatically, including the device profile capabilities and the plugin layout and behavior. These are predefined in the template. You can build the plugin immediately and test it.
  • Use a device profile ID

    • Device profiles are collections of capabilities that you define and save under a device profile ID. You can use a single device profile ID to create multiple custom plugins. Each plugin inherits the capabilities defined in the device profile. To see existing device profiles, use the command st list device-profile. Unlike with a template, some assets (such as the plugin folder that contains the layout) are not predefined and must be added via command line.

Use a template

The SmartThings SDK provides basic plugin templates to help you get started on projects quickly.

The default template directory is C:\Users\%userprofile%.atom\packages\smartthings\tools\cli\assets\templates

To list the available templates, use the following command.

st list template

Samsung Account

To create a project with a template ID, use the following command. The output is saved under the current directory you are targeting in the CLI.

st create project --name  --template 

Samsung Account

Reference

  • --name: Enter the name for this project, which will also be used as the project folder name.
  • --template: Select from one of the predefined templates for devices.

Use a device profile

You can also create a project starting with a device profile. By default, device profiles are saved in this directory: C:\Users\%user%\.smartThings\device_profiles.

To create a project with a Device profile, use the following command.

st create project --name  --device-profile 

Projects created with a device profile are saved in the same directory you are targeting with the command line. For example, C:\Users\%user%.

Reference

  • --name: Enter the name for this project, which will also be used as the project folder name.
  • --device profile: Enter the ID of the device profile.

Optional commands

  • --device-profile: Specify a device profile ID.
  • --main-state: Specify a capability for displaying as the main state on device card.
  • --main-action: Specify a capability to display as the main action on a device card.
  • --device-plugin: Specify a device plugin ID that represents the device information in detail.
  • --create-device-plugin: Generate source code for a custom device plugin.
st create project -n,--name  --device-profile 
  [--main-state 
][--main-action
] [--device-plugin ] [--create-device-plugin]

Optional examples

This command creates the plugin folder in your project.

st create project --name  --device-profile  --create-device-plugin --device-plugin

This command provides a main state action and capability in your plugin.

st create project --name helloWord --device-profile f61d5a98-c824-11e7-80db-cfc4208a1c5d --main-state switch

The main state code can be viewed if you open the {MNID}_{VID}_ui.json file that was generated. It is nested under the ma object.

For example, this is the main action generated using the switch parameter.

      "ma": [
      {
      "name": "PowerSwitch",
      "type": "main",
      "order": 1,
      "link": {
        "href": "/capability/switch/main/0",
        "if": "oic.if.a",
        "rt": "x.com.st.powerswitch"
      },
      "iconUrl": {
        "vector": "",
        "small": "",
        "large": "",
        "mid": "icon://ic_function_power_switch"
      },
      "property": "power",
      "controlType": "ToggleSwitch",
      "alternatives": [
        {
          "key": "on",
          "value": "__PO_CODE_POWERSWITCH_ON"
        },
        {
          "key": "off",
          "value": "__PO_CODE_POWERSWITCH_OFF",
          "type": "inactive"
        }
      ],
      "step": 0,
      "label": {
        "label": "__PO_CODE_POWERSWITCH"
      },
      "emphasis": false
    }  
    ],

Build your Project

You need to build a project before you can test it. Building a project provides the .ppk file you install into the SmartThings app.

To build your project, navigate to the project folder and use the the following command.

st build project

Building a project generates your app with your manufacturer ID (MNID) and your device-profile Vendor ID (VID).

Reference

Your app is built using the following files:

  • catalog.json: contains easy setup information for how to add devices into the SmartThings app.
  • project.json: contains information for building your .ppk file.
  • {MNID}_{VID}_ui.json: contains information for displaying device cards.
  • {MNID}_{VID}_voice.json: contains information for handling devices using voice.

Once you build your project, a new folder is created in the project directory named /out. Here you find your .ppk file.

  • {Device-Plugin ID}_{Version}.ppk: displays device information in detail.

Test your App

The SmartThings SDK provides a virtual device and the simulator to test an application. The virtual device can check and update the status of device that is registered on SmartThings Cloud, similar to a real device.

The simulator displays the device’s status like the SmartThings app. If you click a card, the simulator also displays device’s status in detail by loading installed device plugin.

To test your app with the virtual device, follow these steps:

  1. Install your app into the simulator
  2. Publish the device into the virtual device
  3. Launch the virtual device
  4. Launch the simulator.

Steps

1. Install your app into the simulator.

The simulator shows how your plugin looks in the SmartThings app. You install an app on a SmartThings simulator with the following command:

st install app --simulator

2. Publish the device into the virtual device. To launch a virtual device, you must register it to match the device profile of a project. To do this, use the following command:

st publish device --device-profile 

Reference

  • --device-profile: Specify target device project ID
  • --id: Specify device project ID. Generate a random ID if you don’t specify

Optional commands

  • --authcode: Specify an authcode to get the Access Token for registering device. Use internal SSO Token if you don’t specify.
  • --name: Specify a device name. Use a name on device profile if you don’t specify.

3. Launch the virtual device

You launch the virtual device with the following command. For more information, see the virtual device page.

 st launch virtual-device

The device list is shown at first. To open a virtual device, select your device and tap LAUNCH.

img

4. Launch the simulator

You launch the simulator with the following command. For more information on using the simulator, see the device plugin simulator pages.

st launch simulator

img

Request a signing key for devices

You can also use the CLI to request a device certificate. For more information, see here.

st request device-crt --device-name  [--email ] [--mnid ] [--common-name ] [--organization ] [--organizational-unit ] [--locality ] [--state ] [--country ] [--out-dir ]

Reference

  • --mnid: Specify your manufacturer ID (MNID).

Optional commands

  • --email: Specify your email address.
  • --common-name: Specify the name of your enterprise.
  • --organization, --organization-unit: Specify your company.
  • --locality, --State, --Country: Specify your country (and language), state, and locale of your enterprise (headquarters).
  • --out-dir: Specify the directory certificate file will be located.

Request a signing key for plugins

You can also use the CLI to request a signing key for plugins. For more information, see here.

st request ppk-crt --passwd  [--distributor-type ] [--common-name ] [--organization ] [--organizational-unit ] [--state ] [--country ]

Reference

  • --passwd: Specify a password used to protect access to your private key.
  • --distributor-type: Specify permission level to use plugin API. (Use “Public” only)

Optional commands

  • --common-name: Specify the name of your enterprise.
  • --organization, --organization-unit: Specify your company.
  • --locality, --State, --Country: Specify your country (and language), state, and locale of your enterprise (headquarters).

Submit an App (Self-Publish)

Based on feedback from our open beta, we are still working to finalize the app publishing process. In the meantime, you can still test your app with the virtual device and simulator.

Check back soon for more information. Thanks for your patience.

Manage/Control Devices

You can also use the CLI to display and control the status of a device. The following commands display all the devices registered on SmartThings Cloud.

st list device
  • --resource-model: Print devices that contain an OCF resource model.
  • --client: Print client devices.

Check detailed information of a device.

You can also use the CLI to display detailed information of a device. Information listed about a device includes deviceID, label, name, locationID, deviceTypeId, deviceTypeName, DeviceNetworkType, deviceManufacturerCode and components.

st describe device -i,--id 
st describe device -i,--id  --resource-model [--detail]
  • --id: Specify a target device ID.
  • --resource-model: Print a resource mode of target device.
  • --detail: Print a resource model in detail.

Check the status of a device.

st describe device-status -i,--id  [--component ]
st describe device-status -i,--id  --resource-model -r,--resource 
  • --id: Specify a target device ID
  • --component: Specify a component ID of target device.
  • --resource-model: Print an OCF resource status of target device.
  • --resource: Specify HREF information of target resource when --resource-mode option is enabled.

Update the status of a device.

st command device -i,--id  --capability  --command  --args  [--component ]
  • --id: Specify a target device ID.
  • --capability: Specify a Capability ID to which you want to send a command.
  • --command: Specify a command that a Capability supports, Refer to the Capabilities reference page for more information.
  • --component: Specify a component ID of device. It is main by default if you don’t specify a name.
  • --args: Specify arguments of a command. Refer to the Capabilities reference page for more information.

Update the status of a resource directly

This command only applies if a device contains an OCF resource model.

st command device -i,--id  --resource-model -r,--resource  --args  [--resource-type ] [--interface ]
  • --resource-model: Update the OCF resource status of device
  • --resource: Specify the HREF information of target resource when --resource-mode is enabled
  • --args: Specify a target resource’s status (JSON format) that will be updated when --resource-mode is enabled
  • --resource-type: Specify an OCF resource type when --resource-mode option is enabled
  • --interface: Specify an OCF interface when --resource-mode is enabled

Delete a device from cloud

st delete device -i,--id 

Manage a device profile

The SmartThings SDK defines a device type using a device profile. This is based on a JSON Capability model, similar to below:

{
    "name": "{Name}"
    "components": [
        {
            "id": "{Component ID}",
            "capabilities": [
            {
                "id": "{Capability ID}"
            }, ...
            ]
        }, ...
    ],
    "metadata": {
        "mnmn" : "{MNID}",
        "vid" : "{VID}",
        ...
    }
}
  • Name: Name of device profile
  • Component ID: Component ID of device
  • Capability ID: Capability ID supported by component
  • MNID: Manufacturer ID of developer
  • VID: Device Vendor ID

You can check the supported Capability IDs on the capabilities reference page

st list capability

The CLI also provides a default device profile.

st list device-profile [--built-in] [--category ]

You can also check a detailed device model by with the device profile ID.

st describe device-profile --id  [--resource-model]
  • --id: Specify the target device profile ID

  • --resource-model: Print the device model based on Capability as OCF resource model

Custom device profile

To create a custom device profile, you need to generate the device profile file in the JSON model and then execute the following command.

st create device-profile --in 
  • --in: Specify the device profile file path that is written in JSON format

Command-line Help

The CLI --Help command provides a list of all help topics.

st --help

You can also target information for a specific command.

st {command} --help

Or, you can see the detailed description.

st {command} {target} --help

References