# IoT Twitter Listener Party Parrot ## Overview https://youtu.be/p2iboSAZfqM Create an IoT party parrot sprite animation that alerts you about new tweets that folks send you with the hashtag #partyparrot. ![](https://cdn-learn.adafruit.com/assets/assets/000/095/326/medium800/led_matrices_000020.png?1601927545) This project uses the Twitter API v2 to query tweets. You can fetch these tweets with the **adafruit\_matrixportal** library and a MatrixPortal M4 plugged directly into your 32x32 RGB LED Matrix. The MatrixPortal M4 has a USB C port for power and data, which keeps the number of wires low. This makes for a nice and compact IoT project for your desk so that you never miss a virtual party. **#partyparrot!** ![](https://cdn-learn.adafruit.com/assets/assets/000/095/325/medium800/led_matrices_P1220834_edited.jpg?1601927497) ## Parts List ### 32x32 RGB LED Matrix Panel - 5mm Pitch [32x32 RGB LED Matrix Panel - 5mm Pitch](https://www.adafruit.com/product/2026) Bring a little bit of Times Square into your home with this sweet 32 x 32 square RGB LED matrix panel. These panels are normally used to make video walls, here in New York we see them on the sides of busses and bus stops, to display animations or short video clips. We thought they looked... In Stock [Buy Now](https://www.adafruit.com/product/2026) [Related Guides to the Product](https://learn.adafruit.com/products/2026/guides) ![Video of assembled and powered on 32x32 RGB LED Matrix Panel - 5mm pitch. The matrix displays swirling, psychedelic rainbow colors.](https://cdn-shop.adafruit.com/product-videos/640x480/2026-04.jpg) ### Adafruit Matrix Portal - CircuitPython Powered Internet Display [Adafruit Matrix Portal - CircuitPython Powered Internet Display](https://www.adafruit.com/product/4745) Folks love our [wide selection of RGB matrices](https://www.adafruit.com/category/327) and accessories, for making custom colorful LED displays... and our RGB Matrix Shields and FeatherWings can be quickly soldered together to make the wiring much easier. But what if we made it... In Stock [Buy Now](https://www.adafruit.com/product/4745) [Related Guides to the Product](https://learn.adafruit.com/products/4745/guides) ![Video of a person rotating an LED matrix panel with animation resembling falling colored sand.](https://cdn-shop.adafruit.com/product-videos/640x480/4745-05.jpg) ### Black LED Diffusion Acrylic Panel 12" x 12" - 0.1" / 2.6mm thick [Black LED Diffusion Acrylic Panel 12" x 12" - 0.1" / 2.6mm thick](https://www.adafruit.com/product/4594) A nice whoppin' slab of some lovely black acrylic to add some extra diffusion to your LED Matrix project. This material is 2.6mm (0.1") thick and is made of special cast acrylic that makes it perfect for glowy projects, especially matricies or NeoPixels. Unlike smoke or... In Stock [Buy Now](https://www.adafruit.com/product/4594) [Related Guides to the Product](https://learn.adafruit.com/products/4594/guides) ![LED RGB matrix 12" x 12" with "Adafruit Industries LED Matrix" text showing, and LED acrylic slowly covering to make it nicely diffused](https://cdn-shop.adafruit.com/product-videos/640x480/4594-04.jpg) ### USB Type A to Type C Cable - approx 1 meter / 3 ft long [USB Type A to Type C Cable - approx 1 meter / 3 ft long](https://www.adafruit.com/product/4474) As technology changes and adapts, so does Adafruit. This   **USB Type A to Type C** cable will help you with the transition to USB C, even if you're still totin' around a USB Type A hub, computer or laptop. USB C is the latest industry-standard connector for... In Stock [Buy Now](https://www.adafruit.com/product/4474) [Related Guides to the Product](https://learn.adafruit.com/products/4474/guides) ![Angled shot of a coiled black, USB-C to USB-A cable.](https://cdn-shop.adafruit.com/640x480/4474-02.jpg) ### USB C to USB C Cable - USB 3.1 Gen 4 with E-Mark - 1 meter long [USB C to USB C Cable - USB 3.1 Gen 4 with E-Mark - 1 meter long](https://www.adafruit.com/product/4199) As technology changes and adapts, so does Adafruit! Rather than the regular USB A, this cable has  **USB C to USB C**  plugs! USB C is the latest industry-standard connector for transmitting data _and_ power. Like Lightning and MagSafe cables, USB C... In Stock [Buy Now](https://www.adafruit.com/product/4199) [Related Guides to the Product](https://learn.adafruit.com/products/4199/guides) ![USB C to USB C cable. USB 3.1 gen 4 with E-Mark. 1 meter long](https://cdn-shop.adafruit.com/640x480/4199-01.jpg) # IoT Twitter Listener Party Parrot ## Install CircuitPython [CircuitPython](https://github.com/adafruit/circuitpython) is a derivative of [MicroPython](https://micropython.org) designed to simplify experimentation and education on low-cost microcontrollers. It makes it easier than ever to get prototyping by requiring no upfront desktop software downloads. Simply copy and edit files on the **CIRCUITPY** drive to iterate. ## Set up CircuitPython Quick Start! Follow this quick step-by-step for super-fast Python power :) [Download the latest version of CircuitPython for this board via circuitpython.org](https://circuitpython.org/board/matrixportal_m4/) ## Further Information For more detailed info on installing CircuitPython, check out [Installing CircuitPython](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython). **Click the link above and download the latest UF2 file.** Download and save it to your desktop (or wherever is handy). ![led_matrices_Save_to_Desktop.png](https://cdn-learn.adafruit.com/assets/assets/000/095/075/medium640/led_matrices_Save_to_Desktop.png?1601050695) 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.** Double-click the **Reset** button (indicated by the green arrow) on your board, and you will see the NeoPixel RGB LED (indicated by the magenta arrow) turn green. If it turns red, check the USB cable, try another USB port, etc. If double-clicking doesn't work the first time, try again. Sometimes it can take a few tries to get the rhythm right! ![led_matrices_matrixportal_install_cp.jpg](https://cdn-learn.adafruit.com/assets/assets/000/125/447/medium640/led_matrices_matrixportal_install_cp.jpg?1697644568) You will see a new disk drive appear called **MATRIXBOOT**.   Drag the **adafruit\_circuitpython\_etc.uf2** file to **MATRIXBOOT****.** ![led_matrices_MATRIXBOOT.png](https://cdn-learn.adafruit.com/assets/assets/000/125/448/medium640/led_matrices_MATRIXBOOT.png?1697644692) ![led_matrices_Drag_to_Drive.png](https://cdn-learn.adafruit.com/assets/assets/000/125/449/medium640/led_matrices_Drag_to_Drive.png?1697644703) 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! :) ![led_matrices_circuitpy.png](https://cdn-learn.adafruit.com/assets/assets/000/125/450/medium640/led_matrices_circuitpy.png?1697645066) # IoT Twitter Listener Party Parrot ## 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: [Download latest Library Bundle](https://circuitpython.org/libraries) Download the **adafruit-circuitpython-bundle-version-mpy-\*.zip** bundle zip file, and unzip a folder of the same name. Inside you'll find a **lib** folder. The entire collection of libraries is too large to fit on the **CIRCUITPY** drive. Instead, add each library as you need it, this will reduce the space usage but you'll need to put in a little more effort. At a minimum we recommend the following libraries, in fact we more than recommend. They're basically required. So grab them and install them into **CIRCUITPY/lib** now! - **adafruit\_matrixportal** - this library is the main library used with the MatrixPortal. - **adafruit\_debouncer.mpy** - this library is used for debouncing a digital input pin - **adafruit\_portalbase**  - This is the base library that adafruit\_matrixportal is built on top of. - **adafruit\_esp32spi** - this is the library that gives you internet access via the ESP32 using (you guessed it!) SPI transport. You need this for anything Internet - **neopixel.mpy** - for controlling the onboard neopixel - **adafruit\_bus\_device** - low level support for I2C/SPI - **adafruit\_requests.mpy** - this library allows us to perform HTTP requests and get responses back from servers. GET/POST/PUT/PATCH - they're all in here! - **adafruit\_fakerequests.mpy **  - This library allows you to create fake HTTP requests by using local files. - **adafruit\_io** - this library helps connect the PyPortal to our free data logging and viewing service - **adafruit\_bitmap\_font** - we have fancy font support, and it's easy to make new fonts. This library reads and parses font files. - **adafruit\_display\_text** - not surprisingly, it displays text on the screen - **adafruit\_lis3dh.mpy** - this library is used for the onboard accelerometer to detect the orientation of the MatrixPortal - **adafruit\_minimqtt** - this is used for communicating with MQTT servers. # IoT Twitter Listener Party Parrot ## Coding the IoT Party Parrot To use with CircuitPython, you need to first install a few libraries, into the lib folder on your **CIRCUITPY** drive. Then you need to update **code.py** with the example script. Thankfully, we can do this in one go. In the example below, click the **Download Project Bundle** button below to download the necessary libraries and the **code.py** file in a zip file. Extract the contents of the zip file, open the directory **IoT\_Party\_Parrot/** and then click on the directory that matches the version of CircuitPython you're using and copy the contents of that directory to your **CIRCUITPY** drive. Your **CIRCUITPY** drive should now look similar to the following image: ![CIRCUITPY](https://adafruit.github.io/Adafruit_Learning_System_Guides/IoT_Party_Parrot.png ) https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/IoT_Party_Parrot/code.py # IoT Twitter Listener Party Parrot ## Animating Sprites with CircuitPython You can create animations with the **displayio** library using sprite sheets. Sprite sheets can be thought of as an array of images. They can be iterated through just like an array of variables, strings or integers in code.  If the sprite sheet is set up with images that are sequential, then it will appear as an animation when they're played. You can do this by splitting out of the layers of a .GIF or creating your own artwork. ![led_matrices_partyParrotsMatrix.bmp](https://cdn-learn.adafruit.com/assets/assets/000/095/300/medium640/led_matrices_partyParrotsMatrix.bmp?1601900165) To begin animating your sprites, you'll setup your matrix and display objects as usual with the **displayio** and **adafruit\_matrixportal** libraries.  The bitmap sprite sheet is brought into the code with the **adafruit\_imageload** library. This bitmap is sliced into a `TileGrid`, which will be how the images will be iterated through to create an animation. ```python matrix = Matrix(width=32, height=32) display = matrix.display group = displayio.Group() parrot_bit, parrot_pal = adafruit_imageload.load("/partyParrotsTweet.bmp", bitmap=displayio.Bitmap, palette=displayio.Palette) parrot_grid = displayio.TileGrid(parrot_bit, pixel_shader=parrot_pal, width=1, height=1, tile_height=32, tile_width=32, default_tile=10, x=0, y=0) group.append(parrot_grid) display.root_group = group ``` Two variables are needed to animate a sprite: one to track the index of the `TileGrid` and one to track the time. `p` will be used as the `TileGrid` index and `party` will be used to track time with `time.monotonic()`. In the loop, every `0.1` seconds, the `TileGrid`'s index advances by `1`. You can increase or decrease the timing to adjust the speed for your animation. When `p` reaches the end of the `TileGrid` array, it is reset to `0` so that the animation can loop. ```python party = 0 p = 0 while True: if (party + 0.1) < time.monotonic(): parrot_grid[0] = p p += 1 party = time.monotonic() if p > 9: p = 0 ``` And that's it! With just a few lines of code, you can get a looping animation running (or partying) on your matrix display. # IoT Twitter Listener Party Parrot ## Setting up the Twitter API and settings.toml You can access Twitter data for your projects using the Twitter API. To begin, you'll need to apply for a developer account with your Twitter account at [https://developer.twitter.com/en/apply-for-access](https://developer.twitter.com/en/apply-for-access) Once you click apply, you'll be prompted to select your use case. Under Hobbyist, select Exploring the API. ![led_matrices_exploring.png](https://cdn-learn.adafruit.com/assets/assets/000/095/302/medium640/led_matrices_exploring.png?1601905170) After confirming your contact details, you'll be asked to describe how you'll be using the Twitter API. Enter in information as applicable. If you're planning to use the API for other projects beyond this one, you may want to include that information here for the future. ![led_matrices_how.png](https://cdn-learn.adafruit.com/assets/assets/000/095/303/medium640/led_matrices_how.png?1601905276) After confirming your information and agreeing to terms of service, you'll click Submit Application. Applications are usually approved fairly quickly, usually within a few minutes.  ![led_matrices_submit.png](https://cdn-learn.adafruit.com/assets/assets/000/095/304/medium640/led_matrices_submit.png?1601905625) ## Create a Project When you log into the developer portal, you'll see your developer dashboard. Here you can access all of your account information and documentation. In order to pull from the Twitter API, you need to create a Project. At the bottom of the Dashboard page, click on New Project and then complete the information about your Project. ![led_matrices_project.png](https://cdn-learn.adafruit.com/assets/assets/000/095/322/medium640/led_matrices_project.png?1601922495) Each Project has an App, which stores your API keys and access points. Add an App to the Project your just created. Enter your desired name for your App and then click Complete. ![led_matrices_createApp2.png](https://cdn-learn.adafruit.com/assets/assets/000/095/321/medium640/led_matrices_createApp2.png?1601922099) After you've created the Project and App, you can access the Project page which supplies Usage stats and allows access to your App.  If you click on the App Settings button (the cog wheel), you can adjust access settings for the App and access your Authentication tokens. ![led_matrices_dashboardPage.png](https://cdn-learn.adafruit.com/assets/assets/000/095/323/medium640/led_matrices_dashboardPage.png?1601922704) Warning: ## Keep Your Secrets Secret The project's code needs access to your Twitter API Authorization tokens. To keep this information secret, but still accessible, you can enter this information into a file called **settings.toml**. ```python CIRCUITPY_WIFI_SSID="your-wifi-ssid" CIRCUITPY_WIFI_PASSWORD="your-wifi-password" timezone="America/New_York" # http://worldtimeapi.org/timezones twitter_api_key="insert your twitter api key here" twitter_secret_key="insert your twitter secret key here" bearer_token="insert your bearer token here" ``` # IoT Twitter Listener Party Parrot ## Getting and Parsing Tweets You can access tweets with the Twitter API using a few different methods. For this project, the recent search method is used. This involves creating a hyperlink that contains the search parameters to filter the tweets that you're getting. Twitter has documentation on the available parameters that you can use with v2 of the API: [https://developer.twitter.com/en/docs/twitter-api/tweets/search/quick-start](https://developer.twitter.com/en/docs/twitter-api/tweets/search/quick-start) The goal for this project is to see the most recent tweets that contain a hashtag (#partyparrot) that are sent to a specific user. This means that your hyperlink query will look like this: - `'https://api.twitter.com/2/tweets/search/recent?query=#partyparrot to:blitzcitydiy'` Notice that there is a space between the hashtag and `to:` queries. If you want to add more options to your query, they just need to be separated by a space. This URL is going to be used in the CircuitPython code as the data source for the JSON feed. You'll access that feed in order to pull data to trigger your sprite animation. ## Introducing the Twitter API To Your CircuitPython Code After all of the setup comes the fun part: bringing the Twitter API information into the CircuitPython code.  First, `bear` is created as a variable to hold your Bearer token. This is needed to access the API. It's imported from your **secrets.py** file. Then `DATA_SOURCE` is setup to hold your query URL and `DATA_LOCATION` is setup to list your JSON path information, which will be important in the main loop. A `MatrixPortal` object is created using the **adafruit\_matrixportal** library. This allows your MatrixPortal M4 to connect to the internet and then access your query URL to pull down your desired data via the filtered JSON path. ```python bear = secrets['bearer_token'] DATA_SOURCE = ('https://api.twitter.com/2/tweets/search/recent?query=#partyparrot to:blitzcitydiy') DATA_LOCATION = ["meta", "newest_id"] matrixportal = MatrixPortal( url=DATA_SOURCE, json_path=DATA_LOCATION, status_neopixel=board.NEOPIXEL ) ``` The Twitter API requires a Bearer token to authorize access to the query URL. This is sent as a header along with the request made with the **adafruit\_matrixportal** library. You can setup headers using `matrixportal.set_headers()`. After the header is created, a few states are setup for use in the loop. Their functions are commented below. ```python matrixportal.set_headers({'Authorization': 'Bearer ' + bear}) last_value = 0 # checks last tweet's ID check = 0 # time.monotonic() holder parrot = False # state to track if an animation is currently running party = 0 # time.monotonic() holder p = 0 # index for tilegrid party_count = 0 # count for animation cycles ``` In the loop, the code is running `matrixportal.fetch()` to check and see if a new tweet has been sent that matches the query parameters. This data stream is stored as `value` and holds the JSON path information. In this case, it's the most recent tweet's ID number. This ID number is compared to the previous tweet's ID number, which is stored in `last_value`. If they are not a match, then this means that a new tweet with matching parameters has been received and the `parrot` state is updated to `True`. ```python while True: if (check + 30) < time.monotonic(): value = matrixportal.fetch() print("Response is", value) check = time.monotonic() if last_value != value: print("new party!") last_value = value parrot = True else: print("no new party... :(") ``` When `party` is `True`, the party parrot begins animating on the LED matrix. The entire animation cycle is played 16 times and is tracked with `party_count`. After 16 cycles, the animation stops and all of the states are reset to await the next tweet. ```python if parrot: if (party + 0.1) < time.monotonic(): parrot_grid[0] = p p += 1 party = time.monotonic() if p > 9: p = 0 party_count += 1 print("party parrot", party_count) if party_count > 15: parrot = False party_count = 0 p = 0 parrot_grid[0] = 10 print("the party is over") ``` ## Customization You shouldn't feel limited by the parameters of this party project though. You can setup custom queries looking at a wide variety of filters for Twitter, whether it be hashtags, emoji usage, retweets, etc. You can also include any sprite animation that you want. Perhaps you want a different animation for different Twitter notifications. There are definitely many ways that you could customize this project for your own needs. ![](https://cdn-learn.adafruit.com/assets/assets/000/095/361/medium800thumb/led_matrices_00002.jpg?1601992585) ## Featured Products ### Adafruit Matrix Portal - CircuitPython Powered Internet Display [Adafruit Matrix Portal - CircuitPython Powered Internet Display](https://www.adafruit.com/product/4745) Folks love our [wide selection of RGB matrices](https://www.adafruit.com/category/327) and accessories, for making custom colorful LED displays... and our RGB Matrix Shields and FeatherWings can be quickly soldered together to make the wiring much easier. But what if we made it... In Stock [Buy Now](https://www.adafruit.com/product/4745) [Related Guides to the Product](https://learn.adafruit.com/products/4745/guides) ### 32x32 RGB LED Matrix Panel - 4mm Pitch [32x32 RGB LED Matrix Panel - 4mm Pitch](https://www.adafruit.com/product/607) Bring a little bit of Times Square into your home with this totally adorable 5 inch square 32 x 32 RGB LED matrix panel. These panels are normally used to make video walls, here in New York we see them on the sides of busses and bus stops, to display animations or short video clips. We thought... In Stock [Buy Now](https://www.adafruit.com/product/607) [Related Guides to the Product](https://learn.adafruit.com/products/607/guides) ### 32x32 RGB LED Matrix Panel - 5mm Pitch [32x32 RGB LED Matrix Panel - 5mm Pitch](https://www.adafruit.com/product/2026) Bring a little bit of Times Square into your home with this sweet 32 x 32 square RGB LED matrix panel. These panels are normally used to make video walls, here in New York we see them on the sides of busses and bus stops, to display animations or short video clips. We thought they looked... In Stock [Buy Now](https://www.adafruit.com/product/2026) [Related Guides to the Product](https://learn.adafruit.com/products/2026/guides) ### 32x32 RGB LED Matrix Panel - 6mm pitch [32x32 RGB LED Matrix Panel - 6mm pitch](https://www.adafruit.com/product/1484) Bring a little bit of Times Square into your home with this sweet 32 x 32 square RGB LED matrix panel. These panels are normally used to make video walls, here in New York we see them on the sides of busses and bus stops, to display animations or short video clips. We thought they looked... In Stock [Buy Now](https://www.adafruit.com/product/1484) [Related Guides to the Product](https://learn.adafruit.com/products/1484/guides) ### Black LED Diffusion Acrylic Panel 12" x 12" - 0.1" / 2.6mm thick [Black LED Diffusion Acrylic Panel 12" x 12" - 0.1" / 2.6mm thick](https://www.adafruit.com/product/4594) A nice whoppin' slab of some lovely black acrylic to add some extra diffusion to your LED Matrix project. This material is 2.6mm (0.1") thick and is made of special cast acrylic that makes it perfect for glowy projects, especially matricies or NeoPixels. Unlike smoke or... In Stock [Buy Now](https://www.adafruit.com/product/4594) [Related Guides to the Product](https://learn.adafruit.com/products/4594/guides) ### USB C to USB C Cable - USB 3.1 Gen 4 with E-Mark - 1 meter long [USB C to USB C Cable - USB 3.1 Gen 4 with E-Mark - 1 meter long](https://www.adafruit.com/product/4199) As technology changes and adapts, so does Adafruit! Rather than the regular USB A, this cable has  **USB C to USB C**  plugs! USB C is the latest industry-standard connector for transmitting data _and_ power. Like Lightning and MagSafe cables, USB C... In Stock [Buy Now](https://www.adafruit.com/product/4199) [Related Guides to the Product](https://learn.adafruit.com/products/4199/guides) ## Related Guides - [Adafruit MatrixPortal M4](https://learn.adafruit.com/adafruit-matrixportal-m4.md) - [Halloween Countdown Display Matrix](https://learn.adafruit.com/halloween-countdown-display-matrix.md) - [AdaBox 016](https://learn.adafruit.com/adabox016.md) - [Matrix Portal Flow Visualizer](https://learn.adafruit.com/matrix-portal-flow-visualizer.md) - [Adafruit Protomatter RGB Matrix Library](https://learn.adafruit.com/adafruit-protomatter-rgb-matrix-library.md) - [LED Matrix Display for Bitmap Pixel Art and Animation](https://learn.adafruit.com/pixel-art-matrix-display.md) - [Matrix Portal RGB Display Handbag](https://learn.adafruit.com/matrix-portal-rgb-display-handbag.md) - [Matrix Portal New Guide Scroller](https://learn.adafruit.com/matrix-portal-new-guide-scroller.md) - [Ocean Epoxy Resin Lightbox with RGB LED Matrix Image Scroller](https://learn.adafruit.com/ocean-epoxy-resin-lightbox-with-rgb-led-matrix-image-scroller.md) - [Cardboard Window Skull With Animated LED Eyes](https://learn.adafruit.com/cardboard-window-skull-animated-led-eyes.md) - [RGB Matrix Portal Room CO2 Monitor](https://learn.adafruit.com/matrix-portal-room-co2-monitor.md) - [Animated GIF Player for Matrix Portal](https://learn.adafruit.com/animated-gif-player-for-matrix-portal.md) - [Matrix Portal Sand Handles](https://learn.adafruit.com/matrix-portal-sand.md) - [RGB Matrix Dreidel Game](https://learn.adafruit.com/rgb-matrix-dreidel-game.md) - [RGB Matrix Automatic YouTube ON AIR Sign](https://learn.adafruit.com/rgb-matrix-automatic-youtube-on-air-sign.md)