Download
Share
Print this page
  1. Manuals
  2. Brands
  3. adafruit learning system Manuals
  4. Educational Equipment
  5. MatrixPortal M4
  6. Manual

adafruit learning system MatrixPortal M4 Manual

Hide thumbs

Advertisement

Quick Links

Download this manual
Adafruit MatrixPortal M4
Created by Melissa LeBlanc-Williams
Last updated on 2021-08-09 02:02:07 PM EDT

Advertisement

loading
Need help?

Need help?

Do you have a question about the MatrixPortal M4 and is the answer not in the manual?

Questions and answers

Related Manuals for adafruit learning system MatrixPortal M4

Summary of Contents for adafruit learning system MatrixPortal M4

  • Page 1 Adafruit MatrixPortal M4 Created by Melissa LeBlanc-Williams Last updated on 2021-08-09 02:02:07 PM EDT...
  • Page 2 Guide Contents Guide Contents Overview Pinouts Microcontroller and Flash WiFi HUB75 Connector RGB Matrix Power Sensors Stemma QT Connector Reset Pin Debugging Interface Serial UART Pins Analog Connector/Pins Power Pins Status LED and NeoPixel USB-C Connector Buttons Address E Line Jumper Prep the MatrixPortal Power Prep Power Terminals...
  • Page 3 MatrixPortal Module Library Demos CircuitPython Pins and Modules CircuitPython Pins import board I2C, SPI, and UART What Are All the Available Names? Microcontroller Pin Names CircuitPython Built-In Modules MatrixPortal Library Docs CircuitPython RGB Matrix Library CircuitPython BLE CircuitPython BLE UART Example On-Board Airlift Co-Processor - No Wiring Needed Update the AirLift Firmware Install CircuitPython Libraries...
  • Page 4 “doublebuffer_scrolltext” examples and tweaking these for their needs. Check Refresh Rate Arduino Sand Demo Protomatter Library Using the Accelerometer Arduino Usage CircuitPython Usage Updating ESP32 Firmware Downloads Files Schematic Fab Print © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 4 of 96...
  • Page 5 Overview Folks love Adafruit's wide selection of RGB matrices (https://adafru.it/NAX) and accessories for making custom colorful LED displays... and Adafruit RGB Matrix Shields and FeatherWings can be quickly soldered together to make the wiring much easier. But what if we made it even easier than that? Like, no solder, no wiring, just instant plug-and-play? Dream no more - with the Adafruit Matrix Portal add-on for RGB Matrices , there has never been an easier way to create powerful internet-connected LED displays.
  • Page 6 projects, power the matrices with a separate 5V power adapter) Then code up your project in CircuitPython (https://adafru.it/L7b) Arduino (https://adafru.it/MNa), the Adafruit Protomatter matrix library works great on the SAMD51 chipset, knowing that you've got the wiring and level shifting all handled. Here's what you get: ATSAMD51J19 Cortex M4 processor, 512KB flash, 192K of SRAM, with full Arduino or CircuitPython support ESP32 WiFi co-processor with TLS support and SPI interface to the M4, with full Arduino or...
  • Page 7 The Matrix Portal uses an ATMEL (Microchip) ATSAMD51J19, and an Espressif ESP32 Wi-Fi coprocessor with TLS/SSL support built-in. The M4 and ESP32 are a great couple - and each bring their own strengths to this board. The SAMD51 M4 has native USB, so it can show up like a disk drive, act as a MIDI or HID keyboard/mouse, and of course bootload and debug over a serial port.
  • Page 8 to act as the user interface. You get a great programming experience thanks to the native USB with files available for drag-n-drop, and you don't have to spend a ton of processor time and memory to do SSL encryption/decryption and certificate management. It's the best of both worlds! ©...
  • Page 9 Pinouts There are so many great features on the Adafruit MatrixPortal M4. Let's take a look at what's available! Microcontroller and Flash The main processor chip is the ATSAMD51J19 Cortex M4 running at 120MHz with 3.3v logic/power. It has 512KB of Flash and 192KB of RAM.
  • Page 10 The WiFi capability uses an Espressif ESP32 Wi-Fi coprocessor with TLS/SSL support built-in. The ESP32 uses the SPI port for data, and also uses a CS pin ( or Arduino ), Ready/Busy pin board.ESP_CS or Arduino ), and reset pin board.ESP_BUSY or Arduino board.ESP_RESET...

  • Page 11: Reset Pin

    There are +5V and Ground screw terminals on either side of the HUB75 connector. These provide power to the RGB Matrix. Sensors The MatrixPortal M4 includes a LIS3DH Triple-Axis Accelerometer. The accelerometer is connected via the I2C bus. Please note the address of the accelerometer is 0x19 not 0x18 which is the default in our libraries.

  • Page 12: Debugging Interface

    RST is the Reset pin. Tie to ground to manually reset the ATSAMD51, as well as launch the bootloader manually. Debugging Interface If you'd like to do more advanced development, trace- debugging, or not use the bootloader, we have the SWD interface exposed.

  • Page 13: Power Pins

    On the bottom side towards the right, there is a connector labeled A0. This is a 3-pin JST analog connector for sensors or NeoPixels, analog output or input Along the bottom there are also pins labeled through All of these pins can be used for analog inputs or digital I/O.
  • Page 14 RGB Matrix. Buttons There are three buttons along the left side of the MatrixPortal M4. The reset button is located in the top position. Click it once to re-start your firmware. Click twice to enter bootloader mode.
  • Page 15 © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 15 of 96...
  • Page 16 Prep the MatrixPortal Power Prep The MatrixPortal supplies power to the matrix display panel via two standoffs. These come with protective tape applied (part of our manufacturing process) which MUST BE REMOVED! Use some tweezers or a fingernail to remove the two amber circles.

  • Page 17: Power Terminals

    Power Terminals Next, screw in the spade connectors to the corresponding standoff. red wire goes to +5V black wire goes to GND Panel Power Plug either one of the four-conductor power plugs into the power connector pins on the panel. The plug can only go in one way, and that way is marked on the board's silkscreen.
  • Page 18 © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 18 of 96...

  • Page 19: Board Connection

    Board Connection Now, plug the board into the left side shrouded 8x2 connector as shown. The orientation matters, so take a moment to confirm that the white indicator arrow on the matrix panel is oriented pointing up and right as seen here and the MatrixPortal overhangs the edge of the panel when connected.
  • Page 20 For info on adding LED diffusion acrylic, see the page LED Matrix Diffuser. © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 20 of 96...
  • Page 21 LED Matrix Diffuser LED Diffusion Acrylic You can add an LED diffusion acrylic faceplate (https://adafru.it/MEF) to the your LED matrix display. (Pictured here with the ON AIR project (https://adafru.it/MPE)) This can help protect the LEDs as well as enhance the look of the sign both indoors and out by reducing glare and specular highlights of the plastic matrix grid.
  • Page 22 © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 22 of 96...
  • Page 23 Peel away the paper backing from both sides and set the acrylic onto your matrix display. © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 23 of 96...
  • Page 24 Uglu Dashes The best method we've found for adhering acrylic to the matrix display is to use Uglu Dashes clear adhesive rectangles from Pro Tapes (https://adafru.it/NcP). They are incredibly strong (although can be removed if necessary), easy to apply, and are invisible once attached. Use one at each corner and one each at the halfway point of the long edges, then press the acrylic and matrix panel together for about 20 seconds.
  • Page 25 Stand A very simple and attractive way to display your matrix is with the adjustable bent-wire stand (https://adafru.it/MPF). © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 25 of 96...
  • Page 26 Alternately, you can use a frame, 3D printed brackets (https://adafru.it/MZf), tape, glue, or even large binder clips to secure the acrylic to the sign and then mount it on on a wall, shelf, or display cabinet. These mini-magnet feet (https://adafru.it/MZA) can be used to stick the sign to a ferrous surface.
  • Page 27 © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 27 of 96...

  • Page 28: Further Information

    Click the link above and download the latest UF2 file. Download and save it to your desktop (or wherever is handy). Plug your MatrixPortal M4 into your computer using a known-good USB cable. A lot of people end up using charge-only USB cables and it is very frustrating! So make sure you have a USB cable you know is good for data sync.
  • Page 29 You will see a new disk drive appear called MATRIXBOOT. Drag the adafruit_circuitpython_etc.uf2 file to MATRIXBOOT. The LED will flash. Then, the MATRIXBOOT drive will disappear and a new disk drive called CIRCUITPY will appear. That's it, you're done! :) ©...
  • Page 30 What is CircuitPython? CircuitPython is a programming language designed to simplify experimenting and learning to program on low-cost microcontroller boards. It makes getting started easier than ever with no upfront desktop downloads needed. Once you get your board set up, open any text editor, and get started editing code. It's that simple.
  • Page 31 microcontroller chip that's essentially an itty-bitty all-in-one computer. The board you're holding is a microcontroller board! CircuitPython is easy to use because all you need is that little board, a USB cable, and a computer with a USB connection. But that's only the beginning. Other reasons to use CircuitPython include: You want to get up and running quickly.
  • Page 32 CircuitPython Setup To use all the amazing features of your MatrixPortal M4 with CircuitPython, you must first install a number of libraries. This page covers that process. Adafruit CircuitPython Bundle Download the Adafruit CircuitPython Library Bundle. You can find the latest release here: https://adafru.it/ENC...
  • Page 33 Internet Connect! Once you have CircuitPython setup and libraries installed we can get your board connected to the Internet. Note that access to enterprise level secured WiFi networks is not currently supported, only WiFi networks that require SSID and password. To get connected, you will need to start by creating a secrets file .
  • Page 34 OK now you have your secrets setup - you can connect to the Internet. Lets use the ESP32SPI and the Requests libraries - you'll need to visit the CircuitPython bundle and install (https://adafru.it/ENC): adafruit_bus_device adafruit_esp32spi adafruit_requests neopixel Into your folder. Once that's done, load up the following example using Mu or your favorite editor: # SPDX-FileCopyrightText: 2019 ladyada for Adafruit Industries # SPDX-License-Identifier: MIT import board...
  • Page 35 spi = busio.SPI(board.SCK, board.MOSI, board.MISO) esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset) requests.set_socket(socket, esp) if esp.status == adafruit_esp32spi.WL_IDLE_STATUS: print("ESP32 found and in idle mode") print("Firmware vers.", esp.firmware_version) print("MAC addr:", [hex(i) for i in esp.MAC_address]) for ap in esp.scan_networks(): print("\t%s\t\tRSSI: %d" % (str(ap["ssid"], "utf-8"), ap["rssi"])) print("Connecting to AP...") while not esp.is_connected: try:...
  • Page 36 In order, the example code... Initializes the ESP32 over SPI using the SPI port and 3 control pins: esp32_cs = DigitalInOut(board.ESP_CS) esp32_ready = DigitalInOut(board.ESP_BUSY) esp32_reset = DigitalInOut(board.ESP_RESET) spi = busio.SPI(board.SCK, board.MOSI, board.MISO) esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset) Tells our library the type of socket we're using (socket type varies by connectivity type - we'll be requests using the...
  • Page 37 if esp.status == adafruit_esp32spi.WL_IDLE_STATUS: print("ESP32 found and in idle mode") print("Firmware vers.", esp.firmware_version) print("MAC addr:", [hex(i) for i in esp.MAC_address]) Performs a scan of all access points it can see and prints out the name and signal strength: for ap in esp.scan_networks(): print("\t%s\t\tRSSI: %d"...
  • Page 38 JSON_URL = "http://api.coindesk.com/v1/bpi/currentprice/USD.json" print("Fetching json from", JSON_URL) r = requests.get(JSON_URL) print('-'*40) print(r.json()) print('-'*40) r.close() Requests We've written a requests-like (https://adafru.it/Kpa) library for web interfacing named Adafruit_CircuitPython_Requests (https://adafru.it/FpW). This library allows you to send HTTP/1.1 requests without "crafting" them and provides helpful methods for parsing the response from the server. # SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries # SPDX-License-Identifier: MIT # adafruit_requests usage with an esp32spi_socket...
  • Page 39 esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset) print("Connecting to AP...") while not esp.is_connected: try: esp.connect_AP(secrets["ssid"], secrets["password"]) except RuntimeError as e: print("could not connect to AP, retrying: ", e) continue print("Connected to", str(esp.ssid, "utf-8"), "\tRSSI:", esp.rssi) # Initialize a requests object with a socket and esp32spi interface socket.set_interface(esp) requests.set_socket(socket, esp) TEXT_URL = "http://wifitest.adafruit.com/testwifi/index.html"...
  • Page 40 The code first sets up the ESP32SPI interface. Then, it initializes a object using an ESP32 request socket and the object. import board import busio from digitalio import DigitalInOut import adafruit_esp32spi.adafruit_esp32spi_socket as socket from adafruit_esp32spi import adafruit_esp32spi import adafruit_requests as requests # If you are using a board with pre-defined ESP32 Pins: esp32_cs = DigitalInOut(board.ESP_CS) esp32_ready = DigitalInOut(board.ESP_BUSY)
  • Page 41 print("Fetching text from %s"%TEXT_URL) response = requests.get(TEXT_URL) print('-'*40) print("Text Response: ", response.text) print('-'*40) response.close() While some servers respond with text, some respond with json-formatted data consisting of attribute– value pairs. CircuitPython_Requests can convert a JSON-formatted response from a server into a CPython dict.
  • Page 42 json_data = {"Date" : "July 25, 2019"} print("POSTing data to {0}: {1}".format(JSON_POST_URL, json_data)) response = requests.post(JSON_POST_URL, json=json_data) print('-'*40) json_resp = response.json() # Parse out the 'json' key from json_resp dict. print("JSON Data received from server:", json_resp['json']) print('-'*40) response.close() Advanced Requests Usage Want to send custom HTTP headers, parse the response as raw bytes, or handle a response's http status code in your CircuitPython code? We've written an example to show advanced usage of the requests module below.

  • Page 43: Wifi Manager

    print("Connecting to AP...") while not esp.is_connected: try: esp.connect_AP(secrets["ssid"], secrets["password"]) except RuntimeError as e: print("could not connect to AP, retrying: ", e) continue print("Connected to", str(esp.ssid, "utf-8"), "\tRSSI:", esp.rssi) # Initialize a requests object with a socket and esp32spi interface socket.set_interface(esp) requests.set_socket(socket, esp) JSON_GET_URL = "http://httpbin.org/get"...
  • Page 44 from adafruit_esp32spi import adafruit_esp32spi from adafruit_esp32spi import adafruit_esp32spi_wifimanager print("ESP32 SPI webclient test") # Get wifi details and more from a secrets.py file try: from secrets import secrets except ImportError: print("WiFi secrets are kept in secrets.py, please add them there!") raise # If you are using a board with pre-defined ESP32 Pins: esp32_cs = DigitalInOut(board.ESP_CS) esp32_ready = DigitalInOut(board.ESP_BUSY)
  • Page 45 response.close() counter = counter + 1 print("OK") except (ValueError, RuntimeError) as e: print("Failed to get data, retrying\n", e) wifi.reset() continue response = None time.sleep(15) You'll note here we use a secrets.py file to manage our SSID info. The wifimanager is given the ESP32 object, secrets and a neopixel for status indication.
  • Page 46 © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 46 of 96...
  • Page 47 MatrixPortal Library Overview The MatrixPortal library was inspired by the PyPortal library, but a slightly different approach was taken. Rather than having everything in a single module, it was divided into layers. The reason for having different layers is you can use lower layers if you want more control and better memory usage. The main library now piggyback's on top of the base library.
  • Page 48 The matrix module is responsible for detecting and initializing the matrix through the CircuitPython rgbmatrix and framebufferio modules. It currently supports the MatrixPortal M4 and Metro M4 with RGB Matrix Shield. If you just wanted to initialize the matrix, you could use this module. If you would like to go...
  • Page 49 Library Demos The MatrixPortal library has been used in a number of projects. Here are a few of them with guides available. RGB Matrix Automatic YouTube ON AIR Sign (https://adafru.it/MPE) Network Connected RGB Matrix Clock (https://adafru.it/NA-) Bitcoin Value RGB Matrix Display (https://adafru.it/NB0) Weather Display Matrix (https://adafru.it/NB1)
  • Page 50 CircuitPython Pins and Modules CircuitPython is designed to run on microcontrollers and allows you to interface with all kinds of sensors, inputs and other hardware peripherals. There are tons of guides showing how to wire up a circuit, and use CircuitPython to, for example, read data from a sensor, or detect a button press.
  • Page 51 You can use the pin names on the physical board, regardless of whether they seem to be specific to a certain protocol. For example, you do not have to use the SDA pin for I2C - you can use it for a button or LED. On the flip side, there may be multiple names for one pin.
  • Page 52 Then, you pass the I2C object to a driver for the hardware you're using. For example, if you were using the TSL2591 light sensor and its CircuitPython library, the next line of code would be: tsl2591 = adafruit_tsl2591.TSL2591(i2c) However, CircuitPython makes this simpler by including the singleton in the module.
  • Page 53 """CircuitPython Essentials Pin Map Script""" import microcontroller import board board_pins = [] for pin in dir(microcontroller.pin): if isinstance(getattr(microcontroller.pin, pin), microcontroller.Pin): pins = [] for alias in dir(board): if getattr(board, alias) is getattr(microcontroller.pin, pin): pins.append("board.{}".format(alias)) if len(pins) > 0: board_pins.append(" ".join(pins)) for pins in sorted(board_pins): print(pins) Here is the result when this script is run on QT Py:...
  • Page 54 look at the datasheet for your microcontroller, you'll likely find a pinout with a series of pin names, such as "PA18" or "GPIO5". If you want to get to the actual microcontroller pin name in CircuitPython, you'll need module. As with , you can run in the REPL to receive a microcontroller.pin...
  • Page 55 MatrixPortal Library Docs MatrixPortal Library Docs (https://adafru.it/Oa5) © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 55 of 96...
  • Page 56 CircuitPython RGB Matrix Library CircuitPython RGB Matrix Library (https://adafru.it/L7b) © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 56 of 96...
  • Page 57 CircuitPython BLE CircuitPython BLE UART Example It's easy to use Adafruit AirLift ESP32 co-processor boards for Bluetooth Low Energy (BLE) with CircuitPython. When you reset the ESP32, you can put it in WiFi mode (the default), or in BLE mode; you cannot use both modes simultaenously.
  • Page 58 Make sure you are running the latest version of Adafruit CircuitPython (https://adafru.it/Amd) for your board; you'll need 6.0.0 or later. Next you'll need to install the necessary libraries to use the hardware and BLE. Carefully follow the steps to find and install these libraries from Adafruit's CircuitPython library bundle (https://adafru.it/uap).
  • Page 59 # esp32 = ESP32(tx=board.TX, rx=board.RX) # If you are using an AirLift FeatherWing or AirLift Bitsy Add-On, # use the pin settings below. Comment out the DEFAULT line above # and uncomment the lines below. # If you are using an AirLift Breakout, check that these # choices match the wiring to your microcontroller board, # or change them as appropriate.
  • Page 60 You'll then see a list of Bluefruit Connect functions ("modules"). Choose the UART module (2): © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 60 of 96...
  • Page 61 On the UART module page, you can type a string and press Send (3). You'll see that string entered, and then see it echoed back (echoing is in gray). © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 61 of 96...
  • Page 62 © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 62 of 96...
  • Page 63 Arduino IDE Setup The first thing you will need to do is to download the latest release of the Arduino IDE. You will need to be using version 1.8 or higher for this guide https://adafru.it/f1P https://adafru.it/f1P After you have downloaded and installed the latest version of Arduino IDE , you will need to start the IDE and navigate to the Preferences menu.
  • Page 64 We will be adding a URL to the new Additional Boards Manager URLs option. The list of URLs is comma separated, and you will only have to add each URL once. New Adafruit boards and updates to existing boards will automatically be picked up by the Board Manager each time it is opened. The URLs point to index files that the Board Manager uses to build the list of available &...
  • Page 65 Here's a short description of each of the Adafruit supplied packages that will be available in the Board Manager when you add the URL: Adafruit AVR Boards - Includes support for Flora, Gemma, Feather 32u4, ItsyBitsy 32u4, Trinket, & Trinket Pro. Adafruit SAMD Boards - Includes support for Feather M0 and M4, Metro M0 and M4, ItsyBitsy M0 and M4, Circuit Playground Express, Gemma M0 and Trinket M0 Arduino Leonardo &...
  • Page 66 Using with Arduino IDE The Feather/Metro/Gemma/QTPy/Trinket M0 and M4 use an ATSAMD21 or ATSAMD51 chip, and you can pretty easily get it working with the Arduino IDE. Most libraries (including the popular ones like NeoPixels and display) will work with the M0 and M4, especially devices & sensors that use I2C or SPI. Now that you have added the appropriate URLs to the Arduino IDE preferences in the previous page, you can open the Boards Manager by navigating to the Tools->Board menu.
  • Page 67 Install Adafruit SAMD Next you can install the Adafruit SAMD package to add the board file definitions Make sure you have Type All selected to the left of the Filter your search... box You can type Adafruit SAMD in the top search bar, then when you see the entry, click Install Even though in theory you don't need to - I recommend rebooting the IDE Quit and reopen the Arduino IDE to ensure that all of the boards are properly installed.
  • Page 68 Metro M4 Airlift Lite PyGamer M4 Express MONSTER M4SK Hallowing M4 MatrixPortal M4 BLM Badge Install Drivers (Windows 7 & 8 Only) When you plug in the board, you'll need to possibly install a driver Click below to download our Driver Installer https://adafru.it/EC0...
  • Page 69 Download and run the installer Run the installer! Since we bundle the SiLabs and FTDI drivers as well, you'll need to click through the license Select which drivers you want to install, the defaults will set you up with just about every Adafruit board! Click Install to do the installin' ©...
  • Page 70 Blink Now you can upload your first blink sketch! Plug in the M0 or M4 board, and wait for it to be recognized by the OS (just takes a few seconds). It will create a serial/COM port, you can now select it from the drop-down, it'll even be 'indicated' as Trinket/Gemma/Metro/Feather/ItsyBitsy/Trellis! Please note, the QT Py and Trellis M4 Express are two of our very few boards that does not have an onboard pin 13 LED so you can follow this section to practice uploading but you wont see an LED blink!
  • Page 71 // the setup function runs once when you press reset or power the board void setup() { // initialize digital pin 13 as an output. pinMode(13, OUTPUT); // the loop function runs over and over again forever void loop() { digitalWrite(13, HIGH);...
  • Page 72 Compilation Issues If you get an alert that looks like Cannot run program "{runtime.tools.arm-none-eabi-gcc.path}\bin\arm-non-eabi-g++" Make sure you have installed the Arduino SAMD boards package, you need both Arduino & Adafruit SAMD board packages Manually bootloading If you ever get in a 'weird' spot with the bootloader, or you have uploaded code that crashes and doesn't auto-reboot into the bootloader, click the RST button twice (like a double-click)to get back into the bootloader.
  • Page 73 Ubuntu & Linux Issue Fix Follow the steps for installing Adafruit's udev rules on this page. (https://adafru.it/iOE) © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 73 of 96...
  • Page 74 Arduino Libraries OK now that you have Arduino IDE set up, drivers installed if necessary and you've practiced uploading code, you can start installing all the Libraries we'll be using to program it. There's a lot of libraries! Install Libraries Open up the library manager...
  • Page 75 Adafruit Protomatter This library is used for writing to the RGB Matrix. Adafruit LIS3DH This will let you use the onboard accelerometer Adafruit GFX This is the graphics library used to draw to the screen If using an older (pre-1.8.10) Arduino IDE, locate and install Adafruit_BusIO (newer versions do this automatically when installing Adafruit_GFX).
  • Page 76 Adafruit ImageReader For reading bitmaps from SD and displaying Adafruit PixelDust To compile and run the PixelDust demo, you will need this library. This library calculates where the particles should be. © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 76 of 96...
  • Page 77 Using the Protomatter Library Let’s look at a minimal Arduino example for the Adafruit_Protomatter library to illustrate how this works (this is pared down from the “simple” example sketch): #include <Adafruit_Protomatter.h> uint8_t rgbPins[] = {7, 8, 9, 10, 11, 12}; uint8_t addrPins[] = {17, 18, 19, 20};...
  • Page 78 PORT. Should still aim for in a single byte or word though! rgbPins[] With those constraints in mind, here’s what the code looks like for an Adafruit MatrixPortal M4 with a 64x32 pixel matrix: uint8_t rgbPins[] = {7, 8, 9, 10, 11, 12};...
  • Page 79 , we call the constructor. The Arduino library can only drive one Next, still in the global area above setup() matrix at a time (or one chain of matrices, where “out” from one is linked to “in” of the next), so we just have one instance of an object here, which we’ll call Adafruit_Protomatter...
  • Page 80 already implicit in the first argument — if you had two 64x32 matrices side-by-side, you’d pass 128 there. But if you had four such matrices arranged 2x2, you’d still pass 128 for the first argument, but then add either 2 here (if cabling is in a “progressive” order) or -2 (if a “serpentine” order, where the second row of panels is rotated 180°...
  • Page 81 “doublebuffer_scrolltext” examples and tweaking these for their needs. Any color argument passed to a drawing function here is a 16-bit value, with the highest 5 bits representing red brightness (0 to 31), middle 6 bits for green (0 to 63), and least 5 bits for blue (0 to 31). It’s just how Adafruit_GFX works and is a carryover from early PC graphics and most small LCD/OLED displays.
  • Page 82 The matrix refresh rate is influenced by so many factors…processor speed, matrix chain length, bit depth… that it’s difficult to accurately predict ahead of time, so this is a way to see what you get when changing different values in the constructor. This is a subjective thing, but in broad terms 200 Hz or better should provide a solid image…any less and it starts to become flickery, so you might want a lower bit depth in that case.
  • Page 83 = {17, 18, 19, 20}; #endif // Remaining pins are the same for all matrix sizes. These values // are for MatrixPortal M4. See "simple" example for other boards. uint8_t rgbPins[] = {7, 8, 9, 10, 11, 12};...
  • Page 84 void err(int x) { uint8_t i; pinMode(LED_BUILTIN, OUTPUT); // Using onboard LED for(i=1;;i++) { // Loop forever... digitalWrite(LED_BUILTIN, i & 1); // LED on/off blink to alert user delay(x); void setup(void) { Serial.begin(115200); //while (!Serial) delay(10); ProtomatterStatus status = matrix.begin(); Serial.printf("Protomatter begin() status: %d\n", status);...
  • Page 85 64 // Matrix height (pixels) - SET TO 64 FOR 64x64 MATRIX! Now upload the sketch to your MatrixPortal M4. You may need to press the Reset button to reset the MatrixPortal. You should see a a series of colored rectangles along the bottom. Go ahead and start moving the matrix around! ©...
  • Page 86 If you have a 3D Printer, be sure to check out the Matrix Portal Sand Handles (https://adafru.it/NDg) guide. © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 86 of 96...
  • Page 87 Protomatter Library Protomatter Library (https://adafru.it/MNa) © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 87 of 96...
  • Page 88 Using the Accelerometer On the back of the MatrixPortal is a triple-axis accelerometer that you can use to detect motion. (That's how our cool digital sand demo works!) You can use this sensor in both CircuitPython and Arduino. After the library support is installed, you can then use the example code provided to get X, Y and Z acceleration values.
  • Page 89 This will change the library to use the alternate address 0x19 of the accelerometer instead of the default 0x18! // Basic demo for accelerometer readings from Adafruit LIS3DH #include <Wire.h> #include <SPI.h> #include <Adafruit_LIS3DH.h> #include <Adafruit_Sensor.h> // Used for software SPI #define LIS3DH_CLK 13 #define LIS3DH_MISO 12 #define LIS3DH_MOSI 11...
  • Page 90 void loop() { lis.read(); // get X Y and Z data at once // Then print out the raw data Serial.print("X: "); Serial.print(lis.x); Serial.print(" \tY: "); Serial.print(lis.y); Serial.print(" \tZ: "); Serial.print(lis.z); /* Or..get a new sensor event, normalized */ sensors_event_t event; lis.getEvent(&event);...
  • Page 91 # SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries # SPDX-License-Identifier: MIT import time import board import busio import adafruit_lis3dh # Hardware I2C setup. Use the CircuitPlayground built-in accelerometer if available; # otherwise check I2C pins. if hasattr(board, "ACCELEROMETER_SCL"): i2c = busio.I2C(board.ACCELEROMETER_SCL, board.ACCELEROMETER_SDA) lis3dh = adafruit_lis3dh.LIS3DH_I2C(i2c, address=0x19) else: i2c = board.I2C()
  • Page 92 # Hardware I2C setup. Use the CircuitPlayground built-in accelerometer if available; # otherwise check I2C pins. if hasattr(board, "ACCELEROMETER_SCL"): i2c = busio.I2C(board.ACCELEROMETER_SCL, board.ACCELEROMETER_SDA) int1 = digitalio.DigitalInOut(board.ACCELEROMETER_INTERRUPT) lis3dh = adafruit_lis3dh.LIS3DH_I2C(i2c, address=0x19, int1=int1) else: i2c = busio.I2C(board.SCL, board.SDA) int1 = digitalio.DigitalInOut(board.D6) # Set to correct pin for interrupt! lis3dh = adafruit_lis3dh.LIS3DH_I2C(i2c, int1=int1) And 'uncomment' these lines: # PyGamer OR MatrixPortal I2C Setup:...
  • Page 93 Updating ESP32 Firmware There may come a time when you want to update the firmware on the ESP32 itself. This isn't something we expect you'll do often if at all, but its good to know how if you need to. We have a guide here which details the process of updating the ESP32 firmware on Airlift All-in-One boards (including the PyPortal, MatrixPortal, and Metro M4 AirLift) here...
  • Page 94 Downloads Files ATSAMD51J19 datasheet (https://adafru.it/NBJ) EagleCAD PCB files on GitHub (https://adafru.it/NBK) Fritzing object in Adafruit Fritzing Library (https://adafru.it/E9e) https://adafru.it/ScN https://adafru.it/ScN Schematic Fab Print © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 94 of 96...
  • Page 95 © Adafruit Industries https://learn.adafruit.com/adafruit-matrixportal-m4 Page 95 of 96...
  • Page 96 © Adafruit Industries Last Updated: 2021-08-09 02:02:06 PM EDT Page 96 of 96...