WiFi-Controlled NeoPixel Matrix LED Sign

Adafruit Mini Skinny NeoPixel Digital RGB LED Strip - 30 LED/m

Adafruit NeoPixel Digital RGB LED Strip wired with all the LEDs illuminating various colors.

So thin. So mini. So teeeeeeny-tiny. It's the 'skinny' version of our classic NeoPixel strips!

$84.75

In Stock

Cable Gland PG-9 size - 0.158" to 0.252" Cable Diameter

We have some great waterproof and weather-proof items in the adafruit shop, but once you have a project built, you'll want...

$1.95

In Stock

Waterproof Polarized 4-Wire Cable Set

Outdoor enthusiasts rejoice! We now have very useful 4-wire polarized cable sets in a waterproof variety. These cable sets are ideal for projects that must weather the weather: dust,...

$2.50

In Stock

1 x Silicone Ribbon Cable

Silicone Cover Stranded-Core Ribbon Cable - 10 Wire 1 Meter Long - 28AWG Black

1 x USB Micro-B PCB

USB Micro-B Breakout Board

1 x Heat-Set Insert For Soldering Irons

M3 sized

1 x M3 Heat Set Inserts

M3 x 4mm heat set inserts

Download CAD source files

1 x USB C breakouts

USB 3.1 Type C male Connector

Buy Now

Hardware Screws

Use the following list of hardware to secure the Metro ESP32-S2 to the 3D printed enclosure.

8x M3 x 6mm long screws
4x M3 x 10mm long FF standoffs
4x M3 x 4mm heat set inserts

Source Files

The cad files are available to download using the links below.

Fusion 360, STEP files
Adjustable User Parameters

Download STL files

Plans

The wood working portion of the project feature a set of plans for printing out. These are handy to reference while cutting and assembling the parts.

Download Parts PDF

Download Steps PDF

3D Parts List

STL files for 3D printing are oriented to print "as-is" on FDM style machines. Parts are designed to 3D print without any support material. Original design source may be downloaded using the links below.

1x case-box.stl
1x case-gasket.stl
1x case-cover.stl
2x panel-bracket.stl
4x frame-bracket.stl
6x neopixel-holder.stl

Slicing Parts

Slice with setting for PLA material. The parts were sliced using CURA using the slice settings below.

PLA filament
215c extruder
0.2 layer height
10% gyroid infill
60mm/s print speed
60c heated bed

The diagram below provides a visual reference for wiring of the components. This diagram was created using the software package Fritzing.

Adafruit Library for Fritzing

Use Adafruit's Fritzing parts library to create circuit diagrams for your projects. Download the library or just grab individual parts. Get the library and parts from GitHub - Adafruit Fritzing Parts.

Metro ESP32-S2 features a built-in On/Off switch – Ensure it is set to the ON position in order to power up the board.

Wired Connections

The wiring diagram only shows 4 strips for simplicity. This project is designed to use 12x strips with 12x pixels on each strip. Arrange the NeoPixel strips so the flow of data is in a zigzag pattern.

NeoPixels to Metro

DIN from NeoPixel strip to Pin 6 on Metro
5V from NeoPixel strip to VHI on Metro
GND from NeoPixel strip to GND on Metro

NeoPixel strip to NeoPixels strip

DOUT from strip to DIN on strip
5V from strip to 5V on strip
GND from strip to GND on strip

Powering

The Adafruit board can be powered via USB or JST using a 3.7v lipo battery. In this project, a 5V power supply is used. If a lipo battery is being used, it can be rechargeable over the USB-C port on the Metro ESP32-S2.

Obtain Adafruit IO Key

Adafruit IO is Adafruit's free internet of things data portal. If you do not have an account, navigate to https://io.adafruit.com/ and create one.

You will need your Adafruit IO username and secret API key.

Navigate to Adafruit IO and click the Adafruit IO Key button to retrieve these values. Write them down in a safe place, you'll need them later.

Create Group

This guide will use multiple Adafruit IO feeds to store sensor values. To organize these feeds, you will need to create a new group.

