ligo 0.1.0.beta → 0.1.0

data/.gitignore

@@ -1,2 +1,3 @@
 doc/
 pkg/
+.yardoc

data/ChangeLog.md

@@ -1,4 +1,3 @@
-### 0.1.0 / 2012-12-06
-
-* Initial release:
+### 0.1.0 / 2012-12-24
 
+* Initial release

data/Rakefile

@@ -31,10 +31,30 @@ begin
   gem 'yard', '~> 0.8'
   require 'yard'
 
-  YARD::Rake::YardocTask.new  
+  YARD::Rake::YardocTask.new
 rescue LoadError => e
   task :yard do
     abort "Please run `gem install yard` to install YARD."
   end
 end
 task :doc => :yard
+
+begin
+  gem 'yardstick', '~> 0.8.0'
+
+  require 'yardstick/rake/measurement'
+
+  Yardstick::Rake::Measurement.new(:yardstick_measure) do |measurement|
+    measurement.output = 'doc/measurement_report.txt'
+  end
+
+  require 'yardstick/rake/verify'
+
+  Yardstick::Rake::Verify.new do |verify|
+    verify.threshold = 100
+  end
+rescue LoadError => e
+  task :yardstick do
+    abort "Please run `gem install yardstick` to install yardstick."
+  end
+end

data/bin/ligo-sample

@@ -46,9 +46,13 @@ eof
         loop do
           res = nil
           mutex.synchronize do
-            output_string = dev.recv(1024)
-            unless output_string.nil?
-              puts "IN  -- String received: #{output_string}"
+            begin
+              output_string = dev.read(1024, 200)
+              unless output_string.nil?
+                puts "IN  -- String received: #{output_string}"
+              end
+            rescue LIBUSB::ERROR_TIMEOUT
+              # do nothing and proceed
             end
           end
           # get some time to write data if any

data/lib/ligo.rb

@@ -20,15 +20,14 @@ require 'libusb'
 
 require 'ligo/version'
 
-# Ligo module.
-#
 # This module contains the Android Open Accessory Protocol utility classes to
 # enable custom USB I/O with AOAP-compatible devices.
 #
-# @see http://source.android.com/tech/accessories/aoap/aoa.html
 # @see http://source.android.com/tech/accessories/index.html
+# @see http://source.android.com/tech/accessories/aoap/aoa.html
 # @see
 #  http://developer.android.com/guide/topics/connectivity/usb/accessory.html
+# @author Renaud AUBIN
 module Ligo
   require 'ligo/logging'
   require 'ligo/constants'

data/lib/ligo/accessory.rb

@@ -17,26 +17,121 @@
 
 module Ligo
 
+  # A virtual accessory to interact via usb with an android device according
+  # to the Android Open Accessory Protocol.
+  #
+  # @see http://source.android.com/tech/accessories/index.html
+  # @see http://source.android.com/tech/accessories/aoap/aoa.html
+  # @see
+  #  http://developer.android.com/guide/topics/connectivity/usb/accessory.html
+  #
+  # @author Renaud AUBIN
+  # @api public
   class Accessory
     include Logging
 
-    # http://stackoverflow.com/questions/2680523/dry-ruby-initialization-with-hash-argument
-    attr_reader :id, :manufacturer, :model, :description, :version, :uri, :serial
-
+    # The default id used to initialize a new accessory if none is provided to
+    # the constructor
     DEFAULT_ID = {
       manufacturer: 'ligō',
       model:        'Demo',
       description:  'ligō virtual accessory',
       version:      '1.0',
       uri:          'https://github.com/nibua-r/ligo#readme',
-      serial:       '6c6967c58d20312e30' # 'ligō 1.0'.each_byte {|c| print c.to_i.to_s(16), '' }
+      # 'ligō 1.0'.each_byte {|c| print c.to_i.to_s(16), '' }
+      serial:       '6c6967c58d20312e30'
     }
 
