ruby-nxt 0.8.1

data/lib/commands/rotation_sensor.rb

@@ -0,0 +1,72 @@
+# ruby-nxt Control Mindstorms NXT via Bluetooth Serial Port Connection
+# Copyright (C) 2006 Tony Buser <tbuser@gmail.com> - http://juju.org
+#
+# 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 2 of the License
+#
+# 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.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software Foundation,
+# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+# Implements the "Rotation Sensor" block in NXT-G (using an nxt motor as rotation sensor)
+class Commands::RotationSensor
+
+  attr_accessor :port, :trigger_direction, :trigger_point, :comparison
+  
+  def initialize(nxt)
+    @nxt      = nxt
+    
+    # defaults the same as NXT-G
+    @port               = :a
+    @trigger_direction  = :forward
+    @trigger_point      = 360
+    @comparison         = ">"
+    reset
+    @internal_counter   = degrees
+  end
+
+  # returns true or false based on comparison type and difference between last time reset point
+  def logic
+    @trigger_direction == :forward ? trigger = @trigger_point : trigger = -@trigger_point
+    case @comparison
+      when ">"
+        degrees >= trigger ? true : false
+      when "<"
+        degrees <= trigger ? true : false
+    end
+  end
+  
+  # resets the value_scaled property, use this to reset the degrees counter
+  def reset
+    @nxt.reset_motor_position(NXTComm.const_get("MOTOR_#{@port.to_s.upcase}"))
+  end
+  
+  # returns the number of degrees moved since last reset point
+  def degrees
+    @internal_counter = rotation_count
+    @internal_counter
+  end
+  
+  # attempts to determine direction based on last time position was requested (may not be accurate)
+  def direction
+    case true
+      when rotation_count > @internal_counter
+        "forwards"
+      when rotation_count < @internal_counter
+        "backwards"
+      when rotation_count == @internal_counter
+        "stopped"
+    end
+  end
+  
+  # attempt to return the output_state requested
+  def method_missing(cmd)
+    @nxt.get_output_state(NXTComm.const_get("MOTOR_#{@port.to_s.upcase}"))[cmd]
+  end
+end

data/lib/commands/sound.rb

@@ -0,0 +1,102 @@
+# ruby-nxt Control Mindstorms NXT via Bluetooth Serial Port Connection
+# Copyright (C) 2006 Tony Buser <tbuser@gmail.com> - http://juju.org
+#
+# 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 2 of the License
+#
+# 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.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software Foundation,
+# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+# Implements the "Sound" block in NXT-G
+class Commands::Sound
+  
+  attr_accessor :action
+  attr_accessor :control
+  attr_accessor :volume # TODO not sure how to set this with direct commands?
+  attr_accessor :repeat
+  attr_accessor :file
+  attr_accessor :note
+  attr_accessor :duration
+  attr_accessor :wait
+  
+  def initialize(nxt)
+    @nxt      = nxt
+    
+    # defaults the same as NXT-G
+    @action   = :file
+    @control  = :play
+    @volume   = 75
+    @repeat   = false
+    @file     = "Good Job.rso"
+    @note     = "C"
+    @duration = 0.5
+    @wait     = true
+  end
+
+  # execute the Sound command based on the properties specified
+  def start
+    if @action == :file
+      @nxt.play_sound_file(@file,@repeat)
+    else
+      @nxt.play_tone(@note.to_freq,(@duration * 1000).to_i)
+    end
+    
+    # TODO figure out a logical way to repeat a tone without blocking execution
+    
+    if @wait
+      if @action == :tone
+        sleep(@duration)
+      else
+        # TODO don't know how to sleep until a sound file finishes
+      end
+    end
+  end
+
+  # stop the Sound command
+  def stop
+    @nxt.stop_sound_playback
+  end
+  
+end
+
+class String
+  # converts a note string to equiv frequency in Hz
+  # TODO need to get a better range...
+  def to_freq
+    case self.downcase
+      when "c"
+        523
+      when "c#"
+        554
+      when "d"
+        587
+      when "d#"
+        622
+      when "e"
+        659
+      when "f"
+        698
+      when "f#"
+        740
+      when "g"
+        784
+      when "g#"
+        830
+      when "a"
+        880
+      when "a#"
+        923
+      when "b"
+        988
+      else
+        raise "Unknown Note: #{self}"
+    end
+  end
+end