Navigate to your Adafruit IO Feeds page.

Click Actions -> Create a New Group

Name the group sign-quotes. You can optionally set a description.

Click Create

Add Feeds to Group

Let's add a few feeds to the sign-quotes group to hold NeoPixel color and text.

Click Actions -> Create a New Feed

Name the feed signcolor

Click Add to Groups and select the sign-quotes group

Click Create

Repeat the process in the step above to create a feed for signtext.

Before proceeding, make sure your Air Quality Sensor group looks exactly like the screenshot below.

Adafruit IO Dashboard

Dashboards allow you to visualize data and control Adafruit IO connected projects from any modern web browser. We'll be adding a text block to enter text and color picker to choose a color for the NeoPixels.

Navigate to the dashboards page on Adafruit IO.

Click Actions -> Create New Dashboard

Name the dashboard My IoT NeoPixel LED Sign

Click Create

You should see your new dashboard pop-up in the list of Dashboards. Click the My IoT NeoPixel LED Sign dashboard link to navigate to the dashboard page.

You should see an empty dashboard. Let's fill it with blocks!

Click the '+' button on your dashboard to add a new block.

From the Create a New Block picker, click the Text Block

On the Choose Feed picker, select the signtext feed

Under Block Settings:

Set Block Title to LED Text
Set Font Size to Large
Click Create Block

From the Create a New Block picker, click the Color Picker Block

On the Choose Feed Picker, select the signcolor feed

Name the block Text Color

Click Create

Organize Dashboard

You can drag the dashboard blocks around to re-organize your dashboard.

Before moving on, make sure your dashboard contains the same blocks as the screenshot below

The ESP32-S2 has a built in bootloader, which means you never have to worry about 'bricking' your board. You can use it to load code directly, say CircuitPython or the binary output of an Arduino compilation or you can use it to load a second bootloader on, like UF2 which has a drag-n-drop interface.

The ROM bootloader can never be disabled or erased, so its always there if you need it!

Enter ROM Bootloader Mode

Entering the bootloader is easy. Complete the following steps.

Make sure your ESP32-S2 is plugged into USB port to your computer using a data/sync cable. Charge-only cables will not work!
Turn on the On/Off switch - check that you see the OK light on so you know the board is powered, a prerequisite!
Press and hold the DFU / Boot0 button down. Don't let go of it yet!
Press and release the Reset button. You should have the DFU/Boot0 button pressed while you do this.
Now you can release the DFU / Boot0 button
Check your computer for a new serial / COM port. On windows check the Device manager

On Windows check the Device manager - you will see a COM port, for example here its COM88. You may also see another "Other device" called ESP32-S2

It's best to do this with no other dev boards plugged in so you don't get confused about which COM port is the ESP32-S2

On Mac/Linux you will need to find the tty name which lives under /dev

On Linux, try ls /dev/ttyS* for example, to find the matching serial port name. In this case it shows up as /dev/ttyS87. If you don't see it listed try ls /dev/ttyA* on some Linux systems it might show up like /dev/ttyACM0

On Mac, try ls /dev/cu.usbmodem* for example, to find the matching serial port name. In this case, it shows up as /dev/cu.usbmodem01

It's best to do this with no other dev boards plugged in so you don't get confused about which serial port is the ESP32-S2

Run esptool and check connection

Once you have entered ROM bootloader mode, you can then use Espressif's esptool program to communicate with the chip! esptool is the 'official' programming tool and is the most common/complete way to program an ESP chip.

You will need to use the command line / Terminal to install and run esptool.

You will also need to have pip and Python installed (any version!)

Install the latest version using pip (you may be able to run pip without the 3 depending on your setup):

pip3 install --upgrade esptool

Then, you can run:

esptool.py

Run esptool.py in a new terminal/command line and verify you get something like the below:

Make sure you are running esptool v 3.0 or higher, which adds ESP32-S2 support

esptool v3.2 has a bug which prevents automatic chip detection. Add the argument `--chip esp32-s2` to your commands if you are getting errors.

