denko 0.13.0

data/examples/uart/bit_bang_write.rb

@@ -0,0 +1,16 @@
+#
+# Example that writes to bit bang UART and reads back on hardware UART1. Tested on Arduino Mega.
+#
+require 'bundler/setup'
+require 'denko'
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+
+hw_uart = Denko::UART::Hardware.new(board: board, index: 1, baud: 31250)
+bb_uart = Denko::UART::BitBang.new(board: board, pins: { rx:10, tx:11 }, baud: 31250)
+
+bb_uart.write("Hello World!\n")
+
+sleep 1
+
+puts hw_uart.gets

data/examples/uart/board_passthrough.rb

@@ -0,0 +1,34 @@
+#
+# Example using one board's UART as the transport for a second board, also running Denko.
+#
+# For this example, board1 (direct) is an Arduino Mega. board2 (passthrough) is an Uno,
+# running Denko, with its UART pins (0, 1) connected to the Mega's UART1 pins (18, 19)
+#
+# This isn't 100% reliable. The Rx buffer on the direct board is periodically read, so
+# it can potentially overflow, causing data sent from the passthrough board to be lost.
+# Eventually flow control data will be lost and the host will stop sending altogether.
+#
+# Use at your own risk, but for the best possible performance:
+#  1) Avoid long running commands on the direct board (eg. IR transmission, HTU21D).
+#     These block the CPU enough that the Rx buffer won't be read in time to avoid overflow.
+#  2) Use the lowest practical baud rate on the passthrough board. 19200 is used here, so
+#     the direct board's Rx buffer takes 6x the time to fill, compared to 115200 baud.
+#
+require 'bundler/setup'
+require 'denko'
+
+board1 = Denko::Board.new(Denko::Connection::Serial.new)
+
+uart = Denko::UART::Hardware.new(board: board1, index: 1)
+board2 = Denko::Board.new(Denko::Connection::BoardUART.new(uart, baud: 19200))
+
+led1 = Denko::LED.new(board: board1, pin: 13)
+led1.blink(0.02)
+
+led2 = Denko::LED.new(board: board2, pin: 13)
+led2.blink(0.02)
+
+sensor = Denko::AnalogIO::Input.new(board: board1, pin: :A0)
+sensor.listen(4)
+
+sleep

data/examples/uart/hardware_loopback.rb

@@ -0,0 +1,16 @@
+#
+# Example that writes to TX pin of hardware UART1 and reads back on RX pin of same UART.
+#
+require 'bundler/setup'
+require 'denko'
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+
+uart = Denko::UART::Hardware.new(board: board, index: 1, baud: 31250)
+
+uart.write("Hello World!\nBye World!\n")
+
+sleep 1
+
+puts uart.gets
+puts uart.gets

data/lib/denko/analog_io/ads1118.rb