+    # Returns the full identifying information hash
+    # @example
+    #   accessory = Ligo::Accessory.new
+    #   accessory.id
+    #   # => {:manufacturer=>"ligō",
+    #   #     :model=>"Demo",
+    #   #     :description=>"ligō virtual accessory",
+    #   #     :version=>"1.0",
+    #   #     :uri=>"https://github.com/nibua-r/ligo#readme",
+    #   #     :serial=>"6c6967c58d20312e30"}
+    # @return [Hash<Symbol, String>] the full identifying information hash.
+    attr_reader :id
+
+    # Returns the `manufacturer name` identifying string
+    # @example
+    #   accessory = Ligo::Accessory.new
+    #   accessory.manufacturer
+    #   # => "ligō"
+    # @return [String] the `manufacturer name` identifying string.
+    attr_reader :manufacturer
+
+    # Returns the `model name` identifying string
+    # @example
+    #   accessory = Ligo::Accessory.new
+    #   accessory.model
+    #   # => "Demo"
+    # @return [String] the `model name` identifying string.
+    attr_reader :model
+
+    # Returns the `description` identifying string
+    # @example
+    #   accessory = Ligo::Accessory.new
+    #   accessory.description
+    #   # => "ligō virtual accessory"
+    # @return [String] the `description` identifying string.
+    attr_reader :description
+
+    # Returns the `version` identifying string
+    # @example
+    #   accessory = Ligo::Accessory.new
+    #   accessory.version
+    #   # => "1.0"
+    # @return [String] the `version` identifying string.
+    attr_reader :version
+
+    # Returns the `uri` identifying string
+    # @example
+    #   acc = Ligo::Accessory.new
+    #   acc.uri
+    #   # => "https://github.com/nibua-r/ligo#readme"
+    # @return [String] the `uri` identifying string.
+    attr_reader :uri
+
+    # Returns the `serial` identifying string
+    # @example
+    #   accessory = Ligo::Accessory.new
+    #   accessory.serial
+    #   # => "6c6967c58d20312e30"
+    # @return [String] the `serial` identifying string.
+    attr_reader :serial
+
+    # Returns a new {Accessory} initialized with the provided identification
+    #
+    # @param [Hash<Symbol, String>] id
+    #   The accessory identifying information as a hash.
+    # @raise [ArgumentError] if the provided id is not a Hash or if one of the
+    #   identifying string is missing.
+    # @example
+    #   new_id =
+    #   {
+    #     manufacturer: 'MyVeryBigCompany Corp.',
+    #     model:        'AwesomeProduct',
+    #     description:  'Who cares about description! ← 😠',
+    #     version:      '0.0',
+    #     uri:          'http://www.foo.bar/awesome_product',
+    #     serial:       '⚀⚁⚂⚃⚄⚅012345678'
+    #   }
+    #   accessory = Ligo::Accessory.new(new_id)
     def initialize(id = DEFAULT_ID)
 
-      raise ArgumentError, '#new must be called with a Hash' unless id.is_a? Hash
+      unless id.is_a? Hash
+        raise ArgumentError, '#new must be called with a Hash'
+      end
+
+      required_ids = [:manufacturer,
+                      :model, :description,
+                      :version,
+                      :uri,
+                      :serial]
 
-      required_ids = [:manufacturer, :model, :description, :version, :uri, :serial]
       required_ids.each do |sym|
         raise ArgumentError, "Missing argument: #{sym}" unless id.include? sym
       end
@@ -44,7 +139,9 @@ module Ligo
       id.each do |k, v|
         raise ArgumentError, "#{k} is not a String" unless v.is_a? String
         raise ArgumentError, "#{k} must not be empty" if v.empty?
-        raise ArgumentError, "#{k} must contain at most 255 bytes" if v.bytesize > 255
+        if v.bytesize > 255
+          raise ArgumentError, "#{k} must contain at most 255 bytes"
+        end
         instance_variable_set "@#{k}", v unless v.nil?
       end
 