Run the following command, replacing the identifier after --port with the COMxx, /dev/cu.usbmodemxx or /dev/ttySxx you found above.

esptool.py --port COM88 chip_id

You should get a notice that it connected over that port and found an ESP32-S2

You can now upload a binary file with the following command

esptool.py --port COM88 --after=no_reset write_flash 0x0 firmware.bin

don't forget to change the --port name to match, and the file name from firmware.bin to whatever the firmware file name is.

For example, I downloaded CircuitPython .bin and programmed it thus:

Once the data is verified, press the Reset button once more to launch the code you just programmed in!

If you're familiar with our other products and chipsets you may be famliar with our drag-n-drop bootloader, a.k.a UF2. We have a UF2 bootloader for the ESP32-S2, that will let you drag firmware on/off a USB disk drive

Unlike the M0 (SAMD21) and M4 (SAMD51) boards, there is no bootloader protection for the UF2 bootloader. That means it is possible to erase or damage the bootloader, especially if you upload Arduino sketches to ESP32S2 boards that doesn't "know" there's a bootloader it should not overwrite!

However, thanks to the ROM bootloader, you don't have to worry about it if the UF2 bootloader is damaged. You can simply re-load the UF2 bootloader (USB-disk-style) with the ROM bootloader (non-USB-drive)

Installing a new bootloader will erase your board! Be sure to back up your data first.

Step 1. Get into the ROM bootloader and install esptool.py

See the previous page on how to do that!

Step 2. Download the TinyUF2 release for your board

Choose the right release file from the list below. If your board is not explicitly mentioned, find it in the "all boards" link. These links are to .zip files.

Latest MagTag TinyUF2 release

Latest Metro ESP32-S2 TinyUF2 release

Latest Adafruit FunHouse TinyUF2 release

Look here if your board is not one of the ones above:

Latest TinyUF2 release for all boards

Step 3. Extract the combined.bin file from TinyUF2 release

The file you downloaded in Step 2 is a .zip file. Unzip it and find the combined.bin file. Note that this file is 3MB but that's because the bootloader is near the end of the available flash. It's not actually 3MB of program: mostof the file is empty but it's easier to program if we give you one combined 'swiss cheese' file. Save this file to your desktop or wherever you plan to run esptool from.

Step 4. Option A) Use esptool.py to upload

Put the board into bootloader mode (hold down BOOT0/DFU and click reset)
Determine the serial or COM port of the board

Run this command and replace the serial port name with your matching port and the file you just downloaded

esptool.py -p COM88 write_flash 0x0 combined.bin

There might be a bit of a 'wait' when programming, where it doesn't seem like its working. Give it a minute, it has to erase the old flash code which can cause it to seem like its not running.

You'll finally get an output like this:

Click RESET button to launch the bootloader. You'll see a new disk drive on your computer with the name MAGTAGBOOT or similar

Step 4 Option B) Use the Web Serial ESPTool to upload

Another option if you are having trouble getting ESPTool running, is to use the Web Serial ESPTool in this guide. This tool uses Web Serial to erase or upload firmware to your board.

CircuitPython is a derivative of MicroPython 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

Follow the steps to get CircuitPython installed on your Metro ESP32-S2.

Download the latest CircuitPython for your board from circuitpython.org

Click the link above and download the latest .BIN file.

Download and save it to your desktop (or wherever is handy).

Plug your Metro ESP32-S2 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.

Follow the 6 steps listed in the Enter the ROM Bootloader section of the ROM Bootloader page to enter the bootloader.

Follow the initial steps found in the Run esptool and check connection section of the ROM Bootloader page to verify your environment is set up, your board is successfully connected, and which port it's using.

In the final command to write a binary file to the board, replace the port with your port, and replace "firmware.bin" with the the file you downloaded above.

The output should look something like the output in the image.

Press reset to exit the bootloader.

Your CIRCUITPY drive should appear!

You're all set!