@@ -0,0 +1,182 @@
+module Denko
+  module AnalogIO
+    class ADS1118
+      include SPI::Peripheral
+      include Behaviors::Reader
+      include Behaviors::Threaded
+
+      PGA_SETTINGS = [  # Bitmask   Full scale voltage
+        0.0001875,      # 0b000     6.144 V
+        0.000125,       # 0b001     4.095 V
+        0.0000625,      # 0b010     2.048 V (default)
+        0.00003125,     # 0b011     1.024 V
+        0.000015625,    # 0b100     0.512 V
+        0.0000078125,   # 0b101     0.256 V
+        0.0000078125,   # 0b110     0.256 V
+        0.0000078125,   # 0b111     0.256 V
+      ]
+      PGA_RANGE = (0..7).to_a
+
+      # Sample rate bitmask maps to sample time in seconds.
+      SAMPLE_TIMES = [  # Bitmask
+        0.125,          # 0b000
+        0.0625,         # 0b001
+        0.03125,        # 0b010
+        0.015625,       # 0b011
+        0.0078125,      # 0b100 (default)
+        0.004,          # 0b101
+        0.002105263,    # 0b110
+        0.00116279,     # 0b111
+      ]
+      SAMPLE_RATE_RANGE = (0..7).to_a
+
+      # Wait times need to be slightly longer than the actual sample times.
+      WAIT_TIMES = SAMPLE_TIMES.map { |time| time + 0.0005 }
+
+      # Mux bits map to array of form [positive input, negative input].
+      MUX_SETTINGS = {
+        0b000 => [0, 1],
+        0b001 => [0, 3],
+        0b010 => [1, 3],
+        0b011 => [2, 3],
+        0b100 => [0, nil],
+        0b101 => [1, nil],
+        0b110 => [2, nil],
+        0b111 => [3, nil],
+      }
+
+      # Config register values on startup.
+      CONFIG_DEFAULT = [0x05, 0x8B]
+
+      # Base config bytes to mask settings into. Not same as default.
+      BASE_MSB = 0b10000001
+      BASE_LSB = 0b00001011
+
+      def after_initialize(options={})
+        super(options)
+
+        # SPI mode 1 recommended.
+        @spi_mode = options[:spi_mode] || 1
+
+        # Mutex and variables for BoardProxy behavior.
+        @mutex        = Mutex.new
+        @active_pin   = nil
+        @active_gain  = nil
+
+        # Set register bytes to default and write to device.
+        @config_register = CONFIG_DEFAULT.dup
+        spi_write(@config_register)
+
+        # Enable BoardProxy callbacks.
+        enable_proxy
+      end
+
+      def _read(config)
+        # Write config register to start reading.
+        spi_write(config)
+        
+        # Sleep the right amount of time for conversion, based on sample rate bits.
+        sleep WAIT_TIMES[config[1] >> 5]
+
+        # Read the result, triggering callbacks.
+        spi_read(2)
+      end
+
+      # Pack the 2 bytes back into a string, then unpack as big-endian int16.
+      def pre_callback_filter(message)
+        bytes = message.split(",").map { |b| b.to_i }
+        bytes.pack("C*").unpack("s>")[0]
+      end
+
+      def _temperature_read
+        # Wrap in mutex to not interfere with other reads.
+        @mutex.synchronize do
+          _read([0b10000001, 0b10011011])
+        end
+      end
+
+      def temperature_read(&block)
+        reading = read_using -> { _temperature_read }
+        
+        # Temperature is shifted 2 bits left, and is 0.03125 degrees C per bit.
+        temperature = (reading / 4) * 0.03125
+
+        block.call(temperature) if block_given?
+        return temperature
+      end
+
+      #
+      # BoardProxy behavior so AnalogIO classes can use this as a Board.
+      #
+      include Behaviors::BoardProxy
+
+      # Mimic Board#update, but inside a callback, wrapped by #update.
+      def enable_proxy
+        self.add_callback(:board_proxy) do |value|
+          components.each do |component|
+            if @active_pin == component.pin
+              component.volts_per_bit = PGA_SETTINGS[@active_gain]
+              component.update(value) 
+            end
+          end
+        end
+      end
+
+      def analog_read(pin, negative_pin=nil, gain=nil, sample_rate=nil)
+        # Wrap in mutex so calls and callbacks are atomic.
+        @mutex.synchronize do
+          # Default gain and sample rate.
+          gain        ||= 0b010
+          sample_rate ||= 0b100
+
+          # Set these for callbacks.
+          @active_pin   = pin
+          @active_gain  = gain
+
+          # Set gain in upper config register.
+          raise ArgumentError "wrong gain: #{gain.inspect} given for ADS1118" unless PGA_RANGE.include?(gain)
+          @config_register[0] = BASE_MSB | (gain << 1)
+
+          # Set mux bits in upper config register.
+          mux_bits = pins_to_mux_bits(pin, negative_pin)
+          @config_register[0] = @config_register[0] | (mux_bits << 4)
+
+          # Set sample rate in lower config_register.
+          raise ArgumentError "wrong sample_rate: #{sample_rate.inspect} given for ADS1118" unless SAMPLE_RATE_RANGE.include?(gain)
+          @config_register[1] = BASE_LSB | (sample_rate << 5)
+
+          read(@config_register)
+        end
+      end
+
+      def pins_to_mux_bits(pin, negative_pin)
+        # Pin 1 is negative input. Only pin 0 can be read.
+        if negative_pin == 1
+          raise ArgumentError, "given pin: #{pin.inspect} cannot be used when pin 1 is negative input, only 0" unless pin == 0
+          return 0b000
+        end
+
+        # Pin 3 is negative input. Pins 0..2 can be read.
+        if negative_pin == 3
+          raise ArgumentError, "given pin: #{pin.inspect} cannot be used when pin 3 is negative input, only 0..2" unless [0,1,2].include? pin
+          return 0b001 + pin
+        end
+
+        # No negative input. Any pin from 0 to 3 can be read.
+        unless negative_pin
+          raise ArgumentError, "given pin: #{pin.inspect} is out of range 0..3" unless [0,1,2,3].include? pin
+          return (0b100 + pin)
+        end
+
+        raise ArgumentError, "only pins 1 and 3 can be used as negative input"
+      end
+
+      def analog_listen(pin, divider=nil)
+        raise StandardError, "ADS1118 does not implement #listen for subcomponents. Use #read or #poll instead"
+      end
+
+      def stop_listener(pin)
+      end
+    end
+  end
+end