data/lib/commands/sound_sensor.rb

@@ -0,0 +1,67 @@
+# ruby-nxt Control Mindstorms NXT via Bluetooth Serial Port Connection
+# Copyright (C) 2006 Tony Buser <tbuser@gmail.com> - http://juju.org
+#
+# 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 2 of the License
+#
+# 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.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software Foundation,
+# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+require "nxt_comm"
+require "commands/mixins/sensor"
+
+# Implements the "Sound Sensor" block in NXT-G
+class Commands::SoundSensor
+  
+  include Commands::Mixins::Sensor
+  
+  attr_reader :port, :mode
+  attr_accessor :trigger_point, :comparison
+  
+  def initialize(nxt)
+    @nxt      = nxt
+    
+    # defaults the same as NXT-G
+    @port           = 2
+    @trigger_point  = 50
+    @comparison     = ">"
+    @mode           = "dba"
+    set_mode
+  end
+  
+  def mode=(mode)
+    @mode = mode
+    set_mode
+  end
+  
+  # scaled value read from sensor
+  def sound_level
+    value_scaled
+  end
+  
+  # returns the raw value of the sensor
+  def raw_value
+    value_raw
+  end
+  
+  # sets up the sensor port
+  def set_mode
+    @nxt.set_input_mode(
+      NXTComm.const_get("SENSOR_#{@port}"),
+      NXTComm.const_get("SOUND_#{@mode.upcase}"),
+      NXTComm::PCTFULLSCALEMODE
+    )
+  end
+  
+  # attempt to return the input_value requested
+  def method_missing(cmd)
+    @nxt.get_input_values(NXTComm.const_get("SENSOR_#{@port}"))[cmd]
+  end
+end

data/lib/commands/touch_sensor.rb

@@ -0,0 +1,84 @@
+# ruby-nxt Control Mindstorms NXT via Bluetooth Serial Port Connection
+# Copyright (C) 2006 Tony Buser <tbuser@gmail.com> - http://juju.org
+#
+# 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 2 of the License
+#
+# 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.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software Foundation,
+# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+# require File.dirname(File.expand_path(__FILE__))+'/../nxt_comm'
+# require File.dirname(File.expand_path(__FILE__))+'/mixins/sensor'
+require "nxt_comm"
+require "commands/mixins/sensor"
+
+# Implements the "Touch Sensor" block in NXT-G
+class Commands::TouchSensor
+
+  include Commands::Mixins::Sensor
+
+  attr_reader :port, :action
+  
+  def initialize(nxt)
+    @nxt      = nxt
+    
+    # defaults the same as NXT-G
+    @port   = 1
+    @action = :pressed
+    set_mode
+  end
+
+  def action=(action)
+    @action = action
+    set_mode
+  end
+  alias trigger_point= action=
+  
+  def comparison=(op)
+  	raise NotImplementedError, "Cannot assign a comparison operator for this sensor type."
+  end
+
+  # returns true or false based on action type
+  def logic
+    case @action
+      when :pressed
+        value_scaled > 0 ? true : false
+      when :released
+        value_scaled > 0 ? false : true
+      when :bumped
+        value_scaled > 0 ? true : false
+    end
+  end
+  
+  # returns the raw value of the sensor
+  def raw_value
+    value_raw
+  end
+  
+  # resets the value_scaled property, use this to reset the sensor when in :bumped mode
+  def reset
+    @nxt.reset_input_scaled_value(NXTComm.const_get("SENSOR_#{@port}"))
+  end
+  
+  # sets up the sensor port
+  def set_mode
+    @action == :bumped ? mode = NXTComm::PERIODCOUNTERMODE : mode = NXTComm::BOOLEANMODE
+    @nxt.set_input_mode(
+      NXTComm.const_get("SENSOR_#{@port}"),
+      NXTComm::SWITCH,
+      mode
+    )
+  end
+  
+  # attempt to return the input_value requested
+  def method_missing(cmd)
+    @nxt.get_input_values(NXTComm.const_get("SENSOR_#{@port}"))[cmd]
+  end
+end

