Do you want to use your favorite WiFi development board with Adafruit.io WipperSnapper?

This guide will walk you through the process of adding a new board to Adafruit.io WipperSnapper - our no-code IoT platform. Upon completion of the guide, your board will be included with every new release of the WipperSnapper library.

You'll begin by creating a board definition to describe the physical characteristics and properties of your board. Then, you create local forks of WipperSnapper and its required build tool and test that everything is working correctly by building the firmware. You'll edit files so WipperSnapper can detect your development board and create a pull request to add the board to WipperSnapper. Finally, once your board is added to the WipperSnapper library, its corresponding firmware file(s) will be built and distributed with each release of the library.

You will need to be familiar with Git and GitHub to complete this guide. Adafruit has a great guide on Contributing to CircuitPython with Git and GitHub if you're unsure how to get started. You will also be asked to modify some Python, C++, and JSON code. If you are unfamiliar with any of these - don't fret - this guide will explain what to do, step by step.

Is my board's microcontroller compatible with WipperSnapper?

The following platforms/microcontrollers are compatible with the Adafruit.io WipperSnapper firmware at this time:

  • ESP8266
  • ESP32
  • ESP32-S2
  • ESP32-S3
  • ESP32-C3
  • Raspberry Pi RP2040
  • SAMD51 + Adafruit "AirLift" ESP32 Co-Processor

If your development board uses one of these platforms - you can add it to WipperSnapper by following the steps in this guide!

We're first going to create a board definition for the development board. This is a required step and is used to help WipperSnapper identify a development board's physical characteristics.

What is a board definition?

In WipperSnapper, a board definition is a JSON file that contains a virtual representation of a physical development board. The definition file contains information about the board's physical pin locations, microcontroller type, and vendor information. WipperSnapper requires one board definition file for each development board it supports.

This guide assumes you already have a GitHub account, have installed Git, and are comfortable using Git and GitHub.

If you are unfamiliar with GitHub and Git or would like to refresh before starting, we have a great guide on using the features of GitHub here >>>.

Fork the Adafruit_WipperSnapper_Boards Repository

WipperSnapper's board definition files are stored in the WipperSnapper_Boards repository on GitHub. You'll want to create a fork of this repository on your account before continuing.

Locally Clone the Fork of WipperSnapper_Boards 

Once forked, create a clone on your computer of the Wippersnapper_Boards repository you forked above.

Duplicate an Existing Board Directory

After you've locally cloned the WipperSnapper_Boards repository, navigate to this folder on your computer. Hardware definition files are kept within the Wippersnapper_Boards/boards folder and are organized by board name.

Each folder contains two files: the board definition (definition.json) and an image of the board (image.png).

Finding an existing development board that matches your development board is the simplest method of adding a new board to WipperSnapper. For the best results, pick an existing board directory to duplicate based on the following:

  • Which microcontroller are you using? You'll want to match as closely as possible to ensure RAM, size, etc are the same. You can do this by verifying that the full name of the chip, e.g. ESP32-S3, matches the board you're copying from.
  • What's your board's form factor? If your board uses the standard Arduino Uno form factor, you may want to duplicate an Adafruit Metro board. If it uses the Feather or QT Py form factors, we have a number of Feather-compatible boards to select from.

As an example, this guide will illustrate the process of adding the Adafruit Feather ESP32-S3 to WipperSnapper. Using the questions above, you can identify two things about this board:

  • The microcontroller used is the ESP32-S3 by Espressif. 
  • The form factor for this board is the Adafruit Feather form factor.

While the Wippersnapper_Boards/boards directory does not (at the time of writing) contain an ESP32-S3 board, there are a number of Feather boards including one using the Espressif ESP32-S2 (an older version of the ESP32-S3).

Select the folder for a board within Wippersnapper_Boards/boards that is closest to your board and make a copy of it.

