lego_ev3 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5b2fb90c9305d336e5d81ec1a7d7ac242542c1cc
-  data.tar.gz: fcc6149efda2798a9e3c1cfff391812511cf9e14
+  metadata.gz: b418f6caad54717971ee644696289198bd6a1c62
+  data.tar.gz: cb47b39657e7913366bd821f76a35d6eabcd1d28
 SHA512:
-  metadata.gz: 2eb2ba5f4c07fa9e387845ff5d1d27d89114294f94a4f2482456ba3142f4f25f23c5bb302e3dfa39b21ff0bf4a2e42c6447be2c32ab8e4a6689728e693d91f39
-  data.tar.gz: 43e8cab0d3c77082c7ba1eab43c6f5d3299f9c939df5434f2aff32ba7976ee012101b018b49e6261350b9a4b825f37c048ca32c50873c61038762da40348769b
+  metadata.gz: 1b476defd2bde6d39c2d7bf843cdbba04f3dd4612a211deaa56537b6ee1458b059eda153ade4efc5b1b3151312ed2177bf7b5c42d3e067581e26c961c7446037
+  data.tar.gz: 5027148c8a6d338752fc3682ef0c8435dd3192da8a60c716ac305f93f276c1e939a343807b81f658d81a4a04bd24287b534ac8e54aa8a42febf1e8b38cb6e62b

data/README.md

@@ -1,46 +1,129 @@
 # Lego EV3
 
