STM32F4 USB RNDIS драйвер (управление устройством через Web-интерфейс)

в 14:33, , рубрики: C, dhcp, DNS, ethernet, lwip, rndis, STM32F4, STM32F4Discovery, usb, встраиваемые системы, гаджеты и девайсы, интерфейс, интерфейсы, клиент-сервер, контроллер, программирование микроконтроллеров, разработка, Сетевые технологии, стандарты, метки:

Доброе время суток, дорогие друзья!
Первым делом хотелось бы с лучшими пожеланиями поздравить всех с минувшими новогодними праздниками!
Ранее в статье была анонсирована разработка RNDIS USB драйвера для контроллеров серии STM32F4. С тех пор библиотека постепенно развивалась и нынче доросла до первой release-версии. Библиотека под названием LRNDIS (LWIP + RNDIS) позволяет нам создавать на базе контроллера STM32F4 как устройства класса USB «модем», так и любые другие устройства с управлением через web-интерфейс. Пример управления платой stm32f4-discovery из web-браузера на Android-планшете представлен на видео:

На странице видеоролика представлена ссылка на исходные коды и HEX-файл прошивки для платы discovery, с которым вы сможете повторить данный эксперимент. В статье рассказано о том, как и когда технология доступа через WEB-интерфейс полезна, а также — как работает библиотека LRNDIS для контроллеров STM32F4. Также присутствует обучающий материал о работе USB и устройстве Ethernet-сетей.

Предыстория создания библиотеки
image
Предыстория проекта весьма типовая. Стоял тёплый летний день. Гхм… Для заказчика стояла задача разработать устройство с сервисным интерфейсом управления.

Подробности

По мере развития прошивки было введено несколько команд управления по VCP-интерфейсу. Это значит, что после подключения USB-устройства в ОС создавался виртуальный COM-порт. Используя его, из пользовательского терминала передавались команды управления и диагностики. В ответ от устройства принимался статус выполнения и его текущее состояние.
Система вполне типовая с сервисной точки зрения: есть последовательный порт и набор команд для управления и диагностики.
Всё изменилось в короткий срок. По объективным причинам рос требуемый набор команд. Также понадобилась интерактивность вывода: некоторые параметры стало необходимо отображать в динамике. Как, например, показания магнитного датчика при проносе мимо него ферромагнетика. Для этого были введены дополнительные команды, которые, оперируя управляющими последовательностями, печатали информацию в пользовательском терминале с высокой периодичностью. Это создавало необходимое ощущение риалтаймовости наблюдения. Интерактивные команды оказались настолько удобными для инженеров, что некоторая часть команд позже была добавлена в соответствии с концепцией. И тут раздался треск. Требовалось поддержать сразу несколько групп команд: интерактивные, диагностические, команды управления. При этом периодический рефакторинг кода был связан с трудоёмкой правкой в большом количестве обрабатываемых команд. Ясно стало, что ещё должна быть пользовательская группа команд — для менее квалифицированного персонала, который будет просто следовать инструкциям по эксплуатации. Для них возникла идея написания клиентского терминала с кнопочками и флажочками… И вот тут возникли сомнения: стало ясно, что мы занимаемся сервисной частью, уделяя всё меньше внимания функциональности! А ведь пользовательская программа, запускаемая на клиентской ЭВМ, также должна обладать своими требованиями: кроссплатформенность и LTS (длительностью поддержки).
Устройство, предположим, мы закончили, а пользовательское ПО мы должны портировать и тестировать с каждой версией выпускаемых операционных систем! А как долго?
Так и родился вопрос — как избавиться от дополнительных трудозатрат?