Rename this folder to the name of your development board. We suggest using the following naming convention for the folder: vendor-product-chip

  • For example, the Adafruit Feather ESP32-S2 folder would be named adafruit-feather-esp32s3

Add Board Image

Next, you'll need to add an image of your board. For Adafruit boards, it's preferred to use a vectorized illustration of the board from the Adafruit Fritzing Library. If you do not have an illustration of the board, you will want to take an image from the manufacturer's website.

Next, make sure your image adheres to the following specifications: 

  • The image file's extension can be any one of: JPG, JPEG, GIF, PNG, SVG
  • The image file's size must be at least 3kb and must not exceed 100kb

With the photo added, the new Wippersnapper_Boards/boards/adafruit-feather-esp32s3 directory should look like the following:

(Optional) Add Board Installation Photos

Installing WipperSnapper on a board for the first time involves using the web-based installation processes on Adafruit IO, shown below.

To have your board appear in the steps of the web-based installer, you'll need to first add a new directory in boards/BOARD_NAME/images.

Next, you'll want to fill this directory with the following image files (note - the image files can have any image extension):

Optionally, you can add a GIF, boot-loader.gif, which is used to instruct a user on how to enter the UF2 bootloader on the board.

We have examples of all of these images within the WipperSnapper_Boards repository under each Adafruit board: https://github.com/adafruit/Wippersnapper_Boards/tree/main/boards/funhouse/images

Edit Board Definition

Open the definition.json file within the board's directory in a text editor. It should look something like the following.

{
    "boardName":"adafruit-feather-esp32s2",
    "mcuName":"esp32s2",
    "mcuRefVoltage":2.6,
    "VID":"0x239A",
    "PID":"0x80EB",
    "displayName":"Adafruit ESP32-S2 Feather",
    "vendor":"Adafruit",
    "productPageURL":"https://www.adafruit.com/product/5000",
    "documentationURL":"https://learn.adafruit.com/",
    "components":{
       "digitalPins":[
          {
             "name":"D1",
             "displayName":"D1",
             "dataType":"bool"
          },
          ...
          {
             "name":"D14",
             "displayName":"D14",
             "dataType":"bool"
          }
       ],
       "analogPins":[
          {
             "name":"A18",
             "displayName":"A0",
             "dataType":"int16"
          },
          ...
          {
             "name":"A8",
             "displayName":"A5",
             "dataType":"int16"
          }
       ],
       "i2cPorts":[
          {
             "i2cPortId":0,
             "SDA":3,
             "SCL":4
          }
       ]
    }
 }

Editing the Board's Metadata

The first section of the definition.json file to fill out contains information related to the development board including the hardware's name, description, chipset, and other unique identifiers.

Change boardName

The boardName field is the board's identifier when it logs into Adafruit IO. This field should be the same as the folder name. For the Feather ESP32-S3, it would be changed to:

"boardName":"adafruit-feather-esp32s3"

Change mcuName

The mcuName field contains an identifier for the type of microcontroller used on the board. For example, the microcontroller used by the Adafruit Feather ESP32-S3 is the ESP32-S3, the field would look like the following:

"mcuName":"esp32s3"

If you are unsure about what to enter in this field, reach out to the vendor you bought your hardware from.

Change the mcuRefVoltage

The mcuRefVoltage field sets the reference voltage of the microcontroller's ADC. This value is found within the microcontroller's datasheet. The ESP32-S3's reference voltage is 2.6V, so we'll set mcuRefVoltage field to be 2.6.

"mcuRefVoltage":2.6

Add Product Information

The next few fields in the JSON file deal with descriptive product information about the board being adding. This information will be visible on the Adafruit IO WipperSnapper website under the board's image.

The displayName is the full name of the board. This is how the board's name will be displayed on the Adafruit IO WipperSnapper website. You can also put extra information in the string about hardware configuration.

"displayName":"Adafruit Feather ESP32-S3 No PSRAM"

The vendor field is the name of the board's manufacturer (not the chip's manufacturer). Since this page is using an Adafruit board, the vendor is Adafruit.

