From edf52efbc32fdfeaf482929d8161d70d1f2543f2 Mon Sep 17 00:00:00 2001 From: Stanislav N Mikhailov Date: Fri, 1 May 2026 20:45:54 +0300 Subject: [PATCH] Update README quick start instructions --- README.md | 131 +++++++++++++++++++++++++++++++++++++++++++++++++-- README.ru.md | 131 +++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 252 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 4274c53..445db1c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # RP Pico Display Engine -A lightweight C display engine for `RP2040/RP2350` and `ST7789` displays (SPI + DMA) with an explicit `begin/end paint` frame contract. +A lightweight C display engine for `RP2040/RP2350` and `ST7789` / `ILI9341` SPI displays (DMA) with an explicit `begin/end paint` frame contract. ## Features @@ -20,6 +20,34 @@ A lightweight C display engine for `RP2040/RP2350` and `ST7789` displays (SPI + - `include/Font/`, `src/Font/` - font data and text rendering - `Examples/Thermometr/` - working Pico SDK example project +## Required Environment + +- `git` +- `cmake` version `3.18.4+` +- build tool supported by CMake (`make` by default on Unix-like systems) +- `Pico SDK` with `PICO_SDK_PATH` pointing to it +- ARM toolchain `arm-none-eabi-gcc` + +## Supported Displays and Default Wiring + +Supported controller backends: + +- `DISPLAY_TYPE_ST7789` +- `DISPLAY_TYPE_ILI9341` + +If you do not pass any display-related compile definitions, the library defaults from [src/core/display_driver.h](/home/smikhai/repo/rp_pico_display_engine/src/core/display_driver.h:1) are used: + +- Controller: `DISPLAY_TYPE_ST7789` +- SPI port: `spi0` +- `MOSI=19` +- `SCK=18` +- `CS=17` +- `DC=22` +- `RST=13` +- `BL=12` + +These defaults mean: if you build without overriding pins or `DISPLAY_TYPE`, the firmware is meant for an `ST7789` display wired to those RP2040/RP2350 GPIOs. + ## Quick Start ### 1. Add as a subproject (recommended) @@ -27,7 +55,27 @@ A lightweight C display engine for `RP2040/RP2350` and `ST7789` displays (SPI + The most practical integration pattern is to add this repository (for example, as a git submodule) and build `display_engine` from your main `CMakeLists.txt`. You do not have to include all rendering primitives immediately: keep only what you need and uncomment extra modules later. -```cmake +Create a new project and add this repository as a submodule: + +```bash +mkdir pico_display_app +cd pico_display_app +git init +git submodule add https://github.com/stasenso/rp_pico_display_engine.git external/rp_pico_display_engine +git submodule update --init --recursive +mkdir -p src +``` + +Make sure `PICO_SDK_PATH` is set: + +```bash +export PICO_SDK_PATH=/absolute/path/to/pico-sdk +``` + +Create the root `CMakeLists.txt`: + +```bash +cat > CMakeLists.txt <<'EOF' cmake_minimum_required(VERSION 3.18.4) include($ENV{PICO_SDK_PATH}/external/pico_sdk_import.cmake) @@ -79,6 +127,46 @@ target_compile_definitions(display_engine PUBLIC add_executable(my_app src/main.c) target_link_libraries(my_app PRIVATE display_engine) pico_add_extra_outputs(my_app) +EOF +``` + +Create `src/main.c`: + +```bash +cat > src/main.c <<'EOF' +#include "pico/stdlib.h" +#include "display/display.h" +#include "display/render/context.h" + +int main(void) { + stdio_init_all(); + + display_config_t cfg = { + .width = 320, + .height = 240, + .buffer_count = 1, + .mode = DISPLAY_MODE_SAFE + }; + display_init(&cfg); + + render_ctx_t rc; + + while (1) { + uint16_t *buf = display_begin_paint_blocking(); + render_begin(&rc, buf, 320, 240); + render_clear(&rc, RGB16(0, 0, 0)); + display_end_paint(); + sleep_ms(16); + } +} +EOF +``` + +Build the project: + +```bash +cmake -S . -B build +cmake --build build ``` ### 2. Change display pins and controller type @@ -89,7 +177,16 @@ Set these compile definitions on `display_engine`: - `DISPLAY_PIN_MOSI`, `DISPLAY_PIN_SCK`, `DISPLAY_PIN_CS`, `DISPLAY_PIN_DC`, `DISPLAY_PIN_RST`, `DISPLAY_PIN_BL` - `DISPLAY_TYPE` (`DISPLAY_TYPE_ST7789` or `DISPLAY_TYPE_ILI9341`) -If no definitions are provided, defaults from `src/core/display_driver.h` are used. +If no definitions are provided, these defaults from [src/core/display_driver.h](/home/smikhai/repo/rp_pico_display_engine/src/core/display_driver.h:1) are used: + +- `DISPLAY_TYPE=DISPLAY_TYPE_ST7789` +- `DISPLAY_SPI_PORT=spi0` +- `DISPLAY_PIN_MOSI=19` +- `DISPLAY_PIN_SCK=18` +- `DISPLAY_PIN_CS=17` +- `DISPLAY_PIN_DC=22` +- `DISPLAY_PIN_RST=13` +- `DISPLAY_PIN_BL=12` ### 3. Safe mode with a single display loop @@ -208,6 +305,8 @@ draw_string(&rc, 16, 16, L"Cyrillic check", RGB565(255, 255, 255)); ## Build Example (Pico SDK) +If you just want to build the ready-made example from this repository: + ```bash cd Examples/Thermometr mkdir -p build && cd build @@ -215,8 +314,30 @@ cmake .. cmake --build . ``` -Display config is set in `Examples/Thermometr/CMakeLists.txt` via `target_compile_definitions(...)`: -`DISPLAY_TYPE`, `DISPLAY_SPI_PORT`, `DISPLAY_PIN_MOSI`, `DISPLAY_PIN_SCK`, `DISPLAY_PIN_CS`, `DISPLAY_PIN_DC`, `DISPLAY_PIN_RST`, `DISPLAY_PIN_BL`. +This example builds firmware for the Pico SDK default board unless you set `PICO_BOARD` yourself. The display configuration is set in [Examples/Thermometr/CMakeLists.txt](/home/smikhai/repo/rp_pico_display_engine/Examples/Thermometr/CMakeLists.txt:1): + +- Controller: `DISPLAY_TYPE_ILI9341` +- SPI port: `spi1` +- `MOSI=15` +- `SCK=14` +- `CS=13` +- `DC=12` +- `RST=11` +- `BL=10` + +There is also [Examples/EngineDemo/CMakeLists.txt](/home/smikhai/repo/rp_pico_display_engine/Examples/EngineDemo/CMakeLists.txt:1), which defaults to: + +- Board: `Pico 2` / `RP2350` (`TARGET_BOARD=pico2_RP2350`) +- Controller: `DISPLAY_TYPE_ST7789` +- SPI port: `spi1` +- `MOSI=15` +- `SCK=14` +- `CS=13` +- `DC=12` +- `RST=11` +- `BL=10` + +So the produced `.uf2` must be flashed to the board selected by that example's CMake config, and the display must be wired to the pins listed there. ## API Contract (Important) diff --git a/README.ru.md b/README.ru.md index 9c772e0..33e2e3d 100644 --- a/README.ru.md +++ b/README.ru.md @@ -1,6 +1,6 @@ # RP Pico Display Engine -Лёгкий C-движок вывода для `RP2040/RP2350` и дисплеев `ST7789` (SPI + DMA) с явным контрактом кадра `begin/end paint`. +Лёгкий C-движок вывода для `RP2040/RP2350` и дисплеев `ST7789` / `ILI9341` (SPI + DMA) с явным контрактом кадра `begin/end paint`. ## Возможности @@ -20,6 +20,34 @@ - `include/Font/`, `src/Font/` - данные шрифта и текстовый рендер - `Examples/Thermometr/` - рабочий пример проекта на Pico SDK +## Что должно быть установлено заранее + +- `git` +- `cmake` версии `3.18.4+` +- средство сборки, которое поддерживает CMake (`make` по умолчанию на Unix-подобных системах) +- `Pico SDK` и переменная окружения `PICO_SDK_PATH`, указывающая на него +- ARM toolchain `arm-none-eabi-gcc` + +## Поддерживаемые дисплеи и wiring по умолчанию + +Поддерживаются два backend-контроллера: + +- `DISPLAY_TYPE_ST7789` +- `DISPLAY_TYPE_ILI9341` + +Если не передавать compile definitions для дисплея, библиотека использует значения по умолчанию из [src/core/display_driver.h](/home/smikhai/repo/rp_pico_display_engine/src/core/display_driver.h:1): + +- Контроллер: `DISPLAY_TYPE_ST7789` +- SPI порт: `spi0` +- `MOSI=19` +- `SCK=18` +- `CS=17` +- `DC=22` +- `RST=13` +- `BL=12` + +То есть без переопределения пинов и `DISPLAY_TYPE` прошивка рассчитана на `ST7789`, подключённый к этим GPIO у `RP2040/RP2350`. + ## Быстрый старт ### 1. Подключение как subproject (рекомендуется) @@ -27,7 +55,27 @@ Практичный вариант интеграции: добавить этот репозиторий в проект (например, как git submodule) и собрать `display_engine` из вашего основного `CMakeLists.txt`. Подключать все примитивы сразу не обязательно: оставьте только нужные и раскомментируйте остальные позже. -```cmake +Создайте новый проект и добавьте библиотеку как submodule: + +```bash +mkdir pico_display_app +cd pico_display_app +git init +git submodule add https://github.com/stasenso/rp_pico_display_engine.git external/rp_pico_display_engine +git submodule update --init --recursive +mkdir -p src +``` + +Убедитесь, что переменная `PICO_SDK_PATH` выставлена: + +```bash +export PICO_SDK_PATH=/absolute/path/to/pico-sdk +``` + +Создайте `CMakeLists.txt` в корне проекта: + +```bash +cat > CMakeLists.txt <<'EOF' cmake_minimum_required(VERSION 3.18.4) include($ENV{PICO_SDK_PATH}/external/pico_sdk_import.cmake) @@ -79,6 +127,46 @@ target_compile_definitions(display_engine PUBLIC add_executable(my_app src/main.c) target_link_libraries(my_app PRIVATE display_engine) pico_add_extra_outputs(my_app) +EOF +``` + +Создайте `src/main.c`: + +```bash +cat > src/main.c <<'EOF' +#include "pico/stdlib.h" +#include "display/display.h" +#include "display/render/context.h" + +int main(void) { + stdio_init_all(); + + display_config_t cfg = { + .width = 320, + .height = 240, + .buffer_count = 1, + .mode = DISPLAY_MODE_SAFE + }; + display_init(&cfg); + + render_ctx_t rc; + + while (1) { + uint16_t *buf = display_begin_paint_blocking(); + render_begin(&rc, buf, 320, 240); + render_clear(&rc, RGB16(0, 0, 0)); + display_end_paint(); + sleep_ms(16); + } +} +EOF +``` + +Соберите проект: + +```bash +cmake -S . -B build +cmake --build build ``` ### 2. Как менять пины и тип дисплея @@ -89,7 +177,16 @@ pico_add_extra_outputs(my_app) - `DISPLAY_PIN_MOSI`, `DISPLAY_PIN_SCK`, `DISPLAY_PIN_CS`, `DISPLAY_PIN_DC`, `DISPLAY_PIN_RST`, `DISPLAY_PIN_BL` - `DISPLAY_TYPE` (`DISPLAY_TYPE_ST7789` или `DISPLAY_TYPE_ILI9341`) -Если определения не заданы, используются значения по умолчанию из `src/core/display_driver.h`. +Если определения не заданы, используются такие значения по умолчанию из [src/core/display_driver.h](/home/smikhai/repo/rp_pico_display_engine/src/core/display_driver.h:1): + +- `DISPLAY_TYPE=DISPLAY_TYPE_ST7789` +- `DISPLAY_SPI_PORT=spi0` +- `DISPLAY_PIN_MOSI=19` +- `DISPLAY_PIN_SCK=18` +- `DISPLAY_PIN_CS=17` +- `DISPLAY_PIN_DC=22` +- `DISPLAY_PIN_RST=13` +- `DISPLAY_PIN_BL=12` ### 3. Режим SAFE с одним буфером в цикле @@ -208,6 +305,8 @@ draw_string(&rc, 16, 16, L"Проверка кириллицы", RGB565(255, 255 ## Сборка примера (Pico SDK) +Если хотите собрать готовый пример из этого репозитория без создания собственного проекта: + ```bash cd Examples/Thermometr mkdir -p build && cd build @@ -215,8 +314,30 @@ cmake .. cmake --build . ``` -Конфигурация дисплея задаётся в `Examples/Thermometr/CMakeLists.txt` через `target_compile_definitions(...)`: -`DISPLAY_TYPE`, `DISPLAY_SPI_PORT`, `DISPLAY_PIN_MOSI`, `DISPLAY_PIN_SCK`, `DISPLAY_PIN_CS`, `DISPLAY_PIN_DC`, `DISPLAY_PIN_RST`, `DISPLAY_PIN_BL`. +Этот пример собирается для стандартной платы Pico SDK, если вы явно не зададите `PICO_BOARD`. Конфигурация дисплея задаётся в [Examples/Thermometr/CMakeLists.txt](/home/smikhai/repo/rp_pico_display_engine/Examples/Thermometr/CMakeLists.txt:1): + +- Контроллер: `DISPLAY_TYPE_ILI9341` +- SPI порт: `spi1` +- `MOSI=15` +- `SCK=14` +- `CS=13` +- `DC=12` +- `RST=11` +- `BL=10` + +Также есть [Examples/EngineDemo/CMakeLists.txt](/home/smikhai/repo/rp_pico_display_engine/Examples/EngineDemo/CMakeLists.txt:1), где по умолчанию выбрано: + +- Плата: `Pico 2` / `RP2350` (`TARGET_BOARD=pico2_RP2350`) +- Контроллер: `DISPLAY_TYPE_ST7789` +- SPI порт: `spi1` +- `MOSI=15` +- `SCK=14` +- `CS=13` +- `DC=12` +- `RST=11` +- `BL=10` + +То есть получившийся `.uf2` нужно заливать именно в ту плату, которая выбрана в `CMakeLists.txt` конкретного примера, а дисплей подключать к перечисленным там пинам. ## Контракт API (важно)