data/lib/commands/ultrasonic_sensor.rb

@@ -0,0 +1,84 @@
+# ruby-nxt Control Mindstorms NXT via Bluetooth Serial Port Connection
+# Copyright (C) 2006 Tony Buser <tbuser@gmail.com> - http://juju.org
+#
+# 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 2 of the License
+#
+# 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.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software Foundation,
+# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+require "nxt_comm"
+require "ultrasonic_comm"
+require "commands/mixins/sensor"
+
+# Implements the "Ultrasonic Sensor" block in NXT-G
+class Commands::UltrasonicSensor
+  
+  include Commands::Mixins::Sensor
+  
+  # Exception thrown by distance! when the sensor cannot determine the distance.
+  class UnmeasurableDistance < Exception; end
+  
+  attr_reader :port
+  attr_accessor :mode, :trigger_point, :comparison
+  
+  def initialize(nxt)
+    @nxt      = nxt
+    
+    # defaults the same as NXT-G
+    @port           = 4
+    @trigger_point  = 50
+    @comparison     = "<"
+    @mode           = :inches
+    set_mode
+  end
+  
+  # returns distance in requested mode (:inches or :centimeters)
+  def distance
+    @nxt.ls_write(NXTComm.const_get("SENSOR_#{@port}"), UltrasonicComm.read_measurement_byte(0))
+    
+    # Keep checking until we have data to read
+    while @nxt.ls_get_status(NXTComm.const_get("SENSOR_#{@port}")) < 1
+      sleep(0.1)
+      # TODO: implement timeout so we don't get stuck if the expected data never comes
+    end
+    
+    distance = @nxt.ls_read(NXTComm.const_get("SENSOR_#{@port}"))[:data][0]
+    
+    if @mode == :centimeters
+      distance.to_i
+    else
+     (distance * 0.3937008).to_i
+    end
+  end
+  alias value_scaled distance
+  
+  # returns the distance in requested mode; raises an UnmeasurableDistance exception
+  # when the distance cannot be measured (i.e. when the distance == 255, which is
+  # the code the sensor returns when it cannot get a distance reading)
+  def distance!
+    d = distance
+    raise UnmeasurableDistance if d == 255
+    return d
+  end
+  
+  # sets up the sensor port
+  def set_mode
+    @nxt.set_input_mode(
+      NXTComm.const_get("SENSOR_#{@port}"),
+      NXTComm::LOWSPEED_9V,
+      NXTComm::RAWMODE
+    )
+    # clear buffer
+    @nxt.ls_read(NXTComm.const_get("SENSOR_#{@port}"))
+    # set sensor to continuously send pings
+    @nxt.ls_write(NXTComm.const_get("SENSOR_#{@port}"), UltrasonicComm.continuous_measurement_command)
+  end
+end

data/lib/motor.rb

