sphero_pwn 0.0.0 → 0.0.1

data/lib/sphero_pwn/commands/boot_main_app.rb

@@ -0,0 +1,17 @@
+# Asks the robot's bootloader to boot the main application.
+#
+# This command is only valid when the robot is executing the bootloader.
+class SpheroPwn::Commands::BootMainApp < SpheroPwn::Command
+  def initialize
+    super 0x01, 0x04, nil
+  end
+
+  # @see {SpheroPwn::Command#response_class}
+  def response_class
+    SpheroPwn::Commands::BootMainApp::Response
+  end
+end
+
+# The response to a boot main application command.
+class SpheroPwn::Commands::BootMainApp::Response < SpheroPwn::Response
+end

data/lib/sphero_pwn/commands/enter_bootloader.rb

@@ -0,0 +1,15 @@
+# Asks the robot to jump into its bootloader.
+class SpheroPwn::Commands::EnterBootloader < SpheroPwn::Command
+  def initialize
+    super 0x00, 0x30, nil
+  end
+
+  # @see {SpheroPwn::Command#response_class}
+  def response_class
+    SpheroPwn::Commands::EnterBootloader::Response
+  end
+end
+
+# The response to an enter bootloader command.
+class SpheroPwn::Commands::EnterBootloader::Response < SpheroPwn::Response
+end

data/lib/sphero_pwn/commands/get_device_mode.rb

@@ -0,0 +1,35 @@
+# Asks the robot about the versions of its software stack components.
+class SpheroPwn::Commands::GetDeviceMode < SpheroPwn::Command
+  def initialize
+    super 0x02, 0x44, nil
+  end
+
+  # @see {SpheroPwn::Command#response_class}
+  def response_class
+    SpheroPwn::Commands::GetDeviceMode::Response
+  end
+end
+
+# The development mode of the robot.
+class SpheroPwn::Commands::GetDeviceMode::Response < SpheroPwn::Response
+  # @return {Symbol} the device's mode; can be :normal or :user_hack
+  attr_reader :mode
+
+  # @see {SpheroPwn::Response#initialize}
+  def initialize(code_byte, sequence_byte, data_bytes)
+    super
+
+    if code == :ok
+      @mode = case data_bytes[0]
+      when 0x00
+        :normal
+      when 0x01
+        :user_hack
+      else
+        :unknown
+      end
+    else
+      @mode = :error
+    end
+  end
+end

data/lib/sphero_pwn/commands/get_flash_block.rb

@@ -0,0 +1,34 @@
+# Asks the robot to send a configuration block from the flash memory.
+class SpheroPwn::Commands::GetFlashBlock < SpheroPwn::Command
+  # @param {Symbol} block_type :soul, :factory_config or :user_config
+  def initialize(block_type)
+    case block_type
+    when :soul
+      command_id = 0x46
+      data_bytes = nil
+    when :factory_config
+      command_id = 0x40
+      data_bytes = [0x00]
+    when :user_config
+      command_id = 0x40
+      data_bytes = [0x01]
+    when /^block_/
+      command_id = 0x40
+      data_bytes = block_type.to_s.split('_')[1..-1].
+                              map { |char| char.to_i(16) }
+    else
+      raise ArgumentError, "Unimplemented block type #{block_type.inspect}"
+    end
+
+    super 0x02, command_id, data_bytes
+  end
+
+  # @see {SpheroPwn::Command#response_class}
+  def response_class
+    SpheroPwn::Commands::GetFlashBlock::Response
+  end
+end
+
+# The response to a get flash block command.
+class SpheroPwn::Commands::GetFlashBlock::Response < SpheroPwn::Response
+end

data/lib/sphero_pwn/commands/get_permanent_flags.rb

