denko 0.13.6 → 0.15.0

data/lib/denko/analog_io.rb

@@ -1,11 +1,26 @@
+# Represent files to be autoloaded in CRuby as an Array.
+# This allows Mruby::Build to parse and preload them instead.
+ANALOG_IO_FILES = [
+  [:InputHelper,    "input_helper"],
+  [:Input,          "input"],
+  [:Output,         "output"],
+  [:Potentiometer,  "potentiometer"],
+  [:Joystick,       "joystick"],
+  [:ADS111X,        "ads111x"],
+  [:ADS1100,        "ads1100"],
+  [:ADS1115,        "ads1115"],
+  [:ADS1118,        "ads1118"],
+]
+
 module Denko
   module AnalogIO
-    autoload :Input,          "#{__dir__}/analog_io/input"
-    autoload :Output,         "#{__dir__}/analog_io/output"
-    autoload :Potentiometer,  "#{__dir__}/analog_io/potentiometer"
-    autoload :Sensor,         "#{__dir__}/analog_io/sensor"
-    autoload :ADS111X,        "#{__dir__}/analog_io/ads111x"
-    autoload :ADS1115,        "#{__dir__}/analog_io/ads1115"
-    autoload :ADS1118,        "#{__dir__}/analog_io/ads1118"
+    ANALOG_IO_FILES.each do |file|
+      file_path = "#{__dir__}/analog_io/#{file[1]}"
+      if file[0]
+        autoload file[0], file_path
+      else
+        require file_path
+      end
+    end
   end
 end

data/lib/denko/behaviors/board_proxy.rb

@@ -11,11 +11,23 @@ module Denko
         0
       end
 
+      def analog_read_high
+        nil
+      end
+
+      def analog_write_high
+        nil
+      end
+
+      alias :pwm_high :analog_write_high
+      alias :dac_high :analog_write_high
+      alias :adc_high :analog_read_high
+
       def convert_pin(pin)
         pin.to_i
       end
 
-      def set_pin_mode(pin, mode, pull=nil); end
+      def set_pin_mode(pin, mode, options={}); end
 
       def start_read; end
     end

data/lib/denko/behaviors/bus_controller.rb

@@ -1,10 +1,12 @@
 module Denko
   module Behaviors
     module BusController
+      include Component
       include Subcomponents
 
       def mutex
-        @mutex ||= Mutex.new
+        # mruby doesn't have Thread or Mutex, so only stub there.
+        @mutex ||= Denko.mruby? ? Denko::MutexStub.new : Mutex.new
       end
     end
   end

data/lib/denko/behaviors/bus_controller_addressed.rb

@@ -8,6 +8,7 @@ module Denko
         if addresses.include? component.address
           raise ArgumentError, "duplicate peripheral address for #{component}"
         end
+        
         super(component)
       end
     end

data/lib/denko/behaviors/bus_peripheral.rb

@@ -2,13 +2,12 @@ module Denko
   module Behaviors
     module BusPeripheral
       include Component
+      include Lifecycle
 
-      attr_reader :address
       alias  :bus :board
 
-      def before_initialize(options={})
-        options[:board] ||= options[:bus]
-        super(options)
+      before_initialize do
+        params[:board] = params[:bus] if params[:bus]
       end
 
       def atomically(&block)

data/lib/denko/behaviors/bus_peripheral_addressed.rb

@@ -1,14 +1,16 @@
 module Denko
   module Behaviors
     module BusPeripheralAddressed
-      include Denko::Behaviors::BusPeripheral
+      include BusPeripheral
+      include Lifecycle
 
-      def before_initialize(options={})
-        # Allow @address override in options, even if peripheral sets a default.
-        @address = options[:address] if options[:address]
+      def address
+        @address ||= params[:address]
+      end
 
-        raise ArgumentError, "missing address for #{self}. Try Bus#search first" unless @address
-        super(options)
+      # Validate address presence after initialization.
+      after_initialize do
+        raise ArgumentError, "no address set for for #{self}. Try Bus#search first" unless address
       end
     end
   end

data/lib/denko/behaviors/callbacks.rb

@@ -1,30 +1,32 @@
 module Denko
   module Behaviors
     module Callbacks
