lignite 0.3.0 → 0.4.0

data/lib/lignite/ev3_tool.rb

@@ -0,0 +1,175 @@
+require "lignite"
+require "thor"
+require "fileutils"
+require "objspace"
+
+module Lignite
+  # Implements the `ev3tool` command line interface
+  class Ev3Tool < Thor
+    # 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
+
+    include Lignite::Bytes
+
+    def self.exit_on_failure?
+      true
+    end
+
+    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)
+      puts raw_list_files(name)
+    end
+
+    desc "ls DIRNAME", "list DIRNAME in a short format"
+    def ls(name)
+      puts raw_ls(name)
+    end
+
+    no_commands do
+      def raw_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
+
+      def raw_ls(name)
+        raw = 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
+
+      def runnable_name(name)
+        if name.start_with?("/")
+          name
+        elsif name.include?("/")
+          "#{EV3TOOL_HOME}/#{name}"
+        else
+          "#{EV3TOOL_HOME}/#{name}/#{name}.rbf"
+        end
+      end
+    end
+
+    desc "start NAME", "start a program"
+    def start(name)
+      name = runnable_name(name)
+
+      raise Thor::Error, "File #{name.inspect} not found on the brick" unless file_exist?(name)
+
+      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 = raw_ls(dirname) || []
+        files.include?(filename)
+      end
+
+      def assisted_connection
+        c = Lignite::Connection.create
+        # When invoking via Thor we can't get at the instance otherwise :-/
+        ObjectSpace.define_finalizer(self, ->(_id) { close })
+        c
+      rescue StandardError => 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
+
+        try_config_from_template(fn, Lignite::Connection::Bluetooth.template_config_filename)
+        raise Thor::Error, ""
+      end
+
+      def try_config_from_template(config_fn, template_fn)
+        return unless !File.exist?(config_fn) && File.exist?(template_fn)
+        FileUtils.mkdir_p(File.dirname(config_fn))
+        FileUtils.install(template_fn, config_fn)
+        $stderr.puts "(A template config file has been copied for your convenience)"
+      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
+
+      def close
+        @conn.close if @conn
+        @conn = nil
+      end
+    end
+  end
+end

data/lib/lignite/logger.rb

@@ -1,6 +1,7 @@
 require "logger"
 
 module Lignite
+  # Include this to provide a simple `logger.debug` etc.
   module Logger
     def self.default_logger
       logger = ::Logger.new(STDERR)

data/lib/lignite/message.rb

@@ -71,6 +71,7 @@ module Lignite
     end
   end
 
+  # A reply to a SystemCommand
   class SystemReply < Message
     def initialize(msgid:, error:, body:)
       @msgid = msgid
@@ -87,6 +88,7 @@ module Lignite
     end
   end
 
+  # A reply to a DirectCommand
   class DirectReply < Message
     def initialize(msgid:, error:, body:)
       @msgid = msgid

data/lib/lignite/motors.rb

@@ -144,7 +144,7 @@ module Lignite
       dc.output_clr_count(layer, nos)
     end
 
-    def get_count
+    def get_count # rubocop:disable Naming/AccessorMethodName, upstream API name
       layer = @layer
       nos_as_indices.map do |no|
         tachos = dc.with_reply do

data/lib/lignite/op_compiler.rb

@@ -1,137 +1,18 @@
-require "yaml"
+require "lignite/defines"
+require "lignite/enums"
+require "lignite/ev3_ops"
 
 module Lignite
-  # Dynamically constructs methods for all the instructions in ev3.yml
+  # Compiles methods for all the instructions in ev3.yml
   # The methods return the {ByteString}s corresponding to the ops.
   class OpCompiler
-    # TODO: doing it dynamically
-    # - is slow
-    # - makes the implementation harder to understand
-    # - means we cannot use YARD to document the API
-    # Therefore we should generate (most of) op_compiler.rb statically from
-    # ev3.yml ahead of the time.
-
-    include Bytes
     include Logger
