charlie

charlie.jal - Control charlieplexed led matrix

Author Rob Hamerling, Copyright © 2014..2014, all rights reserved.
Adapted-by
Compiler 2.4q3

Description

Control a matrix or array of charlieplexed leds.
Of a set of charlieplexed leds only one led can be on at a time. To display
a stable pattern formed by multiple on-leds the leds must be switched on and off
very quickly after each other such that the human eye won't notice the off-period.
This library takes care of this switching. The user-program only needs to provide
the pattern to be shown in the led matrix and some parameters describing the
physical configuration.
This library was developed with in mind Jimmie Rogers' LoL (Lots of Leds) shield
for the Arduino with 9x14 (126) leds controlled with 12 pins, but the library is
flexible enough to control other configurations of charlieplexed leds.
.
Before including this library some basic constants should be declared:
  const byte CP_COLS             -- number of leds in a row (default 14, max 16)
  const byte CP_ROWS             -- number of rows of leds (default 9)
  const byte CP_FREQ             -- led refresh frequency (default 40)
.
One or two dedicated ports are required, depending on the number of pins that
have to be controlled. For up to 56 leds a single port (8 pins) is sufficient.
With a larger number of leds a second port is required.
For the chosen ports an alias must be specified, for example:
   alias cp_port1 is portA       -- required first or only port (default portA)
   alias cp_port2 is portC       -- [optional] second port
Also corresponding aliases for the direction settings are required, like:
   alias cp_port1_direction is portA_direction
   alias cp_port2_direction is portC_direction
Because of performance reasons this library handles the assigned port(s)
exclusively. Unused pins may be usable for other purposes but for input only.
.
A const byte array CP_XY[CP_ROWS * CP_COLS] must be declared to describe the
matrix of charlieplexed leds. Each byte of the array represents one led and must
contain the pin-number of the '+'pin (source pin) in the higher nibble and the
pin-number of the '-'pin (sink pin) in the lower nibble.
Pin numbers 0..7 should be connected to  pins 0..7,
pin numbers 8..15 should be connected to  pins 0..7.
The required array may look like:
   const byte CP_XY[CP_ROWS * CP_COLS] = { (3 << 4) | 1,   -- source pin 3, sink pin 1
                                           (2 << 4) | 9,   -- source pin 2, sink pin 9
                                           etc....
                                         }
.
An array of words 'cp_pattern' must be declared for the pattern to be shown
in the led matrix. Each word represents a row of the led matrix.
The low order bit of the first word represents the first led of the first row,
the next higher order bit the second led in the row, and so on.
How this corresponds to the physical display depends of course on the
orientation of the led matrix and the contents of the CP_XY[] array.
   var word cp_pattern[CP_ROWS]
This is most likely an array of which the elements will change over time.
It can be initialized with the declaration with all zeroes and be
filled later in the program, but may also contain an initial pattern.
For example to have 4 leds ON in the upper row of a matrix specify:
   var word cp_pattern[CP_ROWS] = { 0b0000_0011_1100_0000,  -- 1st row
                                    0b0000_0000_0000_0000   -- 2nd row
                                    etc....                 -- for every row
                                  }


Sources

- Microchip Application note TB029.
- Site of Jimmie Rogers for a LoL ("Lots of Leds") shield for Arduino
  (a 9x14 matrix of charlieplexed leds).


Notes

- This library uses Timer0 and a Timer0 interrupt routine.
         Don't touch TMR0IE and GIE. The leds are normally controlled with
         a pretty high current for a very short time (low PWM duty cycle).
         Interrupting the refresh cycle may damage the led matrix.
       - The interrupt processing is quite intensive:
         Each ON-bit requires (avg) about 300 processor cycles
         (machine instructions), each OFF-bit about 60 cycles.
         A high Fosc value is desired to leave enough cycles for the
         'real' application! The more leds the stronger this requirement.
       - Limitations: - Maximum colums: 16
                      - Maximum number of pins: 16
       - A more flexible implementations with existing libraries like
         pintools and timer0_isr_interval showed (much) heavier
         processor load and memory usage.


Dependencies

No dependency found



Summary

Global variables/contants

Procedures

Private

Functions


API details

Global variables/contants

Procedures

Private

Functions


Related samples

Here are the list of samples which use this library:

12f184012f1840_charlie_12leds.jal
12f68312f683_charlie_10leds.jal
16f178616f1786_charlie_lolshield_ticker.jal
16f178616f1786_charlie_126leds.jal
18f24k2018f24k20_charlie_lolshield_ticker1.jal
18f24k2018f24k20_charlie_lolshield_ticker.jal