The original FAQ information in this thread refers to the original smartthings architecture, which was in place through the end of 2022 and a little beyond. Custom code was written in the groovy programming language and ran in the smartthings cloud.
As of May 2023, you can no longer add new Groovy DTH‘s or smartapps to your smartthings account. So if you came here because of a link in an old forum thread, or on another site, I’m afraid the Groovy information is no longer usable.
All of this was replaced by a new architecture. Cloud to cloud integrations use the smartthings API. Hub connected devices, mostly Zigbee and zwave, now use “Edge Drivers,” written in the LUA programming language. Here’s the official announcement on those:
The process for using a custom Edge Driver in the new 2023 architecture is completely different and considerably easier: you just click on a link the author gives you, and the Edge Driver will be automatically installed on your hub.
You can read more about this in the community FAQ on the new architecture:
FAQ: I have no idea what Edge is. Is that a new developer tool? (2022)
OBSOLETE INFORMATION FOR THE PRE-2023 ARCHITECTURE. These methods can no longer be used with smartthings and are retained here solely for archival purposes.
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 Handler”?
(Note: the official terminology has changed a couple of times. “device type handler,” “device handler,” “DTH,” and “device type” all mean the same thing, and you will find all these terms used in the forums.)
SECTION I: SMARTAPPS AND DEVICE HANDLERS: WHAT THEY ARE
SmartAPPS: 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. (The exception is the very popular WebCore which is a smartapp that is a very sophisticated rules engine. Each WebCore “piston” solves a specific problem while WebCore lets you create those rules.)
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:
You can also quick browse the section if you only want to see smartapps for lighting or HVAC or security, etc.
Or ask in the New SmartApp Ideas topic for help if you can’t find what you want:
.
Device Type Handlers (Also called Device Types or Device Handlers)
Like a smartapp, this is another tiny program. Instead of controlling what happens when, though, the device type handler 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 handler for a laptop. In a home automation system, every connected device needs a device type handler.
SmartThings provides a bunch of standard device type handlers, as well as specialized device type handlers 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 handler. 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 handler” so that other people can use it. These will usually be published in the Community-created Device Types category of the forum, but may be linked directly from the topic for a particular SmartApp that needs that device type handler to work properly.
Note that the physical device has to already be manufactured to provide the feature. The device type handler code (DTH) just sets up the request in the right format.
https://community.smartthings.com/c/projects-stories/community-created-device-types
You can also quick browse the section and look at just DTHs for lighting or security devices or motion sensors, etc.:
If the device type handler is still being developed, you will probably find a discussion thread in the devices section of the forum.
SECTION II: HOW TO PUBLISH CUSTOM SMARTAPPS AND DEVICE HANDLERS 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 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
SA1) Copy the code from the author.
SA2) Sign in to the Developers section of the SmartThings website so you can access the IDE (Integrated Development Environment).
The URL: http://ide.smartthings.com/ should take you to your account if you are in North America.
If you are in the UK/EU, use
https://graph-eu01-euwest1.api.smartthings.com
SA3) Choose SmartApps, then Add a New SmartApp from Code.
SA4) Paste in the code you copied, change anything necessary based on the author’s instructions, then PUBLISH it to yourself.
SA5) Make any additional edits according to the author’s instructions, such as enabling OAUTH.
Now when you open the classic SmartThings mobile app, this new custom smartapp will appear as a choice under My SmartApps in the SmartApp section in the Marketplace.
In the new V3 app, it will appear under “SmartApps.” At the time of this writing, those were under the 3 horizontal lines icon in the top left of the main screen.
Next, the Install Process to Assign that SmartApp to a Specific Device..
To assign that SmartApp to a specific device in the classic app:
SA6) Open the ST mobile app.
SA7) Go to the Dashboard, then click on the Marketplace icon (the multicolored asterisk in the lower right).
SA8) Choose SmartApps
SA9) Scroll down to the MY SMARTAPPS section and choose it.
SA10) Scroll down to find the custom smartapp you want, then install it.
SA11) Follow the set up wizard instructions for that smartapp.
Steps SA6-SA11 are a little different in the new V3 app. Just find the SmartApps section (at the time of the writing it was an option on the three horizontal line icon in the upper right) and you should see the smartapps listed that you added through the IDE.
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 HANDLER
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 handler, 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 handler for the placeholder since you’re going to change it in a minute anyway. Then you can continue with the following steps.)
DT1) Copy the code from the author.
DT2) Sign in to the Developers section of the SmartThings website so you can access the IDE (Integrated Development Environment).
The URL: https://account.smartthings.com should take you to your account.
DT3) Choose My Device Handlers, then Add a New Device Handler from Code.
DT4) Paste in the code you copied, change anything necessary based on the author’s instructions, then CREATE it for yourself.
DT5) Once the Device Handler 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 handler.
DT6) Edit the Device so that it uses that device type handler.
Done!
Now any SmartApp that wants to talk to that device will be able to request the features specified in the custom device type handler. (Again, the physical device has to already support the features, the device type handler just translates the requests between SmartThings and the device.)
SECTION III: 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 handler, 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 handler 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 handler 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 handler 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 type handler does not support, you may need a custom Device type handler.
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 handler in order to work properly.
In all cases, you copy the custom code from the author, then use the Developers section of the SmartThings website to paste this into your own library.
Once it’s in your library:
For device type handlers, you can then edit a specific device profile to use that device type handler.
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.
Also remember that device type handlers are also called device types and device handlers, so you will find references to all three.
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.
A Note About “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 developers 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 support github integration or you just don’t want to use it, asking author’s thread if there is a way to “manually install” the code, which should be a cut-and-paste method.
I rely on text-to-speech software, so I can’t really do anything with Github.