Beginner / 2–3 hours

CircuitPython essentials

CircuitPython makes the edit-and-try part of a hardware project pleasantly short. Your board runs code.py, you save a change, and the program usually restarts automatically. You don't need to compile and upload your program for every little experiment.

There's still a small amount of setup to understand. Let's get that out of the way before we ask the LEDs to do anything interesting.

Prefer to compile and upload C++ sketches? Use the Arduino setup page instead.

Connect the right board

Plug PixelWing into your computer with a USB data cable. With CircuitPython installed and USB storage enabled, a drive named CIRCUITPY appears. Open boot_out.txt there and check that it identifies Kavrous PixelWing ESP32S3. That file also tells you the firmware version.

If the drive doesn't appear, try a known data cable and a direct USB port. A board in its ROM download mode won't present a CIRCUITPY drive.

Need to install firmware? Use the PixelWing hardware repository's getting-started instructions for the board-specific release and procedure. At the time this guide was prepared, that repository still described the installation release as pending. Don't substitute the older S2 firmware or a random ESP32-S3 image. Pin assignments, flash settings, and USB support need to match. If your board arrived without firmware, obtain the S3 image and installation instructions from Kavrous before continuing.

Your first file

Save this as code.py in the root of CIRCUITPY, beside boot_out.txt:

import time

message = "Hello from PixelWing!"
count = 0

while True:
    print(message, count)
    count = count + 1
    time.sleep(1)

Open a CircuitPython serial console, such as the one in Mu or Thonny, and select PixelWing's serial port. You should see a greeting with a number that increases once a second. Close other serial programs if the port is already in use. Adafruit's serial console guide walks through editor-specific connections.

import time makes the timing module available. A variable gives a value a name, so message holds text and count holds a number. while True: repeats the indented block until the program stops. time.sleep(1) pauses for one second.

Python uses indentation to group instructions. Keep four spaces before every line inside this loop. Also make sure your editor saved code.py, not code.py.txt.

Try changing the greeting and the delay. Saving should restart the count at zero. That restart is useful feedback: the board loaded your new file.

Talk to the board directly

In the serial console, press Ctrl-C to stop the running program. At the >>> prompt, called the REPL, enter these lines one at a time:

import board
print(dir(board))
print(board.NEOPIXEL)

board supplies names for the physical connections. On the S3 firmware used here, NEOPIXEL is the matrix data connection; SDA and SCL are the I2C connector signals. board.I2C() creates the default I2C bus. We don't need to memorize module pad numbers to use those names.

Press Ctrl-D to reload and run code.py again. Code typed into the REPL is temporary; put anything you want to keep in a file.

Add libraries

Built-in modules such as board, time, wifi, and socketpool come with the appropriate CircuitPython firmware. Other libraries are files you add to CIRCUITPY/lib/.

Download the CircuitPython library bundle matching your firmware's major version. For example, a 9.x firmware needs the 9.x bundle. Extract it on your computer, then copy the libraries each project needs from the bundle's lib folder into the board's lib folder. Keep library folders intact.

| Project | Add to CIRCUITPY/lib/ | | --- | --- | | Basic matrix | neopixel.mpy, adafruit_pixelbuf.mpy if supplied by your bundle and not built in | | Animations | Above, plus the entire adafruit_led_animation folder | | BME280 sensor | Basic matrix libraries, adafruit_bme280 folder, adafruit_bus_device folder, adafruit_register folder | | Web controller | Basic matrix libraries, plus the entire adafruit_httpserver folder and its bundle-listed dependencies |

Some firmware builds already include particular libraries. If an import fails, the traceback names what's missing. Copy that dependency from the same bundle rather than mixing files from different releases. Adafruit's library installation guide explains the folder layout and version errors.

Read the error before rewriting the project

An error prints a traceback in the serial console. Start with its last line, then look at the line number in code.py.

Each full project below replaces the previous code.py. You don't need several programs competing for the matrix or trying to claim the same I2C pins.

Next: Make the matrix your own with NeoPixel.