Было принято решение использовать стандарты гарантированно длительной поддержки. Те стандарты, которые нам позволят создать клиентскую программу управления устройством, которая будет поддерживаться максимально полным набором операционных систем в настоящем и будущем времени. На первых парах были найдены недостатки популярных кроссплатформенных фрэймворков:
— java: необходимость наличия в ОС JVM, и вытекающий из противного предположения необходимость дистрибьюции виртуальной машины
— qt: периодическая необходимость версионного портирования и нюансы запуска под Android
Нет, эти сложности пугать не должны. Вопрос, пожалуй, только в трудочасах, которые мы, бывает, недооцениваем с учётом фактора длительной поддержки.
Так родилась идея сделать WEB-интерфейс для управления устройством. Он не требует разработки стороннего ПО, браузеры для отображения управляющей страницы есть во всех требуемых ОС. Потенциал оформления интерфейса огромный. Длительность поддержки в части стандартов http/html/js тоже не вызывает сомнений.
По замыслу, управление должно было работать следующим образом.
1. Подключаемое по USB устройство представляется сетевой картой
2. Клиентская ЭВМ (ПК или гаджет) получает IP-адрес для работы в сети нашего устройства
3. По запросу web-браузера на клиентской ЭВМ наше устройство отдаёт страницу
4. На странице присутствует информация о текущем состоянии и доступные элементы управления
5. При активации клиентом элементов управления, из браузера передаются соответствующие HTTP-запросы.
По сути, между браузером и устройством, ходят те же самые текстовые команды, но только в формате HTTP протокола.
Надо понимать, что это всего лишь один из вариантов из большого набора возможных решений. Он имеет свои плюсы и минусы. Так случилось, что сейчас к использованию web-интерфейсов прибегают производители в основном сугубо сетевых устройств: настройка модемов и роутеров. Посыл данной статьи — давайте применять то что, действительно, удобно. И давайте не бояться сложностей на пути: их преодоление сейчас нам сэкономит куда больше времени в будущем!

Сфера применения библиотеки
image
К сожалению, первый анонс в полной мере успешным не был, т.к. рассказ о сфере применения был упущен.
Попробуем немного наверстать упущенное и раскрыть эту тему.
Если мы находимся на этапе системного проектирования устройства, то следующие соображения могут склонить нас в сторону использования web-интерфейсов (вне зависимости от физического канала, Ethernet или USB):
1. Устройство должно иметь интерфейс управления и/или диагностики
2. Средства управления могут использоваться не только на этапе разработки, но и на этапе эксплуатации (ПО пользователя)
3. Квалификация пользователя может быть недостаточно высокой, что требует дружественный интерфейс управления
4. Способ «дружественного» управления должен быть доступен из под разных платформ и ОС
5. Соответствующие средства требуется поддерживать в рабочем состоянии длительное время
Дополнительным критерием может являться то, разрабатываем ли мы изначально сетевое устройство. А также: не будет ли (в противном случае) добавление в прошивку сетевого стека и web-сервера являться избыточным на фоне куда менее богатого функционала устройства. Иными словами, добавление web-интерфейса в контроллер управления лампочкой — очевидно, избыточное решение.
Если мы поверили в web-интерфейс, то следующие соображения, возможно, нам помогут в выборе физического канала связи (из Ethernet и USB перспективы).

Тип Внутрисхемное подключение Типовое применение
Ethernet Ethernet PHY контроллер — Промышленные устройства
— Бытовые устройства с сетевой функцией и доп. питанием
USB ULPI контроллер или прямое подключение к МК Бытовые и часть промышленных устройств. В особенности, если:
— устройства имеют не гарантированный источник питания (питание от батареи, например)
— устройства потенциально подключаемые к хосту только с USB интерфейсом (например, планшет)
— миниатюрный класс устройств

От себя добавлю — не смотря на все прелести, не посоветовал бы применять USB в промышленных узлах с требованием повышенной надёжности: часто встречается негативный опыт. Если альтернативы нет — то вопрос устойчивости требуется изучить досконально.
Исходя из приведённых пунктов, становится ясна сфера применения библиотеки: бытовые и часть промышленных устройств, которые:
— работают на базе МК STM32F4
— должны обладать дружественным интерфейсом управления
— должны управляться из под разного аппаратного и программного набора
— могут не иметь гарантированного источника питания
— должны иметь длительный период поддержки ПО управления
Возможных примеров использования технологии много даже вне области сугубо сетевых устройств.
К примеру, на данный момент есть планы по превращению stm32f4-discovery в инструмент любительской разработки с функциями портативного генератора/анализатора сигналов и осциллографа. Подключите такой помощник к телефону и посмотрите в динамике что происходит в интересующей вас цепи. Из бесплатных плюсов — не требуется собирать или устанавливать ПО; достаточно прошить HEX-файл и открыть браузер — в нём будут присутствовать все прелести GUI-интерфейса. На мой привередливый вкус — то что нужно. Конечно, инструмент не для профессиональной разработки, но известный интерес к нему присутствует.
Итак, надеюсь, разобрались. А теперь о том как работает библиотека.

