sphero_pwn 0.0.0

data/lib/sphero_pwn/commands.rb

@@ -0,0 +1,3 @@
+# Namespace for all the commands.
+module SpheroPwn::Commands
+end

data/lib/sphero_pwn/commands/get_versions.rb

@@ -0,0 +1,44 @@
+# Asks the robot about the versions of its software stack components.
+class SpheroPwn::Commands::GetVersions < SpheroPwn::Command
+  def initialize
+    super 0x00, 0x02, nil
+  end
+
+  # @see {SpheroPwn::Command#response_class}
+  def response_class
+    SpheroPwn::Commands::GetVersions::Response
+  end
+end
+
+# The versions of a robot's software stack.
+class SpheroPwn::Commands::GetVersions::Response < SpheroPwn::Response
+  # @return {Hash<Symbol, Number>} the software versions of the components in
+  #   the robot's software stack
+  attr_reader :versions
+
+  # @see {SpheroPwn::Response#initialize}
+  def initialize(code_byte, sequence_byte, data_bytes)
+    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] }
+    end
+  end
+
+  # Decodes a version from packed nibble format.
+  #
+  # @param {Number} byte the byte value packing the version
+  # @return {Hash<Symbol, Number>} maps :major and :minor to version numbers
+  def self.parse_packed_nibble(byte)
+    { major: (byte >> 4), minor: (byte & 0x0F) }
+  end
+end

data/lib/sphero_pwn/commands/l1_diagnostics.rb

@@ -0,0 +1,16 @@
+# Asks the robot to send ASCII diagnostic data.
+class SpheroPwn::Commands::L1Diagnostics < SpheroPwn::Command
+  def initialize
+    super 0x00, 0x40, nil
+  end
+
+  # @see {SpheroPwn::Command#response_class}
+  def response_class
+    SpheroPwn::Commands::L1Diagnostics::Response
+  end
+end
+
+# The response to an L1 diagnostics command.
+class SpheroPwn::Commands::L1Diagnostics::Response < SpheroPwn::Response
+end
+

data/lib/sphero_pwn/commands/ping.rb

@@ -0,0 +1,15 @@
+# Asks the robot to echo this message.
+class SpheroPwn::Commands::Ping < SpheroPwn::Command
+  def initialize
+    super 0x00, 0x01, nil
+  end
+
+  # @see {SpheroPwn::Command#response_class}
+  def response_class
+    SpheroPwn::Commands::Ping::Response
+  end
+end
+
+# The response to an echo command.
+class SpheroPwn::Commands::Ping::Response < SpheroPwn::Response
+end

data/lib/sphero_pwn/replay_channel.rb

@@ -0,0 +1,81 @@
+# Implements the Channel API using data from a file.
+class SpheroPwn::ReplayChannel
+  #
+  #
+  # @param {String} recording_path the file storing the recording
+  def initialize(recording_path)
+    @file = File.open recording_path, 'rt'
+    @lines = @file.read.split("\n").map do |line|
+      tokens = line.split ' '
+
+      tokens.map! do |token|
+        case token
+        when '<'
+          :recv
+        when '>'
+          :send
+        else
+          token.to_i 16
+        end
+      end
+    end
+
+    @line_index = 0
+    @byte_index = 0
+  end
+
+  # @see {Channel#recv_bytes}
+  def recv_bytes(count)
+    if @lines[@line_index].nil? || @lines[@line_index].first != :recv
+      raise RuntimeError, "Received data at an unexpected time!"
+    end
+
+    line_bytes = @lines[@line_index].length - 1
+    if @byte_index + count > line_bytes
+      raise ArgumentError, "Attempted to receive #{count} bytes, but only " +
+          "#{line_bytes - @byte_index} are available"
+    end
+
+    data = @lines[@line_index][@byte_index + 1, count].pack('C*')
+    @byte_index += count
+
+    if @byte_index == line_bytes
+      @byte_index = 0
+      @line_index += 1
+    end
+
+    data
+  end
+
+  # @see {Channel#send_bytes}
+  def send_bytes(bytes)
+    if @lines[@line_index] && @lines[@line_index].first == :recv
+      line_bytes = @lines[@line_index].length - 1
+      raise RuntimeError, "Sent data before receiving " +
+          "#{line_bytes - @byte_index} of #{line_bytes} bytes!"
+    end
+
+    if @lines[@line_index].nil? || @lines[@line_index].first != :send
+      raise RuntimeError, "Sent data at an unexpected time!"
+    end
+
+    expected = @lines[@line_index][1..-1]
+    data = bytes.unpack 'C*'
+    if data != expected
+      raise ArgumentError, "Incorrect bytes sent! " +
+          "Expected: #{expected.inspect} Got: #{data.inspect}"
+    end
+    @line_index += 1
+    self
+  end
+
+  # @see {Channel#close}
+  def close
+    if @line_index != @lines.length
+      ops_left = @lines.length - @line_index
+      raise RuntimeError, "Closed before performing #{ops_left} operations!"
+    end
+
+    self
+  end
+end

