ruby-player 0.4.1 → 0.5.0

data/NEWS.md

@@ -1,3 +1,13 @@
+## 2012-03-21 0.5.0
+
+* Log level by default :notice is removed. Use :info. 
+* Added ActArray#power? method.
+* Added #beams and #stored attributes for Gripper class.
+* Added #position, #speed, #acceleration and #current attributes for Actor class.
+* Added #px, #py, #pa, #vx, #vy, #va and #power? attributes for Position2d class. Method #power is deprecated.
+* Added #volts, #percent, #joules and #watts attributes for Power class.
+* Added blobfinder interface
+
 ## 2012-03-06 0.4.1
 
 * Fixed bug in logging of warn and error messages

data/README.md

@@ -4,7 +4,15 @@ Summary
 -------------------------------------
 Ruby Player provide high level client library to access to Player server in pure Ruby.
 
-Currently (2012-01-07) the Ruby Player are developing and testing with Player 3.1.0 latest svn version
+This project is active developing now! *Please don't use it in serious projects.*
+
+Why?
+-------------------------------------
+The Player project distributes bindings of client libraries for Ruby and Python but I think that this project has several reasons to be:
+
+1. Pure implementation doesn't require C\C++ libraries of Player, SWIG and compilator. You can use it on any platform with installed Ruby.
+2. In contrast to standard bindings Ruby Player is spreaded as gem and you can use it with Bundle, RVM and others tools which we all are loving.
+3. Standard bindings doesn't use the expression of Ruby. Calls of function in C style without blocks, hashes and exceptions. 
 
 Install
 -------------------------------------
@@ -32,6 +40,7 @@ The list of support objects and devices of Player.
 
 * Client object
 * ActArray
+* BlobFinder
 * Gripper
 * Position2d
 * Power

data/TODO.md

@@ -5,11 +5,13 @@ For supported devices
 
 Implement PLAYER_RANGER_DATA_RANGESTAMPED and PLAYER_RANGER_DATA_INTNSTAMPED
 
+**position2d** - The position2d proxy provides an interface to a mobile robot base
+
+Implement PLAYER_POSITION2D_CMD_POS command
+
 Candidates for support
 --------------------------------------
 
-**blobfinder** - The blobfinder proxy provides an interface to color blob detectors such as the ACTS vision system.
-
 **graphics2d** - The graphics2d proxy provides an interface to the graphics2d.
 
 **graphics3d** - The graphics3d proxy provides an interface to the graphics3d.

data/examples/simple_example.rb

@@ -5,7 +5,7 @@ Player::Client.connect("localhost") do |robot|
   #main loop
   robot.loop(0.05) do
     puts "Position: x=%{px}, y=%{py}, a=%{pa}" % pos2d.state
-    r = ranger.rangers
+    r = ranger.collect { |r| r.range }
     puts "Rangers: #{r}"
 
     if r[0] < 2.5

data/lib/ruby-player/actarray.rb

@@ -29,6 +29,12 @@ module Player
       @geom   = { px: 0.0, py: 0.0, pz: 0.0, proll: 0.0, ppitch: 0.0, pyaw: 0.0 }
     end
 
+    # Check common power
+    # @return [Boolean]
+    def power?
+      state[:motor_state] != 0
+    end
+
     # Turn on power all actuators
     # Be careful when turning power on that the array is not obstructed 
     # from its home position in case it moves to it (common behaviour)
@@ -151,10 +157,10 @@ module Player
       msg[8..-5].unpack("a20" * c).each_with_index do |s,i|
         @actuators[i] ||= Actuator.new(i,self)
         @actuators[i].read_state(s)
-        debug "Get state for actuator ##{i}: " + hash_to_sft(@actuators[i].state)
+        debug "Got state for actuator ##{i}: " + hash_to_sft(@actuators[i].state)
       end
       @state[:motor_state] = msg[-4,4].unpack("N")[0]
-      debug "Get state: motor_state=%d" % @state[:motor_state]
+      debug "Got state: motor_state=%d" % @state[:motor_state]
     end
 
     def read_geom(msg)
@@ -162,10 +168,10 @@ module Player
       msg[8..-48].unpack("a80" * c).each_with_index do |s, i|
         @actuators[i] ||= Actuator.new(i,self)
         @actuators[i].read_geom(s)
-        debug "Get geom for actuator ##{i}: " + hash_to_sft(@actuators[i].geom)
+        debug "Got geom for actuator ##{i}: " + hash_to_sft(@actuators[i].geom)
       end
       fill_hash!(@geom, msg[-48..-1].unpack("G6"))