+      include Lifecycle
       include State
-      attr_reader :callback_mutex
 
-      def initialize(options={})
-        @callback_mutex = Mutex.new
-        remove_callbacks
-        super(options)
+      after_initialize do
+        @callback_mutex = Denko.gil? ? Denko::MutexStub.new : Mutex.new
+        callbacks
       end
 
       def callbacks
-        callback_mutex.synchronize { @callbacks }
+        @callbacks ||= {}
       end
 
       def add_callback(key=:persistent, &block)
-        callback_mutex.synchronize do
-          @callbacks[key] ||= []
-          @callbacks[key] << block
-        end
+        @callback_mutex.lock
+        @callbacks      ||= {}
+        @callbacks[key] ||= []
+        @callbacks[key] << block
+        @callback_mutex.unlock
+        @callbacks
       end
 
       def remove_callback(key=nil)
-        callback_mutex.synchronize do
-          key ? @callbacks.delete(key) : @callbacks = {}
-        end
+        @callback_mutex.lock
+        (@callbacks && key) ? @callbacks.delete(key) : @callbacks = {}
+        @callback_mutex.unlock
+        @callbacks
       end
 
       alias :on_data :add_callback
@@ -45,7 +47,8 @@ module Denko
           return nil
         end
 
-        callback_mutex.synchronize do
+        @callback_mutex.lock
+        if @callbacks && !@callbacks.empty?
           @callbacks.each_value do |array|
             array.each do |callback|
               callback.call(filtered_data)
@@ -54,6 +57,7 @@ module Denko
           # Remove one-time callbacks added by #read.
           @callbacks.delete(:read)
         end
+        @callback_mutex.unlock
 
         update_state(filtered_data)
       end

data/lib/denko/behaviors/component.rb

@@ -1,17 +1,19 @@
 module Denko
   module Behaviors
     module Component
+      attr_reader :board, :params
       include State
-      attr_reader :board
 
       def initialize(options={})
-        super(options)
-        before_initialize(options)
-        initialize_board(options)
-        convert_pins(options)
-        initialize_pins(options)
+        @params = options
+        run_before_initialize_cbs
+
+        initialize_board
+        convert_pins(params)
+        initialize_pins(params)
         register
-        after_initialize(options)
+
+        run_after_initialize_cbs
       end
 
       def micro_delay(duration)
@@ -20,9 +22,9 @@ module Denko
 
       protected
 
-      def initialize_board(options={})
-        raise ArgumentError, 'a board is required for a component' unless options[:board]
-        @board = options[:board]
+      def initialize_board
+        raise ArgumentError, 'a board is required for a component' unless params[:board]
+        @board = params[:board]
       end
 
       def register
@@ -36,13 +38,9 @@ module Denko
       # Behaviors::Component only requires a board.
       # Include modules from Setup or override this to use pins.
       #
-      def before_initialize(options={}); end
       def convert_pins(options={});      end
       def initialize_pins(options={});   end
       alias :initialize_pin :initialize_pins
-
-      # Override in components. Call super when inheriting or mixing in.
-      def after_initialize(options={}); end
     end
   end
 end

data/lib/denko/behaviors/input_pin.rb

@@ -1,26 +1,25 @@
 module Denko
   module Behaviors
     module InputPin
+      include Component
       include SinglePin
-      
+      include Lifecycle
+
+      INPUT_MODES = [:input, :input_pulldown, :input_pullup]
+
+      before_initialize do
+        params[:mode] ||= :input
+        unless INPUT_MODES.include?(params[:mode])
+          raise "invalid input mode: #{params[:mode]} given. Should be one of #{INPUT_MODES.inspect}"
+        end
+      end
+
       def _stop_listener
         board.stop_listener(pin)
       end
 
-    protected
-    
-      def initialize_pins(options={})
-        super(options)
-        
-        # Assume input direction, and look for pull mode in options.
-        initial_mode = :input
-        initial_mode = :input_pullup   if options[:pullup]
-        initial_mode = :input_pulldown if options[:pulldown]
-
-        # If user was explicit about mode, just use that.
-        initial_mode = options[:mode]  if options[:mode]
-        
-        self.mode = initial_mode
+      def debounce_time=(value)
+        board.set_pin_debounce(pin, value)
       end
     end
   end

