Next, to modify two files within the WipperSnapper Arduino library to detect your board.

Modify Wippersnapper_Boards.h

This file can be found within WipperSnapper_Arduino/src/Wippersnapper_Boards.h and contains the following information for each board:

BOARD_ID - A required string identifying the board. This is the same as the board definition boardName entry.
The required provisioning method is either defined by:
- USE_TINYUSB - UF2-based Provisioning (Uses Native USB)
- or
- USE_LITTLEFS - Web-based Provisioning (Uses Web Installer)
The required method of displaying the board's status using lights. Each board should implement only one of the following methods:
- USE_STATUS_NEOPIXEL - If your development board has a NeoPixel built-in for displaying the status
  - STATUS_NEOPIXEL_PIN - The data pin on the board the NeoPixel is connected to.
  - STATUS_NEOPIXEL_NUM - The number of NeoPixels connected to your board.
- USE_STATUS_DOTSTAR - If your development board has a DotStar (APA102) built-in for displaying the status.
  - STATUS_DOTSTAR_PIN_DATA - The data pin on the board that the DotStar LED is connected to.
  - STATUS_DOTSTAR_PIN_CLK - The clock pin on the board that the DotStar LED is connected to.
  - STATUS_DOTSTAR_NUM - The number of DotStar LEDs connected to your board.
- USE_STATUS_LED - If your development board has a LED (one-color) built-in for displaying the status.
  - STATUS_LED_PIN - The pin on the board that the status LED is connected to.

As an example, you can add the Adafruit Feather ESP32-S3 to WipperSnapper_Boards.h.

First, you'll need to add a new expression for the Adafruit Feather ESP32 S3 to the end of the WipperSnapper_Boards.h file. This case is used by the Arduino compiler to detect which board its building WipperSnapper for.

To find the build name used by Arduino, locate the board's support package. For example, the Adafruit Feather ESP32-S3 uses the Arduino-ESP32 board support package. Within the arduino-esp32/boards.txt file (or boards.txt file for your platform), search for the board you're using. Once you've found your board, navigate to the build.board entry.

In the case of the Feather ESP32-S3, the platformName.build.board string is:

Download File

Copy Code

adafruit_feather_esp32s3.build.board=ADAFRUIT_FEATHER_ESP32S3_NOPSRAM

adafruit_feather_esp32s3.build.board=ADAFRUIT_FEATHER_ESP32S3_NOPSRAM

Add a new #elif defined() expression to the end of the WipperSnapper_Boards.h file. This string should be prepended by ARDUINO_ so the Arduino compiler knows to pick it up.

Download File

Copy Code

#elif defined(ARDUINO_ADAFRUIT_FEATHER_ESP32S3_NOPSRAM)
...
#else
#warning "Board type not identified within Wippersnapper_Boards.h!"
#endif

#elif defined(ARDUINO_ADAFRUIT_FEATHER_ESP32S3_NOPSRAM)
...
#else
#warning "Board type not identified within Wippersnapper_Boards.h!"
#endif

Next, let's fill out the expression. The Adafruit Feather ESP32-S3 uses the Native USB (TinyUSB) workflow, so you'll #define USE_TINYUSB.

Download File

Copy Code

#elif defined(ARDUINO_ADAFRUIT_FEATHER_ESP32S3_NOPSRAM)
#define USE_TINYUSB
#else
#warning "Board type not identified within Wippersnapper_Boards.h!"
#endif

#elif defined(ARDUINO_ADAFRUIT_FEATHER_ESP32S3_NOPSRAM)
#define USE_TINYUSB
#else
#warning "Board type not identified within Wippersnapper_Boards.h!"
#endif

The Feather ESP32-S3 has one built-in NeoPixel connected to digital pin 33.

Add a #define USE_STATUS_NEOPIXEL to the expression along with the pin (STATUS_NEOPIXEL_PIN) and the number of NeoPixels connected to the board (STATUS_NEOPIXEL_NUM)

Download File

Copy Code

#elif defined(ARDUINO_ADAFRUIT_FEATHER_ESP32S3_NOPSRAM)
#define USE_TINYUSB
#define USE_STATUS_NEOPIXEL
#define STATUS_NEOPIXEL_PIN PIN_NEOPIXEL
#define STATUS_NEOPIXEL_NUM NEOPIXEL_NUM
#else
#warning "Board type not identified within Wippersnapper_Boards.h!"
#endif

