Skip to content

development-setup.mdx

Latest commit

 

History

History
95 lines (72 loc) · 3.8 KB

development-setup.mdx

File metadata and controls

95 lines (72 loc) · 3.8 KB
Raw
title Development Setup
sidebarTitle Development Setup
description Everything you need to go from a fresh machine to building Pocketbyte apps.

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

If you haven't already, install ESP-IDF v5.5.1 by following the [official Espressif get-started guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/get-started/index.html) for your operating system. After installation, source the environment script so that `idf.py` is available in your shell: 
```bash
. $HOME/esp/esp-idf/export.sh
```

Verify the installation by checking the version:

```bash
idf.py --version
```

You should see output similar to `ESP-IDF v5.5.1`. If you see an error, make sure the environment is sourced correctly before continuing.

<Tip>
  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.
</Tip>

<Note>
  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.
</Note>
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. 
```bash
idf.py create-project my-pocketbyte-app
cd my-pocketbyte-app
```

Set the build target to the ESP32-S3 so that the toolchain and configuration defaults match your Pocketbyte hardware:

```bash
idf.py set-target esp32s3
```
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. 
```bash
idf.py add-dependency "omrawaley/pocketbyte"
```

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.
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. 
```c
#include <pocketbyte.h>

void app_main(void)
{
    return 0;
}
```
Connect your Pocketbyte to your computer via USB. Build the project and flash it to the device. 
```bash
idf.py build && idf.py flash
```

The device will reset after flashing and your app will start running immediately.

<Tip>
  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.
</Tip>

<Tip>
  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.
</Tip>