Package: the-matrix
# Driver Module for Boldport TheMatrixHere's a Python module to drive your board from a Raspberry Pi.## PrerequisitesYou need I2C set up on your Raspberry Pi. If you haven't done this before, youneed to enable the I2C hardware:sudo raspi-configChoose `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-smbusIt's possible that you'll need to reboot at this point, but I've not found thatnecessary on the Raspberry Pi boards I've tried so far.## InstallationThe module is available as a Python package, so you can install it with `pip`.# Install for Python 2pip install the_matrixor# Install for Python 3pip3 install the_matrixDepending on your system configuration, you may need to run those withsuperuser privileges:# Superuser install for Python 2sudo pip install the_matrixor# Superuser install for Python 3sudo pip3 install the_matrix## ConnectionsTo connect to the I2C bus on the Raspberry Pi, connect directly to theexpansion header. Here's a top-down view - pin 1 is closest to the displayconnector:VCC  1  2SDA  3  4SCL  5  67  8GND  9 1011 1213 1415 1617 1819 2021 2223 2425 2627 2829 3031 3233 3435 3637 3839 40[USB ports this end]## Usage>From your Raspberry Pi shell, run `i2cdetect` to check that your TheMatrix isresponding and has the address you're expecting:i2cdetect -y 1By default, TheMatrix will have address 0x30 if you haven't added a resistor atR5 (R4 on the prototype boards) to specify otherwise. The output should looksomething like this:0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f00:          -- -- -- -- -- -- -- -- -- -- -- -- --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 theaddress in the range expected for TheMatrix - 0x30 to 0x37. If you run thisscript with no parameters:# detect and identify TheMatrix boardsthe_matrix_identifythen each detected board will display its own address. If you want to identifya particular board or boards, you can specify their addresses on the commandline:# detect one specific boardthe_matrix_identify -a 0x30# detect two specific boardsthe_matrix_identify -a 0x30,0x31That might be useful if you've got other I2C devices on the same bus - somewrite-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 onindividually - that may be useful for testing too. You can specify LEDs eitherby coordinates or by their logical number in hex, or groups of LEDs by AS1130pin:# turn on three LEDsthe_matrix_leds 7 9 b0# turn on top left corner and top right corner LEDsthe_matrix_leds 0,0 23,0# turn on all LEDs whose anode connects to CS2the_matrix_leds cs2# turn on all LEDs whose cathode connects to CS10the_matrix_leds /CS10If you don't specify a board address, the script will automatically detect anyTheMatrix 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 0x37the_matrix_leds -a 0x37 7 9 b0# turn on some LEDs on boards 0x30 and 0x31the_matrix_leds -a 0x30,0x31 /CS9It can also show a map of the physical connections for each LED:the_matrix_leds -pPhysical 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 onthe command line):the_matrix_leds -lLogical 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 TheMatrixboards:the_matrix_scrolltext Hello, world!If you don't specify a board address, the script will auto-detect and use anyTheMatrix boards it finds. It will assume that they're arrange in ascendingaddress order, left-to-right, and will combine them into a wide display. Forexample, 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 theexpected order, you can use the `-a` option:# scroll message on one particular boardthe_matrix_scrolltext -a 0x37 'hello again'# scroll message on two unsorted boardsthe_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 theRaspberry 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_weband visit your Raspberry Pi's IP address or hostname on port 5000 in yourbrowser. The application lets you control individual LEDS, rows and columns ofthem together and vary the LED current.The web interface auto-detects the connected boards and displays a separatematrix input for each one. You can control indvidual LEDs, whole rows and wholecolumns on each board.There's also a graphical depiction of the AS1130 chip which you can use totoggle LEDs based on their connection to the chip itself. This may be usefulwhen debugging soldering problems - experimenting with the high and low togglesfor each pin will let you track down exactly which pins have got bad joints, ifany, or if the problem instead lies with the LEDs.If toggling a given pin makes any difference at all, the connection on the chipis probably okay. :)