/ 
Device-MiniLED-1.03
River stage zero No dependents
/ Device::MiniLED

NAME

Device::MiniLED - send text and graphics to small LED badges and signs

VERSION

Version 1.03

SYNOPSIS

use Device::MiniLED;
my $sign=Device::MiniLED->new(devicetype => "sign");
#
# add a text only message
#
$sign->addMsg(
    data => "Just a normal test message",
    effect => "scroll",
    speed => 4
);
#
# create a picture and an icon from built-in clipart
#
my $pic=$sign->addPix(clipart => "zen16");
my $icon=$sign->addIcon(clipart => "heart16");
#
# add a message with the picture and animated icon we just created
#
$sign->addMsg(
        data => "Message 2 with a picture: $pic and an icon: $icon",
        effect => "scroll",
        speed => 3
);
$sign->send(device => "COM3");

DESCRIPTION

Device::MiniLED is used to send text and graphics via RS232 to our smaller set of LED Signs and badges.

CONSTRUCTOR

new

my $sign=Device::MiniLED->new(
       devicetype => $devicetype
);
# $devicetype can be either:
#   sign  - denoting a device with a 16 pixel high display
#   badge - denoting a device with a 12 pixel high display

METHODS

$sign->addMsg

This family of devices support a maximum of 8 messages that can be sent to the sign. These messages can consist of three different types of content, which can be mixed together in the same message..plain text, pixmap images, and 2-frame anmiated icons.

The $sign->addMsg method has one required argument, data, It also has three optional arguments: effect, speed, and slot.

data: (required) The data to be sent to the sign. Plain text, optionally with tags for fonts and $variables that reference pixmap images or animated icons.
font tags: You can insert a font tag to create flashing text. The supported tags are &lt;f:normal&gt; and &lt;f:flash&gt. On the badges, these tags work as expected. On the signs, either flag is actually just a toggle back and forth from flashing to normal. If you use them in the right order, you won't notice. For example: $sign->addMsg( data => "Some <f:flash>flashing text<f:normal>. Neat, right?" );
effect: (optional, defaults to "scroll") One of "hold", "scroll", "snow", "flash" or "hold+flash"
speed: (optional, defaults to "4") An integer from 1 to 5, where 1 is the slowest and 5 is the fastest
slot: (optional) An integer from 1 to 8, representing the message slots in the sign. If you don't supply this, it will assign slot numbers automatically, in ascending order.

The addMsg method returns a number that indicates how many messages have been created. This may be helpful to ensure you don't try to add a 9th message, which will fail:

my $sign=Device::MiniLED->new(devicetype => "sign");
for (1..9) {
     my $number=$sign->addMsg(
         data => "Message number $_",
         effect => "scroll",
         speed => 5
     );
     # on the ninth loop, $number will be undef, and a warning will be
     # generated
}

Assigning slots manually

my $sign=Device::MiniLED->new(devicetype => "sign");
$sign->addMsg(
    data => "A msg in slot 3",
    slot => 3
);
$sign->addMsg(
    data => "A msg in slot 1",
    slot => 1
);
$sign->addMsg(
    data => "A msg in slot 5",
    slot => 5
);
# even though we loaded a message in slot 3, the use of "showslots"
# below means that only the messages in slots 1 and 5 will be displayed
$sign->send(
    device => "/dev/ttyUSB0",
    showslots => "1,5"
);
# sleep for a minute...
sleep(60);
# now we'll have the sign show just what's in slot number 3.
$sign->send(
    device => "/dev/ttyUSB0",
    showslots => "3"
);
#
# note: if the sign already has messages in a slot, you can have a script
# that does nothing other than $sign->send (with the showslots parameter)
# to select which of them to  display on the sign.
#
# for example, you could preload messages in slots 1 through 7, with message
# 1 being "Happy Monday", 2 being "Happy Tuesday", and so forth.
# Then, on monday morning, your script could send:
# run $sign->send(device => 'COM1', showslots => "1"), and just the monday
# message would display on the sign
#
# For unknown reasons, however, the message slot selection buttons on the
# sign itself won't show stored messages.  They are there, and will be 
# displayed if you use the showslots parameter in $sign->send.
#

$sign->addPix

The addPix method allow you to create simple, single color pixmaps that can be inserted into a message. There are two ways to create a picture.

Using the built-in clipart

#
# load the built-in piece of clipart named phone16
#   the "16" is hinting that it's 16 pixels high, and thus better suited to
#   a 16 pixel high device, and not a 12 pixel high device
#
my $pic=$sign->addPix(
      clipart   => "phone16"
);
# now use that in a message
$sign->addMsg(
    data => "here is a phone: $pic",
);

Rolling your own pictures

To supply your own pictures, you need to supply 3 arguments:

height: height of the picture in pixels

width: width of the picture in pixels (max is 256)

data : a string of 1's and 0's, where the 1 will light up the pixel and a 0 won't. You might find Image::Pbm and it's $image->as_bitstring method helpful in generating these strings.

# make a 5x5 pixel outlined box 
my $pic=$sign->addPix(
      height => 5,
      width  => 5,
      data   => 
        "11111".
        "10001".
        "10001".
        "10001".
        "11111" 
);
# now use that in a message
$sign->addMsg(
    data => "here is a 5 pixel box outline: $pic",
);

$sign->addIcon

