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.

Set up the SDK in Gradle

Shade's SDK is available in Maven Central, with the with the following coordinates in your build.gradle file

implementation("com.inkapplications.shade:core:2.+")

Create a Shade Object

All of Shade's commands can be run through the Shade object. To use it, you can start by creating an Instance of the class for your application:

val shade = Shade()

The discovery process uses Hue's API to find Hue Bridges on the local network. This is the only command in the SDK that requires an internet connection, and is only used to find bridges. If you know the IP address of the hue bridge that you want to connect to, this step can be skipped.

Request a list of local devices on the network with the getDevices() command:

val devices = shade.onlineDiscovery.getDevices()

Shade's Auth module can be used to obtain an access token from the hue bridge using it's single button authorization.

To request a token call the awaitToken() method, providing information about your application:

val token = shade.auth.awaitToken(
    appId = AppId(
        appName = "MyApp",
        instanceId = "android",
    ),
)

This will suspend until the button on the hue bridge is pressed and an AuthToken is returned. Shade will automatically set this token for use internally. However, you should save the returned token for future connections.

Optionally, you may set a maximum number of retries and change the timeout between checks that is used for authorization by including the retries or timout arguments when calling awaitToken.

Individual lights can be controlled through the lights module:

shade.lights.updateLight(
    id = lightId,
    parameters = LightUpdateParameters(
        brightness = 10.percent,
    ),
)

The lights module supports the following actions:

• listLights To get a list of all lights on the hue bridge
• getLight To get information about a single light
• updateLight To update information about a single light

Rooms can be created and updated through the rooms module:

shade.rooms.createRoom(
    parameters = RoomCreateParameters(
        metadata = RoomMetadata(
            name = "Game Room",
            archetype = RoomArchetype.Recreation,
        ),
        children = listOf(lightReference),
    ),
)

The rooms module supports the following actions:

• listRooms To get a list of all rooms on the hue bridge
• getRoom To get information about a single room
• updateRoom To update information about a single room
• createRoom To create a new room on the hue bridge
• deleteRoom To remove a room from the hue bridge

Zones can be created and updated through the zones module:

shade.zones.listZones()

The zones module supports the following actions:

• listZones To get a list of all zones on the Hue bridge
• getZone To get information about a specific zone.
• updateZone To update the configuration for a zone.
• createZone To create a new zone configuration.
• deleteZone To remove a zone configuration.

Grouped Light resources can be fetched and updated groupedLights module:

shade.groupedLights.listGroups()

The zones module supports the following actions:

• listGroups to get a list of all grouped lights configured.
• getGroup to get information about a single grouped light.
• updateGroup to update the state of a grouped light.

Devices information can be retrieved/updated through the devices module:

shade.devices.listDevices()

The devices module supports the following actions:

• listDevices to get a list of all devices configured.
• getDevice to get information about a single device.
• updateDevice to update the state of a device.
• identifyDevice to trigger a visual identification sequence on the device.
• deleteDevice to remove a device from the bridge.

Bridge API resources can be retrieved using the resources module:

shade.resources.listResources()

• listResources to retrieve a list of all api resources on the hue bridge.

Scenes can be controlled through the scenes module:

shade.scenes.listScenes()

• listScenes to retrieve a list of all scenes on the hue bridge.
• getScene to retrieve information about a specific scene.
• createScene to create a new scene.
• updateScene to update a scene.
• deleteScene to delete a scene.