data/lib/denko/analog_io/input.rb

@@ -0,0 +1,79 @@
+module Denko
+  module AnalogIO
+    class Input
+      include Behaviors::InputPin
+      include Behaviors::Reader
+      include Behaviors::Poller
+      include Behaviors::Listener
+      
+      def before_initialize(options={})        
+        options[:board] = options[:adc] if options[:adc]
+        options[:adc] = nil
+        super(options)
+      end
+
+      def after_initialize(options={})
+        super(options)
+
+        # Default 16ms listener for analog inputs connected to a Board.
+        @divider = 16
+
+        # If using a negative input on a supported ADC, store the pin.
+        @negative_pin = options[:negative_pin]
+
+        # If the ADC has a programmable amplifier, pass through its setting.
+        @gain = options[:gain]
+
+        # If using a non-default sampling rate, store it.
+        @sample_rate = options[:sample_rate]
+
+        # Default to smoothing disabled.
+        @smoothing        = false
+        @smoothing_set  ||= []
+      end
+
+      attr_reader :negative_pin, :gain, :sample_rate
+
+      # ADCs can set this based on gain, so exact voltages can be calculated.
+      attr_accessor :volts_per_bit
+
+      def _read
+        board.analog_read(pin, negative_pin, gain, sample_rate)
+      end
+
+      def _listen(divider=nil)
+        @divider = divider || @divider
+        board.analog_listen(pin, @divider)
+      end
+      
+      # Attach a callback that only fires when state changes.
+      def on_change(&block)
+        add_callback(:on_change) do |new_state|
+          block.call(new_state) if new_state != self.state
+        end
+      end
+
+      #
+      # Smoothing features.
+      # Does a moving average of the last 8 readings.
+      #
+      attr_accessor :smoothing
+
+      def smooth_input(value)
+        # Add new value, but limit to the 8 latest values.
+        @smoothing_set << value
+        @smoothing_set.shift if @smoothing_set.length > 8
+        
+        average = @smoothing_set.reduce(:+) / @smoothing_set.length.to_f
+        
+        # Round up or down based on previous state to reduce fluctuations.
+        state && (state > average) ? average.ceil : average.floor
+      end
+
+      # Convert data to integer, or pass it through smoothing if enabled.
+      def pre_callback_filter(value)
+        smoothing ? smooth_input(value.to_i) : value.to_i
+      end
+    end
+  end
+end

data/lib/denko/analog_io/output.rb

@@ -0,0 +1,20 @@
+module Denko
+  module AnalogIO
+    class Output
+      include Behaviors::OutputPin
+      include Behaviors::Callbacks
+      include Behaviors::Threaded
+      
+      interrupt_with :write
+      
+      def initialize_pins(options={})
+        super(options)
+        self.mode = :output_dac
+      end
+
+      def write(value)
+        board.dac_write(pin, @state = value)
+      end
+    end
+  end
+end

data/lib/denko/analog_io/potentiometer.rb

@@ -0,0 +1,15 @@
+module Denko
+  module AnalogIO
+    class Potentiometer < Input      
+      def after_initialize(options={})
+        super(options)
+        
+        # Enable smoothing.
+        self.smoothing = true
+
+        # Start listening immediately. Read 2x as often as regular Input.
+        listen(@divider = 8)
+      end
+    end
+  end
+end

data/lib/denko/analog_io/sensor.rb

@@ -0,0 +1,6 @@
+module Denko
+  module AnalogIO
+    class Sensor < Input
+    end
+  end
+end

data/lib/denko/analog_io.rb

@@ -0,0 +1,9 @@
+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 :ADS1118,        "#{__dir__}/analog_io/ads1118"
+  end
+end

data/lib/denko/behaviors/board_proxy.rb

@@ -0,0 +1,23 @@
+module Denko
+  module Behaviors
+    module BoardProxy
+      include Subcomponents
+
+      def high
+        1
+      end
+
+      def low
+        0
+      end
+
+      def convert_pin(pin)
+        pin.to_i
+      end
+
+      def set_pin_mode(pin, mode, pull=nil); end
+
+      def start_read; end
+    end
+  end
+end

data/lib/denko/behaviors/bus_controller.rb

@@ -0,0 +1,11 @@
+module Denko
+  module Behaviors
+    module BusController
+      include Subcomponents
+
+      def mutex
+        @mutex ||= Mutex.new
+      end
+    end
+  end
+end

data/lib/denko/behaviors/bus_controller_addressed.rb

@@ -0,0 +1,15 @@
+module Denko
+  module Behaviors
+    module BusControllerAddressed
+      include BusController
+
+      def add_component(component)
+        addresses = components.map { |c| c.address }
+        if addresses.include? component.address
+          raise ArgumentError, "duplicate peripheral address for #{component}"
+        end
+        super(component)
+      end
+    end
+  end
+end

