This SDK is no longer being maintained and should not be chosen for new projects.
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 API.
- Java 1.8+
- A Samsung account
SmartApps are custom applications that execute outside of the SmartThings Platform. All of the SmartApp execution will happen on the server or Lambda that you control. The complexity of execution and the number of expected users will need to be examined to understand the hardware or execution requirements your app needs to handle. Your application will respond to lifecycle events sent from SmartThings to perform actions on behalf of your users and will execute any scheduled tasks that you have created in the SmartApp. Creating a SmartApp allows you to control and get status notifications from SmartThings devices using the SmartThings API.
Visit the SmartThings developer documentation to earn more about SmartApps.
There are two distinct options for hosting your SmartApp: AWS Lambda and Webhook.
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.
The best hosting option for your Automation depends on a number of factors, both objective and subjective.
To learn more about SmartApps, including choosing the best hosting option for your SmartApp, visit the SmartThings developer documentation.
Take a quick look at how SmartApps are declared in various languages.
Kotlin
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
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
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());
})
);-
The smartapp-core module provides the core SmartApp framework, enabling you to define a SmartApp that can be used in many different environments including AWS Lambda, Dropwizard, Ratpack, and more.
-
The smartthings-client module is an API library that provides useful utilities for working with the Subscription, Schedules, and Device APIs.
-
The smartapp-guice extension library provides support for building a SmartApp with Guice dependency injection.
-
The smartapp-spring extension library provides support for building a SmartApp with Spring dependency injection.
-
The smartapp-contextstore-dynamodb extension library implements a context store using DynamoDB.
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.
Several simple, runnable examples of using the SDK are included in the examples directory.
This Kotlin example implements the Java smartapp-core library with a simple Ktor server.
This Java example implements the Java smartapp-core library with a Ratpack server and uses Guice for dependency management.
This Java example implements the Java smartapp-core library using Spring Boot.
This Java example implements the Java smartapp-core library as an AWS Lambda.
Check out our complete developer documentation here.
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.
Licensed under the Apache License, Version 2.0
Copyright 2019 SmartThings, Inc.