JarCastingSmartThings SmartApp SDK Java (Preview) 
Welcome! This SDK is currently in preview and is not recommended for use in production applications at this time. We welcome your bug reports, feature requests, and contributions.
This SDK includes a set of JVM libraries for building webhook and AWS Lambda SmartApps, and interacting with the public SmartThings REST API.
Prerequisites
- Java 1.8+
- SmartThings developer account
Adding the SDK to your build
Several artifacts are published to the Maven central repository under the com.smartthings.sdk group.
smartapp-core- Core SmartApp Frameworksmartapp-guice- Extension library for use with Google Guicesmartapp-spring- Extension library for use with Spring Dependency Injectionsmartapp-contextstore-dynamodb- Extension library to use DynamoDB to store installed application context data.
smartthings-client- Library for working with SmartThings APIs
Import the library dependencies as needed:
Apache Maven
<dependency>
<groupId>com.smartthings.sdk</groupId>
<artifactId>smartapp-core</artifactId>
<version>0.0.4-PREVIEW</version>
<type>pom</type>
</dependency>
Gradle Groovy DSL
implementation 'com.smartthings.sdk:smartapp-core:0.0.4-PREVIEW'
If you prefer, the artifacts can be downloaded directly from Maven Central.
Getting Started
What is a SmartApp?
SmartApps are an example of a SmartThings Automation. Automations allow users to control the SmartThings ecosystem without manual intervention. Creating a SmartApp allows you to control and get status notifications from SmartThings devices using the SmartThings REST API.
Webhook SmartApps are any publicly-accessible web server that will receive a POST request payload.
AWS Lambda SmartApps are hosted in the Amazon Web Services cloud and are invoked by ARN instead of a public-DNS address.
To learn more about what a SmartApp is and how you can create interesting automations, please visit the developer portal documentation.
Basics
Take a quick look at how SmartApps are declared in various languages.
Kotlin (click to toggle)
package app
val smartApp: SmartApp = SmartApp.of { spec ->
spec
.configuration(Configuration())
.install {
Response.ok(InstallResponseData())
}
.update {
Response.ok(UpdateResponseData())
}
.event {
Response.ok(EventResponseData())
}
.uninstall {
Response.ok(UninstallResponseData())
}
}
fun Application.main() {
install(Routing) {
post("/smartapp") {
call.respond(smartApp.execute(call.receive()))
}
}
}
Groovy (click to toggle)
SmartApp smartApp = SmartApp.of { spec ->
spec
.install({ req ->
// create subscriptions
Response.ok()
})
.update({ req ->
// delete subscriptions
// create subscriptions
Response.ok()
})
.configuration({ req ->
ConfigurationResponseData data = ...// build config
Response.ok(data)
})
.event(EventHandler.of { eventSpec ->
eventSpec
.onSubscription("switch", { event ->
// do something
})
.onSchedule("nightly", { event ->
// do something
})
.onEvent(
{ event ->
// test event
true
},
{ event ->
// do something
}
)
})
}
Java (click to toggle)
private final SmartApp smartApp = SmartApp.of(spec ->
spec
.install(request -> {
return Response.ok();
})
.update(request -> {
return Response.ok(UpdateResponseData.newInstance());
})
.configuration(request -> {
return Response.ok(ConfigurationReponseData.newInstance());
})
.event(request -> {
EventData eventData = request.getEventData();
EventHandler.of(eventSpec ->
eventSpec
.onEvent(event -> {
// when this predicate is true...
return true;
}, event -> {
// ...do something with event
})
.onSchedule("nightly", event -> {
// do something
})
.onSubscription("switch", event -> {
// do something
})
);
return Response.ok(EventResponseData.newInstance());
})
);
Runnable Examples
Several simple examples of using the sdk are included in the examples directory.
kotlin-smartapp (Documentation) 
This Kotlin example implements the Java smartapp-core library with a simple Ktor server.
java-ratpack-guice-smartapp (Documentation) 
This Java example implements the Java smartapp-core library with a Ratpack server and uses Guice for dependency management.
java-springboot-smartapp (Documentation) 
This Java example implements the Java smartapp-core library using Spring Boot.
java-lambda-smartapp (Documentation) 
This Java example implements the Java smartapp-core library as an AWS Lambda.
Documentation
Modules
smartapp-core (Documentation)
Core SmartApp framework. Provides abilities for defining a SmartApp that could be used in many environments - AWS Lambda / Dropwizard / Ratpack / etc
smartthings-client (Documentation)
An API library that provides useful utilities for working with the Subscription / Schedules / Device APIs
Extension Libraries
smartapp-guice (Documentation)
An extension library that provides support for building a SmartApp with Guice dependency injection.
smartapp-spring (Documentation)
An extension library that provides support for building a SmartApp with Spring dependency injection.
smartapp-contextstore-dynamodb (Documentation)
An extension library that implements a context store using DynamoDB.
More about SmartThings
If you are not familiar with SmartThings, we have extensive on-line documentation.
To create and manage your services and devices on SmartThings, create an account in the developer workspace.
The SmartThings Community is a good place share and ask questions.
There is also a SmartThings reddit community where you can read and share information.
License and Copyright
Licensed under the Apache License, Version 2.0
Copyright 2019 SmartThings, Inc.
