From e5447aacc697207db5d771c4be63c753cfffbeab Mon Sep 17 00:00:00 2001 From: Renee Vandervelde Date: Sat, 4 Apr 2020 11:21:45 -0500 Subject: [PATCH] Break SDK and CLI into separate pages --- docs/cli-overview.html | 139 ++++++++++ docs/css/{dark-1.0.css => dark-1.1.css} | 4 + docs/css/{main-1.0.css => main-1.1.css} | 87 +++++- docs/index.html | 334 +++++------------------- docs/sdk-overview.html | 240 +++++++++++++++++ 5 files changed, 523 insertions(+), 281 deletions(-) create mode 100644 docs/cli-overview.html rename docs/css/{dark-1.0.css => dark-1.1.css} (83%) rename docs/css/{main-1.0.css => main-1.1.css} (57%) create mode 100644 docs/sdk-overview.html diff --git a/docs/cli-overview.html b/docs/cli-overview.html new file mode 100644 index 00000000..677edb09 --- /dev/null +++ b/docs/cli-overview.html @@ -0,0 +1,139 @@ + + + + + + + + + CLI / Shade + + + + + + + + + + + + +
+ + + + +
+
+
+ +

CLI

+ +
+

+ Shade's CLI can provide an API for system tools to control lights, + can be run manually, and functions as a sample project for the SDK! +

+
+ +

Install

+ +

Using HomeBrew

+

+ If you're on a Mac with HomeBrew you can + install Shade with the following command: +

+ 

+$ brew install inkapplications/cli-tools/shade
+
+

Manual Install

+

+ For Windows or Linux, Shade's CLI can be installed by + downloading the + latest release + and running the or bin/shade.bat or + bin/shade executable or adding them to your + $PATH. +

+
+
+ +

Connect to a Hue bridge

+ +

+ You can set up your connection to Hue using the + connect command. This will automatically discover + hue bridges on the network and attempt to authenticate with + them. +

+ 

+$ shade connect
+Connecting to bridge at 192.168.1.100
+Waiting to connect. Press the button on your Hue Device now.
+
+
+
+ +

List lights

+ +

+ You can get information about of all the lights known to your + Hue bridge with the lights:list command. +

+ 

+$ shade lights:list
+1:
+  name: Renee's Office
+  uuid: 00:19:28:37:00:a1:b9:f2-0b
+  type: Extended color light
+  firmware: 5.127.1.26581
+2:
+  name: Kitchen
+  uuid: 00:91:82:73:00:b9:c3:7a-0b
+  type: Extended color light
+  firmware: 5.127.1.26581
+
+
+
+ +

Control Lights

+ +

+ You can control lights using the lights:control + command, including on/off, brightness, and color. +

+ 

+$ shade lights:control 1 --on --brightness 50
+
+
+
+ +

Groups, Scenes, and more

+ +

+ Shade supports commands for many of Hue's API's like Groups and + Scenes. For a full list of commands, run + shade-cli --help +

+
+
+
+
+ +

Contributions and Issues

+ +
+

+ Shade is free, Open Source, + actively maintained, and always looking for contributions. +

+

+ There are many Hue devices and things to do with them.
+ Testing all that can be difficult. + If you have an issue, please + tell us! +