-    extend Logger
-
-    # A marker for features that are not implemented yet
-    class TODO < StandardError
-    end
-
-    def self.load_const(name, value)
-      raise "duplicate constant #{name}" if Lignite.const_defined?(name)
-      Lignite.const_set(name, value)
-    end
-
-    def self.load_op(oname, odata)
-      ovalue = odata["value"]
-      oparams = odata["params"]
-      p1 = oparams.first
-      if p1 && p1["type"] == "SUBP"
-        commands = p1["commands"]
-        commands.each do |cname, cdata|
-          cvalue = cdata["value"]
-          load_const(cname, cvalue)
-          cparams = cdata["params"]
-          define_op("#{oname}_#{cname}", ovalue, cvalue, cparams)
-        end
-        define_multiop(oname, commands)
-      else
-        define_op(oname, ovalue, nil, oparams)
-      end
-    end
-
-    def self.define_multiop(oname, commands)
-      names = commands.map do |cname, cdata|
-        csym = cname.downcase.to_sym
-        cvalue = cdata["value"]
-        [cvalue, csym]
-      end.to_h
-
-      osym = oname.downcase.to_sym
-      define_method(osym) do |*args|
-        logger.debug "called #{osym} with #{args.inspect}"
-        cvalue = args.shift
-        csym = names.fetch(cvalue)
-        send("#{osym}_#{csym}", *args)
-      end
-    end
-
-    def self.define_op(oname, ovalue, cvalue, params)
-      check_arg_count = true
-      param_handlers = params.map do |par|
-        case par["type"]
-        when "PARLAB"           # a label, only one opcode
-          raise TODO
-        when "PARNO"            # the value says how many other params follow
-          check_arg_count = false
-          ->(x) { param_simple(x) }
-        when "PARS"             # string
-          raise TODO
-        when "PARV"             # value, type depends
-          raise TODO
-        when "PARVALUES"
-          raise TODO
-        when "PAR8", "PAR16", "PAR32", "PARF"
-          ->(x) { param_simple(x) }
-        else
-          raise "Unhandled param type #{par["type"]}"
-        end
-      end
-
-      osym = oname.downcase.to_sym
-      define_method(osym) do |*args|
-        logger.debug "called #{osym} with #{args.inspect}"
-        if check_arg_count && args.size != param_handlers.size
-          raise ArgumentError, "expected #{param_handlers.size} arguments, got #{args.size}"
-        end
-
-        bytes = u8(ovalue)
-        bytes += param_simple(cvalue) unless cvalue.nil?
-
-        bytes += args.zip(param_handlers).map do |a, h|
-          h ||= ->(x) { param_simple(x) }
-          # h.call(a) would have self = Op instead of #<Op>
-          instance_exec(a, &h)
-        end.join("")
-        logger.debug "returning bytecode: #{bytes.inspect}"
-        bytes
-      end
-    rescue TODO
-      logger.debug "Could not define #{oname}"
-    end
-
-    @loaded = false
-
-    def self.load_yml
-      return if @loaded
-      fname = File.expand_path("../../../data/ev3.yml", __FILE__)
-      yml = YAML.load_file(fname)
-      op_hash = yml["ops"]
-      op_hash.each do |oname, odata|
-        load_op(oname, odata)
-      end
-
-      defines = yml["defines"]
-      defines.each do |dname, ddata|
-        load_const(dname, ddata["value"])
-      end
-
-      enums = yml["enums"]
-      enums.each_value do |edata|
-        edata["members"].each do |mname, mdata|
-          load_const(mname, mdata["value"])
-        end
-      end
-
-      @loaded = true
-    end
+    include Bytes
+    include Ev3Ops
 
     # @param globals [Variables,nil]
     # @param locals  [Variables,nil]
     def initialize(globals = nil, locals = nil)
-      self.class.load_yml
       @globals = globals
       @locals = locals
     end
@@ -218,13 +99,20 @@ module Lignite
       end
     end
 
+    # @return [ByteString]
+    def param_multiple(*args)
+      args.map { |a| param_simple(a) }.join("")
+    end
+
     # @return [ByteString]
     def param_simple(x)
       case x
       when Integer
         make_lc(x).map(&:chr).join("")
       when Complex
-        # a Complex number: real: just like an Integer above, but imag tells how many bytes to use for it
+        # a Complex number:
+        #   #real: just like an Integer above, but
+        #   #imag tells how many bytes to use for it
         make_lc(x.real, x.imag).map(&:chr).join("")
       when String
         u8(0x80) + x + u8(0x00)

data/lib/lignite/system_commands.rb

@@ -1,4 +1,6 @@
 module Lignite
+  # The commands that cannot appear in a .rbf program,
+  # used mostly for program manipulation
   class SystemCommands
     include Bytes
     include Logger
@@ -52,15 +54,21 @@ module Lignite
 
         reply = system_command_with_reply(bytes)
 
-        # TODO: parse it with return_handlers
-        replies = return_handlers.map do |h|
-          parsed, reply = h.call(reply)
-          parsed
-        end
-        raise "Unparsed reply #{reply.inspect}" unless reply.empty?
-        # A single reply is returned as a scalar, not an array
-        replies.size == 1 ? replies.first : replies
+        parse_reply(reply, return_handlers)
+      end
+    end
+
+    # @param reply [ByteString]
+    # @param return_handlers [Array<Proc>]
+    # @return [Object,Array<Object>]
+    def parse_reply(reply, return_handlers)
+      replies = return_handlers.map do |h|
+        parsed, reply = h.call(reply)
+        parsed
       end
+      raise "Unparsed reply #{reply.inspect}" unless reply.empty?
+      # A single reply is returned as a scalar, not an array
+      replies.size == 1 ? replies.first : replies
     end
 
     def handlers(odata)
@@ -79,16 +87,11 @@ module Lignite
 
     def param_handler(oparam)
       case oparam["type"]
-      when "U8"
-        ->(x) { u8(x) }
-      when "U16"
-        ->(x) { u16(x) }
-      when "U32"
-        ->(x) { u32(x) }
-      when "BYTES"
-        ->(x) { x }
-      when "ZBYTES"
-        ->(x) { x + u8(0) }
+      when "U8" then ->(x) { u8(x) }
+      when "U16" then ->(x) { u16(x) }
+      when "U32" then ->(x) { u32(x) }
+      when "BYTES" then ->(x) { x }
+      when "ZBYTES" then ->(x) { x + u8(0) }
       else
         raise
       end
@@ -98,14 +101,10 @@ module Lignite
     # a parsed value and the rest of the input
     def return_handler(oparam)
       case oparam["type"]
-      when "U8"
-        ->(i) { [unpack_u8(i[0, 1]), i[1..-1]] }
-      when "U16"
-        ->(i) { [unpack_u16(i[0, 2]), i[2..-1]] }
-      when "U32"
-        ->(i) { [unpack_u32(i[0, 4]), i[4..-1]] }
-      when "BYTES"
-        ->(i) { [i, ""] }
+      when "U8" then ->(i) { [unpack_u8(i[0, 1]), i[1..-1]] }
+      when "U16" then ->(i) { [unpack_u16(i[0, 2]), i[2..-1]] }
+      when "U32" then ->(i) { [unpack_u32(i[0, 4]), i[4..-1]] }
+      when "BYTES" then ->(i) { [i, ""] }
       else
         raise
       end