Device::MiniLED - send text and graphics to small LED badges and signs
Version 1.03
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");
Device::MiniLED is used to send text and graphics via RS232 to our smaller set of LED Signs and badges.
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
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.
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. #
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", );
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]" );
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:
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" );
Kerry Schwab, <sales at brightledsigns.com>
<sales at brightledsigns.com>
You can find documentation for this module with the perldoc command.
perldoc Device::MiniSign
Other links that may be helpful:
Our website: brightledsigns.com
Our page for developers
The signs that work with this api are here. They are the first three shown, the badge, the "micro sign" and the "mini sign".
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.
bug-device-miniled at rt.cpan.org
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:
http://zunkworks.com/ProgrammableLEDNameBadges - Some code samples for different types of LED badges. The last one, "Badge Three", uses the same protocol we're targeting here.
https://github.com/ajesler/ledbadge-rb - Ruby library that appears to be targeting led badges with a very similar protocol.
https://github.com/danzel/CodemaniaBadge - A game, written in C#, that uses LED badges. Also has some protocol information and C# code. Targeting the same type of signs/badges.
https://github.com/ghewgill/ledbadge - Python code, again, using the same protocol.
Other Cpan modules related to Led Signs
http://search.cpan.org/~mspencer/ProLite-0.01/ProLite.pm - The only other CPAN perl module I could find that does something similar, albeit for a different type of sign.
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.
To install Device::MiniLED, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Device::MiniLED
CPAN shell
perl -MCPAN -e shell install Device::MiniLED
For more information on module installation, please visit the detailed CPAN module installation guide.