denko 0.13.5 → 0.14.0

data/examples/uart/board_passthrough.rb

@@ -4,31 +4,37 @@
 # 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.
+# This isn't 100% reliable. The Rx buffer on the direct board is periodically read, instead
+# of using an interrupt. It can potentially overflow, causing data from the passthrough board
+# to be lost. If flow control data is lost, the connection will halt.
 #
 # 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.
+#  1) Avoid long running commands on the direct board (eg. IR output, WS2812 etc.).
+#     These block the CPU enough that the Rx buffer may not be read in time to avoid overflow.
+#  2) Use the lowest practical baud rate on the passthrough board, so the direct board's Rx
+#     buffer takes as long as possible to fill, reducing the chance of data loss.
 #
 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))
+uart   = Denko::UART::Hardware.new(board: board1, index: 1)
+board2 = Denko::Board.new(Denko::Connection::BoardUART.new(uart, baud: 115200))
 
 led1 = Denko::LED.new(board: board1, pin: 13)
-led1.blink(0.02)
+led1.blink(0.5)
 
 led2 = Denko::LED.new(board: board2, pin: 13)
-led2.blink(0.02)
+led2.blink(0.5)
 
-sensor = Denko::AnalogIO::Input.new(board: board1, pin: :A0)
-sensor.listen(4)
+input = Denko::AnalogIO::Input.new(board: board2, pin: :A0)
+input.smoothing = true
+input.smoothing_size = 10
+# Show input value only if it differs from previous state.
+input.add_callback do |value|
+  puts "A0 value: #{value}" if value != input.state
+end
+input.listen(16)
 
 sleep

data/examples/uart/hardware_loopback.rb

@@ -1,5 +1,5 @@
 #
-# Example that writes to TX pin of hardware UART1 and reads back on RX pin of same UART.
+# Write to Tx pin of hardware UART1 and read data back on its Rx pin.
 #
 require 'bundler/setup'
 require 'denko'

data/lib/denko/analog_io/ads1100.rb

