ligo 0.1.0.beta

data/lib/ligo/device.rb

@@ -0,0 +1,300 @@
+# -*- coding: utf-8; fill-column: 80 -*-
+#
+# Copyright (c) 2012 Renaud AUBIN
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+module Ligo
+
+  require 'ligo/constants'
+
+  class Device < LIBUSB::Device
+    include Logging
+
+    # TODO: Document the attr!
+    attr_reader :pDev, :pDevDesc
+    attr_reader :aoap_version, :accessory, :in, :out, :handle
+
+    def initialize context, pDev
+      @aoap_version = 0
+      @accessory, @in, @out, @handle = nil, nil, nil, nil
+      super context, pDev
+    end
+
+    def process(&block)
+      begin
+        self.open_interface(0) do |handle|
+          @handle = handle
+          yield handle
+          @handle = nil
+        end
+        # close
+      rescue LIBUSB::ERROR_NO_DEVICE
+        msg =  'The target device has been disconnected'
+        logger.debug msg
+        # close
+        raise Interrupt, msg
+      end
+    end
+
+    def open_and_claim
+      @handle = open
+      @handle.claim_interface(0)
+      @handle.clear_halt(@in)
+      @handle
+    end
+
+    def finalize
+      if @handle
+        @handle.release_interface(0)
+        @handle.close
+      end
+    end
+
+    # Simple write method (blocking until timeout).
+    # @param [Fixnum] buffer_size
+    #   The number of bytes expected to be received.
+    # @param [Fixnum] timeout
+    #   The timeout in ms (default: 1000). 0 for an infinite timeout.
+    # @return [String] the received buffer (at most buffer_size bytes).
+    # @raise [LIBUSB::ERROR_TIMEOUT] in case of timeout.
+    def read(buffer_size, timeout = 1000)
+      handle.bulk_transfer(endpoint: @in,
+                           dataIn: buffer_size,
+                           timeout: timeout)
+    end
+
+    # Simple write method (blocking until timeout).
+    # @param [String] buffer
+    #   The buffer to be sent.
+    # @param [Fixnum] timeout
+    #   The timeout in ms (default: 1000). 0 for an infinite timeout.
+    # @return [Fixnum] the number of bytes actually sent.
+    # @raise [LIBUSB::ERROR_TIMEOUT] in case of timeout.
+    def write(buffer, timeout = 1000)
+        handle.bulk_transfer(endpoint: @out,
+                             dataOut: buffer,
+                             timeout: timeout)
+    end
+
+    # 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.
+    #
+    # Prepare an OAP compatible device to interact with a given {Ligo::Accessory}:
+    # * Switch the current assigned device to accessory mode
+    # * Set the I/O endpoints
+    # @param [Ligo::Accessory] accessory
+    #   The virtual accessory to be associated with the Android device.
+    # @return [true, false] true for success, false otherwise.
+    def attach_accessory(accessory)
+      logger.debug "attach_accessory(#{accessory})"
+
+      @accessory = accessory
+
+      if accessory_mode?
+        # if the device is already in accessory mode, we send
+        # set_configuration to force an usb attached event on the device
+        begin
+          set_configuration
+        rescue LIBUSB::ERROR_NO_DEVICE
+          logger.debug '  set_configuration raises LIBUSB::ERROR_NO_DEVICE - Retry'
+          sleep REENUMERATION_DELAY
+          # Set configuration may fail
+          retry
+        end
+      else
+        # the device is not in accessory mode, start_accessory_mode is
+        # sufficient to get an usb attached event on the device
+        return false unless start_accessory_mode
+      end
+
+      # Find out the in/out endpoints
+      self.interfaces.first.endpoints.each do |ep|
+        if ep.bEndpointAddress & 0b10000000 == 0
+          @out = ep if @out.nil?
+        else
+          @in = ep if @in.nil?
+        end
+      end
+      true
+    end
+
+    # Send identifying string information to the device and request the device start up in accessory
+    # mode.
+    def start_accessory_mode
+      logger.debug 'start_accessory_mode'
+      sn = self.serial_number
+
+      self.open_interface(0) do |handle|
+        @handle = handle
+        send_accessory_id
+        send_start
+        @handle = nil
+      end
+
+      wait_and_retrieve_by_serial(sn)
+    end
+
+    # 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.
+    def set_configuration
+      logger.debug 'set_configuration'
+      res = nil
+      sn = self.serial_number
+      device = @context.devices(idVendor: GOOGLE_VID).collect do |d|
+        d.serial_number == sn ? d : nil
+      end.compact.first
+
+      begin
+        device.open_interface(0) do |handle|
+          req_type = LIBUSB::ENDPOINT_OUT | LIBUSB::REQUEST_TYPE_STANDARD
+          res = handle.control_transfer(bmRequestType: req_type,
+                                        bRequest: LIBUSB::REQUEST_SET_CONFIGURATION,
+                                        wValue: 1, wIndex: 0x0, dataOut: nil)
+        end
+
+        wait_and_retrieve_by_serial(sn)
+        res == 0
+      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.
+    def accessory_mode?
+      self.idVendor == GOOGLE_VID
+    end
+
+    # Check if the current {Ligo::Device} supports AOAP.
+    # @return [true, false] true if the {Ligo::Device} supports AOAP, false
+    #   otherwise.
+    def aoap?
+      @aoap_version = self.get_protocol
+      logger.info "#{self.inspect} supports AOAP version #{@aoap_version}."
+      @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.
+    def uas?
+      if RUBY_PLATFORM=~/linux/i
+        # http://cateee.net/lkddb/web-lkddb/USB_UAS.html
+        (self.settings[0].bInterfaceClass == 0x08) &&
+          (self.settings[0].bInterfaceSubClass == 0x06)
+      else
+        false
+      end
+    end
+
+    # Send a 51 control request ("Get Protocol") to figure out if the device
+    # supports the Android accessory protocol.
+    # @return [Fixnum] the AOAP protocol version supported by the device (0 for
+    #   no AOAP support).
+    def get_protocol
+      logger.debug 'get_protocol'
+      res, version = 0, 0
+      self.open do |h|
+
+        h.detach_kernel_driver(0) if self.uas? && h.kernel_driver_active?(0)
+        req_type = LIBUSB::ENDPOINT_IN | LIBUSB::REQUEST_TYPE_VENDOR
+        res = h.control_transfer(bmRequestType: req_type,
+                                 bRequest: COMMAND_GETPROTOCOL,
+                                 wValue: 0x0, wIndex: 0x0, dataIn: 2)
+
+        version = res.unpack('S')[0]
+      end
+
+      (res.size == 2 && version >= 1 ) ? version : 0
+    end
+
+    # Send identifying string information to the device.
+    def send_accessory_id
+      logger.debug 'send_accessory_id'
+      req_type = LIBUSB::ENDPOINT_OUT | LIBUSB::REQUEST_TYPE_VENDOR
+      @accessory.each do |k,v|
+        # Ensure the string is terminated by a null char
+        s = "#{v}\0"
+        r = @handle.control_transfer(bmRequestType: req_type,
+                                     bRequest: COMMAND_SENDSTRING, wValue: 0x0,
+                                     wIndex: @accessory.keys.index(k), dataOut: s)
+
+        # TODO: Manage an exception there. This should terminate the program.
+        logger.error "Failed to send #{k} string" unless r == s.size
+      end
+    end
+    private :send_accessory_id
+
+    # Request the device start up in accessory mode
+    def send_start
+      logger.debug 'send_start'
+      req_type = LIBUSB::ENDPOINT_OUT | LIBUSB::REQUEST_TYPE_VENDOR
+      res = @handle.control_transfer(bmRequestType: req_type,
+                                     bRequest: COMMAND_START, wValue: 0x0,
+                                     wIndex: 0x0, dataOut: nil)
+    end
+    private :send_start
+
+    # Internal use only.
+    def wait_and_retrieve_by_serial(sn)
+      sleep REENUMERATION_DELAY
+      # The device should now reappear on the usb bus with the Google vendor id.
+      # We retrieve it by using its serial number.
+      device = @context.devices(idVendor: GOOGLE_VID).collect do |d|
+        d.serial_number == sn ? d : nil
+      end.compact.first
+
+      if device
+        # Retrieve new pointers (check if the old ones should be dereferenced)
+        @pDev = device.pDev
+        @pDevDesc = device.pDevDesc
+      else
+        logger.error ['Failed to retrieve the device after switching to ',
+                      'accessory mode. This may be due to a lack of proper ',
+                      'permissions ⇒ check your udev rules.', "\n",
+                      'The Google vendor id rule may look like:', "\n",
+                      'SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ',
+                      'MODE="0666", GROUP="plugdev"'
+                     ].join
+      end
+    end
+    private :wait_and_retrieve_by_serial
+
+  end
+
+end

