denko 0.14.0 → 0.15.0

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

data/lib/denko/display/ssd1306.rb

@@ -1,238 +1,16 @@
-require_relative 'canvas'
-
 module Denko
   module Display
     class SSD1306
-      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)
-        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]
-
-      attr_accessor :canvas
-
-      # Default to a 128x64 display.
-      def columns
-        @columns ||= params[:columns] || params[:width] || 128
-      end
-
-      def rows
-        @rows ||= params[:rows] || params[:height] || 64
-      end
-
-      def rotated
-        return @rotated unless @rotated.nil?
-        @rotated = params[:rotated]
-        @rotated = params[:rotate] if @rotated.nil?
-        @rotated = false if @rotated.nil?
-        @rotated
-      end
-
-      # Decide whether this instnace is I2C or SPI.
-      before_initialize do
-        bus = params[:bus] || params[:board]
-
-        if bus.class.ancestors.include?(Denko::SPI::Bus) || bus.class.ancestors.include?(Denko::SPI::BitBang)
-          mutate_spi
-        elsif bus.class.ancestors.include?(Denko::I2C::Bus) || bus.class.ancestors.include?(Denko::I2C::BitBang)
-          mutate_i2c
-        else
-          raise ArgumentError, "#{self.class} must be connected to either an I2C or SPI bus"
-        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)
+      include MonoOLED
 
-        # Reflecting horizontally and vertically to effectively rotate 180 degrees.
-        seg_remap     = rotated ? 0x01 : 0x00
-        com_direction = rotated ? 0x08 : 0x00
+      def draw_partial(buffer, x_start, x_finish, p_start, p_finish, color=1)
+        partial_buffer = get_partial_buffer(buffer, x_start, x_finish, p_start, p_finish)
 
-        # Startup sequence (SPI doesn't work properly if this isn't sent twice.)
-        2.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
-
-        # Create a new blank canvas and draw it.
-        self.canvas = Canvas.new(columns, rows)
-        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 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
-
-        # If drawing the whole frame (default), bypass temp buffer to save time.
-        if (x_min == 0) && (x_max == columns-1) && (p_min == 0) && (p_max == rows/8)
-          draw_partial(canvas.framebuffer, x_min, x_max, p_min, p_max)
-
-        # Copy bytes for the given rectangle into a temp buffer.
-        else
-          temp_buffer = []
-          (p_min..p_max).each do |page|
-            src_start = (columns * page) + x_min
-            src_end   = (columns * page) + x_max
-            temp_buffer += canvas.framebuffer[src_start..src_end]
-          end
-
-          # And draw them.
-          draw_partial(temp_buffer, x_min, x_max, p_min, p_max)
-        end
-      end
-
-      def draw_partial(buffer, x_min, x_max, p_min, p_max)
         # Limit auto-incrementing GRAM address to the rectangle being drawn.
-        command [ COLUMN_ADDRESS_RANGE, x_min, x_max, PAGE_ADDRESS_RANGE, p_min, p_max ]
-
-        # Send all the bytes at once if within board I2C limit.
-        if buffer.length < (bus.board.i2c_limit - 1)
-          data(buffer)
-
-        # Or split into chunks.
-        else
-          buffer.each_slice(bus.board.i2c_limit - 1) { |slice| data(slice) }
-        end
-      end
-
-      def mutate_i2c
-        singleton_class.class_eval do
-          include I2C::Peripheral
-
-          # 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
-        end
-      end
-
-      def mutate_spi
-        singleton_class.class_eval do
-          include SPI::Peripheral::MultiPin
-
-          def initialize_pins(options={})
-            super(options)
-            proxy_pin :dc,    DigitalIO::Output, board: bus.board
-            proxy_pin :reset, DigitalIO::Output, board: bus.board, optional: true
-            reset.high if reset
-          end
-
-          # Commands are SPI bytes written while DC pin low.
-          def command(bytes)
-            dc.low
-            spi_write(bytes)
-          end
+        command [ COLUMN_ADDRESS_RANGE, x_start, x_finish, PAGE_ADDRESS_RANGE, p_start, p_finish ]
 
-          # Data are SPI SPI bytes written while DC pin high.
-          def data(bytes)
-            dc.high
-            spi_write(bytes)
-          end
-        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/ssd1680.rb

@@ -0,0 +1,14 @@
+module Denko
+  module Display
+    class SSD1680 < SSD168X
+      COLUMNS = 296
+      ROWS    = 128
+
+      # SSD1680 needs an extra byte here to offset source start by 8 pixels.
+      def set_display_update_control
+        super
+        data [0b1000_0000]
+      end
+    end
+  end
+end

data/lib/denko/display/ssd1681.rb