Как оно работает
image
При ответе на этот вопрос спешить не будем. Человек, имеющий небольшой опыт взаимодействия с сетями, может вполне справедливо смутиться. Поэтому, касаясь того или иного протокола взаимодействия я буду также давать его краткое техническое описание на том уровне… которого когда-то не хватало самому.

Шаг 1. Подключаем USB-устройство.
Как говорилось раньше, на этом этапе наше устройство говорит хосту «я — сетевая карта!».
Хост (т.е. клиентская ЭВМ) после подключения к нему нашей поделки, начинает отправлять запросы.

Хосту требуется получить следующую информацию

— как изделие называется
— какой у изделия VID и PID (идентификаторы производителя и изделия, см. список)
— к какому классу и подклассу относится устройство
— по каким endpoint точкам и какими блоками следует обмениваться данными
Ну, и некоторую другую информацию. Конфигурационные пакеты при этом передаются по точке endpoint 0. Ответные пакеты от устройства с информацией о себе обычно называют «дескрипторы USB устройства».
Подробно ознакомиться о процессе опроса (энумерации) можно здесь.
Вообще, протокол USB достаточно богат… иногда даже кажется, что избыточно. Однако, это богатство вот уже много лет позволяет подключать совершенно разные устройства, даёт возможность передавать изохронные потоки, блоки данных, прерывания. В общем, всё необходимое, что может потребоваться широкому набору современных устройств. Обратная сторона медали — высокий порог входа в разработку USB-устройств.

После получения информации об устройстве, ОС хоста производит поиск подходящего драйвера для взаимодействия. В типовом случае, вроде flash-носителей (USB класс MSC) или клавиатуры с мышкой (HID класс), загружается стандартный для класса драйвер. В более «тяжёлом» случае, вроде нашей USB сетевой карты (CDC класс с RNDIS подклассом), операционная система поступает по усмотрению:
— ОС linux/android/mac, как правило, успешно пытается наладить типовой обмен
— ОС windows просит установить внешний драйвер
Наше устройство в первом случае работает сразу.
В случае ОС windows (позднее XP) можно установить стандартный драйвер фирмы Microsoft. Для Windows XP необходимо поставить inf-файл, доступный в репозитории библиотеки LRNDIS.

Шаг 2. Драйвер инициализирует RNDIS-устройство
На данной картинке изображён принцип связи с RNDIS устройством (ОС Windows).
image
Более подробно о нём можно почитать тут и там.
Если вкратце, то RNDIS протокол — это расширение NDIS для внешних устройств. Роль протокола — обеспечить поддержку PnP и обмен сетевыми пакетами. По сути своей, RNDIS — самостоятельный сетевой интерфейс, информационной нагрузкой которого являются кадры канального/сетевого уровней (Ethernet или IP кадры, опционально).
На приведённой схеме это реализует кубик «Минипорт Remote NDIS», который отвечает за:
— сервис общения (спросить у сетевого устройства его MAC-адрес, размер пакета, скорость работы и прочее)
— оборачивает отправляемые хостом сетевые пакеты в RNDIS заголовок
— транслирует принимаемые от устройства пакеты, выбрасывая RNDIS заголовок
Кубик «Минипорт Remote NDIS USB» отвечает за транзит RNDIS посылок, работая с драйвером USB шины.
На стороне контроллера STM32 за поддержку RNDIS протокола и работу с USB отвечает файл usbd_rndis_core.c. Он делает то же самое, что и «кубик» хоста «Минипорт Remote NDIS» — занимается приклеиванием/отклеиванием заголовков, а также отвечает на вопросы драйвера. Ответы, вроде MAC-адреса и скорости он берёт из файла usbd_rndis_core.h.
После успешной инициализации RNDIS драйвер Windows создаёт сетевой интерфейс, который в последствии отображается в «Центре управления сетями» и в области трей-индикатора.

Шаг 3. Получение IP-адреса
Итак, для чего нужна служба получения динамического адреса. Эта служба называется DHCP (протокол динамической настройки узла).
После того как хост инициализирует наше устройство, он создаёт сетевой интерфейс.

Сетевой интерфейс (если кто не знает)

