lego-nxt 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e972fae0b3659e85c16a77bf735809a97b0c9bf0
+  data.tar.gz: bc3d2844376e99a2f4fb55f3001beef1a9a36ab1
+SHA512:
+  metadata.gz: e08a116ed02b6d2a38856b29e6e23489543bdedcfcf3ade4c0f33c58b835c31f0a1e9ddea0d78cabadca5f8a8829e7c8553b733cc3e39001b9462b15b3b766b1
+  data.tar.gz: f90c8c66c8f1390d5ed6ef4d41d7ea7268c356de0ee656e35e5fc312013a2308e942b21c2e6c610211d3d97aa5f03ac7fb00f09838375a344239cadd28b441be

data/README.md

@@ -0,0 +1,107 @@
+# Lego NXT
+
+Control a Lego NXT 2.0 brick using Ruby code. This library works by piping commands over a serialport connection to the brick, allowing you to write Ruby scripts to control your bot. This means you can use both the Bluetooth and USB serial ports provided on the brick as interfaces within your code.
+
+This project used to be based on "ruby-nxt", and Tony Buser's subsequent rewrite "nxt". It is now a complete rewrite, based heavily in some parts on the aforesaid projects internally, but with a brand new external API that should prove cleaner and easier to work with.
+
+This code implements direct command, as outlined in "Appendix 2-LEGO MINDSTORMS NXT Direct Commands.pdf". Not all functionality is implemented yet!
+
+## Getting Started
+
+### Connect to Your NXT Brick
+
+In order to start coding with your NXT, you'll need to set up either a USB or Bluetooth connection to it. Follow one of the below sets of steps; if you go for a Bluetooth connection, you'll need to remember the `/dev/*` address you end up using, as you'll need to provide it when making a connection with this library.
+
+### Connecting Via USB
+
+Simply plug in the NXT, and that's it! This library will take care of enumerating the USB host devices to find the NXT device for you, no effort required on your behalf!
+
+#### Connecting Via Bluetooth
+
+##### Linux
+
+Make sure you have the `bluez` package installed, which should include the `rfcomm` and `hcitool` commands. We start by searching for the MAC address of our NXT:
+
+```sh
+$ hcitool scan
+  Scanning ...
+      90-8E-E0-C1-2A-7B       NXT
+```
+
+Then open the `/etc/bluetooth/rfcomm.conf` file and add an entry as follows:
+
+```
+rfcomm0 {
+  bind yes;
+  # Bluetooth address of the device
+  device 90-8E-E0-C1-2A-7B;
+  # RFCOMM channel for the connection
+  channel 1;
+  # Description of the connection
+  comment "NXT";
+}
+```
+
+If you're on a distro which has a Bluetoth daemon running automatically, you can simply restart it. For Ubuntu, that will look something like:
+
+```sh
+$ sudo /etc/init.d/bluez-utils
+```
+
+On other distros where you manage the Bluetooth daemon yourself, you'll need to do the bind calls yourself:
+
+```sh
+$ sudo rfcomm bind /dev/rfcomm0 '90-8E-E0-C1-2A-7B'
+```
+
+After that, the Bluetooth connection should be established. Check that by running the `rfcomm` command with no arguments:
+
+```sh
+$ rfcomm
+rfcomm0: 90-8E-E0-C1-2A-7B channel 1 clean
+```
+
+The NXT should now be accessible from `/dev/rfcomm0`!
+
+##### Mac OS X
+
+Turn on the NXT and make sure Bluetooth is turned on. Click the bluetooth icon in the menubar of your Mac and select "Setup bluetooth device". It will prompt you for a device type; choose "Any device". Select the NXT from the list and click continue.
+
+The NXT will beep and ask for a passkey. Choose `1234` and press orange button. Enter the `1234` passcode on your Mac when promted. The NXT will beep again; press the orange button to use `1234` again.
+
+Your Mac will then alert you that "There were no supported services found on your device". Ignore and click "Continue", followed by "Quit".
+
+Now click the Bluetooth icon and select "Open bluetooth preferences"; you should see the NXT listed. Select it, then click "Edit Serial Ports".
+It should show `NXT-DevB-1`; if not, click "Add", and use:
+
+```
+Port Name: NXT-DevB-1
+Device Service: Dev B
+Port type: RS-232
+```
+
+Click "Apply". The NXT should now be accessible from `/dev/tty.NXT-DevB-1`!
+
+## Documentation and Examples
+
+The NXT project has been heavily documented using nice, clean, human readable markdown. YARD is used to generated the docs, and the options have been included in our `.yardopts` file, so simply run a YARD server to read them:
+
+```sh
+$ yard server
+```
+
+This documents the API, both internal and external. For bite-sized chunks of NXT code that is much more appropriate for beginners, [have a look at the examples](https://github.com/nathankleyn/nxt/tree/master/examples).
+
+In addition to this, you might find the tests quite helpful. There are currently only RSpec unit tests, which can be found in the [`spec`](spec) directory; the plan is to add some decent feature tests soon.
+
+## License
+
+The MIT License
+
+Copyright (c) 2013 Nathan Kleyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,35 @@
+require 'rake'
+require 'rake/clean'
+require 'rdoc/task'
+require 'rspec/core/rake_task'
+
+RDoc::Task.new do |rdoc|
+  files = ['README.markdown', 'lib/**/*.rb']
+  rdoc.rdoc_files.add(files)
+  rdoc.main = 'README.markdown'
+  rdoc.title = 'ruby_events Docs'
+  rdoc.rdoc_dir = 'doc/rdoc'
+  rdoc.options << '--line-numbers'
+end
+
+RSpec::Core::RakeTask.new(:spec)
+
+desc 'NXT related tasks'
+namespace :nxt do
+  desc 'Detect a connected NXT brick within /dev.'
+  task :detect do
+    unless $DEV ||= ENV['NXT'] || ENV['DEV']
+      begin
+        devices = Dir['/dev/*NXT*']
+        if devices.size > 0
+          $DEV = devices[0]
+          puts "Detected a NXT brick at '#{$DEV}'."
+        else
+          puts 'Could not detect any connected NXT bricks.'
+        end
+      rescue
+        # FIXME: The /dev directory isn't there, possibly running on Windows.
+      end
+    end
+  end
+end

data/lib/nxt.rb

@@ -0,0 +1,27 @@
+$:.unshift(File.dirname(__FILE__))
+
+require 'active_support/inflector'
+
+require 'nxt/patches/module'
+
+require 'nxt/exceptions'
+
+require 'nxt/interfaces/base'
+require 'nxt/interfaces/usb'
+require 'nxt/interfaces/serial_port'
+
+require 'nxt/commands/base'
+require 'nxt/commands/input'
+require 'nxt/commands/output'
+require 'nxt/commands/program'
+require 'nxt/commands/sound'
+require 'nxt/commands/tone'
+
+require 'nxt/connectors/input/color'
+require 'nxt/connectors/input/touch'
+require 'nxt/connectors/input/ultrasonic'
+require 'nxt/connectors/output/motor'
+
+require 'nxt/nxt_brick'
+
+require 'pry'

data/lib/nxt/commands/base.rb

@@ -0,0 +1,36 @@
+module NXT
+  module Command
+    module Base
+      private
+
+      COMMAND_TYPES = {
+        direct: 0x00,
+        system: 0x01,
+        reply: 0x02
+      }.freeze
+
+      PORTS = {
+        a: 0x00,
+        b: 0x01,
+        c: 0x02,
+        one: 0x00,
+        two: 0x01,
+        three: 0x02,
+        four: 0x03,
+        all: 0xFF
+      }
+
+      def send_and_receive(command_identifier, payload = [], response_required = true)
+        @interface.send_and_receive([
+          command_type,
+          command_identifier,
+          port_as_byte(self.port)
+        ] + payload, response_required)
+      end
+
+      def port_as_byte(port)
+        PORTS[port]
+      end
+    end
+  end
+end

data/lib/nxt/commands/input.rb

@@ -0,0 +1,89 @@
+require 'nxt/utils/accessors'
+
+module NXT
+  module Command
+    # An implementation of all the input related NXT commands:
+    #
+    # * SETINPUTMODE
+    # * GETINPUTVALUES
+    # * RESETINPUTSCALEDVALUE
+    #
+    # This class can also be used to talk to other third-party accessories
+    # connected in the input ports on the NXT brick.
+    module Input
+      include NXT::Command::Base
+      extend NXT::Utils::Accessors
+
+      COMMAND_IDENTIFIER = {
+        set_input_mode: 0x05,
+        get_input_values: 0x07,
+        reset_input_scaled_value: 0x08
+      }.freeze
+
+      # The sensor type enum. This is a list of possible values when setting the
+      # sensor type byte.
+      #
+      # Reference: Appendix 2, Page 7
+      SENSOR_TYPE = {
+        no_sensor: 0x00,
+        switch: 0x01,
+        temperature: 0x02,
+        reflection: 0x03,
+        angle: 0x04,
+        light_active: 0x05,
+        light_inactive: 0x06,
+        sound_db: 0x07,
+        sound_dba: 0x08,
+        custom: 0x09,
+        lowspeed: 0x0A,
+        lowspeed_9v: 0x0B,
+        no_of_sensor_types: 0x0C
+      }.freeze
+
+      # The sensor mode enum. This is a list of possible values when setting the
+      # sensor mode byte.
+      #
+      # Reference: Appendix 2, Page 7
+      SENSOR_MODE = {
+        raw: 0x00,
+        boolean: 0x20,
+        transition_cnt: 0x40,
+        period_counter: 0x60,
+        pct_full_scale: 0x80,
+        celsius: 0xA0,
+        fahrenheit: 0xC0,
+        angle_steps: 0xE0,
+        slope: 0x1F,
+        mode_mask: 0XE0
+      }.freeze
+
+      attr_combined_accessor :sensor_type, :no_sensor
+      attr_combined_accessor :sensor_mode, :raw
+
+      attr_setter :sensor_type, is_key_in: SENSOR_TYPE
+      attr_setter :sensor_mode, is_key_in: SENSOR_MODE
+
+      def command_type
+        COMMAND_TYPES[:direct]
+      end
+
+      def set_input_mode(response_required = false)
+        send_and_receive(COMMAND_IDENTIFIER[:set_input_mode], [
+          self.power,
+          SENSOR_TYPE[self.sensor_type],
+          SENSOR_MODE[self.sensor_mode]
+        ], response_required)
+      end
+
+      def get_input_values
+        # TODO: Parse this response and return hash or something similar.
+        send_and_receive(COMMAND_IDENTIFIER[:get_input_values])
+      end
+
+      def reset_input_scaled_value
+        # TODO: Parse this response and return hash or something similar.
+        send_and_receive(COMMAND_IDENTIFIER[:reset_input_scaled_value])
+      end
+    end
+  end
+end

data/lib/nxt/commands/output.rb

@@ -0,0 +1,110 @@
+require 'nxt/utils/accessors'
+
+module NXT
+  module Command
+    # An implementation of all the output related NXT commands:
+    #
+    # * SETOUTPUTSTATE
+    # * GETOUTPUTSTATE
+    #
+    # This is used predominantly to interface with the servo-motor connectors
+    # that come prepackaged with NXT kits.
+    #
+    # This class can also be used to talk to other third-party accessories
+    # connected in the output ports on the NXT brick.
+    module Output
+      include NXT::Command::Base
+      extend NXT::Utils::Accessors
+
+      COMMAND_IDENTIFIER = {
+        set_output_state: 0x04,
+        get_output_state: 0x06
+      }.freeze
+
+      # The mode enum. This is a list of possible values when setting the mode
+      # byte.
+      #
+      # Reference: Appendix 2, Page 6
+      MODE = {
+        # Motor will rotate freely.
+        # NOTE: This is not documented in the Appendixes.
+        coast: 0x00,
+        # Turn on the specified motor.
+        motor_on: 0x01,
+        # Use run/brake instead of run/float in PWM. This means the voltage is
+        # not allowed to float between PWM pulses, improving accuracy at the
+        # expense of greater power usage.
+        brake: 0x02,
+        # Turns on the regulation. This is required when setting a regulation
+        # mode setting.
+        regulated: 0x04
+      }.freeze
+
+      # The regulation mode enum. This is a list of possible values when
+      # setting the regulation mode byte.
+      #
+      # Reference: Appendix 2, Page 6
+      REGULATION_MODE = {
+        # No regulation will be enabled.
+        idle: 0x00,
+        # Power control will be enabled on specific output.
+        motor_speed: 0x01,
+        # Synchronisation will be enabled. This requires two output ports to
+        # have this enabled before it will work.
+        motor_sync: 0x02
+      }.freeze
+
+      # The run state enum. This is a list of possible values when setting the
+      # run state byte.
+      #
+      # Reference: Appendix 2, Page 6
+      RUN_STATE = {
+        # Output will be idle.
+        idle: 0x00,
+        # Output will ramp-up to the desired speed.
+        ramp_up: 0x10,
+        # Output will be running.
+        running: 0x20,
+        # Output will ramp-down to the desired speed.
+        ramp_down: 0x40
+      }.freeze
+
+      attr_combined_accessor :power, 75
+      attr_combined_accessor :mode, :motor_on
+      attr_combined_accessor :regulation_mode, :idle
+      attr_combined_accessor :run_state, :running
+      attr_combined_accessor :tacho_limit, 0
+
+      attr_setter :power, is: Integer
+      attr_setter :mode, is_key_in: MODE
+      attr_setter :regulation_mode, is_key_in: REGULATION_MODE
+      attr_setter :run_state, is_key_in: RUN_STATE
+      attr_setter :tacho_limit, is: Integer
+
+      def command_type
+        COMMAND_TYPES[:direct]
+      end
+
+      def set_output_state(response_required = false)
+        # Pack this value into a 32-bit unsigned little-endian binary string,
+        # then unpack it into 4 8 bit unsigned integer chunks. We are
+        # converting the passed in value to a little endian, unsigned long
+        # value.
+        tacho_limit_as_bytes = [self.tacho_limit].pack('V').unpack('C4')
+
+        send_and_receive(COMMAND_IDENTIFIER[:set_output_state], [
+          self.power,
+          MODE[self.mode],
+          REGULATION_MODE[self.regulation_mode],
+          0, # turn ratio
+          RUN_STATE[self.run_state]
+        ] + tacho_limit_as_bytes, response_required)
+      end
+
+      def get_output_state
+        # TODO: Parse this response and return hash or something similar.
+        send_and_receive(COMMAND_IDENTIFIER[:get_output_state])
+      end
+    end
+  end
+end

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

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

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

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