The $sign->addIcon method is almost identical to the $sign->addPix method. The addIcon method accepts either a 16x32 pixel image (for signs), or a 12x24 pixel image (for badges). It internally splits the image down the middle into a left and right halves, each one being 16x16 (or 12x12) pixels.

Then, when displayed on the sign, it alternates between the two, in place, creating a simple animation.

# make an icon using the built-in heart16 clipart
my $icon=$sign->addIcon(
    clipart => "heart16"
);
# now use that in a message
$sign->addMsg(
    data => "Animated heart icon: $icon",
);

You can "roll your own" icons as well.

# make an animated icon that alternates between a big box and a small box
my $sign=Device::MiniLED->new(devicetype => "sign");
my $icon16x32=
     "XXXXXXXXXXXXXXXX" . "----------------" .
     "X--------------X" . "----------------" .
     "X--------------X" . "--XXXXXXXXXXX---" .
     "X--------------X" . "--X---------X---" .
     "X--------------X" . "--X---------X---" .
     "X--------------X" . "--X---------X---" .
     "X--------------X" . "--X---------X---" .
     "X--------------X" . "--X---------X---" .
     "X--------------X" . "--X---------X---" .
     "X--------------X" . "--X---------X---" .
     "X--------------X" . "--X---------X---" .
     "X--------------X" . "--X---------X---" .
     "X--------------X" . "--X---------X---" .
     "X--------------X" . "--XXXXXXXXXXX---" .
     "X--------------X" . "----------------" .
     "XXXXXXXXXXXXXXXX" . "----------------";
# translate X to 1, and - to 0
$icon16x32=~tr/X-/10/;
# no need to specify width or height, as
# it assumes 16x32 if $sign is devicetype "sign", 
# and assumes 12x24 if $sign
my $icon=$sign->addIcon(
    data => $icon16x32
);
$sign->addMsg(
    data => "Flashing Icon: [$icon]"
);

$sign->send

The send method connects to the sign over RS232 and sends all the data accumulated from prior use of the $sign->addMsg method. The only mandatory argument is 'device', denoting which serial device to send to.

It supports three optional arguments, showslots, baudrate and packetdelay:

showslots: A string that is a comma separated list of the slot numbers that you want to display on the sign. If you omit this, it will display the messages you just added with addMsg. If you supply a null string, then the sign will continue to display whatever slots it is currently displaying.
baudrate: defaults to 38400, no real reason to use something other than the default, but it's there if you feel the need. Must be a value that Device::Serialport or Win32::Serialport thinks is valid
packetdelay: An amount of time, in seconds, to wait, between sending packets to the sign. The default is 0.20. If you see "XX" displayed on your sign while sending data, increasing this value may help. Must be greater than zero.
Note: For reference, each text message generates 3 packets, and each 16x32 portion of an image sends one packet. There's also an additional, short, packet sent after all message and image packets are delivered. So, if you make packetdelay a large number...and have lots of text and/or images, you may be waiting a while to send all the data. Similarly, you may get some milage out of using a number smaller than the default, provided you don't see 'XX' displayed on the sign while sending.

Examples of using $sign->send

# typical use on a windows machine
$sign->send(
    device => "COM4"
);
# typical use on a unix/linux machine
$sign->send(
    device => "/dev/ttyUSB0"
);
# using optional arguments, set baudrate to 9600, and sleep 1/2 a second
# between sending packets.  
$sign->send(
    device => "COM8",
    baudrate => "9600",
    packetdelay => 0.5
);

Note that if you have multiple connected signs, you can send to them without creating a new object:

 # send to the first sign
 $sign->send(device => "COM4");
 # send to another sign
 $sign->send(device => "COM6");
 # send to a badge connected on COM7
 #   this works fine for plain text, but won't work well for
 #   pictures and icons...you'll have to create a new
 #   sign object with devicetype "badge" for them to render correctly
 $sign->send(device => "COM7");

Using the showslots parameter. Also see the "slot" parameter under "$sign->addMsg".

#
# showslots is a string, with the numbers of the messages you want
# displayed separated by commas
#
$sign->send(device => "/dev/ttyUSB0",
            showslots => "1,5,7"
);

AUTHOR

Kerry Schwab, <sales at brightledsigns.com>

SUPPORT

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

perldoc Device::MiniSign

Other links that may be helpful:

BUGS

Please report any bugs or feature requests to bug-device-miniled at rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

TODO

Font Upload: The signs only natively support one line of text, but they do support uploading and replacing the native font. The native font that comes with the sign is 12 pixels tall, I suppose to allow for the effect that outlines the text in a box. A 15 or 16 pixel font, however, would be much more visible.
Emulating 2 lines of text: If we provided a way to render smaller fonts, like a standard 5x7 LED font, into a pixmap, you could present two lines of text on the sign, abeit, only as a picture via addPix.
Migration of this code to a more generic module: Need a better module structure that supports other models of LED signs that use a different protocol. Like LEDSign::Mini LEDSign:OtherModel, etc.

ACKNOWLEDGEMENTS

I was able to leverage some existing work I found, though none of these examples reverse engineered the protocol to the same degree that we've done in this API. Here's what I found:

Other Cpan modules related to Led Signs

LICENSE AND COPYRIGHT

Copyright 2013 Kerry Schwab.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Aggregation of this Package with a commercial distribution is always permitted provided that the use of this Package is embedded; that is, when no overt attempt is made to make this Package's interfaces visible to the end user of the commercial distribution. Such use shall not be construed as a distribution of this Package.

The name of the Copyright Holder may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.