lignite 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bf1b7c4214285394b080eee7ac292b74a02583ec
-  data.tar.gz: 2e8eceb5bb0058722da49642ac252c9054f3582b
+  metadata.gz: ce4cca8022a372bfd1ee229725d3a538376c6d54
+  data.tar.gz: 7957e5d6aa35cf8551752d3a324f2cef141bd466
 SHA512:
-  metadata.gz: 7dba38b35d34ffbafce9c5788c792f12d598623d4862dbfa0f3a3ed99c1c31c490495619cef96970047e9622832d0c92ae97cbfc9282a5e3c52a0f2e06992114
-  data.tar.gz: dddf6c17fd11bd751b111d6c03e70c6114a5333a3acd61ee7fe4dd8958195ab7c3b5c44260144b5e2bea2d3945a8b2621b36d278fc55a5b08d969766a81e417a
+  metadata.gz: fdf692daad988853107d65e5ebf31da38e0c6bd5d4bf6819e9b0e8e8ca5a140fe95bdf51d32db8c556f1e07298f3671aa389e8c994ff2293f087ae1c237cf1a7
+  data.tar.gz: c5a98aedfde6259e69cdadbed737ee7fa1eed93d505a42489ee99a2a64ff8dcadabbdd8c1f4d7bca0a7cb004fc18caaa4cc33f61275153789a63386404896d18

data/.rubocop.yml

@@ -2,11 +2,39 @@ inherit_from: rubocop-suse.yml
 
 AllCops:
   TargetRubyVersion: 2.1
+  Exclude:
+    - 'vendor/**/*'
+    - '.git/**/*'
+    - lib/lignite/ev3_ops.rb
 
 Naming/FileName:
   Exclude:
     - spec/data/*.rb
 
 Layout/IndentHeredoc:
+  Enabled: false
+
+Performance/RedundantBlockCall:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: false
+
+Metrics/BlockLength:
   Exclude:
     - lignite.gemspec
+    - lib/lignite/ev3_tool.rb
+    - spec/**/*.rb
+
+Metrics/ClassLength:
+  Exclude:
+    - lib/lignite/ev3_tool.rb
+    - lib/lignite/motors.rb
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/ModuleLength:
+  Exclude:
+    # generated
+    - lib/lignite/enums.rb

data/NEWS.md

@@ -2,6 +2,12 @@
 
 ## unreleased
 
+## 0.4.0, 2018-03-04
+
+- Generate Ev3Ops ahead of time, enabling YARD docs for them,
+  reducing startup time
+- Fixed `ev3tool ls`, `ls-l`, `start`, all broken in 0.3.0
+
 ## 0.3.0, 2018-03-02
 
 - Added Tap and Replay to simulate a real robot with YAML files for tests

data/Rakefile

@@ -1,6 +1,27 @@
-task default: :test
+task default: [:test, :rubocop, :yard]
 
 desc "Run tests"
 task :test do
   system "rspec"
 end
+
+desc "Run RuboCop"
+task :rubocop do
+  system "rubocop --display-cop-names"
+end
+
+desc "Generate YARD documentation"
+task :yard do
+  system "yardoc --use-cache"
+end
+
+EV3_YML = "data/ev3.yml".freeze
+GENERATOR = "tools/ops_from_yml".freeze
+OPS = "lib/lignite/ev3_ops.rb".freeze
+
+desc "Regenerate the EV3 assembler operations"
+task ops: OPS
+
+file OPS => [EV3_YML, GENERATOR] do |t|
+  sh GENERATOR, t.prerequisites.first, t.name
+end

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

data/bin/ev3tool

@@ -1,151 +1,4 @@
 #!/usr/bin/env ruby
-require "lignite"
-require "thor"
-require "fileutils"
-include Lignite::Bytes
+require "lignite/ev3_tool"
 