One of the great things about the ESP32 is the built-in WiFi capabilities. This page covers the basics of getting connected using CircuitPython.

The first thing you need to do is update your code.py to the following. 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, and copy the entire lib folder and the code.py file to your CIRCUITPY drive.

Download Project Bundle

# SPDX-FileCopyrightText: 2020 Brent Rubell for Adafruit Industries
#
# SPDX-License-Identifier: MIT

import ipaddress
import ssl
import wifi
import socketpool
import adafruit_requests

# URLs to fetch from
TEXT_URL = "http://wifitest.adafruit.com/testwifi/index.html"
JSON_QUOTES_URL = "https://www.adafruit.com/api/quotes.php"
JSON_STARS_URL = "https://api.github.com/repos/adafruit/circuitpython"

# 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

print("ESP32-S2 WebClient Test")

print("My MAC addr:", [hex(i) for i in wifi.radio.mac_address])

print("Available WiFi networks:")
for network in wifi.radio.start_scanning_networks():
    print("\t%s\t\tRSSI: %d\tChannel: %d" % (str(network.ssid, "utf-8"),
            network.rssi, network.channel))
wifi.radio.stop_scanning_networks()

print("Connecting to %s"%secrets["ssid"])
wifi.radio.connect(secrets["ssid"], secrets["password"])
print("Connected to %s!"%secrets["ssid"])
print("My IP address is", wifi.radio.ipv4_address)

ipv4 = ipaddress.ip_address("8.8.4.4")
print("Ping google.com: %f ms" % (wifi.radio.ping(ipv4)*1000))

pool = socketpool.SocketPool(wifi.radio)
requests = adafruit_requests.Session(pool, ssl.create_default_context())

print("Fetching text from", TEXT_URL)
response = requests.get(TEXT_URL)
print("-" * 40)
print(response.text)
print("-" * 40)

print("Fetching json from", JSON_QUOTES_URL)
response = requests.get(JSON_QUOTES_URL)
print("-" * 40)
print(response.json())
print("-" * 40)

print()

print("Fetching and parsing json from", JSON_STARS_URL)
response = requests.get(JSON_STARS_URL)
print("-" * 40)
print("CircuitPython GitHub Stars", response.json()["stargazers_count"])
print("-" * 40)

print("done")

# SPDX-FileCopyrightText: 2020 Brent Rubell for Adafruit Industries
#
# SPDX-License-Identifier: MIT

import ipaddress
import ssl
import wifi
import socketpool
import adafruit_requests

# URLs to fetch from
TEXT_URL = "http://wifitest.adafruit.com/testwifi/index.html"
JSON_QUOTES_URL = "https://www.adafruit.com/api/quotes.php"
JSON_STARS_URL = "https://api.github.com/repos/adafruit/circuitpython"

# 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

print("ESP32-S2 WebClient Test")

print("My MAC addr:", [hex(i) for i in wifi.radio.mac_address])

print("Available WiFi networks:")
for network in wifi.radio.start_scanning_networks():
    print("\t%s\t\tRSSI: %d\tChannel: %d" % (str(network.ssid, "utf-8"),
            network.rssi, network.channel))
wifi.radio.stop_scanning_networks()

print("Connecting to %s"%secrets["ssid"])
wifi.radio.connect(secrets["ssid"], secrets["password"])
print("Connected to %s!"%secrets["ssid"])
print("My IP address is", wifi.radio.ipv4_address)

ipv4 = ipaddress.ip_address("8.8.4.4")
print("Ping google.com: %f ms" % (wifi.radio.ping(ipv4)*1000))

pool = socketpool.SocketPool(wifi.radio)
requests = adafruit_requests.Session(pool, ssl.create_default_context())

print("Fetching text from", TEXT_URL)
response = requests.get(TEXT_URL)
print("-" * 40)
print(response.text)
print("-" * 40)

print("Fetching json from", JSON_QUOTES_URL)
response = requests.get(JSON_QUOTES_URL)
print("-" * 40)
print(response.json())
print("-" * 40)

print()