-      debug("Get geom: " + hash_to_sft(@geom))
+      debug("Got geom: " + hash_to_sft(@geom))
     end
   end
 end

data/lib/ruby-player/actuator.rb

@@ -49,6 +49,34 @@ module Player
       }
     end
 
+    # The position of the actuator in m or rad depending on the type.
+    # @see #state
+    # @return [Float]
+    def position
+      state[:position]
+    end
+
+    # The speed of the actuator in m/s or rad/s depending on the type. 
+    # @see #state
+    # @return [Float]
+    def speed
+      state[:speed]
+    end
+
+    # The acceleration of the actuator in m/s^2 or rad/s^2 depending on the type.
+    # @see #state
+    # @return [Float]
+    def acceleration
+      state[:acceleration]
+    end
+
+    # The current of the actuator in A.
+    # @see #state
+    # @return [Float]
+    def current
+      state[:current]
+    end
+
     # Set speed for a joint for all subsequent movements
     # @param speed - speed setting in rad/s or m/s
     # @return [Actuator] self

data/lib/ruby-player/blob.rb

@@ -0,0 +1,79 @@
+# Ruby Player - Ruby client library for Player (tools for robots) 
+#
+# Copyright (C) 2012  Aleksey Timin
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+module Player
+  # Classs describing a single blob. 
+  class Blob
+    # @return [Hash] blob description => { :id, :color, :area, :x, :y, :left, :right, :top, :bottom, :range }
+    attr_reader :state
+
+    def initialize(index, blobfinder)
+      @index, @blobfinder = index, blobfinder
+      @state = { id: 0, color: 0, area: 0, x: 0, y: 0, left: 0, right: 0, top: 0, bottom: 0, range: 0.0 }
+    end
+
+    # Blob id
+    # @return [Integer]
+    def id
+      state[:id]
+    end
+
+    # A descriptive color for the blob (useful for gui's). 
+    # @return [Integer]
+    def color
+      state[:color]
+    end
+
+    # The blob area [pixels]. 
+    # @return [Integer]
+    def area
+      state[:area]
+    end
+
+    # The blob centroid [pixels]. 
+    def x
+      state[:x]
+    end
+    
+    # The blob centroid [pixels]. 
+    def y
+      state[:y]
+    end
+
+    # Bounding box for the blob [pixels]. 
+    def left
+      state[:left]
+    end
+
+    # Bounding box for the blob [pixels]. 
+    def right 
+      state[:right]
+    end
+
+    # Bounding box for the blob [pixels]. 
+    def top
+      state[:top]
+    end
+
+    # Bounding box for the blob [pixels]. 
+    def bottom
+      state[:bottom]
+    end
+
+    # Range to the blob center [m].
+    def range
+      state[:range]
+    end
+  end
+end

data/lib/ruby-player/blob_finder.rb

