SmartThings Developer Documentation¶

What We Believe¶

As a starting point in understanding our approach, it is important to recognize that we believe strongly in the separation of intelligence from devices. Said another way, we think that most of the value will be created in the space between the devices. We believe that the time has come when devices themselves can be limited to their primitive capabilities (open/close, on/off, heat/cool, brew/don’t brew), and that the intelligence layer should be kept separate.

By doing this we allow the intelligence (or application) layer to apply flexibly across a wide range of devices, and make it easier to create applications that interact with and across the physical world. In many cases, we also benefit from lower-cost end devices, less maintenance complexity and longer battery life.

Key Concepts¶

The SmartThings platform provides methods to abstract away the underlying complexity of devices and protocols (using Device Type Handlers) from the application of intelligence (using SmartApps).

Each device in SmartThings has “capabilities”, which define and standardize available attributes and commands for a device. This allows you to develop an application for a device type, regardless of the connection protocol or the manufacturer.

All of the code that developers can write on our platform is written in Groovy, which is a dynamic, object-oriented language built for the Java platform. You can learn more about Groovy on the Groovy – The SmartThings Programming Language page.

preferences {
   input "theswitch", "capability.switch"
   input "thedoor", "capability.contactSensor"
}

def installed() {
   subscribe(thedoor, "contact.open", doorOpenHandler)
}

def doorOpenHandler(event) {
   theswitch.on()
}

Supported Protocols¶

The following protocols are supported in the SmartThings Hub:

• ZigBee - A Personal Area Mesh Networking standard for connecting and controlling devices. ZigBee is an open standard supported by the ZigBee Alliance. For more information on ZigBee see http://en.wikipedia.org/wiki/ZigBee.
• Z-Wave - A proprietary wireless protocol for Home Automation and Lighting Control. For more information on Z-Wave see http://en.wikipedia.org/wiki/Z-Wave.
• IP-Connected Devices - Local Area Network (LAN) connected devices (both hard-wired and WiFi) within the home can be connected to the SmartThings Hub.
• Cloud-Connected Devices - Some device manufacturers have their own Cloud solutions that support their devices and that we can connect to. Most of these devices are actually WiFi connected devices, but they connect to a proprietary set of Cloud services, and therefore we have to go through those services to gain access to the device.

The Samsung SmartThings Hub also ships with a Bluetooth Low Energy (BLE) chip to support future expandability. While not enabled at launch, having the hardware available allows us to support BLE in the future via firmware and software updates.

Asynchronous & Eventually Consistent Programming¶

When dealing with the physical graph there will always be a delay between when you request something to happen and when it actually happens. There is latency in all networks, but it’s especially pronounced when dealing with the physical graph.

To deal with this, the SmartApps platform utilizes asynchronous execution. This means that anytime you execute a command, it doesn’t stop everything else from running. This helps everyone’s code run the most efficiently.

Our basic methodology towards executing a command, such as turning a light switch on, is “fire and forget”. This means that you execute a command, and assume it will turn on in due time, without any sort of follow up.

You cannot be guaranteed that your command has been executed, because another SmartApp could interact with your end device, and change its state. For example, you might turn a light switch on, but another app might sneak in and turn it off.

If you needed to know if a command was executed, you can subscribe to an event triggered by the command you executed and check its timestamp to ensure it fired after you told it to. You will, however, still have latency issues to take into consideration, so it’s impossible to know the exact current status at any given time.

The SmartApps platform follows eventually consistent programming, meaning that responses to a request for a value in SmartApps will eventually be the same, but in the short term they might differ.

Containers¶

Within the SmartThings platform, there are three different “containers” that are important concepts to understand. These are: accounts, locations, and groups. These containers represent both security boundaries and navigation containers that make it easy for users to browse their devices.

The diagram below shows the hierarchical relationship between these containers. Each type of container is described below in more detail.

Capability Taxonomy¶

Capabilities represent the common taxonomy that allows us to link SmartApps with Device Handlers. An application interacts with devices based on their capabilities, so once we understand the capabilities that are needed by a SmartApp, and the capabilities that are provided by a device, we can understand which devices (based on their device type and inherent capabilities) are eligible for use within a specific SmartApp.

The Capabilities Reference is evolving and is heavily influenced by existing standards like ZigBee and Z-Wave.

Capabilities themselves may decompose into both ‘Actions’ or ‘Commands’ (these are synonymous), and Attributes. Actions represent ways in which you can control or actuate the device, whereas Attributes represent state information or properties of the device.

Overview¶

We made the decision at SmartThings to support a “Cloud First” approach for our platform. This means that in our initial release, there is a dependency on the Cloud. This means that your hub will need to be online and connected to the SmartThings cloud.

The second generation of our hub, the Samsung SmartThings Hub, allows for some hub-local capabilities. Certain automations can execute even when disconnected from the SmartThings cloud. This allows us to improve performance and insulate the customer from intermittent internet outages.

This is accomplished by delivering certain automations to the Samsung SmartThings Hub itself, where it can execute locally. The engine that executes these automations are typically referred to as “App Engine”. Events will still be sent to the SmartThings cloud - this is necessary to ensure that the mobile application reflects the current state of the home, as well as to send any notifications or perform other cloud-based services.

The specific automations that execute locally is managed by the SmartThings internal team.

That said, there are a number of important scenarios where the Cloud is simply required and where we can’t reduce or eliminate dependence on the Cloud:

There may not be a hub at all

Many devices are now connected devices, via WiFi/IP.

The advantage of Wifi devices is that they can eliminate the need for a gateway device (hub) and connect directly to the cloud. When you consider the breadth of devices like this that are coming onto the market, it’s easy to imagine that there will be customers who want to be able to add intelligence to those devices through SmartApps, but that may not have a SmartThings Hub at all because all of their devices are directly connected to the vendor cloud or the SmartThings Cloud.

Put simply, if there is no Hub, then the SmartApps layer must run in the cloud!

SmartApps May Run Across both Cloud and Hub Connected Devices

As a corollary to the first point above, since there are cases where devices are not hub-connected, SmartApps might be installed to use one device that is hub-connected, and another device that is cloud-connected, all in the same app. In this case, the SmartApp needs to run in the Cloud.

There may be Multiple Hubs

While the mesh network standards for ZigBee and Z-Wave generally eliminate the need for multiple SmartThings Hubs, we didn’t want to exclude this as a valid deployment configuration for large homes or even business applications of our technology. In the multi-hub case, SmartApps that use multiple devices that are split across hubs will run in the Cloud in order to simplify the complexity of application deployment.

External Service Integration

SmartApps may call external web services and calling them from our Cloud reduces risk because it allows us to easily monitor for errors and ensure the security and privacy of our customers.

In some cases, the external web services might even use IP white-listing such that they simply can’t be called from the Hub running at a user’s home or place of business.

Accordingly, SmartApps that use web services will run in the Cloud as well.

myGarageDoor.open()

Benefits¶

There are a number of important benefits to the overall SmartThings approach:

Bringing Supercomputing Power to SmartApps and the Physical World

No matter how much computing power we put into the SmartThings Hub, there are scenarios where it simply wouldn’t be enough.

Take for example the ability to apply advanced facial recognition algorithms to a photo taken by a connected camera to automatically determine who just walked into your house while you were away. In the Cloud, we can bring all necessary computing power to solve complex problems, that we would not have if limited to the local processing power in a hub.

The Value of the Network Effect

Our vision is to make your physical world smarter, and we are doing that not just for our Hub and Devices, but for lots of different devices and scenarios. The easier that we make it to create that intelligence (through SmartApps), the bigger that ecosystem of developers and makers will be.

For consumers, that will mean the power of choice and the ability to solve problems with a solution that best fits their needs.

As a developer or maker, it means broad access to consumers and distribution channels for your product.

Increased Ease of Use, Accessibility, Reliability & Availability

By centralizing many capabilities into the SmartThings Cloud, we increase our ability to monitor, manage, and respond to any failures or other issues. More importantly, we can simplify the customer experience and make our solution easier to use than ever before. Further, we ensure that customers have an increased level of access and visibility.

This is not a new trend - there are many examples where on-premise capabilities have migrated to the service provider, because it improved the overall service reliability and customer experience.

Big Picture¶

Who can Develop with SmartThings?¶

Developing for SmartThings is free and open to all.

Our typical guideline is that anyone with a web developer (back-end) background will be best-equipped to develop with SmartThings.

That said, if you have programmed in any programming language before, you’ll be able to learn how to develop with SmartThings.

Never programmed before? You may want to spend some time learning some programming basics first, but you certainly don’t need a degree in Computer Science to be successful developing with SmartThings.

SmartThings uses Groovy as its development programming language. You can learn more about Groovy, and its use in SmartThings, in the Groovy – The SmartThings Programming Language chapter.

Create Device Type Handlers¶

If you have a new device that we don’t already support, you can actually write a new Device Handler for the SmartThings platform that integrates the device.

Building support for new device types means that you also get to design the device detail screens for how the device will appear in our mobile experience.

For information about developing for hub-connected devices, see the Device Handlers.

For information about developing for Cloud or LAN-Connected devices, see the Cloud and LAN-Connected Devices.

Create Event-Handler SmartApps¶

You can write SmartApps that provide unique functionality across devices.

These are SmartApps that don’t have a UI except for configuring their behavior. They generally run in the background and handle events from devices and then issue commands back to other devices to control them.

For information about developing Event-Handler SmartApps, see the SmartApps.

Create Integration SmartApps¶

SmartApps can call external web services and they can expose web services for external systems to call.

What is Groovy?¶

Groovy is an object-oriented programming language for the Java platform. It is a dynamic language with features similar to those of Python, Ruby, Perl, and Smalltalk.

It can be used as a scripting language for the Java Platform, is dynamically compiled to Java Virtual Machine (JVM) bytecode, and interoperates with other Java code and libraries.

Groovy uses a Java-like bracket syntax. Most Java code is also syntactically valid Groovy.

Why Groovy?¶

By basing our first programming language on Groovy, we provide the benefits of a dynamic language with the scalability and performance of Java. Longer term, we hope to enable other programming languages in the SmartThings Cloud so that you can ultimately chose from several supported languages. Likely candidates (no promises) for additional languages include Ruby, JavaScript, Clojure, and Python.

For more documentation on the syntax, structure, and capabilities of Groovy, visit the Groovy Documentation. There you will find information for getting started with Groovy, and comprehensive language documentation.

Note, however, that because of the application “sandboxing” that we do in the SmartThings Cloud, some features of Groovy are disabled for security reasons. We will discuss this more in the Groovy Sandboxing topic below.

Groovy Sandboxing¶

SmartThings runs with a sandboxed environment. This means that not all features of the Groovy programming language are available to SmartThings developers. This is done for reasons of security and simplicity.

Here are some of the restrictions:

class Foo {
    def list
}

def squareItClosure = {it * it}

Tips & Tricks¶

To get comfortable with Groovy, it’s recommended you install it and try it out. You can find information about installing Groovy here.

You can also use this handy Groovy web console if you don’t have Groovy installed locally. Some features may not be available, but it’s a handy way to try things out quick.

A full discussion of Groovy is obviously beyond the scope of this document, but there are a few key language features that you’ll see often in the SmartThings platform that are worth brief discussion here.

