# Weather Display Matrix ## Overview ![](https://cdn-learn.adafruit.com/assets/assets/000/094/552/medium800/weathermx-3658.jpg?1599063056) Always know the current weather without even sticking you head out the window with the Weather Display Matrix. Using CircuitPython, this project queries the Open Weather Maps site API to find out the current weather for your location. It displays the temperature and weather condition icon, while scrolling additional details such as humidity and conditions. Want to change between Imperial and metric units? We've got you covered! Use the Matrix Portal buttons or the added jumper on the Metro M4 Airlift's pin D12 to do so. ## Parts ### Adafruit Metro M4 Express AirLift (WiFi) - Lite [Adafruit Metro M4 Express AirLift (WiFi) - Lite](https://www.adafruit.com/product/4000) Give your next project a lift with _AirLift_ - our witty name for the ESP32 co-processor that graces this Metro M4. You already know about the  **Adafruit Metro M4**  featuring the  **Microchip ATSAMD51** , with it's 120MHz Cortex M4 with... In Stock [Buy Now](https://www.adafruit.com/product/4000) [Related Guides to the Product](https://learn.adafruit.com/products/4000/guides) ![Adafruit Metro M4 Airlift Lite dev board with SAMD51 an ESP32 Wifi Co-processor.](https://cdn-shop.adafruit.com/640x480/4000-08.jpg) or ### 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) ### 64x32 RGB LED Matrix - 4mm pitch [64x32 RGB LED Matrix - 4mm pitch](https://www.adafruit.com/product/2278) Bring a little bit of Times Square into your home with this sweet 64 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/2278) [Related Guides to the Product](https://learn.adafruit.com/products/2278/guides) ![Two white hands hold out an assembled and powered on 64x32 RGB LED Matrix Panel - 4mm pitch. The matrix displays "Adafruit Industries LED MATRIX! 32x64 *RGB*"](https://cdn-shop.adafruit.com/640x480/2278-00.jpg) ### Adafruit RGB Matrix Shield for Arduino [Adafruit RGB Matrix Shield for Arduino](https://www.adafruit.com/product/2601) Our RGB matrices are dazzling, with their hundreds or even _thousands_ of individual RGB LEDs. Compared to NeoPixels, they've got great density, power usage and the price-per-LED can't be beat. But...(isn't there always a _but_?) You need to use our special library to... In Stock [Buy Now](https://www.adafruit.com/product/2601) [Related Guides to the Product](https://learn.adafruit.com/products/2601/guides) ![Adafruit RGB Matrix Shield for Arduino connected to a LED Matrix that reads "Adafruit Industries LED MATIX! 32x64 *RGB*"](https://cdn-shop.adafruit.com/640x480/2601-02.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) ### 5V 2.5A Switching Power Supply with 20AWG MicroUSB Cable [5V 2.5A Switching Power Supply with 20AWG MicroUSB Cable](https://www.adafruit.com/product/1995) Our all-in-one 5V 2.5 Amp + MicroUSB cable power adapter is the perfect choice for powering single-board computers like Raspberry Pi, BeagleBone, or anything else that's power-hungry! This adapter was specifically designed to provide 5.25V, not 5V, but we still call it a 5V USB... In Stock [Buy Now](https://www.adafruit.com/product/1995) [Related Guides to the Product](https://learn.adafruit.com/products/1995/guides) ![MicroUSB power supply with bundled cable and U.S. plugs.](https://cdn-shop.adafruit.com/640x480/1995-02.jpg) ### USB cable - USB A to Micro-B [USB cable - USB A to Micro-B](https://www.adafruit.com/product/592) This here is your standard A to micro-B USB cable, for USB 1.1 or 2.0. Perfect for connecting a PC to your Metro, Feather, Raspberry Pi or other dev-board or microcontroller Approximately 3 feet / 1 meter long Out of Stock [Buy Now](https://www.adafruit.com/product/592) [Related Guides to the Product](https://learn.adafruit.com/products/592/guides) ![USB cable - USB A to Micro-B - 3 foot long](https://cdn-shop.adafruit.com/640x480/592-01.jpg) ### Micro B USB to USB C Adapter [Micro B USB to USB C Adapter](https://www.adafruit.com/product/4299) As technology changes and adapts, so does Adafruit, and speaking of _adapting_, this _ **adapter** _ has a Micro B USB jack and a USB C plug. USB C is the latest industry-standard connector for transmitting data _and_ power.... In Stock [Buy Now](https://www.adafruit.com/product/4299) [Related Guides to the Product](https://learn.adafruit.com/products/4299/guides) ![Angled shot of Micro B USB to USB C Adapter.](https://cdn-shop.adafruit.com/640x480/4299-02.jpg) ## Optional ### 36-pin 0.1" Female header - pack of 5! [36-pin 0.1" Female header - pack of 5!](https://www.adafruit.com/product/598) Female header is like the duct tape of electronics. Its great for connecting things together, soldering to perf-boards, sockets for wires or break-away header, etc. We go through these guys real fast, and thought that given how handy they are, we'd offer them in a pack of five! Out of Stock [Buy Now](https://www.adafruit.com/product/598) [Related Guides to the Product](https://learn.adafruit.com/products/598/guides) ![pack of five, 36-pin 0.1 inch Female header](https://cdn-shop.adafruit.com/640x480/598-04.jpg) ### Solid-Core Wire Spool - 25ft - 22AWG - Red [Solid-Core Wire Spool - 25ft - 22AWG - Red](https://www.adafruit.com/product/288) Perfect for bread-boarding, free wiring, etc. This spool of solid-core wire is easy to solder to. When bent it keeps its shape pretty well. We like to have a few spools of this stuff around. We suggest picking up wire strippers to match. Wire gauge is 22 AWG which we've found is the best... In Stock [Buy Now](https://www.adafruit.com/product/288) [Related Guides to the Product](https://learn.adafruit.com/products/288/guides) ![Small spool of red wire.](https://cdn-shop.adafruit.com/640x480/288-02.jpg) ### Flush diagonal cutters [Flush diagonal cutters](https://www.adafruit.com/product/152) These are the best diagonal cutters, large super-comfortable grip to use and have strong nippers for perfect trimming of wires and leads. I've used my pair every day for years. In Stock [Buy Now](https://www.adafruit.com/product/152) [Related Guides to the Product](https://learn.adafruit.com/products/152/guides) ![Red and black diagonal flush cutters](https://cdn-shop.adafruit.com/640x480/152-02.jpg) # Weather Display Matrix ## Using M4 Airlift If you have a Metro M4 AirLift, you can build this project easily - you just need an RGB Matrix shield to help connect! You will need a Metro M4 Airlift, matrix shield and matrix ### Adafruit Metro M4 Express AirLift (WiFi) - Lite [Adafruit Metro M4 Express AirLift (WiFi) - Lite](https://www.adafruit.com/product/4000) Give your next project a lift with _AirLift_ - our witty name for the ESP32 co-processor that graces this Metro M4. You already know about the  **Adafruit Metro M4**  featuring the  **Microchip ATSAMD51** , with it's 120MHz Cortex M4 with... In Stock [Buy Now](https://www.adafruit.com/product/4000) [Related Guides to the Product](https://learn.adafruit.com/products/4000/guides) ![Adafruit Metro M4 Airlift Lite dev board with SAMD51 an ESP32 Wifi Co-processor.](https://cdn-shop.adafruit.com/640x480/4000-08.jpg) ### Adafruit RGB Matrix Shield for Arduino [Adafruit RGB Matrix Shield for Arduino](https://www.adafruit.com/product/2601) Our RGB matrices are dazzling, with their hundreds or even _thousands_ of individual RGB LEDs. Compared to NeoPixels, they've got great density, power usage and the price-per-LED can't be beat. But...(isn't there always a _but_?) You need to use our special library to... In Stock [Buy Now](https://www.adafruit.com/product/2601) [Related Guides to the Product](https://learn.adafruit.com/products/2601/guides) ![Adafruit RGB Matrix Shield for Arduino connected to a LED Matrix that reads "Adafruit Industries LED MATIX! 32x64 *RGB*"](https://cdn-shop.adafruit.com/640x480/2601-02.jpg) ### 64x32 RGB LED Matrix - 4mm pitch [64x32 RGB LED Matrix - 4mm pitch](https://www.adafruit.com/product/2278) Bring a little bit of Times Square into your home with this sweet 64 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/2278) [Related Guides to the Product](https://learn.adafruit.com/products/2278/guides) ![Two white hands hold out an assembled and powered on 64x32 RGB LED Matrix Panel - 4mm pitch. The matrix displays "Adafruit Industries LED MATRIX! 32x64 *RGB*"](https://cdn-shop.adafruit.com/640x480/2278-00.jpg) # Weather Display Matrix ## 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/metro_m4_airlift_lite/) ## 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). ![adafruit_products_MetroAirLiftCPDownload.png](https://cdn-learn.adafruit.com/assets/assets/000/074/832/medium640/adafruit_products_MetroAirLiftCPDownload.png?1556052786) Plug your Metro 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 next to the USB connector on your board (blue arrow), and you will see the NeoPixel RGB (LED circled in red) turn green. If it turns red, check the USB cable, try another USB port, etc. If double-clicking the Reset button doesn't work the first time, try again. Sometimes it can take a few tries to get the rhythm right! ![adafruit_products_one_one_one.png](https://cdn-learn.adafruit.com/assets/assets/000/125/965/medium640/adafruit_products_one_one_one.png?1699472441) You will see a new disk drive appear called **METROM4BOOT**.   Drag the **adafruit\_circuitpython\_etc.uf2** file to **METROM4BOOT.** ![adafruit_products_AirLift_METROM4BOOT.png](https://cdn-learn.adafruit.com/assets/assets/000/074/949/medium640/adafruit_products_AirLift_METROM4BOOT.png?1556211532) ![adafruit_products_AirLift_Drag_UF2.png](https://cdn-learn.adafruit.com/assets/assets/000/074/950/medium640/adafruit_products_AirLift_Drag_UF2.png?1556211541) The LED will flash. Then, the **METROM4BOOT** drive will disappear and a new disk drive called **CIRCUITPY** will appear. That's it, you're done! :) ![adafruit_products_AirLift_CIRCUITPY.png](https://cdn-learn.adafruit.com/assets/assets/000/074/951/medium640/adafruit_products_AirLift_CIRCUITPY.png?1556211595) # Weather Display Matrix ## Build Metro M4 Airlift Matrix Display ## Assembly Talking to an LED matrix display can be tricky! The 64 x 32 LED used here has a whopping 2,048 pixels, and each can display RGB colors, which makes for a whole lot of data to sling around. Thankfully, our RGB Matrix shield paired with the Metro M4 Airlift does most of the heavy lifting. Let's assemble the boards and the display so we can get things running! ![](https://cdn-learn.adafruit.com/assets/assets/000/094/022/medium800/led_matrices_onairbuild-3406.jpg?1597091957) ## Shields Up First, add the male headers, screw terminal block, and the 8x2-pin socket to the Matrix shield, by [following this guide](https://learn.adafruit.com/32x16-32x32-rgb-led-matrix/connecting-using-rgb-matrix-shield). Be careful to match the socket polarity to the silkscreen image on the board. Be sure to also perform the clock pin mod [as shown here](https://learn.adafruit.com/32x16-32x32-rgb-led-matrix/connecting-using-rgb-matrix-shield#metro-m4-usage-2991520-5). Then plug the shield into the Metro M4 Airlift. ![led_matrices_onairbuild-3407.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/014/medium640/led_matrices_onairbuild-3407.jpg?1597091821) ## Power Connections To provide power, we'll screw the wiring harness connectors to the screw terminal blocks of the shield. Be sure to match the **black** wire to **GND** and the **red** wire to + **5Vout.** Now, simply plug the other end into the panel's power header. It can only go in one way. ![led_matrices_onairbuild-3408.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/023/medium640/led_matrices_onairbuild-3408.jpg?1597092003) ![led_matrices_onairbuild-3410.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/024/medium640/led_matrices_onairbuild-3410.jpg?1597092013) ## Data Cable Plug in the two ends of the ribbon cable, note that the connectors are keyed to only fit in the correct orientation. ![led_matrices_onairbuild-3411.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/025/medium640/led_matrices_onairbuild-3411.jpg?1597092443) ![led_matrices_onairbuild-3412.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/026/medium640/led_matrices_onairbuild-3412.jpg?1597092451) ![](https://cdn-learn.adafruit.com/assets/assets/000/094/027/medium800/led_matrices_onairbuild-3413.jpg?1597092963) ## Wall Adapter We'll power the Metro M4 from the 5V 2.5 (or a 4A) DC wall adapter plugged into the barrel jack. Even though USB can provide power to the board, the current isn't adequate for lighting up hundreds and thousands of LEDs! ![led_matrices_IMG_3414.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/028/medium640/led_matrices_IMG_3414.jpg?1597093064) ![led_matrices_IMG_3415.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/029/medium640/led_matrices_IMG_3415.jpg?1597093070) Info: # Weather Display Matrix ## Using MatrixPortal You can build this project with an all-in-one Matrix Portal board, its definitely the easiest and least-expensive way to go about it. You will need a matrix portal, matrix, and USB C power/data cable ### 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) ### 64x32 RGB LED Matrix - 4mm pitch [64x32 RGB LED Matrix - 4mm pitch](https://www.adafruit.com/product/2278) Bring a little bit of Times Square into your home with this sweet 64 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/2278) [Related Guides to the Product](https://learn.adafruit.com/products/2278/guides) ![Two white hands hold out an assembled and powered on 64x32 RGB LED Matrix Panel - 4mm pitch. The matrix displays "Adafruit Industries LED MATRIX! 32x64 *RGB*"](https://cdn-shop.adafruit.com/640x480/2278-00.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) # Weather Display Matrix ## 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. ![adafruit_io_mxprtl-3866.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/902/medium640/adafruit_io_mxprtl-3866.jpg?1600706317) ![adafruit_io_mxprtl-3867.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/903/medium640/adafruit_io_mxprtl-3867.jpg?1600706324) ## Power Terminals Next, screw in the spade connectors to the corresponding standoff. - **red** wire goes to **+5V**   - **black** wire goes to **GND** ![adafruit_io_mxprtl-3869.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/907/medium640/adafruit_io_mxprtl-3869.jpg?1600706432) ![adafruit_io_mxprtl-3871.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/908/medium640/adafruit_io_mxprtl-3871.jpg?1600706551) ## 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. ![adafruit_io_mxprtl-3872.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/910/medium640/adafruit_io_mxprtl-3872.jpg?1600706597) ![adafruit_io_mxprtl-3873.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/911/medium640/adafruit_io_mxprtl-3873.jpg?1600706672) ## Dual Matrix Setup If you're planning to use a 64x64 matrix, [follow these instructions on soldering the Address E Line jumper](https://learn.adafruit.com/adafruit-matrixportal-m4/pinouts#address-e-line-jumper-3072815). ## 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. This allows you to use the edge buttons from the front side.   Check nothing is impeding the board from plugging in firmly. If there's a plastic nub on the matrix that's keeping the Portal from sitting flat, cut it off with diagonal cutters ![adafruit_io_mxprtl-3874.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/912/medium640/adafruit_io_mxprtl-3874.jpg?1600706721) ![adafruit_io_mxprtl-3875.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/913/medium640/adafruit_io_mxprtl-3875.jpg?1600706732) ![](https://cdn-learn.adafruit.com/assets/assets/000/094/914/medium800/adafruit_io_mxprtl-3876.jpg?1600706891) ![](https://cdn-learn.adafruit.com/assets/assets/000/094/915/medium800/adafruit_io_mxprtl-3877.jpg?1600706894) Info: # Weather Display Matrix ## 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) # Weather Display Matrix ## Code the Weather Display Matrix ## Libraries We'll need to make sure we have these libraries installed. (Check out this [link](https://learn.adafruit.com/welcome-to-circuitpython/circuitpython-libraries) on installing libraries if needed.) - **adafruit\_bitmap\_font** - **adafruit\_bus\_device** - **adafruit\_display\_shapes** - **adafruit\_display\_text** - **adafruit\_esp32spi** - **adafruit\_io** - **adafruit\_matrixportal** - **adafruit\_requests.mpy** - **neopixel.mpy** ![CIRCUITPY drive with required project files and libraries](https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/folder-images/Weather_Display_Matrix.png?raw=true ) ## Connect to the Internet Once you have CircuitPython setup and libraries installed we can get your board connected to the Internet. The process for connecting can be found [here](https://learn.adafruit.com/adafruit-matrixportal-m4/internet-connect). ## Text Editor Adafruit recommends using the Mu editor for editing your CircuitPython code. You can get more info in [this guide](https://learn.adafruit.com/welcome-to-circuitpython/installing-mu-editor). Alternatively, you can use any text editor that saves simple text files. ## Code Click the Download: Zip File link below in the code window to get a zip file with all the files needed for the project. Copy **weather\_display\_matrix.py** from the zip file and place on the **CIRCUITPY** drive, then rename it to **code.py**. You'll also need to copy the following files to the **CIRCUITPY** drive. See the graphic at the top of the page as to filenames and where they go): - **fonts** directory, which contains three bitmap fonts - **loading.bmp** - **openweather\_graphics.py** - **weather-icons.bmp** - **settings.toml (after you edit to put your WiFi and weather credentials in the file, noted below)** https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Weather_Display_Matrix/code.py ## Open Weather Maps API Key We'll be using OpenWeatherMaps.org to retrieve the weather info through its API. In order to do so, you'll need to register for an account and get your API key. Go to this [link](https://home.openweathermap.org/users/sign_up) and register for a free account. Once registered, you'll get an email containing your API key, also known as the "openweather token". Copy and paste this key into your **settings.toml** file that is on the root level of your **CIRCUITPY** drive, so it looks something like this: ```python CIRCUITPY_WIFI_SSID="your-wifi-ssid" CIRCUITPY_WIFI_PASSWORD="your-wifi-password" openweather_token="xxxxxxxxxxxxxxxxxxxxxxxx" ``` ## Adafruit IO Time Server In order to get the precise time, our project will query the Adafruit IO Internet of Things service for the time. Adafruit IO is absolutely free to use, but you'll need to log in with your Adafruit account to use it. If you don't already have an Adafruit login, create [one here](https://accounts.adafruit.com/users/sign_up). If you haven't used Adafruit IO before, [check out this guide for more info](https://learn.adafruit.com/welcome-to-adafruit-io/getting-started-with-adafruit-io). Once you have logged into your account, there are two pieces of information you'll need to place in your **settings.toml** file: **Adafruit IO username** , and **Adafruit IO key**. Head to [io.adafruit.com](https://io.adafruit.com/) and simply click the **View AIO Key** link on the left hand side of the Adafruit IO page to get this information. Then, add them to the **settings.toml** file like this: ```python CIRCUITPY_WIFI_SSID="your-wifi-ssid" CIRCUITPY_WIFI_PASSWORD="your-wifi-password" ADAFRUIT_AIO_USERNAME="my_username" ADAFRUIT_AIO_KEY="my_key" openweather_token="my_openweather_token" ``` ## Problems Getting Data If you have any problems getting the data to display correctly, check that the **settings.toml** file has the information noted above. ## How it Works ### Libraries First we import libraries to help us behind the scenes. `time` will allow us to pause between weather queries. `board` gives us pin definitions. And, we'll use the `digitalio` library to query a `DigitalInOut` pin in the input `Direction` with `Pull` down resistor for mode selection. The `adafruit_matrixportal` library will be used both for `Network` queries and for controlling the `Matrix` display. We'll also import the `openweather_graphics` class to take care of the graphics, text display, scrolling and more. ### Settings Next, we import the settings needed for WiFi access point connection, Open Weather Maps key, and more. ## Units Primary: ### Jumper For the Metro M4 Airlift version, next we set up a digital input pin and a variable called jumper in order to switch the device from imperial to metric units. ### Buttons For the Matrix Portal version we can use the on-board buttons instead. By holding down one of the button while you power on the Matrix Portal, you can set unit mode of the display. The value is stored in non-volatile memory and is automatically used the next time the Matrix Portal is powered on. - Hold **Down** for **metric** mode - Hold **Up** for **imperial** mode ```python if hasattr(board, "D12"): jumper = DigitalInOut(board.D12) jumper.direction = Direction.INPUT jumper.pull = Pull.UP is_metric = jumper.value elif hasattr(board, "BUTTON_DOWN") and hasattr(board, "BUTTON_UP"): button_down = DigitalInOut(board.BUTTON_DOWN) button_down.switch_to_input(pull=Pull.UP) button_up = DigitalInOut(board.BUTTON_UP) button_up.switch_to_input(pull=Pull.UP) if not button_down.value: print("Down Button Pressed") microcontroller.nvm[0] = 1 elif not button_up.value: print("Up Button Pressed") microcontroller.nvm[0] = 0 print(microcontroller.nvm[0]) is_metric = microcontroller.nvm[0] else: is_metric = False if is_metric: UNITS = "metric" # can pick 'imperial' or 'metric' as part of URL query print("Jumper set to metric") else: UNITS = "imperial" print("Jumper set to imperial") ``` ### Data We'll set a variable for the `DATA_SOURCE` which will be used to query Open Weather Maps API next. This query will use the `LOCATION` and `UNITS` variables to form the request. ```python LOCATION = "Los Angeles, US" print("Getting weather for {}".format(LOCATION)) DATA_SOURCE = ( "http://api.openweathermap.org/data/2.5/weather?q=" + LOCATION + "&units=" + UNITS ) DATA_SOURCE += "&appid=" + getenv("openweather_token") ``` ## API Query and JSON Using this information, the code can then send a query to Open Weather Maps's API that looks something like this: `http://api.openweathermap.org/data/2.5/weather?q=Los Angeles, US&appid=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` (where all of those 'x's are your token). When this query is complete, it returns a JSON file that looks like this: ```java { "coord": { "lon": -118.24, "lat": 34.05 }, "weather": [ { "id": 501, "main": "Rain", "description": "moderate rain", "icon": "10d" } ], "base": "stations", "main": { "temp": 287.42, "pressure": 1016, "humidity": 50, "temp_min": 285.15, "temp_max": 289.15 }, "visibility": 16093, "wind": { "speed": 3.6, "deg": 300 }, "rain": { "1h": 1.52 }, "clouds": { "all": 75 }, "dt": 1552073935, "sys": { "type": 1, "id": 3514, "message": 0.0087, "country": "US", "sunrise": 1552054308, "sunset": 1552096542 }, "id": 5368361, "name": "Los Angeles", "cod": 200 } ``` ## JSON Traversal The JSON file is formatted in a way that makes it easy to traverse the hierarchy and parse the data. In it, you'll see keys, such as `main`, `description`, `icon` , and `temp`, and their respective values. So, here are some **key : value** pairs we care about for the weather station: - `"main" : "Rain"` - `"description" : "moderate rain"` - `"icon" : "10d"` - `"temp" : "287.42"` In order to fetch this data from the file, we need to be able to describe their locations in the file hierarchically. This is helpful, for example, in differentiating between the `'main'` weather condition and the `'main'` section containing temperature and other data. To avoid name clashing we rely on JSON traversal. In the **openweather\_graphics.py** file, you'll see how this is done. For example, the main key is found in this hierarchy of the JSON file: `['weather'], [0], ['main']` This means there is a key at the top level of the JSON file called `'weather'`, which has a sub-tree indexed `[0]`, and then below that is the `'main'` key. This process is used to cast the values of the temperature, weather, description, and which icon to display from the directory of bitmap icons. ### Scroll Time You can customize your scroll hold time here: `SCROLL_HOLD_TIME = 0 # set this to hold each line before finishing scroll` Setting this value to 0 means there will not be a hold when a line of text reaches the edge of the display. ### Display and Network Setup The display and network setup is next, along with setting the call to the `openweather_graphics` class: ```python matrix = Matrix() network = Network(status_neopixel=board.NEOPIXEL, debug=True) if UNITS == "imperial" or UNITS == "metric": gfx = openweather_graphics.OpenWeather_Graphics( matrix.display, am_pm=True, units=UNITS ) ``` ### Main Loop In the main loop we check the online time server once an hour to stay in sync with internet time, and we check the weather data every ten minutes, using the `gfx` call to the `openweather_graphics` class. ```python if (not localtime_refresh) or (time.monotonic() - localtime_refresh) > 3600: try: print("Getting time from internet!") network.get_local_time() localtime_refresh = time.monotonic() except RuntimeError as e: print("Some error occured, retrying! -", e) continue # only query the weather every 10 minutes (and on first run) if (not weather_refresh) or (time.monotonic() - weather_refresh) > 600: try: value = network.fetch_data(DATA_SOURCE, json_path=(DATA_LOCATION,)) print("Response is", value) gfx.display_weather(value) weather_refresh = time.monotonic() except RuntimeError as e: print("Some error occured, retrying! -", e) continue ``` With the json data from Open Weather Maps parsed, we can then scroll through the text labels for **weather description** , **humidity** , **wind speed** , and **location**. # Weather Display Matrix ## LED Matrix Diffuser ## LED Diffusion Acrylic You can add an [LED diffusion acrylic faceplate](https://www.adafruit.com/product/4594) to the your LED matrix display. (Pictured here with the [ON AIR project](https://learn.adafruit.com/rgb-matrix-automatic-youtube-on-air-sign)) 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. ![led_matrices_onairbuild-3367.jpg](https://cdn-learn.adafruit.com/assets/assets/000/093/987/medium640/led_matrices_onairbuild-3367.jpg?1597088161) ## Measure and Cut the Plastic You can use the sign to measure and mark cut lines on the paper backing of the acrylic sheet. Then, use a tablesaw or bandsaw with a fine toothed blade and a guide or sled to make the cuts. Note: it is possible to score and snap acrylic, but it can be very tricky to get an even snap without proper clamping. ![led_matrices_onairbuild-3343.jpg](https://cdn-learn.adafruit.com/assets/assets/000/093/988/medium640/led_matrices_onairbuild-3343.jpg?1597088278) ![led_matrices_onairbuild-3346.jpg](https://cdn-learn.adafruit.com/assets/assets/000/093/989/medium640/led_matrices_onairbuild-3346.jpg?1597088290) ![led_matrices_onairbuild-3347.jpg](https://cdn-learn.adafruit.com/assets/assets/000/093/991/medium640/led_matrices_onairbuild-3347.jpg?1597089259) ![led_matrices_onairbuild-3349.jpg](https://cdn-learn.adafruit.com/assets/assets/000/093/992/medium640/led_matrices_onairbuild-3349.jpg?1597089270) ![](https://cdn-learn.adafruit.com/assets/assets/000/093/998/medium800/led_matrices_onairbuild-3352.jpg?1597089308) Peel away the paper backing from both sides and set the acrylic onto your matrix display with the matte finished side facing out. ![led_matrices_onairbuild-3355.jpg](https://cdn-learn.adafruit.com/assets/assets/000/093/999/medium640/led_matrices_onairbuild-3355.jpg?1597089331) ## 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://www.protapes.com/products/uglu-600-dashes-sheets). 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. ![adafruit_io_weathermx-2-3.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/842/medium640/adafruit_io_weathermx-2-3.jpg?1600463849) ![adafruit_io_weathermx-2.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/843/medium640/adafruit_io_weathermx-2.jpg?1600463856) ![adafruit_io_weathermx-2-2.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/844/medium640/adafruit_io_weathermx-2-2.jpg?1600463866) Here you can see the impact of using the diffusion acrylic. (Pictured here with the ON AIR sign project) ![](https://cdn-learn.adafruit.com/assets/assets/000/094/006/medium800thumb/led_matrices_diffusionOnAir.jpg?1597089757) ## Stand A very simple and attractive way to display your matrix is with the adjustable [bent-wire stand](https://www.adafruit.com/product/1679). ![led_matrices_onairbuild-3418.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/032/medium640/led_matrices_onairbuild-3418.jpg?1597094067) ![led_matrices_onairbuild-3419.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/033/medium640/led_matrices_onairbuild-3419.jpg?1597094085) ![led_matrices_onairbuild-3421.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/034/medium640/led_matrices_onairbuild-3421.jpg?1597094097) ![led_matrices_onairbuild-3422.jpg](https://cdn-learn.adafruit.com/assets/assets/000/094/035/medium640/led_matrices_onairbuild-3422.jpg?1597094107) ![](https://cdn-learn.adafruit.com/assets/assets/000/095/378/medium800/adafruit_io_led_matrices_onairbuild-3383.jpg?1602006263) Alternately, you can use a frame, [3D printed brackets](https://learn.adafruit.com/led-protest-sign/build-the-sign#step-3065326), 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://www.adafruit.com/product/4631) can be used to stick the sign to a ferrous surface. ## 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) ### Adafruit Metro M4 Express AirLift (WiFi) - Lite [Adafruit Metro M4 Express AirLift (WiFi) - Lite](https://www.adafruit.com/product/4000) Give your next project a lift with _AirLift_ - our witty name for the ESP32 co-processor that graces this Metro M4. You already know about the  **Adafruit Metro M4**  featuring the  **Microchip ATSAMD51** , with it's 120MHz Cortex M4 with... In Stock [Buy Now](https://www.adafruit.com/product/4000) [Related Guides to the Product](https://learn.adafruit.com/products/4000/guides) ### 64x32 RGB LED Matrix - 4mm pitch [64x32 RGB LED Matrix - 4mm pitch](https://www.adafruit.com/product/2278) Bring a little bit of Times Square into your home with this sweet 64 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/2278) [Related Guides to the Product](https://learn.adafruit.com/products/2278/guides) ### Adafruit RGB Matrix Shield for Arduino [Adafruit RGB Matrix Shield for Arduino](https://www.adafruit.com/product/2601) Our RGB matrices are dazzling, with their hundreds or even _thousands_ of individual RGB LEDs. Compared to NeoPixels, they've got great density, power usage and the price-per-LED can't be beat. But...(isn't there always a _but_?) You need to use our special library to... In Stock [Buy Now](https://www.adafruit.com/product/2601) [Related Guides to the Product](https://learn.adafruit.com/products/2601/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) ### 5V 2.5A Switching Power Supply with 20AWG MicroUSB Cable [5V 2.5A Switching Power Supply with 20AWG MicroUSB Cable](https://www.adafruit.com/product/1995) Our all-in-one 5V 2.5 Amp + MicroUSB cable power adapter is the perfect choice for powering single-board computers like Raspberry Pi, BeagleBone, or anything else that's power-hungry! This adapter was specifically designed to provide 5.25V, not 5V, but we still call it a 5V USB... In Stock [Buy Now](https://www.adafruit.com/product/1995) [Related Guides to the Product](https://learn.adafruit.com/products/1995/guides) ### USB cable - USB A to Micro-B [USB cable - USB A to Micro-B](https://www.adafruit.com/product/592) This here is your standard A to micro-B USB cable, for USB 1.1 or 2.0. Perfect for connecting a PC to your Metro, Feather, Raspberry Pi or other dev-board or microcontroller Approximately 3 feet / 1 meter long Out of Stock [Buy Now](https://www.adafruit.com/product/592) [Related Guides to the Product](https://learn.adafruit.com/products/592/guides) ## Related Guides - [Adafruit Metro M4 Express AirLift (WiFi)](https://learn.adafruit.com/adafruit-metro-m4-express-airlift-wifi.md) - [Adafruit MatrixPortal M4](https://learn.adafruit.com/adafruit-matrixportal-m4.md) - [Purple Air AQI Display](https://learn.adafruit.com/purple-air-aqi-display.md) - [Matrix Portal M4 Boxing Interval Timer](https://learn.adafruit.com/matrix-portal-m4-boxing-interval-timer.md) - [Matrix Portal Stained Glass with WLED](https://learn.adafruit.com/matrix-portal-stained-glass-with-wled.md) - [RGB Matrix Automatic YouTube ON AIR Sign](https://learn.adafruit.com/rgb-matrix-automatic-youtube-on-air-sign.md) - [Quickstart: Adafruit IO WipperSnapper ](https://learn.adafruit.com/quickstart-adafruit-io-wippersnapper.md) - [Star Trek LCARS Display](https://learn.adafruit.com/star-trek-lcars-display.md) - [Matrix Portal Sand Handles](https://learn.adafruit.com/matrix-portal-sand.md) - [Tombstone Prop-Maker RP2040](https://learn.adafruit.com/tombstone-prop-maker-rp2040.md) - [Halloween Countdown Display Matrix](https://learn.adafruit.com/halloween-countdown-display-matrix.md) - [Matrix Portal Money-Sensing Tip Jar](https://learn.adafruit.com/matrix-portal-money-sensing-tip-jar.md) - [Adafruit Protomatter RGB Matrix Library](https://learn.adafruit.com/adafruit-protomatter-rgb-matrix-library.md) - [Network Connected RGB Matrix Clock](https://learn.adafruit.com/network-connected-metro-rgb-matrix-clock.md) - [Expressive Pixels for Adafruit Matrix Portal](https://learn.adafruit.com/expressive-pixels-for-matrix-portal.md)