WT9932S31-TINY Development Guide
Update history
| Date | Version | Author | Update content |
|---|---|---|---|
| 2026-11-05 | 1.0.0 | Iris | Initial document creation |
1. Development Approach
WT_BSP is the board support package maintained by Wireless-Tag for ESP32 development boards. When developing for WT9932S31-TINY, build application logic on WT_BSP instead of hard-coding GPIOs, display initialization parameters, camera pins, or SD card pins in application code.
All board selection, USB connections, and peripheral entry points in this guide are adapted for WT9932S31-TINY. The S31 camera interface is DVP.
The core workflow for development with WT_BSP is:
- Include the BSP component through
components/wt_bspin the application project. - Select
WT9932S31-TINYwithidf.py set-board. - Call
wt_bsp_init()to initialize board resources. - Obtain resource handles through
wt_bsp_get_rgb(),wt_bsp_get_button(),wt_bsp_get_sdmmc(),wt_bsp_get_dsi(),wt_bsp_get_csi(), andwt_bsp_get_touch(). - Check each return value to determine whether the feature is available, then implement the required application logic.
This approach provides several benefits:
- Application code is not tied to specific hardware pins.
- The same example can be adapted to multiple Wireless-Tag boards with less effort.
- Peripheral features can be removed through
menuconfig. - Board differences are maintained centrally in
components/wt_bsp/boards/WT9932S31-TINY.
2. Obtain and Update WT_BSP
The official WT_BSP repository is:
The repository is actively updated. Clone it from the official repository the first time. If it is already installed, synchronize the main branch before starting a new project or troubleshooting so that you use the latest board support, examples, and tools.
2.1 Requirements
Prepare the following before starting:
- Git.
- ESP-IDF v6.1 or later; this guide was verified against the v6.1 release.
- An activated ESP-IDF command-line environment.
- A USB Type-C cable that supports data transfer; two cables are recommended when verifying HUSB applications.
- The corresponding accessories for SD card or camera examples.
ESP-IDF v6.1 lists esp32s31 as a preview target. Therefore, this guide uses --preview for board selection, builds, configuration, and flashing. Preview refers to the S31 target support status; the v6.1 SDK itself is still a production release.
2.2 Clone the Repository
Choose a directory for development projects and clone the official repository:
mkdir -p ~/work
cd ~/work
git clone https://github.com/Wireless-TAG-Maker/WT_BSP.git
cd WT_BSP
The repository currently does not require --recursive to obtain submodules. After cloning, check the current branch and latest commit:
git status --short --branch
git log -1 --oneline
Normally, the repository should be on the main branch. The examples below assume the repository is located at:
~/work/WT_BSP
You may use another directory in practice; replace the paths in the commands with your actual path.
2.3 Update an Existing Repository
If WT_BSP already exists locally, enter the repository and check for uncommitted changes:
cd ~/work/WT_BSP
git status --short --branch
If the working tree is clean, switch to main and synchronize using fast-forward only:
git switch main
git pull --ff-only origin main
Confirm the current revision after updating:
git log -1 --oneline
If git status shows local changes, commit them to your development branch or temporarily store them with git stash before updating main. Do not delete local work merely to update the repository.
Recommendation: keep custom applications outside the WT_BSP repository or in a separate Git branch. This reduces conflicts when synchronizing the official
mainbranch. Teams should also record the verified WT_BSP commit so that other developers can reproduce the same build environment.
2.4 Verify with blink
After each WT_BSP update, build the minimal blink example first to confirm that ESP-IDF, the BSP, and the board-selection tool work correctly:
cd ~/work/WT_BSP/examples/get-started/blink
idf.py set-board
idf.py build
Select WT9932S31-TINY from the interactive list. For a non-interactive build, run:
WT_BSP_BOARD=WT9932S31-TINY idf.py set-board
idf.py build
set-board generates the board presets used by the current project. When switching to a board with a different target chip, the tool automatically runs fullclean.
3. WT_BSP Directory Structure
All paths below are relative to the root of the WT_BSP repository.
| Path | Purpose |
|---|---|
components/wt_bsp |
BSP core component |
components/wt_bsp/include/wt_bsp.h |
Top-level public API |
components/wt_bsp/src |
Common BSP implementation |
components/wt_bsp/features |
Reusable features such as RGB, Button, SDMMC, USB CDC, and Camera |
components/wt_bsp/boards/WT9932S31-TINY |
S31 board pins, resource lifecycle, and DVP/UVC support |
components/wt_bsp/tools |
set-board and CMake helper scripts |
examples/get-started/blink |
Minimal RGB example |
examples/get-started/button |
Button event example |
examples/storage/sdmmc |
SD card mount, file I/O, and rename example |
examples/usb/device_cdc |
HUSB CDC byte-echo example |
examples/camera/usb_device_uvc |
DVP camera to HUSB UVC example |
examples/wt_factory/wt9932s31-tiny |
Combined camera, SD, RGB, SW2, and UVC+CDC example |
Application developers normally need to focus only on:
examples/: read the example and itsREADME.mdthat most closely match the requirement before copying or referencing its code.components/wt_bsp/include/wt_bsp.h: review the top-level BSP API.components/wt_bsp/features/*/include/: review the APIs for individual peripheral features.
Application code should not directly include:
#include "boards/WT9932S31-TINY/board.h"
#include "board_config.h"
These files are internal board-support implementation details. Applications should use the unified interfaces in wt_bsp.h.
4. Create an Application Project
4.1 Choose a Starting Point
| Development requirement | Recommended example |
|---|---|
| Verify the environment or set an RGB status indicator | examples/get-started/blink |
| Respond to BOOT/SW2 input | examples/get-started/button |
| MicroSD storage | examples/storage/sdmmc |
| Custom serial protocol between a computer and S31 | examples/usb/device_cdc |
| Use a DVP camera as a computer camera | examples/camera/usb_device_uvc |
| Combined camera, storage, and USB application | examples/wt_factory/wt9932s31-tiny |
Read the selected example's README.md first to confirm the hardware connection and build steps, then use that example as the development baseline.
4.2 Copy a Minimal Application from blink
For a first custom application, start from blink because it has the smallest structure and clearest dependencies.
get_idf
cd ~/work/WT_BSP/examples
mkdir -p my_apps
cp -r get-started/blink my_apps/my_s31_app
cd my_apps/my_s31_app
Remove old build output after copying:
rm -rf build managed_components sdkconfig sdkconfig.old
Keep or modify the following files:
| File | Action | Description |
|---|---|---|
CMakeLists.txt |
Keep | Already includes the WT_BSP CMake helper |
main/CMakeLists.txt |
Keep | Registers application sources |
main/main.c |
Modify | Replace with application logic |
sdkconfig.defaults |
Keep or modify | Project default configuration |
sdkconfig.wt9932s31_tiny |
Keep | Board preset read by set-board |
README.md / README_CN.md |
Modify | Replace with the application's documentation |
Select the board and build:
WT_BSP_BOARD=WT9932S31-TINY idf.py set-board
idf.py build
4.3 Required CMake Configuration
The project's top-level CMakeLists.txt must add the WT_BSP components directory to ESP-IDF and call the WT_BSP board-default configuration function.
For a project under WT_BSP/examples/..., use:
cmake_minimum_required(VERSION 3.16)
set(EXTRA_COMPONENT_DIRS "../../../components")
include("../../../components/wt_bsp/tools/wt_bsp_project.cmake")
wt_bsp_apply_sdkconfig_defaults()
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(my_s31_app)
If the project is outside the WT_BSP repository, for example:
~/work/my_s31_app
and WT_BSP is located at:
~/work/WT_BSP
use:
cmake_minimum_required(VERSION 3.16)
set(WT_BSP_PATH "$ENV{HOME}/work/WT_BSP")
set(EXTRA_COMPONENT_DIRS "${WT_BSP_PATH}/components")
include("${WT_BSP_PATH}/components/wt_bsp/tools/wt_bsp_project.cmake")
wt_bsp_apply_sdkconfig_defaults()
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(my_s31_app)
main/CMakeLists.txt can normally remain simple:
idf_component_register(SRC_DIRS "."
INCLUDE_DIRS ".")
Add additional source directories to SRC_DIRS or SRCS if the application is split across more directories.
4.4 Add the Board Preset File
idf.py set-board searches the current project for the selected board's preset file. For WT9932S31-TINY, the filename is:
sdkconfig.wt9932s31_tiny
The minimal content is:
CONFIG_WT_BSP_BOARD_WT9932S31_TINY=y
Real projects may also include board-related defaults for the partition table, PSRAM, LVGL, display, or camera. Copy the file with the same name from an official example and adjust it for the project.
Running:
idf.py set-board
generates:
sdkconfig.board
sdkconfig.board.Kconfig
These files are generated by the tool and should not be edited manually.
5. Basic Application Template
The minimal template below initializes the BSP, lights the RGB LED, and obtains board information.
#include "esp_err.h"
#include "esp_log.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "wt_bsp.h"
static const char *TAG = "my_app";
void app_main(void)
{
esp_err_t ret = wt_bsp_init();
if (ret != ESP_OK) {
ESP_LOGE(TAG, "BSP init failed: %s", esp_err_to_name(ret));
return;
}
wt_bsp_board_t board = wt_bsp_get_board();
if (board) {
ESP_LOGI(TAG, "WT_BSP board initialized");
}
wt_bsp_rgb_t rgb = wt_bsp_get_rgb();
if (rgb) {
wt_bsp_rgb_set_pixel(rgb, 0, (wt_bsp_rgb_color_t){.r = 0, .g = 64, .b = 255});
wt_bsp_rgb_refresh(rgb);
}
while (1) {
vTaskDelay(pdMS_TO_TICKS(1000));
}
}
Key points:
- Call
wt_bsp_init()first. wt_bsp_get_*()may returnNULL; always check the result.- Do not assume every board has a display, camera, touch controller, or SD card.
- Do not use private board pin macros in application code.
6. Select, Build, and Flash
6.1 Select the Board
Interactive selection:
idf.py set-board
Non-interactive selection:
WT_BSP_BOARD=WT9932S31-TINY idf.py set-board
Specify the board directly during a build:
WT_BSP_BOARD=WT9932S31-TINY idf.py build
If the project contains multiple board configuration files, set-board lists the available boards. Selecting WT9932S31-TINY sets the target chip to esp32s31.
6.2 Build
idf.py build
If unusual build errors appear after changing the board, target chip, or low-level settings, clean and rebuild:
idf.py fullclean
idf.py build
6.3 Flash
S31 applications are flashed through FUSB:
idf.py -p /dev/ttyACM0 flash monitor
Exit the monitor with:
Ctrl + ]
6.4 Remove Unused Features with menuconfig
Open the configuration interface:
idf.py menuconfig
Disable unused peripheral features to reduce initialization overhead and dependencies, then rebuild:
idf.py build
Application code must still check each wt_bsp_get_*() return value. A peripheral may be unavailable because the hardware does not support it, it is disabled in configuration, or initialization failed.
7. Common BSP Features
7.1 RGB LED
Use the following sequence:
#if WT_BSP_RGB_ENABLED
wt_bsp_rgb_t rgb = wt_bsp_get_rgb();
if (rgb != NULL) {
ESP_ERROR_CHECK(wt_bsp_rgb_set_pixel(
rgb, 0, (wt_bsp_rgb_color_t){.r = 24, .g = 0, .b = 0}));
ESP_ERROR_CHECK(wt_bsp_rgb_refresh(rgb));
}
#endif
Applications set colors in RGB field order. The BSP configuration handles the WS2812's underlying GRB order, so application code does not need to swap color channels.
7.2 BOOT / SW2 Button
wt_bsp_get_button() returns the default SW2 handle. Current public events include:
WT_BSP_BUTTON_EVENT_PRESS: button pressed.WT_BSP_BUTTON_EVENT_RELEASE: button released.WT_BSP_BUTTON_EVENT_CLICK: complete click.WT_BSP_BUTTON_EVENT_KEEPALIVE: long-press held.
Register a callback with wt_bsp_button_register_event_cb(button, callback, user_data) and check the result. The callback should only notify a task or post to a queue; run time-consuming work in an application task.
examples/get-started/button/main/main.c demonstrates the event flow. To test a normal button event, operate SW2 after the application is running. Holding SW2 during reset affects the boot mode.
7.3 MicroSD / TF
The S31 SDMMC connection uses slot 0 in 4-bit mode:
| Signal | GPIO |
|---|---|
| CLK | 24 |
| CMD | 25 |
| D0, D1, D2, D3 | 20, 21, 22, 23 |
The card slot is powered at 3.3 V, while the current BSP configures the SD pads to use the on-chip LDO1 at 1.8 V. Do not confuse card-slot VCC with the controller signal power domain. GPIO20–25 also cannot be treated as freely reroutable S31 GPIO matrix signals for this connection.
BSP initialization only prepares the resource. The application must mount it explicitly before accessing files:
#if WT_BSP_SDMMC_ENABLED
wt_bsp_sdmmc_t sdmmc = wt_bsp_get_sdmmc();
if (sdmmc != NULL) {
esp_err_t ret = wt_bsp_sdmmc_mount(sdmmc);
if (ret == ESP_OK) {
const char *mount_point = wt_bsp_sdmmc_get_mount_point(sdmmc);
ESP_LOGI("storage", "Mounted at %s", mount_point);
} else {
ESP_LOGE("storage", "Mount failed: %s", esp_err_to_name(ret));
}
}
#endif
examples/storage/sdmmc creates or overwrites /sdcard/hello.txt, deletes any existing foo.txt, and performs rename and read tests. Use a test card; do not run this example on a card containing important files.
The BSP does not automatically format a card when mounting fails. Close files promptly after writing and synchronize important data as required by the application. Stop writes and power off before replacing the card. Do not treat an RGB color as proof that file finalization has completed.
7.4 HUSB USB CDC
The USB CDC example is examples/usb/device_cdc:
cd WT_BSP/examples/usb/device_cdc
idf.py --preview set-board
idf.py --preview build
idf.py --preview -p $flashPort flash
Before building, set the primary log console to FUSB USB Serial/JTAG as described in Section 6.2. Flashing still uses FUSB. After the firmware starts, connect HUSB. The computer should detect the application-provided Wireless-Tag CDC serial port. Enable DTR when opening the port; transmitted bytes are echoed unchanged.
The ports have different roles:
- FUSB: view
usb_device_cdcstartup logs and flash new firmware. - HUSB: send and receive the example's echo data.
The “115200 baud” USB CDC setting is a serial-application setting, not the USB bus transfer rate. Disable “local echo” in the serial utility when verifying echo behavior so local display is not mistaken for data returned by the board.
The application obtains the handle through wt_bsp_get_usb_device_cdc():
wt_bsp_usb_device_cdc_is_mounted()means USB has been configured by the host; it does not require the CDC port to be open.wt_bsp_usb_device_cdc_is_connected()means the host has asserted DTR.wt_bsp_usb_device_cdc_read()reads currently received data.wt_bsp_usb_device_cdc_write()reports the number of bytes actually queued and may perform a short write; retry only the unqueued suffix.
The current hardware has no J1 VBUS-detection line available to this feature. Neither software state can be used as direct physical disconnect detection. If FUSB continues to power the board, unplugging only HUSB may not immediately clear the enumeration state.
The BSP owns the TinyUSB driver. Applications must not install a second USB stack or free BSP-owned handles.
7.5 DVP Camera and UVC
S31 uses a DVP FPC interface, not MIPI CSI. Disconnect both USB cables before connecting a camera. Verify the 24-pin connector's pin sequence, contact side, cable orientation, and voltage; the same pin count does not guarantee compatibility.
Standalone UVC example:
cd WT_BSP/examples/camera/usb_device_uvc
idf.py --preview set-board
idf.py --preview menuconfig
idf.py --preview build
idf.py --preview -p $flashPort flash
In menuconfig, select the installed camera under WT BSP → Camera sensor:
| Camera | Current standalone UVC configuration | Encoding path |
|---|---|---|
| GC2145 / matching module, default | MJPEG 1600×1200, nominal 8 FPS, Bulk | DVP frames enter the S31 hardware JPEG engine |
| OV3660 | MJPEG 640×480, nominal 25 FPS, Isochronous | Sensor-native JPEG |
These are example configurations, not frame rates measured for this revision. Both sensors use SCCB address 0x3c; select the driver that matches the physical sensor at build time instead of identifying the model from its address alone.
After the firmware starts successfully, connect HUSB to the computer and select Wireless-Tag Camera in UVC-compatible software. FUSB remains connected for logging and flashing.
In this UVC example, wt_bsp_init() manages the camera and USB resources. wt_bsp_get_csi() always returns NULL on S31. Local JPEG capture uses wt_bsp_get_camera(), wt_bsp_camera_prepare(), wt_bsp_camera_capture(), and wt_bsp_camera_get_status(). A frame passed to the capture callback remains valid only for the duration of that callback; do not retain its data pointer afterward.
Local capture may return ESP_ERR_INVALID_STATE when USB owns the capture path. Applications must not concurrently initialize another esp_video, TinyUSB, or camera lifecycle.
Standalone UVC and standalone CDC cannot be combined by simply merging the two examples. For an S31 composite device, refer to the factory example.
8. Develop from the Factory Example
examples/wt_factory/wt9932s31-tiny combines the camera, SDMMC, RGB, SW2, and HUSB UVC+CDC and is a suitable starting point for an integrated application.
8.1 Build and Configure
cd WT_BSP/examples/wt_factory/wt9932s31-tiny
idf.py --preview set-board
idf.py --preview menuconfig
idf.py --preview build
idf.py --preview -p $flashPort flash
- In menuconfig, select GC2145 or OV3660 under
WT BSP → Camera sensor. S31 factory → Enable SD card recordingcontrols SD recording.- Recording is disabled by default. The example still checks the camera and SD card but does not create recording directories or files.
- When recording is enabled, segmented MJPEG AVI files are created. Check card capacity and existing data before use.
- Both cameras use Bulk in the factory example. Do not copy the standalone OV3660 example's Isochronous setting directly into the factory-device configuration.
8.2 FUSB and HUSB Roles
- J2/FUSB: flashing, startup logs, and diagnostic logs.
- J1/HUSB: enumerates as a UVC camera and CDC diagnostic serial port.
- When HUSB is not connected, the example performs offline checks and records if recording is enabled.
- After HUSB enumerates, the example enters USB mode, stops offline recording, and provides UVC and CDC.
- To return from USB mode to offline mode, unplug HUSB, keep FUSB connected for power, and press SW1/EN to reset.
8.3 CDC Diagnostic Commands
The factory CDC protocol differs from the standalone CDC echo example. Open the HUSB serial port, enable DTR, and send an ASCII command terminated by a newline:
| Command | Function |
|---|---|
ping |
Returns pong |
status |
Returns JSON containing the mode, recording configuration, camera and SD status, and other state |
list |
Lists completed recordings that match the naming rules and ends with END |
get rec_000001.avi |
Reads a completed recording with a length header, binary data, and an end marker |
Read each response completely before sending the next command. list/get are limited by USB mode and storage state and are not general-purpose file-access interfaces. FUSB logs are not mixed into the binary file data on HUSB.
8.4 RGB and Buttons
The factory example uses these status colors:
| State | RGB |
|---|---|
| Camera, SD, button registration, and CDC console all normal | Green |
| SD error, camera normal | Red |
| Camera error, SD normal | Blue |
| Camera and SD both in error | Yellow |
| Camera and SD normal, but button callback registration or CDC console failed | White |
| Light manually disabled with SW2 | Off; this does not indicate whether the hardware is healthy |
Each press of SW2 toggles the light. If recording is enabled in offline mode, it also pauses or resumes recording. Reset restores the light to its default on state. A brief red light during startup detection is not, by itself, proof of an SD fault.
These colors are defined by this example and are not universal WT_BSP status meanings. Confirm that recording has ended safely from pause and file-finalization logs, not from the LED color alone.
8.5 Adapt the Example
Proceed in this order:
- Build, flash, and run the unmodified example with the matching configuration.
- Keep
wt_bsp_init()and the board-resource acquisition pattern. - Move camera, SD, and USB business logic into application tasks or a state machine.
- Remove unused recording, diagnostic-command, or UI logic.
- Adjust the partition table, buffers, log levels, and performance parameters last.
- Change only one group of behavior at a time, preserving a version that can be restored and its verification logs.
Old hardware test records in the repository README are historical context only. Revalidate new applications, different sensors, and different hosts.
9. Debugging and Troubleshooting
9.1 Module Logs
Give each application module its own TAG:
static const char *TAG = "my_module";
ESP_LOGI(TAG, "module started");
First confirm the SDK, target chip, Flash, PSRAM, and project name in the startup information, then analyze BSP peripheral logs. Do not mistake output from another example or older firmware for the currently running build.
9.2 Build Directories and Dependencies
A project can use separate build directories:
idf.py --preview -B build_debug build
idf.py --preview -B build_release build
Do not mix different board or sensor configurations in the same build directory. New directories such as build_debug and build_release generate separate SDKCONFIG files. Configure the primary console in each directory or provide it through the project's defaults. Component Manager generates managed_components/ and dependencies.lock; teams should retain the lock file to record verified component versions.
9.3 Fault Isolation
| Symptom | Check first |
|---|---|
| Flashing serial port not found | Confirm J2/FUSB is connected, the cable supports data, and the port has not changed |
| Unsure which of two COM ports to use | FUSB appears as USB Serial/JTAG; HUSB is enumerated by the application. Unplug and reconnect them separately if needed |
| Flashing connection fails | Close software using the port and use BOOT+RESET to enter download mode |
| No HUSB device while running blink | blink disables CDC/UVC; this is expected. Flash the appropriate USB example |
| FUSB flashes but shows no startup log | Confirm the primary console is USB Serial/JTAG and reset after the monitor is ready; blink does not continuously print logs |
| CDC does not echo | Confirm HUSB is connected, select the application COM port, enable DTR, and disable local echo |
esp32s31 target rejected |
Confirm the SDK is at least v6.1 and v6.1 commands include --preview |
| SDKCONFIG does not match the board | Return to the project directory, select the board again, and inspect generated configuration and the build directory |
| Physical Flash is larger than the image configuration | Confirm that the S31 16 MB board defaults are active |
| TinyUSB dependency copy reports “No such file,” or the Windows path is too long | Clone the repository to a short ASCII path such as C:\espwork\WT_BSP and rebuild. Do not reuse managed_components or build from the deep path; no global registry change is required |
| SD mount fails | Check card format, contact, and BSP power-domain configuration |
| Camera detection fails | Check DVP wiring, sensor model, and build configuration; power off before inspecting the ribbon cable |
| UVC works but local capture does not | Check whether USB owns the capture path and whether the local Camera feature is enabled |
| Offline mode does not return after unplugging only HUSB | J1 has no reliable VBUS detection; unplug it and reset as described above |
| Board repeatedly resets | Save the complete FUSB log and distinguish power, panic, watchdog, and application-requested resets |
The computer USB port should supply at least 5V/1A; use a good-quality cable. Power off before connecting a camera, replacing a card, or changing wiring. If both USB cables are connected, disconnect both rather than only one.
10. Development Recommendations
- Access resources through
wt_bsp.hand public feature APIs. - Check every getter for
NULLand handle errors from every importantesp_err_treturn value. - Keep the application buildable when a feature is disabled by guarding its code with BSP feature macros.
- Do not perform time-consuming camera, USB, or storage work in button or USB callbacks.
- Camera callback data is a borrowed frame and must not be referenced after the callback returns.
- For a short USB CDC write, retry only unqueued data rather than resending the entire block.
- Do not interpret HUSB enumeration state as exact physical cable detection.
- Synchronize important writes as required and close them before power-off; validate the write workflow with a test card.
- Record the SDK, BSP commit, lock file, board model, sensor model, configuration, and host port.
- Times, COM ports, MAC addresses, build directories, and individual sample details in logs are not product constants.
11. Recommended Reading Order
- Root
README.md: supported boards and repository workflow. components/wt_bsp/boards/WT9932S31-TINY/README.md: S31 pins and USB/camera boundaries.examples/get-started/blink: board selection, BSP initialization, and RGB.examples/get-started/button: button events.examples/usb/device_cdc: HUSB CDC and FUSB roles.examples/storage/sdmmc: mounting and file operations.examples/camera/usb_device_uvc: S31 DVP/UVC behavior.examples/wt_factory/wt9932s31-tiny: composite USB, camera, and storage.components/wt_bsp/include/wt_bsp.handfeatures/*/include/: public APIs.
Board resources and USB connections were checked against the official board features and a pinned BSP commit.
Official references: