lego-nxt 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: e972fae0b3659e85c16a77bf735809a97b0c9bf0
-  data.tar.gz: bc3d2844376e99a2f4fb55f3001beef1a9a36ab1
+SHA256:
+  metadata.gz: f05dd5e79c55b8b179ff31bec9197f5ba3a5e671c1d09fd59123e6cc3fb944f5
+  data.tar.gz: 9b3bcfe2965efa57b1b972d3cdc1752a736e1a515dd48b98ce529831b49f204b
 SHA512:
-  metadata.gz: e08a116ed02b6d2a38856b29e6e23489543bdedcfcf3ade4c0f33c58b835c31f0a1e9ddea0d78cabadca5f8a8829e7c8553b733cc3e39001b9462b15b3b766b1
-  data.tar.gz: f90c8c66c8f1390d5ed6ef4d41d7ea7268c356de0ee656e35e5fc312013a2308e942b21c2e6c610211d3d97aa5f03ac7fb00f09838375a344239cadd28b441be
+  metadata.gz: 718bebac8ff71116d2cc12271cac115697caa88edf1387d4689591a017be8e5e78d2eaf911880691437250cb7e07a2aa5839bbada3f6c9842e0f17d720b17ce1
+  data.tar.gz: 1aaefd9d5090f06a656067b4379202368dde9a96b995e8d5fc2ded602d72d5d50592fa25e3a01c91cbfcd351cb9ceb64190f69a7097be28719e8108374b86805

data/README.md

@@ -1,6 +1,8 @@
-# Lego NXT
+# Lego NXT [![Build Status](https://github.com/nathankleyn/lego-nxt/workflows/Tests/badge.svg)](https://github.com/nathankleyn/lego-nxt/actions?query=workflow%3ATests) [![Coverage Status](https://coveralls.io/repos/github/nathankleyn/attr_combined_accessor/badge.svg?branch=master)](https://coveralls.io/github/nathankleyn/lego-nxt?branch=master) [![RubyGems Version](https://img.shields.io/gem/v/lego-nxt.svg)](https://rubygems.org/gems/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 gem is under heavy development!** A lot of the below code may not work, and is certainly not guranteed to be reliable if it does! If you need to base a working project on this, I recommend [going back to the `ruby-nxt` gem this work is inspired by](https://github.com/zuk/ruby-nxt) for the time being.
+
+Control a Lego NXT 2.0 brick using Ruby code. This library works by piping commands over a Bluetooth or USB connection to the brick, allowing you to write Ruby scripts to control your NXT brick.
 
 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.
 
@@ -8,11 +10,21 @@ This code implements direct command, as outlined in "Appendix 2-LEGO MINDSTORMS
 
 ## Getting Started
 
+### Installing This Library
+
+Install the gem:
+
+```sh
+gem install lego-nxt
+```
+
+Add it as a Bundler dependency as you see fit!
+
 ### 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
+#### 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!
 
@@ -96,12 +108,4 @@ In addition to this, you might find the tests quite helpful. There are currently
 
 ## 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.
+This project is licensed [via MIT license](LICENSE).

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rake'
 require 'rake/clean'
 require 'rdoc/task'
@@ -18,18 +20,13 @@ 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
+    unless ENV['NXT'] || ENV['DEV']
+      raise "/dev not fount, please ensure you're using a *nix system." unless Dir.exist?('/dev')
+
+      devices = Dir['/dev/*NXT*']
+      raise 'Could not detect any connected NXT bricks.' if devices.empty?
+
+      puts "Detected a NXT brick at '#{devices.first}'."
     end
   end
 end

data/lib/lego_nxt.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+require 'active_support/inflector'
+
+require 'nxt/patches/module'
+require 'nxt/patches/string'
+
+require 'nxt/exceptions'
+
+require 'nxt/utils/assertions'
+require 'nxt/utils/accessors'
+
+require 'nxt/interface/base'
+require 'nxt/interface/usb'
+require 'nxt/interface/serial_port'
+
+require 'nxt/protocols/i2c'
+
+require 'nxt/commands/base'
+require 'nxt/commands/input'
+require 'nxt/commands/low_speed'
+require 'nxt/commands/output'
+require 'nxt/commands/program'
+require 'nxt/commands/sound'
+require 'nxt/commands/tone'
+
+require 'nxt/connector/input/base'
+require 'nxt/connector/input/color'
+require 'nxt/connector/input/touch'
+require 'nxt/connector/input/ultrasonic'
+require 'nxt/connector/output/base'
+require 'nxt/connector/output/motor'
+
+require 'nxt/nxt_brick'

data/lib/nxt/commands/base.rb

@@ -1,5 +1,14 @@
+# frozen_string_literal: true
+
 module NXT
   module Command
+    # The base implementation of all commands, providing low-level details that
+    # are consistent across all supported types. These are things such as:
+    #
+    # * Errors.
+    # * Sending and receiving of responses.
+    # * Addressing the port safely.
+    # * Command types.
     module Base
       private
 
@@ -18,18 +27,58 @@ module NXT
         three: 0x02,
         four: 0x03,
         all: 0xFF
-      }
+      }.freeze
+
+      ERRORS = {
+        'Pending communication transaction in progress' => 0x20,
+        'Specified mailbox queue is empty' => 0x40,
+        'Request failed (i.e. specified file not found)' => 0xBD,
+        'Unknown command opcode' => 0xBE,
+        'Insane packet' => 0xBF,
+        'Data contains out-of-range values' => 0xC0,
+        'Communication bus error' => 0xDD,
+        'No free memory in communication buffer' => 0xDE,
+        'Specified channel/connection is not valid' => 0xDF,
+        'Specified channel/connection not configured or busy' => 0xE0,
+        'No active program' => 0xEC,
+        'Illegal size specified' => 0xED,
+        'Illegal mailbox queue ID specified' => 0xEE,
+        'Attempted to access invalid field of a structure' => 0xEF,
+        'Bad input or output specified' => 0xF0,
+        'Insufficient memory available' => 0xFB,
+        'Bad arguments' => 0xFF
+      }.invert.freeze
+
+      def port_as_byte(port)
+        PORTS[port]
+      end
+
+      def send_and_receive(command_identifier, payload = [], response_required: true)
+        send(command_identifier, payload, response_required)
+        # We bail unless we need to wait for response.
+        return unless response_required
 
-      def send_and_receive(command_identifier, payload = [], response_required = true)
-        @interface.send_and_receive([
+        receive
+      end
+
+      def send(command_identifier, payload = [], response_required: true)
+        command_identifier |= 0x80 unless response_required
+
+        @interface.send([
           command_type,
           command_identifier,
-          port_as_byte(self.port)
-        ] + payload, response_required)
+          port_as_byte(port)
+        ] + payload)
       end
 
-      def port_as_byte(port)
-        PORTS[port]
+      def receive
+        response = @interface.receive
+
+        raise 'Not a valid response package.' unless response[0] == 0x02
+        raise 'Not a valid response to the command that was sent.' unless response[1] == command_identifier
+        raise ERRORS[response[2]] unless response[2].zero?
+
+        response[3..]
       end
     end
   end

data/lib/nxt/commands/input.rb

@@ -1,4 +1,4 @@
-require 'nxt/utils/accessors'
+# frozen_string_literal: true
 
 module NXT
   module Command
@@ -17,7 +17,10 @@ module NXT
       COMMAND_IDENTIFIER = {
         set_input_mode: 0x05,
         get_input_values: 0x07,
-        reset_input_scaled_value: 0x08
+        reset_input_scaled_value: 0x08,
+        ls_get_status: 0x0E,
+        ls_write: 0x0F,
+        ls_read: 0x10
       }.freeze
 
       # The sensor type enum. This is a list of possible values when setting the
@@ -54,7 +57,7 @@ module NXT
         fahrenheit: 0xC0,
         angle_steps: 0xE0,
         slope: 0x1F,
-        mode_mask: 0XE0
+        mode_mask: 0x00
       }.freeze
 
       attr_combined_accessor :sensor_type, :no_sensor
@@ -67,22 +70,37 @@ module NXT
         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)
+      def update_input_mode(response_required: false)
+        send_and_receive(
+          COMMAND_IDENTIFIER[:set_input_mode],
+          [
+            SENSOR_TYPE[sensor_type],
+            SENSOR_MODE[sensor_mode]
+          ],
+          response_required
+        )
       end
 
-      def get_input_values
+      def input_values
         # TODO: Parse this response and return hash or something similar.
-        send_and_receive(COMMAND_IDENTIFIER[:get_input_values])
+        send_and_receive(COMMAND_IDENTIFIER[:get_input_values], [], response_required)
       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])
+        send_and_receive(COMMAND_IDENTIFIER[:reset_input_scaled_value], [], response_required)
+      end
+
+      def ls_get_status(response_required: false)
+        send_and_receive(COMMAND_IDENTIFIER[:ls_get_status], [], response_required)
+      end
+
+      def ls_write(bytes, response_required: false)
+        send_and_receive(COMMAND_IDENTIFIER[:ls_write], bytes, response_required)
+      end
+
+      def ls_read(response_required: false)
+        send_and_receive(COMMAND_IDENTIFIER[:ls_read], [], response_required)
       end
     end
   end

