playful 0.1.0.alpha.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9760e12299c1d42be1a43596cc66d5d70ad07065
+  data.tar.gz: 4f64c01cb96411ca5f93174bfb145a12a34cc3f3
+SHA512:
+  metadata.gz: 51668cea99a82a52dbcbba1e08f134fb2300db97327fa7f7be0f15135646e53ecf4c5ab4f4a6bdf7a5b2be4b3823b9bff083df61717bc03c7332939ff9295053
+  data.tar.gz: 76f05414e46d0683230d8c38856efb78a2d412880a31bf9a00878b359d899caf9d83d0a8609e39e375276f8f138ac36056d3b0d550fab0487f2f366901c8484b

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+.bundle
+Gemfile.lock
+
+.autotest
+.DS_Store
+.loadpath
+.project
+.yardoc/
+.bundle/
+.idea/
+
+coverage/
+doc/
+pkg/
+tmp/
+
+*/.DS_Store
+atlassian-ide-plugin.xml

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0

data/Gemfile

@@ -0,0 +1,6 @@
+source 'http://rubygems.org'
+gemspec
+
+gem 'coveralls', require: false
+#gem "httpi", '>=2.0.0.rc1'
+#gem 'em-synchrony'

data/History.rdoc

@@ -0,0 +1,3 @@
+=== 0.1.0 TBD
+
+* I do stuffs!

data/LICENSE.rdoc

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2012 Steve Loveless
+
+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.rdoc