@@ -52,10 +149,27 @@ module Ligo
       logger.debug self.inspect
     end
 
+    # Returns {#id}.each
+    # @return block execution.
+    # @example
+    #   accessory.each do |k,v|
+    #     puts "#{k} = #{v}"
+    #   end
+    #   # manufacturer = ligō
+    #   # model = Demo
+    #   # description = ligō virtual accessory
+    #   # version = 1.0
+    #   # uri = https://github.com/nibua-r/ligo#readme
+    #   # serial = 6c6967c58d20312e30
     def each(&block)
       @id.each(&block)
     end
 
+    # Returns {#id}.keys
+    # @return [Array] {#id}.keys.
+    # @example
+    #   accessory.keys.inspect
+    #   # => "[:manufacturer, :model, :description, :version, :uri, :serial]"
     def keys
       @id.keys
     end

data/lib/ligo/context.rb

@@ -15,14 +15,20 @@
 # limitations under the License.
 #
 
-# TODO: Add a proper mention to libusb LGPL licensing since the following code
-# is a derivative work of Lars Kanis LIBUSB::Context.
-
 module Ligo
 
+  # This class is a derivative work of `LIBUSB::Context` as included in
+  #   [LIBUSB](https://github.com/larskanis/libusb), written by Lars Kanis and
+  #   released under the LGPLv3.
+  # @author Renaud AUBIN
+  # @api public
   class Context < LIBUSB::Context
     include LIBUSB
 
+    # @api private
+    # Returns the list of AOAP-compatible devices
+    # @return [Array<Ligo::Device>] the list of AOAP-compatible devices
+    #   currently connected on the USB bus.
     def device_list
       pppDevs = FFI::MemoryPointer.new :pointer
       size = Call.libusb_get_device_list(@ctx, pppDevs)
@@ -37,7 +43,7 @@ module Ligo
             # Include only AOAP compatible devices
             pDevs << device if device.aoap?
           rescue LIBUSB::ERROR_ACCESS
-            # TODO: do something about this exception, log at least!
+            # @todo Do something about this exception, log at least!
           end
         end
       end

data/lib/ligo/device.rb

@@ -19,13 +19,49 @@ module Ligo
 
   require 'ligo/constants'
 
+  # This class provides a convenient wrapper class around `LIBUSB::Device` and
+  #   implements the Android Open Accessory Protocol to interact with compatible
+  #   devices.
+  #
+  # This class is a derivative work of `LIBUSB::Device` as included in
+  #   [LIBUSB](https://github.com/larskanis/libusb), written by Lars Kanis and
+  #   released under the LGPLv3.
+  # @author Renaud AUBIN
+  # @api public
   class Device < LIBUSB::Device
     include Logging
 
-    # TODO: Document the attr!
-    attr_reader :pDev, :pDevDesc
-    attr_reader :aoap_version, :accessory, :in, :out, :handle
+    # @api private
+    attr_reader :pDev
 
+    # @api private
+    attr_reader :pDevDesc
+
+    # Returns the version of the AOA protocol that this device supports
+    # @return [Fixnum] the version of the AOA protocol that this device
+    #   supports.
+    attr_reader :aoap_version
+
+    # Returns the associated {Accessory}
+    # @return [Accessory, nil] the associated accessory if any or nil.
+    attr_reader :accessory
+
+    # Returns the accessory mode input endpoint
+    # @return [LIBUSB::Endpoint, nil] the input endpoint or nil if the device is
+    #   not in accessory mode.
+    attr_reader :in
+
+    # Returns the accessory mode output endpoint
+    # @return [LIBUSB::Endpoint, nil] the output endpoint or nil if the device
+    #   is not in accessory mode.
+    attr_reader :out
+
+    # Returns the device handle
+    # @todo Improve the :handle doc
+    # @return [LIBUSB::DevHandle, nil] the device handle or nil.
+    attr_reader :handle
+
+    # @api private
     def initialize context, pDev
       @aoap_version = 0
       @accessory, @in, @out, @handle = nil, nil, nil, nil
