denko 0.13.0

data/lib/denko/sensor/htu31d.rb

@@ -0,0 +1,187 @@
+module Denko
+  module Sensor
+    class HTU31D
+      include I2C::Peripheral
+      include Behaviors::Poller
+
+      # Commands
+      RESET           = 0x1E
+      RESET_TIME      = 0.015 # Reset time in seconds.
+      HEATER_ON       = 0X04
+      HEATER_OFF      = 0X02
+      READ_T_AND_H    = 0x00 # Returns 6 bytes: [T_MSB, T_LSB, T_CRC, H_MSB, H_LSB, H_CRC]
+      READ_H          = 0x10 # Returns 3 bytes: [H_MSB, H_LSB, H_CRC]
+      READ_SERIAL     = 0x0A # Returns 6 bytes: [S1, S1_CRC, S2, S2_CRC, S3, S3_CRC]
+      READ_DIAGNOSTIC = 0x08 # Returns 1 byte:  [HEATER, T_LOW, T_HIGH, T_RUN, H_LOW, H_HIGH, H_RUN, NVM_ERR]
+      #
+      # HEATER         : Bit set if heater is turned on.
+      # T_LOW / T_HIGH : Bit set if temperature is outside range of -50 to 150 C.
+      # H_LOW / H_HIGH : Bit set if humidity is outside range of -10 to 120 % RH.
+      # T_RUN / H_RUN  : Bit set if storage register under/overruns, truncated to min or max integer value.
+      # NVM_ERR        : Bit set if internal CRC failed.
+      #
+      START_CONVERSION  = 0x40 # Must be OR'ed with resolution setting bits.
+
+      # User can give resolutions as integer from 0-3, as shown in the datasheet.
+      T_RESOLUTIONS = {
+        0 => 0x00, # LSBIT = 0.040 C
+        1 => 0x02, # LSBIT = 0.025 C
+        2 => 0x04, # LSBIT = 0.016 C
+        3 => 0x06, # LSBIT = 0.012 C
+      }
+      H_RESOLUTIONS = {
+        0 => 0x00, # LSBIT = 0.020%
+        1 => 0x08, # LSBIT = 0.014%
+        2 => 0x10, # LSBIT = 0.010%
+        3 => 0x18, # LSBIT = 0.007%
+      }
+
+      # Leave some margin for error, since this doesn't lock the bus during conversion like the HTU21D.
+      CONVERSION_SAFETY_FACTOR = 1.2
+
+      # Conversion times in seconds.
+      T_CONVERSION_TIMES = {
+        0 => 0.00111 * CONVERSION_SAFETY_FACTOR,
+        1 => 0.00214 * CONVERSION_SAFETY_FACTOR,
+        2 => 0.00421 * CONVERSION_SAFETY_FACTOR,
+        3 => 0.00834 * CONVERSION_SAFETY_FACTOR,
+      }
+      H_CONVERSION_TIMES = {
+        0 => 0.00157 * CONVERSION_SAFETY_FACTOR,
+        1 => 0.00306 * CONVERSION_SAFETY_FACTOR,
+        2 => 0.00603 * CONVERSION_SAFETY_FACTOR,
+        3 => 0.01198 * CONVERSION_SAFETY_FACTOR,
+      }
+
+      def before_initialize(options={})
+        @i2c_address = 0x40
+        super(options)
+      end
+
+      def after_initialize(options={})
+        super(options)
+
+        # Avoid repeated memory allocation for callback data and state.
+        @reading     = { temperature: nil, humidity: nil }
+        self.state   = { temperature: nil, humidity: nil }
+        @resolutions = { temperature: 0, humidity: 0 }
+
+        reset
+      end
+
+      def reset
+        i2c_write [RESET]
+        sleep RESET_TIME
+        @heater_on = false
+      end
+
+      def heater_on?
+        @heater_on
+      end
+
+      def heater_off?
+        !@heater_on
+      end
+      
+      def heater_on
+        i2c_write [HEATER_ON]
+        @heater_on = true
+      end
+
+      def heater_off
+        i2c_write [HEATER_OFF]
+        @heater_on = false
+      end
+      
+      def temperature_resolution
+        @resolutions[:temperature]
+      end
+
+      def temperature_resolution=(setting)
+        raise ArgumentError, "wrong resolution given: #{setting}. Must be in range 0..3" unless (0..3).include?(setting)
+        @resolutions[:temperature] = setting
+      end
+      
+      def humidity_resolution
+        @resolutions[:humidity]
+      end
+      
+      def humidity_resolution=(setting)
+        raise ArgumentError, "wrong resolution given: #{setting}. Must be in range 0..3" unless (0..3).include?(setting)
+        @resolutions[:humidity] = setting
+      end
+
+      def [](key)
+        @state_mutex.synchronize do
+          return @state[key]
+        end
+      end
+      
+      def _read
+        # Calculate total conversion time.
+        conversion_time = T_CONVERSION_TIMES[temperature_resolution] +
+                          H_CONVERSION_TIMES[humidity_resolution]
+
+        # Build the conversion command from the set resolutions.
+        conversion_command = START_CONVERSION | T_RESOLUTIONS[temperature_resolution] | H_RESOLUTIONS[humidity_resolution]
+
+        # Write it and sleep.
+        i2c_write [conversion_command]
+        sleep conversion_time
+
+        # Write the read command and read back 6 bytes.
+        i2c_read(READ_T_AND_H, 6)
+      end
+
+      def pre_callback_filter(bytes)
+        # Bytes given as: [T_MSB, T_LSB, T_CRC, H_MSB, H_LSB, H_CRC]
+
+        # Temperature
+        t_raw = (bytes[0] << 8) | bytes[1]
+        if calculate_crc(t_raw) != bytes[2]
+          @reading[:temperature] = nil
+        else
+          @reading[:temperature] = (165 * t_raw.to_f / 65535) - 40
+        end
+
+        # Humidity
+        h_raw = (bytes[3] << 8) | bytes[4]
+        if calculate_crc(h_raw) != bytes[5]
+          @reading[:humidity] = nil
+        else
+          @reading[:humidity] = h_raw.to_f / 655.35
+        end
+
+        # Ignore entire reading if either CRC failed.
+        return nil unless (@reading[:temperature] && @reading[:humidity])
+        @reading
+      end
+      
+      def update_state(reading)
+        @state_mutex.synchronize do
+          @state[:temperature] = reading[:temperature]
+          @state[:humidity]    = reading[:humidity]
+        end
+      end
+
+      #
+      # CRC calculation adapted from offical driver, found here:
+      # https://github.com/TEConnectivity/HTU21D_Generic_C_Driver/blob/master/htu21d.c#L275
+      #
+      def calculate_crc(value)
+        polynomial = 0x988000   # x^8 + x^5 + x^4 + 1
+        msb        = 0x800000
+        mask       = 0xFF8000
+        result     = value << 8 # Pad right with length of output CRC
+
+        while msb != 0x80
+          result = ((result ^ polynomial) & mask) | (result & ~mask) if (result & msb !=0)
+          msb        >>= 1
+          mask       >>= 1
+          polynomial >>= 1
+        end
+        result
+      end
+    end
+  end
+end