print("Fetching and parsing json from", JSON_STARS_URL)
response = requests.get(JSON_STARS_URL)
print("-" * 40)
print("CircuitPython GitHub Stars", response.json()["stargazers_count"])
print("-" * 40)

print("done")

Your CIRCUITPY drive should resemble the following.

To get connected, the next thing you need to do is update the secrets.py file.

Secrets File

We expect people to share tons of projects as they build CircuitPython WiFi widgets. What we want to avoid is people accidentally sharing their passwords or secret tokens and API keys. So, we designed all our examples to use a secrets.py file, that is on your CIRCUITPY drive, to hold secret/private/custom data. That way you can share your main project without worrying about accidentally sharing private stuff.

The initial secrets.py file on your CIRCUITPY drive should look like this:

Download Project Bundle

# SPDX-FileCopyrightText: 2020 Adafruit Industries
#
# SPDX-License-Identifier: Unlicense

# This file is where you keep secret settings, passwords, and tokens!
# If you put them in the code you risk committing that info or sharing it

secrets = {
    'ssid' : 'home_wifi_network',
    'password' : 'wifi_password',
    'aio_username' : 'my_adafruit_io_username',
    'aio_key' : 'my_adafruit_io_key',
    'timezone' : "America/New_York", # http://worldtimeapi.org/timezones
    }

# SPDX-FileCopyrightText: 2020 Adafruit Industries
#
# SPDX-License-Identifier: Unlicense

# This file is where you keep secret settings, passwords, and tokens!
# If you put them in the code you risk committing that info or sharing it

secrets = {
    'ssid' : 'home_wifi_network',
    'password' : 'wifi_password',
    'aio_username' : 'my_adafruit_io_username',
    'aio_key' : 'my_adafruit_io_key',
    'timezone' : "America/New_York", # http://worldtimeapi.org/timezones
    }

Inside is a Python dictionary named secrets with a line for each entry. Each entry has an entry name (say 'ssid') and then a colon to separate it from the entry key ('home_wifi_network') and finally a comma (,).

At a minimum you'll need to adjust the ssid and password for your local WiFi setup so do that now!

As you make projects you may need more tokens and keys, just add them one line at a time. See for example other tokens such as one for accessing GitHub or the Hackaday API. Other non-secret data like your timezone can also go here, just cause its called secrets doesn't mean you can't have general customization data in there!

For the correct time zone string, look at http://worldtimeapi.org/timezones and remember that if your city is not listed, look for a city in the same time zone, for example Boston, New York, Philadelphia, Washington DC, and Miami are all on the same time as New York.

Of course, don't share your secrets.py - keep that out of GitHub, Discord or other project-sharing sites.

Don't share your secrets.py file, it has your passwords and API keys in it!

If you connect to the serial console, you should see something like the following:

adafruit_products_1__screen__Users_brentrubell__screen_.png

In order, the example code...

Checks the ESP32's MAC address.

print("My MAC addr:", [hex(i) for i in wifi.radio.mac_address])

print("My MAC addr:", [hex(i) for i in wifi.radio.mac_address])

Performs a scan of all access points and prints out the access point's name (SSID), signal strength (RSSI), and channel.

print("Avaliable WiFi networks:")
for network in wifi.radio.start_scanning_networks():
    print("\t%s\t\tRSSI: %d\tChannel: %d" % (str(network.ssid, "utf-8"),
            network.rssi, network.channel))
wifi.radio.stop_scanning_networks()

print("Avaliable WiFi networks:")
for network in wifi.radio.start_scanning_networks():
    print("\t%s\t\tRSSI: %d\tChannel: %d" % (str(network.ssid, "utf-8"),
            network.rssi, network.channel))
wifi.radio.stop_scanning_networks()

Connects to the access point you defined in the secrets.py file, prints out its local IP address, and attempts to ping google.com to check its network connectivity.

print("Connecting to %s"%secrets["ssid"])
wifi.radio.connect(secrets["ssid"], secrets["password"])
print(print("Connected to %s!"%secrets["ssid"]))
print("My IP address is", wifi.radio.ipv4_address)

