lego-nxt 0.2.0

data/lib/nxt/connectors/input/ultrasonic.rb

@@ -0,0 +1,11 @@
+module NXT
+  module Connector
+    module Input
+      class Ultrasonic
+        def initialize(port)
+          @port = port
+        end
+      end
+    end
+  end
+end

data/lib/nxt/connectors/output/motor.rb

@@ -0,0 +1,116 @@
+module NXT
+  module Connector
+    module Output
+      class Motor
+        include NXT::Command::Output
+        extend NXT::Utils::Accessors
+
+        DURATION_TYPE = [:seconds, :degrees, :rotations].freeze
+        DURATION_AFTER = [:coast, :brake].freeze
+        DIRECTION = [:forwards, :backwards].freeze
+
+        attr_accessor :port, :interface
+
+        attr_combined_accessor :duration, 0
+        attr_combined_accessor :duration_type, :seconds
+        attr_combined_accessor :duration_after, :stop
+        attr_combined_accessor :direction, :forwards
+
+        attr_setter :direction, is_key_in: DIRECTION
+
+        def initialize(port, interface)
+          @port = port
+          @interface = interface
+        end
+
+        def duration=(duration, options = {})
+          raise TypeError.new('Expected duration to be a number') unless duration.is_a?(Integer)
+          @duration = duration
+
+          if options.include?(:type)
+            type = options[:type]
+
+            unless DURATION_TYPE.include?(type)
+              raise TypeError.new("Expected duration type to be one of: :#{DURATION_TYPE.join(', :')}")
+            end
+
+            @duration_type = type
+          else
+            @duration_type = :seconds
+          end
+
+          if options.include?(:after)
+            if @duration_type == :seconds
+              after = options[:after]
+
+              unless DURATION_AFTER.include?(after)
+                raise TypeError.new("Expected after option to be one of: :#{DURATION_AFTER.join(', :')}")
+              end
+
+              @duration_after = after
+            else
+              raise TypeError.new('The after option is only available when the unit duration is in seconds.')
+            end
+          else
+            @duration_after = :stop
+          end
+
+          case @duration_type
+          when :rotations
+            self.tacho_limit = @duration * 360
+          when :degrees
+            self.tacho_limit = @duration
+          end
+
+          self
+        end
+
+        def forwards
+          self.direction = :forwards
+          self
+        end
+
+        def backwards
+          self.direction = :backwards
+          self
+        end
+
+        def stop(type = :coast)
+          self.power = 0
+          self.mode = :coast
+
+          self.move
+        end
+
+        # takes block for response, or can return the response instead.
+        def move
+          response_required = false
+
+          if self.duration > 0 && self.duration_type != :seconds
+            response_required = true
+          end
+
+          set_output_state(response_required)
+
+          if self.duration > 0 && self.duration_type == :seconds
+            sleep(self.duration)
+            self.reset
+            self.stop(self.duration_after)
+          else
+            self.reset
+          end
+        end
+
+        def reset
+          self.duration = 0
+          self.direction = :forwards
+          self.power = 75
+          self.mode = :motor_on
+          self.regulation_mode = :idle
+          self.run_state = :running
+          self.tacho_limit = 0
+        end
+      end
+    end
+  end
+end

data/lib/nxt/exceptions.rb

@@ -0,0 +1,26 @@
+module NXT
+  module Exceptions
+    # Raised when a class has not implemented a method from the base class
+    # that is required to be overriden.
+    class InterfaceNotImplemented < NotImplementedError; end
+
+    # Raised when an invalid interface is attempted to be constructed.
+    class InvalidInterfaceError < TypeError; end
+
+    # Raised when a port is attempted to be named when it already has been.
+    class PortTakenError < TypeError; end
+
+    # Raised when an invalid name is attempted to be given to a port.
+    class InvalidIdentifierError < TypeError; end
+
+    # Raised when the device file attempted to be used for communication is
+    # for whatever reason does not exist or is not correct.
+    class InvalidDeviceError < TypeError; end
+
+    # Raised when communication with a Serial Port connection fails.
+    class SerialPortConnectionError < RuntimeError; end
+
+    # Raised when communication with a USB Port connection fails.
+    class UsbConnectionError < RuntimeError; end
+  end
+end

data/lib/nxt/interfaces/base.rb

@@ -0,0 +1,26 @@
+module NXT
+  module Interface
+    class Base
+      def send_and_receive(msg, response_required = true)
+        unless response_required
+          msg[0] = msg[0] | 0x80
+        end
+
+        self.send(msg)
+
+        if response_required
+          response = self.receive
+          response
+        end
+      end
+
+      def send
+        raise InterfaceNotImplemented.new('The #send method must be implemented.')
+      end
+
+      def receive
+        raise InterfaceNotImplemented.new('The #receive method must be implemented.')
+      end
+    end
+  end
+end

data/lib/nxt/interfaces/serial_port.rb

@@ -0,0 +1,76 @@
+require 'serialport'
+
+module NXT
+  module Interface
+    class SerialPort < Base
+      include NXT::Exceptions
+
+      attr_reader :dev
+
+      BAUD_RATE = 57600
+      DATA_BITS = 8
+      STOP_BITS = 1
+      PARITY = ::SerialPort::NONE
+      READ_TIMEOUT = 5000
+
+      def initialize(dev)
+        self.dev = (dev)
+      end
+
+      def dev=(dev)
+        raise InvalidDeviceError unless File.exists?(dev)
+        @dev = dev
+      end
+
+      def connect
+        @connection = ::SerialPort.new(@dev, BAUD_RATE, DATA_BITS, STOP_BITS, PARITY)
+
+        if @connection.nil?
+          raise SerialPortConnectionError.new("Could not establish a SerialPort connection to #{dev}")
+        end
+
+        @connection.flow_control = ::SerialPort::HARD
+        @connection.read_timeout = READ_TIMEOUT
+
+        @connection
+      rescue ArgumentError
+        raise SerialPortConnectionError.new("The #{dev} device is not a valid SerialPort")
+      end
+
+      def disconnect
+        @connection.close if self.connected?
+      end
+
+      def connected?
+        @connection && !@connection.closed?
+      end
+
+      def send(msg)
+        # The expected data package structure for NXT Bluetooth communication is:
+        #
+        #     [Length Byte 1, Length Byte 2, Command Type, Command, ...]
+        #
+        # So here we calculate the two leading length bytes, and rely on the
+        # passed in argument to give us the rest of the message to send.
+        #
+        # Note that the length is stored in Little Endian ie. LSB -> MSB
+        #
+        # Reference: Appendix 1, Page 22
+        msg = [(msg.length & 255), (msg.length >> 8)] + msg
+
+        msg.each do |b|
+          @connection.putc(b)
+        end
+      end
+
+      def receive
+        # This gets the length of the received data from the header that was sent
+        # to us. We unpack it, as it's stored as a 16-bit Little Endian number.
+        #
+        # Reference: Appendix 1, Page 22
+        length = @connection.sysread(2)
+        @connection.sysread(length.unpack('v')[0])
+      end
+    end
+  end
+end

data/lib/nxt/interfaces/usb.rb

@@ -0,0 +1,51 @@
+require 'libusb'
+
+module NXT
+  module Interface
+    class Usb < Base
+      include NXT::Exceptions
+
+      ID_VENDOR_LEGO = 0x0694
+      ID_PRODUCT_NXT = 0x0002
+      OUT_ENDPOINT = 0x01
+      IN_ENDPOINT = 0x82
+      TIMEOUT = 10000
+      READSIZE = 64
+      INTERFACE = 0
+
+      def connect
+        @usb_context = LIBUSB::Context.new
+        @dev = @usb_context.devices(idVendor: ID_VENDOR_LEGO, idProduct: ID_PRODUCT_NXT).first
+
+        if @dev.nil?
+          raise UsbConnectionError.new("Could not find NXT attached as USB device")
+        end
+
+        @connection = @dev.open
+        @connection.claim_interface(INTERFACE)
+
+        @connection
+      end
+
+      def disconnect
+        if self.connected?
+          @connection.release_interface(INTERFACE)
+          @connection.close
+        end
+      end
+
+      def connected?
+        # FIXME: How do we check if the device is connected?
+        @connection
+      end
+
+      def send(msg)
+        @connection.bulk_transfer(endpoint: OUT_ENDPOINT, dataOut: msg.pack('C*'), timeout: TIMEOUT)
+      end
+
+      def receive
+        @connection.bulk_transfer(endpoint: IN_ENDPOINT, dataIn: READSIZE, timeout: TIMEOUT)
+      end
+    end
+  end
+end

data/lib/nxt/nxt_brick.rb

@@ -0,0 +1,153 @@
+# This class is the entry point for end-users creating their own list of
+# commands to execute remotely on a Lego NXT brick.
+#
+# An instance of this class provides all the endpoints necessary to:
+#
+# * educate the API on the connected input and output devices; and,
+# * access these input and output devices and run commands using them.
+#
+# @example Creating an instance using a block, with one motor output.
+#
+#   NXTBrick.new(interface) do |nxt|
+#     nxt.add_motor_output(:a, :front_left)
+#   end
+#
+# @example Creating an instance without a block, with one motor and one light sensor.
+#
+#   nxt = NXTBrick.new(interface)
+#   nxt.add_motor_output(:a, :front_left)
+#   # ...
+#   nxt.disconnect
+class NXTBrick
+  include NXT::Exceptions
+
+  # An enumeration of possible ports, both input and output, that the NXT brick
+  # can have connectors attached to.
+  PORTS = [:a, :b, :c, :one, :two, :three, :four]
+
+  # Get the instance of the interface that this runner class is using to connect
+  # to the NXT brick.
+  attr_accessor :interface
+
+  # Accessors for output ports on the NXT brick. These will be populated with
+  # the appropriate instances of their respective output connectors.
+  attr_reader :a, :b, :c
+
+  # Accessors for input ports on the NXT brick. These will be populated with the
+  # appropriate instances of their respective input connectors.
+  attr_reader :one, :two, :three, :four
+
+  # We mandate that all added port connections have an identifier associated
+  # with it. This is so that code is not fragile when port swapping needs to
+  # be done.
+  attr_reader :port_identifiers
+
+  def initialize(interface_type, *interface_args)
+    @port_identifiers = {}
+    interface_type = interface_type.to_s.classify
+
+    unless NXT::Interface.constants.include?(interface_type.to_sym)
+      raise InvalidInterfaceError.new("There is no interface of type #{interface_type}.")
+    end
+
+    self.interface = NXT::Interface.const_get(interface_type).new(*interface_args)
+
+    if block_given?
+      begin
+        self.connect
+        yield(self)
+      rescue Exception => e
+        binding.pry
+      ensure
+        self.disconnect
+      end
+    end
+  end
+
+  # Connect using the given interface to the NXT brick.
+  def connect
+    self.interface.connect
+  end
+
+  # Close the connection to the NXT brick, and dispose of any resources that
+  # this instance of NXTBrick is using. Any commands run against this runner
+  # after calling disconnect will fail.
+  def disconnect
+    self.interface.disconnect
+  end
+
+  # Add a new connector instance, binding a specific identifier to the given
+  # port.
+  #
+  # If the given port already is bound, an exception will be thrown. The
+  # instance given though can be of any class, presuming it talks the
+  # correct language.
+  #
+  # @param Symbol port The port to bind to.
+  # @param Symbol identifier The identifier to associate with this port.
+  # @param Class klass The Class to instantiate as the instance of this
+  #                    port. There is no limitation on what type this can
+  #                    be, though it must be able to hook in correctly
+  #                    with the NXT library.
+  def add(port, identifier, klass)
+    raise TypeError.new('Expected port to be a Symbol') unless port.is_a?(Symbol)
+    raise TypeError.new('Expected identifier to be a Symbol') unless identifier.is_a?(Symbol)
+    raise TypeError.new('Expected klass to be a Class') unless klass.is_a?(Class)
+
+    unless PORTS.include?(port)
+      raise TypeError.new("Expected port to be one of: :#{PORTS.join(', :')}")
+    end
+
+    port_variable = :"@#{port}"
+
+    if !self.respond_to?(identifier)
+      # Makes a new instance of the class and pushes it into our instance variable
+      # for the given port.
+      self.instance_variable_set(port_variable, klass.new(port, self.interface))
+
+      # Given that that succeeded, all that remains is to add the identifier
+      # to our lookup Hash. We'll use this Hash later on within method_missing.
+      @port_identifiers[identifier] = port
+
+      # Define a method on the eigenclass of this instance.
+      (class << self; self; end).send(:define_method, identifier) do
+        self.instance_variable_get(port_variable)
+      end
+    else
+      if !self.instance_variable_get(port_variable).nil?
+        raise PortTakenError.new("Port #{port} is already set, call remove first")
+      else
+        raise InvalidIdentifierError.new("Cannot use identifier #{identifier}, a method on #{self.class} is already using it.")
+      end
+    end
+  end
+
+  # Remove the assigned (if any) connector instance from the given
+  # identifier.
+  #
+  # @param Symbol identifier The identifier to search for and remove.
+  def remove(identifier)
+    raise TypeError.new('Expected identifier to be a Symbol') unless identifier.is_a?(Symbol)
+    !!@port_identifiers.delete(identifier)
+  end
+
+  # This will dynamically add methods like:
+  #
+  # * add_light_input
+  # * add_motor_output
+  # * add_ultrasonic_input
+  #
+  # This means they don't have to provide the class each and every time. For
+  # connectors they have added themselves, it's likely best to use the
+  # {#add} method.
+  NXT::Connector.constants.each do |type_const|
+    NXT::Connector.const_get(type_const).constants.each do |const|
+      # We don't use a splat here for the args, because that way when
+      # people don't pass in the correct number of params, it says helpfully
+      # '1 of 2' args passed (or something similar).
+      define_method("add_#{const.to_s.underscore}_#{type_const.to_s.underscore}") do |port, identifier|
+        self.add(port, identifier, NXT::Connector.const_get(type_const).const_get(const))
+      end
+    end
+  end
+end