"vendor":"Adafruit"

The productPageURL and documentationURL are two fields which contain the URLs for the hardware's product page (where someone would purchase the hardware) and the documentation page (where someone would go for extra information about the hardware)

"productPageURL":"https://www.adafruit.com/product/5000", "documentationURL":"https://learn.adafruit.com/"

Adding ESPTool Information for Boards without Native USB

If you are not adding a WipperSnapper board that contains an ESP8266, ESP32, or ESP32-C3 chip - Skip this step.

Boards that use the ESP8266, ESP32, or ESP32-C3 do not contain Native USB and WipperSnapper can not be installed using a .UF2 file. Instead, for these boards, WipperSnapper presents a web-based firmware uploader to the user. 

If you are adding an ESP32/ESP8266 board, you will need to add an esptool array to tell WipperSnapper that your board uses the web uploader workflow.

An example of the esptool array is as follows.

"esptool": {
      "fileSystemSize": 94208,
      "blockSize": 4096,
      "offset": "0x290000",
      "structure": {
          "0xe000": "wippersnapper.feather_esp32.littlefs.VERSION.boot_app0.bin",
          "0x1000": "wippersnapper.feather_esp32.littlefs.VERSION.bootloader.bin",
          "0x10000": "wippersnapper.feather_esp32.littlefs.VERSION.bin",
          "0x8000": "wippersnapper.feather_esp32.littlefs.VERSION.partitions.bin"
        }

The esptool array contains the following parameters which differ between chipsets (ESP32, ESP8266, ESP32-C3) but not between boards: 

  • fileSystemSize - The size of the chip's filesystem in bytes
  • blockSize - The size of the logical block size used by the filesystem in bytes
  • offset - The flash offset at which the firmware binaries will be flashed
  • structure - An array containing the 4 binary files produced by the Arduino compiler when WipperSnapper is compiled
    • While these entries vary between chips (ESP8266 v.s. ESP32) but not between boards, the board name must be changed (i.e: wippersnapper.feather_esp32.littlefs.VERSION.boot_app0.bin).

We have an example of the esptool array for the ESP8266 here.

We have an example of the esptool array for the ESP32 here.

Component Array

The next chunk of text in the definition.json file is a large array called components. This array contains a map of the board's pins, buses, and capabilities.

Note - While chips like the ESP32-S3 have lots of pins, not all of them are easily accessible or "brought out" to physical pins on the microcontroller. Since WipperSnapper is a beginners-first platform, Adafruit only maps the usable pins to this file, which are visible on the board's silkscreen.

Add Digital Pins

These are the digital input and digital output pins used to connect your board to digital components like push buttons, digital sensors, LEDs, and more.

These pins are stored within the digitalPins array. Since you started with an existing JSON file, delete all the existing items in the list except for the first item. Your list should look like the following:

"components":{
      "digitalPins":[
        {
          "name":"D1",
          "displayName":"D1",
          "dataType":"bool"
        }
      ]...

Each entry within the digitalPins array contains the following information:

  • name - The physical location of the pin (i.e: How you'd access this pin in the Arduino IDE). This string will be sent from Adafruit IO to the development board.
  • displayName - The "pretty name" for the pin. This string will be used by the component picker on Adafruit IO and shown to users. You can find this value by looking at the labels on the board's silkscreen.
  • dataType - What type of data is being sent to Adafruit IO by this pin. You're working with digital pins only right now, so the dataType is a boolean.

The Adafruit Feather ESP32-S3 has a LED built into the board on Digital Pin 13. As an example, let's add it to the digitalPins array above. Note that the displayName string contains both the pin's logical number on the board and information that it's a LED.

"components":{
      "digitalPins":[
        {
          "name":"D1",
          "displayName":"D1",
          "dataType":"bool"
        },
        {
            "name":"D13",
            "displayName":"Red LED (D13)",
            "dataType":"bool"
        }
      ],
      ...

For a full example of how the Adafruit Feather ESP32-S3's digital pins are configured, check out the definition.json file on GitHub here.

(Optional) Add Analog Pins

Next, let's add the board's analog pins. These pins are used for reading analog values from sensors. At this time, WipperSnapper does not support Analog Output, it only supports reading from analog pins.

Since you started with an existing JSON file, delete all the existing items in the analogPins list except for the first item. Your list should look like the following:

"analogPins":[
        {
          "name":"A18",
          "displayName":"A0",
          "dataType":"int16"
        },
        ...
      ],
      ...

Each entry within the analogPins array contains the following information:

  • name - The physical location of the pin (i.e: How you'd access this pin in the Arduino IDE). This string will be sent from Adafruit IO to the development board.
  • displayName - The "pretty name" for the pin. This string will be used by the component picker on Adafruit IO and shown to users. You can find this value by looking at the labels on the board's silkscreen.
  • dataType - What type of data is being sent to Adafruit IO by this pin. Analog pins int16 values to Adafruit IO. This value should be sent by an analog pin.

Note that for the Adafruit Feather ESP32-S3, analog pin "A0" on the silkscreen is internally referenced as A18.  This value can be found in two locations. First, check the board's pinout page provided by the vendor.

If it was not referenced by the vendor, or you're still having trouble finding it - locate the Arduino Board Support Package (BSP/"Arduino Core") for your development board. In the case of this example, the Feather ESP32-S3 uses the Espressif ESP32 Arduino Core. The pin map is found within the board support package's variants/your-board-name folder. For example, the Adafruit Feather ESP32-S3 pin mapping for the Arduino IDE is located at https://github.com/espressif/arduino-esp32/blob/master/variants/adafruit_feather_esp32s3_nopsram/pins_arduino.h

For a full example of how the Adafruit Feather ESP32-S3's analog pins are configured, check out the definition.json file on GitHub here.

(Optional) Add I2C Port

A large number of sensors can connect over the 2-wire I2C 'bus' protocol. The i2cPorts array contains three values:

  • i2cPortId - The I2C port, defaults to 0.
    • NOTE: While some development boards may have more than 1 I2C port, WipperSnapper only supports one I2C port at this time.
  • SDA - The I2C clock pin
  • SCL - The I2C data pin
"i2cPorts":[
        {
          "i2cPortId":0,
          "SDA":3,
          "SCL":4
        }
      ]
   ...

Create a Pull Request on WipperSnapper_Boards

First, let's push the changes you made to the build script within your CI-Arduino fork.

In a terminal window, navigate to the location of Wippersnapper_Boards on your computer.

Use the git branch command to create a new branch. The branch should contain the name of the board you're adding. As an example, we named our branch add-esp32-s3-feather.

Next, use the git status command to verify that only the folder for your development board has been added.

Add the files by running git add .

Finally, verify that the definition JSON file and image have been added by running git status one last time.

Use git commit to commit your changes and git push to push the changes to your fork.

Use GitHub to create a pull request (PR) to the WipperSnapper_Boards repository with your changes.

The repository will run checks on these files. If the checks pass, Adafruit will review the files and merge the board definition into WipperSnapper.

For reference, an example of the pull request for this guide is here >>>

Next, you'll need to add code to the WipperSnapper firmware to detect your board.

The easiest way to build WipperSnapper firmware on your computer is by using a combination of Microsoft Visual Studio Code (VSCode) and PlatformIO

Navigate to https://code.visualstudio.com and install the latest version of the VSCode editor. 

Once downloaded and installed, open VSCode and navigate to the Extensions tab (If you do not have this tab, you can find it using the toolbar by navigating to Settings->Extensions).

Search for the PlatformIO extension.

Select the PlatformIO extension and click Install.

Fork WipperSnapper Firmware

To contribute to WipperSnapper, you will need to create a copy of the WipperSnapper project's repository. This copy is called a fork and you will use it to make changes to WipperSnapper before submitting them to the official project repository.

Sign in to your Github.com account and navigate to the WipperSnapper firmware repository.

Click the "Fork" button to fork your own copy of the adafruit/Adafruit_Wippersnapper_Arduino repository.

Click "Create Fork" and wait a few seconds for GitHub to create a copy of the WipperSnapper repository on your account.

Clone WipperSnapper Firmware

Next, let's clone your fork of the Wippersnapper firmware so we can download it, make changes locally, compile it, and eventually send your changes up to the official repository.

On the page for your forked repository, click the green Code button. The dropdown should present a link like the one below:

https://github.com/brentru/Adafruit_Wippersnapper_Arduino.git

Copy the link to your clipboard.

Using a terminal program, enter the following command to clone the forked repository to your computer. Be sure to replace youruserid with your GitHub user ID, and paste the URL from your clipboard. 

git clone -o youruserid https://your-fork-URL

Now that the WipperSnapper firmware is local on your computer, check out a new branch and move on to the new step - building WipperSnapper.

If you are unfamiliar with how to check out a new branch, Kattni wrote a great overview of the process here...

Open WipperSnapper Firmware in PlatformIO

Open Visual Studio Code and click Open to bring up the file explorer.

Navigate to the Folder containing your local copy of Adafruit_Wippersnapper_Arduino and click Open.  

VSCode should open to WipperSnapper's platformio.ini file. A notification on the bottom-right of your VSCode instance shows a message that PlatformIO is configuring the project and installing the required libraries to build WipperSnapper.

When the libraries finish installing, you should see a notification (or terminal output) that the "Project has been successfully updated!".

Click the PlatformIO logo (it looks like an alien's head) on the left-hand side of the VSCode editor to open PlatformIO.

Under PlatformIO's Project Tasks tab, every board WipperSnapper supports is listed as a folder.

Select the board you'd like to build for. For example, I have an Adafruit Feather ESP32 v2 and I will select the featheresp32v2 board from the dropdown.

When PlatformIO is loading tasks for a new environment, a blue clock appears on top of the logo. Wait until the blue clock disappears before continuing the build process.

When PlatformIO loads the featheresp32v2 environment, you should see a Build step underneath featheresp32v2->General->Build. 

Click Build and PlatformIO should begin to build WipperSnapper firmware for the Feather ESP32 V2.

Once WipperSnapper builds successfully, the terminal will show SUCCESS along with the time it took to build.

Congrats- you've successfully built WipperSnapper locally! 

Upload Locally-Built WipperSnapper Firmware

To upload and test WipperSnapper on your device, you will need to specify the upload_port belonging to your device.

Within VSCode, open the platformio.ini file and navigate to the board you are using. Using this guide as an example, we previously compiled for the Adafruit Feather ESP32 V2. The build environment looks like the following.

Next, add the upload_port for your board. This port name varies but will take the form of:

  • /dev/ttyUSB0 - Serial port (Unix-based OS)

  • COM3 - Serial port (Windows OS)

On the VSCode sidebar, click the PlatformIO logo.

Under Project Tasks-> Your Board (for this example, the board is featheresp32v2), click Upload to upload WipperSnapper firmware to your development board.

After the PlatformIO upload succeeds, press the RESET button on your board and navigate to https://io.adafruit.com/devices

If the upload was successful, you should see your board connected to Adafruit IO!

When a board running Wippersnapper "checks in" to Adafruit.io, it sends information about itself to Adafruit IO. Then, if the firmware supports the board, Adafruit IO recognizes the board and associates it with the board definition.

The next step in this process is to add two files within WipperSnapper firmware in order for the firmware to associate itself with a board type.

Add Code to Detect Your Board

Open your fork of Adafruit_WipperSnapper_Arduino within Visual Studio Code and navigate to the file Adafruit_Wippersnapper_Arduino/src/Wippersnapper_Boards.h. This file is used for detecting which type of development board is being used with WipperSnapper at compile-time.

Add a new conditional case at the end of the WipperSnapper_Boards.h file. This case is used by the Arduino compiler to detect which board it's 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: ARDUINO_ADAFRUIT_FEATHER_ESP32S3:

...
#elif defined(ARDUINO_ADAFRUIT_FEATHER_ESP32S3)
// TO-DO: Add more here!
...

Add theBOARD_ID, a required string identifying the board. This is the same as the boardName entry in the board definition JSON file.

#elif defined(ARDUINO_ADAFRUIT_FEATHER_ESP32S3)
#define BOARD_ID "feather-esp32s3"
...

Boards are provisioned with a secrets.json credentials file in two ways:

If the board supports native USB and has a UF2 bootloader, we #define USE_TINYUSB to make the board appear as a USB Drive.

If the board does not support native USB, we tell the firmware that it was installed using the web-based installer by using #define USE_LITTLEFS

The Feather ESP32-S3 has a native USB and a UF2 bootloader. 

#elif defined(ARDUINO_ADAFRUIT_FEATHER_ESP32S3)
#define BOARD_ID "feather-esp32s3"
#define USE_TINYUSB
...

WipperSnapper firmware requires a status pixel on a board. This status pixel is used to display connectivity status or notify a user of an error.

Depending on what type of status pixel your board has (NeoPixel, DotStar, or a LED), you'll need to #define the following:

    • 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.

The Feather ESP32-S3 uses a NeoPixel as the status pixel.

#elif defined(ARDUINO_ADAFRUIT_FEATHER_ESP32S3)
#define BOARD_ID "feather-esp32s3-4mbflash-2mbpsram"
#define USE_TINYUSB
#define USE_STATUS_NEOPIXEL
#define STATUS_NEOPIXEL_PIN PIN_NEOPIXEL
#define STATUS_NEOPIXEL_NUM NEOPIXEL_NUM
...

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 step is for boards using the TinyUSB provisioning workflow. Open the file src/provisioning/tinyusb/Wippersnapper_FS.cpp and add the build string you located above (ex: ARDUINO_ADAFRUIT_FEATHER_ESP32S3_NOPSRAM) to the top of the file:

#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's platform is 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.

#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 Board to Platformio.ini File

The platformio.ini build environment file needs to be updated with the board we're adding. This build environment file supports three platforms: ESP32, ESP8266, and ATMEL SAM.

Navigate to the PlatformIO board listing for your board's platform:

On the board listing, locate your board:

On the board's page, scroll down to the "Configuration" header. The board option's name should be listed here along with the board name.

Copy the environment name and add it to the platformio.ini file:

Within the platformio.ini file, add the board name:

; Adafruit Feather ESP32-S3 2MB PSRAM
[env:adafruit_feather_esp32s3]
...

To reduce the amount of code in this file, we have common build environments for ESP32-X, ESP8266, and SAMD.

The ESP32-S3 uses the ESP32 build environment: 

; Adafruit Feather ESP32-S3 2MB PSRAM
[env:adafruit_feather_esp32s3]
extends = common:esp32

Add the board name (this is from the configuration page):

; Adafruit Feather ESP32-S3 2MB PSRAM
[env:adafruit_feather_esp32s3]
extends = common:esp32
board = adafruit_feather_esp32s3

Add a build flag for the compiler to identify this board. The build flag should be identical to the #elif defined(board_identifier_for_compiler) string you added earlier in src/WipperSnapper_Boards.h:

; Adafruit Feather ESP32-S3 2MB PSRAM
[env:adafruit_feather_esp32s3]
extends = common:esp32
board = adafruit_feather_esp32s3
build_flags = -DARDUINO_ADAFRUIT_FEATHER_ESP32S3
The following step is only for boards using Native USB/Tiny USB. You may skip it if you are using the web-based uploader.

If your board uses the TinyUSB workflow, add the following line:

; Adafruit Feather ESP32-S3 2MB PSRAM
[env:adafruit_feather_esp32s3]
extends = common:esp32
board = adafruit_feather_esp32s3
build_flags = -DARDUINO_ADAFRUIT_FEATHER_ESP32S3
extra_scripts = pre:rename_usb_config.py

Build WipperSnapper Firmware with Platform IO

Click the PlatformIO logo on the Visual Studio Code sidebar to open Platform IO. 

Under Project Tasks, click Refresh to refresh the project's tasks. 

After refreshing, you should see the board you just added.

If you do not see your build environment appear, click the toggle button to toggle between the multi-environment project tasks.

Within your board's folder, click General->Build to start the build process. 

Once WipperSnapper is done building, it'll show SUCCESS at the bottom of your screen.

Upload WipperSnapper Firmware to Board

Upload the modified WipperSnapper firmware to your board by navigating to PlatformIO and clicking Upload.

After uploading, from the PlatformIO tab, click Monitor. A new serial monitor should open. You should see the following debug output stating WipperSnapper is running.

Add Credentials/Secrets File to 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:

This step is ONLY for boards without native USB using the web-based workflow such as ESP32, ESP8266, ESP32-C3

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.

This step is ONLY for boards using the TinyUSB-based workflow such as ESP32-S2, ESP32-S3, SAMD51

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, press the board's RESET button. Navigate to adafruit.io and let the board connect.

You should see a pop-up with the text "New Device Detected!" appear along with a picture of the board.

Your board now works with WipperSnapper! Next, create a pull request for adding the board to the WipperSnapper firmware so everyone can use it!

Now that the library files and build script have been updated, it's time to open two pull requests: one on Adafruit_Wippersnapper_Arduino and one on the CI-Arduino repository.

Submit a Pull Request to CI-Arduino

First, let's push the changes you made to the build script within your CI-Arduino fork.

In a terminal window, navigate to ci-arduino's location on your computer.

Use the git branch command to create a new branch. The branch should contain the name of the board you're adding. As an example, name the branch add-esp32-s3-feather.

Next, use the git status command to verify that only the build_platform.py file has been modified.

Add the build_platform.py file by running git add build_platform.py.

Finally, verify that build_platform.py has been added by running git status one last time.

Use git commit to commit your changes and git push to push the changes to your fork.

Use GitHub to create a pull request (PR) to the CI-Arduino repository with your changes.

Submit a Pull Request to WipperSnapper Arduino Library

Next, to push the changes you made to the build script within your fork of the WipperSnapper Arduino Library.

First, verify that you have modified only the following files:

  • The board detection file
    • src/Wippersnapper_Boards.h
  • And one of the provisioning method files:
    • src/provisioning/tinyusb/Wippersnapper_FS.cpp
    • or
    • src/provisioning/littlefs/WipperSnapper_LittleFS.cpp

Next, in a terminal window, navigate the location of Adafruit_WipperSnapper_Arduino on your computer.

Use the git branch command to create a new branch. The branch should contain the name of the board you're adding. As an example, this branch is named add-esp32-s3-feather.

Next, use the git status command to verify that only the files listed above have been modified.

Add the files by running git add .

Finally, verify that your files have been added by running git status one last time.

Now commit your changes, and push your branch to your fork. Use GitHub to create a pull request to the WipperSnapper Arduino library with your changes.

What's next?

Once your pull requests are created, it's now up to Adafruit! We'll take a look at it and make sure everything is in order before merging your changes into WipperSnapper Arduino. If anything was missed, we'll let you know so you can get it taken care of. Once the changes in both repositories are merged, your board is officially part of WipperSnapper.

The next time WipperSnapper is released, all the boards that have been added to the repository will be included in the release. That includes your board! Firmware builds are available on the latest release on GitHub. The web-based WipperSnapper firmware uploader will also populate with the latest firmware and supported boards on a new release.

This guide was first published on May 04, 2022. It was last updated on Mar 31, 2024.