def currentDateString = "The current date is ${new Date()}"

def awesomePlatform = "SmartThings"
def newString = "Programming with $awesomePlatform is fun!"

"SmartThings".contains "Smart"
"SmartThings".contains("Smart")

def yell() {
    return "all caps".toUpperCase()
}

def yellAgain() {
    "all caps".toUpperCase()
}

def names = ['Erlich', 'Richard', 'Gilfoyle', 'Dinesh', 'Big Head']
def programmers = names.findAll {
    it != 'Erlich'
}
// programmers => ['Richard', 'Gilfoyle', 'Dinesh', 'Big Head']

def names = ['Erlich', 'Richard', 'Gilfoyle', 'Dinesh', 'Big Head']
def programmers = names.findAll {dude ->
    dude != 'Erlich'
}

References and Resources¶

Groovy is simple enough to be able to jump in and start writing code quickly, but powerful enough to get yourself stuck pretty quickly.

Here are a few resources you can use to sharpen your Groovy skills:

• Groovy Documentation Portal
• Groovy Closures
• Groovy Collections
• Groovy Web Console
• Learn Groovy in 5 Minutes

Locations¶

My Locations will show all locations registered to your account. Choosing a particular location will allow you to see more in depth information on that location, including the groups created under that location. You can also see all events, notifications, and SmartApps under a particular location.

Hubs¶

My Hubs will show all hubs registered to your account. Choosing a particular hub will give a comprehensive look at all of the attributes of your hub, with the opportunity to observe all events that have taken place, by clicking on List Events. You can also view all of the devices that are registered to your hub.

Devices¶

My Devices will show all devices attached to any of your hubs. Choosing a particular device will give a comprehensive look at all of the attributes of your device, with the opportunity to observe all events that have taken place, by clicking on List Events.

SmartApps¶

My SmartApps will show all your custom (written or edited by you) SmartApps. You can view the SmartApp status, category, and locations from this list, as well as edit SmartApp metadata. You can click the SmartApp name to be taken to the editor where you can view and modify the code.

Device Types¶

My Device Types will show all your custom (written or edited by you) Device Type Handlers. You can view the status, supported capabilities, and sessions from this list, as well as edit the metadata associated with this Device Type Handler. You can click on the name to be taken to the editor, where you can view and modify the code.

Publication Requests¶

My Publication Requests will show all your publication requests for submissions to the SmartThings catalog, along with the publication request status.

Live Logging¶

Live Logging will show a live logging view for your SmartThings account. Here you will find logs for all your installed SmartApps and Device Type Handlers. You can also filter the logs by a specific SmartApp.

Creating a New SmartApp¶

To create a new SmartApp, click the New SmartApp button from the My SmartApps page.

There are three different tabs on the New SmartApp page that allow you to create a new SmartApp in different ways:

• From Form allows you to create a new SmartApp based on the some metadata you can enter into the form.
• From Code allows you to create a new SmartApp directly from existing code. This is useful if you receive the code for a SmartApp - just paste it in to the page and a new SmartApp will be created from it.
• From Template allows you to create a new SmartApp based upon existing SmartApps. This is especially useful if you are new to SmartThings development, since you can start from an existing SmartApp.

Creating a new Device Type Handler¶

To create a new Device Type, click the New SmartDevice button from the My Device Types page.

There are three different tabs on the New SmartDevice page that allow you to create a new Device Type Handler in different ways:

• From Form allows you to create a new Device Type Handler based on the some metadata you can enter into the form.
• From Code allows you to create a new Device Type Handler directly from existing code. This is useful if you receive the code for a Device Type Handler - just paste it in to the page and a new Device Type Handler will be created from it.
• From Template allows you to create a new Device Type Handler based upon existing Device Type Handlers. This is especially useful if you are new to SmartThings development, since you can start from an existing Device Type Handlers.

Using the Editor¶

The SmartThings web editor allows you to edit code, and provides syntax highlighting for easy code readability.

You can choose from a variety of themes, key maps, and font sizes to suit your preferences by clicking on the IDE Settings button above the editor frame.

Using the Simulator¶

The simulator allows you to test your SmartApps or Device Type Handlers within the IDE, and without requiring you to have the actual physical devices.

When you run your application in the IDE, it is always running in the simulation framework. The IDE simulator does two very important things to support simulation:

• It acts as a “Virtual Hub” that has virtual devices connected to it
• It acts as if it was the SmartThings Mobile application to receive and process status updates and support direct user actions on devices through a simulated mobile app control.

The IDE simulation environment also allows you to run the simulator attached to any of the “Locations” defined within your account.

When editing a SmartApp or Device Type Handler, you can see the simulator on the right of the page. You can choose a location and click the Set Location button, and then input any preferences required by the SmartApp or Device Type Handler. Click the Install button to run the simulator.

When simulating a SmartApp, any selected devices will appear in the IDE, along with controls to actuate the devices:

Log Console¶

Once installed in the simulator, you will see a log console on the bottom of the page. This is where any logging statements in your code will appear.

The most recent logging statements will appear at the top of the logging console.

For more information about logging, refer to the Logging chapter of this guide.

Logging Levels¶

The log instance currently supports these log levels, in decreasing order of severity:

Logging Examples¶

Consider the following simple SmartApp which sets up some switch devices and has an event handler method that will log how many switches are currently turned on.

preferences {
    section {
        input "switches", "capability.switch", multiple: true
    }
}

def installed() {
    log.debug "Installed with settings: ${settings}"
    initialize()
}

def updated() {
    log.debug "Updated with settings: ${settings}"
    unsubscribe()
    initialize()
}

def initialize() {
    subscribe(switches, "switch", someEventHandler)
}

def someEventHandler(evt) {
    // returns a list of the values for all switches
    def currSwitches = switches.currentSwitch

    def onSwitches = currSwitches.findAll { switchVal ->
        switchVal == "on" ? true : false
    }

    log.debug "${onSwitches.size()} out of ${switches.size()} switches are on"
}

Let’s start the above SmartApp execution in the IDE. The first thing that we can see are messages like this:

It is easy to see that the debug message came from the updated() method