data/lib/denko/sensor/virtual.rb

@@ -0,0 +1,42 @@
+module Denko
+  module Sensor
+    class Temperature
+      include Behaviors::Poller
+
+      def initialize(sensor)
+        @sensor = sensor
+        super
+      end
+
+      def _read
+        @sensor.read_temperature
+      end
+
+      alias :celsius :state
+      alias :to_i    :state
+
+      def fahrenheit
+        (celsius * 9 / 5) + 32
+      end
+
+      def kelvin
+        celsius + 273.15
+      end
+    end
+
+    class Humidity
+      include Behaviors::Poller
+
+      def initialize(sensor)
+        @sensor = sensor
+        super
+      end
+
+      def _read
+        @sensor.read_humidity
+      end
+
+      alias :to_i :state
+    end
+  end
+end

data/lib/denko/sensor.rb

@@ -0,0 +1,13 @@
+module Denko
+  module Sensor
+    autoload :Temperature, "#{__dir__}/sensor/virtual"
+    autoload :Humidity,    "#{__dir__}/sensor/virtual"
+    autoload :DHT,         "#{__dir__}/sensor/dht"
+    autoload :DS18B20,     "#{__dir__}/sensor/ds18b20"
+    autoload :BME280,      "#{__dir__}/sensor/bme280"
+    autoload :HTU21D,      "#{__dir__}/sensor/htu21d"
+    autoload :HTU31D,      "#{__dir__}/sensor/htu31d"
+    autoload :AHT10,       "#{__dir__}/sensor/aht"
+    autoload :AHT20,       "#{__dir__}/sensor/aht"
+  end
+end

