# Installation

Note

The library has been tested against Python 3.6 and newer.

## Pre-requisites

### MAX7219 Devices

By default, the SPI kernel driver is NOT enabled on a Raspberry Pi Raspbian image. You can confirm whether it is enabled using the shell command below:

    $ lsmod | grep -i spi
    spi_bcm2835             7424  0

Depending on the hardware/kernel version, this may report spi_bcm2807 rather than spi_bcm2835 - either should be adequate.

And to verify that the devices are successfully installed in `/dev`:

    $ ls -l /dev/spi*
    crw------- 1 root root 153, 0 Jan  1  1970 /dev/spidev0.0
    crw------- 1 root root 153, 1 Jan  1  1970 /dev/spidev0.1

If you have no `/dev/spi` files and nothing is showing using `lsmod` then this implies the kernel SPI driver is not loaded. Enable the SPI as follows (steps taken from https://learn.sparkfun.com/tutorials/raspberry-pi-spi-and-i2c-tutorial#spi-on-pi):

1. Run `sudo raspi-config`

2. Use the down arrow to select `5 Interfacing Options`

3. Arrow down to `P4 SPI`

4. Select yes when it asks you to enable SPI

5. Also select yes when it asks about automatically loading the kernel module

6. Use the right arrow to select the <Finish> button

7. Reboot.

After rebooting re-check that the `lsmod | grep -i spi` command shows whether SPI driver is loaded before proceeding. If you are stil experiencing problems, refer to the official Raspberry Pi SPI troubleshooting guide for further details, or ask a new question - but please remember to add as much detail as possible.

## GPIO pin-outs

### MAX7219 Devices (SPI)

The breakout board has two headers to allow daisy-chaining:

Board Pin | Name | Remarks | RPi Pin | RPi Function
1 | VCC | +5V Power | 2 | 5V0
2 | GND | Ground | 6 | GND
3 | DIN | Data In | 19 | GPIO 10 (MOSI)
4 | CS | Chip Select | 24 | GPIO 8 (SPI CE0)
5 | CLK | Clock | 23 | GPIO 11 (SPI CLK)

See also

Also see the section for cascading/daisy-chaining, power supply and level-shifting.

### WS2812 NeoPixels (DMA)

Typically, WS2812 NeoPixels reqire VCC, VSS (GND) and DI pins connecting to the Raspberry Pi, where the DI pin is usually connected to a PWM control pin such as GPIO 18.

Board Pin | Name | Remarks | RPi Pin | RPi Function

1

DO

Data Out

2 | DI | Data In | 12 | GPIO 18 (PWM0)
3 | VCC | +5V Power | 2 | 5V0

4

NC

Not connected

5

VDD

Not connected

6 | VSS | Ground | 6 | GND

The DO pin should be connected to the DI pin on the next (daisy-chained) neopixel, while the VCC and VSS are supplied in-parallel to all LED’s. WS2812b devices now are becoming more prevalent, and only have 4 pins.

### NeoSegments

@msurguy’s NeoSegments should be connected as follows:

Board Pin | Name | Remarks | RPi Pin | RPi Function
1 | GND | Ground | 6 | GND
2 | DI | Data In | 12 | GPIO 18 (PWM0)
3 | VCC | +5V Power | 2 | 5V0

## Installing from PyPi

Install the dependencies for library first with:

    $ sudo usermod -a -G spi,gpio pi
    $ sudo apt install build-essential python3-dev python3-pip libfreetype6-dev libjpeg-dev libopenjp2-7 libtiff5

Warning

The default `pip` and `setuptools` bundled with apt on Raspbian are really old, and can cause components to not be installed properly. Make sure they are up to date by upgrading them first:

    $ sudo -H pip install --upgrade --ignore-installed pip setuptools

Proceed to install latest version of the luma.led_matrix library directly from PyPI:

    $ sudo python3 -m pip install --upgrade luma.led_matrix

## Examples

Ensure you have followed the installation instructions above. Clone the repo from github, and run the example code as follows:

    $ python examples/matrix_demo.py

The matrix demo accepts optional flags to configure the number of cascaded devices and correct the block orientation phase shift when using 4x8x8 matrices:

    $ python examples/matrix_demo.py -h
    usage: matrix_demo.py [-h] [--cascaded CASCADED]
                          [--block-orientation {0,90,-90}] [--rotate {0,1,2,3}]
                          [--reverse-order REVERSE_ORDER]

    matrix_demo arguments

    optional arguments:
      -h, --help            show this help message and exit
      --cascaded CASCADED, -n CASCADED
                            Number of cascaded MAX7219 LED matrices (default: 1)
      --block-orientation {0,90,-90}
                            Corrects block orientation when wired vertically
                            (default: 0)
      --rotate {0,1,2,3}    Rotate display 0=0_, 1=90_, 2=180_, 3=270_
                            (default: 0)
      --reverse-order REVERSE_ORDER
                            Set to true if blocks are in reverse order (default:
                            False)

Similarly, there is a basic demo of the capabilities of the `luma.led_matrix.virtual.sevensegment` wrapper:

    $ python examples/sevensegment_demo.py

and for the `luma.led_matrix.device.neopixel` device:

    $ sudo python examples/neopixel_demo.py

Further examples are available in the luma.examples. git repository. Follow the instructions in the README for more details.

A small example application using ZeroSeg to display TOTP secrets can be found in https://github.com/rm-hull/zaup.