denko 0.13.6 → 0.15.0

data/lib/denko/display/mono_oled.rb

@@ -0,0 +1,193 @@
+module Denko
+  module Display
+    module MonoOLED
+      include Behaviors::BusPeripheral
+      include Behaviors::Lifecycle
+
+      # I2C Defaults
+        I2C_ADDRESS   = 0x3C
+        I2C_FREQUENCY = 400_000
+
+      # Fundamental Commands
+        # Single byte (no need to OR with anything)
+        PIXELS_FROM_RAM = 0xA4
+        PIXELS_ALL_ON   = 0xA5
+        INVERT_OFF      = 0xA6
+        INVERT_ON       = 0xA7
+        DISPLAY_OFF     = 0xAE
+        DISPLAY_ON      = 0xAF
+
+        # Double byte (following byte sets value)
+        CONTRAST        = 0x81
+          # Values: 0x00 to 0xFF. Default is 0x7F
+
+      # Scrolling commands ignored.
+
+      # Address Setting Commands
+        # Single byte. OR with value. These are for page addressing mode only.
+        COLUMN_START_LOWER = 0x00 # lower 4 bytes of column
+        COLUMN_START_UPPER = 0x10 # upper 4 bytes of column
+        PAGE_START         = 0xB0 # page 0-7
+
+        # Double byte. Following byte sets value.
+        ADDRESSING_MODE  = 0x20
+          # Values:
+          #   0x00 = horizontal (Pages auto-increment. Used for SSD1306)
+          #   0x01 = vertical
+          #   0x02 = page       (Default. Page and column must be set each time. Needed on SH1106, SH1107)
+        ADDRESSING_MODE_DEFAULT = 0x00
+
+        # Triple byte. Following 2 bytes sets value. For H/V addressing modes only.
+        COLUMN_ADDRESS_RANGE = 0x21
+        PAGE_ADDRESS_RANGE   = 0x22
+          # For both: first value = min column/row, second value = max column/row
+
+      # Hardware Configuration Commands
+        # Single byte. OR with value.
+        START_LINE      = 0x40  # Value: lowest 6 bits set RAM start line (default 0b000000)
+        SEGMENT_REMAP   = 0xA0  # Value: 0x00 = default, 0x01 = column draw order reversed (horizontal reflection)
+        COM_DIRECTION   = 0xC0  # Value: 0x00 = default, 0x08 = row draw order reversed (vertical reflection)
+
+        # Double-byte commands. Following byte sets value.
+        CHARGE_PUMP = 0x8D  # Value: 0x10 = disable/external, 0x14 = enable/internal
+        MULTIPLEX_RATIO = 0xA8  # Value: rows of display - 1
+        DISPLAY_OFFSET  = 0xD3  # Value: lowest 5 bits. Vertically shifts COM by that amount.
+        COM_PIN_CONFIG  = 0xDA
+          # 0x02 = sequential, left and right not swapped
+          # 0x12 = alternative, left and right not swapped (default)
+          # 0x22 = sequential, left and right sawpped
+          # 0x32 = alternative, left and right swapped
+
+      # Timing & Driving Commands
+        # Double-byte commands. Following byte sets value.
+        CLOCK               = 0xD5  # Lowest 4 bits = divider. Upper 4 bits = oscillator frequency.
+        PRECHARGE_PERIOD    = 0xD9  # Lowest 4 bits = phase 1. Upper 4 bits = phase 2. 0xF1 for internal charge pump. 0x22 for external.
+        VCOM_DESELECT_LEVEL = 0xDB  # 0x00 = 0.65 x Vcc, 0x20 = x 0.77 * Vcc (default), 0x30 = 0.83 x Vcc
+
+      # Valid widths and heights for displays
+      WIDTHS  = [64,96,128]
+      HEIGHTS = [16,32,48,64,128]
+
+      # Default to a 128x64 display.
+      COLUMNS = 128
+      ROWS    = 64
+
+      # Decide whether this instance is I2C or SPI.
+      before_initialize do
+        bus = params[:bus] || params[:board]
+
+        if bus.class.ancestors.include?(Denko::I2C::BusCommon)
+          mutate_i2c
+        elsif bus.class.ancestors.include?(Denko::SPI::BusCommon)
+          mutate_spi
+        else
+          raise ArgumentError, "#{self.class} must be connected to either an I2C or SPI bus"
+        end
+      end
+
+      def mutate_i2c
+        singleton_class.class_eval do
+          include I2C::Peripheral
+          include PixelCommon
+
+          # Commands are I2C messages prefixed with 0x00.
+          def command(bytes)
+            i2c_write([0x00] + bytes)
+          end
+
+          # Data are I2C messages prefixed with 0x40.
+          def data(bytes)
+            i2c_write([0x40] + bytes)
+          end
+
+          # Data prefix always takes one byte, so subtract that.
+          def transfer_limit
+            @transfer_limit ||= bus.board.i2c_limit - 1
+          end
+        end
+      end
+
+      def mutate_spi
+        singleton_class.class_eval do
+          include SPICommon
+        end
+      end
+
+      after_initialize do
+        # Validate known sizes.
+        raise ArgumentError, "error in #{self.class} width: #{columns}. Must be in: #{WIDTHS.inspect}" unless WIDTHS.include?(columns)
+        raise ArgumentError, "error in #{self.class} height: #{rows}. Must be in: #{HEIGHTS.inspect}" unless HEIGHTS.include?(rows)
+
+        # Everything except 96x16 size uses clock 0x80.
+        clock = 0x80
+        clock = 0x60 if (columns == 96 && rows == 16)
+
+        # 128x32 and 96x16 sizes use com pin config 0x02
+        com_pin_config = 0x12
+        com_pin_config = 0x02 if (columns == 96 && rows == 16) || (columns == 128 && rows == 32)
+
+        # Defaul to no reflection or rotation.
+        @seg_remap     = 0x00
+        @com_direction = 0x00
+
+        # Startup sequence. SPI needs 2 repeats for some reason.
+        startup_count = 1
+        startup_count = 2 if singleton_class.ancestors.include? Denko::SPI::Peripheral
+        startup_count.times do
+          command [
+            MULTIPLEX_RATIO,        rows - 1,
+            DISPLAY_OFFSET,         0x00,
+            START_LINE            | 0x00,
+            SEGMENT_REMAP         | @seg_remap,
+            COM_DIRECTION         | @com_direction,
+            COM_PIN_CONFIG,         com_pin_config,
+            PIXELS_FROM_RAM,
+            INVERT_OFF,
+            CLOCK,                  clock,
+            VCOM_DESELECT_LEVEL,    0x20,
+            PRECHARGE_PERIOD,       0xF1, # Charge period for internal charge pump
+            CHARGE_PUMP,            0x14, # Internal charge pump
+            ADDRESSING_MODE,        self.class::ADDRESSING_MODE_DEFAULT,
+            DISPLAY_ON
+          ]
+        end
+
+        draw
+      end
+
+      def off
+        command [DISPLAY_OFF]
+      end
+
+      def on
+        command [DISPLAY_ON]
+      end
+
+      def contrast=(value)
+        raise ArgumentError, "contrast must be in range 0..255" if (value < 0 || value > 255)
+        command [CONTRAST, value]
+      end
+
+      def reflect_x
+        # Swap @seg_remap to the other value and write it.
+        @seg_remap = (@seg_remap == 0x00) ? 0x01 : 0x00
+        command [SEGMENT_REMAP | @seg_remap]
+      end
+
+      def reflect_y
+        # Swap @com_direction to the other value and write it.
+        @com_direction = (@com_direction == 0x00) ? 0x08 : 0x00
+        command [COM_DIRECTION | @com_direction]
+      end
+
+      def rotate
+        reflect_x
+        reflect_y
+      end
+
+      def draw_partial(buffer, x_min, x_max, p_min, p_max)
+        raise NotImplementedError, "#draw_partial must be implemented for each class including MonoOLED"
+      end
+    end
+  end
+end