def updated() {
    log.debug "Updated with settings: ${settings}"

But where did the other trace messages come from? These messages are coming from the SmartApp framework. The SmartApp framework automatically will provide certain information like this during the execution of a SmartApp. Try turning one of the switches on in the IDE. You will see some more of these trace messages coming from the SmartApp framework. You will also see the debug message in the someEventHandler() method.

log.debug "${onSwitches.size()} out of ${switches.size()} switches are on"

You should expect to see something like this in the console.

Lets see an example of how each one of the log levels look when output to the console. In the someEventHandler() method, I’ve added the following log messages for this example.

log.error "${onSwitches.size()} out of ${switches.size()} switches are on"
log.warn "${onSwitches.size()} out of ${switches.size()} switches are on"
log.info "${onSwitches.size()} out of ${switches.size()} switches are on"
log.debug "${onSwitches.size()} out of ${switches.size()} switches are on"
log.trace "${onSwitches.size()} out of ${switches.size()} switches are on"

The output is nice and color coordinated so we can visually see the severity of the various levels.

Finally, an example of how the logger can be used in a try/catch block instead of getting the exception.

try {
    def x = "some string"
    x.somethingThatDoesNotExist
} catch (all) {
    log.error "Something went horribly wrong!\n${all}"
}

Overview¶

The GitHub IDE integration allows you to integrate your forked SmartThingsPublic repository with the IDE. This allows you to easily view and work with SmartApps or Device Types already in the repository, as well as update the versions in your IDE with upstream repository changes, and make commits to your forked repository right from the IDE.

When you setup GitHub integration in the IDE, you will create a fork of the SmartThingsPublic repository in GitHub. This will then be the repository that the IDE will be connected to. When you add files from the repository to the IDE, this is the repository it will look at to get the available files. When you commit changes in the IDE, you are making commits in your remote forked repository.

You will need to manage the syncing of your forked repository with the original SmartThingsPublic repository, just as you would with any forked repository in GitHub.

Setup¶

To connect your GitHub account with the SmartThingsPublic repository in the IDE, follow these steps.

Step 1 - Enable GitHub Integration¶

Click the Enable GitHub Integration link on the My SmartApps or My Device Types page. This will launch a wizard that will guide you through the process.

Step 2 - Connect your GitHub Account to SmartThings¶

On Step 1 of the wizard, follow the instructions to authorize SmartThings to integrate with your GitHub account. Click the Next button after you have done this.

---

Step 3 - Create a Fork¶

Follow the instructions to fork the SmartThingsCommunity/SmartThingsPublic repository, and then click the Next button.

---

Step 4 - Clone the Forked Repository¶

Tip

While not required to for submitting changes, this is useful so that you have a local copy of the source code (useful for grepping the source locally, using your favorite editor, etc.), and is required to update your fork from the main SmartThingsPublic repository.

Follow these steps to clone your forked repository to your local machine (it is assumed that you have installed and configured Git on your local machine):

On the main page of your forked repository in GitHub, copy the HTTPS clone URL link:

In a terminal or command prompt, type:

git clone <clone URL copied as above>

Press Enter. This will create a local clone of your forked repository.

---

Step 5 - Configure Git to Sync Fork with SmartThings¶

If you chose to create a local clone of your forked repository, you should configure it get upstream changes from the original SmartThings repository.

On GitHub, navigate to the SmartThingsCommunity/SmartThingsPublic repository. On the right sidebar of the repository page, copy the clone URL:

Important

This is the clone URL for the main SmartThingsPublic repository, not your fork!

In a terminal or command prompt, change directories to the location of your cloned fork, and type:

git remote add upstream <remote URL as copied above>

It should look like this:

git remote add upstream https://github.com/SmartThingsCommunity/SmartThingsPublic.git

Press Enter.

In a terminal or command prompt, type:

git remote -v

This will show all the configured remotes. You should see an upstream remote configured for the SmartThingsPublic repository.

---

That’s it! You now have connected your GitHub account with the SmartThings IDE. You will now be able to commit changes made in the IDE to this repository, and update SmartApps and Device Types in the IDE from changes merged into this repository from other sources.

Repository Structure¶

The repository is organized by type (SmartApps or Device Types) and namespace.

Each SmartApp and Device Type should be in its own directory, named the same as the SmartApp or Device Type, and appended with ".src".

For SmartApps:

smartapps/<namespace>/<smartapp-name>.src/<smartapp file>.groovy

For Device Types:

devicetypes/<namespace>/<device-type-name>.src/<device type file>.groovy

The namespace is typically your GitHub user name. When you create a SmartApp or Device Type in the IDE, you provide a namespace, which is then populated in the definition method. This namespace will be used in the directory structure as shown above.

GitHub Integration IDE Tour¶

GitHub Actions Buttons¶

When you enable GitHub integration, you will see a few buttons added to the My SmartApps and My DeviceTypes pages in the IDE:

Commit Changes¶

Clicking the Commit Changes button will first prompt you to select what repository you want to commit to, and then launch a wizard allows you to commit any new or modified code to your forked repository. You can (and should) also add a commit message as you would normally do when making commits in Git.

Update from Repo¶

Clicking the Update from Repo button will first prompt you to select what repository you’d like to update from, and then launch a wizard that allows you to update your IDE code from your forked repository.

The wizard will display three columns, each of which is described below:

Tip

The files considered for this action will depend on if you are on the My SmartApps or My DeviceTypes page in the IDE. Only SmartApps will be considered if launched from My SmartApps, and only Device Types if launched from My DeviceTypes

Obsolete (updated in GitHub)

Entries showing in the Obsolete column represent files that you have included in the IDE, but have since been updated in your forked repository (with no conflicts existing). To update your IDE version, select the files you wish to update, and click the Execute Update button.

Conflicted (updated locally and in GitHub)

Entries showing in the Conflicted column represent files that have been modified both in the IDE and in your forked repository. To resolve these conflicts, select the files and click the Execute Update button.

New (only in GitHub)

Entries showing in the New column are any files found in your forked repository that are not currently in the IDE. To bring these files into your IDE, select the files and click the Execute Update button.

Note

When updating from the repo, you also have the ability to publish any updates (either for yourself or all) by checking the Publish check box.

Settings¶

This is where you can find information about the repository and branch integrated with the IDE, as well as actions to update, remove, or add new repositories.

How-To¶

Add Files from Repository to the IDE¶

To add files from your forked SmartThingsPublic repository into the IDE, follow these steps:

Step 1 - Navigate to the *My SmartApps* or *My Device Types* page in the IDE

The files available to add to the IDE vary depending upon the context. If you want to add SmartApps to your IDE, navigate to the My SmartApps page. If you want to add Device Types, navigate to the My Device Types.

Step 2 - Update from Repo

Click the Update from Repo button (above the list of SmartApps or Device Types), and select the repo you want to update from.

In the resulting wizard, select the files you want to add to the IDE in the New (only in GitHub) column.

Click the Execute Update button in the wizard.

The IDE will now have the files you selected.

---

Best Practices¶

FAQ¶

I don’t want to grant SmartThings access to my GitHub account. Is there a way around this?

Integrating the GitHub repositories with the IDE requires that you grant SmartThings read and write access to your GitHub repositories. If you would rather not grant SmartThings this level of access to your GitHub account, we recommend that you create a new GitHub user to use for SmartThings development. That will allow you to keep your primary GitHub account separate from the SmartThings account.

Do I have to use the GitHub integration?

No. The GitHub integration is optional.

Does this change the process for submitting SmartApps or Device Types to SmartThings ?

The process for submitting a publication request is essentially the same. The result is slightly different, in that the requests themselves become pull requests in the main SmartThingsPublic repository. This is similar to how it was working previously, but now the pull requests will be visible in the repository since the repository is public.

Can I just a make a pull request to the SmartThingsPublic repository, without using the GitHub IDE Integration?

If you make a pull request to the SmartThingsPublic repository, but have not enabled GitHub integration in the IDE, your pull request will not be reviewed or merged in to the SmartThingsPublic repository. Enabling GitHub integration is what allows us to connect your GitHub account with your SmartThings account. If you have enabled the GitHub integration, and then would rather make a pull request to the SmartThingsPublic repository (using the GitHub account you enabled in the IDE) instead of publishing through the IDE, you can. We think it’s more efficient to use the tools in the IDE, but nothing prevents you from making a pull request directly in this case.

Where can I find more information about working with Git?

See the Getting Help section.

I made a commit to my local GitHub fork (not using the IDE), but don’t see it when I try to Update from Repo in the IDE.

Did you push your changes to your forked GitHub repository and branch associated with the IDE? Only changes pushed to your forked repository are visible to the IDE - committing changes to your local repository only, without pushing them to the repository and branch associated with the IDE, will not be visible.

I made a commit through the IDE, but I don’t see it in my cloned forked repository.

Did you merge the latest changes into your local repository? Remember, when you make a commit in the IDE, you are making a commit to your forked version of the SmartThingsPublic repository. If you cloned the repository locally, you need to sync your local repository with the remote repository. See Keep Your Cloned Repo in Sync with Origin for more information.

I think I found a bug. How do I report it?

First, check out the Getting Help section below to see if any of the links may answer your questions. If you’re confident you’ve found a bug, and it’s not already discussed on the community forums, email support@smartthings.com. For the fastest response, be sure to include your SmartThings user name, your GitHub account name, and specific steps that caused the issue.

Getting Help¶

Here are some links for getting help working with Git and GitHub:

• GitHub
• GitHub Help Page
• GitHub Bootcamp - useful for getting started with Git.
• Fork a Repo - documentation on how to fork a repo in GitHub.
• Sync a Repo - documentation on how to sync a fork to the upstream repository.
• Pushing to a Remote - documentation on how to push to a remote repository.

If your questions are about the IDE integration, and aren’t answered in this documentation, the SmartThings Community Forums is a great place to leverage the power of our active community developers to help.

Finally, if you have ideas to help improve this documentation, feel free to contact docs@smartthings.com.

Types of SmartApps¶

Event-Handler SmartApps

Event Handler SmartApps are the most common apps developed by our community. They allow you to subscribe to events from devices and call a handler method upon their firing. This method can then do a variety of things, most commonly invoking a command on another device. We’re confident that if you are familiar with back end development of web sites, then you will be more than capable of developing SmartApps.

A very simple example of a SmartApp would involve you walking through a door and having the lights turn on automatically.

Solution Module SmartApps

These apps exist within the dashboard of the SmartThings app interface, and are containers for other SmartApps. The idea behind Solution Module SmartApps is to combine SmartApps that, in the real world, intuitively go together. One example of this would be the “Home & Family” section of the dashboard which allows you to see the comings and goings of your family.

Solution Module SmartApps have traditionally been built by our internal team, but we will be opening them up for external development in the near future.

Service Manager SmartApps

Service Manager SmartApps are used to connect to LAN or cloud devices, such as the Sonos or WeMo. They are the connecting glue between the unique protocols of your external devices and a device type handler you’d create for those devices. They discover devices and then continue to maintain the connection for those devices.

The Service Manager SmartApp must be installed when a user utilizes a device using LAN or the cloud, so for example, there is a Sonos Service Manager SmartApp that is installed when pairing with a Sonos.

SmartApp Structure¶

SmartApps take the form of a single Groovy script. A typical SmartApp script is composed of four sections: Definition, Preferences, Predefined Callbacks, and Event Handlers. There is also a Mappings section that is required for cloud-connected SmartApps that will be described later.

Definition

The defintion section of the SmartApp specifies the name of the app along with other information that identifies and describes it.

Preferences

The preferences section is responsible for defining the screens that appear in the mobile app when a SmartApp is installed or updated. These screens allow the user to specify which devices the SmartApp interacts with along with other configuration options that affect its behavior.

Pre-defined Callbacks

The following methods, if present, are automatically called at various times during the lifecycle of a SmartApp:

1. installed() - Called when a SmartApp is first installed
2. updated() - Called when the preferences of an installed smart app are updated
3. uninstalled() - Called when a SmartApp is uninstalled.
4. childUninstalled() - Called for the parent app when a child app is uninstalled

The installed and updated methods are commonly found in all apps. Since the selected devices may have changed when an app is updated, both of these methods typically set up the same event subscriptions, so it is common practice to put those calls in an initialize() method and call it from both the installed and updated methods.

The uninstalled method is typically not needed since the system automatically removes subscriptions and schedules when a SmartApp is uninstalled. However, they can be necessary in apps that integrate with other systems and need to perform cleanup on those systems.

Event Handlers

The remainder of the SmartApp contains the event handler methods specified in the event subscriptions and any other methods necessary for implementing the SmartApp. Event handler methods must have a single argument, which contains the Event object.

SmartApp Execution¶

SmartApps aren’t always running. Their various methods are executed when external events occur. SmartApps execute when any of the following types of events occur:

1. Pre-defined callback - Any of the predefined lifecycle events described above occur.
2. Device state change - An attribute changes on a device, which creates an event, which triggers a subscription, which calls a handler method within your SmartApp.
3. Location state change - A location attribute such as mode changes. Sunrise and sunset are other examples of location events
4. User action on the app - The user taps a SmartApp icon or shortcut in the mobile app UI
5. Scheduled event - Using a method like runIn(), you call a method within your SmartApp at a particular time .
6. Web services call Using our web services API, you create an endpoint accessible over the web that calls a method within your SmartApp.

Device Preferences¶

The most common type of input in the preferences section specifies what kind of devices a SmartApp works with. For example, to specify that an app requires one contact sensor:

input "contact1", "capability.contactSensor"

This will generate an input element in the mobile UI that prompts for the selection of a single contact sensor (capability.contactSensor). contact1 is the name of a variable that provides access to the device in the SmartApp.

Device inputs can also prompt for more than one device, so to ask for the selection of one or more switches:

input "switch1", "capability.switch", multiple: true

You can find more information about SmartApp preferences here

Event Subscriptions¶

Subscriptions allow a SmartApp to listen for events from devices, the location, and the SmartApp tile in the mobile UI. Device subscriptions are the most common and take the form:

subscribe ( device , “attribute[.value]” , handlerMethod )

For example, to subscribe to all events from a contact sensor you would write:

subscribe(contact1, "contact", contactHandler)

The contactHandler method would then be called whenever the sensor opened or closed. You can also subscribe to specific event values, so to call a handler only when the contact sensor opens write:

subscribe(contact1, "contact.open", contactOpenHandler)

The subscribe method call accepts either a device or a list of devices, so you don’t need to explicitly iterate over each device in a list when you specify multiple: true in an input preference.

You can learn more about subscribing to device events in the Events and Subscriptions section.

SmartApp Sandboxing¶

SmartApps are developed in a sandboxed environment. The sandbox is a way to limit developers to a specific subset of the Groovy language for performance and security. We have documented the main ways this should affect you.

Execution Location¶

With the original SmartThings Hub, all SmartApps execute in the SmartThings cloud. With the new Samsung SmartThings Hub, certain SmartApps may run locally on hub or in the SmartThings cloud. Execution location varies depending on a variety of factors, and is managed by the SmartThings internal team.

As a SmartThings developer, you should write your SmartApps to satisfy their specific use cases, regardless of where the app executes. There is currently no way to specify or force a certain execution location.

Rate Limiting¶

SmartApps that execute in the cloud are monitored for excessive resource utilization. Rate limiting ensures that no single SmartApp can consume too many shared cloud resources.

All rate limiting is based on an execution limit within a particular time window for an installed SmartApp or Device Handler. When the execution limit has been reached within the time window, no further executions will occur until the next time window. There will be an entry in the logs that will show the SmartApp or Device Type has been rate limited.

SmartApps are limited to executing 250 times in 60 seconds.

The common cause for exceeding this limit is excessive subscriptions. This may be an infinite loop of events (for example, subscribing to an “on” and “off” event, and the “on” command actually triggers the “off” event and vice versa - leading to a never-ending chain of event handlers being called). It’s also possible that a SmartApp that subscribes to a very large number of particularly “chatty” devices may run into this limit.

Additional rate limiting restrictions apply to SmartApps or Device Handlers that expose endpoints via the mappings definitions. You can learn about those in the SmartApp Web Services Guide.

Preferences Overview¶

Preferences are made up of one or more pages, which contain one or more sections, which in turn contain one more elements. The general form of creating preferences looks like:

preferences {
    page() {
        section() {
            paragraph "some text"
            input "motionSensors", "capability.motionSensor",
                title: "Motions sensors?", multiple: true
        }
        section() {
            ...
        }
    }
    page() {
        ...
    }
}

All inputs from the user are stored in a read-only map called settings. You can access the value entered by the user by indexing into the map using the name as the key (settings.someName)

Page Definition¶

Pages can be defined a couple different ways:

page(String pageName, String pageTitle) {}

preferences {
    // page with name and title
    page("page name", "page title") {
        // sections go here
    }
}

page(options) {}

This form takes a comma-separated list of name-value arguments.

preferences {
    page(name: "pageName", title: "page title",
         nextPage: "nameOfSomeOtherPage", uninstall: true) {
        // sections go here
    }
}

The valid options are:

name (required)

String - Identifier for this page.

title

String - The display title of this page

nextPage

String - Used on multi-page preferences only. Should be the name of the page to navigate to next.

install

Boolean - Set to true to allow the user to install this app from this page. Defaults to false. Not necessary for single-page preferences.

uninstall

Boolean - Set to true to allow the user to uninstall from this page. Defaults to false. Not necessary for single-page preferences.

We will see more in-depth examples of pages in the following sections.

Section Definition¶

Pages can have one or more sections. Think of sections as way to group the input you want to gather from the user.

Sections can be created in a few different ways:

section{}

preferences {
    // section with no title
    section {
        // elements go here
    }
}

section(String sectionTitle){}

preferences {
    // section with title
    section("section title") {
        // elements go here
    }
}

section(options, String sectionTitle) {}

preferences {
    // section will not display in IDE
    section(mobileOnly: true, "section title")
}

The valid options are:

hideable

Boolean - Pass true to allow the section to be collapsed. Defaults to false.

hidden

Boolean - Pass true to specify the section is collapsed by default. Used in conjunction with hideable. Defaults to false.

mobileOnly

Boolean - Pass true to suppress this section from the IDE simulator. Defaults to false.

Single Preferences Page¶

A single page preferences declaration is composed of one or more section elements, which in turn contain one or more elements. Note that there is no page defined in the example below. When creating a single-page preferences app, there’s no need to define the page explicitly - it’s implied. Here’s an example:

preferences {
    section("When activity on any of these sensors") {

        input "contactSensors", "capability.contactSensor",
            title: "Open/close sensors", multiple: true

        input "motionSensors", "capability.motionSensor",
            title: "Motion sensors?", multiple: true
    }
    section("Turn on these lights") {
        input "switches", "capability.switch", multiple: true
    }
}

Which would be rendered in the mobile app UI as:

Note that in the above example, we did not specify the name or mode input, yet they appeared on our preferences page. When defining single-page preferences, name and mode are automatically added. Also note that inputs that are marked as required: true are displayed differently by the mobile application, so that the user knows they are required. The mobile application will prevent the user from going to the next page or installing the SmartApp without entering required inputs.

Multiple Preferences Pages¶

Preferences can also be broken up into multiple pages. Each page must contain one or more section elements. Each page specifies a name property that is referenced by the nextPage property. The nextPage property is used to define the flow of the pages. Unlike single page preferences, the app name and mode control fields are not automatically added, and must be specified on the desired page or pages.

Here’s an example that defines three pages:

preferences {
    page(name: "pageOne", title: "When there's activity on any of these sensors", nextPage: "pageTwo", uninstall: true) {
        section("Choose sensors to trigger the action") {

            input "contactSensors", "capability.contactSensor",
                title: "Open/close sensors", multiple: true

            input "motionSensors", "capability.motionSensor",
                title: "Motion sensors?", multiple: true
        }
    }
    page(name: "pageTwo", title: "Turn on these lights", nextPage: "pageThree") {
        section {
            input "switches", "capability.switch", multiple: true
        }
    }
    page(name: "pageThree", title: "Name app and configure modes", install: true, uninstall: true) {
        section([mobileOnly:true]) {
            label title: "Assign a name", required: false
            mode title: "Set for specific mode(s)", required: false
        }
    }
}

The resulting pages in the mobile app would show the name and mode control fields only on the third page, and the uninstall button on the first and third pages:

Page 1	Page 2	Page 3

Preference Elements & Inputs¶

Preference pages (single or multiple) are composed of one or more sections, each of which contains one or more of the following elements:

paragraph¶

Text that’s displayed on the page for messaging and instructional purposes.

Example:

preferences {
    section("paragraph") {
        paragraph "This us how you can make a paragraph element"
        paragraph image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png",
                  title: "paragraph title",
                  required: true,
                  "This is a long description that rambles on and on and on..."
    }
}

The above preferences definition would render as:

Valid options:

title

String - The title of the paragraph

image

String - URL of image to use, if desired

required

Boolean - true or false to specify this input is required. Defaults to false.

icon¶

Allows the user to select an icon to be used when displaying the app in the mobile UI

Example:

preferences {
    section("paragraph") {
        icon(title: "required:true",
             required: true)
    }
}

The above preferences definition would render as:

Tapping the element would then allow the user to choose an icon:

Valid options:

title

String - The title of the icon

required

Boolean - true or false to specify this input is required. Defaults to false.

href¶

A control that selects another preference page or external HTML page.

Example of using href to visit a URL:

preferences {
    section("external") {
        href(name: "hrefNotRequired",
             title: "SmartThings",
             required: false,
             style: "external",
             url: "http://smartthings.com/",
             description: "tap to view SmartThings website in mobile browser")
    }
    section("embedded") {
        href(name: "hrefWithImage", title: "This element has an image and a long title.",
             description: "tap to view SmartThings website inside SmartThings app",
             required: false,
             image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png",
             url: "http://smartthings.com/")
    }
}

The above preferences would render as:

Example of using href to link to another preference page (dynamic pages are discussed later in this section):

preferences {
    page(name: "hrefPage")
    page(name: "deadEnd")
}

def hrefPage() {
    dynamicPage(name: "hrefPage", title: "href example page", uninstall: true) {
        section("page") {
            href(name: "href",
                 title: "dead end page",
                 required: false,
                 page: "deadEnd")
        }
    }
}

def deadEnd() {
    dynamicPage(name: "deadEnd", title: "dead end page") {
        section("dead end") {
            paragraph "this is a simple paragraph element."
        }
    }
}

You can use the params option to pass data to dynamic pages:

preferences {
    page(name: "firstPage")
    page(name: "secondPage")
}

def firstPage() {
    def hrefParams = [
        foo: "bar",
        someKey: "someVal"
    ]

    dynamicPage(name: "firstPage", uninstall: true) {
        section {
            href(name: "toSecondPage",
                 page: "secondPage",
                 params: hrefParams,
                 description: "includes params: ${hrefParams}")
        }
    }
}

// page def must include a parameter for the params map!
def secondPage(params) {
    log.debug "params: ${params}"
    dynamicPage(name: "secondPage", uninstall: true, install: true) {
        section {
            paragraph "params.foo = ${params?.foo}"
        }
    }
}

Valid options:

title

String - the title of the element

required

Boolean - true or false to specify this input is required. Defaults to false.

description

String - the secondary text of the element

external (deprecated - use style instead)

Boolean - true to open URL in mobile browser application, false to open URL within the SmartThings app. Defaults to false

style

String - Controls how the link will be handled. Specify “external” to launch the link in the mobile device’s browser. Specify “embedded” to launch the link within the SmartThings mobile application. Specify “page” to indicate this is a preferences page.

If style is not specified, but page is, then style:"page" is assumed. If style is not specified, but url is, then style:"embedded" is assumed.

Currently, Android does not support the “external” style option.

url

String - The URL of the page to visit. You can use query parameters to pass additional information to the URL (For example, http://someurl.com?param1=value1&param2=value1)

params

Map - Use this to pass parameters to other preference pages. If doing this, make sure your page definition method accepts a single parameter (that will be this params map). See the page-params-by-href example at the end of this document for more information.

page

String - Used to link to another preferences page. Not compatible with the external option.

image

String - URL of an image to use, if desired.

---

mode¶

Allows the user to select which modes the app executes in. Automatically generated by single-page preferences.

Example:

preferences {
    page(name: "pageOne", title: "page one", nextPage: "pageTwo", uninstall: true) {
        section("section one") {
            paragraph "just some text"
        }
    }
    page(name: "pageTwo", title: "page two") {
        section("page two section one") {
            mode(name: "modeMultiple",
                 title: "pick some modes",
                 required: false)
            mode(name: "modeWithImage",
                 title: "This element has an image and a long title.",
                 required: false,
                 multiple: false,
                 image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
        }
    }
}

The second page of the above example would render as:

Valid options:

title

String - the title of the mode field

required

Boolean - true or false to specify this input is required. Defaults to false.

multiple

Boolean - true or false to specify this input allows selection of multiple values. Defaults to true.

image

String - URL of an image to use, if desired.

Note

There are a couple of different ways to use modes that are worth pointing out. The first way is to use modes as a type of enum input like this:

input "modes", "mode", title: "only when mode is", multiple: true, required: false

This method will automatically list the defined modes as the options. Keep in mind when using modes in this way that the modes are just data and can be accessed in the SmartApp as such. This does not effect SmartApp execution. In this scenario, it is up to the SmartApp itself to react to the mode changes.

The second example actually controls whether the app is executed based on the modes selected:

mode(title: "set for specific mode(s)")

Both of these methods of using modes are valid. The impact on SmartApp execution is different in each scenario and it is up to the SmartApp developer to properly label whichever form is used and code the app accordingly.

label¶

Allows the user to name the app installation. Automatically generated by single-page preferences.

Example:

preferences {
    section("labels") {
        label(name: "label",
              title: "required:false",
              required: false,
              multiple: false)
        label(name: "labelRequired",
              title: "required:true",
              required: true,
              multiple: false)
        label(name: "labelWithImage",
              title: "This element has an image and a title.",
              description: "image and a title",
              required: false,
              image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
    }
}

The above preferences definition would render as:

Valid options:

title

String - the title of the label field

description

String - the default text in the input field

required

Boolean - true or false to specify this input is required. Defaults to false. Defaults to true.

image

String - URL to an image to use, if desired

preferences {
    section("section title") {
        // name is "temperature1", type is "number"
        input "temperature1", "number", title: "Temperature"
    }
}

preferences {
    section("section title") {
        input(name: "color", type: "enum", title: "Color", options: ["Red","Green","Blue","Yellow"])
    }
}

Dynamic Preferences¶

One of the most powerful features of multi-page preferences is the ability to dynamically generate the content of a page based on previous selections or external inputs, such as the data elements returned from a web services call. The following example shows how to create a two-page preferences SmartApp where the content of the second page depends on the selections made on the first page.

 preferences {
    page(name: "page1", title: "Select sensor and actuator types", nextPage: "page2", uninstall: true) {
        section {
            input("sensorType", "enum", options: [
                "contactSensor":"Open/Closed Sensor",
                "motionSensor":"Motion Sensor",
                "switch": "Switch",
                "moistureSensor": "Moisture Sensor"])

            input("actuatorType", "enum", options: [
                "switch": "Light or Switch",
                "lock": "Lock"]
            )
        }
    }

    page(name: "page2", title: "Select devices and action", install: true, uninstall: true)

}

def page2() {
    dynamicPage(name: "page2") {
        section {
            input(name: "sensor", type: "capability.$sensorType", title: "If the $sensorType device")
            input(name: "action", type: "enum", title: "is", options: attributeValues(sensorType))
        }
        section {
            input(name: "actuator", type: "capability.$actuatorType", title: "Set the $actuatorType")
            input(name: "action", type: "enum", title: "to", options: actions(actuatorType))
         }

    }
}

private attributeValues(attributeName) {
    switch(attributeName) {
        case "switch":
            return ["on","off"]
        case "contactSensor":
            return ["open","closed"]
        case "motionSensor":
            return ["active","inactive"]
        case "moistureSensor":
            return ["wet","dry"]
        default:
            return ["UNDEFINED"]
    }
}

private actions(attributeName) {
    switch(attributeName) {
        case "switch":
            return ["on","off"]
        case "lock":
            return ["lock","unlock"]
        default:
            return ["UNDEFINED"]
    }
}

The previous example shows how you can achieve dynamic behavior between pages. With the submitOnChange input attribute you can also have dynamic behavior in a single page.

preferences {
    page(name: "examplePage")
}

def examplePage() {
    dynamicPage(name: "examplePage", title: "", install: true, uninstall: true) {

        section {
            input(name: "dimmers", type: "capability.switchLevel", title: "Dimmers",
                  description: null, multiple: true, required: false, submitOnChange: true)
        }

        if (dimmers) {
            // Do something here like update a message on the screen,
            // or introduce more inputs. submitOnChange will refresh
            // the page and allow the user to see the changes immediately.
            // For example, you could prompt for the level of the dimmers
            // if dimmers have been selected:

            section {
                input(name: "dimmerLevel", type: "number", title: "Level to dim lights to...", required: true)
            }
        }
    }
}

Examples¶

page-params-by-href.groovy shows how to pass parameters to dynamic pages using the href element.

Almost every SmartApp makes use of preferences to some degree. You can browse them in the IDE under the “Browse SmartApp Templates” menu.

Overview¶

Recall that SmartApps (and Device Handlers) are not always running, but rather execute according to a certain schedule or in response to events being triggered. But what if we need our application to retain some information between executions? We can use state to persist data across executions.

Here’s a quick example showing how to work with state:

state.myData = "some data"
log.debug "state.myData = ${state.myData}"

state.myCounter = state.myCounter + 1

How it Works¶

Each executing instance of a SmartApp or Device Handler has access to a simple, map-like storage mechanism through the state property. When an application executes, it populates the state property from the backing store. The application can then interact with it, through simple map-like operations.

When the application is finished executing, the values in state are written back to persistent storage.

The contents of state are stored as a string, in JSON format. This means that anything stored in state must be serializable to JSON.

def installed() {
  state.installedAt = now()
}

def someEventHandler(evt) {
  def millisSinceInstalled = now() - state.installedAt
  log.debug "this app was installed ${millisSinceInstalled / 1000} seconds ago"

  // you can also create a Date object back from epoch time:
  log.debug "this app was installed at ${new Date(state.installedAt)}"
}

Using State¶

You can use state to store strings, numbers, lists, booleans, maps, etc. To use state, simply use the state variable that is injected into every SmartApp and Device Handler. You can think of it as a map that will persist its value across executions.

As usual, the best way to describe code is by showing code itself.

def installed() {
  // simple number to keep track of executions
  state.count = 0

  // we can store maps in state
  state.myMap = [foo: "bar", baz: "fee"]

  // booleans are ok of course
  state.myBoolean = true

  // we can use array index notation if we want
  state['key'] = 'value'

  // we can store lists and maps, so we can make some interesting structures
  state.myListOfMaps = [[key1: "val1", bool1: true],
                        [otherKey: ["string 1", "string 2"]]]

}

def someEventHandler(evt) {

  // increment by 1
  state.count = state.count + 1

  log.debug "this event handler has been called ${state.count} times since installed"

  log.debug "state.myMap.foo: ${state.myMap.foo}" // => prints "bar"

  // we can access state value using array notation if we wish
  log.debug "state['myBoolean']: ${state['myBoolean']}"

  // we can navigate our list of maps
  state.myListOfMaps.each { map ->
    log.debug "entry: $map"
    map.each {
      log.debug "key: ${it.key}, value: ${it.value}"
    }
  }

Atomic State¶

Since state is initialized from persistent storage when a SmartApp executes, and is written to storage only when the application is done executing, there is the possibility that another execution could happen within that time window, and cause the values stored in state to appear inconsistent.

Consider the scenario of a SmartApp that keeps a counter of executions. Each time the SmartApp executes, it increments the counter by 1. Assume that the initial value of state.counter is 0.

1. An execution (“Execution 1”) occurs, and increments state.counter by one:

state.counter = state.counter + 1 // counter == 1

2. Another execution (“Execution 2”) occurs before “Execution 1” has finished. It reads state.counter and increments it by one.

state.counter = state.counter + 1 // counter == 1!!!

Because “Execution 1” hasn’t finished executing by the time that “Execution 2” begins, the value of counter is still 0!

Additionally, because the contents of state are only persisted when execution is complete, it’s also possible to inadvertently overwrite values (last finished execution “wins”).

To avoid this type of scenario, you can use atomicState. atomicState writes to the data store when a value is set, and reads from the data store when a value is read - not just when the application execution initializes and completes. You use it just as you would use state:

atomicState.counter = atomicState.counter + 1.

Examples¶

Here are some SmartApps that make use of state. You can find them in the IDE along with the other example SmartApps.

• “Smart Nightlight” - shows using state to store time information.
• “Laundry Monitor” - uses state to store boolean state and time information.
• “Good Night” - shows using state to store time information, including constructing a Date object from a value stored in state.

Subscribe to Specific Device Events¶

The most common use case for event subscriptions is for device events:

subscribe(deviceName, “eventToSubscribeTo”, handlerMethodName)

preferences {
    section {
        input "theSwitch", "capability.switch"
    }
}

def install() {
    subscribe(theSwitch, "switch.on", switchOnHandler)
}

def switchOnHandler(evt) {
    log.debug "switch turned on!"
}

The handler method must accept an event parameter.

Refer to the Event API documentation for more information about the Event object.

You can find the possible events to subscribe to by referring to the Attributes column for a capability in the Capabilities Reference. The general form we use is “<attributeName>.<attributeValue>”. If the attribute does not have any possible values (for example, “battery”), you would just use the attribute name.

In the example above, the switch capability has the attribute “switch”, with possible values “on” and “off”. Putting these together, we use “switch.on”.

Subscribe to All Device Events¶

You can also subscribe to all states by just specifying the attribute name:

subscribe(theSwitch, "switch", switchHandler)

def switchHandler(evt) {
    if (evt.value == "on") {
        log.debug "switch turned on!"
    } else if (evt.value == "off") {
        log.debug "switch turned off!"
    }
}

In this case, the switchHandler method will be called for both the “on” and “off” events.

Subscribe to Multiple Devices¶

If your SmartApp allows multiple devices, you can subscribe to events for all the devices:

preferences {
    section {
        input "switches", "capability.switch", multiple: true
    }
}

def installed() {
    subscribe(switches, "switch", switchesHandler)
}

def switchesHandler(evt) {
    log.debug "one of the configured switches changed states"
}

Subscribe to Location Events¶

In addition to subscribing to device events, you can also subscribe to events for the user’s location.

You can subscribe to the following location events:

mode

Triggered when the mode changes.

position

Triggered when the geofence position changes for this location. Does not get triggered when the fence is widened or narrowed - only fired when the position changes.

sunset

Triggered at sunset for this location.

sunrise

Triggered at sunrise for this location.

sunriseTime

Triggered around sunrise time. Used to get the time of the next sunrise for this location.

sunsetTime

Triggered around sunset time. Used to get the time of the next sunset for this location.

Pass in the location property automatically injected into every SmartApp as the first parameter to the subscribe method.

subscribe(location, "mode", modeChangeHandler)

// shortcut for mode change handler
subscribe(location, modeChangeHandler)

subscribe(location, "position", positionChange)
subscribe(location, "sunset", sunsetHandler)
subscribe(location, "sunrise", sunriseHandler)
subscribe(location, "sunsetTime", sunsetTimeHandler)
subscribe(location, "sunriseTime", sunriseTimeHandler)

Refer to the Sunset and Sunrise section for more information about sunrise and sunset.

The Event Object¶

Event-handler methods must accept a single parameter, the event itself.

Refer to the Event API documentation for more information.

A few of the common ways of using the event:

def eventHandler(evt) {
    // get the event name, e.g., "switch"
    log.debug "This event name is ${evt.name}"

    // get the value of this event, e.g., "on" or "off"
    log.debug "The value of this event is ${evt.value}"

    // get the Date this event happened at
    log.debug "This event happened at ${evt.date}"

    // did the value of this event change from its previous state?
    log.debug "The value of this event is different from its previous value: ${evt.isStateChange()}"
}

See Also¶

• Sunset and Sunrise
• Event API Documentation
• Location API Documentation
• Interacting with Devices

Device Overview¶

Devices are the “things” that SmartApps interact with. Devices may support one or many capabilities.

Capabilities represent the things a device knows (attributes) and the things they can do (commands). They are an abstraction that allows us to work with many different manufacturer’s devices transparently.

To build a flexible SmartApp, we should write our SmartApp to work with any device that supports a given capability. We don’t want to write a SmartApp that only works with a specific manufacturer’s switch for example. We want to write an app that works with any device that supports the switch capability.

Preferences - Selecting the Devices¶

To allow the user to select devices that support a given capability, we use the preferences input element:

preferences {
    section {
        input "presenceSensors", "capability.presenceSensor"
    }
}

The above example will allow the user to select any device that supports the presence sensor capability. This could be a mobile phone, or a SmartSense presence sensor. We don’t care about the specific device - we just declare we want a device that supports the presence sensor capability.

You can refer to the Capabilities Reference for information on all the supported capabilities. The “Preferences Reference” column tells you what to use in your preferences for a given capability.

Interacting with Devices¶

After you have declared the devices your SmartApp needs to interact with, a Device object instance will be available in your SmartApp, with the name that you provided.

preferences {
    section {
        input "theSwitch", "capability.switch"
    }
}

def someEventHandler(evt) {
    theSwitch.on()
}

Device Attributes¶

Attributes represent the state of a device. A device that supports the “temperatureMeasurement” capability has a “temperature” attribute, for example.

Attributes have state - the “temperature” attribute has an associated State object that contains information about the temperature (its value, the date it was recorded, etc.)

Device Commands¶

Devices may expose one or many commands. Commands are the things that devices can do. A switch supports the “on” and “off” commands, that turn the switch “on” and “off”, respectively.

Not all devices have commands. Commands typically perform some sort of physical actuation (turn a switch on, or unlock a lock, for example). A humidity sensor has nothing to physically actuate, for example.

Getting Device Current Values¶

You can retrieve information about a device’s current state in a few ways.

The currentState method and <attributeName>State properties both return a State object representing the current state of this device.

preferences {
    section {
        input "tempSensor", "capability.temperatureMeasurement"
    }
}

def someEventHandler(evt) {

    def currentState = tempSensor.currentState("temperature")
    log.debug "temperature value as a string: ${currentState.value}"
    log.debug "time this temperature record was created: ${currentState.date}"

    // shortcut notation - temperature measurement capability supports
    // a "temperature" attribute. We then append "State" to it.
    def anotherCurrentState = tempSensor.temperatureState
    log.debug "temperature value as an integer: ${anotherCurrentState.integerValue}"
}

You can get the current value directly by using the currentValue(attributeName) and its shortcut, current<Uppercase attribute name>:

preferences {
    section {
        input "myLock", "capability.lock"
    }
}

def someEventHandler(evt) {
    def currentValue = myLock.currentValue("lock")
    log.debug "the current value of myLock is $currentValue"

    // Lock capability has "lock" attribute.
    // <deviceName>.current<uppercase attribute name>:
    def anotherCurrentValue = myLock.currentLock
    log.debug "the current value of myLock using shortcut is: $anotherCurrentValue"
}

Querying Event History¶

To get a list of events in reverse chronological order (newest first), use the events() method:

// returns the last 10 by default
myDevice.events()

// use the max option to get more results
myDevice.events(max: 30)

To get a list of events in reverse chronological order (newest first) since a given date, use the eventsSince method:

// get all events for this device since yesterday (maximum of 1000 events)
myDevice.eventsSince(new Date() - 1)

// get the most recent 20 events since yesterday
myDevice.eventsSince(new Date() - 1, [max: 20])

To get a list of events between two dates, use the eventsBetween method:

// get all events between two days ago and yesterday (up to 1000 events)
// returned events sorted in inverse chronological order (newest first)
myDevice.eventsBetween(new Date() - 2, new Date() - 1)

// get the most recent 50 events in the last week
myDevice.eventsBetween(new Date() - 7, new Date(), [max: 50])

Similar date-constrained methods exist for getting State information for a device.

Refer to the full Device API documentation for more information.

Sending Commands¶

SmartApps often need to send commands to a device - tell a switch to turn on, or a lock to unlock, for example.

The commands available to your device will vary by device. You can refer to the Capabilities Reference to see the available commands for a given capability.

Sending a command is as simple as calling the command method on the device:

myLock.lock()
myLock.unlock()

Some commands may expect parameters. All commands can take an optional map parameter, as the last argument, to specify delay time in milliseconds to wait before the command is sent to the device:

// wait two seconds before sending on command
mySwitch.on([delay: 2000])

Interacting with Multiple Devices¶

If you specified multiple:true in your device preferences, the user may have selected more than one device. Your device instance will refer to a list of objects if this is the case.

You can send commands to all the devices without needing to iterate over each one:

preferences {
    section {
        input "switches", "capability.switch", multiple: true
    }
}

def someEventHandler(evt) {
    log.debug "will send the on() command to ${switches.size()} switches"
    switches.on()
}

You can also retrieve state and event history for multiple devices, using the methods discussed above. Instead of single values or objects, they will return a list of values or objects.

Here’s a simple example of getting all switch state values and logging the switches that are on:

preferences {
    section {
        input "switches", "capability.switch", multiple: true
    }
}

def someEventHandler(evt) {
    // returns a list of the values for all switches
    def currSwitches = switches.currentSwitch

    def onSwitches = currSwitches.findAll { switchVal ->
        switchVal == "on" ? true : false
    }

    log.debug "${onSwitches.size() out of ${switches.size()} switches are on"
}

See Also¶

• Capabilities Reference
• Preferences and Settings
• Events and Subscriptions
• Device API Documentation
• Event API Documentation
• State API Documentation

Overview¶

Modes can be thought of as behavior filters for the smart home. Users can change how things act or behave based on the mode you’re in. For example:

• When in “Home” mode, motion should turn on a light.
• When in “Away” mode, motion should send a text message and turn on an alarm.

SmartThings comes with a few pre-configured modes, such as “Home”, “Away”, and “Night”. Users can also create their own modes for each location.

Getting the Current Mode¶

You can get the current mode by using the mode or currentMode property on the location in a SmartApp:

def currMode = location.mode // "Home", "Away", etc.
log.debug "current mode is $currMode"

def anotherWay = location.currentMode
log.debug "current mode is $anotherWay"

Getting all Modes¶

You can get a list of all the modes for the location the SmartApp is installed into:

def allModes = location.modes // ex: [Home, Away, Night]
log.debug "all modes for this location: $allModes"

Setting the Mode¶

You can use setLocationMode() or location.setMode() to set the mode for the location:

setLocationMode("Away")

location.setMode("Away")

These methods will raise an error if the mode specified does not exist for the location.

Allowing Users to Select Modes¶

In the SmartApp preferences block, you can specify that the user select a mode by using the "mode" input type:

input "modes", "mode", title: "select a mode(s)", multiple: true

This will allow the user to select a mode (or multiple modes), and the SmartApp can then vary its behavior based upon the mode(s) selected.

You can also use the mode() method to allow a user to select a mode that this SmartApp will execute for:

mode(title: "Set for specific mode(s)")

The SmartApp will then only execute when in the selected mode, without any action needed by the developer to determine the correct mode.

You can learn more about the various ways to allow a user to select a mode here.

Mode Events¶

You can listen for a mode change by subscribing to the "mode" on the location object:

def installed() {
    subscribe(location, "mode", modeChangeHandler)
}

def modeChangeHandler(evt) {
    log.debug "mode changed to ${evt.value}"
}

In the example above modeChangeHandler() will be called whenever the mode changes for the location this SmartApp is installed into.

Example¶

The following example is a simplified version of the “Scheduled Mode Change” SmartApp. You can view the SmartApp in the IDE templates for the full example.

This example shows how to use the "mode" input type to ask the user to select a mode, and then (based on the user-defined schedule), changes the mode as specified.

preferences {
    section("At this time every day") {
                  input "time", "time", title: "Time of Day"
        }
    section("Change to this mode") {
        input "newMode", "mode", title: "Mode?"
    }
}

def installed() {
    initialize()
}

def updated() {
    unschedule()
    initialize()
}

def initialize() {
    schedule(time, changeMode)
}

def changeMode() {
    log.debug "changeMode, location.mode = $location.mode, newMode = $newMode, location.modes = $location.modes"

    if (location.mode != newMode) {
        if (location.modes?.find{it.name == newMode}) {
            setLocationMode(newMode)
        }  else {
            log.warn "Tried to change to undefined mode '${newMode}'"
        }
    }
}

In the changeMode() method above, there are a few things worth calling out.

First, notice we first check if we are already in the mode specified - if we are, we don’t do anything:

if (location.mode != newMode)

If we do need to change the mode, we first verify that the mode actually exists. This ensures that we don’t try and set the mode to one that does not exist for the location.

if (location.modes?.find{it.name == newMode})

Further Reading¶

• Mode Input
• Location Object
• Mode Object

Overview¶

Routines allow for certain things to happen whenever it executes. SmartThings comes with a few routines already installed:

• Good Morning! - You or the house is waking up
• Good Night! - You or the house is going to sleep
• Goodbye! - You’re leaving the house
• I’m Back! - You’ve returned to the house

Each routine can be configured to do certain things. For example, when “I’m Back!” executes, you can set the mode to “Home”, unlock doors, adjust the thermostat, etc.

Routines exist for each location in a SmartThings account.

Get Available Routines¶

You can get the routines for the location the SmartApp is installed into by accessing the helloHome object on the location:

def actions = location.helloHome?.getPhrases()*.label

Execute Routines¶

To execute a Routine, you can call the execute() method on helloHome:

location.helloHome?.execute("Good Night!")

Allowing Users to Select Routines¶

A SmartApp may want to allow a user to execute certain Routines in a SmartApp. Since the routines for each location will vary, we need to get the available routines, and use them as options for an enum input type.

This needs to be done in a dynamic preferences page, since we need to execute some code to populate the available actions:

preferences {
    page(name: "selectActions")
}

def selectActions() {
    dynamicPage(name: "selectActions", title: "Select Hello Home Action to Execute", install: true, uninstall: true) {

        // get the available actions
            def actions = location.helloHome?.getPhrases()*.label
            if (actions) {
            // sort them alphabetically
            actions.sort()
                    section("Hello Home Actions") {
                            log.trace actions
                // use the actions as the options for an enum input
                input "action", "enum", title: "Select an action to execute", options: actions
                    }
            }
    }
}

You can read more about the enum input type and dynamic pages here.

You can then access the selected phrase like so:

def selectedAction = settings.action

Example¶

This example simply shows executing a selected routine when a switch turns on, and another action when a switch turns off:

preferences {
    page(name: "configure")
}

def configure() {
    dynamicPage(name: "configure", title: "Configure Switch and Phrase", install: true, uninstall: true) {
            section("Select your switch") {
                    input "theswitch", "capability.switch",required: true
            }

            def actions = location.helloHome?.getPhrases()*.label
            if (actions) {
            actions.sort()
                    section("Hello Home Actions") {
                            log.trace actions
                input "onAction", "enum", title: "Action to execute when turned on", options: actions, required: true
                input "offAction", "enum", title: "Action to execute when turned off", options: actions, required: true
                    }
            }
    }
}

def installed() {
    log.debug "Installed with settings: ${settings}"
    initialize()
}

def updated() {
    log.debug "Updated with settings: ${settings}"
    unsubscribe()
    initialize()
}

def initialize() {
    subscribe(theswitch, "switch", handler)
    log.debug "selected on action $onAction"
    log.debug "selected off action $offAction"
}

def handler(evt) {
    if (evt.value == "on") {
            log.debug "switch turned on, will execute action ${settings.onAction}"
            location.helloHome?.execute(settings.onAction)
    } else {
        log.debug "switch turned off, will execute action ${settings.offAction}"
            location.helloHome?.execute(settings.offAction)
    }
}

Further Reading¶

• Preferences and Settings Guide

Schedule From Now¶

A SmartApp may want to take some action in a certain amount of time after some event has occurred. Consider a few examples:

• When a door closes, turn a light off after two minutes.
• When everyone leaves, adjust the thermostat after ten minutes.
• If a door opens and is not shut after five minutes, send a notification.

All these scenarios follow a common pattern: when a certain event happens, take some action after a given amount of time. This can be accomplished this by using the runIn method.

runIn(seconds, method, options)

Executes the specified method in the specified number of seconds from now:

def someEventHandler(evt) {
    // execute handler in five minutes from now
    runIn(60*5, handler)
}

def handler() {
    switch.off()
}

options

Optional. Map of options. Valid options:

[overwrite: true or false]

By default, if a method is scheduled to run in the future, and then another call to runIn with the same method is made, the last one overwrites the previously scheduled method. This is usually preferable. Consider the situation if we have a switch scheduled to turn off after five minutes of a door closing. First, the door closes at 2:50 and we schedule the switch to turn off after five minutes (2:55). Then two minutes later (2:52), the door opens and closes again - another call to runIn will be made to schedule the switch to turn off in five minutes from now (2:57). If we specified [overwrite: false], we’d now have two schedules to turn off the switch - one at 2:55, and one at 2:57. So, if you do specify [overwrite: false], be sure to write your handler so that it can handle multiple calls.

def someEventHandler(evt) {
    runIn(300, handler, [overwrite: false])
}

def handler() {
    // need to handle multiple calls since overwrite:false specified
}

Run Once in the Future¶

Some SmartApps may need to schedule certain actions to happen once at a specific time and date. runOnce handles this case.

runOnce(dateTime, handlerMethod, options)

Executes the handlerMethod once at the specified date and time. The dateTime argument can be either a Date object or a date string.

options

Optional. Map of options. Valid options:

[overwrite: true or false]

Specify [overwrite: false] if you do not want the most recently created job for the handlerMethod to overwrite an existing job. See the discussion in the runIn documentation above for more information.

def someEventHandler(evt) {
    // execute handler tomorrow, at the current time
    runOnce(new Date() + 1, handler)
}

def handler() {
    switch.off()
}

def someEventHandler(evt) {
    // execute handler at 4 PM CST on October 21, 2015 (e.g., Back to the Future 2 Day!)
    runOnce("2015-10-21T16:00:00.000-0600", handler)
}

def handler() {
    // do something awesome, like ride a hovercraft
}

Run on a Schedule¶

Oftentimes, there is a need to schedule a job to run on a specific schedule. For example, maybe you want to turn the lights off at 11 PM every night. SmartThings provides the schedule method to allow you to create recurring schedules.

The various schedule methods follow a similar form - they take an argument representing the desired schedule, and the method to be called on this schedule. Each SmartApp or device-type handler can only have one handler method scheduled at any time. This means that, unlike runIn or runOnce, a job created with schedule must either execute or be canceled with the unschedule method before you can schedule another job with the same method. The schedule method does not accept the overwrite option like runOnce and runIn.

schedule(dateTime, handlerMethod)

Creates a scheduled job that calls the handlerMethod every day at the time specified by the dateTime argument. The dateTime argument can be a String, Date, or number (to schedule based on Unix epoch time).

Only the time information will be used to derive the recurring schedule.

Here’s how you might use a preference to set up a daily scheduled job:

preferences {
    section("Time to run") {
        input "time1", "time"
    }
}

...

def someEventHandler(evt) {
    schedule(time1, handlerMethod)
}

def handlerMethod() {
    ...
}

Of course, you can create and pass the dateTime string explicitly:

def someEventHandler(evt) {
    // call handlerMethod every day at 3:36 PM CST
    schedule("2015-01-09T15:36:00.000-0600", handlerMethod)
}

def handlerMethod() {
    ...
}

You can also pass a Groovy Date object:

def someEventHandler(evt) {
    // call handlerMethod every day at the current time
    schedule(new Date(), handlerMethod)
}

def handlerMethod() {
    ...
}

Finally, you can pass a Long representing the desired time in milliseconds (using Unix time) to schedule:

def someEventHandler(evt) {
    // call handlerMethod every day, at two minutes from the current time
    schedule(now() + 120000, handlerMethod)
}

def handlerMethod() {
    ...
}

Scheduling jobs to execute at a particular time is useful, but what if we want to execute a job at some other interval? What if, for example, we want a method to execute at fifteen minutes past the hour, every hour?

SmartThings allows you to pass a cron expression to the schedule method to accomplish this. A cron expression is based on the cron UNIX tool, and is a way to specify a recurring schedule. They are extremely powerful, but can be pretty confusing.

schedule(cronExpression, handlerMethod)

Creates a scheduled job that calls the handlerMethod according to the specified cronExpression.

def someEventHandler(evt) {
    // execute handlerMethod every hour on the half hour.
    schedule("0 30 * * * ?", handlerMethod)
}

def handlerMethod() {
    ...
}

Scheduled jobs are limited to running no more often than once per minute.

In addition to creating schedules using cron expressions, SmartThings also provides some convenience methods to set up the schedule for you. They are in the form of runEveryXMinutes(handlerMethod) or runEveryXHours(handlerMethod).

These methods work by creating a random start time in the X minutes or hours, and then every X minutes or hours after that. For example, runEvery5Minutes(handlerMethod) will execute handlerMethod at a random time in the next five minutes, and then run every five minutes from then.

These methods have the advantage of randomizing the start time for schedules, which can reduce the load on the SmartThings cloud. As such, they should be preferred over cron expressions when available.

The currently available methods are:

runEvery5Minutes(handlerMethod)

runEvery10Minutes(handlerMethod)

runEvery15Minutes(handlerMethod)

runEvery30Minutes(handlerMethod)

runEvery1Hour(handlerMethod)

runEvery3Hours(handlerMethod)

Other Scheduling-related Methods¶

canSchedule()

returns true if a job can be scheduled, false otherwise. Only four jobs may be scheduled for the future at any time.

def someEventHandler(evt) {
    runIn(300, someHandlerMethod1)
    runIn(300, someHandlerMethod2)
    runIn(300, someHandlerMethod3)
    runIn(300, someHandlerMethod4)

    // false, since we already have four jobs scheduled
    canSchedule()
}

unschedule(nameOfMethod = ‘’)

Removes the method from the schedule queue, if specified. Note that this is not specific to jobs created with any of the schedule methods - any job scheduled for the future (using runIn, runOnce, or any of other scheduling methods) may be canceled using unschedule.

// unschedule the someHandlerMethod
unschedule("someHandlerMethod")

unschedule can also be called with no arguments to unschedule all jobs.

// unschedule all jobs
unschedule()

Scheduling Limitations, Best Practices, and Things Good to Know¶

When using any of the scheduling APIs, it’s important to understand some limitations and best practices. These limitations are due in part to the fact that execution occurs in the cloud, and are thus subject to limiting factors like load, network connectivity, etc.

Do not expect exact execution time in scheduled jobs

SmartThings will try to execute your scheduled job at the specified time, but cannot guarantee it will execute at that exact moment. As a general rule of thumb, you should expect that your job will be called within the minute of scheduled execution. For example, if you schedule a job at 5:30:20 (20 seconds past 5:30) to execute in five minutes, we expect it to be executed at some point in the 5:35 minute.

When using runIn with values less than one minute, your mileage will vary.

Do not use runIn to set up a recurring schedule of less than sixty seconds

You may have noticed that none of the schedule APIs allow you to schedule jobs for less than sixty second intervals. You may be tempted to work around this limitation by using runIn to create such a schedule (i.e., a handler method that reschedules itself). This is discouraged, and at some point may be prevented by the SmartThings framework.

The primary reason for discouraging jobs that run more often than every sixty seconds is overall system resource utilization. Using runIn to circumvent this is problematic because any failure to execute, even once, will cause the scheduled event to stop triggering.

Only four jobs may be scheduled at any time

To prevent any one SmartApp or device-type handler from using too many resources, only four jobs may be scheduled for future execution at any time.

Do not excessively schedule/poll

While there are some limitations in place to prevent excessive scheduling, it’s important to note that excessive polling or scheduling is discouraged. It is one of the items we look for when reviewing community-developed SmartApps or device-type handlers.

Missed job executions will not accumulate

Due to a variety of issues (perhaps the local Internet connection has been dropped, or there is heavy load on the SmartThings server, or some other extreme circumstance), it’s possible that a scheduled job could be missed. For example, say you have set up a job to execute every minute, and for some reason, it doesn’t execute for three minutes.

When the job does execute again, it will resume its schedule (once every minute) - your handler won’t suddenly be called three times, for example.

unschedule can take several seconds to execute

As discussed above, unschedule is currently a potentially expensive operation.

We plan to address this in the near future. Until we do, be aware of the potential performance impacts of calling unschedule.

Examples¶

These SmartApps can be viewed in the IDE using the “Browse Templates” button:

• “Once a Day” uses schedule to turn switches on and off every day at a specified time.
• “Turn It On For 5 Minutes” uses runIn to to turn a switch off after five minutes.
• “Left It Open” uses runIn to see if a door has been left open for a specified number of minutes.
• “Medicine Reminder” uses schedule to check if a medicine door has been opened at a certain time.

Sunrise and Sunset Events¶

Using the sunrise and sunset events is the preferred (and simpler) way to take some action at (or around) sunrise or sunset. It is required that the location has set up a geofence.

Taking action at sunrise or sunset

If you wish to have certain actions take place at sunrise or sunset, you can use the sunrise and sunset events. These events will be fired at (gasp!) sunrise and sunset times for the user’s location.

You can subscribe to the events by passing in the location (automatically injected into every SmartApp), the event (“sunrise” or “sunset”), and your handler method:

def installed() {
    subscribe(location, "sunset", sunsetHandler)
    subscribe(location, "sunrise", sunriseHandler)
}

def sunsetHandler(evt) {
    log.debug "Sun has set!"
    ...
}

def sunriseHandler(evt) {
    log.debug "Sun has risen!"
    ...
}

Taking action before or after sunrise/sunset times

If you want to take some action a certain amount of time before or after sunset or sunrise, you can use the “sunriseTime” and “sunsetTime” events. These events are fired every day around the time of sunset or sunrise, and their value is the next sunrise or sunset. You can use this information to calculate an offset so that some action happens a certain amount of time before or after sunrise or sunset.

To use, you can subscribe to the events by passing the location, the event (“sunriseTime” or “sunsetTime”), and the handler method.

Consider the following example that turns on lights a specified number of minutes before sunset for the user’s location:

preferences {
    section("Lights") {
        input "switches", "capability.switch", title: "Which lights to turn on?"
        input "offset", "number", title: "Turn on this many minutes before sunset"
    }
}

def installed() {
    initialize()
}

def updated() {
    unsubscribe()
    initialize()
}

def initialize() {
    subscribe(location, "sunsetTime", sunsetTimeHandler)

    //schedule it to run today too
    scheduleTurnOn(location.currentValue("sunsetTime"))
}

def sunsetTimeHandler(evt) {
    //when I find out the sunset time, schedule the lights to turn on with an offset
    scheduleTurnOn(evt.value)
}

def scheduleTurnOn(sunsetString) {
    //get the Date value for the string
    def sunsetTime = Date.parse("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", sunsetString)

    //calculate the offset
    def timeBeforeSunset = new Date(sunsetTime.time - (offset * 60 * 1000))

    log.debug "Scheduling for: $timeBeforeSunset (sunset is $sunsetTime)"

    //schedule this to run one time
    runOnce(timeBeforeSunset, turnOn)
}

def turnOn() {
    log.debug "turning on lights"
    switches.on()
}

Because the sunriseTime and sunsetTime events are fired every day for the next sunrise/sunset event, we use runOnce to schedule one execution. Sunrise and sunset times change, so the next time the events are fired, we will create another scheduled execution using the runOnce method for that time.

We want it to run today too, so we use the sunsetTime value of the user’s location to schedule the lights to turn on today.

Looking up Sunrise or Sunset Directly¶

SmartApps can use the provided getSunriseAndSunset methods to get the sunrise and sunset time. You can pass in a ZIP code, which can be useful if the user has not set a geofence for their location.

getSunriseAndSunset(Map options)

The supported options are:

zipCode

Optional. The ZIP code to get the sunrise and sunset data for. Defaults to the user’s location if not provided.

sunsetOffset

Optional. A string in the format of “HH:MM” to specify how long or after sunset to return. Use the “-” symbol to indicate time should be before sunset (“-00:30” for 30 minutes prior to sunset)

sunriseOffset

Optional. A string in the format of “HH:MM” to specify how long or after sunrise to return. Use the “-” symbol to indicate time should be before sunrise (“-00:30” for 30 minutes prior to sunrise)

date

Optional. If you want to find the sunrise or sunset time for a date other than today, you can specify a Date object.

The return value is a map in the following form:

[sunrise: Date, sunset: Date]

def initialize() {
    def noParams = getSunriseAndSunset()
    def beverlyHills = getSunriseAndSunset(zipCode: "90210")
    def thirtyMinsBeforeSunset = getSunriseAndSunset(sunsetOffset: "-00:30")

    log.debug "sunrise with no parameters: ${noParams.sunrise}"
    log.debug "sunset with no parameters: ${noParams.sunset}"
    log.debug "sunrise and sunset in 90210: $beverlyHills"
    log.debug "thirty minutes before sunset at current location: ${thirtyMinsBeforeSunset.sunset}"

}

Polling for Sunrise/Sunset¶

You may have seen some SmartApp code that runs a task sometime after midnight (usually in a method called “astroCheck”) and calls a third party weather API to get the sunrise/sunset times. This is strongly discouraged now; it is much more efficient to use location events as they do not rely on third party services.

Examples¶

You can refer to these example SmartApps in the IDE to see how sunrise and sunset can be used:

• Smart Nightlight
• Sunrise/Sunset

You can also refer to the following examples in Github:

• Sunset Event Example
• Sunset Offset Example
• Sunset by ZIP Code Example

Configuring The Request¶

The various APIs for making HTTP requests all accept a map of parameters that define various information about the request:

Handling The Response¶

The HTTP APIs accept a closure that will be called with the response information from the reqeust.

The closure is passed an instance of a HttpResponseDecorator. You can inspect this object to get information about the response.

Here’s an example of getting various response information:

def params = [
    uri: "http://httpbin.org",
    path: "/get"
]

try {
    httpGet(params) { resp ->
        // iterate all the headers
        // each header has a name and a value
        resp.headers.each {
           log.debug "${it.name} : ${it.value}"
        }

        // get an array of all headers with the specified key
        def theHeaders = resp.getHeaders("Content-Length")

        // get the contentType of the response
        log.debug "response contentType: ${resp.contentType}"

        // get the status code of the response
        log.debug "response status code: ${resp.status}"

        // get the data from the response body
        log.debug "response data: ${resp.data}"
    }
} catch (e) {
    log.error "something went wrong: $e"
}

If the response returns JSON, data will be in a map-like structure that allows you to easily access the response data:

def makeJSONWeatherRequest() {
    def params = [
        uri:  'http://api.openweathermap.org/data/2.5/',
        path: 'weather',
        contentType: 'application/json',
        query: [q:'Minneapolis', mode: 'json']
    ]
    try {
        httpGet(params) {resp ->
            log.debug "resp data: ${resp.data}"
            log.debug "humidity: ${resp.data.main.humidity}"
        }
    } catch (e) {
        log.error "error: $e"
    }
}

The resp.data from the request above would look like this (indented for readability):

resp data: [id:5037649, dt:1432752405, clouds:[all:0],
    coord:[lon:-93.26, lat:44.98], wind:[speed:4.26, deg:233.507],
    cod:200, sys:[message:0.012, sunset:1432777690, sunrise:1432722741,
        country:US],
    name:Minneapolis, base:stations,
    weather:[[id:800, icon:01d, description:Sky is Clear, main:Clear]],
    main:[humidity:73, pressure:993.79, temp_max:298.696, sea_level:1026.82,
        temp_min:298.696, temp:298.696, grnd_level:993.79]]

We can easily get the humidity from this data structure as shown above:

resp.data.main.humidity

Try It Out¶

If you’re interested in experimenting with the various HTTP APIs, there are a few tools you can use to try out the APIs without signing up for any API keys.

You can use httpbin.org to test making simple requests. The httpGet() example above uses it.

For testing POST requests, you can use PostCatcher. You can generate a target URL and then inspect the contents of the request. Here’s an example using httpPostJson():

def params = [
    uri: "http://postcatcher.in/catchers/<yourUniquePath>",
    body: [
        param1: [subparam1: "subparam 1 value",
                 subparam2: "subparam2 value"],
        param2: "param2 value"
    ]
]

try {
    httpPostJson(params) { resp ->
        resp.headers.each {
            log.debug "${it.name} : ${it.value}"
        }
        log.debug "response contentType: ${resp.    contentType}"
    }
} catch (e) {
    log.debug "something went wrong: $e"
}

See Also¶

A simple example using httpGet that connects a SmartSense Temp/Humidity to your Weather Underground personal weather station can be found here.

You can browse some templates in the IDE that use the various HTTP APIs. The Ecobee Service Manager is an example that uses both httpGet() and httpPost().

Send Notifications with Contact Book¶

If a user has added contacts to their Contact Book, SmartApps can prompt a user to select contacts to send notifications to. This allows a user’s contacts to be managed independently through the Contact Book, and SmartApps can tap into that feature. This has the advantage that a user does not have to enter in phone numbers for every SmartApp.

Sending notifications by using the Contact Book feature is the preferred way for sending notifications in a SmartApp.

Selecting Contacts to Notify¶

To allow a user to select from a list of their contacts, use the "contact" input type:

preferences {
    section("Send Notifications?") {
        input("recipients", "contact", title: "Send notifications to")
    }
}

When the user configures this SmartApp, they can then select which contacts they want to notify, and how they should be notified (SMS or push):

In the example above, the users selected will be stored in a variable named recipients. This is just a simple list that we can pass into the sendNotificationToContacts() method.

Note

When creating contacts, the user can enter an email address. Emails are not currently sent by SmartThings, though they are used to identify SmartThings users, and enable them to receive push notifications.

sendNotificationToContacts("something you care about!", recipients)

sendNotificationToContacts("something you care about!", recipients, [event: false])

preferences {
    section("Send Notifications?") {
        input("recipients", "contact", title: "Send notifications to") {
            input "phone", "phone", title: "Warn with text message (optional)",
                description: "Phone Number", required: false
        }
    }
}

// check that contact book is enabled and recipients selected
if (location.contactBookEnabled && recipients) {
    sendNotificationToContacts("your message here", recipients)
} else if (phone) { // check that the user did select a phone number
    sendSms(phone, "your message here")
}

definition(
    name: "Contact Book Example",
    namespace: "smartthings",
    author: "SmartThings",
    description: "Example using Contact Book",
    category: "My Apps",
    iconUrl: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png",
    iconX2Url: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience@2x.png",
    iconX3Url: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience@2x.png")


preferences {
    section("Which Door?") {
        input "door", "capability.contactSensor", required: true,
              title: "Which Door?"
    }

    section("Send Notifications?") {
        input("recipients", "contact", title: "Send notifications to") {
            input "phone", "phone", title: "Warn with text message (optional)",
                description: "Phone Number", required: false
        }
    }
}

def installed() {
    initialize()
}

def updated() {
    initialize()
}

def initialize() {
    subscribe(door, "contact.open", doorOpenHandler)
}

def doorOpenHandler(evt) {
    log.debug "recipients configured: $recipients"

    def message = "The ${door.displayName} is open!"
    if (location.contactBookEnabled && recipients) {
        log.debug "contact book enabled!"
        sendNotificationToContacts(message, recipients)
    } else {
        log.debug "contact book not enabled"
        if (phone) {
            sendSms(phone, message)
        }
    }
}

Send Push Notifications¶

To send a push notification through the SmartThings mobile app, you can use the sendPush() or sendPushMessage() methods. Both methods simply take the message to display. sendPush() will display the message in the Notifications feed; sendPushMessage() will not.

A simple example below shows (optionally) sending a push message when a door opens:

preferences {
    section("Which door?") {
        input "door", "capability.contactSensor", required: true,
              title: "Which door?"
    }
    section("Send Push Notification?") {
        input "sendPush", "bool", required: false,
              title: "Send Push Notification when Opened?"
    }
}

def installed() {
    initialize()
}

def updated() {
    initialize()
}

def initialize() {
    subscribe(door, "contact.open", doorOpenHandler)
}

def doorOpenHandler(evt) {
    if (sendPush) {
        sendPush("The ${door.displayName} is open!")
    }
}

Push notifications will be sent to all users with the SmartThings mobile app installed, for the account the SmartApp is installed into.

Send SMS Notifications¶

In addition to sending push notifications through the SmartThings mobile app, you can also send SMS messages to specified numbers using the sendSms() and sendSmsMessage() methods.

Both methods take a phone number (as a string) and a message to send. The message can be no longer than 140 characters. sendSms() will display the message in the Notifications feed; sendSmsMessage() will not.

Extending the example above, let’s add the ability for a user to (optionally) send an SMS message to a specified number:

preferences {
    section("Which door?") {
        input "door", "capability.contactSensor", required: true,
              title: "Which door?"
    }
    section("Send Push Notification?") {
        input "sendPush", "bool", required: false,
              title: "Send Push Notification when Opened?"
    }
    section("Send a text message to this number (optional)") {
        input "phone", "phone", required: false
    }
}

def installed() {
    initialize()
}

def updated() {
    initialize()
}

def initialize() {
    subscribe(door, "contact.open", doorOpenHandler)
}

def doorOpenHandler(evt) {
    def message = "The ${door.displayName} is open!"
    if (sendPush) {
        sendPush(message)
    }
    if (phone) {
        sendSms(phone, message)
    }
}

SMS notifications will be sent from the number 844647 (“THINGS”).

Send Both Push and SMS Notifications¶

The sendNotification() method allows you to send both push and/or SMS messages, in one convenient method call. It can also optionally display the message in the Notifications feed.

sendNotification() takes a message parameter, and a map of options that control how the message should be sent, if the message should be displayed in the Notifications feed, and a phone number to send an SMS to (if specified):

// sends a push notification, and displays it in the Notifications feed
sendNotification("test notification - no params")

// same as above, but explicitly specifies the push method (default is push)
sendNotification("test notification - push", [method: "push"])

// sends an SMS notification, and displays it in the Notifications feed
sendNotification("test notification - sms", [method: "phone", phone: "1234567890"])

// Sends a push and SMS message, and displays it in the Notifications feed
sendNotification("test notification - both", [method: "both", phone: "1234567890"])

// Sends a push message, and does not display it in the Notifications feed
sendNotification("test notification - no event", [event: false])

Only Display Message in the Notifications Feed¶

Use the sendNotificationEvent() method to display a message in the Notifications feed, without sending a push notification or SMS message:

sendNotificationEvent("Your home talks!")

Examples¶

Several examples exist in the SmartApp templates that send notifications. Here are a few you can look at to learn more:

• “Notify Me When” sends push or text messages in response to a variety of events.
• “Presence Change Push” and “Presence Change Text” send notifications when people arrive or depart.

Related API Documentation¶

• sendNotificationToContacts()
• contactBookEnabled
• sendPush()
• sendPushMessage()
• sendSms()
• sendSmsMessage()
• sendNotification()
• sendNotificationEvent()