# Introducing Adafruit Trellis ## Overview ![](https://cdn-learn.adafruit.com/assets/assets/000/012/733/medium800/adafruit_products_1616_LRG.jpg?1386359574) ![](https://cdn-learn.adafruit.com/assets/assets/000/012/752/medium800/adafruit_products_1616finger8x8_LRG.jpg?1386361285) Trellis is an open source backlight keypad driver system. It is easy to use, works with any 3mm LEDs and eight tiles can be tiled together on a shared I2C bus. ![](https://cdn-learn.adafruit.com/assets/assets/000/012/730/medium800/adafruit_products_1616top_LRG.jpg?1386359520) The Trellis PCB is specially made to match the Adafruit 4x4 elastomer keypad. Each Trellis PCB has 4x4 pads and 4x4 matching spots for 3mm LEDs. The circuitry on-board handles the background key-presses and LED lighting for the 4x4 tile. However, it does not have any microcontroller or other 'brains' - an Arduino (or similar microcontroller) is required to control the Trellis to read the keypress data and let it know when to light up LEDs as desired. ![](https://cdn-learn.adafruit.com/assets/assets/000/012/732/medium800/adafruit_products_1616bottom_LRG.jpg?1386359558) Each tile has an I2C-controlled LED sequencer and keypad reader already on it. The chip can control all 16 LEDs individually, turning them on or off. It cannot do grayscale or dimming. The same chip also reads any keypresses made with the rubber keypad. The connections are 'diode multiplexed' so you do not have to worry about "ghosting" when pressing multiple keys, each key is uniquely addressed. ![](https://cdn-learn.adafruit.com/assets/assets/000/012/750/medium800/adafruit_products_1616casual8x8_LRG.jpg?1386361254) The tiles have 3 address jumpers. You can tile up to 8 PCBs together (for a total of 4x32 or 16x8=128 buttons/leds) on a single I2C bus, as long as each one has a unique address. All the tiles connect by the edges with solder, and share the same power, ground, interrupt, and i2c clock/data pins. So, you can easily set up to 128 LEDs and read up to 128 buttons using only 2 I2C wires! The tiles can be arranged in any configuration they want as long as each tile is connected to another with the 5 edge-fingers. ![](https://cdn-learn.adafruit.com/assets/assets/000/012/751/medium800/adafruit_products_1616bottom8x8_LRG.jpg?1386361264) Each LED is multiplexed with a constant-current driver, so you can mix and match any colors you like. You don't need it to be all blue, all red, etc. Mix it up! Any 3mm LED can be used, although we find that diffused LEDs with 250mcd+ brightness look best. # Introducing Adafruit Trellis ## Adding LEDs ![](https://cdn-learn.adafruit.com/assets/assets/000/012/749/medium800/adafruit_products_1616isoled_LRG.jpg?1386361205) The Trellis PCB comes with all the driver circuitry **but doesn't come with LEDs installed!** This is because we know people want to get creative with the LED colors - choose any color you like! Diffused 3mm LEDs with 250mcd+ brightness look best. As you can see here, the LEDs sit inside the button cavity and the two button contacts surround it. This allows for the nice frosted LED effect. The LEDs are seperately controlled from the buttons - an Arduino or similar is required to read data from the buttons and then write out what LEDs to light up. ![](https://cdn-learn.adafruit.com/assets/assets/000/012/735/medium800/adafruit_products_ledplace.jpg?1386360178) LEDs have **polarity** so they have to be installed the right way or they won't work! There's a little + symbol on the left hand LED pads, thats the anode/positive pin. LEDs have a longer leg on the + pin so make sure that pin goes into the + hole. ![](https://cdn-learn.adafruit.com/assets/assets/000/012/736/medium800/adafruit_products_ledpolarity.jpg?1386360255) You can do one LED at a time, or all at once, its up to you and how experienced you are in soldering LEDs. Bend the LED legs out so that the LEDs sit nice and flat against the PCB. Flip over the PCB so you can solder them in ![adafruit_products_ledflip.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/737/medium640/adafruit_products_ledflip.jpg?1386360463) Solder each and every LED leg. I like to do one LED at a time. ![adafruit_products_ledsolder1.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/738/medium640/adafruit_products_ledsolder1.jpg?1386360512) ![adafruit_products_ledsolder2.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/739/medium640/adafruit_products_ledsolder2.jpg?1386360638) Clip the legs about 2-3mm from the PCB so the leads aren't flying everywhere ![adafruit_products_ledclip.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/740/medium640/adafruit_products_ledclip.jpg?1386360745) ![adafruit_products_ledclipped.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/741/medium640/adafruit_products_ledclipped.jpg?1386360775) Keep soldering! ![adafruit_products_ledsolder3.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/742/medium640/adafruit_products_ledsolder3.jpg?1386360820) ![adafruit_products_ledsclip.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/745/medium640/adafruit_products_ledsclip.jpg?1386361056) ![adafruit_products_ledsolder4.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/747/medium640/adafruit_products_ledsolder4.jpg?1386361124) Till you are done with all of them ![adafruit_products_ledsdone.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/748/medium640/adafruit_products_ledsdone.jpg?1386361171) # Introducing Adafruit Trellis ## Connecting ![](https://cdn-learn.adafruit.com/assets/assets/000/012/783/medium800/adafruit_products_1616_LRG.jpg?1386363564) As shown here, Trellis is just an LED/keypad controller. You still need an Arduino or similar to do the work of reading the keypad data and then signifying when to light LEDs. Luckily, we wrote a library that handles all the hard work for you, making it all very easy! [Download the Trellis Arduino library from our github repository](https://github.com/adafruit/Adafruit_Trellis_Library) by clicking this shiny button [Download Trellis Arduino library](https://github.com/adafruit/Adafruit_Trellis_Library/archive/master.zip) Rename the uncompressed folder **Adafruit\_Trellis**. Check that the **Adafruit\_**** Trellis **folder contains** Adafruit\_ ****Trellis****.cpp **and** Adafruit\_ ****Trellis****.h **, and an** examples** folder Place the **Adafruit\_Trellis** library folder your **_sketchbookfolder_/libraries/** folder. You may need to create the libraries subfolder if its your first library. Restart the IDE. You can figure out your **_sketchbookfolder_** by opening up the Preferences tab in the Arduino IDE. If you're not familiar with installing Arduino libraries, please visit our tutorial: [All About Arduino Libraries](http://learn.adafruit.com/adafruit-all-about-arduino-libraries-install-use "Link: http://learn.adafruit.com/adafruit-all-about-arduino-libraries-install-use")!Next we will connect up the PCBs, we soldered solid-core wires from the 5 connection fingers and plug them into an Arduino. We suggest starting with an Uno since its guaranteed to work Connect the wires: - **5V** goes to the 5V power pin on the Arduino - **GND** goes to and GND ground pin - **SCL** goes to the I2C clock pin, on an Uno this is also known as A5 - **SDA** goes to the I2C data pin, on an Uno this is also known as A4 - We connect the **INT** interrupt pin to A2 - this pin isn't used in our demo code so you can leave it unconnected if you wish. ![](https://cdn-learn.adafruit.com/assets/assets/000/012/785/medium800/adafruit_products_trellisconnect.jpg?1386364170) Now open up the Arduino IDE and open up the **File-\>Examples-\>Adafruit\_Trellis-\>TrellisTest** example sketch and upload it to your Arduino This sketch tests a single tile, with the default 0x70 address. It will light up all the LEDs in order and then turn them off. Then you can place the elastomer on top & press buttons to toggle buttons # Library reference The trellis example sketch shows you just about everything you can do with the Trellis library. ## Creating the objects Each panel has its own named object called an Adafruit\_Trellis, created like this: > **Adafruit\_Trellis matrix = Adafruit\_Trellis();** when you have many Adafruit\_Trellis objects, we suggest creating a TrellisSet which will read all the buttons at once, write all the LEDs at once, etc. Each TrellisSet is given the names of the Adafruit\_Trellis objects you created, up to 8. > **Adafruit\_TrellisSet trellis = Adafruit\_TrellisSet(&matrix0, &matrix1, &matrix2, &matrix3);** When you call **begin** to start the **Adafruit\_TrellisSet** object, pass in the addresses that correspond to your PCBs (see the next page on how to set addresses). The addresses range from 0x70 to 0x77 > **trellis.begin(0x70, 0x71, 0x72, 0x73); // or four!** ## Controlling LEDs You can set or clear LEDs with **trellis.setLED(_n_)** and **trellis.clrLED(_n_)** where **n** is the LED # from 0 to (number of Trellis')\*16-1. So if you have 4 Trellis's in a set, thats 0 to 63 You can only turn LEDs on or off, there is no grayscale or PWM on this chip When you are done setting and clearing LEDs you **must** call writeDisplay() to send the data to all the boards: **trellis.writeDisplay()** will write all Trellis PCBs in the set at once You can also test if an LED is lit with **trellis.isLED(_n_)** - will return true if the LED is lit, and false if it isn't # Reading Switches You can read buttons by calling > **trellis.readSwitches()** It will return **true** if there has been any **change** in switches since the last time you called readSwitches(). So if some buttons were pressed and now aren't or vice versa, it will return **true**. If nothing's changed, it will return **false** Once you've read the switches, you can query the TrellisSet about them. If you'd like to know if a key # **k** (k is 0..(number of Trellis')\*16-1) is currently pressed, call > **isKeyPressed(_k_)** If you want to know if there was a _change_ in the button, you can ask if it's been pressed or released since the last call to readSwitches() > **trellis.justReleased(_k_)** > **trellis.justPressed(_k_)** # Adding support for more tiles You can tile up to 8 Trellis PCBs together (see the next page for the mechanical connections of doing so) Make sure each Trellis has a unique address ID! Open up the TrellisTest sketch and change the following ## Make more objects After **Adafruit\_Trellis matrix0 = Adafruit\_Trellis();** add as many matrices as you like, each with a unique name, e.g. **Adafruit\_Trellis matrix1 = Adafruit\_Trellis();** **Adafruit\_Trellis matrix2 = Adafruit\_Trellis();** etc... ## Make a bigger set Next we will make a set of matrices. Instead of **Adafruit\_TrellisSet trellis = Adafruit\_TrellisSet(&matrix0);** update it to add up to 8 matrix names you defined. For example, 4 panels looks like: **Adafruit\_TrellisSet trellis = Adafruit\_TrellisSet(&matrix0, &matrix1, &matrix2, &matrix3);** ## Say the number Change this number from 1 to whatever # you are addressing // set to however many you're working with here, up to 8 **#define NUMTRELLIS 1** Begin again Change the begin() call to add more addresses. Originally we only have the default 0x70 address: **trellis.begin(0x70); // only one** Change this to add all the addresses you are using: **trellis.begin(0x70, 0x71, 0x72, 0x73);** // four! That's it! Now your TrellisSet will know and control up to 8 panels. # Introducing Adafruit Trellis ## Tiling ![](https://cdn-learn.adafruit.com/assets/assets/000/012/753/medium800/adafruit_products_1616finger8x8_LRG.jpg?1386361305) You can tile up to eight Trellis PCBs on a single 2-wire I2C bus. This allows you to easily build up to 8x16 or 4x32 panels which can be lots of fun! To start with, its a good idea to assemble and test each individually so you know each Trellis works individually. ![](https://cdn-learn.adafruit.com/assets/assets/000/012/766/medium800/adafruit_products_1616bottom8x8_LRG.jpg?1386362492) There's little nubs on the sides of some PCBs that keep them on the assembly panel, you can file them off with any file or sandpaper. ![adafruit_products_file.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/761/medium640/adafruit_products_file.jpg?1386362160) Arrange the tiles up the way you want, we'll start with two. Make sure the Adafruit logo is lined up the same. ![adafruit_products_tilestart.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/759/medium640/adafruit_products_tilestart.jpg?1386362041) Solder two blobs of solder on two adjacent finger pads. ![adafruit_products_tileblob.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/760/medium640/adafruit_products_tileblob.jpg?1386362092) Use your soldering iron to drag solder from one pad to another, with a little effort they'll stick together and make a connection. You can add more solder to make the connection stronger. Its still not mechanically strong - so be careful not to bend or shake the arrangement ![adafruit_products_tiletack.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/762/medium640/adafruit_products_tiletack.jpg?1386362229) ![adafruit_products_tiletacked.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/763/medium640/adafruit_products_tiletacked.jpg?1386362277) _For a more robust connection, use a small bare wire across the pads instead of just solder. The legs trimmed off the LEDs are perfect for this!_ Repeat for the other 4 fingers ![adafruit_products_tiledone.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/764/medium640/adafruit_products_tiledone.jpg?1386362351) Check that the panels are aligned by looking from the side, gently bend/reheat until they are nice and straight ![adafruit_products_align1.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/777/medium640/adafruit_products_align1.jpg?1386362932) ![adafruit_products_align2.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/778/medium640/adafruit_products_align2.jpg?1386362967) You can add a little more mechanical stability by soldering the large front tabs as well ![adafruit_products_toptack.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/773/medium640/adafruit_products_toptack.jpg?1386362818) ![adafruit_products_toptacked.jpg](https://cdn-learn.adafruit.com/assets/assets/000/012/775/medium640/adafruit_products_toptacked.jpg?1386362851) ![](https://cdn-learn.adafruit.com/assets/assets/000/012/768/medium800/adafruit_products_1616top8x8_LRG.jpg?1386362537) Repeat for up to 8 panels connected together, in any arrangement you like # Addressing Each Trellis tile must have a unique address. You can set the addresses on the back of each panel using a little solder over the address jumpers. The HT16K33 driver chip on the Trellis has a default I2C address of **0x70**. Since each device on an I2C bus must have a unique address, its important to avoid collisions or you'll get a lot of strange responses from your electronic devices! Luckily, the HT16K33 has 3 address adjust pins, so that the address can be changed. Each pin changes one binary bit of the address, so you can set the address to any of the following (in hex) 0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76, 0x77 The panels don't have to have consecutive address #'s, they just have to be unique. ## Changing Addresses You can change the address of very easily. Look on the back to find the three **A0, A1 or A2** solder jumpers. Each one of these is used to hardcode in the address. If a jumper is shorted with solder, that sets the address. **A0** sets the lowest bit with a value of **1** , **A1** sets the middle bit with a value of **2** and **A2** sets the high bit with a value of **4**. The final address is **0x70 + A2 + A1 + A0**. So for example if **A2** is shorted and **A0** is shorted, the address is **0x70 + 4 + 1 = 0x75.** If only A1 is shorted, the address is **0x70 + 2 = 0x72** For example, this Trellis has **A0** shorted, the address is 0x71 ![](https://cdn-learn.adafruit.com/assets/assets/000/012/779/medium800/adafruit_products_addr71.jpg?1386363292) This one has **A1** shorted, the address is 0x72 ![](https://cdn-learn.adafruit.com/assets/assets/000/012/780/medium800/adafruit_products_addr72.jpg?1386363356) If both **A0** and **A1** are shorted, the address is 0x73 ![](https://cdn-learn.adafruit.com/assets/assets/000/012/781/medium800/adafruit_products_addr73.jpg?1386363386) If **A2** , **A0** and **A1** are shorted, the address is 0x77 ![](https://cdn-learn.adafruit.com/assets/assets/000/012/782/medium800/adafruit_products_addr77.jpg?1386363398) Once you have set the unique addresses, you can set the addresses in the Arduino code, see the software page for details on how to do it. # Introducing Adafruit Trellis ## Python & CircuitPython It's easy to use the Adafruit Trellis with Python or CircuitPython, and the [Adafruit CircuitPython Trellis module](https://github.com/adafruit/Adafruit_CircuitPython_Trellis). This module enables you to write Python code that allows you to easily control the LEDs and read button presses on a single Trellis board, or with a matrix of up to eight Trellis boards. You can use this board with any CircuitPython microcontroller board or with a computer that has GPIO and Python [thanks to Adafruit\_Blinka, our CircuitPython-for-Python compatibility library](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux). ## CircuitPython Microcontroller Wiring First wire up a Trellis to your board exactly as shown on the previous pages for Arduino.  Here's an example of wiring a Feather M0 to the Trellis using I2C: - **Board 3V**  to **Trellis 5V/VCC** - **Board GND**  to **Trellis GND** - **Board SCL**  to **Trellis SCL** - **Board SDA** to  **Trellis** **SDA** ![adafruit_products_Trellis_Feather_M0_bb.png](https://cdn-learn.adafruit.com/assets/assets/000/082/071/medium640/adafruit_products_Trellis_Feather_M0_bb.png?1570221664) ## Python Computer Wiring Since there's _dozens_ of Linux computers/boards you can use we will show wiring for Raspberry Pi. For other platforms, [please visit the guide for CircuitPython on Linux to see whether your platform is supported](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux).  Here's the Raspberry Pi wired to a Trellis: - **Pi 5V** to **Trellis 5V** - **Pi GND** to **Trellis GND** - **Pi SCL** to **Trellis SCL** - **Pi SDA** to **Trellis SDA** ![adafruit_products_raspi_trellis_i2c_bb.png](https://cdn-learn.adafruit.com/assets/assets/000/082/076/medium640/adafruit_products_raspi_trellis_i2c_bb.png?1570221953) ## CircuitPython Installation of Trellis Library Next you'll need to install the [Adafruit CircuitPython Trellis](https://github.com/adafruit/Adafruit_CircuitPython_Trellis) library on your CircuitPython board.   First, make sure you are running the [latest version of Adafruit CircuitPython](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython) for your board. Next, you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from [Adafruit's CircuitPython library bundle](https://circuitpython.org/libraries).  Our introduction guide has [a great page on how to install the library bundle](https://learn.adafruit.com/welcome-to-circuitpython/circuitpython-libraries) for both express and non-express boards. Copy the following libraries from the bundle to the **lib** folder on your **CIRCUITPY** drive: - **adafruit\_trellis.mpy** - **adafruit\_bus\_device** Before continuing make sure your board's **lib** folder or root filesystem has the  **adafruit\_trellis.mpy,** and ** adafruit\_bus\_device****   **files and folders**  **copied over. Next[ connect to the board's serial REPL](https://learn.adafruit.com/welcome-to-circuitpython/the-repl) so you are at the CircuitPython  **\>\>\>**  prompt. ## Python Installation of Trellis Library You'll need to install the **Adafruit\_Blinka** library that provides the CircuitPython support in Python. This may also require enabling I2C on your platform and verifying you are running Python 3. [Since each platform is a little different, and Linux changes often, please visit the CircuitPython on Linux guide to get your computer ready](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux)! Once that's done, from your command line run the following command: - `pip3 install adafruit-circuitpython-trellis` If your default Python is version 3 you may need to run 'pip' instead. Just make sure you aren't trying to use CircuitPython on Python 2.x, it isn't supported! ## CircuitPython & Python Usage To demonstrate the usage of the Trellis, we'll initialize it, control the LEDs and read the button presses from the board's Python REPL. Run the following code to import the necessary modules and initialize the I2C connection with the Trellis: ```python import time import busio from board import SCL, SDA from adafruit_trellis import Trellis i2c = busio.I2C(SCL, SDA) trellis = Trellis(i2c) ``` Now, you're ready to control the LEDs and read button presses with the following: - **fill** - Turns on all of the LEDs - **brightness** - Change the brightness of the LEDs - **auto\_show** - When set to True, LED changes update automatically. When set to False, you must call `show()` to update the LEDs. Defaults to True. - **show()** - Required to update the LEDs if `auto_show=False`. - **read\_buttons** - read the button matrix on the Trellis board. Returns two lists: one for button presses and one for button releases. To turn on all the LEDs: ```python trellis.led.fill(True) ``` To turn off all the LEDs: ```python trellis.led.fill(False) ``` To read when the buttons are pressed and released: ```python pressed_buttons = set() while True: time.sleep(.1) just_pressed, released = trellis.read_buttons() for b in just_pressed: print('pressed:', b) trellis.led[b] = True pressed_buttons.update(just_pressed) for b in released: print('released:', b) trellis.led[b] = False pressed_buttons.difference_update(released) for b in pressed_buttons: print('still pressed:', b) trellis.led[b] = True ``` ![](https://cdn-learn.adafruit.com/assets/assets/000/082/152/medium800/adafruit_products_Trellis_read_buttons_output_REPL.png?1570484735) That's all there is to using your Trellis with CircuitPython! ## Full Example Code https://github.com/adafruit/Adafruit_CircuitPython_Trellis/blob/main/examples/trellis_simpletest.py # Introducing Adafruit Trellis ## Python Docs # Introducing Adafruit Trellis ## Downloads ![](https://cdn-learn.adafruit.com/assets/assets/000/012/795/medium800/adafruit_products_shade.gif?1448052299) - [EagleCAD PCB and CAD files for the Trellis buttons and PCB from the github repo here](https://github.com/adafruit/Adafruit_Trellis "Link: https://github.com/adafruit/Adafruit\_Trellis") - [You can get the Arduino library for Trellis from the github repo here](https://github.com/adafruit/Adafruit_Trellis_Library "Link: https://github.com/adafruit/Adafruit\_Trellis\_Library") - [Fritzing object in the Adafruit Fritzing library](https://github.com/adafruit/Fritzing-Library) # Schematic ![](https://cdn-learn.adafruit.com/assets/assets/000/035/764/medium800/adafruit_products_schem.png?1474059909) # Fabrication Print Dims in mm ![](https://cdn-learn.adafruit.com/assets/assets/000/035/765/medium800/adafruit_products_fabprint.png?1474059948) ## Related Guides - [Trellis M4 Audio Filter Visualizer](https://learn.adafruit.com/trellis-m4-audio-visualizer-and-filter.md) - [Launch Deck Trellis M4](https://learn.adafruit.com/launch-deck-trellis-m4.md) - [IR Sensor](https://learn.adafruit.com/ir-sensor.md) - [Crickit Powered Holiday Diorama](https://learn.adafruit.com/crickit-powered-holiday-diorama.md) - [MIDI for Makers](https://learn.adafruit.com/midi-for-makers.md) - [NeoTrellis Sound Board](https://learn.adafruit.com/neotrellis-soundboard.md) - [Ambient Color Control Pad](https://learn.adafruit.com/ambient-color-controller.md) - [Guardian Robot – Zelda BOTW](https://learn.adafruit.com/guardian-robot-zelda-botw.md) - [Adafruit NeoTrellis M4 Express](https://learn.adafruit.com/adafruit-neotrellis-m4.md) - [Guardian Robot with LEDs](https://learn.adafruit.com/guardian-robot-with-leds.md) - [Capacitive Touch Unicorn Horn](https://learn.adafruit.com/capacitive-touch-unicorn-horn.md) - [NeoTrellis MIDI Feedback Controller](https://learn.adafruit.com/neotrellis-midi-feedback-controller.md) - [Wireless NeoPixel Controller](https://learn.adafruit.com/neotrellis-neopixel-controller.md) - [How to Build a Testing Jig](https://learn.adafruit.com/how-to-build-a-testing-fixture.md) - [Adafruit 555 PWM Output STEMMA](https://learn.adafruit.com/adafruit-555-pwm-output-stemma.md)