@@ -0,0 +1,150 @@
+# Ruby Player - Ruby client library for Player (tools for robots) 
+#
+# Copyright (C) 2012  Aleksey Timin
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+module Player
+  # The blobfinder interface provides access to devices that detect blobs in images
+  class BlobFinder < Device
+    include Enumerable
+    
+    # Blobfinder data
+    # @return [Hash] iby defult{ width: 0.0, height: 0.0, blobs: [] }
+    attr_reader :state
+
+    # Tracking color
+    # @see #set_color
+    # @return [Hash] by default { channel: 0, rmin: 0, rmax: 0, gmin: 0, gmax: 0, bmin: 0, bmax: 0 }
+    attr_reader :color
+
+    # Imager params.
+    # @see #set_imager_params
+    # @return [Hash] by default { brightness: 0, contrast: 0, colormode: 0, autogain: 0 }
+    attr_reader :imager_params 
+
+    def initialize(dev, client)
+      super
+      @blobs = []
+      @state = { width: 0, height: 0, blobs: @blobs }
+      @color = { channel: 0, rmin: 0, rmax: 0, gmin: 0, gmax: 0, bmin: 0, bmax: 0 }
+      @imager_params = { brightness: 0, contrast: 0, colormode: 0, autogain: 0 }
+    end
+
+    # The image width. 
+    # @return [Integer]
+    def width
+      state[:width] 
+    end
+
+    # The image height. 
+    # @return [Integer]
+    def height
+      state[:height] 
+    end
+
+    # The list of blobs.
+    # @return [Array] 
+    def blobs
+      state[:blobs] 
+    end
+
+    # Query color settings
+    # @return [BlobFinder] self
+    def query_color
+      send_message(PLAYER_MSGTYPE_REQ, PLAYER_BLOBFINDER_REQ_GET_COLOR)
+      self
+    end
+
+    # Set tracking color.
+    # @param [Hash] color
+    # @option [Integer] color :chanel For devices that can track multiple colors, indicate which color channel we are defining with this structure. 
+    # @option [Integer] color :rmin RGB minimum and max values (0-255) 
+    # @option [Integer] color :rmax RGB maximum and max values (0-255) 
+    # @option [Integer] color :gmin RGB minimum and max values (0-255) 
+    # @option [Integer] color :gmax RGB maximum and max values (0-255) 
+    # @option [Integer] color :bmin RGB minimum and max values (0-255) 
+    # @option [Integer] color :bmax RGB maximum and max values (0-255) 
+    # @return [BlobFinder] self
+    def set_color(color={})
+      data = to_a_by_default(color, @color)
+
+      send_message(PLAYER_MSGTYPE_REQ, PLAYER_BLOBFINDER_REQ_SET_COLOR, data.pack("N*"))
+      self
+    end
+    
+    # Set imager params 
+    # Imaging sensors that do blob tracking generally have some sorts of image quality parameters that you can tweak.
+    # @param [Hash] params
+    # @option [Integer] params :brightness brightness (0-255)
+    # @option [Integer] params :contrast contrast (0-255)
+    # @option [Integer] params :color color mode (0=RGB/AutoWhiteBalance Off, 1=RGB/AutoWhiteBalance On, 2=YCrCB/AWB Off, 3=YCrCb/AWB On) 
+    # @option [Integer] params :autogain auto gain (0=off, 1=on)
+    # @return [BlobFinder] self
+    def set_imager_params(params={})
+      data = to_a_by_default(params, @imager_params)
+      send_message(PLAYER_MSGTYPE_REQ, PLAYER_BLOBFINDER_REQ_SET_IMAGER_PARAMS, data.pack("N*"))
+      self
+    end
+
+    # Get blob
+    # @param [Integer] blob index 
+    # @return [Blob] blob
+    def [](index)
+      @blobs[index] ||= Blob.new(index, self) 
+    end
+
+    def each
+      @blobs.each { |b| yield b }
+    end
+
+    def fill(hdr, msg)
+      case hdr.subtype
+      when PLAYER_BLOBFINDER_DATA_BLOBS
+        read_data(msg)
+      else
+        unexpected_message hdr
+      end
+    end
+
+    def handle_response(hdr, msg)
+      case hdr.subtype
+      when PLAYER_BLOBFINDER_REQ_GET_COLOR
+        read_color(msg)
+      when 1,2
+        nil
+      else
+        unexpected_message hdr
+      end
+    end
+
+    private
+    def read_data(msg)
+      data = msg[0..16].unpack("N*")
+      state[:width] = data[0]
+      state[:height] = data[1]
+
+      debug "Got image size #{state[:width]}x#{state[:height]}"
+
+      blob_count = data[2] + data[3]*256
+      blob_count.times do |i|
+        blob_data = msg[i*40 + 16, 40].unpack("N9g")
+        fill_hash!(self[i].state, blob_data)
+        debug "Got blob: " + hash_to_sft(self[i].state) 
+      end
+    end
+
+    def read_color(msg)
+      fill_hash!(@color, msg.unpack("N7"))
+        debug "Got color: " + hash_to_sft(@color) 
+    end
+  end
+end

data/lib/ruby-player/client.rb

@@ -12,6 +12,8 @@
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 
+require "socket"
+
 module Player
   # The client object manages the connection with the Player server
   #
@@ -23,7 +25,7 @@ module Player
   #     pos2d.set_speed(vx: 1, vy: 0, va: 0.2)
   #     #main loop
   #     robot.loop do
-  #       puts "Position: x=%{px}, y=%{py}, a=%{pa}" % pos2d.position
+  #       puts "Position: x=%{px}, y=%{py}, a=%{pa}" % pos2d.state
   #     end
   #   end
   class Client < Device
@@ -35,10 +37,10 @@ module Player
     # @param [String] host host of Player server 
     # @param [Hash] opts client options
     # @option opts :port port of connection
-    # @option opts :log_level level of log messages [:debug,:notice, :warn, :error] default :notice
+    # @option opts :log_level level of log messages [:debug, :info, :warn, :error] default :info
     def initialize(host, opts = {})
       port = opts[:port] || 6665
-      @log_level = (opts[:log_level] || :notice).to_sym
+      @log_level = (opts[:log_level] || :info).to_sym
 
       @socket = TCPSocket.new(host, port)
       @addr = DevAddr.new(host: 0, robot: 0, interface: PLAYER_PLAYER_CODE, index: 0)