data/lib/denko/display/pcd8544.rb

@@ -0,0 +1,154 @@
+module Denko
+  module Display
+    class PCD8544
+      include Behaviors::Lifecycle
+      include SPICommon
+
+      COLUMNS = 84
+      ROWS    = 48
+
+      FUNCTION_SET = 0b00100000
+      # OR these options into lowest 3 bits:
+      POWER_UP      = 0b000
+      POWER_DOWN    = 0b100
+      H_ADDRESSING  = 0b00
+      V_ADDRESSING  = 0b10
+      BASIC_INS_SET = 0b0
+      EXT_INS_SET   = 0b1
+
+      #
+      # Basic Instruciton Set (H = 0)
+      #
+      DISPLAY_CONTROL_SET = 0b00001000
+      # OR these options into lowest 3 bits:
+      DISPLAY_BLANK    = 0b000
+      DISPLAY_NORMAL   = 0b100
+      DISPLAY_ALL_SEGS = 0b001
+      DISPLAY_INVERT   = 0b101
+
+      RAM_Y_SET = 0b01000000 # OR Y value into lowest 3 bits
+      RAM_X_SET = 0b10000000 # OR X value into lowest 7 bits
+
+      #
+      # Extended Instruciton Set (H = 1)
+      #
+      TEMP_COEFF_SET = 0b00000100 # OR temperature coeff. into lowest 2 bits
+      BIAS_SET       = 0b00010000 # OR bias system values into lowest 3 bits
+      VOP_SET        = 0b10000000 # OR VOP values into lowest 7 bits
+
+      def power_up
+        @function_state = (function_state & 0b11111011) | POWER_UP
+        command [function_state]
+      end
+
+      def power_down
+        @function_state = (function_state & 0b11111011) | POWER_DOWN
+        command [function_state]
+      end
+
+      def basic_instruction_mode
+        @function_state = (function_state & 0b11111110) | BASIC_INS_SET
+        command [function_state]
+      end
+
+      def extended_instruction_mode
+        @function_state = (function_state & 0b11111110) | EXT_INS_SET
+        command [function_state]
+      end
+
+      def function_state
+        @function_state ||= FUNCTION_SET
+      end
+
+      VALID_VOPS = (0..127).to_a
+
+      def vop=(value)
+        raise ArgumentError, "invalid Vop: #{value}" unless VALID_VOPS.include?(value)
+        extended_instruction_mode
+        command [VOP_SET | value]
+        basic_instruction_mode
+        @vop = value
+      end
+
+      VALID_BIASES = (0..7).to_a
+
+      def bias=(value)
+        raise ArgumentError, "invalid bias: #{value}" unless VALID_BIASES.include?(value)
+        extended_instruction_mode
+        command [BIAS_SET | value]
+        basic_instruction_mode
+        @bias = value
+      end
+
+      VALID_TCOEFFS = (0..3).to_a
+
+      def temperature_coefficient=(value)
+        raise ArgumentError, "invalid temperature coefficient: #{value}" unless VALID_TCOEFFS.include?(value)
+        extended_instruction_mode
+        command [TEMP_COEFF_SET | value]
+        basic_instruction_mode
+        @temperature_coefficient = value
+      end
+
+      def vop
+        @vop ||= 0
+      end
+
+      def bias
+        @bias ||= 0
+      end
+
+      def temperature_coefficient
+        @temperature_coefficient ||= 0
+      end
+
+      def set_display_control(value)
+        command [DISPLAY_CONTROL_SET | value]
+      end
+
+      def blank
+        set_display_control(DISPLAY_BLANK)
+      end
+
+      def all_segments_on
+        set_display_control(DISPLAY_ALL_SEGS)
+      end
+
+      def invert
+        @inverted = !@inverted
+        value = @inverted ? DISPLAY_INVERT : DISPLAY_NORMAL
+        set_display_control(value)
+      end
+
+      after_initialize do
+        # Reset sequence.
+        reset.low if reset
+        sleep 0.001
+        reset.high if reset
+
+        self.vop = 56
+        self.bias = 4
+        set_display_control(DISPLAY_NORMAL)
+        self.temperature_coefficient = 0
+      end
+
+      def draw_partial(buffer, x_start, x_finish, p_start, p_finish, color=1)
+        # Always use horizontal addressing mode.
+        basic_instruction_mode
+
+        (p_start..p_finish).each do |page|
+          # Set start page and column.
+          command [RAM_X_SET | x_start, RAM_Y_SET | page]
+
+          # Get needed bytes for this page only.
+          src_start       = (columns * page) + x_start
+          src_end         = (columns * page) + x_finish
+          partial_buffer  = buffer[src_start..src_end]
+
+          # Send in chunks up to maximum transfer size.
+          partial_buffer.each_slice(transfer_limit) { |slice| data(slice) }
+        end
+      end
+    end
+  end
+end

