/ 
Device-Chip-SSD1306-0.14
River stage zero No dependents
/ Device::Chip::SSD1306

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.

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>