#elif defined(ARDUINO_ADAFRUIT_FEATHER_ESP32S3_NOPSRAM)
#define USE_TINYUSB
#define USE_STATUS_NEOPIXEL
#define STATUS_NEOPIXEL_PIN PIN_NEOPIXEL
#define STATUS_NEOPIXEL_NUM NEOPIXEL_NUM
#else
#warning "Board type not identified within Wippersnapper_Boards.h!"
#endif

That's it! WipperSnapper should now be able to detect your board during compilation.

Modify TinyUSB (UF2-backed Workflow) Provisioning File

This step is only for if your board supports the TinyUSB bootloader.

This enables your board to use the TinyUSB provisioning workflow. Open the file provisioning/tinyusb/Wippersnapper_FS.cpp in a text editor and add the build string you located above (ex: ARDUINO_ADAFRUIT_FEATHER_ESP32S3_NOPSRAM) to the top of the file.

Download File

Copy Code

#if defined(ARDUINO_MAGTAG29_ESP32S2) || defined(ARDUINO_METRO_ESP32S2) ||     \
    ...
    defined(ARDUINO_ADAFRUIT_FEATHER_ESP32S3_NOPSRAM)
#include "Wippersnapper_FS.h"

#if defined(ARDUINO_MAGTAG29_ESP32S2) || defined(ARDUINO_METRO_ESP32S2) ||     \
    ...
    defined(ARDUINO_ADAFRUIT_FEATHER_ESP32S3_NOPSRAM)
#include "Wippersnapper_FS.h"

Modify LittleFS (Web-backed Workflow) Provisioning File

This step is only for if your board uses an ESP8266, ESP32, or ESP32-C3.

This enables your board to use the web-backed provisioning workflow. Open the file provisioning/littlefs/WipperSnapper_LittleFS.cpp in a text editor and add the build string you located above to the top of the file.

Download File

Copy Code

#if defined(ARDUINO_FEATHER_ESP32) ||                                          \
    defined(ARDUINO_ESP8266_ADAFRUIT_HUZZAH) ||                                \
    defined(ARDUINO_ADAFRUIT_FEATHER_ESP32_V2) ||							   \
    defined(YOUR_PLATFORM_HERE)
#include "WipperSnapper_LittleFS.h"

#if defined(ARDUINO_FEATHER_ESP32) ||                                          \
    defined(ARDUINO_ESP8266_ADAFRUIT_HUZZAH) ||                                \
    defined(ARDUINO_ADAFRUIT_FEATHER_ESP32_V2) ||							   \
    defined(YOUR_PLATFORM_HERE)
#include "WipperSnapper_LittleFS.h"

Add your Board to CI-Arduino

You'll need to add your board to CI-Arduino so you can build WipperSnapper for your board.

To do this, you'll need to identify the board's fully-qualified board name (FQBN). This can be found by plugging your board into USB and running the command arduino-cli board list in a terminal.

The FQBN for the Feather ESP32-S3, esp32:esp32:adafruit_feather_esp32s3 esp32:esp32, is highlighted blue on the screenshot above.

Next, open ci-arduino/build_platform.py in a text editor and scroll down until you reach the list containing the supported boards.

"feather_esp32s3" : ["esp32:esp32:adafruit_feather_esp32s3", "0xc47e5767", None],

Download File

Copy Code

ALL_PLATFORMS={
    # classic Arduino AVR
    "uno" : ["arduino:avr:uno", None, None],
    "leonardo" : ["arduino:avr:leonardo", None, None],
    "mega2560" : ["arduino:avr:mega:cpu=atmega2560", None, None],
    # Arduino SAMD
    ...
}

ALL_PLATFORMS={
    # classic Arduino AVR
    "uno" : ["arduino:avr:uno", None, None],
    "leonardo" : ["arduino:avr:leonardo", None, None],
    "mega2560" : ["arduino:avr:mega:cpu=atmega2560", None, None],
    # Arduino SAMD
    ...
}

Locate the section of the list containing your board's chip.

