Kotlin SDK

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))