data/lib/denko/behaviors/bus_peripheral.rb

@@ -0,0 +1,21 @@
+module Denko
+  module Behaviors
+    module BusPeripheral
+      include Component
+
+      attr_reader :address
+      alias  :bus :board
+
+      def before_initialize(options={})
+        options[:board] ||= options[:bus]
+        super(options)
+      end
+
+      def atomically(&block)
+        bus.mutex.synchronize do
+          block.call
+        end
+      end
+    end
+  end
+end

data/lib/denko/behaviors/bus_peripheral_addressed.rb

@@ -0,0 +1,15 @@
+module Denko
+  module Behaviors
+    module BusPeripheralAddressed
+      include Denko::Behaviors::BusPeripheral
+
+      def before_initialize(options={})
+        # Aallow @address override in options, even if peripheral sets default.
+        @address = options[:address] if options[:address]
+
+        raise ArgumentError, "missing address for #{self}. Try Bus#search first" unless @address
+        super(options)
+      end
+    end
+  end
+end

data/lib/denko/behaviors/callbacks.rb

@@ -0,0 +1,67 @@
+module Denko
+  module Behaviors
+    module Callbacks
+      include State
+      attr_reader :callback_mutex
+
+      def initialize(options={})
+        @callback_mutex = Mutex.new
+        remove_callbacks
+        super(options)
+      end
+
+      def callbacks
+        callback_mutex.synchronize { @callbacks }
+      end
+
+      def add_callback(key=:persistent, &block)
+        callback_mutex.synchronize do
+          @callbacks[key] ||= []
+          @callbacks[key] << block
+        end
+      end
+
+      def remove_callback(key=nil)
+        callback_mutex.synchronize do
+          key ? @callbacks.delete(key) : @callbacks = {}
+        end
+      end
+
+      alias :on_data :add_callback
+      alias :remove_callbacks :remove_callback
+
+      def update(data)
+        # nil will unblock #read without running callbacks.
+        unless data
+          remove_callback(:read)
+          return nil
+        end
+
+        filtered_data = pre_callback_filter(data)
+
+        # nil will unblock #read without running callbacks.
+        unless filtered_data
+          remove_callback(:read)
+          return nil
+        end
+
+        callback_mutex.synchronize do
+          @callbacks.each_value do |array|
+            array.each do |callback|
+              callback.call(filtered_data)
+            end
+          end
+          # Remove one-time callbacks added by #read.
+          @callbacks.delete(:read)
+        end
+
+        update_state(filtered_data)
+      end
+
+      # Override to process data before giving to callbacks and state.
+      def pre_callback_filter(data)
+        data
+      end
+    end
+  end
+end

data/lib/denko/behaviors/component.rb

@@ -0,0 +1,48 @@
+module Denko
+  module Behaviors
+    module Component
+      include State
+      attr_reader :board
+
+      def initialize(options={})
+        super(options)
+        before_initialize(options)
+        initialize_board(options)
+        convert_pins(options)
+        initialize_pins(options)
+        register
+        after_initialize(options)
+      end
+
+      def micro_delay(duration)
+        board.micro_delay(duration)
+      end
+
+      protected
+
+      def initialize_board(options={})
+        raise ArgumentError, 'a board is required for a component' unless options[:board]
+        @board = options[:board]
+      end
+
+      def register
+        board.add_component(self)
+      end
+
+      def unregister
+        board.remove_component(self)
+      end
+
+      # Setup::Base 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

@@ -0,0 +1,24 @@
+module Denko
+  module Behaviors
+    module InputPin
+      include SinglePin
+      
+      def _stop_listener
+        board.stop_listener(pin)
+      end
+
+    protected
+    
+      def initialize_pins(options={})
+        super(options)
+        
+        initial_mode = :input
+        initial_mode = :input_pullup   if options[:pullup]
+        initial_mode = :input_pulldown if options[:pulldown]
+        initial_mode = options[:mode]  if options[:mode]
+        
+        self.mode = initial_mode
+      end
+    end
+  end
+end

data/lib/denko/behaviors/listener.rb

@@ -0,0 +1,22 @@
+module Denko
+  module Behaviors
+    module Listener
+      include Callbacks
+      
+      attr_reader :divider
+
+      def listen(divider=nil, &block)
+        @divider = divider || @listener
+        stop
+        add_callback(:listen, &block) if block_given?
+        _listen(@divider)
+      end
+
+      def stop
+        super if defined?(super)
+        _stop_listener
+        remove_callbacks :listen
+      end
+    end
+  end
+end