NAME

Device::Chip::MAX7219Panel - chip driver for a panel of MAX7219 modules

SYNOPSIS

   use Device::Chip::MAX7219Panel;
   use Future::AsyncAwait;

   my $chip = Device::Chip::MAX7219Panel->new;
   await $chip->mount( Device::Chip::Adapter::...->new );

   await $chip->init;
   await $chip->intensity( 2 );

   $panel->clear;
   $panel->draw_hline( 0, $panel->columns-1, 2 );
   $panel->draw_vline( 12, 0, $panel->rows-1 );

   await $panel->refresh;

DESCRIPTION

This Device::Chip subclass provides specific communication to an LED panel comprised of multiple Maxim Integrated MAX7219 or similar chips, attached to a computer via an SPI adapter. It maintains a virtual frame-buffer to drive the display in terms of drawing commands.

This module expects to find a chain of MAX7219 or similar chips connected together in a daisy-chain fashion; sharing the SCK and CS signals, and with each chip's DO feeding into the DI of the next. The chips should be connected in rows, with the first at top left corner, then across the top row, with each subsequent row below it in the same manner. For example, when using 8 chips arranged in a 32x16 geometry, the chips would be in the order below:

   1 2 3 4
   5 6 7 8

The overall API shape of this module is similar to that of Device::Chip::SSD1306, 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

   $panel = Device::Chip::MAX7219Panel->new( %opts );

Returns a new Device::Chip::MAX7219Panel instance.

The following additional options may be passed:

geom => STRING

The overall geometry of the display panel, as two integers giving column and row count expressed as a string COLUMNSxROWS. If not specified, will default to the common size for cheaply available module panels, of 32x8.

Both the column and row count must be a multiple of 8.

xflip => BOOL

yflip => BOOL

If true, the order of columns or rows respectively will be reversed. 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 = $panel->rows;

   $n = $panel->columns;

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

init

   await $panel->init();

Initialises the settings across every chip and ready to be used by this module. This method should be called once on startup.

intensity

   await $panel->intensity( $value );

Sets the intensity register across every chip. $value must be between 0 and 15, with higher values giving a more intense output.

shutdown

   await $panel->shutdown( $off = 1 );

Sets the shutdown register across every chip. $off defaults to true, to turn the panel off. If defined but false (such as 0), the panel will be switched on.

displaytest

   await $panel->displaytest( $on );

Sets the display test register across every chip, overriding the output control and turning on every LED if set to a true value, or restoring normal operation if set to false.

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 panel chips after calling them.

clear

   $panel->clear;

Resets the stored framebuffer to blank.

draw_pixel

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

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

draw_hline

   $panel->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

   $panel->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

   $panel->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 spaces will be left alone, a hyphen will be cleared, and any other character (for example a #) will be set.

For example, to draw a rightward-pointing arrow:

   $panel->draw_blit( 6, 1,
      "   #  ",
      "   ## ",
      "######",
      "######",
      "   ## ",
      "   #  " );

refresh

   await $panel->refresh;

Sends the framebuffer to the panel chips.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm Device::Chip::MAX7219

perl -MCPAN -e shell
install Device::Chip::MAX7219