data/lib/nxt/commands/low_speed.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module NXT
+  module Command
+    # An implementation of all the low speed I2C related NXT commands:
+    #
+    # * LSGETSTATUS
+    # * LSWRITE
+    # * LSREAD
+    #
+    # This class can also be used to talk to other third-party accessories
+    # connected in the input ports on the NXT brick that talk using I2C
+    # low speed master/slave communication.
+    module LowSpeed
+      include NXT::Command::Base
+      extend NXT::Utils::Accessors
+
+      COMMAND_IDENTIFIER = {
+        ls_get_status: 0x0E,
+        ls_write: 0x0F,
+        ls_read: 0x10
+      }.freeze
+
+      def command_type
+        COMMAND_TYPES[:direct]
+      end
+
+      def ls_clear_buffer
+        ls_read
+      rescue StandardError
+        nil
+      end
+
+      def ls_get_status(response_required: false)
+        send_and_receive(COMMAND_IDENTIFIER[:ls_get_status], [], response_required)
+      end
+
+      def ls_write(response_required: false)
+        send_and_receive(COMMAND_IDENTIFIER[:ls_write], [], response_required)
+      end
+
+      def ls_read(response_required: false)
+        send_and_receive(COMMAND_IDENTIFIER[:ls_read], [], response_required)
+      end
+    end
+  end
+end

data/lib/nxt/commands/output.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'nxt/utils/accessors'
 
 module NXT
@@ -85,23 +87,23 @@ module NXT
         COMMAND_TYPES[:direct]
       end
 
-      def set_output_state(response_required = false)
+      def update_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')
+        tacho_limit_as_bytes = [tacho_limit].pack('V').unpack('C4')
 
         send_and_receive(COMMAND_IDENTIFIER[:set_output_state], [
-          self.power,
-          MODE[self.mode],
-          REGULATION_MODE[self.regulation_mode],
+          power,
+          MODE[mode],
+          REGULATION_MODE[regulation_mode],
           0, # turn ratio
-          RUN_STATE[self.run_state]
+          RUN_STATE[run_state]
         ] + tacho_limit_as_bytes, response_required)
       end
 
-      def get_output_state
+      def output_state
         # TODO: Parse this response and return hash or something similar.
         send_and_receive(COMMAND_IDENTIFIER[:get_output_state])
       end

data/lib/nxt/commands/program.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+# FIXME: Create commands for program.

data/lib/nxt/commands/sound.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+# FIXME: Create commands for sound.

data/lib/nxt/commands/tone.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+# FIXME: Create commands for tone.

data/lib/nxt/connector/input/base.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module NXT
+  module Connector
+    # Holds implementations of connectors that are input based.
+    module Input
+    end
+  end
+end

data/lib/nxt/{connectors → connector}/input/color.rb

@@ -1,6 +1,9 @@
+# frozen_string_literal: true
+
 module NXT
   module Connector
     module Input
+      # Implements the "color" sensor for the NXT 2.0 module.
       class Color
         def initialize(port)
           @port = port

data/lib/nxt/{connectors → connector}/input/touch.rb

@@ -1,6 +1,9 @@
+# frozen_string_literal: true
+
 module NXT
   module Connector
     module Input
+      # Implements the "touch" sensor for the NXT 2.0 module.
       class Touch
         def initialize(port)
           @port = port

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module NXT
+  module Connector
+    module Input
+      # Implements the "ultrasonic" sensor for the NXT 2.0 module.
+      class Ultrasonic
+        include NXT::Command::Input
+        include NXT::Command::LowSpeed
+        include NXT::Utils::Assertions
+        extend NXT::Utils::Accessors
+
+        # Exception thrown by distance! when the sensor cannot determine the distance.
+        class UnmeasurableDistance < RuntimeError; end
+
+        UNIT = %i[centimeters inches].freeze
+
+        attr_accessor :port, :interface
+
+        attr_combined_accessor :unit, :centimeters
+
+        attr_setter :unit, is_key_in: UNIT
+
+        def initialize(port, interface)
+          @port = port
+          @interface = interface
+        end
+
+        def distance
+          ls_write(NXT::Protocols::I2C.read_measurement_byte_0)
+
+          while ls_get_status < 1
+            sleep(0.1)
+            # TODO: implement timeout so we don't get stuck if the expected data never comes
+          end
+
+          distance = ls_read[0]
+
+          if @unit == :centimeters
+            distance.to_i
+          else
+            (distance * 0.3937008).to_i
+          end
+        end
+
+        def distance!
+          d = distance
+          raise UnmeasurableDistance if d == 255
+
+          d
+        end
+
+        def start
+          sensor_type(:lowspeed_9v)
+          sensor_mode(:raw)
+
+          update_input_mode
+          ls_clear_buffer
+
+          # set sensor to continuously send pings
+          ls_write(NXT::Protocols::I2C.continuous_measurement_command)
+        end
+      end
+    end
+  end
+end