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 - I²C

      * 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.

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_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,
          "   #  ",
          "   ## ",
          "######",
          "######",
          "   ## ",
          "   #  " );

 refresh

       await $chip->refresh;

    Sends the framebuffer to the display chip.

TODO

      * More interfaces - 3-wire SPI

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>