# 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

- `var byte _cp_y = CP_ROWS - 1`
- `var byte _cp_x = CP_COLS - 1`

### Procedures

- `charlie_init()`

Private

- `_charlie_timer0_isr()`

### Functions

## API details

### Global variables/contants

- `var byte _cp_y = CP_ROWS - 1`

      row offset

- `var byte _cp_x = CP_COLS - 1`

      led offset in row

### Procedures

- `charlie_init()`

      Title: Initialize library: start the refresh process

Private

- `_charlie_timer0_isr()`

  No documentation found

### Functions

## Related samples

Here are the list of samples which use this library:

12f1840 | 12f1840_charlie_12leds.jal
12f683 | 12f683_charlie_10leds.jal
16f1786 | 16f1786_charlie_lolshield_ticker.jal
16f1786 | 16f1786_charlie_126leds.jal
18f24k20 | 18f24k20_charlie_lolshield_ticker1.jal
18f24k20 | 18f24k20_charlie_lolshield_ticker.jal