-# The VM current working directory is /home/root/lms2012/sys
-# which is not very useful. A better default is /home/root/lms2012/prjs
-# which is displayed on the 2nd tab of the brick UI.
-EV3TOOL_HOME = "../prjs".freeze
-
-def phandles
-  handles = sc.list_open_handles
-  puts "OPEN HANDLES: ", hexdump(handles)
-end
-
-class Ev3Tool < Thor
-  desc "upload LOCAL_FILENAME [BRICK_FILENAME]", "upload a program or a file"
-  map "ul" => "upload"
-  def upload(local_filename, brick_filename = nil)
-    data = File.read(local_filename, encoding: Encoding::BINARY)
-    unless brick_filename
-      prj = File.basename(local_filename, ".rbf")
-      brick_filename = "#{EV3TOOL_HOME}/#{prj}/#{prj}.rbf"
-    end
-    handle = sc.begin_download(data.bytesize, brick_filename)
-    sc.continue_download(handle, data)
-  end
-
-  desc "download BRICK_FILENAME [LOCAL_FILENAME]", "download a file"
-  map "dl" => "download"
-  def download(brick_filename, local_filename = nil)
-    local_filename ||= File.basename(brick_filename)
-    fsize, handle, data = sc.begin_upload(4096, brick_filename)
-    File.open(local_filename, "w") do |f|
-      loop do
-        f.write(data)
-        fsize -= data.bytesize
-        break if fsize.zero?
-        handle, data = sc.continue_upload(handle, 4096)
-      end
-    end
-  end
-
-  desc "list-files DIRNAME", "list DIRNAME in a long format"
-  map "ls-l" => "list-files"
-  def list_files(name)
-    name ||= EV3TOOL_HOME
-    name = "#{EV3TOOL_HOME}/#{name}" unless name.start_with?("/")
-
-    result = ""
-    fsize, handle, data = sc.list_files(4096, name)
-    loop do
-      result += data
-      fsize -= data.bytesize
-      break if fsize.zero?
-      handle, data = sc.continue_list_files(handle, 4096)
-    end
-    result
-  rescue Lignite::VMError
-    nil
-  end
-
-  desc "ls DIRNAME", "list DIRNAME in a short format"
-  def ls(name)
-    raw = list_files(name)
-    return nil if raw.nil?
-
-    raw.lines.map do |l|
-      l = l.chomp
-      next nil if ["./", "../"].include?(l)
-      next l if l.end_with?("/")
-      # skip checksum + space + size + space
-      l[32 + 1 + 8 + 1..-1]
-    end.compact
-  end
-
-  desc "start NAME", "start a program"
-  def start(name)
-    if name.include?("/")
-      name = "#{EV3TOOL_HOME}/#{name}" unless name.start_with?("/")
-    else
-      name = "#{EV3TOOL_HOME}/#{name}/#{name}.rbf"
-    end
-
-    unless file_exist?(name)
-      $stderr.puts "File #{name.inspect} not found"
-      exit 1
-    end
-
-    slot = Lignite::USER_SLOT
-    no_debug = 0
-    dc.block do
-      # these are local variables
-      data32 :size
-      data32 :ip
-      file_load_image(slot, name, :size, :ip)
-      program_start(slot, :size, :ip, no_debug)
-    end
-  end
-
-  desc "stop", "stop a running program"
-  def stop
-    dc.program_stop(Lignite::USER_SLOT)
-  end
-
-  no_commands do
-    def file_exist?(name)
-      dirname = File.dirname(name)
-      filename = File.basename(name)
-      files = ls(dirname) || []
-      files.include?(filename)
-    end
-
-    def assisted_connection
-      Lignite::Connection.create
-    rescue => e
-      fn = Lignite::Connection::Bluetooth.config_filename
-      $stderr.puts <<MSG
-Could not connect to EV3.
-Use a USB cable or configure a Bluetooth address in #{fn.inspect}.
-Details:
-  #{e.message}
-MSG
-
-      template = Lignite::Connection::Bluetooth.template_config_filename
-      if !File.exist?(fn) && File.exist?(template)
-        FileUtils.mkdir_p(File.dirname(fn))
-        FileUtils.install(template, fn)
-        $stderr.puts "(A template config file has been copied for your convenience)"
-      end
-      exit 1
-    end
-
-    def sc
-      return @sc if @sc
-      @sc = Lignite::SystemCommands.new(conn)
-    end
-
-    def dc
-      return @dc if @dc
-      @dc = Lignite::DirectCommands.new(conn)
-    end
-
-    def conn
-      @conn ||= assisted_connection
-    end
-  end
-end
-
-Ev3Tool.start(ARGV)
+Lignite::Ev3Tool.start(ARGV)

