sphero_pwn 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6b51f0b12bbd766e4ad620a00be1d1841b90fe72
+  data.tar.gz: c23728318daf4e7e42d756b195461c39f3cdd0be
+SHA512:
+  metadata.gz: 033e26a33d83a0e8a8ee49f38a43a69b75f975dbf81e2252055d1383aa5e96b275ebfb8ef1a49aa0d7d8961073eff0ec9d6f05e378528ac6f9cb492409cf0caf
+  data.tar.gz: 409bd796603489498346cab6f01caff53231c78a9e05d34a3302a0eb4f1b24208e7b1ef591da29791b56b4f6789f212cdd8ae83a53c6e1627317759b3906a242

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.2.3

data/Gemfile

@@ -0,0 +1,12 @@
+source 'https://rubygems.org'
+
+gem 'rubyserial', '>= 0.2.4'
+
+group :development do
+  gem 'bundler', '>= 1.3.5'
+  gem 'jeweler', '>= 2.0.1'
+  gem 'minitest', '>= 5.8.3'
+  gem 'mocha', '>= 1.1.0'
+  gem 'simplecov', '>= 0', platform: :mri
+  gem 'yard', '>= 0.8.7.6'
+end

data/Gemfile.lock

@@ -0,0 +1,76 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.4.0)
+    builder (3.2.2)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
+    docile (1.1.5)
+    faraday (0.9.2)
+      multipart-post (>= 1.2, < 3)
+    ffi (1.9.10)
+    git (1.2.9.1)
+    github_api (0.13.0)
+      addressable (~> 2.3)
+      descendants_tracker (~> 0.0.4)
+      faraday (~> 0.8, < 0.10)
+      hashie (>= 3.4)
+      multi_json (>= 1.7.5, < 2.0)
+      nokogiri (~> 1.6.6)
+      oauth2
+    hashie (3.4.3)
+    highline (1.7.8)
+    jeweler (2.0.1)
+      builder
+      bundler (>= 1.0)
+      git (>= 1.2.5)
+      github_api
+      highline (>= 1.6.15)
+      nokogiri (>= 1.5.10)
+      rake
+      rdoc
+    json (1.8.3)
+    jwt (1.5.2)
+    metaclass (0.0.4)
+    mini_portile2 (2.0.0)
+    minitest (5.8.3)
+    mocha (1.1.0)
+      metaclass (~> 0.0.1)
+    multi_json (1.11.2)
+    multi_xml (0.5.5)
+    multipart-post (2.0.0)
+    nokogiri (1.6.7)
+      mini_portile2 (~> 2.0.0.rc2)
+    oauth2 (1.0.0)
+      faraday (>= 0.8, < 0.10)
+      jwt (~> 1.0)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (~> 1.2)
+    rack (1.6.4)
+    rake (10.4.2)
+    rdoc (4.2.0)
+    rubyserial (0.2.4)
+      ffi (~> 1.9.3)
+    simplecov (0.11.1)
+      docile (~> 1.1.0)
+      json (~> 1.8)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    thread_safe (0.3.5)
+    yard (0.8.7.6)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (>= 1.3.5)
+  jeweler (>= 2.0.1)
+  minitest (>= 5.8.3)
+  mocha (>= 1.1.0)
+  rubyserial (>= 0.2.4)
+  simplecov
+  yard (>= 0.8.7.6)
+
+BUNDLED WITH
+   1.10.6

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2015 Victor Costan
+
+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.markdown