@@ -0,0 +1,44 @@
+# Obtains the robot's configuration flags that persist across power cycles.
+class SpheroPwn::Commands::GetPermanentFlags < SpheroPwn::Command
+  def initialize
+    super 0x02, 0x36, nil
+  end
+
+  # @see {SpheroPwn::Command#response_class}
+  def response_class
+    SpheroPwn::Commands::GetPermanentFlags::Response
+  end
+
+  # @return {Hash<Number, Symbol>} symbolic values for the returned flags
+  FLAGS = {
+    0x01 => :no_sleep_while_charging,
+    0x02 => :vector_drive,
+    0x04 => :no_leveling_while_charging,
+    0x08 => :tail_led_always_on,
+    0x10 => :motion_timeouts,
+    0x20 => :demo_mode,
+    0x40 => :light_double_tap,
+    0x80 => :heavy_double_tap,
+    0x100 => :gyro_max_async,
+  }.freeze
+end
+
+# The robot's configuration flags that persist across power cycles.
+class SpheroPwn::Commands::GetPermanentFlags::Response < SpheroPwn::Response
+  # @return {Hash<Symbol, Boolean>} maps developer-friendly flag names to
+  #   whether the corresponding bits were set in the flags field
+  attr_reader :flags
+
+  # @see {SpheroPwn::Response#initialize}
+  def initialize(code_byte, sequence_byte, data_bytes)
+    super
+
+    @flags = {}
+    if code == :ok
+      flags_number = data_bytes[0, 4].pack('C*').unpack('N').first
+      SpheroPwn::Commands::GetPermanentFlags::FLAGS.each do |mask, name|
+        @flags[name] = (flags_number & mask) != 0
+      end
+    end
+  end
+end

data/lib/sphero_pwn/commands/get_versions.rb

@@ -21,16 +21,18 @@ class SpheroPwn::Commands::GetVersions::Response < SpheroPwn::Response
     super
 
     @versions = {}
-    response_version = data_bytes[0]
-    if response_version >= 1
-      @versions.merge!  model: data_bytes[1], hardware: data_bytes[2],
-        sphero_app: { version: data_bytes[3], revision: data_bytes[4] },
-        bootloader: self.class.parse_packed_nibble(data_bytes[5]),
-        basic: self.class.parse_packed_nibble(data_bytes[6]),
-        macros: self.class.parse_packed_nibble(data_bytes[7])
-    end
-    if response_version >= 2
-      @versions.merge!  api: { major: data_bytes[8], minor: data_bytes[9] }
+    if code == :ok
+      response_version = data_bytes[0]
+      if response_version >= 1
+        @versions.merge!  model: data_bytes[1], hardware: data_bytes[2],
+          sphero_app: { version: data_bytes[3], revision: data_bytes[4] },
+          bootloader: self.class.parse_packed_nibble(data_bytes[5]),
+          basic: self.class.parse_packed_nibble(data_bytes[6]),
+          macros: self.class.parse_packed_nibble(data_bytes[7])
+      end
+      if response_version >= 2
+        @versions.merge!  api: { major: data_bytes[8], minor: data_bytes[9] }
+      end
     end
   end
 

data/lib/sphero_pwn/commands/is_page_blank.rb

@@ -0,0 +1,36 @@
+# Asks the robot's bootloader if a flash page is blank.
+#
+# This command is only valid when the robot is executing the bootloader.
+class SpheroPwn::Commands::IsPageBlank < SpheroPwn::Command
+  # @param {Number} page_number the flash page that the command will ask the
+  #   robot to look at
+  def initialize(page_number)
+    if page_number > 255
+      raise ArgumentError, "Page number #{page_number} exceeds 255"
+    end
+    super 0x01, 0x05, [page_number]
+  end
+
+  # @see {SpheroPwn::Command#response_class}
+  def response_class
+    SpheroPwn::Commands::IsPageBlank::Response
+  end
+end
+
+# The response to a boot main application command.
+class SpheroPwn::Commands::IsPageBlank::Response < SpheroPwn::Response
+  # @return {Boolean} true if the flash memory page is blank
+  attr_reader :is_blank
+  alias_method :is_blank?, :is_blank
+
+  # @see {SpheroPwn::Response#initialize}
+  def initialize(code_byte, sequence_byte, data_bytes)
+    super
+
+    if code == :ok
+      @is_blank = data_bytes[0] > 0
+    else
+      @is_blank = nil
+    end
+  end
+end

data/lib/sphero_pwn/commands/l1_diagnostics.rb

@@ -13,4 +13,3 @@ end
 # The response to an L1 diagnostics command.
 class SpheroPwn::Commands::L1Diagnostics::Response < SpheroPwn::Response
 end
-

data/lib/sphero_pwn/commands/l2_diagnostics.rb