data/lib/denko/behaviors/lifecycle.rb

@@ -0,0 +1,51 @@
+module Denko
+  module Behaviors
+    module Lifecycle
+      #
+      # Callback hook DSL for setup work in including classes.
+      # include(Component) in final classes to get callbacks methods.
+      #
+      def self.included(base); base.extend ClassMethods; end
+      #
+      CALLBACK_METHODS = [:before_initialize, :after_initialize]
+
+      # Callback methods themselves.
+      module ClassMethods
+        CALLBACK_METHODS.each do |method_sym|
+          civar_sym = "@#{method_sym}_cbs".to_sym
+          define_method(method_sym) do |&block|
+            if self.instance_variable_defined?(civar_sym)
+              blocks = self.instance_variable_get(civar_sym)
+            else
+              blocks = []
+            end
+            blocks << block
+            self.instance_variable_set(civar_sym, blocks)
+          end
+        end
+      end
+
+      # Instance method runners.
+      CALLBACK_METHODS.each do |method_sym|
+        civar_sym  = "@#{method_sym}_cbs".to_sym
+        runner_sym = "run_#{method_sym}_cbs".to_sym
+
+        define_method(runner_sym) do
+          # Need to check civars in ancestors too.
+          klasses = self.class.ancestors
+          # If running "after" reverse hierarchy so they run top-down.
+          klasses = klasses.reverse if method_sym.to_s.start_with? "after"
+
+          blocks = []
+          klasses.each do |klass|
+            if klass.instance_variable_defined?(civar_sym)
+              blocks << klass.instance_variable_get(civar_sym)
+            end
+          end
+          blocks = blocks.flatten
+          blocks.each { |b| instance_exec(&b) }
+        end
+      end
+    end
+  end
+end

data/lib/denko/behaviors/listener.rb

@@ -2,20 +2,26 @@ module Denko
   module Behaviors
     module Listener
       include Callbacks
-      
+
       attr_reader :divider
 
+      #
+      # These delegate to #_listen and #_stop_listener,
+      # which should be defined in the including class.
+      #
       def listen(divider=nil, &block)
-        @divider = divider || @listener
+        @divider = divider
         stop
         add_callback(:listen, &block) if block_given?
         _listen(@divider)
+        @listening = true
       end
 
       def stop
-        super if defined?(super)
+        begin; super; rescue NoMethodError; end
         _stop_listener
         remove_callbacks :listen
+        @listening = false
       end
     end
   end

data/lib/denko/behaviors/multi_pin.rb

@@ -3,11 +3,17 @@ module Denko
     module MultiPin
       #
       # Model complex components, using multiple pins, by using proxy components
-      # with one pin each. 
+      # with one pin each.
       #
       include Component
+      include Lifecycle
+
       attr_reader :pin, :pins, :proxies
-      
+
+      def proxies
+        @proxies ||= {}
+      end
+
       # Return a hash with the state of each proxy component.
       def proxy_states
         hash = {}
@@ -16,17 +22,12 @@ module Denko
         end
         hash
       end
-      
-      def before_initialize(options={})
-        # Get given pins early. Avoids giving them again to require or proxy.
-        self.pins = options[:pins]
-        self.proxies = {}
-        super(options)
-      end
 
       def convert_pins(options={})
-        super(options)
-        self.pins.each { |key,pin| self.pins[key] = board.convert_pin(pin) }
+        @pins = {}
+        params[:pins].each do |key,pin|
+          self.pins[key] = pin ? board.convert_pin(pin) : nil
+        end
         pin_array = pins.values
         raise ArgumentError, "duplicate pins in: #{pins.inspect}" unless pin_array == pin_array.uniq
       end
@@ -34,15 +35,20 @@ module Denko
       #
       # Proxy a pin to a single-pin component. Set this up in the including
       # component's #initialize_pins method. Additional options for each proxy
-      # (eg. pullup/pulldown) can be injected there.
-      # 
+      # (eg. mode: :input_pullup) can be injected there.
+      #
       def proxy_pin(name, klass, pin_options={})
         # Proxied pins are required by default.
         require_pin(name) unless pin_options[:optional]
