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.
- Java 1.8+
- SmartThings developer account
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.
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.
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());
})
);Several simple 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.
Core SmartApp framework. Provides abilities for defining a SmartApp that could be used in many environments - AWS Lambda / Dropwizard / Ratpack / etc
An API library that provides useful utilities for working with the Subscription / Schedules / Device APIs
An extension library that provides support for building a SmartApp with Guice dependency injection.
An extension library that provides support for building a SmartApp with Spring dependency injection.
An extension library that implements a context store using DynamoDB.
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.
Licensed under the Apache License, Version 2.0
Copyright 2019 SmartThings, Inc.