Сетевой интерфейс — это программная сущность, предоставляющая доступ к ресурсам физической или виртуальной сети.
Чаще всего каждому сетевому интерфейсу хоста соответствует конкретный сетевой адаптер. Но есть множество других интерфейсов, вроде локальной петли или те, что служат для взаимодействия с виртуальной машиной. В их случае в сигнальном виде из хоста «ничего не выходит» — обмен происходит программным способом.
Каждому сетевому интерфейсу хоста должен быть сопоставлен хотябы один IP-адрес. По нему «жители сети» может обратиться к хосту.
Если «на проводе» адресовано несколько сетей (например, устройства с IP адресами 10.4.1.xx и 192.168.1.xx), то интерфейсу может назначаться два «личных» IP-адреса. Они могут выглядеть так: 10.4.1.151 и 192.168.1.200. Узнать набор сетевых интерфейсов и сопоставленных им IP-адресов в ОС Windows можно с помощью команды ipconfig и с помощью ifconfig в ОС Linux.
Для описания сетей/подсетей используется маска. Например, правильное описание сети 10.4.1.xx такое: сеть 10.4.1.0, маска 255.255.255.0. Либо, если 4-ёх байтовое число маски представить в двоичном виде и посчитать число ведущих едениц, то получится значение 24. Тогда сеть можно описать так: 10.4.1.0/24.
Подробнее об этом можно почитать в соответствующих источниках.

Известны две основные стратегии назначения IP-адреса интерфейсу: статический способ (когда пользователь сам прописывает адрес интерфейсу) и динамический (с помощью DHCP-службы).
Последний заключается в том, что при создании интерфейса на хосте активизируется служба DHCP-клиента. Она начинает посылать в сеть (конфигурация которой пока не известна) широковещательные пакеты по протоколу UDP, в надежде на то, что в сети присутствует DHCP-сервер.
image
Функция DHCP-сервера в общем, и в частности на нашем контроллере — ответить клиенту. В ответе контроллер «говорит»: клиент, ты в такой-то сети, держи такой-то IP-адрес, а ещё у нас имеется DNS-сервер с таким-то адресом.
После этого хост «чувствует себя» намного лучше: он назначает интерфейсу выданный IP-адрес и запоминает IP-адрес DNS-сервера.
Инициализация закончилась, теперь можно вводить имя страницы (run.stm) в браузере хоста.
Надо сказать, что поведение библиотеки LRNDIS настраивается. Службу DHCP-сервера можно исключить из сборки. Тогда на хосте придётся прописывать любой адрес, принадлежащий диапазону 192.168.7.(2-254). Такая сеть создаётся по умолчанию. Её параметры (192.168.7.0/24) также настраиваются. В примере клиенту выдаются адреса в диапазоне 192.168.7.2… 192.168.7.4 с временем лизинга 24 часа.
Более подробно по вопросу настройки библиотеки можно посмотреть в предыдущей статье.

Шаг 4. Загрузка страницы
Для загрузки страницы пользователь может ввести адрес нашего устройства 192.168.7.1 напрямую.
Однако, запоминать цифры не требуется, т.к. помимо DHCP-сервера, есть возможность собрать библиотеку с поддержкой DNS-сервера, функция которого — разрешать сетевые имена. В публикуемом примере DNS-сервер обучен разрешать имя ресурса «run.stm».
Поэтому, если в браузере написать run.stm, сетевая служба хоста отправит нашему (и не только) DNS-серверу запрос, в ответ на который сервер услужливо сообщит: доменному имени «run.stm» соответствует IP-адрес 192.168.7.1. Далее браузер хоста по известному адресу совершит TCP подключение с целью отправить HTTP запрос на получение корневой страницы.

Запрос и ответ между браузером Firefox и контроллером:
STM32F4 USB RNDIS драйвер (управление устройством через Web-интерфейс) - 6

История запросов при загрузке страницы:
STM32F4 USB RNDIS драйвер (управление устройством через Web-интерфейс) - 7

Из истории мы видим, что, после загрузки корневого HTML-документа браузер также загружает из контроллера другие два файла: discovery.svg и zepto.min.js. Первый — это изображение платы discovery. SVG формат выбран, т.к., являясь изображением векторной графики, мало занимает места в ПЗУ микроконтроллера. Скриптовый файл zepto.min.js включён, т.к. является урезанным аналогом знаменитого JQUERY. Надо заметить, что скрупулёзной экономии места в ПЗУ не производилось, т.к. не смотря на жертву в 35 Кб на все статические ресурсы, памяти контроллера ещё вполне достаточно. К тому же данный размер с дальнейшим увеличением сложности интерфейса обещает расти заметно медленней. Если же интерфейс разросся существенно — всегда есть выход хранить и отдавать статические ресурсы в сжатом виде — все известные браузеры на данный момент поддерживают декомпрессию «на лету».
Ещё один запрос, который отправляет браузер — это запрос /state.cgi. Он формируется скриптом из корневого HTML-документа с периодичностью 5 раз в секунду. Нужен запрос для получения в динамике текущего состояния устройства.
При приёме данного запроса, контроллер формирует и отвечает следующей строкой в JSON формате:

