Skip to main content
This guide walks you through setting up your Pocketbyte development environment, adding the library component, and running your first application on the device in a few steps.

​
Prerequisites

Before you begin, make sure you have the following:
  • A Pocketbyte DevKit
  • A USB-C cable
  • A Windows, macOS, or Linux computer

​
Steps

1

Install ESP-IDF

If you haven’t already, install ESP-IDF v5.x by following the official Espressif get-started guide for your operating system. After installation, source the environment script so that idf.py is available in your shell:
Verify the installation by checking the version:
You should see output similar to ESP-IDF v5.x.x. If you see an error, make sure the environment is sourced correctly before continuing.
VSCode has an official ESP-IDF extension that will install everything you need automatically. If the install process above is too complicated for you, just install this extension instead! After installing the extension, can use the ESP-IDF even without VSCode.
If you are on Windows, you can directly proceed with this step using WSL 2. If you do not want to use WSL2, your best option is to use the VSCode extension.
2

Create a new ESP-IDF project

Create a new ESP-IDF project using the idf.py create-project command. This sets up the standard directory structure including main/, CMakeLists.txt, and the required idf_component.yml manifest.
Set the build target to the ESP32-S3 so that the toolchain and configuration defaults match your Pocketbyte hardware:
3

Add the Pocketbyte component

From inside your project directory, add the Pocketbyte library as a managed component. The ESP-IDF component manager will fetch the latest compatible version and add it to your project’s dependency manifest automatically.
You’ll see the component listed in main/idf_component.yml after this command completes. The library source is downloaded automatically during the next build.
4

Write a minimal main.c

Open main/main.c and replace its contents with the following minimal program. This tests to see if the library can be linked properly and if the code can execute without any runtime errors.
5

Build and flash to your device

Connect your Pocketbyte to your computer via USB. Build the project and flash it to the device.
The device will reset after flashing and your app will start running immediately.
If the flash command times out waiting for the device to enter download mode, hold the BOOT button on Pocketbyte, then press and release the RESET button while keeping BOOT held, then release BOOT. The device will enter flash mode and the command will proceed.
6

Build and flash to your device

Connect your Pocketbyte to your computer via USB. Build the project and flash it to the device.
The device will reset after flashing and your app will start running immediately.
If the flash command times out waiting for the device to enter download mode, hold the BOOT button on Pocketbyte, then press and release the RESET button while keeping BOOT held, then release BOOT. The device will enter flash mode and the command will proceed.
Use idf.py monitor at any time to reconnect to the serial output of an already-flashed device. This is useful for reading debug output from printf statements in your app without reflashing. Press Ctrl+] to exit the monitor.
Last modified on June 14, 2026