Beginner / 2–3 hours

Program PixelWing with Arduino

Want to use Arduino instead of CircuitPython? PixelWing's controller is an ESP32-S3, so we can use Espressif's ESP32S3 Dev Module board definition. We'll tell the sketch which pins PixelWing uses, then upload a little color test for the matrix. You can start here without completing the CircuitPython pages.

Arduino compiles your C++ sketch and writes it to flash. Uploading replaces the CircuitPython firmware, so first copy any files you want to keep from CIRCUITPY to your computer, including code.py, settings.toml, and lib/. Returning to CircuitPython later means reinstalling the PixelWing-specific firmware described on the CircuitPython page, then restoring your files.

Install ESP32 support

Install Arduino IDE, then follow these steps in IDE 2:

  1. Open Settings / Preferences and add this stable package URL to Additional boards manager URLs: https://espressif.github.io/arduino-esp32/package_esp32_index.json.
  2. Open Boards Manager, search for esp32, and install esp32 by Espressif Systems.
  3. Under Tools > Board > esp32, select ESP32S3 Dev Module. The menu group name can vary with the package version.

Espressif's installation instructions cover the package setup. Its Tools menu reference explains using a generic definition for a custom board.

Set up the board and USB

Connect PixelWing with a USB-C data cable. The board uses the S3's native USB connection. Start with these settings under Tools; the exact menu labels depend on your installed ESP32 package:

| Setting | Selection | | --- | --- | | Board | ESP32S3 Dev Module | | USB Mode | Hardware CDC and JTAG | | USB CDC On Boot | Enabled | | Upload Mode | UART0 / Hardware CDC | | USB DFU On Boot | Disabled, if shown | | PSRAM | Disabled for this example | | Flash Size | Match the fitted module; see below | | Partition Scheme | A scheme that fits the selected flash size | | Port | PixelWing's USB serial port |

The sibling PixelWing CircuitPython definition uses 8 MB flash, QIO, 80 MHz. Those are starting settings for a matching 8 MB board, but the published hardware notes still leave the exact module ordering code unconfirmed. Check your module marking or Kavrous's board specification before selecting flash size and mode. This sketch doesn't need PSRAM; leave it disabled rather than guessing a PSRAM type.

For the first upload, or if the board doesn't offer a serial port, enter download mode manually:

  1. Hold BOOT0.
  2. Press and release RESET0 while still holding BOOT0.
  3. Release BOOT0 and select the newly appearing USB port in Arduino IDE.
  4. Upload your sketch. Press RESET0 afterward if it stays in download mode.

The port name may change between download mode and the running sketch. Select the running port again before opening Serial Monitor. Espressif's USB flashing guide explains manual download mode and USB CDC.

Light the matrix

Open Library Manager, search for Adafruit NeoPixel, and install the library by Adafruit. Create a new sketch and replace its contents with this complete program:

#include <Adafruit_NeoPixel.h>

constexpr uint8_t PIXEL_PIN = 48;
constexpr uint16_t PIXEL_COUNT = 50;
Adafruit_NeoPixel pixels(PIXEL_COUNT, PIXEL_PIN, NEO_GRB + NEO_KHZ800);

void setup() {
  Serial.begin(115200);
  pixels.begin();
  pixels.setBrightness(13);  // About 5 percent of the 0–255 range.
  pixels.clear();
  pixels.show();
}

void loop() {
  pixels.fill(pixels.Color(255, 0, 0));
  pixels.show();
  Serial.println("Red");
  delay(1000);

  pixels.fill(pixels.Color(0, 255, 0));
  pixels.show();
  Serial.println("Green");
  delay(1000);

  pixels.fill(pixels.Color(0, 0, 255));
  pixels.show();
  Serial.println("Blue");
  delay(1000);

  pixels.clear();
  pixels.show();
  Serial.println("Off");
  delay(1000);
}

Click Verify, then Upload. Open Serial Monitor at 115200 baud. The matrix should cycle through red, green, blue, and off, with the matching word printed once a second.

setup() runs once after startup. loop() repeats. We prepare the colors with fill() and send them to the LEDs with show(). setBrightness(13) keeps the initial output low; Arduino's NeoPixel library uses a 0–255 brightness scale rather than CircuitPython's 0–1 scale. The Adafruit NeoPixel library provides the pixel methods used here.

Use PixelWing's actual pins

A generic board definition doesn't supply PixelWing's CircuitPython aliases. Use the GPIO numbers from the hardware reference:

| Connection | Arduino GPIO | | --- | --- | | Matrix data | 48 | | I2C SDA | 21 | | I2C SCL | 47 |

For an I2C sensor sketch, include Wire.h and call Wire.begin(21, 47); in setup() before initializing your sensor driver. Pass that bus to the driver if its API requires it. Arduino's argument order here is SDA, then SCL. Use a 3.3 V compatible accessory on the Qwiic / STEMMA QT connector.

For individual pixels, try pixels.setPixelColor(0, pixels.Color(255, 80, 0)); followed by pixels.show(). The NeoPixel coordinates page explains how to verify the chain layout. Its Python examples need translating, but the same sequential-row formula, y * 10 + x, applies once you've checked your board's mapping.

If uploading or lighting fails

Want to add Wi-Fi next? Arduino-ESP32 includes WiFi.h and Wi-Fi examples in the IDE. Buy and fit the external antenna before trying them. The browser controller elsewhere in this guide is a CircuitPython project; an Arduino version needs an Arduino web-server implementation too.

Back to the PixelWing introduction.