@@ -48,6 +84,9 @@ module Ligo
       end
     end
 
+    # Opens an handle and claim the default interface for further operations
+    # @return [LIBUSB::DevHandle] the handle to operate on.
+    # @raise
     def open_and_claim
       @handle = open
       @handle.claim_interface(0)
@@ -55,6 +94,9 @@ module Ligo
       @handle
     end
 
+    # Finalizes the device (release and close)
+    # @return
+    # @raise [LIBUSB::ERROR_TIMEOUT] in case of timeout.
     def finalize
       if @handle
         @handle.release_interface(0)
@@ -62,7 +104,7 @@ module Ligo
       end
     end
 
-    # Simple write method (blocking until timeout).
+    # Simple write method (blocking until timeout)
     # @param [Fixnum] buffer_size
     #   The number of bytes expected to be received.
     # @param [Fixnum] timeout
@@ -74,8 +116,9 @@ module Ligo
                            dataIn: buffer_size,
                            timeout: timeout)
     end
+    alias_method :recv, :read
 
-    # Simple write method (blocking until timeout).
+    # Simple write method (blocking until timeout)
     # @param [String] buffer
     #   The buffer to be sent.
     # @param [Fixnum] timeout
@@ -87,32 +130,9 @@ module Ligo
                              dataOut: buffer,
                              timeout: timeout)
     end
+    alias_method :send, :write
 
-    # Simple recv method.
-    # @param [Fixnum] buffer_size
-    #   The buffer size of the received buffer.
-    # @return [String] the received buffer (at most buffer_size bytes).
-    def recv(buffer_size)
-      begin
-        handle.bulk_transfer(endpoint: @in,
-                             dataIn: buffer_size)
-      rescue LIBUSB::ERROR_TIMEOUT
-        nil
-        # maybe we should implement a internal thread, a sleep and a retry
-      end
-    end
-
-    # Simple send method.
-    # @param [String] data
-    #   The data to be sent.
-    # @return [Fixnum] the number of bytes sent.
-    def send(data)
-      # TODO: Add timeout param?
-      handle.bulk_transfer(endpoint: @out, dataOut: data)
-    end
-
-    # Associate an AOAP compatible device with a virtual accessory and switch the Android device
-    # to accessory mode.
+    # Associates with an accessory and switch to accessory mode
     #
     # Prepare an OAP compatible device to interact with a given {Ligo::Accessory}:
     # * Switch the current assigned device to accessory mode
@@ -153,8 +173,11 @@ module Ligo
       true
     end
 
+    # Switches to accessory mode
+    #
     # Send identifying string information to the device and request the device start up in accessory
     # mode.
+    # @return [true, false] true for success, false otherwise.
     def start_accessory_mode
       logger.debug 'start_accessory_mode'
       sn = self.serial_number
@@ -169,6 +192,8 @@ module Ligo
       wait_and_retrieve_by_serial(sn)
     end
 
+    # Sends a `set configuration` control transfer
+    #
     # Set the device's configuration to a value of 1 with a SET_CONFIGURATION (0x09) device
     # request.
     # @return [true, false] true for success, false otherwise.
@@ -193,14 +218,14 @@ module Ligo
       end
     end
 
-    # Check if the current {Ligo::Device} is in accessory mode.
-    # @return [true, false] true if the {Ligo::Device} is in accessory mode,
-    #   false otherwise.
+    # Check if the current {Device} is in accessory mode
+    # @return [true, false] true if the {Device} is in accessory mode, false
+    #   otherwise.
     def accessory_mode?
       self.idVendor == GOOGLE_VID
     end
 
-    # Check if the current {Ligo::Device} supports AOAP.
+    # Check if the current {Device} supports AOAP
     # @return [true, false] true if the {Ligo::Device} supports AOAP, false
     #   otherwise.
     def aoap?
