| 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 перед сборкой этого примера.
