denko 0.14.0 → 0.15.0

data/lib/denko/display/il0373.rb

@@ -0,0 +1,186 @@
+module Denko
+  module Display
+    class IL0373
+      include SPIEPaperCommon
+      include Behaviors::Lifecycle
+
+      COLUMNS = 212
+      ROWS    = 104
+
+      # Subset of used commands from datasheet:
+      PANEL_SETTING           = 0x00
+      POWER_SETTING           = 0x01
+      POWER_OFF               = 0x02
+      POWER_OFF_SEQUENCE      = 0x03
+      POWER_ON                = 0x04
+      POWER_ON_MEASURE        = 0x05
+      BOOSTER_SOFT_START      = 0x06
+      DEEP_SLEEP              = 0x07
+      DATA_START_1            = 0x10
+      DATA_STOP               = 0x11
+      DISPLAY_REFRESH         = 0x12
+      DATA_START_2            = 0x13
+      VCOM_DATA_SETTING       = 0x50
+      RESOLUTION_SETTING      = 0x61
+      PARTIAL_WINDOW          = 0x90
+      PARTIAL_IN              = 0x91
+      PARTIAL_OUT             = 0x92
+
+      def set_power_setting
+        # Defaults from datasheet.
+        command [POWER_SETTING]
+        data    [0x03, 0x00, 0x26, 0x26, 0x03]
+      end
+
+      def set_panel_setting
+        # NOT DEFAULTS
+        # From datasheet:
+        #   Bits 7..6: Enable all source and gate channels
+        #       Bit 5: 0 = LUT from OTP
+        #       Bit 4: 0 = B/W/R mode, 1 = B/W mode
+        #       Bit 3: 0 = Gate scan decrements (1 increments)
+        #       Bit 2: 0 = Source scan decrements (1 increments)
+        #       Bit 1: 1 = Enable booster
+        #       Bit 0: 1 = Soft reset
+        value  = 0b0000_0011
+
+        # Handle colors
+        value |= (1 << 4) if colors == 2
+
+        # Handle screen size
+        source_gate_bits = 0b11
+        source_gate_bits = 0b10 if (rows <= 128)
+        source_gate_bits = 0b01 if (rows <= 96) && (columns <= 252)
+        source_gate_bits = 0b00 if (rows <= 96) && (columns <= 230)
+        value |= source_gate_bits
+
+        # Handle hardware reflection/rotation
+        value |= (1 << 2) if @reflect_y
+        value |= (1 << 3) if @reflect_x
+
+        command [PANEL_SETTING]
+        data    [value]
+      end
+
+      def reflect_x
+        @reflect_x = !@reflect_x
+      end
+
+      def reflect_y
+        @reflect_y = !@reflect_y
+      end
+
+      def rotate
+        @reflect_x = !@reflect_x
+        @reflect_y = !@reflect_y
+      end
+
+      def set_vcom_data_setting
+        # Default value from data sheet.
+        value = 0b0000_0111
+
+        # Datsheet may be wrong here. Bit 5 set seems to always invert DATA2, so Bit 4 does DATA1?
+        #   In B/W mode:   set bit 5 to avoid black channel inversion relative to Canvas.
+        #   In B/W/R mode: set bit 4 to avoid black channel inversion relative to Canvas.
+        if (colors == 2)
+          value |= (1 << 4) unless @invert_black
+        else
+          value |= (1 << 5) unless @invert_black
+        end
+
+        command [VCOM_DATA_SETTING]
+        data    [value]
+      end
+
+      def invert_black
+        @invert_black = !@invert_black
+      end
+
+      def set_resolution
+        command [RESOLUTION_SETTING]
+        data [
+          p_max+1 << 3,
+          (columns >> 8) & 0b1,
+          columns & 0xFF
+        ]
+      end
+
+      def booster_soft_start
+        # Defaults from datasheet.
+        command [BOOSTER_SOFT_START]
+        data    [0x17, 0x17, 0x17]
+      end
+
+      def power_on
+        command [POWER_ON]
+        busy_wait
+      end
+
+      def wake
+        hw_reset
+        set_power_setting
+        set_panel_setting
+        set_vcom_data_setting
+        set_resolution
+        booster_soft_start
+        power_on
+      end
+
+      def deep_sleep
+        # Default from datasheet.
+        command [DEEP_SLEEP]
+        data    [0xA5]
+      end
+
+      # Treat what the datasheet calls x as vertical (y, page), and vertical as horizontal (x).
+      def set_window(x_start=x_min, x_finish=x_max, p_start=p_min, p_finish=p_max)
+        command [PARTIAL_WINDOW]
+        data [
+          p_start  << 3,
+          p_finish << 3,
+          (x_start >> 8) & 0b1,
+          x_start & 0xFF,
+          (x_finish >> 8) & 0b1,
+          x_finish & 0xFF,
+          0b0
+        ]
+        command [PARTIAL_IN]
+      end
+
+      def draw(*args, **kwargs)
+        wake
+        super(*args, **kwargs)
+      end
+
+      def draw_partial(buffer, x_start, x_finish, p_start, p_finish, color=1)
+        set_window(x_start, x_finish, p_start, p_finish)
+
+        if (colors == 2)
+          # In B/W/Red mode, red goes in DATA2, black in DATA1
+          (color == 2) ? command[DATA_START_2] : command[DATA_START_1]
+        else
+          # In B/W mode, always write to DATA2
+          command [DATA_START_2]
+        end
+
+        # Can't control address increment to go horizontally, always vertical.
+        # So get partial from the full buffer and reorder the bytes.
+        transformed_buffer = []
+        (x_start..x_finish).each do |x|
+          (p_start..p_finish).to_a.reverse.each do |page|
+            index = (page * columns) + x
+            transformed_buffer << buffer[index]
+          end
+        end
+        transformed_buffer.each_slice(transfer_limit) { |slice| data(slice) }
+
+        command [DATA_STOP]
+      end
+
+      def refresh
+        command [DISPLAY_REFRESH]
+        busy_wait
+      end
+    end
+  end
+end

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

@@ -1,40 +1,36 @@
-require_relative 'ssd1306'
-
 module Denko
   module Display
-    class SH1106 < SSD1306
+    class SH1106
+      include MonoOLED
       #
-      # Unlike the SSD1306, SH1106 only supports page addressing mode.
+      # 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(x_min=0, x_max=(@columns-1), y_min=0, y_max=(@rows-1))
-        # Convert y-coords to page coords.
-        p_min = y_min / 8
-        p_max = y_max / 8
-
-        # Offset x_min by 2, since SH1106 has RAM for 132 columns, but we only use 128, then convert to nibbles.
-        x = x_min + 2
+      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_min..p_max).each do |page|
+        (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_min
-          src_end   = (@columns * page) + x_max
-          buffer    = canvas.framebuffer[src_start..src_end]
+          src_start       = (columns * page) + x_start
+          src_end         = (columns * page) + x_finish
+          partial_buffer  = buffer[src_start..src_end]
 
-          # Send all bytes at once if within limit, or split into chunks.
-          if buffer.length < (bus.board.i2c_limit - 1)
-            data(buffer)
-          else  
-            buffer.each_slice(bus.board.i2c_limit - 1) { |slice| data(slice) }
-          end
+          # Send in chunks up to maximum transfer size.
+          partial_buffer.each_slice(transfer_limit) { |slice| data(slice) }
         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