data/lib/denko/spi/base_register.rb

@@ -0,0 +1,37 @@
+module Denko
+  module SPI
+    class BaseRegister
+      include Peripheral
+      #
+      # Registers act as a Board for components that need only digital pins in
+      # in their I/O direction. Give the register as a 'board' when initializing a
+      # new component, and pin numbers that map onto the registers parallel output pins.
+      #
+      include Behaviors::BoardProxy
+
+      attr_reader :bytes
+
+      def before_initialize(options={})
+        super(options)
+        #
+        # To use the register as a board proxy, we need to know how many
+        # bytes there are and map each bit to a virtual pin.
+        # Defaults to 1 byte. Ignore if writing to the register directly.
+        #
+        @bytes = options[:bytes] || 1
+        #
+        # When used as a board proxy, store the state of each register
+        # pin as a 0 or 1 in an array that is (@bytes * 8) long. Zero out to start.
+        #
+        @state = Array.new(@bytes*8) { 0 }
+      end
+
+      def after_initialize(options={})
+        super(options)
+
+        # Drive select pin high by default.
+        self.high
+      end
+    end
+  end
+end

data/lib/denko/spi/bit_bang.rb

@@ -0,0 +1,74 @@
+module Denko
+  module SPI
+    class BitBang
+      include Behaviors::MultiPin
+      include Behaviors::BusController
+      include Behaviors::Reader
+
+      def initialize_pins(options={})
+        # Allow pin aliases.
+        pins[:input]  = pins[:input]  || pins[:poci] || pins[:miso]
+        pins[:output] = pins[:output] || pins[:pico] || pins[:mosi]
+        pins[:clock]  = pins[:clock]  || pins[:sck]  || pins[:clk]
+
+        # Clean up the pins hash.
+        [:poci, :miso, :pico, :mosi, :sck, :clk].each { |key| pins.delete(key) }
+
+        # Validate input or output pin.
+        unless pins[:input] || pins[:output]
+          raise ArgumentError, "no input or output pin given. Require either or both"
+        end
+
+        # If only output or input, set the other 255 for a one-directional bus.
+        pins[:input]  = 255 if pins[:output] && !pins[:input]
+        pins[:output] = 255 if pins[:input]  && !pins[:output]
+
+        require_pins(:clock, :input, :output)
+      end
+
+      def transfer(select_pin, write: [], read: 0, frequency: nil, mode: 0, bit_order: :msbfirst)
+        board.spi_bb_transfer select_pin, clock: pins[:clock], output: pins[:output], input: pins[:input],
+                                          write: write, read: read, mode: mode, bit_order: bit_order
+      end
+
+      def listen(select_pin, read: 0, frequency: nil, mode: 0, bit_order: :msbfirst)
+        board.spi_bb_listen select_pin, clock: pins[:clock], input: pins[:input],
+                                        read: read, mode: mode, bit_order: bit_order
+      end
+
+      # Uses regular Board#spi_stop since listeners are shared.
+      def stop(pin)
+        board.spi_stop(pin)
+      end
+
+      # Delegate this to board so peripherals can initialize their select pins.
+      def set_pin_mode(*args)
+        board.set_pin_mode(*args)
+      end
+
+      def convert_pin(pin)
+        board.convert_pin(pin)
+      end
+
+      # Add peripheral to self and the board. It gets callbacks directly from the board.
+      def add_component(component)
+        # Treat pin 255 as the component having no select pin. Mostly for APA102.
+        return if component.pin == 255
+
+        pins = components.map { |c| c.pin }
+        if pins.include? component.pin
+          raise ArgumentError, "duplicate select pin for #{component}"
+        end
+
+        components << component
+        board.add_component(component)
+      end
+
+      # Remove peripheral from self and the board.
+      def remove_component(component)
+        components.delete(component)
+        board.remove_component(component)
+      end
+    end
+  end
+end

data/lib/denko/spi/bus.rb

