NAME

Device::PiGlow - Interface to the PiGlow board using i2c

SYNOPSIS

    use Device::PiGlow;

    my $pg = Device::PiGlow->new();

    my $values = [0x01,0x02,0x04,0x08,0x10,0x18,0x20,0x30,0x40,0x50,0x60,0x70,0x80,0x90,0xA0,0xC0,0xE0,0xFF];

    $pg->enable_output();
    $pg->enable_all_leds();

    $pg->write_all_leds($values);
    sleep 10;
    $pg->reset();

See the examples directory for more ways of using this.

DESCRIPTION

The PiGlow from Pimoroni (http://shop.pimoroni.com/products/piglow) is a small board that plugs in to the Raspberry PI's GPIO header with 18 LEDs on that can be addressed individually via i2c.

This module uses Device::SMBus to abstract the interface to the device so that it can be controlled from a Perl programme.

It is assumed that you have installed the OS packages required to make i2c work and have configured and tested the i2c appropriately. The only difference that seems to affect the PiGlow device is that it only seems to be reported by i2cdetect if you use the "quick write" probe flag:

   sudo i2cdetect -y -q 1

(assuming you have a Rev B. Pi - if not you should supply 0 instead of 1.) I have no way of knowing the compatibility of the "quick write" with any other devices you may have plugged in to the Pi, so I wouldn't recommend doing this with any other devices unless you know that they won't be adversely affected by "quick write". The PiGlow has a fixed address anyway so the information isn't that useful.

METHODS

new

The constructor. This takes two optional attributes which are passed on directly to the Device::SMBus constructor:

I2CBusDevicePath

This sets the device path, it defaults to /dev/i2c-1 (assuming a newer Raspberry PI,) You will want to set this if you are using an older PI or an OS that creates a different device.

I2CDeviceAddress

This sets the i2c device address, this defaults to 0x54. Unless you have somehow altered the address you shouldn't need to change this.

device_smbus

This is the Device::SMBus object we will be using to interact with i2c. It will be initialised with the attributes described above. You may want this if you need to do something to the PiGlow I haven't thought of.

update

This updates the values set to the LED registers to the LEDs and changes the display.

enable_output

This sets the state of the device to active.

enable_all_leds

This turns on all three banks of LEDs.

write_all_leds

This writes the PWM values supplied as an Array Reference and immediately calls update to apply the values to the LEDs.

The array must be exactly 18 elements long.

The optional second argument will cause the gamma correction to be applied if the value is true.

all_off

This is convenience to turn off (set to brightness 0) all the LEDs at once. It calls update immediately.

set_leds

This sets the leds specified in the array reference in the first argument ( values 0 - 17 to index the LEDs ) all to the single value specified.

Gamma adjustment is applied.

This does not call update, this should be done afterwards in order to update the LED values.

led_table

This provides a mapping between the logical order of the leds (indexed 0 - 17 ) to the registers that control them.

ring_table

The arrangement of the LEDs can be thought of as being arrange logically as 6 "rings". This provides access to the rings indexed 0-5.

set_ring

Sets all of the LEDs in the logical ring indexed 0 - 5 to the value specified. Gamma correction is applied to the value.

This isn't immediately applied to the LEDs, update should be called after all the changes have been applied.

arm_table

This returns an Array Ref of Array references that reference the LEDs in each "arm" of the PiGlow.

set_arm

Sets the LEDs in the specified "arm" of the PiGlow to the specified value.

Value has gamma correction applied.

Update isn't applied and the update method should be called when all the required updates have been performed.

colour_table

This returns a Hash reference mapping the names of the coloured LEDs to the groups of LEDs of that colour.

The delegate colours returns the keys, get_colour_leds returns the list of LEDs

set_colour

Sets the LEDs in the specified "colour" of the PiGlow to the specified value.

Value has gamma correction applied.

Update isn't applied and the update method should be called when all the required updates have been performed.

gamma_table

This is a map of input PWM values (0 - 255) to gamma corrected values that produce a more even range of brightness in the LEDs.

The values were lifted from the piglow library for Node.js which in turn borrowed them from elsewhere.

gamma_fix_values

This applies the gamma adjustment mapping to the supplied array ref.

reset

Resets the device to its default state. That is to say all LEDs off.

It will be necessary to re-enable the groups of LEDs again after calling this.

write_block_data

$self->writeBlockData($register_address, $values)

Writes a maximum of 32 bytes in a single block to the i2c device. The supplied $values should be an array ref containing the bytes to be written.

The register address supplied should be the first of a consecutive set of addresses equal to the number of values supplied. Supplying an address that doesn't fit that description is unlikely to work well and will almost certainly result in undefined behaviour in the device.

CONSTANTS

These define the command registers used by the SN3218 IC used in PiGlow

CMD_ENABLE_OUTPUT

If set to 1 the device will be ready for operation, if 0 then it will be "shutdown"

CMD_ENABLE_LEDS

This should be used for a block write to enable (or disable) all three groups of LEDs in one go. The values are a 6 bit mask, one bit for each LED in the group.

CMD_ENABLE_LEDS_1

A bit mask to enable the LEDs in group 1

CMD_ENABLE_LEDS_2

A bit mask to enable the LEDs in group 2

CMD_ENABLE_LEDS_3

A bit mask to enable the LEDs in group three.

CMD_SET_PWM_VALUES

This should be used in a block write to set the PWM values of all 18 LEDs at once. The values should be 8 bit values.

There are also CMD_SET_PWN_VALUE_[1 .. 18] to set the LEDs individually.

CMD_UPDATE

The written LED values are stored in a temporary register and are not applied to the LEDs until an 8 bit value is written to this register/

CMD_RESET

Writing a value to this register will restore the device to its power on default (i.e. all LEDs blank)

AUTHOR

Jonathan Stowe <jns@gellyfish.co.uk>

COPYRIGHT

This is licensed under the same terms as Perl itself. Please see the LICENSE file in the distribution files for the full details.

SUPPORT

I wrote this because I had the device and I prefer to use Perl. It probably does everything I would like it to do. If you want it to do something else or find a bug or infelicity, please feel free to fork the code at github and send me a pull request:

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

bug reports without patches are likely to be ignored unless you want to do do something with it that I think is fun and interesting.

CREDIT WHERE IT'S DUE

This was largely a no brainer. The author of Device::SMBus did all the hard work on the Perl side and the implementation details were largely translated from the PyGlow library. https://github.com/benleb/PyGlow/

SEE ALSO

Device::SMBus