+
+ + diff --git a/docs/css/dark-1.0.css b/docs/css/dark-1.1.css similarity index 83% rename from docs/css/dark-1.0.css rename to docs/css/dark-1.1.css index 1d833254..8e16e880 100644 --- a/docs/css/dark-1.0.css +++ b/docs/css/dark-1.1.css @@ -27,3 +27,7 @@ code, .only-dark { display: initial; } + +.hero > article { + background-color: #292929; +} diff --git a/docs/css/main-1.0.css b/docs/css/main-1.1.css similarity index 57% rename from docs/css/main-1.0.css rename to docs/css/main-1.1.css index 02678da7..ef5eaec1 100644 --- a/docs/css/main-1.0.css +++ b/docs/css/main-1.1.css @@ -20,13 +20,6 @@ h3 color: #616161; } -section, -body > header -{ - max-width: 1024px; - margin: 0 auto; -} - a, a:visited, a:hover @@ -35,6 +28,18 @@ a:hover text-decoration: none; border-bottom: 1px solid #D84315; } +a[href^="#"] +{ + border: none; +} +a[href^="#"]:hover +{ + cursor: default; +} +a[href^="#"]:focus +{ + outline: none; +} h1 { font-size: 3rem; @@ -80,12 +85,71 @@ pre > code { margin: 1rem 0; } +section, +body > header +{ + max-width: 1024px; + margin: 0 auto; +} + +body > header { + margin-bottom: 2rem; +} + +body > header > a, +body > header > a:hover +{ + border: none +} + .logo { height: 5rem; max-width: 40vw; margin: .5rem 0; } +.hero { + display: flex; + flex-wrap: wrap; + justify-content: space-around; +} +.hero > h1 { + flex-basis: 70%; + align-self: center; + font-size: 2rem; +} +.hero > article { + border-radius: .5rem; + padding: 1rem; + flex-basis: 30%; + background-color: #f2f2f2f2; +} +.hero > article > h1 { + font-size: 2rem; +} +.hero > article > a { + border-bottom: none; + border: 1px solid #D84315; + padding: .5rem; + border-radius: .25rem; + margin: 1rem 0; + display: inline-block; + float: right; +} +.hero > nav { + flex-basis: 30% +} +.hero > nav > a { + border-bottom: none; + display: block; + padding: 1rem; + font-size: 1.25rem; +} +.hero > nav > a:after { + content: '⭢'; + padding-left: .25rem; + padding-top: .125rem; +} .links { margin: 1rem 0; } @@ -114,3 +178,12 @@ pre > code { { display: none; } + +@media(max-width: 820px) { + .hero > h1, + .hero > nav, + .hero > article + { + flex-basis: 100%; + } +} diff --git a/docs/index.html b/docs/index.html index fc0d9649..0ded8cd0 100644 --- a/docs/index.html +++ b/docs/index.html @@ -12,8 +12,8 @@ - - + + @@ -23,67 +23,63 @@ -
-

Shade is a modern toolkit for the Philips Hue API for Kotlin and CLI tools.

- +
+

A modern toolkit for the Philips Hue API.

+ +
+

Kotlin SDK

+

Control your Hue devices with a rich Coroutine API.

+ Get Started +
+
+

CLI Tools

+

Cross-platform command line application to control Hue devices.

+ Get Started +
-
- -

CLI

-
-

- Shade's CLI can provide an API for system tools to control lights, - can be run manually, and functions as a sample project for the SDK! -

-

Install

-

Using HomeBrew

+
+ +

Straightforward API's

+

- If you're on a Mac with HomeBrew you can - install Shade with the following command: + Shade provides API's that are intuitive, making it easy to get + started.

- 

-$ brew install inkapplications/cli-tools/shade
-
-

Manual Install

-

- For Windows or Linux, Shade's CLI can be installed by - downloading the - latest release - and running the or bin/shade.bat or - bin/shade executable or adding them to your - $PATH. -

-
-
-

Connect to a Hue bridge

+ +

+suspend fun turnLightsOn() {
+    shade.groups.setState(
+        GROUP_ALL,
+        GroupStateModification(
+            on = on,
+            brightness = 50.percent,
+            colorTemperature = 5000.kelvin
+        )
+    )
+}
+
+

- You can set up your connection to Hue using the - connect command. This will automatically discover - hue bridges on the network and attempt to authenticate with - them. + Kotlin Coroutines makes controlling your Hue lights on the JVM + easy, while maintaining a well-structured asynchronous API.

- 

-$ shade connect
-Connecting to bridge at 192.168.1.100
-Waiting to connect. Press the button on your Hue Device now.
-
-

List lights

+
+ +

Cross-Platform CLI

+

- You can get information about of all the lights known to your - Hue bridge with the lights:list command. + Shade's command line tools run on Mac, Windows or Linux. Built + on Shade's SDK, the CLI provides an easy way to control + lights in any terminal or script.

+ 

 $ shade lights:list
 1:
@@ -96,237 +92,27 @@ 
List lights

   uuid: 00:91:82:73:00:b9:c3:7a-0b
   type: Extended color light
   firmware: 5.127.1.26581
-
-
-
-

Control Lights

-

- You can control lights using the lights:control - command, including on/off, brightness, and color. -

- 

-$ shade lights:control 1 --on --brightness 50
-
-
-
-

Groups, Scenes, and more

-

- Shade supports commands for many of Hue's API's like Groups and - Scenes. For a full list of commands, run - shade-cli --help -

-
-
-
-
- -

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

-

Modern Kotlin API

-

- Shade is designed for Kotlin's suspending Coroutines and uses many - of Kotlin's modern types. While it's possible to convert these for - use with other frameworks or for use with Java, it is not officially - supported. -

- -
- -

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)
-
+$ shade lights:control 1 --on --brightness 50 -

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

+
+ +

Free and Stable

+

- Groups can be accessed through the groups module - and function very similar to individual lights. + Shade is free, Open Source, + actively maintained, and always looking for contributions.

-

Get a List of Groups

- You can get a list of groups using getGroups() + There are many Hue devices and things to do with them.
+ Testing all that can be difficult. + If you have an issue, please + tell us!

- 

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

Contributions and Issues

-
-

- Shade is free, Open Source, - actively maintained, and always looking for contributions. -

-

- There are many Hue devices and things to do with them.
- Testing all that can be difficult. - If you have an issue, please - tell us! -

-
diff --git a/docs/sdk-overview.html b/docs/sdk-overview.html new file mode 100644 index 00000000..bdb87c89 --- /dev/null +++ b/docs/sdk-overview.html @@ -0,0 +1,240 @@ + + + + + + + + + Kotlin SDK / Shade + + + + + + + + + + + + +
+ + + + +
+
+
+ +

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

Contributions and Issues

+ +
+

+ Shade is free, Open Source, + actively maintained, and always looking for contributions. +

+

+ There are many Hue devices and things to do with them.
+ Testing all that can be difficult. + If you have an issue, please + tell us! +

+
+ +