NAME

    Device::Chip::SSD1306 - chip driver for monochrome OLED modules

DESCRIPTION

    This abstract Device::Chip subclass provides communication to an
    SSD1306, SSD1309 or SH1106 chip attached by an adapter. To actually use
    it, you should use one of the subclasses for the various interface
    types.

      * Device::Chip::SSD1306::I2C - IC

      * Device::Chip::SSD1306::SPI4 - 4-wire SPI

    The reader is presumed to be familiar with the general operation of
    this chip; the documentation here will not attempt to explain or define
    chip-specific concepts or features, only the use of this module to
    access them.

DEVICE MODELS

    This module supports a variety of actual chip modules with different
    display sizes. The specific display module is selected by the model
    argument to the constructor, which should take one of the following
    values:

    SSD1306-128x64

      An SSD1306 driving a display with 128 columns and 64 rows. The most
      common of the display modules, often found with a 0.96 inch display.

      This setting also drives the SSD1309 chip found in the larger 1.6 or
      2.4 inch displays.

    SSD1306-128x32

      An SSD1306 driving a display with 128 columns and 32 rows. This is
      the usual "half-height" module, often found with a 0.91 inch display.
      This uses only even-numbered rows.

    SSD1306-64x32

      An SSD1306 driving a display with 64 columns and 32 rows. This is the
      usual "quarter" size module, often found with a 0.49 inch display.
      This uses the only the middle 64 columns.

    SH1106-128x64

      An SH1106 driving a display with 128 columns and 64 rows. This is the
      chip that's usually found in the larger display modules, such as 1.3
      and 1.6 inch.

    The overall API shape of this module is similar to that of
    Device::Chip::MAX7219Panel, supporting the same set of drawing methods.
    A future version of both of these modules may extend the concept into
    providing access via an interface helper instance, if some standard API
    shape is defined for driving these kinds of 1bpp pixel displays.

CONSTRUCTOR

 new

       $chip = Device::Chip::SSD1306->new(
          model => $model,
          ...
       );

    Returns a new Device::Chip::SSD1306 driver instance for the given model
    name, which must be one of the models listed in "DEVICE MODELS". If no
    model option is chosen, the default of SSD1306-128x64 will apply.

    In addition to model, the following named options may also be passed:

    xflip => BOOL

    yflip => BOOL

      If true, the order of columns or rows respectively will be reversed
      by the hardware. In particular, if both are true, this inverts the
      orientation of the display, if it is mounted upside-down.

    contrast => INT

      Normally set to 0x9F, but you may wish to set a lower value to avoid
      display burn-in on rarely-updated static displays.

    vcomh => INT

      Normally set to 4, but you may wish to set a lower value to avoid
      display burn-in on rarely-updated static displays.

METHODS

    The following methods documented in an await expression return Future
    instances.

 rows

 columns

       $n = $chip->rows;
    
       $n = $chip->columns;

    Simple accessors that return the number of rows or columns present on
    the physical display.

 init

       await $chip->init;

    Initialise the display after reset to some sensible defaults.

 display

       await $chip->display( $on );

    Turn on or off the display.

 display_lamptest

       await $chip->display_lamptest( $enable );

    Turn on or off the all-pixels-lit lamptest mode.

 display_invert

       await $chip->display_invert( $enable );

    Turn on or off the inverted output mode.

 send_display

       await $chip->send_display( $pixels );

    Sends an entire screen-worth of pixel data. The $pixels should be in a
    packed binary string containing one byte per 8 pixels.

DRAWING METHODS

    The following methods operate on an internal framebuffer stored by the
    instance. The user must invoke the "refresh" method to update the
    actual chip after calling them.

 clear

       $chip->clear;

    Resets the stored framebuffer to blank.

 draw_pixel

       $chip->draw_pixel( $x, $y, $val = 1 );

    Draw the given pixel. If the third argument is false, the pixel will be
    cleared instead of set.

 draw_hline

       $chip->draw_hline( $x1, $x2, $y, $val = 1 );

    Draw a horizontal line in the given $y row, between the columns $x1 and
    $x2 (inclusive). If the fourth argument is false, the pixels will be
    cleared instead of set.

 draw_vline

       $chip->draw_vline( $x, $y1, $y2, $val = 1 );

    Draw a vertical line in the given $x column, between the rows $y1 and
    $y2 (inclusive). If the fourth argument is false, the pixels will be
    cleared instead of set.

 draw_rect

       $chip->draw_rect( $x1, $y1, $x2, $y2, $val = 1 );

    Since version 0.15.

    Draw a solid rectangle in between the given $x1 to $2 columns and rows
    $y1 to $y2 (all inclusive). If the final argument is false, the pixels
    will be cleared instead of set.

 draw_blit

       $chip->draw_blit( $x, $y, @lines );

    Draws a bitmap pattern by copying the data given in lines, starting at
    the given position.

    Each value in @lines should be a string giving a horizontal line of
    bitmap data, each character corresponding to a single pixel of the
    display. Pixels corresponding to a spaces will be left alone, a hyphen
    will be cleared, and any other character (for example a #) will be set.

    For example, to draw an rightward-pointing arrow:

       $chip->draw_blit( 20, 40,
          "   #  ",
          "   ## ",
          "######",
          "######",
          "   ## ",
          "   #  " );

 draw_glyph

       $chip->draw_glyph( $x, $y, $glyph, $val = 1, $bg = undef );

    Since version 0.15.

    Draws a glyph by copying the bitmap data out of the $glyph argument, as
    if it were a single glyph structure obtained from Font::PCF. The bitmap
    is copied starting at the given position, and extends rightward and
    downward for whatever is the defined size of the glyph given by its
    data. For each pixel set in the glyph's bitmap, the corresponding pixel
    of the display is set to $val; the other pixels are set to $bg. Either
    of these last two values may be set to undef to not modify those
    corresponding pixels.

    Note that neither this module nor its tests actually depend on
    Font::PCF itself; it merely invokes methods on the object consistent
    with that API. Specifically, it expects the following methods:

    width

         $cols = $glyph->width;

      Returns the number of columns wide that contain pixels of glyph data.

    bitmap

         [ $row0, $row1, ... ] = $glyph->bitmap;

      Returns an ARRAY reference of rows of pixel data. Each row is
      represented by a big-endian 32bit integer. The topmost bit
      corresponds to the leftmost pixel.

 refresh

       await $chip->refresh;

    Sends the framebuffer to the display chip.

TODO

      * More interfaces - 3-wire SPI

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>