@@ -0,0 +1,127 @@
+module Denko
+  module AnalogIO
+    class ADS1100
+      include Behaviors::Lifecycle
+      include I2C::Peripheral
+      include Behaviors::Poller
+      include InputHelper
+
+      I2C_ADDRESS   = 0x48
+      I2C_FREQUENCY = 400_000
+
+      # Convert sample rates in samples-per-seconds to their bit representation.
+      SAMPLE_RATES = [  # Bitmask
+        128,            # 0b00
+        32,             # 0b01
+        16,             # 0b10
+        8               # 0b11 (default)
+      ]
+
+      # Faster sampling rates have lower resolution.
+      BIT_RANGES = [    # Bitmask   Bits  SPS
+        4_096,          # 0b00      12    128
+        16_383,         # 0b01      14    32
+        32_767,         # 0b10      15    16
+        65_535,         # 0b11      16    8
+      ]
+
+      # Wait times need to be slightly longer than the actual sample times.
+      WAIT_TIMES = SAMPLE_RATES.map { |rate| (1 / rate.to_f) + 0.0005 }
+
+      GAINS = [  # Bitmask   Full scale voltage
+        1,       # 0b00      Vdd
+        2,       # 0b01      Vdd / 2
+        4,       # 0b10      Vdd / 4
+        8,       # 0b11      Vdd / 8
+      ]
+
+      # Default config register:
+      #   Bit 7   : Start conversion (write 1) | Conversion in progress (read 1)
+      #   Bit 6-5 : Reserved, must be 00
+      #   Bit 4   : Conversion mode. 0 = continuous (datasheet default). 1 = single (our default).
+      #   Bit 3-2 : Sample Rate (see array above)
+      #   Bit 1-2 : PGA setting (see array above)
+      CONFIG_STARTUP = 0b00011100
+
+      # Masks
+      GAIN_CLEAR = 0b11111100
+      SAMPLE_RATE_CLEAR = 0b11110011
+
+      after_initialize do
+        # Validate user gave full scale voltage.
+        raise ArgumentError "full-scale voltage not a Numeric or not given for ADS1100" unless full_scale_voltage.is_a?(Numeric)
+
+        i2c_write(config_register)
+        sleep WAIT_TIMES[sample_rate_mask]
+      end
+
+      def _read
+        # Set bit 7 of the config register and write it to start conversion.
+        i2c_write(config_register | (1<<7))
+
+        # Sleep the right amount of time for conversion, based on sample rate bits.
+        sleep WAIT_TIMES[sample_rate_mask]
+
+        # Read the result, triggering callbacks.
+        i2c_read(2)
+      end
+
+      def listen(pin, divider=nil)
+        raise StandardError, "ADS1100 does not implement #listen. Use #read or #poll instead"
+      end
+
+      def pre_callback_filter(bytes)
+        # Readings are 16-bits, signed, big-endian.
+        value = bytes.pack("C*").unpack("s>")[0]
+        # Let InputHelper module handle smooothing.
+        super(value)
+      end
+
+      # Default to single conversion.
+      def config_register
+        @config_register ||= CONFIG_STARTUP
+      end
+
+      def sample_rate=(rate)
+        raise Argument Error "wrong sample_rate: #{sample_rate.inspect} given for ADS1100" unless SAMPLE_RATES.include?(rate)
+        @sample_rate_mask = SAMPLE_RATES.index(rate)
+        config_register = (config_register & SAMPLE_RATE_CLEAR) | (sample_rate_mask << 2)
+        @sample_rate = rate
+      end
+
+      def sample_rate_mask
+        @sample_rate_mask ||= SAMPLE_RATES.index(sample_rate)
+      end
+
+      def sample_rate
+        @sample_rate ||= params[:sample_rate] || 8
+      end
+
+      attr_writer :sample_rate_mask
+
+      def gain=(gain)
+        raise ArgumentError "wrong gain: #{gain.inspect} given for ADS1100" unless GAINS.include?(gain)
+        @gain_mask = GAINS.index(gain)
+        config_register = (config_register & GAIN_CLEAR) | gain_mask
+        @gain      = gain
+      end
+
+      def gain_mask
+        @gain_mask ||= GAINS.index(gain)
+      end
+
+      def gain
+        @gain ||= params[:gain] || 1
+      end
+
+      # Unlike some ADS parts, full-scale voltage depends on supply (Vdd). User must specify.
+      def full_scale_voltage
+        @full_scale_voltage ||= params[:full_scale_voltage]
+      end
+
+      def volts_per_bit
+        full_scale_voltage / (GAINS[gain_mask] * BIT_RANGES[sample_rate_mask]).to_f
+      end
+    end
+  end
+end

data/lib/denko/analog_io/ads1115.rb

@@ -1,9 +1,13 @@
 module Denko
   module AnalogIO
     class ADS1115
+      include Behaviors::Lifecycle
       include I2C::Peripheral
       include ADS111X
 
+      I2C_ADDRESS   = 0x48
+      I2C_FREQUENCY = 400_000
+
       # Config register values on startup. MSB-first.
       # Matches datasheet, except MSB bit 7 unset to avoid conversion start.
       # Same as: [0x05, 0x83] or [5, 131]
@@ -19,42 +23,21 @@ module Denko
       CONFIG_ADDRESS     = 0b01
       CONVERSION_ADDRESS = 0b00
 
-      def before_initialize(options={})
-        @i2c_address   = 0x48
-        @i2c_frequency = 400_000
-        super(options)
-      end
-
-      def after_initialize(options={})
-        super(options)
-
-        # Mutex and variables for BoardProxy behavior.
-        @mutex        = Mutex.new
-        @active_pin   = nil
-        @active_gain  = nil
-
+      after_initialize do
         # Set register bytes to default and write to device.