@@ -0,0 +1,8 @@
+module Denko
+  module Display
+    class SSD1681 < SSD168X
+      COLUMNS = 200
+      ROWS    = 200
+    end
+  end
+end

data/lib/denko/display/ssd168x.rb

@@ -0,0 +1,227 @@
+module Denko
+  module Display
+    class SSD168X
+      include Behaviors::Lifecycle
+      include SPIEPaperCommon
+
+      # Used by #hw_reset
+      RESET_TIME = 0.010
+
+      # Typical Commands
+      SW_RESET                = 0x12
+      DRIVER_OUTPUT_CTL       = 0x01 # +3 data
+      DATA_ENTRY_MODE_SET     = 0x11 # +1 data
+      BORDER_WAVEFORM_CTL     = 0x3C # +1 data
+      DISPLAY_UPDATE_CTL1     = 0x21 # +1 data
+      TEMP_SENSOR_SELECT      = 0x18 # +1 data
+      RAM_X_RANGE_SET         = 0x44 # +2 data. X address range to stay within.
+      RAM_Y_RANGE_SET         = 0x45 # +4 data. Y address range to stay within.
+      RAM_X_ADDR_SET          = 0x4E # +1 data. X start address
+      RAM_Y_ADDR_SET          = 0x4F # +2 data. Y start address
+      RAM_WRITE_BW            = 0x24 # write n pixel data bytes after
+      RAM_WRITE_RED           = 0x26 # write n pixel data bytes after
+      MASTER_ACTIVATION       = 0x20
+      DISPLAY_UPDATE_CTL2     = 0x22 # +1 data
+      DEEP_SLEEP              = 0x10 # +1 data
+      BOOSTER_CTL             = 0x0C # +4 data
+
+      #
+      # Other commands taken from data sheet.
+      # Not used yet. Maybe for enabling more features in future?
+      #
+      RAM_AUTO_INC_BW         = 0x46 # +1 data. This sets the auto-increment amount?
+      RAM_AUTO_INC_RED        = 0x47 # +1 data. This sets the auto-increment amount?
+      READ_RAM                = 0x27 # read n pixel data bytes after
+      GATE_VOLTAGE_CTL        = 0x03 # +1 data
+      SOURCE_VOLTAGE_CTL      = 0x04 # +3 data
+      INITIAL_CODE_OTP        = 0x08 # ???
+      INITIAL_CODE_REG_SET    = 0x08 # +3 data
+      INITIAL_CODE_REG_GET    = 0x0A # Read 3 bytes back? Datasheet not clear.
+      HV_READY_DETECTION      = 0x14 # +1 data
+      VCI_DETECTION           = 0x15 # +1 data
+      TEMP_SENSOR_REG_SET     = 0x1A # +2 data
+      TEMP_SENSOR_REG_GET     = 0x1B # +2 data READ
+      TEMP_SENSOR_CTL         = 0x1C # +3 data
+      VCOM_SENSE              = 0x28
+      VCOM_SENS_DURATION      = 0x29 # +1 data
+      PROGRAM_VCOM_OTP        = 0x2A # +1 data
+      VCOM_REG_CTL            = 0x2B # +2 data
+      VCOM_REG_WRITE          = 0x2C # +1 data
+      OTP_REG_GET             = 0x2D # +11 data READ
+      USER_ID_GET             = 0x2E # +10 data READ
+      STATUS_BIT_GET          = 0x2F # +1 data READ
+      PROGRAM_WS_OTP          = 0x30
+      LOAD_WS_OTP             = 0x31
+      WRITE_LUT_REGISTER      = 0x32 # +153 data
+      CRC_CALCULATION         = 0x34
+      CRC_STATUS_GET          = 0x35 # +2 data READ
+      PROGRAM_OTP_SELECTION   = 0x36
+      DISPLAY_OPTION_REG_SET  = 0x37 # +10 data
+      USER_ID_REG_SET         = 0x38 # +10 data
+      OTP_PROGRAM_MODE        = 0x39 # +1 data
+      END_OPTION              = 0x3F # +1 data
+      READ_RAM_OPTION         = 0x41 # +1 data
+      NOP                     = 0x7F
+
+      def set_driver_output_control(gate_lines=columns)
+        # First data byte is lowest 8 bits of MUX value.
+        # Second data byte is 9th bit.
+        mux = gate_lines - 1
+
+        # Third byte:
+        #   Bit 2: toggles gate scan interleave order
+        #   Bit 1: enables gate scan interleaving
+        #   Bit 0: flips gate scan direction, mirroring display in 1 axis
+        third_byte = @reflect_x ? 0b000 : 0b001
+
+        command [DRIVER_OUTPUT_CTL]
+        data    [mux & 0xFF, (mux >> 8) & 0b1, third_byte]
+      end
+
+      def reflect_x
+        @reflect_x = !@reflect_x
+      end
+
+      def set_data_entry_mode
+        # Bit 2 = 1 : update hardware Y (software X) address first (after each byte),
+        # then update hardware X (software P) on overflow. (0 would update hardware X / software P first)
+        # Bit 1 = 1 : increment hardware Y (0 would decrement)
+        # Bit 0 = 1 : increment hardware X (0 would decrement)
+        command [DATA_ENTRY_MODE_SET]
+        data    [0b111]
+      end
+
+      # Treating hardware X axis as page (P) axis, and hardware Y axis as X axis to match framebuffer.
+      def set_range_x(start=x_min, finish=x_max)
+        command [RAM_Y_RANGE_SET]
+        data    [start & 0xFF, (start >> 8) & 0b1, finish & 0xFF, (finish >> 8) & 0b1]
+      end
+
+      def set_range_p(start=p_min, finish=p_max)
+        command [RAM_X_RANGE_SET]
+        data    [start, finish]
+      end
+
+      def set_address_x(addr=x_min)
+        command [RAM_Y_ADDR_SET]
+        data    [addr & 0xFF, (addr >> 8) & 0b1]
+      end
+
+      def set_address_p(addr=p_min)
+        command [RAM_X_ADDR_SET]
+        data    [addr]
+      end
+
+      def set_panel_border
+        # Default to GS Transition: Follow LUT and LUT1, and VBD fix level: VSS.
+        command [BORDER_WAVEFORM_CTL]
+        data    [0b00_00_00_01]
+      end
+
+      def set_temperature_sensor
+        # Use internal temperature sensor
+        command [TEMP_SENSOR_SELECT]
+        data [0x80]
+      end
+
+      def set_display_update_control
+        # In hardware:
+        #   0b1000: display inverted
+        #   0b0100: bypass
+        #   0b0000: display normally
+        #
+        # For black only, hardware treats 1 as blank, 0 as filled. Opposite of Canvas.
+        black = @invert_black ? 0b0000 : 0b1000
+        red   = (colors == 1) ? 0b0100 : 0b0000
+
+        command [DISPLAY_UPDATE_CTL1]
+        data    [red << 4 | black]
+      end
+
+      def invert_black
+        @invert_black = !@invert_black
+      end
+
+      def set_display_update_sequence(value=0x80)
+        # 0x80 enables clock signal without loading pixels from RAM
+        # 0xF7 refreshes all pixels from RAM
+        command [DISPLAY_UPDATE_CTL2]
+        data    [value]
+      end
+
+      def booster_soft_start
+        command [BOOSTER_CTL]
+        data [
+          0b1010_0011, # phase 1
+          0b1100_0111, # phase 2
+          0b1100_0011, # phase 3
+          0b0000_0001, # duration
+        ]
+      end
+
+      def master_activate
+        command [MASTER_ACTIVATION]
+      end
+
+      def deep_sleep(sleep_mode=0b11)
+        # 0b00 = Normal Mode
+        # 0b01 = Deep Sleep Mode 1
+        # 0b11 = Deep Sleep Mode 2
+        command [DEEP_SLEEP]
+        data    [sleep_mode]
+      end
+
+      def wake
+        hw_reset
+        command [SW_RESET]
+        sleep 0.020
+
+        set_driver_output_control
+        set_data_entry_mode
+        set_temperature_sensor
+        set_panel_border
+
+        set_display_update_control
+        set_display_update_sequence
+        master_activate
+        busy_wait
+      end
+
+      after_initialize do
+        wake
+      end
+
+      def draw_partial(buffer, x_start, x_finish, p_start, p_finish, color=1)
+        partial_buffer = get_partial_buffer(buffer, x_start, x_finish, p_start, p_finish)
+
+        # These displays treat bit 7 of a byte as the top pixel, but canvas uses bit 0 as top.
+        # Bytes are sent reversed to fix this, essentially rotating the image by 180 degrees byte-wise.
+        # Transform framebuffer coordinates to rotated hardware coordinates before sending.
+        x1 = x_max - x_finish
+        x2 = x_max - x_start
+        p1 = p_max - p_finish
+        p2 = p_max - p_start
+
+        # Set hardware addresses
+        set_range_x x1, x2
+        set_range_p p1, p2
+        set_address_x x1
+        set_address_p p1
+
+        # Send as black by default, or red if specified
+        ram_select = (color == 2) ? RAM_WRITE_RED : RAM_WRITE_BW
+        command [ram_select]
+        partial_buffer.reverse.each_slice(transfer_limit) { |slice| data(slice) }
+      end
+
+      def refresh
+        booster_soft_start
+        set_driver_output_control
+        set_display_update_control
+        set_display_update_sequence(0xF7)
+        master_activate
+        busy_wait
+      end
+    end
+  end
+end