WT9932S31-TINY Development Guide

  • WT9932S31-TINY
  • ESP32-S31
  • WT_BSP
  • BSP
  • ESP-IDF
  • FUSB
  • HUSB
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:

  1. Include the BSP component through components/wt_bsp in the application project.
  2. Select WT9932S31-TINY with idf.py set-board.
  3. Call wt_bsp_init() to initialize board resources.
  4. Obtain resource handles through wt_bsp_get_rgb(), wt_bsp_get_button(), wt_bsp_get_sdmmc(), wt_bsp_get_dsi(), wt_bsp_get_csi(), and wt_bsp_get_touch().
  5. 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 main branch. Teams should also record the verified WT_BSP commit so that other developers can reproduce the same build environment.

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 its README.md that 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.

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 return NULL; 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_cdc startup 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 recording controls 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:

  1. Build, flash, and run the unmodified example with the matching configuration.
  2. Keep wt_bsp_init() and the board-resource acquisition pattern.
  3. Move camera, SD, and USB business logic into application tasks or a state machine.
  4. Remove unused recording, diagnostic-command, or UI logic.
  5. Adjust the partition table, buffers, log levels, and performance parameters last.
  6. 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.h and public feature APIs.
  • Check every getter for NULL and handle errors from every important esp_err_t return 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.
  1. Root README.md: supported boards and repository workflow.
  2. components/wt_bsp/boards/WT9932S31-TINY/README.md: S31 pins and USB/camera boundaries.
  3. examples/get-started/blink: board selection, BSP initialization, and RGB.
  4. examples/get-started/button: button events.
  5. examples/usb/device_cdc: HUSB CDC and FUSB roles.
  6. examples/storage/sdmmc: mounting and file operations.
  7. examples/camera/usb_device_uvc: S31 DVP/UVC behavior.
  8. examples/wt_factory/wt9932s31-tiny: composite USB, camera, and storage.
  9. components/wt_bsp/include/wt_bsp.h and features/*/include/: public APIs.

Board resources and USB connections were checked against the official board features and a pinned BSP commit.

Official references: