Using Custom Code

The Unofficial SmartThings Blog
Jump to: navigation, search

So you're new to SmartThings, you asked a question, and someone suggested "custom code" as an answer.

Or you were browsing the forums, and you found something that sounded like it would be perfect for what you wanted, but again, "uses custom code."

What does that mean, how hard is it to do, and what's the difference between a "SmartApp" and a "Device Type"?

SmartApps and Device Types: What They Are

SmartApps

What are they? Tiny Programs to decide what a specific device should do when, or to collect the information from a specific device

SmartApps, including the various functions included in the official SmartThings app, are just tiny programs (written in the Groovy programming language) that handle "Do this when" kinds of situation for one specific device. Whether it's "Let me know if motion sensor 1 goes off before motion sensor 2" or "Change the setpoint on the thermostat based on the lux level in the sitting room," a SmartApp is a way of either using information from a device or controlling that device. Most solve a very specific problem.

Many community members enjoy writing custom smartapps, and either share them for others to use or are happy to help write new ones if you have a problem that hasn't already been solved.

See the community-created smartapps area of the forum for some of the most popular smartapps:

https://community.smartthings.com/c/projects-stories/created-smart-apps

Or ask in the New SmartApp Ideas topic for help if you can't find what you want:

https://community.smartthings.com/c/smartapps/smartapp-ideas

Device Types (Also called Device Handlers)

Like a smartapp, this is another tiny program. Instead of controlling what happens when, though, the device type has an even simpler job. It just translates commands from smartapps into the exact format a particular device requires, and vice versa. A printer driver is one kind of device type for a laptop. In a home automation system, every connected device needs a device type.

SmartThings provides a bunch of standard device types, as well as specialized device types for devices on the official "Works with SmartThings" list.

But quite often a new device comes along that has features that aren't yet supported in the standard device type. Or a community member comes up with a more efficient way to talk to a particular device.

Then someone will publish a "custom device type" so that other people can use it. These will usually be published in the Connected Devices category of the forum, but may be linked directly from the topic for a particular SmartApp that needs that device handler to work properly.

Note that the physical device has to already be manufactured to provide the feature. The device type just sets up the request in the right format.

Custom Device Types ready for release are available in the Projects section of the community [1]

See the community section, Connected Things, for general discussion about devices.

How To Publish Custom SmartApps and Device Types to Yourself So You Can Use Them

Using a Custom SmartApp

This involves two steps.

A one time process to "publish" the smartapp code to yourself using the Developers section of the SmartThings.com website so it is available for future installation.

Then using the official SmartThings mobile app to install it so you can use it with specific devices.

First, the One Time Process to Publish it to Yourself

  1. Copy the code from the author.
  2. Sign in to the Developers section of the SmartThings website ([2]).
  3. Choose SmartApps, then Add a New SmartApp from Code.
  4. Paste in the code you copied, change anything necessary based on the author's instructions, then PUBLISH it to yourself.
  5. Make any additional edits according to the author's instructions, such as enabling OAUTH.

Now when you open the official SmartThings mobile app, this new custom smartapp will appear as a choice under My Apps in the SmartApp section in the Marketplace.

Next, the Install Process to Assign that SmartApp to a Specific Device..

To assign that SmartApp to a specific device:

  1. Open the ST mobile app.
  2. Go to the Dashboard, then click on the Marketplace icon (the multicolored asterisk in the lower right).
  3. Choose SmartApps
  4. Scroll down to the My Apps section all the way at the bottom and choose it.
  5. Scroll down to find the custom smartapp you want, then install it.
  6. Follow the set up wizard instructions for that smartapp.

Some custom SmartApps also require a custom Device Handler to work. If so, the author will mention that in the installation instructions

Using a Custom Device Type

Easy!

These steps assume you have already added the device to your account through the SmartThings mobile app. It may be using a standard device type, or it may just have been added as a "thing", but it should show up on the list of devices for your account.

(If this is an ip-addressable device like a camera you may not have been able to add it to your account through the SmartThings mobile app, so the system will not assign it a device ID. In that case you will need to sign into the Developers section (IDE) and first choose My Devices and then use the ADD NEW DEVICE button to enter a placeholder for the device and assign it a unique device ID. You can choose any device type for the placeholder since you're going to change it in a minute anyway. Then you can continue with the following steps.)

  1. Copy the code from the author.
  2. Sign in to the Developers section of the SmartThings website (link in the top right corner of this page).
  3. Choose Device Types, then Add a New Device Type from Code.
  4. Paste in the code you copied, change anything necessary based on the author's instructions, then CREATE it for yourself.
  5. Once the Device Type is published in your own library, select MY DEVICES in the IDE and choose the specific device you want to have use that new device type.
  6. Click on the display name of the device that you want to assign to your new device type handler. This will open up its details page.
  7. Click on the "edit" button at the bottom left of the details page.
  8. Edit the Device so that it uses that device "type."

Done!

Now any SmartApp that wants to talk to that device will be able to request the features specified in the custom device type. (Again, the physical device has to already support the features, the device type just translates the requests between SmartThings and the device.)

Conclusion

Different Problems, Different Solutions

So that's it. You'll still use the regular SmartThings mobile app, you've just added some additional tiny programs to the ST cloud to give you some additional functionality for specific situations.

Some use cases will require a custom device type, especially if it's a device feature which hasn't been officially supported yet. A good example is when smart bulbs that could change color temperature first became available. (Cool white to warm white.) The standard device type could request a change red to blue color, but not request a change in color temperature for one color. The bulb could do it, but SmartThings didn't know how to ask it to do it. A community member contributed a custom device type that could make those change requests.

Some use cases will require a custom SmartApp. For example, one person wanted to make sure the motion detector activated light didn't come on when his family's new baby was napping. So another member helped him write a custom smartapp that could disable the motion sensor temporarily when the parent turned off a specific switch in the baby's room.

Some use cases will require both a custom device type and a custom SmartApp. If so, the author of the SmartApp will usually include those directions in the installation instructions.

Summary

If you need to access features that a physical device has, but the official SmartThings device handler does not support, you may need a custom Device Type.

If you want to control when a device does something in a way that the standard schedulers don't handle, you probably need a custom SmartApp.

Some custom SmartApps also need a custom device type in order to work properly.

In all cases, you copy the custom code from the author, then use the Developers section of the SmartThings.com website to paste this into your own library.

Once it's in your library:

For device types, you can then edit a specific device profile to use that device type.

For SmartApps, you can then install the SmartApp through the Smart Setup feature of the official SmartThings mobile app. Usually the SmartApp will have a setup wizard that then lets you assign it to specific devices. You may want to use the same SmartApp multiple times for different devices, or perhaps for different situations like one way for "on vacation" and another way for "not on vacation."

For questions on any specific custom code, ask the author in the topic devoted to it in the community forums.

You don't have to use custom code to use SmartThings. The standard features cover many different kinds of home automation use cases. However, if you do run into a device or a use case that isn't covered by the built in options, it is pretty easy to get help from the community and add custom code to address many different situations.

For discussion on this topic, see the original forum post [here https://community.smartthings.com/t/faq-an-overview-of-using-custom-code-in-smartthings/16772]

A Note on "GitHub Integration"

Some author threads will recommend that you use "github integration" instead of the cut-and-paste method.

Github is a site where developers can set up their own code libraries and then share them with others. It's not specific to SmartThings, but many SmartThings coders use it.

If you use a method called "github integration" you essentially link the developer's code library to your smartthings account. Once you have done that, you can follow the publishing instructions from that developer and you probably won't have to cut-and-paste. (All of the concepts described in the FAQ above still apply, the only difference is the exact process for getting someone else's code published to your account.)

The initial set up to use github integration is somewhat more complicated than the cut-and-paste method, but it has the advantage that you will be automatically notified of updates to the code. With the cut-and-paste method, you have to check yourself from time to time to see if there is a new release of the code.

SmartThings added GitHub integration as an option for US accounts late in 2015. It is not yet available for the UK.

If you are in a region which does not yet support github integration, or if you just choose not to use it, ask in the author's thread if there is a way to do "manual installation" which should be a cut-and-paste method.