data/lib/ligo/logging.rb

@@ -0,0 +1,54 @@
+# -*- coding: utf-8; fill-column: 80 -*-
+#
+# Copyright (c) 2012 Renaud AUBIN
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require 'logger'
+
+module Ligo
+
+  # Logging module.
+  #
+  # This module enables to share the same logger between all the Ligo classes.
+  module Logging
+
+    def logger
+      @logger ||= Logging.logger_for(self.class.name)
+    end
+
+    # Use a hash class-ivar to cache a unique Logger per class:
+    @loggers = {}
+    @out = STDOUT
+
+    class << self
+      def logger_for(classname)
+        @loggers[classname] ||= configure_logger_for(classname)
+      end
+
+      def configure_logger_for(classname)
+        logger = Logger.new(@out)
+        logger.progname = classname
+        logger
+      end
+
+      #
+      def configure_logger_output(logout)
+        @out = logout if logout != 'STDOUT'
+      end
+    end
+
+  end
+
+end

data/lib/ligo/version.rb

@@ -0,0 +1,21 @@
+# -*- coding: utf-8; fill-column: 80 -*-
+#
+# Copyright (c) 2012 Renaud AUBIN
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+module Ligo
+  # ligō version
+  VERSION = "0.1.0.beta"
+end

data/lib/ligo.rb

