суббота, 31 марта 2018 г.

ESP32, ESP-IDF, Eclipse IDE: настройка окружения и первый запуск под Windows


Эта статья поможет вам настроить рабочее окружение для начала разработки приложений для микроконтроллера Espressif ESP32. Здесь на простом примере показано, как использовать ESP-IDF (Espressif IoT Development Framework), включая конфигурирование проекта с помощью "menuconfig", компиляцию ESP-IDF и загрузку прошивки в ESP32 с помощью IDE Eclipse в операционной системе Windows. Вся информация в данной статье бралась из официальной документации ESP-IDF, но с моими небольшими дополнениями.


Что для этого нужно:


Для разработки приложений для ESP32 вам необходимо:
  1. ПК, с операционной системой Windows (я использовал Windows 10 Pro x64, для других ОС смотрите оф. документацию)
  2. Toolchain (набор инструментов для компиляции и генерации кода) для создания приложения для ESP32 
  3. ESP-IDF, который по существу содержит API для ESP32 и скрипты для работы с Toolchain
  4. Текстовый редактор для написания программ (проектов) на языке C/C++ (Eclipse)
  5. Сама плата ESP32 и USB-кабель для подключения к ПК (я использовал ESP32 DevKitC с AliExpress)
Development of applications for ESP32

Подготовка среды разработки состоит из трех основных этапов: 
  1. Установка Toolchain
  2. Получение ESP-IDF из GitHub
  3. Конфигурирование проекта и настройка IDE Eclipse
После настройки среды вы будете готовы начать самую интересную часть - разработку приложения. Этот процесс можно суммировать в четыре этапа:
  1. Конфигурация проекта и написание кода
  2. Компиляция проекта и создание приложения
  3. Прошивка приложения
  4. Мониторинг/Отладка приложения

Установка Toolchain


В Windows нет встроенной среды «make», поэтому для установки Toolchain вам понадобится GNU-совместимая среда. Для этого можно использовать среду MSYS2. Вам не нужно постоянно использовать эту среду (вы можете использовать Eclipse или какой-либо другой интерфейс), но она необходима для входа в меню настройки приложения menuconfig, о чём пойдёт речь далее.

Для загрузки MSYS2 перейдите по следующей ссылке. Затем разархивируйте zip-файл в C:\ (или в другое место, но это руководство предполагает C:\), у вас должен появится каталог C:\msys32\ с предварительно подготовленной средой. Далее откройте окно терминала запустив C:\msys32\mingw32.exe.
Среда в этом окне является оболочкой bash.  В каталоге C:\msys32\ есть каталог home, который в свою очередь содержит каталог с именем пользователя. Собственно он и является текущим в открытом терминале. Этот каталог будет использоваться для хранения наших файлов. Далее создайте каталог с именем esp, который будет по умолчанию предназначен для разработки приложений ESP32. Для этого запустите следующую команду оболочки:
    mkdir -p ~/esp
Для перехода в созданный каталог:
    cd ~/esp
Окно оболочки MSYS32 (mingw32.exe)

Загрузка ESP-IDF из GitHub


Помимо Toolchain  (которая содержит программы для компиляции и сборки приложения), вам также нужны специальные API/библиотеки ESP32. Они предоставляются Espressif в репозитории ESP-IDF. Чтобы получить его, откройте терминал, находясь в каталоге ~/esp, и клонируйте его с помощью команды git clone:
git clone --recursive https://github.com/espressif/esp-idf.git
ESP-IDF будет загружен в ~/esp/esp-idf.

Добавление IDF_PATH в профиль пользователя


Программа toolchain обеспечивает доступ к ESP-IDF с использованием переменной среды IDF_PATH. Эта переменная должна быть настроена на вашем ПК, иначе проекты не будут компилироваться. Для этого нужно добавить скрипт и указать IDF_PATH в профиле пользователя.
Скрипты пользовательского профиля содержатся в каталоге C:/msys32/etc/profile.d/. Они выполняются каждый раз, когда вы открываете окно MSYS2.
  1. Создайте новый файл скрипта в каталоге C:/msys32/etc/profile.d/. Назовите его export_idf_path.sh.
  2. Определите путь к каталогу ESP-IDF. Он специфичен для вашей конфигурации системы и может выглядеть примерно так: C:\msys32\home\user-name\esp\esp-idf
  3. Добавьте команду экспорта в файл скрипта, например:
    export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
    Не забудьте заменить обратные косые черты в исходном пути Windows (должно быть так как в примере с использованием "/").
  4. Сохраните этот файл скрипта
  5. Закройте окно MSYS2 и затем откройте снова. Проверьте установлен ли IDF_PATH выполнив команду:
    printenv IDF_PATH
