Metadata-Version: 1.1
Name: the-matrix
Version: 0.2.5
Summary: Module to control Boldport "The Matrix"
Home-page: https://github.cm/threebytesfull.com/the_matrix_pi
Author: Rufus Cable
Author-email: rufus@threebytesfull.com
License: MIT
Description: # Driver Module for Boldport TheMatrix
        
        Here's a Python module to drive your board from a Raspberry Pi.
        
        ## Prerequisites
        
        You need I2C set up on your Raspberry Pi. If you haven't done this before, you
        need to enable the I2C hardware:
        
            sudo raspi-config
        
        Choose `9 Advanced Options`, `A6 I2C`, `Yes`, `Ok`, `Finish`.
        
        Next, you'll need to install the I2C support for Python:
        
            sudo apt-get install python-smbus python3-smbus
        
        It's possible that you'll need to reboot at this point, but I've not found that
        necessary on the Raspberry Pi boards I've tried so far.
        
        ## Installation
        
        The module is available as a Python package, so you can install it with `pip`.
        
            # Install for Python 2
            pip install the_matrix
        
        or
        
            # Install for Python 3
            pip3 install the_matrix
        
        Depending on your system configuration, you may need to run those with
        superuser privileges:
        
            # Superuser install for Python 2
            sudo pip install the_matrix
        
        or
        
            # Superuser install for Python 3
            sudo pip3 install the_matrix
        
        ## Connections
        
        To connect to the I2C bus on the Raspberry Pi, connect directly to the
        expansion header. Here's a top-down view - pin 1 is closest to the display
        connector:
        
                VCC  1  2
                SDA  3  4
                SCL  5  6
                     7  8
                GND  9 10
                    11 12
                    13 14
                    15 16
                    17 18
                    19 20
                    21 22
                    23 24
                    25 26
                    27 28
                    29 30
                    31 32
                    33 34
                    35 36
                    37 38
                    39 40
                [USB ports this end]
        
        ## Usage
        
        From your Raspberry Pi shell, run `i2cdetect` to check that your TheMatrix is
        responding and has the address you're expecting:
        
            i2cdetect -y 1
        
        By default, TheMatrix will have address 0x30 if you haven't added a resistor at
        R5 (R4 on the prototype boards) to specify otherwise. The output should look
        something like this:
        
                 0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
            00:          -- -- -- -- -- -- -- -- -- -- -- -- --
            10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
            20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
            30: 30 -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
            40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
            50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
            60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
            70: -- -- -- -- -- -- -- --
        
        ## [the_matrix_identify](./the_matrix/identify.py)
        
        This script can auto-detect the presence of a device on the I2C bus with the
        address in the range expected for TheMatrix - 0x30 to 0x37. If you run this
        script with no parameters:
        
            # detect and identify TheMatrix boards
            the_matrix_identify
        
        then each detected board will display its own address. If you want to identify
        a particular board or boards, you can specify their addresses on the command
        line:
        
            # detect one specific board
            the_matrix_identify -a 0x30
        
            # detect two specific boards
            the_matrix_identify -a 0x30,0x31
        
        That might be useful if you've got other I2C devices on the same bus - some
        write-only devices don't like being asked for data. :)
        
        ## [the_matrix_leds](./the_matrix/leds.py)
        
        There's a script called `the_matrix_leds` which can set specified LEDs on
        individually - that may be useful for testing too. You can specify LEDs either
        by coordinates or by their logical number in hex, or groups of LEDs by AS1130
        pin:
        
            # turn on three LEDs
            the_matrix_leds 7 9 b0
        
            # turn on top left corner and top right corner LEDs
            the_matrix_leds 0,0 23,0
        
            # turn on all LEDs whose anode connects to CS2
            the_matrix_leds cs2
        
            # turn on all LEDs whose cathode connects to CS10
            the_matrix_leds /CS10
        
        If you don't specify a board address, the script will automatically detect any
        TheMatrix boards and send the same commands to each.
        
        If you want to specify one or more boards, you can do so with the `-a` option:
        
            # turn on three LEDs, board address 0x37
            the_matrix_leds -a 0x37 7 9 b0
        
            # turn on some LEDs on boards 0x30 and 0x31
            the_matrix_leds -a 0x30,0x31 /CS9
        
        It can also show a map of the physical connections for each LED:
        
            the_matrix_leds -p
        
            Physical layout:
            +-----------+-----------+-----------+-----------+-----------+-----------+-----------+-----------+-----------+-----------+-----------+-----------+
            |    /CS0   |    /CS1   |    /CS2   |    /CS3   |    /CS4   |    /CS5   |    /CS6   |    /CS7   |    /CS8   |    /CS9   |   /CS10   |   /CS11   |
            +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
            | CS1 | CS6 | CS0 | CS6 | CS0 | CS6 | CS0 | CS6 | CS0 | CS6 | CS0 | CS6 | CS0 | CS5 | CS0 | CS5 | CS0 | CS5 | CS0 | CS5 | CS0 | CS5 | CS0 | CS5 |
            +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
            | CS2 | CS7 | CS2 | CS7 | CS1 | CS7 | CS1 | CS7 | CS1 | CS7 | CS1 | CS7 | CS1 | CS7 | CS1 | CS6 | CS1 | CS6 | CS1 | CS6 | CS1 | CS6 | CS1 | CS6 |
            +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
            | CS3 | CS8 | CS3 | CS8 | CS3 | CS8 | CS2 | CS8 | CS2 | CS8 | CS2 | CS8 | CS2 | CS8 | CS2 | CS8 | CS2 | CS7 | CS2 | CS7 | CS2 | CS7 | CS2 | CS7 |
            +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
            | CS4 | CS9 | CS4 | CS9 | CS4 | CS9 | CS4 | CS9 | CS3 | CS9 | CS3 | CS9 | CS3 | CS9 | CS3 | CS9 | CS3 | CS9 | CS3 | CS8 | CS3 | CS8 | CS3 | CS8 |
            +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
            | CS5 | CS10| CS5 | CS10| CS5 | CS10| CS5 | CS10| CS5 | CS10| CS4 | CS10| CS4 | CS10| CS4 | CS10| CS4 | CS10| CS4 | CS10| CS4 | CS9 | CS4 | CS9 |
            +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
        
        and a logical map with the LED numbers in hex (the same numbers it expects on
        the command line):
        
            the_matrix_leds -l
        
            Logical layout:
            +-----------+-----------+-----------+-----------+-----------+-----------+-----------+-----------+-----------+-----------+-----------+-----------+
            | Segment 0 | Segment 1 | Segment 2 | Segment 3 | Segment 4 | Segment 5 | Segment 6 | Segment 7 | Segment 8 | Segment 9 | Segment A | Segment B |
            +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
            |  00 |  05 |  10 |  15 |  20 |  25 |  30 |  35 |  40 |  45 |  50 |  55 |  60 |  65 |  70 |  75 |  80 |  85 |  90 |  95 |  A0 |  A5 |  B0 |  B5 |
            +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
            |  01 |  06 |  11 |  16 |  21 |  26 |  31 |  36 |  41 |  46 |  51 |  56 |  61 |  66 |  71 |  76 |  81 |  86 |  91 |  96 |  A1 |  A6 |  B1 |  B6 |
            +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
            |  02 |  07 |  12 |  17 |  22 |  27 |  32 |  37 |  42 |  47 |  52 |  57 |  62 |  67 |  72 |  77 |  82 |  87 |  92 |  97 |  A2 |  A7 |  B2 |  B7 |
            +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
            |  03 |  08 |  13 |  18 |  23 |  28 |  33 |  38 |  43 |  48 |  53 |  58 |  63 |  68 |  73 |  78 |  83 |  88 |  93 |  98 |  A3 |  A8 |  B3 |  B8 |
            +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
            |  04 |  09 |  14 |  19 |  24 |  29 |  34 |  39 |  44 |  49 |  54 |  59 |  64 |  69 |  74 |  79 |  84 |  89 |  94 |  99 |  A4 |  A9 |  B4 |  B9 |
            +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
        
        ## [the_matrix_scrolltext](./the_matrix/scrolltext.py)
        
        This example displays scrolling text messages across one or more TheMatrix
        boards:
        
            the_matrix_scrolltext Hello, world!
        
        If you don't specify a board address, the script will auto-detect and use any
        TheMatrix boards it finds. It will assume that they're arrange in ascending
        address order, left-to-right, and will combine them into a wide display. For
        example, with addresses 0x30 and 0x34, it would assume the following display:
        
            +------+------+
            | 0x30 | 0x34 |
            +------+------+
        
        If you want to specify particular boards, or if they are not arranged in the
        expected order, you can use the `-a` option:
        
            # scroll message on one particular board
            the_matrix_scrolltext -a 0x37 'hello again'
        
            # scroll message on two unsorted boards
            the_matrix_scrolltext -a 0x34,0x30 'custom order'
        
        ## Web Interface - [the_matrix_web](./the_matrix/web.py)
        
        This is a very basic web interface for controlling TheMatrix. It runs on the
        Raspberry Pi and uses the code described above. It needs Flask to run,
        which should have been installed when you installed the module with `pip`.
        
        To start the application, just run it:
        
            the_matrix_web
        
        and visit your Raspberry Pi's IP address or hostname on port 5000 in your
        browser. The application lets you control individual LEDS, rows and columns of
        them together and vary the LED current.
        
        The web interface auto-detects the connected boards and displays a separate
        matrix input for each one. You can control indvidual LEDs, whole rows and whole
        columns on each board.
        
        There's also a graphical depiction of the AS1130 chip which you can use to
        toggle LEDs based on their connection to the chip itself. This may be useful
        when debugging soldering problems - experimenting with the high and low toggles
        for each pin will let you track down exactly which pins have got bad joints, if
        any, or if the problem instead lies with the LEDs.
        
        If toggling a given pin makes any difference at all, the connection on the chip
        is probably okay. :)
        
Keywords: boldport led matrix i2c rpi as1130
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