@@ -0,0 +1,50 @@
+# Asks the robot for its debugging counters.
+#
+# This command only works when the robot is in user hacking mode.
+class SpheroPwn::Commands::L2Diagnostics < SpheroPwn::Command
+  def initialize
+    super 0x00, 0x41, nil
+  end
+
+  # @see {SpheroPwn::Command#response_class}
+  def response_class
+    SpheroPwn::Commands::L2Diagnostics::Response
+  end
+end
+
+# The response to an L2 diagnostics command.
+class SpheroPwn::Commands::L2Diagnostics::Response < SpheroPwn::Response
+  # @return {Hash<Symbol, Number>} debugging information counters
+  attr_reader :counters
+
+  # @see {SpheroPwn::Response#initialize}
+  def initialize(code_byte, sequence_byte, data_bytes)
+    super
+
+    @counters = {}
+    if code == :ok
+      data_string = data_bytes.pack('C*')
+      response_version = data_bytes[0x02]
+      if response_version >= 1
+        @counters.merge! received_good: data_string[0x03, 4].unpack('N'),
+          reserved1: data_bytes[0x02],
+          bad_device_id: data_string[0x07, 4].unpack('N'),
+          bad_data_length: data_string[0x0B, 4].unpack('N'),
+          bad_command_id: data_string[0x0F, 4].unpack('N'),
+          bad_checksum: data_string[0x13, 4].unpack('N'),
+          rx_buffer_overrun: data_string[0x17, 4].unpack('N'),
+          transmitted: data_string[0x1B, 4].unpack('N'),
+          tx_buffer_overrun: data_string[0x1F, 4].unpack('N'),
+          last_boot_reason: data_bytes[0x23],
+          boots_by_reason: data_string[0x24, 32].unpack('n*'),
+          reserved2: data_string[0x44, 2].unpack('n'),
+          charge_count: data_string[0x46, 2].unpack('n'),
+          seconds_since_charge: data_string[0x48, 2].unpack('n'),
+          seconds_on: data_string[0x4A, 4].unpack('N'),
+          distance_rolled: data_string[0x4E, 4].unpack('N'),
+          i2c_failures: data_string[0x52, 2].unpack('n'),
+          gyro_adjusts: data_string[0x54, 4].unpack('N')
+      end
+    end
+  end
+end

data/lib/sphero_pwn/commands/set_device_mode.rb

@@ -0,0 +1,25 @@
+# Asks the robot about the versions of its software stack components.
+class SpheroPwn::Commands::SetDeviceMode < SpheroPwn::Command
+  def initialize(mode)
+
+    mode_byte = case mode
+    when :normal
+      0x00
+    when :user_hack
+      0x01
+    else
+      raise ArgumentError, "Unimplemented mode #{mode.inspect}"
+    end
+
+    super 0x02, 0x42, [mode_byte]
+  end
+
+  # @see {SpheroPwn::Command#response_class}
+  def response_class
+    SpheroPwn::Commands::SetDeviceMode::Response
+  end
+end
+
+# The versions of a robot's software stack.
+class SpheroPwn::Commands::SetDeviceMode::Response < SpheroPwn::Response
+end

data/lib/sphero_pwn/commands/set_permanent_flags.rb

@@ -0,0 +1,29 @@
+# Sets the robot's configuration flags that persist across power cycles.
+class SpheroPwn::Commands::SetPermanentFlags < SpheroPwn::Command
+  # @param {Hash<Symbol, Boolean>} maps developer-friendly flag names to
+  #   whether the corresponding bits will be set in the flags field
+  def initialize(new_flags)
+    flags_number = 0
+    new_flags.each do |name, value|
+      mask = SpheroPwn::Commands::SetPermanentFlags::FLAGS[name]
+      if mask.nil?
+        raise ArgumentError, "Unknown flag #{name.inspect}"
+      end
+      flags_number |= mask if value
+    end
+
+    super 0x02, 0x35, [flags_number].pack('N').unpack('C*')
+  end
+
+  # @see {SpheroPwn::Command#response_class}
+  def response_class
+    SpheroPwn::Commands::SetPermanentFlags::Response
+  end
+
+  # @return {Hash<Symbol, Number>} numbers for the symbolic values
+  FLAGS = SpheroPwn::Commands::GetPermanentFlags::FLAGS.invert.freeze
+end
+
+# The robot's configuration flags that persist across power cycles.
+class SpheroPwn::Commands::SetPermanentFlags::Response < SpheroPwn::Response
+end