@@ -0,0 +1,44 @@
+module Denko
+  module SPI
+    class Bus
+      include Behaviors::Component
+      include Behaviors::BusController
+      include Behaviors::Reader
+
+      # Board expects all components to have #pin.
+      attr_reader :pin
+
+      # Forward some methods directly to the board.
+      extend Forwardable
+
+      # Forward SPI methods with prefixed names.
+      def_delegator :board, :spi_transfer,  :transfer
+      def_delegator :board, :spi_listen,    :listen
+      def_delegator :board, :spi_stop,      :stop
+
+      # Forward pin control methods with same names for board proxying.
+      def_delegator :board, :convert_pin
+      def_delegator :board, :set_pin_mode
+
+      # Add peripheral to self and the board. It gets callbacks directly from the board.
+      def add_component(component)
+        # Treat pin 255 as the component having no select pin. Mostly for APA102.
+        return if component.pin == 255
+
+        pins = components.map { |c| c.pin }
+        if pins.include? component.pin
+          raise ArgumentError, "duplicate select pin for #{component}"
+        end
+
+        components << component
+        board.add_component(component)
+      end
+
+      # Remove peripheral from self and the board.
+      def remove_component(component)
+        components.delete(component)
+        board.remove_component(component)
+      end
+    end
+  end
+end

data/lib/denko/spi/input_register.rb

@@ -0,0 +1,130 @@
+module Denko
+  module SPI
+    class InputRegister < BaseRegister
+
+      def before_initialize(options={})
+        super(options)
+        #
+        # Keep track of whether anything is listening or reading a specific pin.
+        # This might be separate from whether a component is attached or not.
+        #
+        @reading_pins   = Array.new(@bytes*8) { false }
+        @listening_pins = Array.new(@bytes*8) { false }
+      end
+
+      def after_initialize(options={})
+        super(options)
+        enable_proxy
+      end
+
+      def read
+        spi_read(@bytes)
+      end
+
+      def listen
+        spi_listen(@bytes)
+      end
+
+      def stop
+        spi_stop
+      end
+
+      #
+      # BoardProxy interface
+      #
+      def digital_read(pin)
+        # Remember what pin was read and force callbacks to run next update.
+        add_callback(:force_update) { Proc.new{} }
+        @reading_pins[pin] = true
+
+        # Don't actually call #read if already listening.
+        read unless any_listening
+      end
+
+      def digital_listen(pin, divider)
+        listen unless any_listening
+        @listening_pins[pin] = true
+      end
+
+      def stop_listener(pin)
+        @listening_pins[pin] = false
+        stop unless any_listening
+      end
+
+      def any_listening
+        @listening_pins.each { |p| return true if p }
+        false
+      end
+
+      #
+      # Mimic Board#update, but in a callback fired through #update.
+      # This doesn't interfere with using the register directly,
+      # and doesn't fire if the board isn't acting as a proxy (no components).
+      #
+      def enable_proxy
+        self.add_callback(:board_proxy) do |bit_array|
+          bit_array.each_with_index do |value, pin|
+            components.each do |part|
+              update_component(part, pin, value) if pin == part.pin
+            end
+            @reading_pins[pin] = false
+          end
+        end
+      end
+
+      #
+      # Override Callbacks#update to make sure we handle :force_update
+      # within the main mutex lock.
+      #
+      def update(message)
+        bits = byte_array_to_bit_array(message.split(","))
+
+        @callback_mutex.synchronize {
+          #
+          # The Arduino code does not de-duplicate repeated state.
+          # Do it here, but if a :force_update callback exists, run anyway.
+          #
+          if (bits != @state)|| @callbacks[:force_update]
+            @callbacks.each_value do |array|
+              array.each { |callback| callback.call(bits) }
+            end
+          end
+
+          # Remove both :read and :force update while inside the lock.
+          @callbacks.delete(:read)
+          @callbacks.delete(:force_update)
+        }
+        @state = bits
+      end
+
+      def update_component(part, pin, value)
+        # Update if component is listening and value has changed.
+        if @listening_pins[pin] && (value != @state[pin])
+          part.update(value)
+        # Also update if the component forced a read.
+        elsif @reading_pins[pin] && @callbacks[:force_update]
+          part.update(value)
+        end
+      end
+
+      #
+      # Convert array of bytes coming from the register into an array of bits
+      # to update self state and give to component callbacks.
+      #
+      def byte_array_to_bit_array(byte_array)
+        #
+        # For each array element (1 byte):
+        # decimal number as string -> integer -> padded string of binary digits 
+        # -> reverse digits from reading order to array indexing order
+        # -> join digits of all bytes into one string
+        #
+        binary_string = byte_array.map do |byte|
+          byte.to_i.to_s(2).rjust(8, "0").reverse
+        end.join
+        
+        # Split the digits out of the string into individual integers.
+        binary_string.split("").map { |bit| bit.to_i }
+      end
+    end
+  end
+end