@@ -0,0 +1,25 @@
+# sphero_pwn
+
+Wrapper around the
+[Bluetooth RFCONN protocol](http://sdk.sphero.com/api-reference/api-packet-format/)
+used to talk to
+[Sphero robots](http://www.sphero.com/).
+
+## Contributing to sphero_pwn
+
+* Check out the latest master to make sure the feature hasn't been implemented
+  or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it
+  and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to
+  have your own version, or is otherwise necessary, that is fine, but please
+  isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2015 Victor Costan. See LICENSE.txt for further details.

data/Rakefile

@@ -0,0 +1,39 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://guides.rubygems.org/specification-reference/ for more options
+  gem.name = "sphero_pwn"
+  gem.homepage = "http://github.com/pwnall/sphero_pwn"
+  gem.license = "MIT"
+  gem.summary = %Q{Wrapper for Sphero's bluetooth protocol}
+  gem.description = %Q{This library is currently focused on reverse-engineering
+      the undocumented parts of Sphero}
+  gem.email = "victor@costan.us"
+  gem.authors = ["Victor Costan"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/VERSION

@@ -0,0 +1 @@
+0.0.0

data/lib/sphero_pwn.rb

@@ -0,0 +1,20 @@
+# Namespace.
+module SpheroPwn
+end
+
+require 'sphero_pwn/async.rb'
+require 'sphero_pwn/asyncs.rb'
+require 'sphero_pwn/channel.rb'
+require 'sphero_pwn/channel_recorder.rb'
+require 'sphero_pwn/command.rb'
+require 'sphero_pwn/commands.rb'
+require 'sphero_pwn/replay_channel.rb'
+require 'sphero_pwn/response.rb'
+require 'sphero_pwn/session.rb'
+require 'sphero_pwn/test_channel.rb'
+
+require 'sphero_pwn/asyncs/l1_diagnostics.rb'
+
+require 'sphero_pwn/commands/get_versions.rb'
+require 'sphero_pwn/commands/l1_diagnostics.rb'
+require 'sphero_pwn/commands/ping.rb'

data/lib/sphero_pwn/async.rb

@@ -0,0 +1,10 @@
+# Superclass for all asynchronous messages sent from the robot to the computer.
+class SpheroPwn::Async
+  # @return {Array<Number>} the payload
+  attr_reader :data_bytes
+
+
+  def initialize(data_bytes)
+    @data_bytes = data_bytes
+  end
+end

data/lib/sphero_pwn/asyncs.rb

@@ -0,0 +1,34 @@
+# Namespace for asynchronous messages sent from the robot to the computer.
+module SpheroPwn::Asyncs
+  # Called by SpheroPwn::Async subclasses to register themselves.
+  #
+  # @param {Class<SpheroPwn::Async>} klass a class that parses asynchronous
+  #   messages with an ID code
+  def self.register(klass)
+    id_code = klass.id_code
+    if other_klass = CLASSES[id_code]
+      raise ArgumentError,
+          "Async ID code #{id_code} already registered by #{other_klass}"
+    end
+    CLASSES[id_code] = klass
+  end
+
+  # Subclasses override this and return the ID of the commands they can parse.
+  #
+  # @return {Number} the ID byte value identifying the commands that can be
+  #   parsed by this class
+  def self.id_code
+    raise RuntimeError, 'id_code must be implemented by subclasses'
+  end
+
+  # @param {Number} class_id the asynchronous message's ID code
+  # @return {Class<SpheroPwn::Async>} the class that can parse
+  def self.create(class_id, data_bytes)
+    return nil unless klass = CLASSES[class_id]
+    klass.new data_bytes
+  end
+
+
+  # Maps ID codes to classes handling responses.
+  CLASSES = {}
+end

data/lib/sphero_pwn/asyncs/l1_diagnostics.rb

@@ -0,0 +1,21 @@
+# The result of an L1 diagnostic request.
+#
+# This is an asynchronous message because it's too long to fit into the command
+# response structure.
+class SpheroPwn::Asyncs::L1Diagnostics < SpheroPwn::Async
+  # @return {String} the text form of the diagnostics
+  attr_reader :text
+
+  def initialize(data_bytes)
+    super
+
+    @text = data_bytes.pack('C*').encode! Encoding::UTF_8
+  end
+
+
+  def self.id_code
+    0x02
+  end
+end
+
+SpheroPwn::Asyncs.register SpheroPwn::Asyncs::L1Diagnostics

data/lib/sphero_pwn/channel.rb

@@ -0,0 +1,65 @@
+require 'rubyserial'
+require 'thread'
+
+# Communication channel with a robot.
+#
+# This is a light abstraction over the Bluetooth serial port (RFCONN) used to
+# talk to a robot.
+class SpheroPwn::Channel
+  # Opens up a communication channel with a robot.
+  #
+  # @param {String} rfconn_path the path to the device file connecting to the
+  #   robot's Bluetooth RFCONN service
+  def initialize(rfconn_path)
+    give_up_at = Time.now + 15
+    @port = nil
+    while @port.nil?
+      begin
+        @port = Serial.new rfconn_path, 115200
+      rescue RubySerial::Exception => e
+        raise e unless e.message == 'EBUSY'
+        raise e if Time.now >= give_up_at
+      end
+    end
+
+    @send_queue = Queue.new
+    @send_thread = Thread.new @send_queue do
+      send_queue = @send_queue
+
+      loop do
+        bytes = send_queue.pop
+        break if bytes == :close
+
+        @port.write bytes
+      end
+    end
+  end
+
+  # @param {String} bytes a binary-encoded string of bytes to be sent to the
+  #   robot over the RFCONN port
+  # @return {Channel} self
+  def send_bytes(bytes)
+    @send_queue.push bytes
+    self
+  end
+
+  # @param {Integer} count the number of bytes to be read from the RFCONN port
+  def recv_bytes(count)
+    retries_left = 100_000
+    while retries_left > 0
+      bytes = @port.read count
+      return bytes unless bytes.empty?
+      retries_left -= 1
+    end
+    nil
+  end
+
+  # Gracefully shuts down the communication channel with the robot.
+  #
+  # @return {Channel} self
+  def close
+    @send_queue.push :close
+    @port.close
+    self
+  end
+end

data/lib/sphero_pwn/channel_recorder.rb

@@ -0,0 +1,60 @@
+# Records all the bytes going to a channel.
+class SpheroPwn::ChannelRecorder
+  # @param {Channel} the channel being recorded
+  # @param {String} recording_path the file where the recording will be saved
+  def initialize(channel, recording_path)
+    @channel = channel
+    @file = File.open recording_path, 'wt'
+
+    @is_receiving = false
+  end
+
+  # @see {Channel#recv_bytes}
+  def recv_bytes(count)
+    bytes = @channel.recv_bytes count
+    return bytes if bytes.nil?
+
+    unless @is_receiving
+      @file.write '<'
+      @is_receiving = true
+    end
+    log_bytes bytes
+    @file.flush
+
+    bytes
+  end
+
+  # @see {Channel#send_bytes}
+  def send_bytes(bytes)
+    if @is_receiving
+      @file.write "\n"
+      @is_receiving = false
+    end
+
+    @file.write '>'
+    log_bytes bytes
+    @file.write "\n"
+    @file.flush
+
+    @channel.send_bytes bytes
+    self
+  end
+
+  # @see {Channel#close}
+  def close
+    if @is_receiving
+      @file.write "\n"
+    end
+    @file.close
+    @channel.close
+    self
+  end
+
+  # @param {String} bytes the bytes to be written to the output file
+  def log_bytes(bytes)
+    unless bytes.empty?
+      @file.write bytes.unpack('C*').map { |byte| ' %02X' % byte }.join('')
+    end
+  end
+  private :log_bytes
+end

data/lib/sphero_pwn/command.rb

@@ -0,0 +1,54 @@
+# Superclass for the command messages going from the computer to the robot.
+class SpheroPwn::Command
+  # @param {Number} device_id the virtual device ID for the command
+  # @param {Number} command_id the command number; unique within a virtual
+  #   device ID
+  # @param {String} data_bytes extra data in the command; can be nil if no
+  #   extra data will be transmitted
+  def initialize(device_id, command_id, data)
+    @device_id = device_id
+    @command_id = command_id
+    @data = data
+    @sop2 = 0xFF
+  end
+
+  # Clears the command bit that asks for a response.
+  def no_response!
+    @sop2 &= 0xFE
+    self
+  end
+
+  # Clears the command bit that resets the client inactivity timeout.
+  def no_timeout_reset!
+    @sop2 &= 0xFD
+    self
+  end
+
+  # @return {Boolean} true if the command will receive a response
+  def expects_response?
+    (@sop2 & 0x01) != 0
+  end
+
+  # @param {Number} the sequence number to be embedded in the command
+  def to_bytes(sequence)
+    data_length = @data.nil? ? 1 : 1 + @data.length
+    data_length = 0xFF if data_length > 0xFF
+    bytes = [0xFF, @sop2, @device_id, @command_id, sequence, data_length]
+    bytes.concat @data unless @data.nil?
+
+    sum = 0
+    bytes.each { |byte| sum = (sum + byte) }
+    bytes.push(((sum - 0xFF - @sop2) & 0xFF) ^ 0xFF)
+    bytes.pack('C*')
+  end
+
+  # The class used to parse the response for this command.
+  #
+  # Subclasses should override this method.
+  #
+  # @return {Class<SpheroPwn::Response>} the class that will be instantiated
+  #   when this command's response is received
+  def response_class
+    SpheroPwn::Response
+  end
+end