ipv4 = ipaddress.ip_address("8.8.4.4")
print("Ping google.com: %f ms" % wifi.radio.ping(ipv4))

print("Connecting to %s"%secrets["ssid"])
wifi.radio.connect(secrets["ssid"], secrets["password"])
print(print("Connected to %s!"%secrets["ssid"]))
print("My IP address is", wifi.radio.ipv4_address)

ipv4 = ipaddress.ip_address("8.8.4.4")
print("Ping google.com: %f ms" % wifi.radio.ping(ipv4))

The code creates a socketpool using the wifi radio's available sockets. This is performed so we don't need to re-use sockets. Then, it initializes a a new instance of the requests interface - which makes getting data from the internet really really easy.

pool = socketpool.SocketPool(wifi.radio)
requests = adafruit_requests.Session(pool, ssl.create_default_context())

pool = socketpool.SocketPool(wifi.radio)
requests = adafruit_requests.Session(pool, ssl.create_default_context())

To read in plain-text from a web URL, call requests.get - you may pass in either a http, or a https url for SSL connectivity.

print("Fetching text from", TEXT_URL)
response = requests.get(TEXT_URL)
print("-" * 40)
print(response.text)
print("-" * 40)

print("Fetching text from", TEXT_URL)
response = requests.get(TEXT_URL)
print("-" * 40)
print(response.text)
print("-" * 40)

Requests can also display a JSON-formatted response from a web URL using a call to requests.get.

print("Fetching json from", JSON_QUOTES_URL)
response = requests.get(JSON_QUOTES_URL)
print("-" * 40)
print(response.json())
print("-" * 40)

print("Fetching json from", JSON_QUOTES_URL)
response = requests.get(JSON_QUOTES_URL)
print("-" * 40)
print(response.json())
print("-" * 40)

Finally, you can fetch and parse a JSON URL using requests.get. This code snippet obtains the stargazers_count field from a call to the GitHub API.

print("Fetching and parsing json from", JSON_STARS_URL)
response = requests.get(JSON_STARS_URL)
print("-" * 40)
print("CircuitPython GitHub Stars", response.json()["stargazers_count"])
print("-" * 40)

print("Fetching and parsing json from", JSON_STARS_URL)
response = requests.get(JSON_STARS_URL)
print("-" * 40)
print("CircuitPython GitHub Stars", response.json()["stargazers_count"])
print("-" * 40)

OK you now have your ESP32 board set up with a proper secrets.py file and can connect over the Internet. If not, check that your secrets.py file has the right ssid and password and retrace your steps until you get the Internet connectivity working!

CircuitPython Install Check

You should ensure you have CircuitPython 6.1.0 or greater on your board. Plug your board in with a known good data + power cable (not the cheesy USB cable that comes with USB power packs, they are power only). You should see a new flash drive pop up.

If the drive loads, then open the boot_out.txt file to ensure the version number is 6.1.0 or greater.

Adafruit CircuitPython 6.1.0-beta.1 on 2020-11-20; Metro ESP32S2 with ESP32S2

Adafruit CircuitPython 6.1.0-beta.1 on 2020-11-20; Metro ESP32S2 with ESP32S2

Add Font

Download the font file below and add it to the root of the CircuitPython drive.

Download Font File

Required Libraries

adafruit_framebuf.mpy
adafruit_io
adafruit_led_animation
adafruit_pixel_framebuf.mpy
adafruit_requests.mpy
neopixel.mpy

Once we have all the files we need, a directory listing will look similar to above as far as files and directories.

Upload Code

Click on the Download Project Zip link below to grab the main code directly from GitHub. Rename the file to code.py and drop it onto the main (root) directory of the CIRCUITPY drive that appeared in your computer file explorer/finder when the board was plugged in via a known, good USB cable The code will run properly when all of the files have been uploaded including libraries.

Use any text editor or favorite IDE to modify the code. We suggest using Mu.

Download Project Bundle