+This library leverages the [ev3dev.org](http://www.ev3dev.org) project to provide a dead simple way to program the Lego Mindstorms EV3 starter kit in Ruby.
+
 ## Getting started
 
-### Make sure you have the necessary Ruby dependencies
+    gem install lego-ev3
+
+Then:
+
+    mkdir example
+    touch example/script.rb
+    touch example/config.yml
+
+Put in `script.rb`:
+
+    require 'lego_ev3'
+
+    connection = LegoEv3::Connection.new
+
+    brick = LegoEv3::Brick.new(connection)
+
+    # Plug any sensor in any input.
+    s = brick.sensors.first
+
+    100.times do
+      puts s.poll
+    end
+
+    connection.close
+
+Put in `config.yml`:
+
+    remote:
+      host: '192.168.2.3'
+      hostname: 'ev3dev'
+      username: 'root'
+      password: 'r00tme'
+      ssh: 22
+      tcp: 13603
+      service: 'ssh'
+
+Execute the script with:
+
+    lego-ev3 example -R
+
+This will open an SSH connection to the brick to send commands. This is one way of doing things, read below for more options.
+
+## Setup the brick to use Ruby
 
-The [ev3dev.org](http://www.ev3dev.org) distribution contains Ruby 2 but some libraries are missing to build native extensions. *This lib requires native extensions to work*.
+### Make sure you have the necessary dependencies
+
+The [ev3dev.org](http://www.ev3dev.org) distribution contains Ruby 2 but some libraries are missing to build native extensions. **Running local scripts with this lib requires native extensions to work**.
 
 Solution #1: Use [RVM](https://rvm.io).
+
 Solution #2: Install those dependencies:
 
-```
-apt-get install build-essential bison openssl libreadline6 libreadline6-dev curl git-core zlib1g zlib1g-dev libssl-dev libyaml-dev libxml2-dev autoconf libc6-dev ncurses-dev automake libtool ruby-dev
-```
+    apt-get install build-essential bison openssl libreadline6 libreadline6-dev curl git-core zlib1g zlib1g-dev libssl-dev libyaml-dev libxml2-dev autoconf libc6-dev ncurses-dev automake libtool ruby-dev
+
+### (Optional) Faster `gem install` operations
+
+To install gems faster, make sure your `~/.gemrc` on the brick looks like:
+
+    ---
+    :verbose: true
+    :sources:
+    - http://rubygems.org/
+    :update_sources: true
+    :backtrace: false
+    :bulk_threshold: 1000
+    :benchmark: false
+    gem: --no-ri --no-rdoc --verbose
+
+## Running a script remotely on the brick for debugging
+
+This is the mode used in _Getting started_ above.
+This mode requires `remote.service: 'ssh'` in the config.
+
+* [+] No need to setup the brick to use Ruby
+* [+] No need to send files to the brick
+* [+] Can use breakpoints in script using [Pry](https://github.com/pry/pry)
+* [-] The slowest approach (~200 ms per command)
+
+## Running a script locally on the brick
+
+The same script in _Getting started_ above can be ran locally on the brick without modifying the code.
+
+* [-] Need to setup the brick to use Ruby
+* [-] Need to send files to the brick
+* [-] Cannot use breakpoints in script
+* [+] Fastest approach (~0.7 ms per command)
+
+Sending a script to the brick:
+
+    lego-ev3 example -u -r
+
+This will:
+
+* Upload the script to the brick (`-u`) at `/home/example`.
+* Execute `ruby /home/example/script.rb` through an SSH connection and capture the output.
+
+**How can the same code be used remotely and locally?**
 
-### Install the gem
+The `LegoEv3::Connection` class is smart enough to determine if the script being executed is on your machine or directly on the brick. To accomplish this, this class uses the `hostname` parameter in the config.
 
-```
-gem install lego-ev3
-```
+## Running a script remotely on the brick for a test run
 
-### A simple script
+* [-] Need to setup the brick to use Ruby
+* [+] No need to send files to the brick
+* [+] Can use breakpoints in script using [Pry](https://github.com/pry/pry)
+* [+] Slow approach (~40 ms per command)
 
-```
-require 'lego_ev3'
+This mode requires `remote.service: 'tcp'` in the config.
 
-# The connection class look at the hostname of the machine to determine
-# if the connection to establish must be local or remote (ssh).
-# machine.hostname != config.hostname => remote.
-connection = LegoEv3::Connection.new('ssh' => {
-  'host' => '192.168.2.3',
-  'hostname' => 'ev3dev',
-  'username' => 'root',
-  'password' => 'r00tme'
-})
+    lego-ev3 example -s # Spawn the TCP server on the brick
+    lego-ev3 example -R # Execute the script with a TCP client
 
-brick = LegoEv3::Brick.new(connection)
+Note that the TCP server is spawned in background on the brick.
+To spawn it in foreground, you need to connect to the brick.
 
-# Plug the touch sensor in any input and run this script by pressing
-# or not the sensor. The 'pressed' value should change accordingly.
-s = brick.sensors.first
-s.poll
-puts s.info.inspect
+## TODO
 
-connection.close
-```
+* Add a DSL on top of current lib
+* Add a state machine on top of current lib
+* Use the state machine to produce graphs of robot logic
+* Add logging and easy way to produce sensor graphs
+* Polling sensors should probably be multi-threaded
+* Add examples

data/bin/lego-ev3

@@ -2,32 +2,85 @@
 
 require 'lego_ev3'
 require 'optparse'
+require 'pp'
 
 options = {
-  user_config: LegoEv3::default_user_config
+  upload: false,
+  mode: :none,
+  user_config: nil
 }
 
 OptionParser.new do |opt|
-  opt.on('-u', '--upload PROJECT', 'Upload everything under ./.../PROJECT to /home/PROJECT on the brick.') do |project|
-    options[:mode] = :upload
-    options[:project] = project
+  opt.banner = 'Usage: lego-ev3 [project] [options]'
+
+  opt.on('-u', '--upload', 'Upload the project to /home/PROJECT on the brick.') do
+    options[:upload] = true
+  end
+
+  opt.on('-r', '--run', 'Run the project locally.') do
+    options[:mode] = :run_local
+  end
+
+  opt.on('-R', '--run-remotely', 'Run the project remotely.') do
+    options[:mode] = :run_remote
   end
 
-  opt.on('-c, --config PATH', 'Use the provided configuration at PATH.') do |path|
+  opt.on('-c', '--config PATH', 'Use the provided configuration at PATH.') do |path|
     options[:user_config].merge!(LegoEv3::load_config(path))
   end
+
+  opt.on('-s', '--server', 'Start a TCP server on the brick.') do |port|
+    options[:mode] = :server
+  end
 end.parse!
 
+options[:project] = ARGV.pop
+options[:user_config] ||= options[:project].nil? || !File.exists?(File.join(options[:project], 'config.yml')) ?
+  LegoEv3::default_user_config :
+  LegoEv3::load_config(File.join(options[:project], 'config.yml'))
+
 puts
 puts "Config used:"
 puts
-ap options
+pp options
 puts
 
-LegoEv3::Uploader
-  .new(
-    options[:user_config]['ssh']['host'],
-    options[:user_config]['ssh']['username'],
-    options[:user_config]['ssh']['password'],
-    options[:project])
-  .upload
+if options[:project].nil? && options[:mode] != :server
+  puts 'This mode requires a project!'
+  puts 'Usage: lego-ev3 [project] [options]'
+  exit
+end
+
+ssh_config = {
+  host_name: options[:user_config]['remote']['host'],
+  port: options[:user_config]['remote']['ssh'],
+  user: options[:user_config]['remote']['username'],
+  password: options[:user_config]['remote']['password'],
+  timeout: 20
+}
+
+if options[:upload]
+  LegoEv3::Uploader
+    .new(ssh_config, options[:project])
+    .upload
+end
+
+if options[:mode] == :run_local
+  command =
+    "cd /home/#{options[:project].split('/').last} && " +
+    "ruby #{options[:user_config]['entry_point']}"
+
+  LegoEv3::SSHScript
+    .new(ssh_config, command)
+    .run
+
+elsif options[:mode] == :run_remote
+  LegoEv3::user_config_overrides = options[:user_config]
+  load File.join(options[:project], options[:user_config]['entry_point'])
+elsif options[:mode] == :server
+  command = "nohup lego-ev3-tcp-server -p #{options[:user_config]['remote']['tcp']} > /dev/null 2>&1 &"
+
+  LegoEv3::SSHScript
+    .new(ssh_config, command)
+    .run
+end

data/bin/lego-ev3-tcp-server

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+
+require 'lego_ev3'
+require 'optparse'
+require 'pp'
+
+options = {
+  port: LegoEv3::default_user_config['remote']['tcp']
+}
+
+OptionParser.new do |opt|
+  opt.banner = 'Usage: lego-ev3-tcp-server [options]'
+
+  opt.on('-p', '--port PORT', 'The port to use') do |port|
+    options[:port] = port
+  end
+end.parse!
+
+LegoEv3::TCPServer.new(options[:port]).open

data/lib/brick.rb

@@ -35,6 +35,8 @@ module LegoEv3
         end
       end
 
+      @connection.flush("Refreshed ports and their status")
+
       # Retrieve Port name -> Tacho motor in batch.
       tacho_motors = {}
       LegoEv3::Commands::TachoMotor.list!(@connection).each do |motor|
@@ -51,7 +53,7 @@ module LegoEv3
         end
       end
 
-      @connection.flush
+      @connection.flush("Refreshed motors and sensors")
 
       # Assemble port info.
       @ports.each do |port|
@@ -79,7 +81,12 @@ module LegoEv3
 
           if driver_name == 'lego-ev3-touch'
             LegoEv3::TouchSensor.new(@connection, id, p)
+          elsif driver_name == 'lego-ev3-color'
+            LegoEv3::ColorSensor.new(@connection, id, p)
+          elsif driver_name == 'lego-ev3-ir'
+            LegoEv3::InfraredSensor.new(@connection, id, p)
           else
+            puts "The sensor #{driver_name} is not supported :( but I accept pull requests!"
             nil
           end
         end.compact

data/lib/commands/builder.rb

@@ -17,11 +17,11 @@ module LegoEv3
         end
       end
 
-      def get(alias_name, type = String, command_name = nil, processor = nil)
+      def get(alias_name, type = String, command_name = nil, handle = 'r', processor = nil)
         command_name ||= alias_name
 
         self.define_singleton_method "get_#{alias_name}" do |connection, id, &callback|
-          connection.send("cat #{get_path(id)}/#{command_name}") do |response|
+          connection.send(:read, "#{get_path(id)}/#{command_name}", nil, handle) do |response|
             sanitized = (response || '').strip
 
             if type == Integer
@@ -48,11 +48,11 @@ module LegoEv3
         end
       end
 
-      def set(alias_name, command_name = nil)
+      def set(alias_name, command_name = nil, handle = 'r')
         command_name ||= alias_name
 
         self.define_singleton_method "set_#{alias_name}" do |connection, id, value|
-          connection.send("echo #{value} > #{get_path(id)}/#{command_name}")
+          connection.send(:write, "#{get_path(id)}/#{command_name}", value.to_s, handle)
         end
 
         self.define_singleton_method "set_#{alias_name}!" do |connection, id, value|
@@ -62,17 +62,17 @@ module LegoEv3
       end
 
       def get_set(alias_name, type = String, command_name = nil, processor = nil)
-        get(alias_name, type, command_name, processor)
-        set(alias_name, command_name)
+        get(alias_name, type, command_name, 'r+', processor)
+        set(alias_name, command_name, 'r+')
       end
 
       def command(alias_name, command_name = nil)
         command_name ||= alias_name
 
         self.define_singleton_method alias_name do |connection, id|
-          connection.send("echo #{command_name} > #{get_command_path(id)}")
+          connection.send(:write, get_command_path(id), command_name, 'w')
         end
-        
+
         self.define_singleton_method "#{alias_name}!" do |connection, id|
           self.send(alias_name, connection, id)
           connection.flush
@@ -81,11 +81,8 @@ module LegoEv3
 
       def has_list
         self.define_singleton_method :list do |connection, &callback|
-          connection.send("ls -C #{get_base_path}") do |response|
-            # TODO: Bug? The folder is not created if no sensor plugged in once.
-            entries_raw = response || ''
-            entries = entries_raw.include?('No such file or directory') ? [] : entries_raw.split(' ').map(&:strip)
-            callback.call(entries)
+          connection.send(:list, get_base_path, nil, 'r') do |response|
+            callback.call(response)
           end
         end
 

data/lib/commands/lego_sensor.rb

@@ -7,6 +7,8 @@ module LegoEv3::Commands::LegoSensor
   get :driver_name
   get :decimals, Integer
   get :num_values, Integer
+  get_set :mode
+  get :modes, String, 'modes', 'r', -> response { response.split(' ').map(&:strip) }
   get :value0, Integer
   get :value1, Integer
   get :value2, Integer

data/lib/commands/tacho_motor.rb

@@ -6,7 +6,7 @@ module LegoEv3::Commands::TachoMotor
   get :port_name
   get :count_per_rot, Integer
   get :duty_cycle, Integer
-  get :states, String, 'state', -> response { response.split(' ').map{ |s| s.strip.to_sym } }
+  get :states, String, 'state', 'r', -> response { response.split(' ').map{ |s| s.strip.to_sym } }
   get_set :duty_cycle_sp, Integer
   get_set :position, Integer
   get_set :position_sp, Integer

data/lib/connection/base.rb

@@ -4,28 +4,25 @@ module LegoEv3
       @to_send = []
     end
 
-    def send(command, &callback)
-      @to_send << [command, callback]
+    def send(verb, path, value = nil, handle = 'r+', &callback)
+      @to_send << [[verb, path, value, handle], callback]
     end
 
-    def flush
+    def flush(summary = nil)
       @connection ||= create_connection
 
-      joined_command = @to_send
-        .map{ |(c, _)| c }
-        .join(';')
+      commands = @to_send.map{ |(c, _)| c }
+      callbacks = @to_send.map{ |(_, c)| c }
 
-      callbacks = @to_send
-        .map{ |(_, c)| c }
-
-      joined_response, time = LegoEv3::with_timer do
-        call_connection(joined_command)
+      responses, time = LegoEv3::with_timer do
+        call_connection(commands)
       end
 
-      puts "#{joined_command}. #{time} ms."
+      summary ||= commands
+        .map{ |c| "[#{c.join(' ')}]" }
+        .join(' ')
 
-      # We assume that one command output one line of result.
-      responses = joined_response.split("\n")
+      puts "#{summary}. #{time} ms."
 
       callbacks.each_with_index.each do |c, i|
         c.call(responses[i]) if c

data/lib/connection/connection.rb

@@ -1,36 +1,34 @@
-require 'optparse'
-
 module LegoEv3
   class Connection
     def initialize(user_config = {})
       options = {
-        user_config: LegoEv3::default_user_config.merge(user_config)
+        user_config: LegoEv3::resolve_user_config
       }
 
-      OptionParser.new do |opt|
-        opt.on('-c, --config PATH', 'Use the provided configuration at PATH.') do |path|
-          options[:user_config].merge!(LegoEv3::load_config(path))
-        end
-      end.parse!
-      is_local = `hostname`.strip == options[:user_config]['ssh']['hostname']
+      is_local = `hostname`.strip == options[:user_config]['remote']['hostname']
 
       @inner_connection = if is_local
         LegoEv3::LocalConnection.new
-      else
-        LegoEv3::RemoteConnection.new(
-          options[:user_config]['ssh']['host'],
-          options[:user_config]['ssh']['username'],
-          options[:user_config]['ssh']['password']
+      elsif options[:user_config]['remote']['service'].to_sym == :tcp
+        LegoEv3::TCPConnection.new(options[:user_config]['remote']['host'] + ':' + options[:user_config]['remote']['tcp'].to_s)
+      elsif options[:user_config]['remote']['service'].to_sym == :ssh
+        LegoEv3::SSHConnection.new(
+          options[:user_config]['remote']['host'],
+          options[:user_config]['remote']['ssh'],
+          options[:user_config]['remote']['username'],
+          options[:user_config]['remote']['password']
         )
+      else
+        raise LegoEv3::InvalidRemoteServiceException.new(options[:user_config]['remote']['service'])
       end
     end
 
-    def send(command, &callback)
-      @inner_connection.send(command, &callback)
+    def send(verb, path, value = nil, handle = 'r+', &callback)
+      @inner_connection.send(verb, path, value, handle, &callback)
     end
 
-    def flush
-      @inner_connection.flush
+    def flush(summary = nil)
+      @inner_connection.flush(summary)
     end
 
     def close