# LED Backpack Displays on Raspberry Pi and BeagleBone Black ## Overview Danger: Recommended Guide: [Matrix and 7-Segment LED Backpack with the Raspberry Pi](https://learn.adafruit.com/matrix-7-segment-led-backpack-with-the-raspberry-pi/overview) https://www.youtube.com/watch?v=7h73ffhzj0Q&feature=youtu.be LED backpack displays are a great way to add a simple, bright LED display to your project. These displays get their name because of the controller chip attached to the back of them like a 'backpack'. This HT16K33 controller can drive up to 128 multiplexed LEDs in matrix, bar graph, 7-segment numeric, and even 14-segment alpha-numeric configurations. It handles the LEDs with a constant-current driver so the light is bright and consistent even if the power supply varies. Best of all, the controller exposes a very simple I2C-based interface which is easy for a small-board computer like the Raspberry Pi or BeagleBone Black to access. This guide will show you how to install and use the [Adafruit Python LED backpack library](https://github.com/adafruit/Adafruit_Python_LED_Backpack "Link: https://github.com/adafruit/Adafruit\_Python\_LED\_Backpack") for driving LED backpack displays from a Raspberry Pi or BeagleBone Black! Before you get started be sure to read the [LED backpack guide](https://learn.adafruit.com/adafruit-led-backpack/overview) to familiarize yourself with the assembly and basic usage of the backpack displays. You will also want to be familiar with connecting to and using a [Raspberry Pi](https://learn.adafruit.com/category/learn-raspberry-pi) or [BeagleBone Black's Linux command line](https://learn.adafruit.com/ssh-to-beaglebone-black-over-usb). Finally, make sure your Raspberry Pi is running the latest [Raspbian](http://www.raspberrypi.org/downloads/) or [Occidentalis](https://learn.adafruit.com/adafruit-raspberry-pi-educational-linux-distro/occidentalis-v0-dot-2 "Link: https://learn.adafruit.com/adafruit-raspberry-pi-educational-linux-distro/occidentalis-v0-dot-2") operating system, or your BeagleBone Black is running the [official Debian](http://beagleboard.org/project/debian/ "Link: http://beagleboard.org/project/debian/") or a Debian-based operating system like Ubuntu. # LED Backpack Displays on Raspberry Pi and BeagleBone Black ## Wiring # Raspberry Pi **Note:** Before wiring up your display, make sure you've [enabled I2C access on the Raspberry Pi](https://learn.adafruit.com/adafruits-raspberry-pi-lesson-4-gpio-setup/configuring-i2c "Link: https://learn.adafruit.com/adafruits-raspberry-pi-lesson-4-gpio-setup/configuring-i2c"). Wire up the LED backpack display to the Pi as follows (note the image below shows a matrix display, however the wiring is the same for any backpack): ![](https://cdn-learn.adafruit.com/assets/assets/000/017/841/medium800/leds_RaspberryPi_I2C_bb.png?1404439131) - Connect **display + (power)** to **Raspberry Pi 3.3V or 5V power** (red wire). 5V is brighter but if you have other devices on the I2C bus its better to go with 3.3V - Connect **display - (ground)** to **Raspberry Pi ground** (black wire). - Connect **display D (data/SDA)** to **Raspberry Pi SDA** (orange wire). - Connect **display C (clock/SCL)** to **Raspberry Pi SCL** (purple wire). - If there's a **Vi2c** or **IO** pin, connect that to 3.3V as well # BeagleBone Black Wire up the LED backpack display to the BeagleBone Black as follows (note the image below shows a matrix display, however the wiring is the same for any backpack): ![](https://cdn-learn.adafruit.com/assets/assets/000/017/842/medium800/leds_BBB_I2C_bb.png?1404439602) - Connect **display + (power)** to **BeagleBone Black 3.3V** **or 5V power (red wire). 5V is brighter but if you have other devices on the I2C bus its better to go with 3.3V** - Connect **display - (ground)** to **BeagleBone Black ground** (black wire). - Connect **display D (data/SDA)** to **BeagleBone Black** **I2C2\_SDA pin P9\_20** (orange wire). - Connect **display C (clock/SCL)** to **BeagleBone Black** **I2C2\_SCL pin P9\_19** (purple wire). - If there's a **Vi2c**  or **IO** pin, connect that to 3.3V as well Note that the BeagleBone Black has two I2C interfaces and this wiring will use the **/dev/i2c-1** interface. Make sure there aren't any [device tree overlays loaded](../../../../introduction-to-the-beaglebone-black-device-tree/overview "Link: https://learn.adafruit.com/introduction-to-the-beaglebone-black-device-tree/overview") which use these I2C pins for other purposes. The default BeagleBone Black device tree configuration with no overlays loaded will expose the necessary I2C interface for the wiring above. # LED Backpack Displays on Raspberry Pi and BeagleBone Black ## Usage # Installation Before installing the LED backpack Python library you must first install a few dependencies. Make sure your Raspberry Pi or BeagleBone Black has internet access, then connect to its command prompt and execute: ``` sudo apt-get update sudo apt-get install build-essential python-dev python-smbus python-imaging git ``` Next download the [LED backpack Python library code and examples](https://github.com/adafruit/Adafruit_Python_LED_Backpack) by executing: ``` git clone https://github.com/adafruit/Adafruit_Python_LED_Backpack.git cd Adafruit_Python_LED_Backpack sudo python setup.py install ``` After executing the commands above the LED backpack Python library will be installed and available for any Python script to use. # Usage You can find a few examples of the library's usage inside the **examples** subdirectory. Navigate into this directory and run the appropriate script for your display. For example if you have your device wired to an 8x8 matrix, you would execute:``` cd examples sudo python matrix8x8_test.py ``` Once running, you should see different pixels of the matrix light up as the display cycles through lighting all the pixels individually. Then the example should end by displaying a graphic of a square with an X in the middle on the display. I'll walk through the **matrix8x8\_test.py** code below to describe the important usage details of the LED backpack library: ``` import time import Image import ImageDraw from Adafruit_LED_Backpack import Matrix8x8 ``` The first line imports the standard Python time library which is needed for the sleep function used later in the script. The next lines import the [Python Imaging Library](http://effbot.org/imagingbook/pil-index.htm "Link: http://effbot.org/imagingbook/pil-index.htm") which is used for drawing shapes on the display. The final line imports the **Matrix8x8** module from the **Adafruit\_LED\_Backpack** package. This line is important because it tells Python that the script will need to use the LED backpack library. ``` # Create display instance on default I2C address (0x70) and bus number. display = Matrix8x8.Matrix8x8() # Alternatively, create a display with a specific I2C address and/or bus. # display = Matrix8x8.Matrix8x8(address=0x74, busnum=1) # Initialize the display. Must be called once before using the display. display.begin() ``` The next lines create an instance of the **Matrix8x8** class and initialize it by calling the **begin()** method. You must call **begin()** once before calling other functions to update the display! Below the first line is a commented line which shows how to create a **Matrix8x8** class that uses a different I2C address or bus number. If you're using multiple displays on the same I2C bus they all must have a unique I2C address. By [soldering jumpers on the back of a backpack display closed](https://learn.adafruit.com/adafruit-led-backpack/changing-i2c-address "Link: https://learn.adafruit.com/adafruit-led-backpack/changing-i2c-address") you can control the address associated with a display. This commented line shows how to pass an address parameter which overrides the default 0x70 address with a new value of 0x74. If you need to use a different I2C bus, for example on a BeagleBone Black which has multiple I2C buses, you can pass the desired bus number in the busnum parameter. If you don't provide this busnum parameter the library will try to determine the default I2C bus for your device--if you followed the wiring in this guide you should be all set and not need to provide the I2C bus number. ``` # Run through each pixel individually and turn it on. for x in range(8): for y in range(8): # Clear the display buffer. display.clear() # Set pixel at position i, j to on. To turn off a pixel set # the last parameter to 0. display.set_pixel(x, y, 1) # Write the display buffer to the hardware. This must be called to # update the actual display LEDs. display.write_display() # Delay for half a second. time.sleep(0.5) ``` The next part of the program will iterate through all 8 rows and columns of the display and light up each pixel individually. You can see the **clear()** function is first used to turn off all the LEDs in the display buffer. Then the **set\_pixel()** function is called and given the x, y coordinates of the pixel and a value of 1 to enable the pixel. Finally the **write\_display()** function is called to write the display buffer to the hardware. It's very important to remember to call write\_display() or else you won't see the display LEDs change! ``` # Draw some shapes using the Python Imaging Library. # Clear the display buffer. display.clear() # First create an 8x8 1 bit color image. image = Image.new('1', (8, 8)) # Then create a draw instance. draw = ImageDraw.Draw(image) # Draw a rectangle with colored outline draw.rectangle((0,0,7,7), outline=255, fill=0) # Draw an X with two lines. draw.line((1,1,6,6), fill=255) draw.line((1,6,6,1), fill=255) # Draw the image on the display buffer. display.set_image(image) # Draw the buffer to the display hardware. display.write_display() ``` The final part of the program uses the [Python Imaging Library](http://effbot.org/imagingbook/pil-index.htm) to draw shapes on the display. First the display buffer is cleared, and then an 8x8 pixel 1-bit color image is created. Once the image is created a [drawing class](http://effbot.org/imagingbook/imagedraw.htm "Link: http://effbot.org/imagingbook/imagedraw.htm") is created which allows drawing on the image buffer. You can see how the rectangle and line functions draw basic shapes on the image. Finally the **set\_image()** function is called to write the image to the display buffer, and the display buffer is written to the hardware with **write\_display()**. If you'd like to draw text on the display, check out the [SSD1306 library examples](https://learn.adafruit.com/ssd1306-oled-displays-with-raspberry-pi-and-beaglebone-black/usage "Link: https://learn.adafruit.com/ssd1306-oled-displays-with-raspberry-pi-and-beaglebone-black/usage") for a sample of drawing text with the PIL library. However the 8x8 display is small and can't display more than a character or two! ![](https://cdn-learn.adafruit.com/assets/assets/000/017/843/medium800/leds_DSC00480_copy.jpg?1404457750) Above you can see an example of graphics drawn on the 8x8 matrix display. To use other displays such as the bicolor matrix, bicolor bar graph, 7 segment, or 14 segment display the basic usage is very similar to the **Matrix8x8** class above. You must first import the associated module from the **Adafruit\_LED\_Backpack** package, create an instance of the class (optionally passing a different I2C address or bus number), and call the **begin()** function to initialize the display. Beyond the setup, each display class has slightly different functionality which I'll cover below. ## Bicolor Matrix 8x8 The bicolor matrix display is demonstrated in the **bicolor\_matrix8x8\_test.py** script in the **examples** folder. This code demonstrates using the **BicolorMatrix8x8** class in a very similar way to the **Matrix8x8** class above. The key difference is that the **set\_pixel()** function takes a color value instead of a 1 or 0 value like with the **Matrix8x8** class. For example to set the pixel at position 1,1 red, the pixel at position 1,2 green, and the pixel at position 1,3 yellow you could write: ``` display.set_pixel(1, 1, BicolorMatrix8x8.RED) display.set_pixel(1, 2, BicolorMatrix8x8.GREEN) display.set_pixel(1, 3, BicolorMatrix8x8.YELLOW) ``` Notice that each color is represented by a global value in the **BicolorMatrix8x8** module. You can also pass a value of 0 to turn off a specific LED. Also the Python Imaging Library is slightly different than with the single color display. Instead of creating a 1-bit color image a full RGB color image is created. Any pixel in the image that is red (i.e. red component is 255 and all other components are 0) will have a red LED, and likewise for green (green component is 255) or yellow (red and green components are 255). **Any other color pixel will be treated as no color/LED lit.** Below you can see an example of graphics on the bicolor 8x8 matrix: ![](https://cdn-learn.adafruit.com/assets/assets/000/017/844/medium800/leds_DSC00479_copy.jpg?1404458027) ## Bicolor Bar Graph 24 The bicolor bar graph display is demonstrated in the **bicolor\_bargraph24\_test.py** script in the **examples** folder. This code will light up 3 bars at a time with different colors and move them up the display. In addition to animating the bars, the example will also cycle through the 16 different brightness levels that can be set for any of the LED backpack displays. The main loop of the example looks like:``` # Run through all bars and colors at different brightness levels. print 'Press Ctrl-C to quit.' brightness = 15 while True: # Set display brightness (15 is max, 0 is min). display.set_brightness(brightness) for i in range(24): # Clear the display buffer. display.clear() # Light up 3 bars, each a different color and position. display.set_bar(i, BicolorBargraph24.RED) display.set_bar(i+1, BicolorBargraph24.GREEN) display.set_bar(i+2, BicolorBargraph24.YELLOW) # Write the display buffer to the hardware. This must be called to # update the actual display LEDs. display.write_display() # Delay for half a second. time.sleep(0.5) # Decrease brightness, wrapping back to 15 if necessary. brightness -= 1 if brightness == 0: brightness = 15 ``` You can see the code starts at brightness level 15, the maximum brightness level, by calling the **set\_brightness()** function. With each iteration of the animation the code will decrease the brightness by one level, until it reaches 0 (minimum brightness) and wraps back up to max brightness. **It's important to note all of the LED backpack classes support the set\_brightness() function! You can dim all the pixels in a matrix, bargraph, or segment display.** You can also see the BicolorBargraph24 class has a **set\_bar()** function which turns on a bar at the specified position (0 to 23) with the given color. Just like with the **BicolorMatrix8x8** class you specify the color from a global value in the module. ## 7 Segment The 7 segment numeric display is demonstrated in the **sevensegment\_test.py** script in the **examples** folder. If you run this example it will loop through displaying different numeric values with different precision and justification (left or right side of the display). The example will also show printing hexadecimal values in a simple counter. The important functions with the 7 segment display are the **print\_float()** and **print\_hex()** functions. The **print\_float()** function will attempt to print a numeric value (either integer or floating point/fractional) to the 4 character 7 segment display. Your value must be small enough to fit on the display, or else you'll see an error display of 4 dashes, ----. For negative values a negative sign will be printed, but remember it takes up an entire digit to display! With the **print\_float()** function you can control how many decimal digits are printed for a floating point/fractional value. By default 2 decimal digits will be displayed, however you can specify the **decimal\_digits** parameter with a different number of digits (including 0 for no decimal digits!). The printed value will be rounded to the desired precision and printed on the display. In addition to controlling the decimal digit precision, you can also change the justification of the number on the display. By default numbers are printed with right justification, which means they are closest to the right side of the display. However if you pass the **justify\_right=False** parameter to the function then the number will be displayed closest to the left side of the display. The **print\_hex()** function will take an integer value between 0 and FFFF and display it in hexadecimal. This is useful for displaying a large range of values like a counter, however it's less intuitive to read (unless you're a machine that understands hexadecimal!). The **print\_hex()** function also has an optional **justify\_right** boolean parameter which controls which side of the display to print the value towards. Below you can see an example of the 7 segment display showing the number -3.14: ![](https://cdn-learn.adafruit.com/assets/assets/000/017/845/medium800/leds_DSC00476_copy.jpg?1404458165) ## 14 Segment Alphanumeric Display The 14 segment alphanumeric display is demonstrated in the **alphanum4\_test.py** script in the examples folder. If you run this example it will scroll a text message across the display. This display is great for showing complete text messages because the 14 segment displays are very flexible. With the 14 segment display the usage is very similar to the 7 segment display above. Just like the 7 segment display you can use the **print\_float()** and **print\_hex()** functions to print numeric and hexadecimal values. However in addition to those functions you can also use the **print\_str()** function to print any 4 character printable ASCII string! For example to print 'ADA!' (without quotes) to the display you could call: ``` display.print_str('ADA!') ``` Using the 14-segment display is as easy as that, just call **print\_str()** with 4 characters of text! Note that only the ASCII values 32-127 (the printable ASCII character range) are supported by the library right now. ![](https://cdn-learn.adafruit.com/assets/assets/000/017/846/medium800/leds_DSC00475_copy.jpg?1404458311) Above you can see the 14-segment display with the text 'ADA!' written to it. Enjoy using your LED backpack displays with the Python library! If you find issues or would like to contribute to the code, feel free to do so on [the library's GitHub home](https://github.com/adafruit/Adafruit_Python_LED_Backpack). ## Featured Products ### Raspberry Pi Model B 512MB RAM [Raspberry Pi Model B 512MB RAM](https://www.adafruit.com/product/998) Adafruit ships the **Raspberry Pi Model B 512MB RAM** as of 10/18/2012. The Raspberry Pi® is a single-board computer developed in the UK by the Raspberry Pi Foundation with the intention of stimulating the teaching of basic computer science in schools. The Raspberry... No Longer Stocked [Buy Now](https://www.adafruit.com/product/998) [Related Guides to the Product](https://learn.adafruit.com/products/998/guides) ### BeagleBone Black Rev C - 4GB Flash - Pre-installed Debian [BeagleBone Black Rev C - 4GB Flash - Pre-installed Debian](https://www.adafruit.com/product/1876) Note: As of May 12, 2014 Adafruit is shipping Rev C. We have discontinued selling Rev B. There are no exchanges or "upgrades" for Rev B to Rev C. If you liked the BeagleBone Black Rev B, you will love the Rev C! The Rev C still has a blistering 1GHz processor and 512MB... No Longer Stocked [Buy Now](https://www.adafruit.com/product/1876) [Related Guides to the Product](https://learn.adafruit.com/products/1876/guides) ### Bi-Color (Red/Green) 24-Bar Bargraph w/I2C Backpack Kit [Bi-Color (Red/Green) 24-Bar Bargraph w/I2C Backpack Kit](https://www.adafruit.com/product/1721) What's better than a single LED? Lots of LEDs! A fun way to make a small linear display is to use two 12-bar Bi-color bar-graphs. However, this LED bargraph is 'multiplexed' - so to control all the 48 LEDs you need a lot of pins. In Stock [Buy Now](https://www.adafruit.com/product/1721) [Related Guides to the Product](https://learn.adafruit.com/products/1721/guides) ### Adafruit Bicolor LED Square Pixel Matrix with I2C Backpack [Adafruit Bicolor LED Square Pixel Matrix with I2C Backpack](https://www.adafruit.com/product/902) What's better than a single LED? Lots of LEDs! A fun way to make a small colorful display is to use a [1.2" Bi-color 8x8 LED Matrix](http://www.adafruit.com/products/458). Matrices like these are 'multiplexed' - so to control all the 128 LEDs you need 24 pins.... In Stock [Buy Now](https://www.adafruit.com/product/902) [Related Guides to the Product](https://learn.adafruit.com/products/902/guides) ### Adafruit 0.56" 4-Digit 7-Segment Display with I2C Backpack - Red [Adafruit 0.56" 4-Digit 7-Segment Display with I2C Backpack - Red](https://www.adafruit.com/product/878) What's better than a single LED? Lots of LEDs! A fun way to make a small display is to use an [8x8 matrix](https://www.adafruit.com/category/37_88) or a [4-digit 7-segment display](https://www.adafruit.com/category/37_103). Matrices like these are... In Stock [Buy Now](https://www.adafruit.com/product/878) [Related Guides to the Product](https://learn.adafruit.com/products/878/guides) ### Quad Alphanumeric Display - Red 0.54" Digits w/ I2C Backpack [Quad Alphanumeric Display - Red 0.54" Digits w/ I2C Backpack](https://www.adafruit.com/product/1911) Display, elegantly, 012345678 or 9! Gaze, hypnotized, at ABCDEFGHIJKLM - well it can display the whole alphabet. You get the point. This is a nice, bright alphanumeric display that shows letters and numbers in a beautiful red hue. It's super bright and designed for viewing from distances... In Stock [Buy Now](https://www.adafruit.com/product/1911) [Related Guides to the Product](https://learn.adafruit.com/products/1911/guides) ### Adafruit Small 1.2" 8x8 LED Matrix w/I2C Backpack - Red [Adafruit Small 1.2" 8x8 LED Matrix w/I2C Backpack - Red](https://www.adafruit.com/product/1049) What's better than a single LED? Lots of LEDs! A fun way to make a small display is to use an [8x8 matrix](https://www.adafruit.com/category/37_88) or a [4-digit 7-segment display](https://www.adafruit.com/category/37_103). Matrices like these are... Out of Stock [Buy Now](https://www.adafruit.com/product/1049) [Related Guides to the Product](https://learn.adafruit.com/products/1049/guides) ### Small 1.2" 8x8 Ultra Bright Square Amber LED Matrix + Backpack [Small 1.2" 8x8 Ultra Bright Square Amber LED Matrix + Backpack](https://www.adafruit.com/product/1854) What's better than a single LED? Lots of LEDs! Matrices like these are 'multiplexed' - so to control 64 LEDs you need 16 pins. That's a lot of pins, and there are [driver chips like the MAX7219](//www.adafruit.com/products/453) that can control a matrix for you but... In Stock [Buy Now](https://www.adafruit.com/product/1854) [Related Guides to the Product](https://learn.adafruit.com/products/1854/guides) ## Related Guides - [Adafruit LED Backpacks](https://learn.adafruit.com/adafruit-led-backpack.md) - [CircuitPython Hardware: LED Backpacks & FeatherWings](https://learn.adafruit.com/micropython-hardware-led-backpacks-and-featherwings.md) - [Tap Tempo Trinket](https://learn.adafruit.com/tap-tempo-trinket.md) - [Making Adabot: Part 2](https://learn.adafruit.com/making-adabot-part-2.md) - [Trinket React Counter](https://learn.adafruit.com/trinket-react-counter.md) - [Personalized NextBus ESP8266 Transit Clock](https://learn.adafruit.com/personalized-esp8266-transit-clock.md) - [Fidget Spinner Tachometer](https://learn.adafruit.com/fidget-spinner-tachometer.md) - [Large Pi-based Thermometer and Clock](https://learn.adafruit.com/large-pi-based-thermometer-and-clock.md) - [Electronic Demon Costume](https://learn.adafruit.com/electronic-demon-costume.md) - [Mindfulness Clock OF DOOM](https://learn.adafruit.com/mindfulness-clock-of-doom.md) - [Ultrasonic Ruler](https://learn.adafruit.com/ultrasonic-ruler.md) - [3D Printed LED Knuckle Jewelry ](https://learn.adafruit.com/3d-printed-led-knuckle-jewelry.md) - [Trinket-Powered Conference Room Occupancy Display](https://learn.adafruit.com/trinket-powered-room-conference-occupancy-display.md) - [Introducing the Raspberry Pi 2 - Model B](https://learn.adafruit.com/introducing-the-raspberry-pi-2-model-b.md) - [Matrix Portal RGB Display Handbag](https://learn.adafruit.com/matrix-portal-rgb-display-handbag.md)