Initializing the Shade SDK

Shade's default configuration stores authorization in memory and uses the Platform's SSL Configuration. However, this can be customized or completely overridden depending on your application.

Manual Configuration

Set the Hostname Manually

If you know the hostname or IP of the Hue bridge you want to connect to, you can specify it when constructing the Shade object: 

Shade(
    hostname = "192.168.1.23",
)

The hostname may simply be the bridge's local IP address. A DNS that resolves to the bridge's IP address is also acceptable, as well as the bridge ID if using the Hue CA SecurityStrategy

Set the Auth Token Manually

If you have saved your connection authorization token from a previous connection, you may set it on initialization to skip the auth process: 

Shade(
    authToken = AuthToken(
        applicationKey = "********",
        clientKey = "*******",
    ),
)

Security

Shade is configured to use HTTPS by default when connecting to the hue bridge. However, since connections are done on a local network, either your platform or application will need to be configured to trust the SSL certificate coming from the Hue bridge.

Platform Trust (default)

Platform trust is the default trust strategy for Shade. This will defer validation of the HTTPS connection to your platform, meaning you will have to manually install or mark the certificate as trusted on your system in order to connect to the hue bridge.

This option requires no configuration and is supported by all platforms, which makes it an ideal default. However, since it requires configuration on your system, it is likely you will want to change it when building an application.

Hue CA

The hue bridge is configured to use a custom CA in its HTTPS certificates. You can configure Shade to trust this root certificate manually on many platforms, when provided the IP and device ID of the bridge that were obtained during discovery: 

Shade(
    hostname = "192.168.1.23",
    securityStrategy = SecurityStrategy.HueCa(
        ip = "192.168.1.23",
        deviceId = "abcde1234",
    ),
)

Insecure

For security reasons it is not recommended that you use an insecure connection for the connection, however you may disable the SSL verification on many platforms for the bridge's hostname: 

Shade(
    hostname = "192.168.1.23",
    securityStrategy = SecurityStrategy.Insecure(
        hostname = "192.168.1.23",
    ),
)

When specifying this security type, the SSL certificate will be ignored for all traffic to the specified hostname done in the library.

Custom Configuration

Shade's in-memory configuration can be overridden entirely by specifying a custom implementation of the HueConfigurationContainer interface.

This interface allows you to load and save your connection configuration any way your application wants, such as to a local database: 

class DatabaseConfig: HueConfigurationContainer {
    override val hostname: StateFlow<String?> = TODO("Load hostname from database")
    override val securityStrategy: StateFlow<SecurityStrategy> = TODO("Load security strategy from database")
    override val authToken: StateFlow<AuthToken?> = TODO("Load auth token from database")

    override suspend fun setHostname(hostname: String?) {
        TODO("Save Hostname to database")
    }

    override suspend fun setAuthToken(token: AuthToken?) {
        TODO("Save auth token fields to database")
    }

    override suspend fun setSecurityStrategy(securityStrategy: SecurityStrategy) {
        TODO("Save Security Strategy to database")
    }
}

val shade = Shade(
    configuration = DatabaseConfig(),
)