Если всё настроено верно, то консоль должна вывести путь к папке ESP-IDF:
    Путь IDF_PATH

    Старт проекта


    Теперь вы готовы подготовить свое первое приложение для ESP32. Чтобы понять как происходит создание приложения, мы выполним это из командной строки MSYS32 (создание приложения с помощью Eclipse описано ниже).
    Чтобы начать быстро, мы будем использовать проект get-started/hello_world из каталога примеров в IDF. Но если вы будете создавать своё приложение с нуля, то производитель рекомендует использовать шаблон esp-idf-template, который остаётся лишь настроить под свои нужды. Вы также можете найти ряд других проектов с примерами в каталоге ESP-IDF.
    Итак, скопируйте get-started/hello_world в каталог ~/esp:
    cd ~/esp
    cp -r $IDF_PATH/examples/get-started/hello_world .
    
    

    Подключение ESP32 к ПК


    Подключите плату ESP32 к ПК с помощью USB-кабеля. Если драйвер устройства не устанавливается автоматически, определите чип USB для последовательного преобразователя на плате ESP32 (или внешний конвертер), найдите драйверы в Интернете и установите их.

    Узнаём порт подключения


    Проверьте список идентифицированных COM-портов в Диспетчере устройств Windows. Отключите ESP32 и подключите его обратно, чтобы проверить, какой порт исчез из списка, а затем снова отобразится.  На приведенном ниже рисунке показан серийный порт для ESP32 DevKitC:

    ESP32 DevKitC и его номер порта в диспетчере устройств

    Конфигурирование порта с помощью menuconfig


    Это обязательный шаг конфигурации проекта без выполнения которого вы не сможете загрузить приложение в свой ESP32. Итак, находясь в терминальном окне, перейдите в каталог проекта hello_world, набрав cd ~/esp/hello_worldЗатем запустите утилиту конфигурации проекта menuconfig:
    cd ~/esp/hello_world
    make menuconfig
    Если предыдущие шаги были выполнены правильно, отобразится следующее меню:


    В меню перейдите в Serial flasher config > Default serial port, чтобы настроить имя последовательного порта, на котором работает подключенный ESP32. По умолчанию он называется как в Linux /dev/ttyUSB0:


    Его нужно изменить на COM3 (номер тот который отображался в диспетчере устройств):


    Подтвердите выбор, нажав enter, сохраните конфигурацию, выбрав < Save > и затем выйдите из приложения, выбрав < Exit >.

    Вот несколько советов по навигации в menuconfig
    • Используйте клавиши со стрелками "вверх" и "вниз" для перемещения по меню. 
    • Используйте клавишу "Enter", чтобы перейти в подменю, клавишу "Escape", чтобы выйти. 
    • Используйте клавишу "?" чтобы увидеть справку. Клавиша "Enter" выходит справки. 
    • Используйте клавишу "пробела" или "Y" и "N" для включения (Yes) и отключения (No) элементов конфигурации с флажками '[*]' 
    • Введите "/ "для поиска элементов конфигурации.
    В настоящее время утилита menuconfig не поддерживается в Eclipse IDE. По этому, перед началом работы с проектом необходимо выполнить описанные выше шаги.

      Создание и загрузка приложения в ESP32


      Теперь вы можете создавать и запускать приложение.
      Выполните в консоли:
      make flash 
      Это скомпилирует приложение и все компоненты ESP-IDF, сгенерирует загрузчик, таблицу разделов и двоичные файлы приложения, а затем загрузит эти двоичные файлы на вашу плату ESP32. Если в процессе сборки нет проблем, вы должны увидеть сообщения, описывающие ход процесса загрузки:


      Наконец, окончательный модуль будет сброшен, и приложение «hello_world» запустится.
      Сразу хочу сказать, что выполнение команды make flash может занять от 5 до 10 минут (зависит от конфигурации вашего ПК), но это только при первом запуске.
      На самом деле, для компиляции и загрузки приложения в ESP32, не обязательно использовать консоль MSYS32, это можно будет делать в Eclipse IDE, с помощью заранее созданных выполняемых команд (build targets).

      Monitor


      Monitor можно использовать для отладки и просмотра состояния приложения. Чтобы убедиться, что приложение «hello_world» действительно запущено, введите make monitor. Эта команда запускает приложение IDF Monitor:


      Запуск IDF Monitor
      После нескольких строк журнала диагностики вы должны увидеть "Hello world!", после которого будет отсчитываться 10 секунд до перезагрузки:

      Hello World в консоли

      Для выхода из monitor нажмите сочетание клавиш Ctrl+]

      Если вместо сообщений выше вы видите случайный мусор, похожий на:
      e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA
      ~zY��Y(1�,1 �� e���)(Xn@�y.!Dr�zY(� jpi�|�+z5Ymvp...
      или монитор выходит из строя вскоре после загрузки, ваша плата, скорее всего, использует 26-мегагерцовый кристалл, а ESP-IDF принимает значение по умолчанию 40 МГц. Выйдите из монитора, вернитесь к menuconfig, измените ESP32_XTAL_FREQ_SEL на 26 МГц, затем снова создайте и загрузите приложение в ESP32. Данный параметр находится в меню  Component config –> ESP32-specific –> Main XTAL frequency.
      Также причина может быть в неправильной установке скорости COM порта (по умолчанию 115200), которую можно изменить в том же menuconfig.

      Установка и настройка IDE Eclipse


      Eclipse IDE предоставляет графическую интегрированную среду разработки для написания, компиляции и отладки проектов ESP-IDF, которая распространяется совершенно бесплатно. Для установки, запуска и настройки  Eclipse выполните следующие шаги:
      • Загрузите установщик Eclipse для windows с eclipse.org.
      • Если у вас не установлено Java SE Runtime Environment, то возможно, при запуске установщика Eclipse, вам предложат это сделать
      • При запуске установщика Eclipse выберите "Eclipse for C/C++ Development" (в других местах вы увидите, что это называется CDT).
      • Eclipse использует поддержку Makefile в ESP-IDF. Это означает, что вам нужно начать с создания проекта ESP-IDF. Вы можете использовать проект idf-template из github или открыть один из примеров в поддиректории примеров esp-idf
      • Далее запустите Eclipse, выберите "File" -> "Import..."
      • В появившемся диалоговом окне выберите "C/C++" -> "Existing Code as Makefile Project" и нажмите "Next". 
      • На следующей странице в "Existing Code Location" введите путь к каталогу вашего проекта IDF. Не указывайте путь к самому каталогу ESP-IDF (который настраивается позже). Указанный каталог должен содержать файл с именем "Makefile" (проект Makefile). 
      • На той же странице в разделе "Toolchain for Indexer Settings" снимите флажок "Show only available toolchains that support this platform". 
      • В появившемся расширенном списке выберите "Cygwin GCC". Затем нажмите "Finish".
      Примечание: вы можете видеть предупреждения в пользовательском интерфейсе, что Cygwin GCC Toolchain не найден. Это нормально, мы собираемся настроить свойства проекта в Eclipse, чтобы он видел наш Toolchain.

      Свойства проекта


      • Новый проект появится в проводнике проектов слева. Щелкните правой кнопкой мыши по имени проекта и в открывшемся контекстном меню выберите "Properties" (свойства проекта). 
      • На странице свойств нажмите на "C/C++ Build" (верхний уровень)
      • Снимите флажок "Use default build command" и в поле build command введите:
        python ${IDF_PATH}/tools/windows/eclipse_make.py
      • Ниже под "C/C++ Build" перейдите на страницу "Environment":
      • Нажмите на кнопку "Add…" и введите имя BATCH_BUILD и значение (value) 1.
      • Нажмите на кнопку "Add…" и введите имя IDF_PATH. Значение должно содержать полный путь к каталогу ESP-IDF. Этот путь должен записываться с использованием знака деления "/", а не обратной косой черты "\". Пример правильной записи: C:/msys32/home/Oleksii/esp-idf.
      • Далее необходимо отредактировать значение переменной PATH. Можно либо в конец, после точки с запятой, либо удалить имеющиеся значение и уже в пустое поле добавить следующее значение:
        C:\msys32\usr\bin;C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin
        (Если вы устанавливали msys32 в другую директорию то вам нужно будет отредактировать пути).
      • Нажмите на "C/C++ General" и в раскрывшемся списке нажмите на "Preprocessor Include Paths, Macros, etc."
      • Перейдите на вкладку "Providers"
      • В отображаемом списке свойств, нажмите на "CDT GCC Built-in Compiler Settings Cygwin". Ниже, в поле "Command to get compiler specs", удалите всё значение и вставте:
        xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"
      • Далее в том же списке свойств, нажмите на "CDT GCC Build Output Parser" и ниже, в поле "Compiler command pattern" удалите всё значение и вставте:
        xtensa-esp32-elf-((g?cc)|([gc]\+\+)|(clang))
      На этом конфигурация проекта закончена. Далее для того чтобы вы могли, в интерфейсе Eclipse, выполнять команды очистки, сборки и загрузки проекта в ESP32, необходимо выполнить следующее:
      • Слева, в проводнике проектов, нажмите правую кнопку мыши по имени проекта (убедитесь что вы выбрали именно корневой каталог, а не внутренний)
      • В открывшемся контекстном меню выберете "Build Targets" -> "Create…"
      • В поле "Target name" введите "flash". Остальные опции оставте по-умолчанию.
      • Теперь для компиляции и загрузки своего приложения вы можете использовать "Project" -> "Build Target" -> "Build" (Shift+F9)
      Команда flash далеко не единственная которую можно использовать в работе. Для получения полного списка команд выполните в терминале msys32 (предварительно перейдя в папку проекта) команду make help. В результате вы увидете весь список поддерживаемых команд:

      Список поддерживаемых комманд приложением make
      Стоит выделить только те которые будут вам полезны:
      • all - создаёт (компилирует) полное приложение с bootloader и таблицей разметки
      • flash - выполняет загрузку всех файлов приложения в память ESP32
      • clean - очищает проект от скомпилированных файлов (может быть полезна если ваш проект был скомпилирован вне Eclipse)
      • erase_flash - очищает память ESP32
      • app - создаёт (компилирует) только пользовательское приложение
      Это всё что необходимо сделать для начала работы с ESP32, ESP-IDF и Eclipse в операционной системе Windows 10.