@@ -209,9 +234,8 @@ module Ligo
       @aoap_version >= 1
     end
 
-    # Check if the current {Ligo::Device} is in UMS mode.
-    # @return [true, false] true if the {Ligo::Device} is in UMS mode, false
-    #   otherwise.
+    # Check if the current {Device} is in UMS mode
+    # @return [true, false] true if the {Device} is in UMS mode, false otherwise
     def uas?
       if RUBY_PLATFORM=~/linux/i
         # http://cateee.net/lkddb/web-lkddb/USB_UAS.html
@@ -222,8 +246,11 @@ module Ligo
       end
     end
 
+    # Sends a `get protocol` control transfer
+    #
     # Send a 51 control request ("Get Protocol") to figure out if the device
-    # supports the Android accessory protocol.
+    #   supports the Android accessory protocol. We assume here that the device
+    #   has not been opened.
     # @return [Fixnum] the AOAP protocol version supported by the device (0 for
     #   no AOAP support).
     def get_protocol
@@ -243,7 +270,11 @@ module Ligo
       (res.size == 2 && version >= 1 ) ? version : 0
     end
 
-    # Send identifying string information to the device.
+    # Sends identifying string information to the device
+    #
+    # We assume here that the device has already been opened.
+    # @api private
+    # @return
     def send_accessory_id
       logger.debug 'send_accessory_id'
       req_type = LIBUSB::ENDPOINT_OUT | LIBUSB::REQUEST_TYPE_VENDOR
@@ -260,7 +291,9 @@ module Ligo
     end
     private :send_accessory_id
 
-    # Request the device start up in accessory mode
+    # Sends AOA protocol start command to the device
+    # @api private
+    # @return [Fixnum]
     def send_start
       logger.debug 'send_start'
       req_type = LIBUSB::ENDPOINT_OUT | LIBUSB::REQUEST_TYPE_VENDOR
@@ -270,7 +303,8 @@ module Ligo
     end
     private :send_start
 
-    # Internal use only.
+    # @api private
+    # @return [true, false] true for success, false otherwise.
     def wait_and_retrieve_by_serial(sn)
       sleep REENUMERATION_DELAY
       # The device should now reappear on the usb bus with the Google vendor id.
@@ -283,6 +317,7 @@ module Ligo
         # Retrieve new pointers (check if the old ones should be dereferenced)
         @pDev = device.pDev
         @pDevDesc = device.pDevDesc
+        true
       else
         logger.error ['Failed to retrieve the device after switching to ',
                       'accessory mode. This may be due to a lack of proper ',
@@ -291,6 +326,7 @@ module Ligo
                       'SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ',
                       'MODE="0666", GROUP="plugdev"'
                      ].join
+        false
       end
     end
     private :wait_and_retrieve_by_serial

data/lib/ligo/logging.rb

@@ -19,7 +19,7 @@ require 'logger'
 
 module Ligo
 
-  # Logging module.
+  # Logging module
   #
   # This module enables to share the same logger between all the Ligo classes.
   module Logging

data/lib/ligo/version.rb

@@ -17,5 +17,5 @@
 
 module Ligo
   # ligō version
-  VERSION = "0.1.0.beta"
+  VERSION = "0.1.0"
 end

data/ligo.gemspec

@@ -24,5 +24,6 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'rspec', '~> 2.4'
   gem.add_development_dependency 'rubygems-tasks', '~> 0.2'
   gem.add_development_dependency 'yard', '~> 0.8'
+  gem.add_development_dependency 'yardstick', '~> 0.8.0'
   gem.add_development_dependency 'pry', '~> 0.9.10'
 end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: ligo
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta
-  prerelease: 6
+  version: 0.1.0
+  prerelease: 
 platform: ruby
 authors:
 - Renaud AUBIN
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-22 00:00:00.000000000 Z
+date: 2012-12-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: libusb
@@ -75,6 +75,22 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: yardstick
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.0
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -137,9 +153,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23