Shade's Kotlin SDK provides simple type-safe access to your Hue
lights. Shade is built using Kotlin's Coroutines to provide a simple
straightforward API on Android or the JVM.
Introduction
Shade can be used to connect and manipulate lights in Hue:
fun main() {
runBlocking {
println("Searching for Hue Bridges")
val shade = Shade()
val devices = shade.discovery.getDevices()
shade.setBaseUrl(devices.first().url)
println("Press the connect button on the hue bridge")
shade.auth.awaitToken()
println("Turning all the lights on!")
shade.groups.setState(
GROUP_ALL,
GroupStateModification(
on = on
)
)
}
}
Shade's Kotlin SDK currently supports controlling Lights, Groups,
Scenes and Schedules. With plans to support new API's as Hue
introduces them.
Installation
If you haven’t already, add JitPack to your gradle repositories in your build.gradle file:
repositories {
maven {
url "https://jitpack.io"
}
}
Next, add Shade as a dependency to your build.gradle file:
compile "com.github.Inkapplications.Shade:shade:+" // Replace with exact version
Discover a Hue Bridge
Before you can start discovering, you need to create an
uninitialized Shade instance. Just call the constructor to do
this:
val shade = Shade()
If you know the URL/IP of the Bridge you want to connect to,
you can specify it with the initBaseUrl
parameter
in the constructor, and skip right to controlling your lights!
Shade is broken into several modules. To find a Hue Bridge to
connect to, you'll use the discovery
module. Which
provides a getDevices()
method.
Because multiple Hue Bridges may be on the network, discovery
returns a list of devices. Each device has an ID and an
IP address.
shade.discovery.getDevices().forEach {
println("found device: ${it.id} ip: ${it.ip}")
}
Once you select a device to use, you can tell Shade to connect
to it using the setBaseUrl
method. This can be
called at any point to change the bridge this instance of
Shade is connected to.
shade.setBaseUrl(device.url)
Authenticate
The last step you need to do before you can start controlling
lights is to request access. Hue does this by tapping the button
on the top of the hub. To start this process use the
awaitToken
method in auth
module.
shade.auth.awaitToken()
This method will eventually timeout after an amount of time.
You can change how many retries and how often the SDK will poll
the bridge for auth using the optional retries
and timeout
arguments on the
awaitToken()
method.
Light Controls
Controlling individual lights is done through the
lights
module.
Get a List of Lights
You can get a list of lights using getLights()
shade.lights.getLights().forEach { (id, light) ->
println("Found light $id named ${light.name}")
}
Change Light State
To turn lights on/off, change their color or brightness you
can use the setState
method with a
LightStateModification
object.
The LightStateModification
object is used to
describe properties that will be changed on the light. If a
property is left null
/ not specified, the current
state of the light will not change.
shade.lights.setState(id, LightStateModification(on = true, brightness = 50.percent))
Group Controls
Groups can be accessed through the groups
module
and function very similar to individual lights.
Get a List of Groups
You can get a list of groups using getGroups()
shade.groups.getGroups().forEach { (id, light) ->
println("Found Group $id named ${light.name}")
}
Change a Group of Lights
Changing a group of lights is similar to changing a light state
except is done with a GroupStateModification
object. Like light modifications, properties that are not set
on the modification object will retain its current state.
shade.groups.setState(id, GroupStateModification(on = true, colorTemperature = 5000.kelvin))