data/lib/denko/spi/output_register.rb

@@ -0,0 +1,67 @@
+module Denko
+  module SPI
+    class OutputRegister < BaseRegister
+
+      def before_initialize(options={})
+        super(options)
+        #
+        # When used as a board proxy, only write sate if @write_delay seconds
+        # have passed since this object last got input. Better for things like SSDs
+        # where many bits change in sequence, but not at exactly the same time.
+        #
+        @buffer_writes = true
+        @buffer_writes = false if options[:buffer_writes] == false
+        @write_delay = options[:write_delay] || 0.001
+      end
+      
+      def after_initialize(options={})
+        write
+      end
+
+      #
+      # Overrides Peripheral#write to always write @state.
+      # Convert bit state to array of 0-255 integers (bytes) first.
+      #
+      def write
+        bytes = []
+        @state.each_slice(8) do |slice|
+          # Convert nils in the slice to zero.
+          zeroed = slice.map { |bit| bit.to_i }
+          
+          # Each slice is 8 bits of a byte, with the lowest on the left.
+          # Reverse to reading order (lowest right) then join into string, and convert to integer.
+          byte = zeroed.reverse.join.to_i(2)
+          
+          # Pack bytes in reverse order.
+          bytes.unshift byte
+        end
+        spi_write(bytes)
+      end
+
+      #
+      # BoardProxy interface
+      #
+      def digital_write(pin, value)
+        state[pin] = value  # Might not be atomic?
+        @buffer_writes ? write_buffered(state) : write
+      end
+      
+      def digital_read(pin)
+        state[pin]
+      end
+
+      #
+      # If acting as board, do writes in a separate thread and with small delay.
+      # Lets us catch multiple changed bits, like when hosting an SSD.
+      #
+      include Behaviors::Threaded
+      def write_buffered(old_state)
+        threaded do
+          sleep @write_delay
+          # Keep delaying if state has changed.
+          write if (old_state == state)
+        end
+      end
+    end
+  end
+end

data/lib/denko/spi/peripheral.rb

@@ -0,0 +1,43 @@
+module Denko
+  module SPI
+    module Peripheral
+      include Behaviors::OutputPin
+      include Behaviors::Callbacks
+      include Behaviors::BusPeripheral
+
+      attr_reader :spi_frequency, :spi_mode, :spi_bit_order
+
+      def before_initialize(options={})
+        super(options)
+
+        # Save SPI settings.
+        @spi_frequency  = options[:spi_frequency]
+        @spi_mode       = options[:spi_mode]
+        @spi_bit_order  = options[:spi_bit_order]
+      end
+
+      #
+      # Delegate methods to the bus.
+      #
+      def spi_transfer(write: [], read: 0)
+        bus.transfer(pin, write: write, read: read, frequency: spi_frequency, mode: spi_mode, bit_order: spi_bit_order)
+      end
+
+      def spi_write(byte_array)
+        bus.transfer(pin, write: byte_array, frequency: spi_frequency, mode: spi_mode, bit_order: spi_bit_order)
+      end
+
+      def spi_read(num_bytes)
+        bus.transfer(pin, read: num_bytes, frequency: spi_frequency, mode: spi_mode, bit_order: spi_bit_order)
+      end
+
+      def spi_listen(num_bytes)
+        bus.listen(pin, read: num_bytes, frequency: spi_frequency, mode: spi_mode, bit_order: spi_bit_order)
+      end
+
+      def spi_stop
+        bus.stop(pin)
+      end
+    end
+  end
+end

data/lib/denko/spi.rb

@@ -0,0 +1,10 @@
+module Denko
+  module SPI
+    autoload :Bus,            "#{__dir__}/spi/bus"
+    autoload :BitBang,        "#{__dir__}/spi/bit_bang"
+    autoload :Peripheral,     "#{__dir__}/spi/peripheral"
+    autoload :BaseRegister,   "#{__dir__}/spi/base_register"
+    autoload :InputRegister,  "#{__dir__}/spi/input_register"
+    autoload :OutputRegister, "#{__dir__}/spi/output_register"
+  end
+end