@@ -46,7 +48,8 @@ module Player
       @devices = []
 
       banner = @socket.read(PLAYER_IDENT_STRLEN)
-      notice "Connect with #{banner} in #{host}:#{port}"
+      info "Connect with #{banner} in #{host}:#{port}"
+      warn "This software required Player version >= 3.1.0" if banner[/\d.\d/].to_f < 3.1
       send_message PLAYER_MSGTYPE_REQ, PLAYER_PLAYER_REQ_DATAMODE, [PLAYER_DATAMODE_PULL].pack("N")
 
       debug "Set delivery mode in PULL"
@@ -85,13 +88,13 @@ module Player
       index = opts[:index] || 0
       access = opts[:access] || PLAYER_OPEN_MODE
 
-      notice "Subscribing to #{type}:#{index}"
+      info "Subscribing to #{type}:#{index}"
       data = DevAddr.new(interface: code, index: index).to_a + [access, 0, 0]
       send_message PLAYER_MSGTYPE_REQ, PLAYER_PLAYER_REQ_DEV, data.pack("N*")
 
       read!
       
-      @devices.select { |d| d.addr.interface == code && d.addr.index == index}.first
+      @dev
     end
 
     # Check connection
@@ -120,7 +123,7 @@ module Player
       end
     end
 
-    def write(hdr, msg)
+    def send_message_with_hdr(hdr, msg)
       send_header hdr
       @socket.write msg 
       @socket.flush
@@ -132,7 +135,7 @@ module Player
         nil
       when PLAYER_PLAYER_REQ_DEV
         # read device identifier
-        dev = DevAddr.decode(msg[0,PLAYERXDR_DEVADDR_SIZE])
+        dev_addr = DevAddr.decode(msg[0,PLAYERXDR_DEVADDR_SIZE])
         # read the granted access and driver name
         data = msg[PLAYERXDR_DEVADDR_SIZE,8].unpack("N*")
         access = data[0]
@@ -140,12 +143,18 @@ module Player
         drv_name = msg[-data[1]-2..-1]
 
         if access == PLAYER_ERROR_MODE
-          raise_error "Error subscribing to " + dev.interface_name + ":" + dev.index 
+          raise_error "Error subscribing to " + dev_addr.interface_name + ":" + dev_addr.index 
         end
         
-        debug "Got response: #{dev.interface_name}:#{dev.index} (driver name - #{drv_name})"
-
-        @devices << make_device(dev)
+        debug "Got response: #{dev_addr.interface_name}:#{dev_addr.index} (driver name - #{drv_name})"
+
+        @dev = make_device(dev_addr)
+        if @devices.one? { |d| d.addr == dev_addr }
+          warn "The device #{dev_addr.interface_name}:#{dev_addr.index} has already been subscribed" 
+          @dev = nil 
+        else 
+          @devices << @dev
+        end
       when PLAYER_PLAYER_REQ_DATAMODE, PLAYER_PLAYER_REQ_DATA
         nil
       else

data/lib/ruby-player/common.rb

@@ -23,20 +23,20 @@ module Player
       end
     end
 
-    def notice(msg)
-      if [:debug, :notice].include?(@log_level)
-        puts log_msg(:notice, msg).to_ansi.normal
+    def info(msg)
+      if [:debug, :info].include?(@log_level)
+        puts log_msg(:info, msg).to_ansi.normal
       end
     end
 
     def warn(msg)
-      if [:debug, :notice, :warn].include?(@log_level)
+      if [:debug, :info, :warn].include?(@log_level)
         puts log_msg(:warn, msg).to_ansi.blue
       end
     end
 
     def error(msg)
-      if [:debug, :notice, :warn, :debug].include?(@log_level)
+      if [:debug, :info, :warn, :debug].include?(@log_level)
         puts log_msg(:error, msg).to_ansi.red
       end
     end
@@ -69,8 +69,12 @@ module Player
       end
     end
 
+    def to_a_by_default(src, default)
+      default.keys.map { |k| src[k] || default[k] }
+    end
+
     def unexpected_message(hdr)
-      warn "Get unexpection message type #{hdr.type_name}::#{hdr.subtype_name} for #@addr"
+      warn "Got unexpection message type #{hdr.type_name}::#{hdr.subtype_name} for #@addr"
     end
 
     def hash_to_sft(hash)

data/lib/ruby-player/constants.rb

@@ -292,6 +292,7 @@ module Player
 
   PLAYER_BLOBFINDER_REQ_SET_COLOR         = 1
   PLAYER_BLOBFINDER_REQ_SET_IMAGER_PARAMS = 2
