/ 
Device-PiLite-0.01
River stage zero No dependents
/ Device::PiLite

NAME

Device::PiLite - Interface to Ciseco Pi-Lite for Raspberry Pi

SYNOPSIS

    use Device::PiLite;

    my $pilite = Device::PiLite->new();

	$p->all_off();

	$p->text("This is a test");

	$p->all_off();

DESCRIPTION

This module provides an interface for the Ciseco Pi-Lite for the Raspberry Pi.

The Pi-Lite has a 14 x 9 grid of LEDs controlled by an embedded ATMEL AVR microcontroller that itself can be programmed using the Arduino toolchain, however the default firmware provides a relatively simple mechanism to communicate with the board from the Raspberry Pi's TTL serial port.

Device::PiLite requires the default firmware and will not work if the Pi-Lite is loaded with some other sketch.

CONFIGURING FOR THE PI-LITE

By default most Linux distributions for the Raspberry Pi will use the serial port for a console, this will interfere with the functioning of the Pi-Lite. Before you try to use the device you will need to turn this off, and instructions for a Debian based distribution can be found at:

http://openmicros.org/index.php/articles/94-ciseco-product-documentation/raspberry-pi/283-setting-up-my-raspberry-pi

If you are using a distribution with a different base (such as e.g. Pidora,) it may use systemd rather than an inittab to start the console process and you will need to use systemctl to disable the getty service. You will still need to alter the cmdline.txt as described in the above instructions.

Any users that want to access the Pi-Lite will need to be in the dialout group, which can be done by doing:

sudo usermod -a -G dialout username

at the command line, where username is the user you want to add to the group.

METHODS

serial_device

This is the name of the serial device to be used.

The default is "/dev/ttyAMA0". If it is to be set to another value this should be provided to the constructor.

device_serialport

This is the Device::SerialPort that will be used to perform the actual communication with the Pi-Lite, configured as appropriate.

This delegates a number of methods and probably doesn't need to be used directly.

all_on

Turns all the LEDs on.

all_off

Turns all the LEDs off.

_on_off

Turns the pixels on or off depending on the boolean supplied.

set_scroll

This sets the scroll delay in milliseconds per pixel. The default is 80 (that is to say it will take 1.120 seconds to scroll the entire width of the screen.)

text

This writes the provided test to the Pi-Lite. Scrolling as necessary at the configured rate.

It won't return until all the text has been displayed, but you may want to pause for $columns * $scroll_rate milliseconds before doing anything else if you want the text to completely scroll off the screen.

The ability or otherwise to display non-ASCII characters is entirely the responsibility of the firmware on the Pi-Lite (it uses a character to pixel map to draw the characters.)

frame_buffer

This writes every pixel in the Pi-Lite in one go, the argument is a 126 character string where each character is a 1 or 0 that indicates the state of a pixel, starting from 1,1 (i.e. top left) to 14,9 (bottom right.)

bargraph

The bargraph comprises 14 columns with values expressed as 0-100% (the resolution is only 9 rows however,) The takes the column number (1-14) and the value as arguments and sets the appropriate column.

vu_meter

This sets one channel of the "vu meter" which is a horizontal two bar graph, with values expressed 1-100%. The arguments are the channel number 1 or 2 and the value.

pixel_on

Turns the pixel specified by $column, $row on.

pixel_off

Turns the pixel specified by $column, $row off.

pixel_toggle

Toggles the pixel specified by $column, $row .

pixel_action

This performs the specified action 'ON' (1), 'OFF' (0), 'TOGGLE' (2) on the pixel specified by column and row. This is used by pixel_on, pixel_off and pixel_toggle internally but may be useful if the state is to be computed.

scroll

This scrolls by the number of columns left or right, a negative value will shift to the right, positive shift to the left.

Once a pixel is off the display it won't come back when you scroll it back as there is no buffer.

character

This displays the specified single character at $column, $row.

If the character would be partially off the screen it won't be displayed.

As with text() above, this is unlikely to work well with non-ASCII characters.

columns

This is the number of columns on the Pi-Lite. This is almost certainly 14.

valid_column

Returns a boolean to indicate whether it is an integer between 1 and columns.

rows

This is the number of rows on the Pi-Lite. This is almost certainly 9.

valid_row

Returns a boolean to indicate whether it is an integer between 1 and rows.

valid_axis

Return a boolean to indicate $value is greater ot equal to 1 and smaller or equal to $bound.

cmd_prefix

A Pi-Lite serial command sequenced is introduced by sending '$$$'.

send_prefix

Write the prefix to the device. And wait for the response 'OK'.

It will return a boolean value to indicate the success or otherwise of the write.

send_command

This sends a command to the Pi-Lite, sending the command prefix and the command constructed by $format and @arguments which are dealt with by _build_command.

_build_command

This returns the command string constructed from the sprintf format specified by $format and the set of replacements in @arguments.

AUTHOR

Jonathan Stowe, <jns at gellyfish.co.uk>

BUGS

This appears to work as documented but it is difficult to test that the device behaves as expected in all cases automatically.

Automated test reports indicating failure will be largely ignored unless they indicate a problem with the tests themselves.

Please feel free to suggest any features with a pull request at:

https://github.com/jonathanstowe/Device-PiLite

though I'd be disinclined to include anything that would require a change to the device's firmware as this is somewhat tricky to deploy.

You can report bugs to bug-device-pilite@rt.cpan.org but you should consider whether it is actually a bug in this code or that of the device, you can find the source for the firmware at:

https://github.com/CisecoPlc/PiLite

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Device::PiLite

SEE ALSO

L<Device::SerialPort>

LICENSE AND COPYRIGHT

Copyright 2014 Jonathan Stowe.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.