@@ -0,0 +1,194 @@
+= playful
+
+* {Homepage}[http://github.com/turboladen/playful]
+* {UPnP Device Architecture Documentation}[http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.0.pdf]
+* previously `upnp`
+
+{<img src="https://travis-ci.org/turboladen/playful.png?branch=master" alt="Build Status" />}[https://travis-ci.org/turboladen/playful]
+{<img src="https://coveralls.io/repos/turboladen/playful/badge.png" alt="Coverage Status" />}[https://coveralls.io/r/turboladen/playful]
+
+
+== Description
+
+Ruby's UPnP RubyGem was outdated in Ruby 1.9 when support for Soap4r was
+dropped.  This gem intends to fill that void for Ruby >= 1.9 and allow for SSDP
+search, discovery, advertisement, the ability to act as a UPnP control point, as
+well as provide UPnP devices and services.
+
+This uses EventMachine[http://github.com/eventmachine/eventmachine], so if
+you're not already, getting familiar with its concepts will be helpful here.
+
+=== Getting Started
+
+I'm still working out the overall design of these components, and thus won't be
+working towards a gem release until this settles down.  As such, don't expect
+interfaces to stay the same if you update.  In the mean time, I do intend to
+keep the master branch (mostly) stable, so please feel free to give it whirl and
+report any issues you encounter.
+
+* <code>gem install bundler</code>
+* <code>bundle install</code>
+
+== Features
+
+=== Implemented
+
+* SSDP search, discovery. (almost settled down)
+* Ability to act as a UPnP Control Point. (in progress)
+* Rack middleware to allow for device access in a Rack app.
+
+=== Coming
+
+* UPnP Devices & Services (server)
+
+== Examples
+
+Take a look at the +tasks+ directory; I've created some working examples using
+Thor[https://github.com/wycats/thor].  You can get a list of these tasks by
+doing `thor -T`.
+
+There's also a more involved, in-progress, working example at
+http://github.com/turboladen/upnp_cp_on_sinatra that uses the Rack middleware
+to build a Sinatra app that allows for controling devices in your network.
+
+=== SSDP Searches
+
+An SSDP search simply sends the M-SEARCH out to the multicast group and listens
+for responses for a given (or default of 5 seconds) amount of time.  The return
+from this depends on if you're running it within an EventMachine reactor or not.
+If not, it returns is an Array of responses as Hashes, where keys are the header
+names, values are the header values.  Take a look at the SSDP.search docs for
+more on the options here.
+
+  require 'playful/ssdp'
+
+  # Search for all devices (do an M-SEARCH with the ST header set to 'ssdp:all')
+  all_devices = UPnP::SSDP.search                         # this is default
+  all_devices = UPnP::SSDP.search 'ssdp:all'              # or be explicit
+  all_devices = UPnP::SSDP.search :all                    # or use short-hand
+
+  # Search for root devices (do an M-SEARCH with ST header set to 'upnp:rootdevices')
+  root_devices = UPnP::SSDP.search 'upnp:rootdevices'
+  root_devices = UPnP::SSDP.search :root                  # or use short-hand
+
+  # Search for a device with a specific UUID
+  my_device = UPnP::SSDP.search 'uuid:3c202906-992d-3f0f-b94c-90e1902a136d'
+
+  # Search for devices of a specific type
+  my_media_server = UPnP::SSDP.search 'urn:schemas-upnp-org:device:MediaServer:1'
+
+  # All of these searches will return something that looks like
+  # => [
+  #      {
+  #         :control => "max-age=1200",
+  #         :date => "Sun, 23 Sep 2012 20:31:48 GMT",
+  #         :location => "http://192.168.10.3:5001/description/fetch",
+  #         :server => "Linux-i386-2.6.38-15-generic-pae, UPnP/1.0, PMS/1.50.0",
+  #         :st => "upnp:rootdevice",
+  #         :ext => "",
+  #         :usn => "uuid:3c202906-992d-3f0f-b94c-90e1902a136d::upnp:rootdevice",
+  #         :length => "0"
+  #       }
+  #     ]
+
+If you do the search inside of an EventMachine reactor, as the
+UPnP::SSDP::Searcher receives and parses responses, it adds them to the accessor
+#discovery_responses, which is an EventMachine::Channel.  This lets you subscribe
+to the resposnes and do what you want with them (most likely you'll want to create
+UPnP::ControlPoint::Device objects so you can control your device) as you
+receive them.
+
+  require 'playful/ssdp'
+  require 'playful/control_point/device'
+
+  EM.run do
+    searcher = UPnP::SSDP.search 'uuid:3c202906-992d-3f0f-b94c-90e1902a136d'
+
+    # Create a deferrable object that can be notified when the device we want
+    # has been found and created.
+    device_controller = EventMachine::DefaultDeferrable.new
+
+    # This callback will get called when the device_creator callback is called
+    # (which is called after the device has been created).
+    device_controller.callback do |device|
+      p device.service_list.first.class                 # UPnP::ControlPoint::Service
+      p device.service_list.first.service_type          # "urn:schemas-upnp-org:service:ContentDirectory:1"
+
+      # SOAP actions are converted to Ruby methods--show those
+      p device.service_list.first.singleton_methods     # [:GetSystemUpdateID, :Search, :GetSearchCapabilities, :GetSortCapabilities, :Browse]
+
+      # Call a SOAP method defined in the service.  The response is extracted from the
+      # XML SOAP response and the value is converted from the UPnP dataType to
+      # the related Ruby type.  Reponses are always contained in a Hash, so as
+      # to maintain the relation defined in the service.
+      p device.service_list.first.GetSystemUpdateID     # { :Id => 1 }
+    end
+
+    # Note that you don't have to check for items in the Channel or for when the
+    # Channel is empty: EventMachine will pop objects off the Channel as soon as
+    # they're put there and stop when there are none left.
+    searcher.discovery_responses.pop do |notification|
+
+      # UPnP::ControlPoint::Device objects are EventMachine::Deferrables, so you
+      # need to define callback and errback blocks to handle when the Device
+      # object is done being created.
+      device_creator = UPnP::ControlPoint::Device.new(ssdp_notification: notification)
+
+      device_creator.errback do
+        puts "Failed creating the device."
+        exit!
+      end
+
+      device_creator.callback do |built_device|
+        puts "Device has been created now."
+
+        # This lets the device_controller know that the device has been created,
+        # calls its callback, and passes the built device to it.
+        device_controller.set_deferred_status(:succeeded, built_device)
+      end
+
+      # This actually starts the Device creation process and will call the
+      # callback or errback (above) when it's done.
+      device_creator.fetch
+    end
+  end
+
+=== ControlPoints
+
+If you're wanting to control devices and their services, you'll probably be more
+interested in using a UPnP::ControlPoint, instead of doing all that work (above)
+to create a UPnP::ControlPoint::Device.  The ControlPoint will handle doing the
+search and device/service creation for you and will hand you over Devices to
+control them (and present them in a UI, perhaps?) as you need.  More to come on
+this as the design settles down.
+
+== Requirements
+
+* Rubies (tested)
+  * 1.9.3
+  * 2.0.0
+  * 2.1.0
+* Gems
+  * eventmachine
+  * em-http-request
+  * em-synchrony
+  * nori
+  * log_switch
+  * savon
+* Gems (development)
+  * bundler
+  * rspec
+  * simplecov
+  * thin
+  * yard
+
+== Install
+
+  # This won't work yet, as the gem has not yet been released...
+  $ gem install playful
+
+== Copyright
+
+Copyright (c) 2012 sloveless
+
+See LICENSE.rdoc for details.

data/Rakefile

@@ -0,0 +1,20 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'cucumber/rake/task'
+require 'yard'
+
+
+YARD::Rake::YardocTask.new
+Cucumber::Rake::Task.new(:features)
+RSpec::Core::RakeTask.new
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+# Alias for rubygems-test
+task test: :spec
+
+task default: :test
+

data/features/control_point.feature

@@ -0,0 +1,13 @@
+Feature: Control Point
+  As a consumer of UPnP devices and services
+  I want to act as a UPnP control point
+  So that I can control the devices and services that fulfill my needs
+
+  Scenario: Search for devices on startup
+    Given I have a non-local IP address
+    And a UDP port on that IP is free
+    When I create my control point
+    And tell it to find all root devices
+    And tell it to find all services
+    Then it gets a list of root devices
+    And it gets a list of services

data/features/device.feature

@@ -0,0 +1,22 @@
+Feature: Controlled Device
+  As a UPnP device user
+  I want to use the device that offers some service
+  So that I can consume that service
+
+  Scenario: Device added to the network
+    Given I have a non-local IP address
+    And a UDP port on that IP is free
+    When I start my device on that IP address and port
+    Then the device multicasts a discovery message
+
+  @negative
+  Scenario: Device startup without an IP
+    Given I don't have an IP address
+    When I start the device
+    Then I get an error message saying I don't have an IP address
+
+  Scenario: Device startup with a local-link IP
+    Given I have a local-link IP address
+    When I start the device
+    Then the device starts running normally
+

data/features/device_discovery.feature

@@ -0,0 +1,9 @@
+Feature: Device discovery
+  As a device control point, I want to be able to discover devices
+  so that I can use the services those devices provide
+
+  Scenario: A single root device
+    Given there's at least 1 root device in my network
+    When I come online
+    Then I should discover at least 1 root device
+    And the location of that device should match my fake device's location

data/features/step_definitions/control_point_steps.rb

@@ -0,0 +1,19 @@
+When /^I create my control point$/ do
+  @control_point = UPnP::ControlPoint.new
+end
+
+When /^tell it to find all root devices$/ do
+  @control_point.find_devices(:root, 5)
+end
+
+When /^tell it to find all services$/ do
+  @control_point.find_services
+end
+
+Then /^it gets a list of root devices$/ do
+  @control_point.device_list.should_not be_empty
+end
+
+Then /^it gets a list of services$/ do
+  @control_point.services.should_not be_empty
+end

data/features/step_definitions/device_discovery_steps.rb

@@ -0,0 +1,40 @@
+require_relative '../support/fake_upnp_device_collection'
+require 'cucumber/rspec/doubles'
+
+Thread.abort_on_exception = true
+UPnP::SSDP.log = false
+
+Given /^there's at least (\d+) root device in my network$/ do |device_count|
+  fake_device_collection.respond_with = <<-ROOT_DEVICE
+HTTP/1.1 200 OK\r
+CACHE-CONTROL: max-age=1200\r
+DATE: Mon, 26 Sep 2011 06:40:19 GMT\r
+LOCATION: http://#{local_ip}:4567\r
+SERVER: Linux-i386-2.6.38-10-generic-pae, UPnP/1.0, PMS/1.25.1\r
+ST: upnp:rootdevice\r
+EXT:\r
+USN: uuid:3c202906-992d-3f0f-b94c-90e1902a136d::upnp:rootdevice\r
+Content-Length: 0\r
+
+  ROOT_DEVICE
+
+  Thread.start { fake_device_collection.start_ssdp_listening }
+  Thread.start { fake_device_collection.start_serving_description }
+  sleep 0.2
+end
+
+When /^I come online$/ do
+  control_point.should be_a UPnP::ControlPoint
+end
+
+Then /^I should discover at least (\d+) root device$/ do |device_count|
+  control_point.find_devices(:root)
+  fake_device_collection.stop_ssdp_listening
+  fake_device_collection.stop_serving_description
+  control_point.device_list.should have_at_least(device_count.to_i).items
+end
+
+Then /^the location of that device should match my fake device's location$/ do
+  locations = control_point.device_list.map { |device| device[:location] }
+  locations.should include "http://#{local_ip}:4567"
+end

data/features/step_definitions/device_steps.rb

@@ -0,0 +1,28 @@
+When /^I start my device on that IP address and port$/ do
+  @device = UPnP::Device.new(@local_ip, @port)
+  @device.start.should be_true
+end
+
+Then /^the device multicasts a discovery message$/ do
+  pending # express the regexp above with the code you wish you had
+end
+
+Given /^I don't have an IP address$/ do
+  pending # express the regexp above with the code you wish you had
+end
+
+When /^I start the device$/ do
+  pending # express the regexp above with the code you wish you had
+end
+
+Then /^I get an error message saying I don't have an IP address$/ do
+  pending # express the regexp above with the code you wish you had
+end
+
+Given /^I have a local\-link IP address$/ do
+  pending # express the regexp above with the code you wish you had
+end
+
+Then /^the device starts running normally$/ do
+  pending # express the regexp above with the code you wish you had
+end

data/features/support/common.rb

@@ -0,0 +1,9 @@
+Given /^I have a non-local IP address$/ do
+  @local_ip, @port = local_ip_and_port
+  @local_ip.should_not be_nil
+  @local_ip.should_not match /^127.0.0/
+end
+
+Given /^a UDP port on that IP is free$/ do
+  @port.should_not be_nil
+end