[OBSOLETE] FAQ: An Overview of Using Custom Code in SmartThings (SmartThings Classic, Groovy Code)

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.

http://thingsthataresmart.wiki/index.php?title=How_to_Quick_Browse_the_Community-Created_SmartApps_Forum_Section

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.:

http://thingsthataresmart.wiki/index.php?title=How_to_Quick_Browse_the_Community-Created_SmartApps_Forum_Section

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.

89 Likes

Once I have created a new device type, where do I see it in the smartphone?

1 Like

You will see the new device handler (formerly called a smart device type) in the IDE, which is a developer tool. You view it through a web browser, not through the phone app.

You should have created it through the IDE as well, so you go through the same process to sign in.

Some custom device types will automatically be assigned to a new device when it is paired. These are usually zigbee devices.

For the others, you sign in to the IDE and follow the instructions in DH5 and DH6 above.

1 Like

For some reason I can’t edit the first post in this thread anymore, but the forum categories for community created smart apps and community created device types have moved.

If you are looking for community created smartapps:

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

And device types ( this is a brand-new subcategory, so it may take a while to get populated. Also check the regular “connected devices” subcategory for now.)

https://community.smartthings.com/c/projects-stories/community-created-device-types

But at this point there are so many different ones that it’s going to be faster to use the quick browse lists in the community – created wiki.

http://thingsthataresmart.wiki/index.php?title=How_to_Quick_Browse_the_Community-Created_SmartApps_Forum_Section

4 Likes

@JDRoberts Incredibly helpful in understanding the SmartThings system :+1:

2 Likes

If I want to develop a smart app where can I get the Dummys Book (and examples to copy from) to developing these apps. I want to do more functionality of my devices and I think I need to create something. I used to be a software developer and now just manage a team of developers for work, but would love to create some for my use and then share them.

Click on the “community” link at the top of this page and then look for the “developer documentation” link at the top right.

Follow-up questions can be asked in the developer section of this forum:

https://community.smartthings.com/c/developers

1 Like

Thank you JD! I’ve been “playing around” with my Smartthings system for about 2 years. And with the help of your tutorial, I just successfully “copied/used”, my first custom SmartApp & Device Type. A BloomSky weather camera.

Now I have 3 other things to attempt.

The hardest part was finding & figuring out that “Developers” site. I wish ST’s would make all of this “stuff” easier.

Many Thanks,
Murray

1 Like

I totally agree. Although new to ST, I find working w/ SmartApps and DTHs to be extremely painful. I have read blogs that mention apps, only to search without any success in finding them. If it takes 2 YEARS to learn enough to complete the first app, then ST is going back to the store. What happened to the IFTTT feature? That’s never spoken of!

ST is very extensible. Admittedly kind of misleading when people look at what you can do versus what’s available without learning a few things. You either live within the walls, find and use the community (requires some learning), or outright learn how to code. Personally, I love the flexibility. If you’re not a coder, checkout CoRE. If you are, it’s not that tough.

SmartThings is very versatile, but definitely lacks discoverability. A lot of that is made up for by this community, which I have found to be very helpful and very active, and which can get you a quick response to most questions. :sunglasses:

The following might also be of interest:

The official blog is always interesting, but unfortunately they don’t go back and update it as things change, and things change often.

Thx JD for the link to the article. While it definitely helps to understand the v2 app, I find ST lacks overall instruction and guidance. Connection was easy and quick which excited me. All my IRIS devices linked without issue BUT the keypad. My wife wants a simple chime to sound when a door is opened and a simple interface for arming. Since I am not a Java (or Groovy) programmer, I started with searching written DTHs to support devices and Apps to integrate actions. I tried to integrate Iris Keypad (which has a lot of discussion in the commune) but there appears to be no official app to support it. I tried one from Mitch ?? that partially works. Then I hear about CoRe and unlock manager and … but cannot find the apps within the smartapps due to poor organization and search tools. This has really frustrated me with a deadline to get done by Friday. Can anyone provide simple step by step directions and links to everything needed to make an IRIS keypad activate an alarm mode and chime with door openings?

1 Like

Thanks John. I agree it takes learning more than a few things, especially the community. I have seen several blogs re CoRE but have yet to find the app. Can you provide the link?

Here you go:

CoRE and Piston Rules Engine, first design steps

If you use the magnifying glass in the upper right, you can search this thread or any thread.

EDIT: Here’s the GitHub (it’s in the thread above; https://github.com/ady624/CoRE)

@khill
That project would be off topic for this particular thread, but I have started a new thread for you and hopefully people will be able to answer your questions about door chimes there.

3 posts were merged into an existing topic: Use Iris Keypad to trigger alarm and Door Chime?

So what does it mean if there is no create button?

As long as you’re working with a Device Handler, not a SmartApp, there should be a create button at the bottom of the “from code” form.

So check to make sure you’re in the correct section of the IDE.

If you are, and you don’t see the blue button, contact support.

@JDRoberts, can you link to how to add a custom device handler or SmartApp from GitHub. I’d rather not copy/paste, but use GitHub Integration to make it easier to get notifications and update it when there is an update.
Thanks.

Good idea! Someone else can add it if they like, either here or in the community created wiki. :sunglasses: I rely on text-to-speech software, so I can’t really do anything with Github.

The authors of most of the very popular code have generally put installation instructions in their author threads which would cover the github piece. They still refer people over to this thread to get an explanation of the concepts, but the specific installation process may be somewhat different.

I think somebody did a thread on github integration, but I don’t remember where that is. Again I can’t read most of those posts. @tgauchat or @jody.albritton might know if there’s a write up somewhere.