Ошибка PICO_SDK_PATH is not set при первой сборке проекта под Raspberry Pi Pico — самый частый симптом того, что SDK установлен, но среда сборки не знает, где его искать. Эта переменная окружения указывает на каталог с исходниками pico-sdk, и без неё cmake не сможет собрать даже пример «Hello World».
Raspberry Pi Pico SDK — это официальный набор библиотек и заголовочных файлов для программирования микроконтроллера RP2040 на языках C и C++. В отличие от среды Arduino IDE, SDK даёт прямой доступ к периферии чипа: обоим ядрам, программируемым блокам ввода-вывода PIO, DMA-контроллеру и аппаратным интерфейсам. Ниже разберём, как развернуть инструментарий с нуля, собрать и загрузить первую прошивку, а также какие типичные ошибки встречаются на этом пути.
Что входит в состав Pico SDK
SDK построен вокруг системы сборки CMake и включает несколько уровней библиотек. Низкоуровневая часть — hardware_* библиотеки (hardware_gpio, hardware_uart, hardware_i2c, hardware_pio и другие) — обеспечивает тонкий слой доступа к регистрам периферии. Поверх них работают высокоуровневые функции pico_stdlib: инициализация платы, стандартный ввод-вывод через USB или UART, таймеры.
Отдельно стоит упомянуть поддержку двухъядерности через pico_multicore и уникальный блок PIO — программируемые конечные автоматы, позволяющие реализовать нестандартные протоколы обмена без нагрузки на процессор. Именно PIO выделяет RP2040 среди других бюджетных микроконтроллеров.
- 🔧 hardware_gpio — управление выводами общего назначения
- 📡 hardware_uart, hardware_spi, hardware_i2c — стандартные интерфейсы
- ⚙️ hardware_pio — программируемые автоматы ввода-вывода
- 🧵 pico_multicore — запуск кода на втором ядре
- ⏱️ hardware_timer и hardware_pwm — таймеры и ШИМ
Установка SDK и инструментария
Порядок действий зависит от операционной системы. На Linux (включая Raspberry Pi OS) достаточно установить компилятор и зависимости через пакетный менеджер, затем клонировать репозиторий SDK. На Windows удобнее всего использовать официальный установщик pico-setup-windows, который разворачивает компилятор arm-none-eabi-gcc, CMake, Python и сам SDK одним пакетом.
На Linux базовая установка выглядит так:
sudo apt install cmake gcc-arm-none-eabi libnewlib-arm-none-eabi build-essential git
git clone https://github.com/raspberrypi/pico-sdk.git
cd pico-sdk
git submodule update --init
После клонирования обязательно задайте переменную окружения PICO_SDK_PATH, указав полный путь к каталогу SDK. На Linux её добавляют в ~/.bashrc или ~/.profile, на Windows — через свойства системы или установщик делает это автоматически.
⚠️ Внимание: не пропускайте шаг git submodule update --init. Без сабмодулей (в частности, библиотеки tinyusb) сборка проектов с USB-функциями завершится ошибкой, причём текст ошибки не всегда явно указывает на причину.
☑️ Проверка готовности окружения
Структура проекта и CMakeLists.txt
Каждый проект на Pico SDK — это, по сути, обычный CMake-проект с несколькими специфичными строками. Минимальный CMakeLists.txt подключает SDK, объявляет цель и линкует нужные библиотеки. Ключевой момент: вызов pico_sdk_init() должен идти после объявления проекта, а pico_add_extra_outputs() генерирует файлы форматов .uf2, .hex и .elf помимо стандартного бинарника.
cmake_minimum_required(VERSION 3.13)
include(pico_sdk_import.cmake)
project(my_project C CXX ASM)
pico_sdk_init()
add_executable(my_project main.c)
target_link_libraries(my_project pico_stdlib)
pico_add_extra_outputs(my_project)
Файл pico_sdk_import.cmake копируется из каталога external внутри SDK в корень вашего проекта. Он отвечает за поиск SDK через переменную окружения — именно его отсутствие или устаревшая версия часто становится причиной ошибок конфигурации.
Сборка и загрузка прошивки на плату
Сборка выполняется стандартной парой команд: сначала конфигурация, затем компиляция. Работать нужно из отдельного каталога build, чтобы не засорять дерево исходников.
mkdir build && cd build
cmake ..
make -j4
Если конфигурация прошла без ошибок, в каталоге сборки появится файл с расширением .uf2. Чтобы загрузить его на плату, зажмите кнопку BOOTSEL на Pico и подключите плату к компьютеру по USB (или нажмите кнопку при уже подключённом кабеле). Плата определится как съёмный накопитель — останется скопировать на него файл .uf2, после чего Pico автоматически перезагрузится и начнёт выполнять прошивку.
Если накопитель не появляется, проверьте USB-кабель: часть кабелей поддерживает только зарядку и не передаёт данные. Это одна из самых частых бытовых причин, по которой «плата не определяется».
Отладка и вывод через USB/UART
Простейший способ видеть, что происходит внутри прошивки, — функция printf из pico_stdlib. По умолчанию вывод может идти через USB (виртуальный последовательный порт) или через аппаратный UART. Режим задаётся в CMake командами pico_enable_stdio_usb(target 1) и pico_enable_stdio_uart(target 0).
При выводе через USB учитывайте нюанс: если программа сразу после старта печатает сообщения, часть из них может потеряться, пока хост не открыл виртуальный COM-порт. Небольшая задержка в начале main() или ожидание подключения терминала решает эту проблему. Для чтения вывода подойдёт любой терминал последовательного порта — например, minicom на Linux или встроенный монитор порта в VS Code.
Продвинутая отладка через SWD
Для полноценной отладки с точками останова используется интерфейс SWD и связка OpenOCD + GDB. В качестве отладочного зонда можно применить вторую плату Pico с прошивкой picoprobe — это официально поддерживаемый и недорогой вариант. Потребуется соединить выводы SWDIO, SWCLK и GND двух плат.
Типичные ошибки при работе с SDK
Большинство проблем на старте связаны не с кодом, а с окружением. Ниже — таблица частых симптомов и их вероятных причин.
| Симптом | Вероятная причина | Что проверить |
|---|---|---|
| PICO_SDK_PATH is not set | Не задана переменная окружения | Значение переменной, перезапуск терминала |
| arm-none-eabi-gcc not found | Компилятор не в PATH | Установку тулчейна и переменную PATH |
| Ошибки при сборке USB-примеров | Не инициализированы сабмодули | git submodule update --init |
| Плата не появляется как накопитель | Кабель без линий данных | Другой USB-кабель, кнопку BOOTSEL |
| Нет вывода printf | Не включён stdio или порт не открыт | pico_enable_stdio_usb, терминал порта |
⚠️ Внимание: выводы RP2040 рассчитаны на логику 3,3 В и не толерантны к 5 В. Подключение пятивольтовых сигналов напрямую к GPIO может вывести порт или весь чип из строя — используйте преобразователи уровней.
Ещё одна категория проблем — конфликты версий. SDK и примеры pico-examples должны быть одной версии: примеры из свежей ветки могут не собраться со старым SDK, и наоборот. Если вы обновляли репозиторий примеров, обновите и сам SDK.
Альтернативы: Arduino, MicroPython и CircuitPython
Нативный SDK — не единственный способ программировать Pico. Ядро Arduino-Pico позволяет писать скетчи в привычной среде Arduino, сохраняя доступ к обоим ядрам и PIO. MicroPython и CircuitPython подходят для быстрого прототипирования: код интерпретируется прямо на плате, а файловая система доступна через USB-накопитель.
Выбор зависит от задачи. Для максимальной производительности, точного тайминга и работы с PIO на низком уровне предпочтителен C/C++ SDK. Для учебных проектов и быстрых экспериментов Python-варианты заметно удобнее.
Часто задаваемые вопросы
Можно ли использовать Pico SDK на Windows без Linux?
Да. Официальный установщик pico-setup-windows разворачивает компилятор, CMake, SDK и примеры, а также ярлыки для готовой командной строки разработчика. Дополнительно настраивать WSL не требуется.
Чем Pico SDK отличается от Arduino IDE для Pico?
SDK — это нативные библиотеки C/C++ с прямым доступом к периферии RP2040 и сборкой через CMake. Arduino-ядро упрощает разработку, но добавляет слой абстракции. Под капотом Arduino-ядро для Pico само использует pico-sdk.
Как вернуть плату в режим загрузки прошивки?
Зажмите кнопку BOOTSEL и подключите плату по USB (или нажмите RESET при зажатой BOOTSEL, если плата уже подключена). Pico появится в системе как съёмный диск, на который копируется файл .uf2.
Нужно ли стирать старую прошивку перед загрузкой новой?
Нет, новый файл .uf2 просто перезаписывает область программы. Полная очистка через flash_nuke.uf2 нужна только в проблемных случаях — например, когда прошивка блокирует USB и мешает диагностике.
Подходит ли Pico SDK для плат на RP2350 (Pico 2)?
Да, актуальные версии SDK поддерживают чип RP2350. Целевая плата выбирается параметром PICO_BOARD при конфигурации CMake. Точный список поддерживаемых плат и опций стоит сверять с документацией вашей версии SDK.