data/examples/bobbee.rb

@@ -1,15 +1,17 @@
 #!/usr/bin/ruby
-
-# https://www.lego.com/mindstorms/build-a-robot/bobb3e
-# A Bobcat® like two-tracked forklift
-
 require "lignite"
 
+# A Bobcat like two-tracked forklift.
+# https://www.lego.com/mindstorms/build-a-robot/bobb3e
 class Bobbee
+  # The pair of motors driving the tracks
   # @return [Lignite::Motors]
   attr_reader :drive
+  # The motor lifting the fork
   # @return [Lignite::Motors]
   attr_reader :lift
+  # Interface to all other commands
+  # @return [Lignite::DirectCommands]
   attr_reader :dc
 
   def initialize(drive: Lignite::PORT_B | Lignite::PORT_C,
@@ -21,33 +23,34 @@ class Bobbee
     @dc = dc
   end
 
+  # @param speed [Integer] -100..100
   # @param turn [Integer] -200..200
-  def time_sync(speed, turn, ms, brake = Lignite::BRAKE, wait: true)
-    # 1500 ms is about 1 boost square at speed 100
-    drive.time_sync(-speed, turn, ms, brake)
-  end
-
-  # @param turn [Integer] -200..200
+  #   turn 0 (straight)
+  #   -  900 (2.5 * 360) degrees is about 1 boost square
+  #   turn 200 (full right)
+  #   -  2400 degrees is a full turn, 600 deg is an about-right turn
+  #      where the center of rotation is the battery-cover of the brick,
+  #      or between the rear axles.
+  #   turn 100 (semi right)
+  #   - 4800 degrees is a full turn, about one of the rear axles
+  # @param degrees [Integer] degrees to turn the motors
+  #   (complicated by gears and *turn*, which see)
+  # @param brake [BRAKE,COAST]
+  # @param wait [Boolean] work around my ignorance of motor readiness
   def step_sync(speed, turn, degrees, brake = Lignite::BRAKE, wait: true)
-    # turn 0 (straight)
-    # -  900 (2.5 * 360) degrees is about 1 boost square
-    # turn 200 (full right)
-    # -  2400 degrees is a full turn, 600 deg is an about-right turn
-    #    where the center of rotation is the battery-cover of the brick,
-    #    or between the rear axles.
-    # turn 100 (semi right)
-    # - 4800 degrees is a full turn, about one of the rear axles
     drive.step_sync(-speed, turn, degrees, brake)
     drive.ready if wait
   end
 
   LIFT_FULL = 220
 
+  # Raise the fork from the ground up
   def raise(wait: true)
     lift.step_power(30, 10, LIFT_FULL - 20, 10)
     lift.ready if wait
   end
 
+  # Raise the fork one third of the way from the ground up
   def third_raise(wait: true)
     lift.step_power(30, 10, LIFT_FULL / 3 - 20, 10)
     lift.ready if wait
@@ -56,6 +59,7 @@ class Bobbee
     sleep 3
   end
 
+  # Lower the fork from above to the ground
   def lower(wait: true)
     lift.step_power(-1, 10, LIFT_FULL - 20, 10) # , Lignite::COAST)
     lift.ready if wait
@@ -64,107 +68,125 @@ class Bobbee
     sleep 3
   end
 
+  # Lower the fork one third of the way from above to the ground
   def third_lower(wait: true)
     lift.step_power(-1, 10, LIFT_FULL / 3 - 20, 10)
     lift.ready if wait
   end
 
+  # Beep
   def beep(ms = 300)
     dc.sound_tone(20, 1760, ms)
     dc.sound_ready
   end
 
+  # steps to move 1 square on the Boost mat
   SQUARE_STEPS = 920
-  def f(steps = SQUARE_STEPS)
+
+  # Drive forward 1 square on the Boost mat
+  def forward(steps = SQUARE_STEPS)
     step_sync(50, 0, steps)
     beep
     sleep 3
   end
 
-  def b(steps = SQUARE_STEPS)
+  # Drive backward 1 square on the Boost mat
+  def back(steps = SQUARE_STEPS)
     step_sync(-50, 0, back_factor(steps))
     beep
     sleep 3
   end
 
-  # it moves faster when going backwards!?
+  # Compensation factor when moving backward
   def back_factor(n)
+    # why? maybe the center of mass affects it
     (n * 0.95).to_i
   end
 
+  # If we want to turn inside a Boost mat square,
+  # we cannot simply make a turn since the center of rotation of the robot
+  # is between the rear axles which is not in the center of the square.
+  # So we need to move forward a bit, turn, and move back the same amount.
   ROTATION_OFFSET = 350
-  def f1
-    f(ROTATION_OFFSET)
+
+  def align_centers_for_turning(&turn_block)
+    forward(ROTATION_OFFSET)
+    beep(100)
+
+    turn_block.call
+
+    back(ROTATION_OFFSET)
     beep(100)
   end
 
+  # Motor degrees needed to turn the robot 90 degrees when using turn=200
   TURN_90_AT_200_STEPS = 600
-  def l2
+
+  # Turn 90 degrees left, simply by moving tracks in opposite directions
+  def left_immediate
     step_sync(50, -200, TURN_90_AT_200_STEPS)
     beep(100)
     sleep 3
   end
 
-  def r2
+  # Turn 90 degrees right, simply by moving tracks in opposite directions
+  def right_immediate
     step_sync(50, 200, TURN_90_AT_200_STEPS)
     beep(100)
     sleep 3
   end
 
-  def f3
-    b(ROTATION_OFFSET)
-    beep(100)
-  end
-
-  def l
-    # a 3 part maneuver: forward, left, and back-a-little
-    # to turn 1 BS left
-    f1
-    l2
-    f3
+  # Turn 90 degrees left, starting and ending inside a Boost mat square
+  def left
+    align_centers_for_turning do
+      left_immediate
+    end
   end
 
-  def r
-    # a 3 part maneuver: forward, right, and back-a-little
-    # to turn 1 BS right
-    f1
-    r2
-    f3
+  # Turn 90 degrees right, starting and ending inside a Boost mat square
+  def right
+    align_centers_for_turning do
+      right_immediate
+    end
   end
 end
 
 bb = Bobbee.new
-# 1 BS
-# bb.time_sync(100, 0, 1500)
 
-# Put Bobb3e on the blue arrow. Move it one square left, and forward.
-# Put the container on a raised platform on the "twins" square.
-# Put a raised platform on the "fire" square
+# Put Bobb3e (B) on the blue arrow (^). Move it one square left, and forward.
+# Put the container on a raised platform on the "twins" square (T).
+# Put a raised platform on the "fire" square (F).
+#
+#     ..F
+#     ...
+#     B.T
+#     .^.
 def from_twins_to_fire(bb)
   bb.instance_exec do
     beep
 
+    2.times { third_raise }
+
+    right
+    forward
     third_raise
-    third_raise
-    r
-    f
-    third_raise
-    b
-    l
+    back
+    left
     # we're at the starting position, but carrying the load
 
     # move towards the recipient
-    f; f; r
+    2.times { forward }
+    right
 
     # deliver and unload
-    f
+    forward
     third_lower
-    b
+    back
 
     # resting position
-    l; b; b
-    third_lower
-    third_lower
+    left
+    2.times { back }
+    2.times { third_lower }
   end
 end
 
@@ -172,37 +194,37 @@ def from_fire_to_twins(bb)
   bb.instance_exec do
     beep
 
-    third_raise
-    third_raise
+    2.times { third_raise }
 
     # move towards the load
-    f; f; r
+    2.times { forward }
+    right
 
     # load
-    f
+    forward
     third_raise
-    b
+    back
 
     # starting position
-    l; b; b
+    left
+    2.times { back }
 
     # deliver
-    r
-    f
+    right
+    forward
     third_lower
-    b
-    l
+    back
+    left
 
     # resting position
-    third_lower
-    third_lower
+    2.times { third_lower }
   end
 end
 
 def calibrate_forward_and_back(bb)
   bb.instance_exec do
-    f; f; f; f
-    b; b; b; b
+    4.times { forward }
+    4.times { back }
   end
 end