Frequently Asked Questions About Pocketbyte Development

What ESP-IDF version is required?

Pocketbyte requires ESP-IDF v5.0 or newer. We recommend using ESP-IDF v5.2 or later for the best stability and access to the latest ESP32-S3 features and bug fixes.You can check your installed version by running:

idf.py --version

Older ESP-IDF 4.x releases are not supported — the Pocketbyte SDK relies on component manager features and APIs introduced in v5.0.To install or update ESP-IDF, follow the official ESP-IDF Getting Started guide for your operating system.

Can I write games in C++ instead of C?

Yes. ESP-IDF supports C++ natively, and the Pocketbyte libraryK headers are fully compatible with C++ projects. You can rename your source files to .cpp and use C++ features including classes, templates, and the standard library.To register a C++ source file with the build system, list it in your main/CMakeLists.txt:

idf_component_register(
    SRCS "main.cpp" "game.cpp"
    INCLUDE_DIRS "."
)

If you mix C and C++ sources, ensure you add extern "C" to app_main() like this:\

extern "C" void app_main(void) {}

The library’s own headers already include these guards, so in most cases you can include them directly.

How much flash storage does Pocketbyte have?

The ESP32-S3 on Pocketbyte comes with 16 MB of on-chip flash storage.The default ESP-IDF partition table reserves space for the bootloader, NVS (non-volatile storage), and a single factory app partition. If you want to store game assets such as sprites, audio samples, or level data, you need to add a dedicated SPIFFS partition by providing a custom partitions.csv file.At build time, run idf.py size to see the current size of your compiled binary and make sure it fits within the app partition you have allocated.

Can I use Wi-Fi or Bluetooth in my app?

Yes. The ESP32-S3 includes a 2.4 GHz radio that supports both Wi-Fi (802.11 b/g/n) and Bluetooth (Classic and BLE). It is also compatible with ESP-NOW. You can use standard ESP-IDF networking and Bluetooth APIs alongside the Pocketbyte library in the same application.For example, you can use ESP-IDF’s esp_wifi component to connect to a network for leaderboard submissions, over-the-air (OTA) firmware updates, or multiplayer, and use the Pocketbyte library for display, input, and audio at the same time.Be aware that the radio increases current draw. If you are running on battery, manage the radio aggressively — enable and disable it only when needed — to extend play time.

How do I update the Pocketbyte library component?

Run the following command in your project directory:

idf.py update-dependencies

This instructs the component manager to check for newer versions of all dependencies that match the constraints in your idf_component.yml and download them into managed_components/.If you want to allow the library to update to a newer major or minor release, adjust the version constraint in main/idf_component.yml before running the command:

dependencies:
  omrawaley/pocketbyte: ">=0.4.0"
  idf: ">=5.0.0"

After updating, rebuild your project with idf.py build and test thoroughly — new library versions may introduce API changes that require updates to your code.

Is there a community or forum for Pocketbyte developers?

Visit pocketbyte.co for links to community channels where you can ask questions, share projects, and connect with other Pocketbyte developers.For bug reports, feature requests, and library issues, open an issue on the GitHub repository. When filing a bug report, include your ESP-IDF version, the library version from your idf_component.yml, a minimal code sample that reproduces the issue, and the serial monitor output.

Can I run emulators on Pocketbyte?

Yes. The ESP32-S3 is more than capable of running emulators for retro platforms, and Pocketbyte was designed with this use case in mind. It can easily run SNES and everything below, plus PC ports like Duke3D, Doom, and Quake. Many PICO-8 games, like Celeste, can also be emulated.Retro-Go is a fantastic emulation firmware that has already been ported to Pocketbyte.

What happens to my app during a device reset?

When Pocketbyte resets — whether from a power cycle, the RESET button, a watchdog timeout, or a crash — the ESP32-S3 restarts its bootloader and launches your app from the beginning of app_main. All in-memory state (variables, buffers, game state) is lost.To preserve state across resets, use the NVS (Non-Volatile Storage) API provided by ESP-IDF:

#include "nvs_flash.h"
#include "nvs.h"

// Initialise NVS
nvs_flash_init();

// Open a namespace and write a value
nvs_handle_t handle;
nvs_open("game_state", NVS_READWRITE, &handle);
nvs_set_u32(handle, "high_score", current_high_score);
nvs_commit(handle);
nvs_close(handle);

NVS data survives resets and power cycles. It is erased only if you explicitly erase it or flash a new partition table that overwrites the NVS partition.

Get Started

Packaging Apps

Misc

Help

Frequently Asked Questions About Pocketbyte Development