README.md (5971B)
1 # Hue - Ruby Library and CLI for Philips Hue 2 3 > **_NOTE:_** This is a modified fork of [birkirb/hue-cli](https://github.com/birkirb/hue-cli) that supports modern Ruby. 4 5 ## WARNING 6 7 All of this is very experimental and could permanently damage your awesome (but ridiculously expensive) lightbulbs. As such, exercise extreme caution. 8 9 ## Installation 10 11 To begin using, install the ruby gem (this requires ruby 3.0+): 12 13 ```bash 14 $ gem install hue 15 ``` 16 17 This will install the `hue` command. 18 19 ## Usage 20 21 ### Command Line Interface 22 23 To check the bridge state, simply type: 24 25 ```bash 26 $ hue 27 ``` 28 29 If this is the first time the command is run, it will scan for bridges on the network and attempt to register the application. Follow the on-screen instructions to do so. 30 31 #### Register 32 33 You can also explicitly register the application with: 34 35 ```bash 36 $ hue register 37 ``` 38 39 #### Bridge state 40 41 Once registered, examine the current state of the bridge: 42 43 ```bash 44 $ hue 45 Philips Hue 46 Button pressed: false 47 Timestamp: 2013-09-02T17:44:10 48 Network configuration: 49 IP: 196.168.0.1 50 Gateway: 196.168.0.255 51 Mask: 255.255.255.0 52 DHCP: true 53 MAC: 00:00:00:00:00:00 54 Proxy: none:0 55 Applications: 56 073f2ed95fcbbef2532c751dd404cc9d : hue-cli 57 Lights: 58 1. Living Overhead - OFF 59 2. Living Cabinet - OFF 60 3. Living Corner Lamp - OFF 61 ``` 62 63 #### Lights state 64 65 ##### Examine or operate on all lights 66 67 ```bash 68 $ hue lights 69 1. Bedroom - Overhead: ON 70 Brightness: 254 (100%) 71 Color: XY=[0.6736, 0.3221], RGB≈[255, 60, 40] 72 2. Living Room - Cabinet: OFF 73 Brightness: 142 (56%) 74 Color: XY=[0.674, 0.322], RGB≈[255, 60, 40] 75 3. Living Room - Overhead: ON 76 Brightness: 254 (100%) 77 Color: Temperature=2710°K (369 mired), RGB≈[255, 166, 87] 78 ``` 79 80 ##### Find new lights 81 82 ```bash 83 $ hue lights find 84 ``` 85 86 #### Light state 87 88 Examine the state of a single light: 89 90 ```bash 91 $ hue light 1 92 ``` 93 94 or just: 95 96 ```bash 97 $ hue 1 98 1. Bedroom - Overhead: ON 99 Brightness: 254 (100%) 100 Color: XY=[0.6736, 0.3221], RGB≈[255, 60, 40] 101 ``` 102 103 ##### Change Light state 104 105 Change a single light state with the following (rather self-explanatory) commands: 106 107 ```bash 108 $ hue 1 on 109 $ hue 1 off 110 $ hue 1 flash 111 $ hue 1 blink 112 $ hue 1 solid 113 ``` 114 115 ##### Brightness 116 117 Brightness can be set with a value (0-255) or percentage (0%-100%): 118 119 ```bash 120 $ hue 1 brightness 200 121 $ hue 1 brightness 50% 122 $ hue 1 123 Living Overhead: ON 124 Brightness: 128 (50%) 125 Color: Temperature=2012°K (497 mired), RGB≈[255, 136, 13] 126 ``` 127 128 ##### Color 129 130 The color command takes 1-3 arguments, each interpreted depending on range and value. 131 132 Set to 6500 Kelvin: 133 134 ```bash 135 $ hue 1 color 6500 136 $ hue 1 137 Living Overhead: ON 138 Brightness: 128 (50%) 139 Color: Temperature=6500°K (153 mired), RGB≈[255, 254, 250] 140 ``` 141 142 Set to 240 mired: 143 144 ```bash 145 $ hue 1 color 240 146 $ hue 1 147 Living Overhead: ON 148 Brightness: 128 (50%) 149 Color: Temperature=4167°K (240 mired), RGB≈[255, 208, 170] 150 ``` 151 152 Set the hue and saturation: 153 154 ```bash 155 $ hue 1 color 30000 255 156 $ hue 1 157 Living Overhead: ON 158 Brightness: 128 (50%) 159 Color: Hue=30000, Saturation=255, RGB≈[0, 255, 190] 160 ``` 161 162 Set the XY: 163 164 ```bash 165 $ hue 1 color 0.25 0.25 166 $ hue 1 167 Living Overhead: ON 168 Brightness: 128 (50%) 169 Color: Hue=30000, Saturation=255, RGB≈[0, 255, 190] 170 ``` 171 172 #### Set all lights 173 174 All the single light state commands can be applied to all lights: 175 176 ```bash 177 $ hue lights brightness 50% 178 ``` 179 180 #### State aliases 181 182 The following state aliases exist and can be used on all or single lights: 183 184 ```bash 185 $ hue 1 relax 186 $ hue lights energize 187 $ hue 1 reading 188 $ hue 1 concentrate 189 $ hue 1 red 190 $ hue 1 blue 191 $ hue 1 green 192 $ hue 1 white 193 $ hue 1 pink 194 ``` 195 196 #### State Dump 197 198 Dump the current state of the light, this will display the current state as a JSON hash. 199 This can then be pasted into your local (`~/.hue-cli/light_alias.yml`) or system (`/etc/hue/light_alias.yml`) alias files. 200 201 ```bash 202 $ hue 1 dump 203 $ hue lights dump 204 ``` 205 206 Paste into your file like this: 207 208 ```yaml 209 "yellow": {"on":true,"bri":254,"xy":[0.4823,0.4621],"alert":"none","effect":"none"} 210 ``` 211 212 ## Ruby Library Usage 213 214 Start by firing up the irb console: 215 216 ```bash 217 $ irb 218 ``` 219 220 ```ruby 221 >> require 'hue' 222 => true 223 ``` 224 225 Start by registering your application. Press the button on the bridge and execute: 226 227 ```ruby 228 >> Hue.register_default 229 => #<Hue::Bridge:0x8b9d950 @application_id="4aa41fe737808af3559f3d22ca67a0ca", @bridge_uri="http://198.168.1.1/api"> 230 ``` 231 232 This will create two config files in your `~/.hue-cli` directory. 233 One for the bridges discovered on your network and one for the registered application. 234 235 You can fetch the default application thus: 236 237 ```ruby 238 >> bridge = Hue.application 239 => #<Hue::Bridge:0x8b9d950 @application_id="4aa41fe737808af3559f3d22ca67a0ca", @bridge_uri="http://198.168.1.1/api"> 240 ``` 241 242 You can see all of the lights attached to your controller by querying the bridge: 243 244 ```ruby 245 >> bridge.lights 246 => {"1"=>{"name"=>"Bedroom Overhead"}, "2"=>{"name"=>"Living Overhead"}, "3"=>{"name"=>"Standing Lamp"}, "4"=>{"name"=>"Living Cabinet"}} 247 >> bridge.light_names 248 => "1. Bedroom Overhead\n2. Living Overhead\n3. Standing Lamp\n4. Living Cabinet" 249 ``` 250 251 If you know the ID number of a particular lamp, you can access it directly: 252 253 ```ruby 254 >> b = Hue::Bulb.new(bridge, 1) 255 => #<Hue::Bulb:0x007fe35a3586b8 @bridge=#<Hue::Bridge:0x007fe35a358690 @id="1">> 256 257 # on/off 258 >> b.on? 259 => false 260 261 >> b.on 262 => true 263 264 >> b.on? 265 => true 266 267 # brightness 268 >> b.brightness = 128 269 => 128 270 271 # color 272 >> b.color = Hue::Colors::ColorTemperature.new(6500) 273 => Temperature=6500°K (153 mired) 274 275 >> b.color = Hue::Colors::HueSaturation.new(10_000, 255) 276 => Hue=10000, Saturation=255 277 278 >> b.color = Hue::Colors::XY.new(0.5, 0.5) 279 => XY=[0.5, 0.5] 280 281 # blinking 282 >> b.blinking? 283 => false 284 285 >> b.blink 286 287 >> b.blinking? 288 => true 289 290 >> b.solid 291 292 >> b.blinking? 293 => false 294 ``` 295 296 ## Development 297 298 ### Building the gem 299 300 ```bash 301 $ rake gem:build 302 ``` 303 304 ### Installing locally 305 306 ```bash 307 $ rake gem:install 308 ``` 309 310 ### Running tests 311 312 ```bash 313 $ rake spec 314 ``` 315 316 ## License 317 318 This project is open source and available under the MIT License.