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