data/lib/denko/display/pixel_common.rb

@@ -0,0 +1,83 @@
+module Denko
+  module Display
+    module PixelCommon
+      def columns
+        return @columns if @columns
+        @columns = self.class.const_get("COLUMNS") if self.class.const_defined?("COLUMNS")
+        @columns = params[:width] if params[:width]
+        @columns = params[:columns] if params[:columns]
+        @columns
+      end
+      alias :cols :columns
+
+      def rows
+        return @rows if @rows
+        @rows = self.class.const_get("ROWS") if self.class.const_defined?("ROWS")
+        @rows = params[:height] if params[:height]
+        @rows = params[:rows] if params[:rows]
+        @rows
+      end
+
+      def x_min
+        @x_min ||= 0
+      end
+
+      def x_max
+        @x_max ||= columns - 1
+      end
+
+      def y_min
+        @y_min ||= 0
+      end
+
+      def y_max
+        @y_max ||= rows - 1
+      end
+
+      def p_min
+        @p_min ||= 0
+      end
+
+      def p_max
+        @p_max ||= (rows / 8.0).ceil - 1
+      end
+
+      def colors
+        @colors ||= params[:colors] || 1
+      end
+
+      def canvas
+        @canvas ||= Canvas.new(columns, rows, colors: colors)
+      end
+
+      def refresh
+      end
+
+      def get_partial_buffer(buffer, x_start, x_finish, p_start, p_finish)
+        # If bounds == max bounds, just return the buffer.
+        return buffer if (x_start == x_min) && (x_finish == x_max) && (p_start == p_min) && (p_finish == p_max)
+
+        # Copy bytes for the given rectangle into a temp buffer.
+        temp_buffer = []
+        (p_start..p_finish).each do |page|
+          src_start = (columns * page) + x_start
+          src_end   = (columns * page) + x_finish
+          temp_buffer += buffer[src_start..src_end]
+        end
+        temp_buffer
+      end
+
+      def draw(x_start=x_min, x_finish=x_max, y_start=y_min, y_finish=y_max)
+        # Convert y-coords to page coords.
+        p_start  = y_start  / 8
+        p_finish = y_finish / 8
+
+        colors.times do |i|
+          draw_partial(canvas.framebuffers[i], x_start, x_finish, p_start, p_finish, i+1)
+        end
+
+        refresh
+      end
+    end
+  end
+end

data/lib/denko/display/sh1106.rb

@@ -0,0 +1,38 @@
+module Denko
+  module Display
+    class SH1106
+      include MonoOLED
+      #
+      # SH1106/SH1107 only support page addressing mode.
+      # Can't send all data as sequential pages and let page index auto-increment,
+      # like with horizontal addressing on the SSD1306.
+      #
+      ADDRESSING_MODE_DEFAULT = 0x02
+      RAM_X_OFFSET = 2
+      #
+      # SH1106 has RAM for 132 columns, but only 128 pixels, so offset by 2 to center.
+      def ram_x_offset
+        @ram_x_offset ||= self.class.const_get("RAM_X_OFFSET")
+      end
+
+      def draw_partial(buffer, x_start, x_finish, p_start, p_finish, color=1)
+        x = x_start + ram_x_offset
+        x_lower = (x & 0b00001111)
+        x_upper = (x & 0b11110000) >> 4
+
+        (p_start..p_finish).each do |page|
+          # Set the page and column to start writing at.
+          command [PAGE_START | page, COLUMN_START_LOWER | x_lower, COLUMN_START_UPPER | x_upper]
+
+          # Get needed bytes for this page only.
+          src_start       = (columns * page) + x_start
+          src_end         = (columns * page) + x_finish
+          partial_buffer  = buffer[src_start..src_end]
+
+          # Send in chunks up to maximum transfer size.
+          partial_buffer.each_slice(transfer_limit) { |slice| data(slice) }
+        end
+      end
+    end
+  end
+end

data/lib/denko/display/sh1107.rb

@@ -0,0 +1,10 @@
+module Denko
+  module Display
+    class SH1107 < SH1106
+      COLUMNS = 128
+      ROWS    = 128
+      # SH1107 RAM has 128 columns, unlike 132 on SH1106. Don't offset by 2.
+      RAM_X_OFFSET = 0
+    end
+  end
+end

data/lib/denko/display/spi_common.rb

@@ -0,0 +1,35 @@
+module Denko
+  module Display
+    module SPICommon
+      include SPI::Peripheral
+      include PixelCommon
+
+      #
+      # SPI displays use a D/C pin to toggle whether bytes being sent are data or commands.
+      # Most also have a RESET pin which is pulsed low to initalize, then held high.
+      #
+      def initialize_pins(options={})
+        super(options)
+        proxy_pin :dc,    DigitalIO::Output
+        proxy_pin :reset, DigitalIO::Output, optional: true
+        reset.high if reset
+      end
+
+      # Commands are SPI bytes written while DC pin is low.
+      def command(bytes)
+        dc.low
+        spi_write(bytes)
+      end
+
+      # Display data are SPI SPI bytes written while DC pin is high.
+      def data(bytes)
+        dc.high
+        spi_write(bytes)
+      end
+
+      def transfer_limit
+        @transfer_limit ||= bus.board.spi_limit
+      end
+    end
+  end
+end

data/lib/denko/display/spi_epaper_common.rb

@@ -0,0 +1,30 @@
+module Denko
+  module Display
+    module SPIEPaperCommon
+      include SPICommon
+
+      # Defaults. Override in subclasses as needed.
+      BUSY_WAIT_TIME = 0.005
+      RESET_TIME     = 0.010
+
+      def initialize_pins(options={})
+        super(options)
+        proxy_pin :busy, DigitalIO::Input, board: bus.board
+        busy.stop
+      end
+
+      def busy_wait
+        # #read is more compatible than #listen
+        sleep self.class::BUSY_WAIT_TIME while busy.read == 1
+      end
+
+      def hw_reset
+        if reset
+          reset.low
+          sleep self.class::RESET_TIME
+          reset.high
+        end
+      end
+    end
+  end
+end