@@ -0,0 +1,38 @@
+# -*- coding: utf-8; fill-column: 80 -*-
+#
+# Copyright (c) 2012 Renaud AUBIN
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require 'logger'
+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://developer.android.com/guide/topics/connectivity/usb/accessory.html
+module Ligo
+  require 'ligo/logging'
+  require 'ligo/constants'
+  require 'ligo/accessory'
+  require 'ligo/context'
+  require 'ligo/device'
+end

data/ligo.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+
+require File.expand_path('../lib/ligo/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name          = 'ligo'
+  gem.version       = Ligo::VERSION
+  gem.authors       = ['Renaud Aubin']
+  gem.date          = Date.today
+  gem.summary       = %q{A ruby utility to create virtual accessories able to communicate with Android devices.}
+  gem.description   = %q{Ligo: virtual accessories for Android}
+  gem.license       = 'Apache License, Version 2.0'
+  gem.authors       = ['Renaud AUBIN']
+  gem.email         = 'root@renaud.io'
+  gem.homepage      = 'https://github.com/nibua-r/ligo#readme'
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ['lib']
+
+  gem.add_dependency 'libusb', '~> 0.2.2'
+
+  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 'pry', '~> 0.9.10'
+end

data/spec/ligo/accessory_spec.rb

@@ -0,0 +1,99 @@
+require 'spec_helper'
+
+describe Ligo::Accessory do
+  before(:all) do
+    @accessory = Ligo::Accessory.new
+  end
+
+  subject { @accessory }
+  it { should respond_to :manufacturer}
+  it { should respond_to :model}
+  it { should respond_to :description}
+  it { should respond_to :version}
+  it { should respond_to :uri}
+  it { should respond_to :serial}
+
+  describe '#new' do
+
+    context 'when called with nil' do
+      it 'should raise ArgumentError' do
+        expect { Ligo::Accessory.new(nil) }.to raise_error(ArgumentError)
+      end
+    end
+
+    context 'when called with an empty Hash' do
+      it 'should raise ArgumentError' do
+        expect { Ligo::Accessory.new(Hash.new) }.to raise_error(ArgumentError)
+      end
+    end
+
+    context 'when called with invalid data (> max length)' do
+      before(:all) do
+        @accessory_arg = {
+          manufacturer: 'a',
+          model:        'a',
+          description:  'a',
+          version:      'a',
+          uri:          'a',
+          serial:       (0...256).map{ ('a'..'z').to_a[rand(26)] }.join
+        }
+      end
+
+      it 'should raise ArgumentError' do
+        expect do
+          Ligo::Accessory.new(@accessory_arg)
+        end.to raise_error(ArgumentError,
+                           'serial must contain at most 255 bytes')
+      end
+    end
+
+    context 'when called with invalid data (wrong datatype)' do
+      before(:all) do
+        @accessory_arg = {
+          manufacturer: 0,
+          model:        'a',
+          description:  'a',
+          version:      'a',
+          uri:          'a',
+          serial:       'a'
+        }
+      end
+
+      it 'should raise ArgumentError' do
+        expect do
+          Ligo::Accessory.new(@accessory_arg)
+        end.to raise_error(ArgumentError,
+                           'manufacturer is not a String')
+      end
+    end
+
+    context 'when called with missing data' do
+      before(:all) do
+        @accessory_arg = {
+          manufacturer: 'a',
+          model:        'a',
+          description:  'a',
+          version:      'a',
+          serial:       'a'
+        }
+      end
+
+      it 'should raise ArgumentError' do
+        expect do
+          Ligo::Accessory.new(@accessory_arg)
+        end.to raise_error(ArgumentError,
+                           'Missing argument: uri')
+      end
+    end
+
+  end # describe #new
+
+  describe '#each' do
+    it 'must be implemented soon'
+  end # describe #each
+
+  describe '#keys' do
+    it 'must be implemented soon'
+  end # describe #keys
+
+end

data/spec/ligo/context_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+# Assumption: two devices are connected on the usb bus and not yet in accessory
+# mode. Those devices are a Galaxy Nexus running 4.2 AOSP and a HTC Flyer
+# running 3.2 (with UMS support).
+
+describe Ligo::Context do
+  it "should derive from LIBUSB::Context" do
+    subject.class.superclass.should be LIBUSB::Context
+  end
+
+  describe "#devices" do
+    it "should return an Array" do
+      subject.devices.class.should be Array
+    end
+    it "should return 2 devices" do
+      subject.devices.size.should equal 2
+    end
+  end
+
+end

data/spec/ligo/device_spec.rb

@@ -0,0 +1,45 @@
+require 'spec_helper'
+
+# Assumption: two devices are connected on the usb bus and not yet in accessory
+# mode. Those devices are a Galaxy Nexus running 4.2 AOSP and a HTC Flyer
+# running 3.2 (with UMS support).
+
+describe Ligo::Device do
+  before(:all) do
+    @default_accessory = Ligo::Accessory.new
+    ctx = Ligo::Context.new
+    @gnexus = ctx.devices(idVendor: 0x04e8).first
+    @flyer  = ctx.devices(idVendor: 0x0bb4).first
+  end
+
+  it 'should derive from LIBUSB::Device' do
+    Ligo::Device.superclass.should be LIBUSB::Device
+  end
+
+  context 'when passing the Galaxy Nexus to accessory mode' do
+    specify { @gnexus.should_not be_accessory_mode }
+    specify { @gnexus.idVendor.should  be 0x04e8 }
+    specify { @gnexus.idProduct.should be 0x6860 }
+    specify { @gnexus.should be_aoap }
+    specify { @gnexus.should_not be_uas }
+    specify { @gnexus.aoap_version.should be 2 }
+    # Now, the order matters!
+    specify { @gnexus.attach_accessory(@default_accessory).should be true }
+    specify { @gnexus.idVendor.should be 0x18d1 }
+    specify { Ligo::GOOGLE_PIDS.should include @gnexus.idProduct }
+  end
+
+  context 'when passing the Flyer to accessory mode' do
+    specify { @flyer.should_not be_accessory_mode }
+    specify { @flyer.idVendor.should  be 0x0bb4 }
+    specify { @flyer.idProduct.should be 0x0ca9 }
+    specify { @flyer.should be_aoap }
+    specify { @flyer.should be_uas }
+    specify { @flyer.aoap_version.should be 1 }
+    # Now, the order matters!
+    specify { @flyer.attach_accessory(@default_accessory).should be true }
+    specify { @flyer.idVendor.should be 0x18d1 }
+    specify { Ligo::GOOGLE_PIDS.should include @flyer.idProduct }
+  end
+
+end

data/spec/ligo_spec.rb

@@ -0,0 +1,7 @@
+require 'spec_helper'
+
+describe Ligo do
+  it "should have a VERSION constant" do
+    subject.const_get('VERSION').should_not be_empty
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+gem 'rspec', '~> 2.4'
+require 'rspec'
+require 'ligo'
+
+include Ligo
+Ligo::Logging.configure_logger_output('/tmp/ligo-spec.log')