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.
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"
Each new defined(BOARD_DEFINE_NAME) check is separated by the double pipes, ||, meaning OR.
Also each broken line of the big if statement ends with a special continuation character, the backslash \, which is used for each line-break, except the final one at the end of the if statement!
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
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:
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, 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!
Page last edited February 18, 2025
Text editor powered by tinymce.
