Запуск примера веб-сервера на ESP32-S3 | arm

Здесь приведены основные шаги по запуску веб-сервера на платке WaveShare ESP32-S3-ETH [1] через интерфейс Ethernet.

1. Сделайте копию папки esp-idf/examples/protocols/http_server/restful_server в отдельном каталоге, например в ~/restful_server.

2. Зайдите в каталог restful_server, выполните инициализацию переменных ESP-IDF запуском скрипта esp-idf/export.sh.

4. Выполните команду idf.py menuconfig, сконфигурируйте следующие опции.

Размещение данных сайта на памяти SPI Flash:
Example Configuration → Website deploy mode → (X) Deploy website to SPI Nor Flash (CONFIG_EXAMPLE_WEB_DEPLOY_SF=y)

Выбор подключения через Ethernet:
Example Connection Configuration → [*] connect using Ethernet interface (CONFIG_EXAMPLE_CONNECT_ETHERNET=y)

PHY-интерфейс Ethernet на платке WaveShare ESP32-S3-ETH реализован на чипе W5500 следующим образом:

Поэтому нужно также установить следующие опции:

Ethernet Type (W5500 Module) ---> (CONFIG_EXAMPLE_USE_SPI_ETHERNET=y, CONFIG_EXAMPLE_USE_W5500=y)
(1) SPI Host Number (CONFIG_EXAMPLE_ETH_SPI_HOST=1)
(13) SPI SCLK GPIO number (CONFIG_EXAMPLE_ETH_SPI_SCLK_GPIO=13)
(11) SPI MOSI GPIO number (CONFIG_EXAMPLE_ETH_SPI_MOSI_GPIO=11)
(12) SPI MISO GPIO number (CONFIG_EXAMPLE_ETH_SPI_MISO_GPIO=12)
(14) SPI CS GPIO number (CONFIG_EXAMPLE_ETH_SPI_CS_GPIO=14)
(36) SPI clock speed (MHz) (CONFIG_EXAMPLE_ETH_SPI_CLOCK_MHZ=36)
(10) Interrupt GPIO number (CONFIG_EXAMPLE_ETH_SPI_INT_GPIO=10)
(9) PHY Reset GPIO number (CONFIG_EXAMPLE_ETH_PHY_RST_GPIO=9)
(1) PHY Address (CONFIG_EXAMPLE_ETH_PHY_ADDR=1)

Отключить IPv6 (CONFIG_EXAMPLE_CONNECT_IPV4=y, # CONFIG_EXAMPLE_CONNECT_IPV6 is not set):

5. Зайдите в каталог front/web-demo, выполните в нем команду:

После выполнения этой команды должна появиться папка dist с файлами сайта.

Устранение ошибки 'sh: 1: vue-cli-service: not found'

Выполните в каталоге front/web-demo команду:

npm install --save-dev @vue/cli-service

6. Вернитесь в корневой каталог проекта, скомпилируйте проект командой isp.py build:

7. Прошейте программу в память чипа и запустите монитор:

В лог монитора должно быть выведено примерно следующее:

8. Подключите кабель Ethernet сети, где доступен DHCP-сервер. В логе должны появиться сообщения о выдаче IP-адреса:

Теперь можно открыть веб-страницы сервера в браузере по ссылке http://192.168.116.162.

README.md

Supported Targets	ESP32	ESP32-C2	ESP32-C3	ESP32-C5	ESP32-C6	ESP32-C61	ESP32-P4	ESP32-S2	ESP32-S3

[Обзор проекта]

Этот пример главным образом обеспечивает введение в реализацию RESTful API server и HTTP-сервера на ESP32, с UI frontend-ом в браузере.

В этом примере несколько API-интерфейсов предназначены для выборки ресурсов следующим образом:

API	Метод	Пример ресурса	Описание	Page URL
`/api/v1/system/info`	`GET`	{ version:"v4.0-dev", cores:2 }	Для получения системной информации наподобие версии IDF, ядер ESP32, и т. п.	`/`
`/api/v1/temp/raw`	`GET`	{ raw:22 }	Для получения сырых данных температуры, полученных из датчика	`/chart`
`/api/v1/light/brightness`	`POST`	{ red:160, green:160, blue:160 }	Для выгрузки управляющих яркостью светодиодов (LED) значений	`/light`

Page URL это URL web-страницы, куда посылается запрос в API.

[Установка Wi-Fi или Ethernet соединения]

Функция example_connect(). Примеры протоколов используют простую вспомогательную функцию example_connect() для установки Wi-Fi и/или Ethernet соединения. Эта функция реализована в examples/common_components/protocol_examples_common/include/protocol_examples_common.h, и она имеет очень простое поведение: блокирует выполнение, пока не установится соединение и не будет получен IP-адрес, после чего делает возврат. Эта функция используется для уменьшения количества лишних усилий, благодаря чему код примера фокусируется на демонстрации протокола или библиотеки.

Простая функция example_connect() не обрабатывает таймауты, не выполняет корректную обработку различных ситуаций ошибки, и она подходит только для использования в примерах. При разработке реальных приложений эта вспомогательная функция должна быть заменена н код, поддерживающий соединение Wi-Fi / Ethernet. Такого рода код можно найти в примерах examples/wifi/getting_started/ и examples/ethernet/basic/.

[Конфигурирование примера]

Для конфигурирования примера на использование Wi-Fi, Ethernet или обоих этих соединений откройте меню конфигурации проекта (idf.py menuconfig) и перейдите в раздел меню "Example Connection Configuration". Выберите здесь "Wi-Fi" или "Ethernet", или обе эти опции в селекторе выбора "Connect using".

Когда соединение использует Wi-Fi, введите SSID и password вашей точки доступа Wi-Fi в соответствующие поля. Если происходит соединение к открытой сети Wi-Fi, то оставьте поле password пустым.

Когда соединение происходит через Ethernet, установите тип PHY и конфигурацию в предоставленных полях. Если Ethernet используется первый раз, то рекомендуется начать с Ethernet example readme, где содержатся инструкции для подключения и конфигурирования PHY. Как только этот пример Ethernet успешно получит IP-адрес, переходите к примеру протоколов, и установите в нем те же самые опции конфигурации.

Запрет IPv6. По умолчанию функция example_connect() ждет, пока не установится соединение Wi-Fi или Ethernet, и не будет получен IPv4-адрес и IPv6 link-local адрес. Если у вас сетевые окружения, где IPv6 link-local адрес не может быть получен, запретите опцию "Obtain IPv6 link-local address" в меню "Example Connection Configuration".

mDNS. IP-адрес устройства IoT может время от времени меняться, так что не практично хардкодить IP-адрес в web-странице. В этом примере используется mDNS для парсинга доменного имени esp-home.local, так что мы всегда можем получить доступ к web-серверу поэтому URL, не беспокоясь о реальном IP-адресе, который за ним скрывается. См. здесь для дополнительной информации об mDNS.

Замечание: mDNS установлена по умолчанию на большинстве операционных систем, или доступна как отдельный пакет.

Режим развертывания веб-страниц. В режиме разработки было бы ужасно неудобно прошивать все web-страницы каждый раз, когда мы обновляем файлы html, js или css. Так что очень рекомендуется развернуть web-страницу на хосте PC через технологию semihost. Всякий раз, когда браузер обращается к web-странице, ESP32 может перенаправить запрос к требуемым файлам, размещенным на хосте PC. Таким способом мы экономим время при разработке новых веб-страниц.

После разработки странички должны быть развернуты в одном из следующих мест:

SPI Flash - этот способ рекомендуется для небольшого web-сайта (что-то типа менее 2MB).
SD Card - вариант, когда размер сайта настолько большой, что не умещается на SPI (т. е. больше 2MB).

Фреймворк фронтэнда. В этом примере могут использоваться многие известные фреймворки (например Vue, React, Angular). Здесь просто используется Vue в качестве примера и адаптировали vuetify в качестве UI-библиотеки.

[Как использовать пример]

Необходимое железо. Для запуска этого примера нам нужна плата разработчика ESP32 dev (например ESP32-WROVER Kit, ESP32-Ethernet-Kit) или ESP32 core (например ESP32-DevKitC). Может также понадобиться дополнительный JTAG-адаптер, если вы решили развернуть web-сейт на основе семихостинга. Для дополнительной информации по поддерживаемому JTAG-адаптеру см. select JTAG adapter. Или если вы решили развернуть web-сайт на карте SD понадобится дополнительная плата со слотом SD.

Используемые выводы. Только если вы развертываете web-сайт на карте SD, используйте в этом примере следующие подключения.

ESP32	SD Card
GPIO2	D0
GPIO4	D1
GPIO12	D2
GPIO13	D3
GPIO14	CLK
GPIO15	CMD

[Конфигурация проекта]

Откройте меню конфигурации проекта (idf.py menuconfig).

В меню Example Connection Configuration:

Выберите сетевой интерфейс в опции Connect using, в зависимости от вашей платы. Сейчас поддерживается и Wi-Fi, и Ethernet.

Если вы выбрали интерфейс Wi-Fi то нужно установить:
Wi-Fi SSID и Wi-Fi password, по которым к точке доступа будет подключаться esp32.

Если вы выбрали интерфейс Ethernet, то нужно установить:
Модель PHY в опции Ethernet PHY, например IP101.
Адрес PHY в опции PHY Address, что определяется схемой вашей платы.
Режим тактирования (EMAC Clock mode), порт GPIO, используемый SMI.

В меню Example Configuration:

Установите доменное имя в опции mDNS Host Name.
Выберите режим развертывания в Website deploy mode, в настоящее время поддерживается развертывание web-сайта на хосте PC, карте SD и SPI Nor flash. Если вы выбрали Deploy website to host (JTAG is needed), то необходимо указать полный путь до web-сайта в Host path to mount (e.g. absolute path to web dist directory).
Установите точку монтирования web-сайта в опции Website mount point in VFS значение по умолчанию /www.

[Сборка и прошивка]

После того, как работа по разработке web-страниц завершена, скомпилируйте проект запуском команд:

cd path_to_this_example/front/web-demo npm install npm run build

ЗАМЕЧАНИЕ: этот пример нуждается в nodejs версии v10.19.0

Через некоторое время вы увидите директорию dist, которая содержит все файлы web-сайта (такие как html, js, css, картинки).

Запустите idf.py -p PORT flash monitor для сборки и прошивки проекта.

(Для выхода из serial monitor нажмите Ctrl-].)

См. Getting Started Guide для описания полных шагов по конфигурированию и использованию ESP-IDF при сборке проектов.

Дополнительные шаги для развертывания web-сайта через семихостинг. Понадобится последняя версия OpenOCD которая должна поддерживать фичу semihost, когда мы тестируем этот режим развертывания:

openocd-esp32/bin/openocd -s openocd-esp32/share/openocd/scripts -f board/esp32-wrover-kit-3.3v.cfg

[Просмотр web-страницы в браузере]

В вашем браузере введите URL веб-сайта (например http://esp-home.local). Вы также можете ввести IP-адрес, который получил ESP32, если ваша операционная система в настоящий момент не поддерживает службу mDNS.

Также этот пример разрешает фичу NetBIOS с доменным именем esp-home. Если в вашей OS включена поддержка NetBIOS (например в Windows есть изначально поддержка NetBIOS), то также будет работать URL http://esp-home.

[Вывод ESP monitor]

На страничке Light, после того как мы установим цвет и кликнем на кнопку check, браузер отправит post-запрос в ESP32, и в консоли просто увидим напечатанное значение color.

I (6115) example_connect: Connected to Ethernet
I (6115) example_connect: IPv4 address: 192.168.2.151
I (6325) esp-home: Partition size: total: 1920401, used: 1587575
I (6325) esp-rest: Starting HTTP Server
I (128305) esp-rest: File sending complete
I (128565) esp-rest: File sending complete
I (128855) esp-rest: File sending complete
I (129525) esp-rest: File sending complete
I (129855) esp-rest: File sending complete
I (137485) esp-rest: Light control: red = 50, green = 85, blue = 28

[Troubleshooting]

Error occurred when building example: ...front/web-demo/dist doesn't exit. Please run 'npm run build' in ...front/web-demo.

Когда вы выбрали развертывание web-сайта на SPI, убедитесь в наличии сгенерированной директории dist перед сборкой этого примера.

Функция example_connect, которая используется для организации сетевого интерфейса в примере restful_server, подключается в составе компонента protocol_examples_common. Этот компонент находится не в онлайн-реестре компонентов, он находится локально в каталоге среды разработки ESP-IDF.

Чтобы можно было использовать функцию example_connect, нужно вручную отредактировать файл idf_component.yml вашего проекта. Выполните следующие шаги по добавлению компонента protocol_examples_common:

1. Перейдите в директорию main вашего проекта. Если в ней нет файла idf_component.yml, то создайте его.

2. Откройте файл idf_component.yml в текстовом редакторе, и укажите в разделе зависимостей локальный путь до компонента:

Здесь `${IDF_PATH}` это переменная, которая автоматически укажет на директорию инсталляции вашей ESP-IDF.

3. Добавьте в свой код, где вызывается функция example_connect, подключение заголовочного файла protocol_examples_common.h:

В качестве примера файла idf_component.yml см. файл idf_component.yml в директории main проекта restful_server [2].

Для чего нужен компонент protocol_examples_common и последующие шаги. Компонент `protocol_examples_common` предоставляет вспомогательный код, упрощающий реализацию сетевых подключений в вашем проекте (обычно Wi-Fi или Ethernet). В нем содержится функция example_connect() (см. также врезку README.md выше), которая обрабатывает процесс соединения, используя опции, настроенные через `idf.py menuconfig`.

После того, как вы добавили в проект зависимость от компонента protocol_examples_common, сконфигурируйте ваш проект. Например, может понадобиться выбрать тип подключения и установить в случае использования Wi-Fi параметр SSID и password. Запустите `idf.py menuconfig`, перейдите в раздел настроек `Example Connection Configuration`, и введите нужные данные.

Альтернативный метод добавления кода с функцией example_connect: просто скопируйте всю папку protocol_examples_common из `$IDF_PATH/examples/common_components/` в директорию components, находящуюся в корне вашего проекта, и добавьте CMakeLists.txt настройки для компиляции необходимого кода protocol_examples_common.