+  PLAYER_BLOBFINDER_REQ_GET_COLOR         = 3
   PLAYER_BLOBFINDER_DATA_BLOBS            = 1
 
   PLAYER_BUMPER_REQ_GET_GEOM = 1

data/lib/ruby-player/dev_addr.rb

@@ -43,7 +43,7 @@ module Player
     end
 
     def to_s
-      "device addr [#@host:#@robot] #@interface_name:#@index"
+      "device addr [#@host:#@robot] #{interface_name}:#@index"
     end
 
     def to_a

data/lib/ruby-player/device.rb

@@ -11,7 +11,6 @@
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
-require "socket"
 
 module Player
   # Basic class for all intrefaces
@@ -35,7 +34,7 @@ module Player
     end
    
     def send_message(type, subtype, msg="")
-      @client.write( Header.new(
+      @client.send_message_with_hdr( Header.new(
           dev_addr: @addr,
           type: type,
           subtype: subtype,

data/lib/ruby-player/gripper.rb

@@ -77,6 +77,22 @@ module Player
       self
     end
 
+    # Provides information on how far into the gripper an object is. 
+    # For most grippers, this will be a bit mask, with each bit representing whether 
+    # a beam has been interrupted or not.
+    # @see #state
+    # @retun [Integer]
+    def beams
+      state[:beams]
+    end
+
+    # Number of currently stored objects
+    # @see #state
+    # @retun [Integer]
+    def stored
+      state[:stored]
+    end
+
     # Check openinig
     def open?
       state[:state] & PLAYER_GRIPPER_STATE_OPEN > 0
@@ -98,24 +114,28 @@ module Player
     end
 
     # Tells the gripper to open
+    # @return [Gripper] self
     def open!
       send_message(PLAYER_MSGTYPE_CMD, PLAYER_GRIPPER_CMD_OPEN)
       self
     end
 
     # Tells the gripper to close
+    # @return [Gripper] self
     def close!
       send_message(PLAYER_MSGTYPE_CMD, PLAYER_GRIPPER_CMD_CLOSE)
       self
     end
     
     # Tells the gripper to stop
+    # @return [Gripper] self
     def stop!
       send_message(PLAYER_MSGTYPE_CMD, PLAYER_GRIPPER_CMD_STOP)
       self
     end
 
     # Tells the gripper to store whatever it is holding.
+    # @return [Gripper] self
     def store!
       send_message(PLAYER_MSGTYPE_CMD, PLAYER_GRIPPER_CMD_STORE)
       self
@@ -123,6 +143,7 @@ module Player
 
     # Tells the gripper to retrieve a stored object (so that it can be put back into the world).
     # The opposite of store.
+    # @return [Gripper] self
     def retrieve!
       send_message(PLAYER_MSGTYPE_CMD, PLAYER_GRIPPER_CMD_RETRIEVE)
       self
@@ -149,23 +170,23 @@ module Player
     private
     def read_state(msg)
       fill_hash!(@state, msg.unpack("NNN"))
-      debug "Get state: " + hash_to_sft(@state)
+      debug "Got state: " + hash_to_sft(@state)
     end
 
     def read_geom(msg)
       data = msg.unpack("G12NN")
       fill_hash!(@geom[:pose], data)
-      debug "Get pose: " + hash_to_sft(@geom[:pose])
+      debug "Got pose: " + hash_to_sft(@geom[:pose])
 
       fill_hash!(@geom[:outer_size], data)
-      debug "Get outer size: " + hash_to_sft(@geom[:outer_size])
+      debug "Got outer size: " + hash_to_sft(@geom[:outer_size])
 
       fill_hash!(@geom[:inner_size], data)
-      debug "Get inner size: " + hash_to_sft(@geom[:inner_size])
+      debug "Got inner size: " + hash_to_sft(@geom[:inner_size])
 
       @geom[:number_beams] = data.shift
       @geom[:capacity] = data.shift
-      debug("Get number_beams=%{number_beams}, capacity=%{capacity}" % @geom)
+      debug("Got number_beams=%{number_beams}, capacity=%{capacity}" % @geom)
     end
   end
 end

data/lib/ruby-player/header.rb

@@ -20,7 +20,7 @@ module Player
     attr_reader :dev_addr, :type, :subtype, :time, :seq, :size
 
     def initialize(param = {})
-      @dev_addr = param[:dev_addr]
+      @dev_addr = param[:dev_addr] || DevAddr.new
       @type = param[:type].to_i
       @subtype = param[:subtype].to_i
       @time = param[:time] || Time.now.to_f / 1000