-    
+
         # Make the proxy, passing through options, and store it.
         if self.pins[name]
-          proxy = klass.new pin_options.merge(board: self.board, pin: self.pins[name])          
+          # Allow pin_options to override board or pin number.
+          proxy_options = pin_options
+          proxy_options[:board] ||= self.board
+          proxy_options[:pin]   ||= self.pins[name]
+
+          proxy = klass.new(proxy_options)
           self.proxies[name] = proxy
           instance_variable_set("@#{name}", proxy)
         end
@@ -50,7 +56,7 @@ module Denko
         # Accessor for the proxy's instance var, or nil, if not given.
         singleton_class.class_eval { attr_reader name }
       end
-      
+
       #
       # Require a single pin that may or may not be proxied. This is useful for
       # components using libraries running on the board, where we need to specify
@@ -63,10 +69,6 @@ module Denko
       def require_pins(*array)
         [array].flatten.each { |name| require_pin(name) }
       end
-      
-      private
-      
-      attr_writer :pins, :proxies
     end
   end
 end

data/lib/denko/behaviors/output_pin.rb

@@ -1,12 +1,17 @@
 module Denko
   module Behaviors
     module OutputPin
+      include Component
       include SinglePin
-      protected
+      include Lifecycle
 
-      def initialize_pins(options={})
-        super(options)
-        self.mode = :output
+      OUTPUT_MODES = [:output, :output_pwm, :output_dac, :output_open_drain, :output_open_source]
+
+      before_initialize do
+        params[:mode] ||= :output
+        unless OUTPUT_MODES.include?(params[:mode])
+          raise "invalid input mode: #{params[:mode]} given. Should be one of #{OUTPUT_MODES.inspect}"
+        end
       end
     end
   end

data/lib/denko/behaviors/poller.rb

@@ -3,8 +3,10 @@ module Denko
     module Poller
       include Reader
       include Threaded
-      
+
       def poll_using(method, interval, *args, &block)
+        mruby_thread_check
+
         unless [Integer, Float].include? interval.class
           raise ArgumentError, "wrong interval given to #poll : #{interval.inspect}"
         end
@@ -13,7 +15,14 @@ module Denko
         add_callback(:poll, &block) if block_given?
 
         threaded_loop do
+          # Lock, THEN wait for other normal reads to finish.
+          @reader_mutex.lock
+          sleep 0.001 while read_busy?
+          @reading_normally = true
+
           method.call(*args)
+          @reader_mutex.unlock
+
           sleep interval
         end
       end
@@ -23,7 +32,7 @@ module Denko
       end
 
       def stop
-        super if defined?(super)
+        begin; super; rescue NoMethodError; end
         remove_callbacks :poll
       end
     end

data/lib/denko/behaviors/reader.rb

@@ -1,49 +1,137 @@
 module Denko
   module Behaviors
     module Reader
+      include Lifecycle
       include Callbacks
 
       #
-      # Defalt behavior for #read is to delegate to #_read.
-      # Define #_read in including classes.
+      # DO NOT REPLACE with MutexStub on CRuby!
+      # Even with GIL, misordered readings possible with multiple threads.
+      #
+      after_initialize do
+        # mruby doesn't have Thread or Mutex, so only stub there.
+        @reader_mutex = Denko.mruby? ? Denko::MutexStub.new : Mutex.new
+      end
+
+      READ_WAIT_TIME = 0.001
+      #
+      # Override #update to allow "raw reads" or "normal reads":
+      #
+      #   - Normal reads perform normal #update behavior, passing through
+      #     #pre_callback_filter, running all callbacks and returning filtered_data.
+      #     Use normal for anything that updates the state of a component, and handle
+      #     that in in #pre_callback_filter and #update_state.
+      #     May or may not block calling thread, depending on platform.
+      #
+      #   - Raw reads bypass #pre_callback_filter, callbacks, and return
+      #     raw data. Use raw for reading things like sensor config/serial etc.
+      #     DOES NOT take block callbacks from the use. ALWAYS handle the return value.
+      #     ALWAYS blocks the calling thread.
+      #
+      def update(data)
+        if @reading_raw
+          @callback_mutex.lock
+          @callbacks[:read_raw].each { |c| c.call(data) }
+          @callbacks.delete(:read_raw)
+          @callback_mutex.unlock
+          @reading_raw = false
+          data
+        else
+          return_value = super(data)
+          @reading_normally = false
+          return_value
+        end
+      end
+
+      #
+      # Delegates to #_read. Data passes through #pre_callback_filter, runs all
+      # callbacks, and @state is set. BLOCKS calling thread.
       #
       def read(*args, **kwargs, &block)
         read_using(self.method(:_read), *args, **kwargs, &block)
       end
 