data/lib/sphero_pwn/session.rb

@@ -65,14 +65,18 @@ class SpheroPwn::Session
   # @return {Response, Async} the response read from the channel; can be nil if
   #   no message was received or if the checksum verification failed
   def recv_message
-    return nil if @channel.recv_bytes(1).ord != 0xFF
+    start_of_packet = @channel.recv_bytes 1
+    return nil if start_of_packet.empty? || start_of_packet.ord != 0xFF
 
     packet_type = @channel.recv_bytes 1
+    return nil if packet_type.empty?
     case packet_type.ord
     when 0xFF
       read_response
     when 0xFE
       read_async_message
+    else
+      nil
     end
   end
 
@@ -103,12 +107,14 @@ class SpheroPwn::Session
   def read_response
     header_bytes = @channel.recv_bytes(3).unpack('C*')
     response_code, sequence, data_length = *header_bytes
+    return nil unless data_length
 
     # It may seem that it'd be better to look up the sequence number and bail
     # early if we don't find it. However, in order to avoid misleading error
     # messages, we don't want to touch anything in the message until we know
     # that the checksum is valid.
-    data_bytes = @channel.recv_bytes(data_length).unpack('C*')
+    return nil unless data = @channel.recv_bytes(data_length)
+    data_bytes = data.unpack 'C*'
     checksum = data_bytes.pop
     unless self.class.valid_checksum?(header_bytes, data_bytes, checksum)
       return nil
@@ -130,13 +136,15 @@ class SpheroPwn::Session
   def read_async_message
     header_bytes = @channel.recv_bytes(3).unpack('C*')
     class_id, length_msb, length_lsb  = *header_bytes
-    data_length = (length_msb << 8) | length_lsb
+    return nil unless length_msb && length_lsb
 
     # It may seem that it'd be better to look up the sequence number and bail
     # early if we don't find it. However, in order to avoid misleading error
     # messages, we don't want to touch anything in the message until we know
     # that the checksum is valid.
-    data_bytes = @channel.recv_bytes(data_length).unpack('C*')
+    data_length = (length_msb << 8) | length_lsb
+    return nil unless data = @channel.recv_bytes(data_length)
+    data_bytes = data.unpack 'C*'
     checksum = data_bytes.pop
     unless self.class.valid_checksum?(header_bytes, data_bytes, checksum)
       return nil

data/sphero_pwn.gemspec

