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 Compatible with WipperSnapper?

Only the following chips are compatible with the Adafruit.io WipperSnapper Library at this time:

  • ESP8266
  • ESP32
  • ESP32-S2
  • ESP32-S3
  • SAMD51 + Adafruit "AirLift" ESP32 Co-Processor

If your development board is based on one of these chips - 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.

Setup Environment

This page assumes you have already installed the Arduino IDE on your computer and have successfully uploaded an Arduino sketch to the development board you're attempting to add to WipperSnapper.

WipperSnapper is distributed as an Arduino Library. This page will take you through the process of installing a fork of the WipperSnapper library on your computer so you can modify its detection code to add a new board.

Find Sketchbook Library Folder

On Linux machines, the folder is named "Sketchbook" and it is typically located in /home/

On Windows and Macintosh machines, the default name of the folder is "Arduino" and is located in your Documents folder.

Once you've located this folder, make a note of its location and continue with the steps below.

Fork and Clone WipperSnapper to the Arduino Sketchbook Library Folder

Create a fork of Adafruit_WipperSnapper_Arduino on your GitHub account.

On your computer, navigate to the Arduino Library Sketchbook Folder and locally clone your fork (Note - this guide uses the adafruit repository for WipperSnapper Arduino in the command below, so change adafruit to your GitHub username).

git clone [email protected]:adafruit/Adafruit_Wippersnapper_Arduino.git

Install Arduino-CLI

Install arduino-cli on your computer by following the step-by-step instructions on this page.

Install CI-Arduino

WipperSnapper utilizes a build script within the Adafruit/CI-Arduino repository, build_platforms.py, to install library dependencies and compile WipperSnapper for a specific platform.

First, create a fork of ci-arduino on your GitHub Account

Then, locally clone your fork to your computer using the command below (Note - we're using the adafruit repository in the command below, so change adafruit to match your GitHub username).

git clone [email protected]:adafruit/ci-arduino.git

Initial Build

Verify that all the steps above work properly by building WipperSnapper for an already-supported development board.

From the Arduino Library Sketchbook folder, navigate to the WipperSnapper folder you created above.

Next, check out the main branch to make sure you're building from the latest code.

# Build using the latest code on the main branch.
git checkout main

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 you're compiling the library for.

This guide uses the Adafruit Feather ESP32-S3 as an example, so you'll attempt to build WipperSnapper using the next closest board - the feather_esp32s2.

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

The script should first install all the required dependencies to build the WipperSnapper library.

Then, it will compile the WipperSnapper_demo.ino sketch for the listed platform.

Once the script completes, it'll give you a location for you to find the compiled binaries.

In this example, these files are located within the directory Adafruit_Wippersnapper_Arduino/examples/Wippersnapper_demo/build/esp32.esp32.adafruit_feather_esp32s2/

Now that you've successfully set up and tested the WipperSnapper build environment, let's make some modifications to WipperSnapper to detect your board.

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:

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.

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

#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)

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

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

#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],

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

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

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

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.

Your board now works with WipperSnapper! Next, you'll create a pull request for adding the board to the WipperSnapper library 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 2022-05-04 10:39:33 -0400.