Your First App

This guide walks you through writing your first piece of software for Pocketbyte and how you can use the simulator to test your app without needing a DevKit.

Prerequisites

Before you begin, please ensure that the ESP-IDF is installed on your computer and that you have set up your project folder with the Pocketbyte Library added as a component. Visit Development Setup to learn how to do this.

Introduction

On Pocketbyte, apps are single, contained programs. They behave exactly how you would expect, for example, an Arduino program to function.

Initialization

When writing your program, you must explicitly initialize the subsystem that you will be using. For example, if you are using audio, you must call pb_audio_init() at the start of your program’s entry point. See the library’s header files for more info.

Graphics

The Pocketbyte Library features two different graphics backends: LVGL and PAX. You must decide which backend to use before writing a line of code. They are not interchangeable, and if you decide to switch later on, you will have to rewrite a substantial portion of your code.

Alternatively, you can also access the raw display handle to blit pixels without using a dedicated graphics library. LVGL and PAX are just layers above this.

LVGL

Retained mode
Cool, polished-looking UI
Lots of pre-built widgets
Great for making traditional apps and utility programs
Expansive dev ecosystem
If you already know it, it will be easy to write Pocketbyte software
Extremely slow - do not use it for games!

PAX

Immediate mode
Blazing fast - the best backend for games
No built-in UI library
Can be more difficult than LVGL
Great for drawing primitives

Examples

“Talk is cheap. Show me the code.” - Linus Torvalds.

LVGL

#include "pocketbyte.h"
#include "gfx_lvgl.h"

void app_main(void)
{
    pb_gfx_lvgl_init();

    lv_obj_t *label = lv_label_create(lv_scr_act());
    lv_label_set_text(label, "Hello, Pocketbyte! :D");
    lv_obj_center(label);

    while (pb_timing_loop(60)) {
        pb_gfx_lvgl_tick();
    }
}

PAX

#include "pocketbyte.h"
#include "gfx_pax.h"

void app_main(void)
{
    pb_gfx_pax_init();

    while (pb_timing_loop(60)) {
        pax_buf_t *gfx = pb_gfx_pax_get_buf();

        pax_background(gfx, pax_col_rgb(255, 0, 0));
        pax_draw_text(gfx, pax_col_rgb(255, 255, 255), pax_font_sky_mono, 18, 0, 0, "Hello, Pocketbyte! :D");

        pb_gfx_pax_flush();
    }
}

As you can see, when developing Pocketbyte applications, the grunt of the work revolves around the graphics. Because Pocketbyte uses third-party libraries, such as LVGL and PAX, to provide this functionality, 90% of what you’ll need to know are actually in the LVGL and PAX documentation.

What Else?

The examples above are simply “Hello World!” applications. The Pocketbyte Library has many other features not yet discussed, such as input, audio, module detection, Wi-Fi, NVS, and even IMU interfacing for motion controls. Most of what you need can be found in the header files of the library itself. I tried my best to make it as intuitive as possible, so you can easily write your software even without a full API reference.

You can find the source code on GitHub: https://github.com/PocketByteTechnology/library

Testing Your Code on the Pocketbyte Simulator

The Pocketbyte Simulator has been unofficially published on GitHub recently. On the README, you will find the basic instructions necessary to get it up and running. You can actually test your software without needing a DevKit! Enjoy!

Get Started

Packaging Apps

Misc

Help

Prerequisites

Introduction

Initialization

Graphics

LVGL

PAX

Examples

LVGL

PAX

What Else?

Testing Your Code on the Pocketbyte Simulator

​Prerequisites

​Introduction

​Initialization

​Graphics

​LVGL

​PAX

​Examples

​LVGL

​PAX

​What Else?

​Testing Your Code on the Pocketbyte Simulator

Prerequisites

Introduction

Initialization

Graphics

LVGL

PAX

Examples

LVGL

PAX

What Else?

Testing Your Code on the Pocketbyte Simulator