data/lib/sphero_pwn/response.rb

@@ -0,0 +1,47 @@
+# Superclass for all messages sent from the robot in response to commands.
+class SpheroPwn::Response
+  # @return {Symbol} the command's response
+  attr_reader :code
+
+  # @return {Number} the sequence number matching the response to its command
+  attr_reader :sequence
+
+  # @return {Array<Number>} the additional payload bytes in the response; this
+  #   array is frozen
+  attr_reader :data_bytes
+
+  # Parses a response to a command.
+  #
+  # @param {Number} code_byte the response code number
+  # @param {Number} sequence_byte the sequence number matching the response to
+  #   its command
+  # @param {Array<Number>} data_bytes the additional response payload; can be
+  #   empty, cannot be nil; the constructor takes ownership of the array and
+  #   freezes it
+  def initialize(code_byte, sequence_byte, data_bytes)
+    @code = RESPONSE_CODES[code_byte] || :unknown
+    @sequence = sequence_byte
+    @data_bytes = data_bytes.freeze
+  end
+
+  # @return {Hash<Integer, Symbol>} maps error codes to symbols
+  RESPONSE_CODES = {
+    0x00 => :ok,  # Command succeeded.
+    0x01 => :generic_error,  # General, non-specific error.
+    0x02 => :bad_checksum,  # Received checksum failure.
+    0x03 => :got_fragment,  # Received command fragment.
+    0x04 => :bad_command,  # Unknown command ID.
+    0x05 => :unsupported,  # Command currently unsupported.
+    0x06 => :bad_message,  # Bad message format.
+    0x07 => :invalid_param,  # Parameter value(s) invalid.
+    0x08 => :exec_failure,  # Failed to execute command.
+    0x09 => :bad_device,  # Unknown Device ID.
+    0x0A => :ram_busy,  # Generic RAM access needed but it is busy.
+    0x0B => :bad_password,  # Supplied password incorrect.
+    0x31 => :low_battery,  # Voltage too low for reflash operation.
+    0x32 => :bad_page,  # Illegal page number provided.
+    0x33 => :flash_fail, # Page did not reprogram correctly.
+    0x34 => :main_app_corrupt,  # Main Application corrupt.
+    0x35 => :timed_out,  # Msg state machine timed out.
+  }.freeze
+end

data/lib/sphero_pwn/session.rb