+      #
+      # Delegates to #_read. Data passes through #pre_callback_filter, runs all
+      # callbacks, and @state is set. DOES NOT BLOCK calling thread.
+      #
+      def read_nb(*args, **kwargs, &block)
+        @reader_mutex.lock
+        sleep READ_WAIT_TIME while read_busy?
+        @reading_normally = true
+        _read(*args, **kwargs, &block)
+        @reader_mutex.unlock
+      end
+
+      #
+      # NEVER call this directly. Use #read_nb instead.
+      #
+      # Define #_read in including class to get data which updates the
+      # peripheral state. See #read_using comments for more info.
+      #
+      def _read
+        raise NotImplementedError.new("#{self.class.name}#_read is not defined.")
+      end
+
       #
       # Take a proc/lambda/method as the first agrument and use it to read.
       # Arguments are passed through, allowing dynamic read methods to be defined.
       # Eg. send commands (in args) to a bus, then wait for data read back.
-      # 
-      # Block given is added as a one-time callback in the :read key, and 
-      # the curent thread waits until data is received. Returns the result of
-      # calling #pre_callback_filter with the data.
+      #
+      # Data is received when the board/bus calls #update on us. If a read was
+      # started by this method, the data will pass through #pre_callback_filter,
+      # trigger all callbacks, and set @state. Use this for reading the state
+      # of peripherals, like digital pin level, enviro sensor reading etc.
       #
       def read_using(reader, *args, **kwargs, &block)
-        add_callback(:read, &block) if block_given?
+        # Lock, THEN wait for other normal reads to finish.
+        @reader_mutex.lock
+        sleep READ_WAIT_TIME while read_busy?
+        @reading_normally = true
 
+        # One-time callbacks.
         return_value = nil
-        add_callback(:read) do |filtered_data|
-          return_value = filtered_data
-        end
-        
+        add_callback(:read) { |filtered_data| return_value = filtered_data }
+        add_callback(:read, &block) if block_given?
+
         reader.call(*args, **kwargs)
-        wait_for_read
+        @reader_mutex.unlock
 
+        # Wait for #update to remove the :read callbacks (return_value is set).
+        sleep READ_WAIT_TIME while callbacks[:read]
         return_value
       end
-      
-      def wait_for_read
-        loop do
-          break if !callbacks[:read]
-          sleep 0.001
-        end
+
+      #
+      # Similar to #read_using, but does not trigger #pre_callback_filter,
+      # or run any callbacks except :read_raw. BLOCKS calling thread.
+      # Use for things like sensor status, config etc.
+      #
+      def read_raw(reader, *args, **kwargs)
+        # Can't guarantee read order.
+        raise StandardError, "#read_raw unavailable while listening" if @listening
+
+        # Lock, THEN wait for any normal read to finish.
+        @reader_mutex.lock
+        sleep READ_WAIT_TIME while read_busy?
+        @reading_raw = true
+
+        # Special :read_raw one-time callback.
+        return_value = nil
+        add_callback(:read_raw) { |bytes| return_value = bytes }
+
+        # Call reader, but block and keep the lock until :read_raw callback gets run.
+        reader.call(*args, **kwargs)
+        sleep READ_WAIT_TIME while callbacks[:read_raw]
+        @reader_mutex.unlock
+
+        return_value
       end
 
-      def _read
-        raise NotImplementedError
-          .new("#{self.class.name}#_read is not defined.")
+      def read_busy?
+        # mruby gets stuck waiting somewhere, but doesn't have threads
+        # so it can never really be busy.
+        !Denko.mruby? && (@reading_normally || @reading_raw)
       end
     end
   end