@@ -0,0 +1,130 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+# stub: sphero_pwn 0.0.1 ruby lib
+
+Gem::Specification.new do |s|
+  s.name = "sphero_pwn"
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.require_paths = ["lib"]
+  s.authors = ["Victor Costan"]
+  s.date = "2015-12-15"
+  s.description = "This library is currently focused on reverse-engineering\n      the undocumented parts of Sphero"
+  s.email = "victor@costan.us"
+  s.executables = ["sphero_diagnostics.rb", "sphero_map_flash.rb", "sphero_save_flash_block.rb", "sphero_set_flag.rb", "sphero_soft_reboot.rb", "sphero_toggle_user_hack.rb"]
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.markdown"
+  ]
+  s.files = [
+    ".document",
+    ".travis.yml",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.markdown",
+    "Rakefile",
+    "VERSION",
+    "bin/sphero_diagnostics.rb",
+    "bin/sphero_map_flash.rb",
+    "bin/sphero_save_flash_block.rb",
+    "bin/sphero_set_flag.rb",
+    "bin/sphero_soft_reboot.rb",
+    "bin/sphero_toggle_user_hack.rb",
+    "lib/sphero_pwn.rb",
+    "lib/sphero_pwn/async.rb",
+    "lib/sphero_pwn/asyncs.rb",
+    "lib/sphero_pwn/asyncs/flash_block.rb",
+    "lib/sphero_pwn/asyncs/l1_diagnostics.rb",
+    "lib/sphero_pwn/channel.rb",
+    "lib/sphero_pwn/channel_recorder.rb",
+    "lib/sphero_pwn/command.rb",
+    "lib/sphero_pwn/commands.rb",
+    "lib/sphero_pwn/commands/boot_main_app.rb",
+    "lib/sphero_pwn/commands/enter_bootloader.rb",
+    "lib/sphero_pwn/commands/get_device_mode.rb",
+    "lib/sphero_pwn/commands/get_flash_block.rb",
+    "lib/sphero_pwn/commands/get_permanent_flags.rb",
+    "lib/sphero_pwn/commands/get_versions.rb",
+    "lib/sphero_pwn/commands/is_page_blank.rb",
+    "lib/sphero_pwn/commands/l1_diagnostics.rb",
+    "lib/sphero_pwn/commands/l2_diagnostics.rb",
+    "lib/sphero_pwn/commands/ping.rb",
+    "lib/sphero_pwn/commands/set_device_mode.rb",
+    "lib/sphero_pwn/commands/set_permanent_flags.rb",
+    "lib/sphero_pwn/replay_channel.rb",
+    "lib/sphero_pwn/response.rb",
+    "lib/sphero_pwn/session.rb",
+    "lib/sphero_pwn/test_channel.rb",
+    "sphero_pwn.gemspec",
+    "test/channel_recorder_test.rb",
+    "test/command_test.rb",
+    "test/commands/boot_main_app_test.rb",
+    "test/commands/enter_bootloader_test.rb",
+    "test/commands/get_device_mode_test.rb",
+    "test/commands/get_flash_block_test.rb",
+    "test/commands/get_permanent_flags_test.rb",
+    "test/commands/get_versions_test.rb",
+    "test/commands/is_page_blank_test.rb",
+    "test/commands/l1_diagnostics_test.rb",
+    "test/commands/l2_diagnostics_test.rb",
+    "test/commands/ping_test.rb",
+    "test/commands/set_device_mode_test.rb",
+    "test/commands/set_permanent_flags_test.rb",
+    "test/data/enter_bootloader.txt",
+    "test/data/get_device_mode.txt",
+    "test/data/get_factory_config.txt",
+    "test/data/get_permanent_flags.txt",
+    "test/data/get_soul.txt",
+    "test/data/get_version.txt",
+    "test/data/is_page_blank.txt",
+    "test/data/l1_diagnostics.txt",
+    "test/data/l2_diagnostics.txt",
+    "test/data/ping.txt",
+    "test/data/set_device_mode.txt",
+    "test/data/set_permanent_flags.txt",
+    "test/helper.rb",
+    "test/replay_channel_test.rb",
+    "test/response_test.rb",
+    "test/session_test.rb",
+    "test/sphero_pwn_test.rb"
+  ]
+  s.homepage = "http://github.com/pwnall/sphero_pwn"
+  s.licenses = ["MIT"]
+  s.rubygems_version = "2.4.5.1"
+  s.summary = "Wrapper for Sphero's bluetooth protocol"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 4
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rubyserial>, [">= 0.2.4"])
+      s.add_development_dependency(%q<bundler>, [">= 1.3.5"])
+      s.add_development_dependency(%q<jeweler>, [">= 2.0.1"])
+      s.add_development_dependency(%q<minitest>, [">= 5.8.3"])
+      s.add_development_dependency(%q<mocha>, [">= 1.1.0"])
+      s.add_development_dependency(%q<simplecov>, [">= 0"])
+      s.add_development_dependency(%q<yard>, [">= 0.8.7.6"])
+    else
+      s.add_dependency(%q<rubyserial>, [">= 0.2.4"])
+      s.add_dependency(%q<bundler>, [">= 1.3.5"])
+      s.add_dependency(%q<jeweler>, [">= 2.0.1"])
+      s.add_dependency(%q<minitest>, [">= 5.8.3"])
+      s.add_dependency(%q<mocha>, [">= 1.1.0"])
+      s.add_dependency(%q<simplecov>, [">= 0"])
+      s.add_dependency(%q<yard>, [">= 0.8.7.6"])
+    end
+  else
+    s.add_dependency(%q<rubyserial>, [">= 0.2.4"])
+    s.add_dependency(%q<bundler>, [">= 1.3.5"])
+    s.add_dependency(%q<jeweler>, [">= 2.0.1"])
+    s.add_dependency(%q<minitest>, [">= 5.8.3"])
+    s.add_dependency(%q<mocha>, [">= 1.1.0"])
+    s.add_dependency(%q<simplecov>, [">= 0"])
+    s.add_dependency(%q<yard>, [">= 0.8.7.6"])
+  end
+end
+