NAME

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.

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 <[email protected]>