-        @config_register = CONFIG_STARTUP.dup
-        i2c_write [CONFIG_ADDRESS] + @config_register
-
-        # Enable BoardProxy callbacks.
+        i2c_write [CONFIG_ADDRESS] + config_register
         enable_proxy
       end
 
       def _read(config)
         # Write config register to start reading.
         i2c_write [CONFIG_ADDRESS] + 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.
-        i2c_read(CONVERSION_ADDRESS, 2)
-      end
-
-      # Readings are 2 bytes big-endian.
-      def pre_callback_filter(bytes)
-        bytes.pack("C*").unpack("s>")[0]
+        i2c_read(2, register: CONVERSION_ADDRESS)
       end
     end
   end

data/lib/denko/analog_io/ads1118.rb

@@ -1,7 +1,8 @@
 module Denko
   module AnalogIO
     class ADS1118
-      include SPI::Peripheral
+      include SPI::Peripheral::SinglePin
+      include Behaviors::Lifecycle
       include ADS111X
 
       # Config register values on startup. MSB-first.
@@ -15,29 +16,19 @@ module Denko
       BASE_MSB = 0b10000001
       BASE_LSB = 0b00001010
 
-      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_STARTUP.dup
-        spi_write(@config_register)
+      def spi_mode
+        @spi_mode ||= params[:spi_mode] || 1
+      end
 
-        # Enable BoardProxy callbacks.
+      after_initialize do
+        spi_write(config_register)
         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]
 
@@ -45,22 +36,16 @@ module Denko
         spi_read(2)
       end
 
-      # Pack the 2 bytes back into a string, then unpack as big-endian signed 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
+        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
 

data/lib/denko/analog_io/ads111x.rb

@@ -5,6 +5,7 @@ module Denko
       # Functionality shared among the ADS111X class of ADC converters.
       #
       include Behaviors::Reader
+      attr_accessor :config_register, :active_pin, :active_gain
 
       PGA_SETTINGS = [  # Bitmask   Full scale voltage
         0.0001875,      # 0b000     6.144 V
@@ -55,38 +56,43 @@ module Denko
       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) 
+            if active_pin == component.pin
+              component.volts_per_bit = PGA_SETTINGS[active_gain]
+              component.update(value)
             end
           end
         end
       end
 
+      def pre_callback_filter(bytes)
+        # Pack the 2 bytes into a string, then unpack as big-endian int16.
+        value = bytes.pack("C*").unpack("s>")[0]
+      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
+        mutex.synchronize do
           # Default gain and sample rate.
           gain        ||= 0b010
           sample_rate ||= 0b100
 
           # Set these for callbacks.
-          @active_pin   = pin
-          @active_gain  = gain
+          self.active_pin   = pin
+          self.active_gain  = gain
 
           # Set gain in upper config register.
           raise ArgumentError "wrong gain: #{gain.inspect} given for ADS111X" unless PGA_RANGE.include?(gain)
-          @config_register[0] = self.class::BASE_MSB | (gain << 1)
+          config_register[0] = self.class::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)
+          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 ADS111X" unless SAMPLE_RATE_RANGE.include?(gain)
-          @config_register[1] = self.class::BASE_LSB | (sample_rate << 5)
+          raise ArgumentError "wrong sample_rate: #{sample_rate.inspect} given for ADS111X" unless SAMPLE_RATE_RANGE.include?(sample_rate)
+          config_register[1] = self.class::BASE_LSB | (sample_rate << 5)
 
-          read(@config_register)
+          read(config_register)
         end
       end
 
@@ -118,6 +124,14 @@ module Denko
 
       def stop_listener(pin)
       end
+
+      def mutex
+        @mutex ||= Mutex.new
+      end
+
+      def config_register
+        @config_register ||= self.class::CONFIG_STARTUP.dup
+      end
     end
   end
 end

data/lib/denko/analog_io/input.rb

@@ -2,77 +2,51 @@ 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)
+      include InputHelper
+      include Behaviors::Lifecycle
+
+      before_initialize do
+        # Allow giving ADC unit with multiple pins as a board proxy.
+        if params[:adc]
+          params[:board] = params[:adc]
+          params.delete(:adc)
+        end
       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]