The Feather ESP32-S3 uses the Espressif ESP32-S3 chip. In ALL_PLATFORMS, there's a comment for "Espressif".

Download File

Copy Code

...
# Arduino SAMD
"zero" : ["arduino:samd:arduino_zero_native", "0x68ed2b88", None, None],
"cpx" : ["arduino:samd:adafruit_circuitplayground_m0", "0x68ed2b88", None],
# Espressif
"esp8266" : ["esp8266:esp8266:huzzah:eesz=4M3M,xtal=80", None, None],
"esp32" : ["esp32:esp32:featheresp32:FlashFreq=80", None, None],
...

...
# Arduino SAMD
"zero" : ["arduino:samd:arduino_zero_native", "0x68ed2b88", None, None],
"cpx" : ["arduino:samd:adafruit_circuitplayground_m0", "0x68ed2b88", None],
# Espressif
"esp8266" : ["esp8266:esp8266:huzzah:eesz=4M3M,xtal=80", None, None],
"esp32" : ["esp32:esp32:featheresp32:FlashFreq=80", None, None],
...

Under the list of boards with the same chip as your board, make a new line and add a new entry containing the board name and its FQBN.

If you're using the TinyUSB-backed workflow, you will also need to add the UF2 family identifier to this entry. This is used for the WipperSnapper build script to automatically generate a UF2 file for your board upon a new library release. Microsoft provides a listing of UF2 families on https://github.com/microsoft/uf2/blob/master/utils/uf2families.json with the family identifier located under the id entry for each array.

For the Feather ESP32-S3, the FQBN is esp32:esp32:adafruit_feather_esp32s3 esp32:esp32. The chip family is the ESP32-S3 and has the UF2 family identifier 0xc47e5767. An entry would look like the following.

Download File

Copy Code

...
"feather_esp32s2" : ["esp32:esp32:adafruit_feather_esp32s2", "0xbfdd4eee", None],
"feather_esp32s2_tft" : ["esp32:esp32:adafruit_feather_esp32s2_tft", "0xbfdd4eee", None],
"feather_esp32s3" : ["esp32:esp32:adafruit_feather_esp32s3", "0xc47e5767", None],
...

...
"feather_esp32s2" : ["esp32:esp32:adafruit_feather_esp32s2", "0xbfdd4eee", None],
"feather_esp32s2_tft" : ["esp32:esp32:adafruit_feather_esp32s2_tft", "0xbfdd4eee", None],
"feather_esp32s3" : ["esp32:esp32:adafruit_feather_esp32s3", "0xc47e5767", None],
...

Build New Firmware

Finally, let's build the modified WipperSnapper library for your platform.

To build WipperSnapper, call the build_platform.py script from the root of Adafruit_WipperSnapper_Arduino. You'll need to provide the script with the board name you added to ci-arduino.

For example, to build WipperSnapper for the ESP32-S3, run the following command.

Download File

Copy Code

python3 /Users/brent/Desktop/github/ci-arduino/build_platform.py feather_esp32s3

python3 /Users/brent/Desktop/github/ci-arduino/build_platform.py feather_esp32s3

The script will install the required dependencies and platform support.

If the build completes with no errors, it will generate binary files within the examples/Wippersnapper_demo/build/platformName directory.

For platforms that generate a .UF2 file, the corresponding .UF2 file should be within this directory.

Test Firmware with WipperSnapper

Next, to test that the firmware you built works with WipperSnapper. Start by loading the created firmware onto your board using a bootloader or programmer.

Add Credentials to your Board

Next, you'll need to add your Adafruit.io and network credentials to your board so it can connect to Adafruit.io WipperSnapper. Depending on which provisioning method you've used, the process differs:

For platforms that use LittleFS - navigate to the WipperSnapper Web Uploader website. Select a board from the dropdown which uses the same chip as your board and follow the steps to connect the board.

After entering your credentials, click the Update Credentials Only button to add your WipperSnapper credentials to your board's filesystem.

For platforms that use TinyUSB, the WIPPER drive should automatically appear on your computer as a USB flash storage drive.

Follow this guide to add your network and Adafruit.io credentials to the secrets.json file

After adding credentials to your board, reset its power and navigate to adafruit.io. You should see a pop-up with the text "New Device Detected!" appear.