{ "systick": 9528746, "button": 0, "acc": [54, -288, 936], "leds": { "g": 0, "o": 0, "r": 0 } } 

Она и содержит все данные о текущем состоянии устройства, которые впоследствии отображаются на странице средствами JavaScript кода.
Ну и, пожалуй, последний момент в общении с браузером — способ управления.
В примере происходит управление тремя светодиодами. Например, при щелчке на флажок красного светодиода средствами JavaScript отправляется HTTP GET запрос с передачей параметра «r» и значения 0 или 1. Полностью запрос выглядит так: /ctl.cgi?r=1
Таким или альтернативными способами можно передавать любой набор данных, будь то логическое состояние 0/1, или значение текстового поля, или уведомление о нажатии кнопки. Красота подхода заключается в том, что программная логика вовсе может не знать о элементах управления, ибо получает строго формализованные управляющие сообщения. Также можно менять и отлаживать интерфейсную часть (HTML+JS) локально со всеми удобствами, после чего однократно заливать в составе прошивки в контроллер. Локальной web-разработкой, что не мало важно, может заниматься соответствующий специалист.

О стеке LWIP
Никакого сетевого обмена устроить бы не получилось, если бы не данный сетевой стек, который и был встроен в библиотеку.
Поскольку библиотека работает под «голым» железом (без ОС и динамической аллокации памяти), то надстройка в виде сокетов для использования недоступна. Написание сетевых приложений поэтому происходит с использованием сырого API стека. По этой теме, к счастью, в сети много информации.
Также в составе пакета contributions есть множество уже готовых решений. В том числе оттуда и был использован HTTP-сервер.
В прошлой статье я давал краткое описание стека и его настройки. На данный момент был уточнён набор важных для стека определений в файле

lwipopts.h

#define NO_SYS                          1
#define MEM_ALIGNMENT                   4
#define LWIP_RAW                        1
#define LWIP_NETCONN                    0
#define LWIP_SOCKET                     0
#define LWIP_DHCP                       0
#define LWIP_ICMP                       1
#define LWIP_UDP                        1
#define LWIP_TCP                        1
#define ETH_PAD_SIZE                    0
#define LWIP_IP_ACCEPT_UDP_PORT(p)      ((p) == PP_NTOHS(67))

#define MEM_SIZE                        10000
#define TCP_MSS                         (1500 /*mtu*/ - 20 /*iphdr*/ - 20 /*tcphhr*/)
#define TCP_SND_BUF                     (2 * TCP_MSS)

#define ETHARP_SUPPORT_STATIC_ENTRIES   1

#define LWIP_HTTPD_CGI                  1
#define LWIP_HTTPD_SSI                  1
#define LWIP_HTTPD_SSI_INCLUDE_TAG      0

Также была решена проблема с mem_malloc. Хоть текущая версия прошивки и не использует динамическую аллокацию, аппаратный крах при вызове mem_malloc держал настороже. Разрешилось добавлением определения MEM_ALIGNMENT, который раньше был обойдён вниманием.
По этой же причине стабильно заработал поддерживаемый сообществом HTTP-сервер, что и побудило отказаться от планов создания собственного.

Нерешённые вопросы
1. Ньюансы релицензирования стека lwip, который может иметь свои условия включения в состав другого ПО;
2. Доработка DNS-сервера для обработки «многовопросных» пакетов;

Вместо заключения
Благодарю читателя за терпение и надеюсь, что данная статья окажется для него полезной. Опубликованная в исходных кодах библиотека LRNDIS доступна для использования на правах MIT-лицензии. Считаю замечательным, если работа, на которую было уделено ощутимое время и запас сил, окажется полезной ещё кому-то. На худой конец, без использования открытых библиотек не получилось бы и этой.
В данный момент планируется поддержка библиотеки, поэтому за вопросами можно обращаться по адресу электронной почты fsenok@gmail.com.

Автор: fse

Источник

* - обязательные к заполнению поля


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js