@@ -0,0 +1,235 @@
+# ruby-nxt Control Mindstorms NXT via Bluetooth Serial Port Connection
+# Copyright (C) 2006 Matt Zukowski <matt@roughest.net>
+#
+# 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 2 of the License
+#
+# 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.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software Foundation,
+# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+require "yaml"
+require "brick"
+
+# Controls an NXT motor.
+# 
+# Example:
+# 
+#   m = Motor.new('a')
+#   m.forward(:degrees => 180, :power => 50)
+#   
+class Motor < Brick
+  
+  POLL_INTERVAL = 0.5
+  
+  attr_accessor :ratio
+  
+  def initialize(nxt, port)
+    super(nxt, port)
+    
+    @port = formalize_motor_port_name(port)
+    
+    @ratio = 0
+  end
+  
+  def name
+    case self.port
+      when NXTComm::MOTOR_A then 'a'
+      when NXTComm::MOTOR_B then 'b'
+      when NXTComm::MOTOR_C then 'c'
+    end
+  end
+  
+  ### high level commands #####################################################
+  
+  # Rotate the motor forwards.
+  # See Motor#run.
+  # Examples:
+  # 
+  #   m.forward(:degrees => 360, :power => 20)
+  #
+  # The above rotates the motor 360 degrees forward at 20% power.
+  #
+  #   m.forward(:time => 5) 
+  #   
+  # The above rotates the motor forwards for 5 seconds at 25% power
+  # (because 25% is the default). 
+  def forward(options)
+    debug(options.to_yaml, :forward)
+    options[:direction] = 1
+    return run(options)
+  end
+  
+  # Rotate the motor backwards.
+  # See Motor#forward and Motor#run.
+  def backward(options)
+    debug(options, :backward)
+    options[:direction] = -1
+    return run(options)
+  end
+  
+  # Return the current state of the motor as a hash.
+  # See NXTComm#get_output_state for info on what data is available here.
+  def read_state
+    @log.debug(:read_state) { "getting state"}
+    state = @nxt.get_output_state(@port)
+    @log.debug(:read_state) { "got state" }
+    
+    debug(state, :state)
+    
+    return state
+  end
+  
+  
+  ### low level commands ######################################################
+  
+  # Low-level command for initiating motor rotation.
+  # Options is a hash with the following keys:
+  # [+:power+] Power from 0 to 100. Default is 25.
+  # [+:time+] Maximum time to run the motor in seconds. 
+  #           By default there is no time limit.
+  #           If :degrees is also specified then the motor
+  #           will only turn as far as :degrees and will stop and
+  #           wait out the remaining :time has expired.
+  # [+:regulate+] False to disable power regulation. It is true (i.e. on)
+  #           by default.
+  # [+:degrees+] The maximum tachometer degrees to turn before automatically
+  #           stopping. Use negative values for backward movement (need to
+  #           double check that this is in fact true)
+  # [+:direction+] Direction in which the motor should move. 1 for forward,
+  #           -1 for backward. The default is 1 (i.e. forward).
+  # [+:wait_until_complete+] If true, the motor will block further commands
+  # 					until this command is complete. This is true by default when
+  # 					:degrees or :time is specified, false by default otherwise.
+  # 					NOTE: currently this setting is always on and cannot be turned off
+  # 					when :time is specified... this will probably be fixed in the future
+  # [+:brake_on_stop+] If true, the motor will try to hard brake when the
+  # 					command completes (otherwise when the command finishes the
+  # 					motor may continue to coast for a while -- especially at higher
+  # 					power levels). This is true by default when :degrees or :time
+  # 					is specified, false by default otherwise.
+  # 
+  # 
+  # ====Examples:
+  # 
+  # Rotate backward up to 90 degrees:
+  # 
+  #   m.run(:degrees => 90, :direction => -1)
+  # 
+  # Rotate forward for 8 seconds at 100% power:
+  # 
+  #   m.run(:time => 8, :power => 100)
+  # 
+  # Forward for 3 seconds up to 180 degrees at 50% power. If the 180 degree 
+  # rotation takes only 1 second to complete, the motor will
+  # sit there and wait out the full 3 seconds anyway:
+  # 
+  #   m.run(:power => 50, :degrees => 180, :time => 3)
+  # 
+  # Rotate forward indefinitely (until Motor#stop is called).
+  # 
+  #   m.run
+  #   
+  def run(options)
+    debug(options, :run)
+  
+    if options[:power]
+      power = options[:power].to_i.abs
+    else
+      power = 25
+    end
+    
+    time = options[:time] || nil
+    regulate = options[:regulate] || true
+    regulation_mode = options[:regulation_mode] || "speed"
+    degrees = options[:degrees] || 0
+    ratio = options[:ratio] || self.ratio
+    direction = options[:direction] || 1 # 1 is forward, -1 is backward
+
+    brake_on_stop = options.has_key?(:time) || options.has_key?(:degrees)
+    wait_until_complete = options.has_key?(:time) || options.has_key?(:degrees)
+    
+    brake_on_stop = options[:brake_on_stop] if options.has_key?(:brake_on_stop)
+
+    wait_until_complete = options[:wait_until_complete] if options.has_key?(:wait_until_complete)
+    # FIXME: wait_until_complete MUST be true if a time period is specified, otherwise we have no way of
+    # 				enforcing the time limit (this is a problem with the way threading is implemented...)
+    wait_until_complete = true if options.has_key?(:time)
+    
+    power = direction * power
+    
+    mode = NXTComm::MOTORON
+    mode |= NXTComm::BRAKE if brake_on_stop
+    mode |= NXTComm::REGULATED if regulate
+    
+    if regulate
+      case regulation_mode
+	      when "idle"
+	        regulation_mode = NXTComm::REGULATION_MODE_IDLE
+        when "speed"
+    	    regulation_mode = NXTComm::REGULATION_MODE_MOTOR_SPEED
+	      when "sync"
+	        regulation_mode = NXTComm::REGULATION_MODE_MOTOR_SYNC
+      end
+    else
+    	regulation_mode = NXTComm::REGULATION_MODE_IDLE
+    end
+
+    @log.debug(:run) {"sending run command"}
+    @nxt.set_output_state(@port, power, mode, regulation_mode, ratio, NXTComm::MOTOR_RUN_STATE_RUNNING, degrees)
+  
+    if time.nil?
+    	if wait_until_complete
+	      @log.debug(:run) {"sleeping until run_state is idle"}
+	      until read_state[:run_state] == NXTComm::MOTOR_RUN_STATE_IDLE
+	        sleep(POLL_INTERVAL)
+	        @log.debug(:run) {"checking run_state again"}
+	      end
+	      @log.debug(:run) {"run_state is idle"}
+    	end
+    else
+      @log.debug(:run) {"waiting #{time} seconds until stop"}
+      sleep(time)
+      @log.debug(:run) {"stopping"}
+      self.stop
+      @log.debug(:run) {"stopped"}
+    end
+  end
+  
+  # Stop movement.
+  def stop
+    debug(nil, :stop)
+    @nxt.set_output_state(@port, 100, NXTComm::BRAKE, NXTComm::REGULATION_MODE_MOTOR_SPEED, 100, NXTComm::MOTOR_RUN_STATE_IDLE, 0)
+  end
+  
+  # Resets the motor's tachometer movement count (i.e. +:degree_count+ in Motor#state).
+  def reset_tacho
+    @log.debug(:reset_tacho) { "resetting tacho" }
+    @nxt.reset_motor_position(@port, false)
+    @log.debug(:reset_tacho) { "reset tacho" }
+  end
+  
+  private
+    def formalize_motor_port_name(port)
+      port = port.downcase.intern if port.kind_of? String
+    
+      if port.kind_of? Symbol
+        case port
+          when :a then return NXTComm::MOTOR_A
+          when :b then return NXTComm::MOTOR_B
+          when :c then return NXTComm::MOTOR_C
+        end
+      elsif [NXTComm::MOTOR_A, NXTComm::MOTOR_B, NXTComm::MOTOR_C].include? port
+        return port
+      else
+        raise "'#{port}' is not a valid motor port"
+      end
+    end
+
+end