@@ -0,0 +1,160 @@
+require 'thread'
+
+# A communication session with a robot.
+class SpheroPwn::Session
+  # @param {Channel} channel the byte-level communication channel with the
+  #   robot
+  def initialize(channel)
+    @channel = channel
+
+
+    # Must be acquired to change any of the values below.
+    @sequence_lock = Mutex.new
+    # Maps sequence numbers to responses expected from the server.
+    @pending_responses = {}
+    # Sweeps the space of valid sequence numbers.
+    @last_sequence = 0
+  end
+
+
+  # Terminates this session and closes the underlying communication channel.
+  #
+  # @return {Session} self
+  def close
+    @channel.close
+    self
+  end
+
+  # @param {Command} command the command to be sent
+  # @return {Session} self
+  def send_command(command)
+    sequence = 0
+    if command.expects_response?
+      @sequence_lock.synchronize do
+        sequence = alloc_sequence
+        @pending_responses[sequence] = command.response_class
+      end
+    end
+
+    bytes = command.to_bytes sequence
+    @channel.send_bytes bytes
+    self
+  end
+
+  # Reads messages from the robot until a response is received.
+  #
+  # @return {Response} the response received
+  def recv_until_response
+    loop do
+      message = recv_message
+      if message && message.kind_of?(SpheroPwn::Response)
+        return message
+      end
+
+      # TODO(pwnall): customizable sleep interval
+      sleep 0.05
+    end
+  end
+
+  # Reads a message from the robot.
+  #
+  # This method blocks until a message is available. The method can be called
+  # in a loop on a dedicated thread, and will synchronize correctly with
+  # {Session#send_command}.
+  #
+  # @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
+
+    packet_type = @channel.recv_bytes 1
+    case packet_type.ord
+    when 0xFF
+      read_response
+    when 0xFE
+      read_async_message
+    end
+  end
+
+  # Finds an unused sequence number.
+  #
+  # Sending a command that requires a response allocates a sequence number.
+  # Receiving the required response frees up the sequence number.
+  #
+  # The caller should own the sequence_lock mutex.
+  #
+  # @return {Number} a sequence number that can be used for a command; the
+  #   sequence number is not considered to be allocated until the caller
+  #   inserts it as a key in @pending_commands
+  def alloc_sequence
+    begin
+      @last_sequence = (@last_sequence + 1) & 0xFF
+    end while @pending_responses.has_key? @last_sequence
+    @last_sequence
+  end
+  private :alloc_sequence
+
+  # Reads the response to a command from the channel.
+  #
+  # This assumes that the start-of-packet was already read and indicates a
+  # command response.
+  #
+  # @return {Response} the parsed response
+  def read_response
+    header_bytes = @channel.recv_bytes(3).unpack('C*')
+    response_code, sequence, data_length = *header_bytes
+
+    # 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*')
+    checksum = data_bytes.pop
+    unless self.class.valid_checksum?(header_bytes, data_bytes, checksum)
+      return nil
+    end
+
+    klass = @sequence_lock.synchronize { @pending_responses.delete sequence }
+    return nil if klass.nil?
+
+    klass.new response_code, sequence, data_bytes
+  end
+  private :read_response
+
+  # Reads an asynchronous message from the channel.
+  #
+  # This assumes that the start-of-packet was already read and indicates an
+  # asynchronous message.
+  #
+  # @return {Response} the parsed response
+  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
+
+    # 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*')
+    checksum = data_bytes.pop
+    unless self.class.valid_checksum?(header_bytes, data_bytes, checksum)
+      return nil
+    end
+
+    SpheroPwn::Asyncs.create class_id, data_bytes
+  end
+  private :read_async_message
+
+  # Checks if a message's checksum matches its contents.
+  #
+  # @param {Array<Number>} header_bytes the header semantics differ between
+  #   command responses and async messages, but both have 3 bytes
+  # @param {Array<Number>} data_bytes
+  def self.valid_checksum?(header_bytes, data_bytes, checksum)
+    sum = 0
+    header_bytes.each { |byte| sum += byte }
+    data_bytes.each { |byte| sum += byte }
+    checksum == ((sum & 0xFF) ^ 0xFF)
+  end
+end

data/lib/sphero_pwn/test_channel.rb

@@ -0,0 +1,18 @@
+module SpheroPwn
+  # Intelligently toggles between recording and replaying test data.
+  #
+  # @param {String} rfconn_path the path to the device file connecting to the
+  #   robot's Bluetooth RFCONN service
+  # @param {String} recording_path the file storing the recording
+  # @return {Channel} if the recording file at the given path exists, the
+  #   return value is a {ReplayChannel} that uses the file; otherwise, the
+  #   return value is a {ChannelRecorder} that creates the recording
+  def self.new_test_channel(rfconn_path, recording_path)
+    if File.exist? recording_path
+      ReplayChannel.new recording_path
+    else
+      channel = Channel.new rfconn_path
+      ChannelRecorder.new channel, recording_path
+    end
+  end
+end