+      # Default 16ms listener for analog inputs connected to a Board.
+      def divider
+        @divider ||= params[:divider] || 16
+      end
 
-        # If the ADC has a programmable amplifier, pass through its setting.
-        @gain = options[:gain]
+      # Negative input on ADCs that support it.
+      def negative_pin
+        @negative_pin ||= params[:negative_pin]
+      end
 
-        # If using a non-default sampling rate, store it.
-        @sample_rate = options[:sample_rate]
+      # PGA gain for ADCs that support it
+      def gain
+        @gain ||= params[:gain]
+      end
 
-        # Default to smoothing disabled.
-        @smoothing        = false
-        @smoothing_set  ||= []
+      # Sample rates for ADCs that support it.
+      def sample_rate
+        @sample_rate ||= params[:sample_rate]
       end
 
-      attr_reader :negative_pin, :gain, :sample_rate
+      attr_writer :divider, :negative_pin, :gain, :sample_rate
 
-      # ADCs can set this based on gain, so exact voltages can be calculated.
+      # Allow ADCs to set this, 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
+      def _listen(div=nil)
+        self.divider = div if div
+        board.analog_listen(pin, divider)
       end
     end
   end

data/lib/denko/analog_io/input_helper.rb

@@ -0,0 +1,42 @@
+module Denko
+  module AnalogIO
+    module InputHelper
+      #
+      # Smoothing features.
+      # Does a moving average of the last smoothing_size readings.
+      #
+      attr_accessor :smoothing, :smoothing_size
+
+      def smoothing_size
+        @smoothing_size ||= 8
+      end
+
+      def smoothing_set
+        @smoothing_set ||= []
+      end
+
+      def smooth_input(value)
+        # Add new value, but limit to the 8 latest values.
+        smoothing_set << value
+        smoothing_set.shift while (smoothing_set.length > smoothing_size)
+
+        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
+
+      # Handle smoothing if enabled. Call super(value) after conversion in subclasses.
+      def pre_callback_filter(value)
+        smoothing ? smooth_input(value.to_i) : value.to_i
+      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
+    end
+  end
+end

data/lib/denko/analog_io/output.rb

@@ -4,12 +4,12 @@ module Denko
       include Behaviors::OutputPin
       include Behaviors::Callbacks
       include Behaviors::Threaded
-      
+      include Behaviors::Lifecycle
+
       interrupt_with :write
-      
-      def initialize_pins(options={})
-        super(options)
-        self.mode = :output_dac
+
+      before_initialize do
+        params[:mode] = :output_dac
       end
 
       def write(value)

data/lib/denko/analog_io/potentiometer.rb

@@ -1,14 +1,12 @@
 module Denko
   module AnalogIO
-    class Potentiometer < Input      
-      def after_initialize(options={})
-        super(options)
-        
-        # Enable smoothing.
-        self.smoothing = true
+    class Potentiometer < Input
+      include Behaviors::Lifecycle
 
-        # Start listening immediately. Read 2x as often as regular Input.
-        listen(@divider = 8)
+      after_initialize do
+        # Enable smoothing and start listening immediately at ~125 Hz.
+        self.smoothing = true
+        listen(8)
       end
     end
   end

data/lib/denko/analog_io.rb

@@ -1,10 +1,11 @@
 module Denko
   module AnalogIO
+    autoload :InputHelper,    "#{__dir__}/analog_io/input_helper"
     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 :ADS1100,        "#{__dir__}/analog_io/ads1100"
     autoload :ADS1115,        "#{__dir__}/analog_io/ads1115"
     autoload :ADS1118,        "#{__dir__}/analog_io/ads1118"
   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,6 +1,7 @@
 module Denko
   module Behaviors
     module BusController
+      include Component
       include Subcomponents
 
       def mutex

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]
       end
 
       def atomically(&block)