wizrb 0.1.0 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c15616ac2e008b66a896a2e152112675c973973e053d948f6dda35226580825
-  data.tar.gz: 681f041c1b7f3a518d74abffffb10ac13b552fdaa1c4045c328021ad6c438960
+  metadata.gz: 93c20b34451939421c8be549770476540295a279b27c1218028c404eee376c78
+  data.tar.gz: 98c458a2589d357984ed03ad873c466ce7cc16869fc82ef0634ec9a963bbcaed
 SHA512:
-  metadata.gz: fc29df12beaed4b5f3506c47d0d86314961404ce88a1671c0ec01a562b18ef3183fe3f6df691e3f4bcde7e03e5d96fabbeb940a798a90269e623139ecda6dcd8
-  data.tar.gz: 39f12e9d4a8c44a651f5f631e67e64630f5d30795630a379fbe25041be3b482e5e565d116695110608269d2ec7f70a6c507dae77210ea15f9f710aa47bfcea48
+  metadata.gz: dfcda0e85d20c77bc3f841bbb362c97401d9a2c469a10a79f9c73df91347b507cbcc368e30d027d7ddd5b4caa232913331ca47bdc248b4ff21f50a140c85cbf9
+  data.tar.gz: b21b5f60f1b98ab1f0a5e70f4fac966548f3fdaf24c84f1e7dab058770243d58a76f808ac335f2b3eaf581fd1c22ff6ca1d504315471809bb0c117ab72b32d51

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2021-09-25
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Bert McCutchen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,62 @@
+# Wizrb
+
+***Pronounced like "Wizard"***
+
+This is a hobby project for getting the most out of Philips WiZ devices. Currently this project only supports Philips WiZ lights and plugs. If you would like to support this project, donations to buy new types of Philips WiZ accessories or coffee will be much appreciated!
+
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/M4M76DVZR)
+
+#### Compatability Notice
+
+Compatability may vary since I only own [Philips WiZ Bulb A19 E26 (Full Color)](https://www.wizconnected.com/en-CA/consumer/products/046677556136/) bulbs and a [LED Strip Starter kit 2m (Full Color)](https://www.wizconnected.com/en-CA/consumer/products/046677560805/) to test with.
+
+Testers with other (supported) Philips WiZ devices are welcome!
+
+#### Tested Devices:
+
+* [Bulb A19 E26 (Full Color)](https://www.wizconnected.com/en-CA/consumer/products/046677556136/)
+* [Filament amber ST64 E27 (Dimmable)](https://www.wizconnected.com/en/consumer/products/8718699787332/)
+* [LED Strip Starter kit 2m (Full Color)](https://www.wizconnected.com/en-CA/consumer/products/046677560805/)
+* [Smart Plug (Type B)](https://www.wizconnected.com/en-CA/consumer/products/046677603090/)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'wizrb'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install wizrb
+
+## Usage
+
+Most of the documentation on how to use this gem is located within [Wizrb Devices](doc/devices.md).
+
+Documentation for specific device types:
+* [Lighting Devices](doc/lighting.md)
+* [Power Devices](doc/power.md)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/bert-mccutchen/wizrb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/bert-mccutchen/wizrb/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Wizrb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/bert-mccutchen/wizrb/blob/master/CODE_OF_CONDUCT.md).

data/doc/devices.md

@@ -0,0 +1,135 @@
+# Wizrb Devices
+
+All devices inherit from a single class `Wizrb::Shared::Devices`. These device classes contain features that are shared among the Phillips WiZ device lineup.
+
+* [Connecting To Devices](#connecting-to-devices)
+  * [Individual Devices](#individual-devices)
+  * [Finding Devices](#finding-devices)
+* [Interacting With Devices](#interacting-with-devices)
+  * [Reading State](#reading-state)
+  * [Power Control](#power-control)
+  * [Information / Administration](#information--administration)
+* [Manually Dispatching Events](#manually-dispatching-events)
+  * [Individual Devices](#individual-devices)
+  * [Device Groups](#device-groups)
+  * [Dispatching Multiple Events](#dispatching-multiple-events)
+  * [Available Device Events](#available-device-events)
+
+## Connecting To Devices
+
+#### Individual Devices
+```ruby
+# Connect to device @ 127.0.0.1
+device = Wizrb::Shared::Products::Device.new(ip: '127.0.0.1')
+
+# Connect to device @ 127.0.0.1:38899
+device = Wizrb::Shared::Products::Device.new(ip: '127.0.0.1', port: 38899)
+```
+
+#### Finding Devices
+```ruby
+# Finding all devices:
+group = Wizrb::Shared::Discover.all
+# => Wizrb::Shared::Group
+
+# Finding all devices in home by ID:
+group = Wizrb::Shared::Discover.home(1234)
+# => Wizrb::Shared::Group
+
+# Finding all devices in room by ID:
+group = Wizrb::Shared::Discover.room(1234)
+# => Wizrb::Shared::Group
+```
+
+## Interacting With Devices
+
+#### Reading State
+```ruby
+device = Wizrb::Shared::Products::Device.new(ip: '127.0.0.1')
+
+device.state
+# => Wizrb::Shared::State
+
+device.state.power
+# => true
+```
+
+#### Power Control
+```ruby
+device = Wizrb::Shared::Products::Device.new(ip: '127.0.0.1')
+
+device.power_on
+device.power_off
+device.power_switch
+```
+
+#### Information / Administration
+```ruby
+device = Wizrb::Shared::Products::Device.new(ip: '127.0.0.1')
+
+device.system_config
+device.model_config
+device.user_config
+device.module_name
+
+device.reboot # Reboots the device.
+device.reset # Factory resets the device.
+device.refresh # Refreshes known device state.
+```
+
+## Manually Dispatching Events
+
+#### Individual Devices
+```ruby
+device = Wizrb::Shared::Products::Device.new(ip: '127.0.0.1')
+
+# Turn the device on.
+device.dispatch_event(Wizrb::Shared::Events::PowerEvent.new(true))
+
+# Turn the device off.
+device.dispatch_event(Wizrb::Shared::Events::PowerEvent.new(false))
+```
+
+#### Device Groups
+```ruby
+group = Wizrb::Shared::Discover.all
+
+# Turn on all devices.
+group.dispatch_event(Wizrb::Shared::Events::PowerEvent.new(true))
+
+# Turn off all devices.
+group.dispatch_event(Wizrb::Shared::Events::PowerEvent.new(false))
+
+# Turn on half of the devices.
+# Groups implement Enumerable to iterate over the devices within.
+group.each_with_index.each do |device, index|
+  next unless index % 2 == 0
+  device.dispatch_event(Wizrb::Shared::Events::PowerEvent.new(true))
+end
+```
+
+#### Dispatching Multiple Events
+Events are merged when dispatching multiples to reduce chatter.
+
+```ruby
+# Notice the pluralization of dispatch_event.
+group.dispatch_events(
+  Wizrb::Shared::Events::PowerEvent.new(true),
+  Wizrb::Shared::Events::RebootEvent.new
+)
+```
+
+#### Available Device Events
+```ruby
+# Boolean ON - OFF
+Wizrb::Shared::Events::PowerEvent.new(true)
+
+# No arguments
+Wizrb::Shared::Events::RebootEvent.new
+
+# No arguments
+Wizrb::Shared::Events::RefreshEvent.new
+
+# No arguments
+Wizrb::Shared::Events::ResetEvent.new
+```

data/doc/lighting.md

@@ -0,0 +1,186 @@
+# Wizrb Lighting Devices
+
+Lighting devices build onto the standard Wizrb Device feature set, providing the capability to create elaborate lighting setups.
+
+* [Connecting To Lighting Devices](#connecting-to-lighting-devices)
+  * [Individual Lighting Devices](#individual-lighting-devices)
+  * [Finding Lighting Devices](#finding-lighting-devices)
+* [Interacting With Lighting Devices](#interacting-with-lighting-devices)
+  * [Reading State](#reading-state)
+  * [Lighting State Control](#lighting-state-control)
+  * [Available Lighting Events](#available-lighting-events)
+* [Scenes](#scenes)
+  * [Creating Custom Scenes](#creating-custom-scenes)
+  * [Using Custom Scenes](#using-custom-scenes)
+
+## Connecting To Lighting Devices
+
+#### Individual Lighting Devices
+```ruby
+# Connect to light @ 127.0.0.1
+light = Wizrb::Lighting::Products::Light.new(ip: '127.0.0.1')
+
+# Connect to light @ 127.0.0.1:38899
+light = Wizrb::Lighting::Products::Light.new(ip: '127.0.0.1', port: 38899)
+```
+
+#### Finding Lighting Devices
+```ruby
+# Finding all devices:
+group = Wizrb::Lighting::Discover.all
+# => Wizrb::Lighting::Group
+
+# Finding all devices in home by ID:
+group = Wizrb::Lighting::Discover.home(1234)
+# => Wizrb::Lighting::Group
+
+# Finding all devices in room by ID:
+group = Wizrb::Lighting::Discover.room(1234)
+# => Wizrb::Lighting::Group
+```
+
+## Interacting With Lighting Devices
+Rrefer to ["Interacting With Devices"](devices.md#interacting-with-devices) in the Wizrb Devices documentation for the standard set of device interactions.
+
+#### Reading State
+```ruby
+light = Wizrb::Lighting::Products::Light.new(ip: '127.0.0.1')
+
+light.state
+# => Wizrb::Lighting::State
+
+light.state.power
+# => true
+
+light.state.cold_white
+# => 255
+
+light.state.color_temp
+# => 3200
+
+light.state.brightness
+# => 100
+
+light.state.rgb
+# => { red: 255, green: 255, blue: 255 }
+
+light.state.scene
+# => :party
+
+light.state.speed
+# => 200
+
+light.state.warm_white
+# => 255
+```
+
+#### Lighting State Control
+```ruby
+light = Wizrb::Lighting::Products::Light.new(ip: '127.0.0.1')
+
+# Integer 10 - 100
+light.brightness(100)
+
+# Integer 1 - 255
+light.cold_white(255)
+
+# Integer 1000 - 10000 in increments of 100
+light.color_temp(3200)
+
+# Integers 0 - 255
+light.rgb(255, 255, 255)
+
+# Any key in Wizrb::Lighting::SCENES
+light.scene(:party)
+
+# Integer 10 - 200
+light.speed(200)
+
+# Integer 1 - 255
+light.warm_white(255)
+```
+
+#### Available Lighting Events
+```ruby
+# Integer 10 - 100
+Wizrb::Lighting::Events::SetBrightnessEvent.new(100)
+
+# Integer 1 - 255
+Wizrb::Lighting::Events::SetColdWhiteEvent.new(255)
+
+# Integer 1000 - 10000 in increments of 100
+Wizrb::Lighting::Events::SetColorTempEvent.new(3200)
+
+# Integers 0 - 255
+Wizrb::Lighting::Events::SetRgbEvent.new(255, 255, 255)
+
+# Any key in Wizrb::Lighting::SCENES
+Wizrb::Lighting::Events::SetSceneEvent.new(:party)
+
+# Integer 10 - 200
+Wizrb::Lighting::Events::SetSpeedEvent.new(200)
+
+# Integer 1 - 255
+Wizrb::Lighting::Events::SetWarmWhiteEvent.new(255)
+```
+
+## Scenes
+
+#### Creating Custom Scenes
+You can create custom scenes that inherit from `Wizrb::Lighting::Scenes::Scene`.
+```ruby
+# frozen_string_literal: true
+
+class BurglarScene < Wizrb::Lighting::Scenes::Scene
+  RED_STATE_EVENTS = [
+    Wizrb::Lighting::Events::SetBrightnessEvent.new(100),
+    Wizrb::Lighting::Events::SetRgbEvent.new(255, 0, 0)
+  ].freeze
+
+  BLUE_STATE_EVENTS = [
+    Wizrb::Lighting::Events::SetBrightnessEvent.new(100),
+    Wizrb::Lighting::Events::SetRgbEvent.new(0, 0, 255)
+  ].freeze
+
+  def initialize(group)
+    super(group)
+    @toggle = true
+  end
+
+  protected
+
+  # Do something before your scene starts.
+  def before_start
+     @group.dispatch_event(Wizrb::Shared::Events::PowerEvent.new(true))
+  end
+
+  # Called on loop until scene stopped.
+  def step
+    if @toggle
+      @group.dispatch_events(*RED_STATE_EVENTS)
+    else
+      @group.dispatch_events(*BLUE_STATE_EVENTS)
+    end
+
+    @toggle = !@toggle
+    sleep(1)
+  end
+
+  # Do something after your scene stops.
+  def after_stop
+    @group.dispatch_event(Wizrb::Shared::Events::PowerEvent.new(false))
+  end
+end
+```
+
+#### Using Custom Scenes
+```ruby
+group = Wizrb::Lighting::Discover.all
+scene = BurglarScene.new(group)
+
+# Start the scene.
+scene.start
+
+# Stop the scene.
+scene.stop
+```

data/doc/power.md

@@ -0,0 +1,37 @@
+# Wizrb Power Devices
+
+Power devices do not extend beyond the features of standard Wizrb Devices. For more information refer to the [Wizrb Devices](devices.md) documentation.
+
+* [Connecting To Power Devices](#connecting-to-power-devices)
+  * [Individual Power Devices](#individual-power-devices)
+  * [Finding Power Devices](#finding-power-devices)
+* [Interacting With Power Devices](#interacting-with-power-devices)
+
+## Connecting To Power Devices
+
+#### Individual Power Devices
+```ruby
+# Connect to plug @ 127.0.0.1
+plug = Wizrb::Power::Products::SmartPlug.new(ip: '127.0.0.1')
+
+# Connect to plug @ 127.0.0.1:38899
+plug = Wizrb::Power::Products::SmartPlug.new(ip: '127.0.0.1', port: 38899)
+```
+
+#### Finding Power Devices
+```ruby
+# Finding all devices:
+group = Wizrb::Power::Discover.all
+# => Wizrb::Power::Group
+
+# Finding all devices in home by ID:
+group = Wizrb::Power::Discover.home(1234)
+# => Wizrb::Power::Group
+
+# Finding all devices in room by ID:
+group = Wizrb::Power::Discover.room(1234)
+# => Wizrb::Power::Group
+```
+
+## Interacting With Power Devices
+Rrefer to ["Interacting With Devices"](devices.md#interacting-with-devices) in the Wizrb Devices documentation.

data/exe/wizrb

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'wizrb/cli'
+Wizrb::CLI.start

data/lib/wizrb/cli.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'wizrb'
+
+module Wizrb
+  class CLI < Thor
+    include Thor::Actions
+
+    package_name 'Wizrb'
+
+    desc 'scene [SCENE]', 'Start a scene on all lights'
+    method_option :scene, aliases: '-s', type: :string, required: true
+    def scene
+      scene_type = load_scene
+      return unless scene_type
+
+      group = find_lights
+      return unless group
+
+      scene = scene_type.new(group)
+      start(scene)
+      prompt_stop
+      stop(scene)
+    end
+
+    private
+
+    def scene_class(string)
+      name = string.split('_').map(&:capitalize).join
+      Object.const_get("Wizrb::Lighting::Scenes::#{name}Scene")
+    rescue NameError
+      nil
+    end
+
+    def load_scene
+      say('Loading scene...  ')
+      scene_type = scene_class(options[:scene])
+
+      if scene_type
+        say('DONE', :green)
+      else
+        say('INVALID SCENE', :red)
+      end
+
+      scene_type
+    end
+
+    def find_lights
+      say('Finding lights... ')
+      group = Wizrb::Lighting::Discover.all(wait: 10)
+
+      if group.count == 0
+        say('NONE FOUND', :red)
+        return nil
+      else
+        say("#{group.count} FOUND", :green)
+      end
+
+      group
+    end
+
+    def start(scene)
+      say('Starting scene... ')
+      scene.start
+      say('DONE', :green)
+    end
+
+    def prompt_stop
+      nil until yes?('Would you like to stop? [y, yes]')
+    end
+
+    def stop(scene)
+      say('Stopping scene... ')
+      scene.stop
+      say('DONE', :green)
+    end
+  end
+end

data/lib/wizrb/lighting/discover.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative '../shared/discover'
+require_relative 'group'
+require_relative 'products/dimable_light'
+require_relative 'products/tunable_light'
+require_relative 'products/rgb_light'
+
+module Wizrb
+  module Lighting
+    class Discover < Wizrb::Shared::Discover
+      private
+
+      def parse_response(data, addr)
+        response = JSON.parse(data)
+        return unless response.dig('result', 'success') && addr[1] && addr[2]
+
+        resolve_device(ip: addr[2], port: addr[1])
+      rescue StandardError
+        nil
+      end
+
+      def resolve_device(ip:, port: 38_899)
+        module_name = Wizrb::Shared::Products::Device.new(ip: ip, port: port).module_name
+
+        if module_name.include?(Wizrb::Lighting::Products::RgbLight::MODULE_NAME_IDENTIFIER)
+          Wizrb::Lighting::Products::RgbLight.new(ip: ip, port: port)
+        elsif module_name.include?(Wizrb::Lighting::Products::TunableLight::MODULE_NAME_IDENTIFIER)
+          Wizrb::Lighting::Products::TunableLight.new(ip: ip, port: port)
+        elsif module_name.include?(Wizrb::Lighting::Products::DimableLight::MODULE_NAME_IDENTIFIER)
+          Wizrb::Lighting::Products::DimableLight.new(ip: ip, port: port)
+        end
+      end
+
+      def group_devices
+        Wizrb::Lighting::Group.new(devices: @devices)
+      end
+    end
+  end
+end

data/lib/wizrb/lighting/events/set_brightness_event.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative '../../shared/events/base'
+
+module Wizrb
+  module Lighting
+    module Events
+      class SetBrightnessEvent < Wizrb::Shared::Events::Base
+        MIN_VALUE = 10
+        MAX_VALUE = 100
+
+        def initialize(value)
+          validate!(value)
+          super(method: 'setState', params: { dimming: value.to_i })
+        end
+
+        private
+
+        def validate!(value)
+          return if value && value >= MIN_VALUE && value <= MAX_VALUE
+
+          raise ArgumentError, "Brightness must be an integer between #{MIN_VALUE} and #{MAX_VALUE}"
+        end
+      end
+    end
+  end
+end

data/lib/wizrb/lighting/events/set_cold_white_event.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative '../../shared/events/base'
+
+module Wizrb
+  module Lighting
+    module Events
+      class SetColdWhiteEvent < Wizrb::Shared::Events::Base
+        MIN_VALUE = 1
+        MAX_VALUE = 255
+
+        def initialize(value)
+          validate!(value)
+          super(method: 'setState', params: { c: value })
+        end
+
+        private
+
+        def validate!(value)
+          return if value && value >= MIN_VALUE && value <= MAX_VALUE
+
+          raise ArgumentError, "Cold white must be between #{MIN_VALUE} and #{MAX_VALUE}"
+        end
+      end
+    end
+  end
+end

data/lib/wizrb/lighting/events/set_color_temp_event.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative '../../shared/events/base'
+
+module Wizrb
+  module Lighting
+    module Events
+      class SetColorTempEvent < Wizrb::Shared::Events::Base
+        MIN_VALUE = 1000
+        MAX_VALUE = 12_000
+
+        def initialize(value)
+          validate!(value)
+          super(method: 'setState', params: { temp: value })
+        end
+
+        private
+
+        def validate!(value)
+          if !value || value < MIN_VALUE || value > MAX_VALUE
+            raise ArgumentError, "Temperature must be between #{MIN_VALUE} and #{MAX_VALUE} kelvin"
+          end
+
+          raise ArgumentError, 'Temperature must be divisible by 100' unless value % 100 == 0
+        end
+      end
+    end
+  end
+end