data/test/channel_recorder_test.rb

@@ -0,0 +1,102 @@
+require_relative './helper.rb'
+
+require 'stringio'
+
+describe SpheroPwn::ChannelRecorder do
+  describe 'with a channel that always responds' do
+    before do
+      @channel = MiniTest::Mock.new
+      @channel.expect :send_bytes, @channel, ["Hello\n"]
+      @channel.expect :recv_bytes, 'Hello', [5]
+      @channel.expect :recv_bytes, " too!\n", [6]
+      @channel.expect :send_bytes, @channel, ['OK']
+      @channel.expect :send_bytes, @channel, ["Bye\n"]
+      @channel.expect :recv_bytes, 'Bye', [3]
+      @channel.expect :recv_bytes, " bye\n", [5]
+      @channel.expect :close, @channel, []
+    end
+
+    after { @channel.verify }
+
+    it 'proxies calls correctly' do
+      output = StringIO.new
+      recorder = File.stub :open, output do
+        SpheroPwn::ChannelRecorder.new @channel, '/tmp/stubbed'
+      end
+
+      assert_equal recorder, recorder.send_bytes("Hello\n")
+      assert_equal 'Hello', recorder.recv_bytes(5)
+      assert_equal " too!\n", recorder.recv_bytes(6)
+      assert_equal recorder, recorder.send_bytes('OK')
+      assert_equal recorder, recorder.send_bytes("Bye\n")
+      assert_equal 'Bye', recorder.recv_bytes(3)
+      assert_equal " bye\n", recorder.recv_bytes(5)
+      assert_equal recorder, recorder.close
+    end
+
+    it 'produces the output file correctly' do
+      output = StringIO.new
+      recorder = File.stub :open, output do
+        SpheroPwn::ChannelRecorder.new @channel, '/tmp/stubbed'
+      end
+
+      recorder.send_bytes "Hello\n"
+      recorder.recv_bytes 5
+      recorder.recv_bytes 6
+      recorder.send_bytes 'OK'
+      recorder.send_bytes "Bye\n"
+      recorder.recv_bytes 3
+      recorder.recv_bytes 5
+      recorder.close
+
+      golden = <<END_STRING
+> 48 65 6C 6C 6F 0A
+< 48 65 6C 6C 6F 20 74 6F 6F 21 0A
+> 4F 4B
+> 42 79 65 0A
+< 42 79 65 20 62 79 65 0A
+END_STRING
+      assert_equal golden, output.string
+    end
+  end
+
+  describe 'with a channel that sometimes returns nils' do
+    before do
+      @channel = MiniTest::Mock.new
+      @channel.expect :send_bytes, @channel, ["Hello\n"]
+      @channel.expect :recv_bytes, nil, [5]
+      @channel.expect :recv_bytes, "Hello too!\n", [11]
+      @channel.expect :close, @channel, []
+    end
+
+    it 'proxies calls correctly' do
+      output = StringIO.new
+      recorder = File.stub :open, output do
+        SpheroPwn::ChannelRecorder.new @channel, '/tmp/stubbed'
+      end
+
+      assert_equal recorder, recorder.send_bytes("Hello\n")
+      assert_equal nil, recorder.recv_bytes(5)
+      assert_equal "Hello too!\n", recorder.recv_bytes(11)
+      assert_equal recorder, recorder.close
+    end
+
+    it 'produces the output file correctly' do
+      output = StringIO.new
+      recorder = File.stub :open, output do
+        SpheroPwn::ChannelRecorder.new @channel, '/tmp/stubbed'
+      end
+
+      recorder.send_bytes "Hello\n"
+      recorder.recv_bytes 5
+      recorder.recv_bytes 11
+      recorder.close
+
+      golden = <<END_STRING
+> 48 65 6C 6C 6F 0A
+< 48 65 6C 6C 6F 20 74 6F 6F 21 0A
+END_STRING
+      assert_equal golden, output.string
+    end
+  end
+end