Universal Asynchronous Receiver/Transmitter (UART) это периферийное устройство, которое обеспечивает последовательный обмен данными с такими интерфейсами, как RS232, RS422, RS485. UART предоставляет широко распространенный и дешевый метод реализации полнодуплексного обмена данными между различными устройствами.
Примечание: в этой статье приведен перевод главы, посвященной UART из документации [1]. Незнакомые термины и сокращения см. в Словарике, в конце статьи.
Чип ESP32 содержит на борту 3 контроллера (порта) UART, каждый из которых содержит идентичный набор регистров, чтобы упростить программирование и предоставить больше гибкости при использовании.
Каждый контроллер UART конфигурируется независимо от других такими параметрами, как скорость (baud rate), количество бит в кадре (data bit length), порядок следования бит (bit ordering), количество стоп-бит в кадре (number of stop bits), наличие бита четности и его значение (parity) и т. д. Все контроллеры совместимы с UART-устройствами от других производителей, и дополнительно могут поддерживать протоколы беспроводной связи инфракрасными лучами (Infrared Data Association protocols, IrDA).
[Обзор функционала UART]
В этой статье приведено описание установки связи между ESP32 и другими UART-устройствами с помощью функций и типов данных драйвера UART (перевод документации [1]). Обзор показывает типовое программирование, и разбит на отдельные секции:
1. Настройка коммуникационных параметров - baud rate, data bits, stop bits, и т. п. 2. Настройка ножек выводов. 3. Установка драйвера - выделение ресурсов ESP32 для драйвера UART. 4. Запуск обмена через UART - отправка / прием данных. 5. Использование прерываний для определенных событий коммуникаций. 6. Удаление драйвера - освобождение ресурсов, если обмен через UART больше не требуется.
Шаги 1 .. 3 выполняются на стадии конфигурирования проекта. Шаг 4 выполняется программой ESP32 в том месте, где UART запускается в работу. Шаги 5 и 6 не обязательны.
Функции драйвера UART идентифицируют каждый из контроллеров UART с помощью типа uart_port_t. Эта идентификация необходима для всех последующих вызовов функций.
Настройка коммуникационных параметров. Параметры можно настроить сразу за один шаг, либо последовательно, один за другим. Для настройки за 1 шаг нужно вызвать функцию uart_param_config() и передать ей номер контроллера UART и структуру параметров uart_config_t:
Примечание: более подробно про конфигурирование опций аппаратного управления потоком hardware flow control см. пример кода examples\peripherals\uart\uart_echo\ в каталоге установки ESP-IDF [2].
Конфигурирование каждого из параметров по одному осуществляется вызовом функций, показанных в таблице ниже. Эти функции полезны, когда нужно переконфигурировать одиночный параметр.
Таблица 1. Функции для индивидуальной конфигурации отдельных параметров UART.
Каждая из этих функций имеет функцию-комплемент с корнем _get_, предназначенный для проверки текущего установленного значения параметра. Например, чтобы проверить текущее установленное значение baud rate, вызовите функцию uart_get_baudrate().
Настройка ножек портов. После настройки параметров обмена сконфигурируйте физические выводы GPIO, через которые будут проходить сигналы UART. Для этого вызовите функцию uart_set_pin(), и укажите номера выводов портов GPIO, на которые драйвер должен вывести сигналы Tx, Rx, RTS и CTS. Если Вы хотите сохранить текущий выделенный номер вывода для определенного сигнала, то передайте макрос UART_PIN_NO_CHANGE.
Тот же самый макрос должен быть использован для выводов, которые не используются.
Установка драйвера. После того, как были настроены выводы для сигналов обмена, установите драйвер вызовом функции uart_driver_install(), и укажите следующие параметры:
● Размер кольцевого буфера передачи (Tx ring buffer) ● Размер кольцевого буфера приема (Rx ring buffer) ● Дескриптор очереди событий (event queue handle) и её размер ● Флаги для назначения прерывания
Эта функция выделит необходимые внутренние ресурсы для драйвера UART.
// Настройка буферизированного UART с очередью событий
// Установка драйвера UART с очередью событий:
ESP_ERROR_CHECK(uart_driver_install(UART_NUM_2, uart_buffer_size, \
uart_buffer_size, 10, &uart_queue, 0));
После того, как этот шаг выполнен, можно подключить внешнее UART-устройство и проверить обмен данными.
Запуск обмена данными. Прием и передача обрабатывается машиной состояний (finite state machine, FSM) каждого контроллера UART.
Процесс отправки данных включает следующие шаги:
1. Запись данных в буфер Tx FIFO (вызовом uart_write_bytes). 2. FSM преобразует данные в последовательность бит. 3. FSM отправляет данные.
Процесс приема похож на передачу, только последовательность шагов обратная:
1. FSM обрабатывает приходящую последовательность бит и преобразует её в параллельное представление данных. 2. FSM записывает данные в буфер Rx FIFO. 3. Чтение данных из буфера Rx FIFO (вызовом uart_read_bytes).
Таким образом, приложению нужно всего лишь записывать и считывать данные вызовами функций uart_write_bytes() и uart_read_bytes() соответственно, остальное берет на себя FSM.
Передача. После того, как данные были подготовлены для передачи, вызовите функцию uart_write_bytes(), и передайте в неё адрес буфера данных и длину этих данных. Функция скопирует данные в кольцевой буфер Tx (либо немедленно, либо после того, как в буфере окажется достаточно места), и сделает возврат. Когда освободится место в буфере Tx FIFO, обработчик прерывания (ISR) переместит данные из кольцевого буфера Tx в буфер Tx FIFO (это будет сделано в фоновом режиме, независимо от основных потоков выполнения программы). Ниже показан пример использования функции uart_write_bytes.
// Запись данных в UART.
char* test_str ="This is a test string.\n";
uart_write_bytes(uart_num, (constchar*)test_str, strlen(test_str));
Функция uart_write_bytes_with_break() работает подобно uart_write_bytes(), однако добавляет в конец передачи последовательный сигнал break (serial break signal). Такой сигнал обозначается удержанием линии Tx на лог. 0 в течение периода времени, большего чем длительность одного фрейма данных.
// Запись данных в UART с завершением сигналом break.
uart_write_bytes_with_break(uart_num,
"test break\n",
strlen("test break\n"),
100);
Существует другая функция для записи данных в буфер Tx FIFO: uart_tx_chars(). В отличие от uart_write_bytes(), эта функция не будет блокировать свое выполнение в ожидании появления доступного места. Вместо этого uart_tx_chars запишет все данные, которые сразу поместились в Tx FIFO, и возвратит количество записанных данных.
Есть функция-компаньон uart_wait_tx_done(), которая мониторит статус буфера Tx FIFO, и выполнит возврат, когда он опустошится.
Прием. Как только данные были приняты аппаратурой UART и сохранены в буфер Rx FIFO, их надо будет извлечь оттуда (прочитать) вызовом функции uart_read_bytes(). Перед чтение данных Вы можете проверить количество данных, доступных в буфере Rx FIFO, путем вызова uart_get_buffered_data_len(). Ниже показан пример использования этих функций.
Если данные в буфере Rx FIFO больше не нужны, то можно этот буфер очистить вызовом uart_flush().
Программное управление потоком. Если аппаратное управление потоком запрещено, Вы можете вручную устанавливать уровни сигналов RTS и DTR с помощью функций uart_set_rts() и uart_set_dtr() соответственно.
Выбор режима обмена данными. Контроллер UART поддерживает несколько режимов обмена (communication modes). Режим можно выбрать с помощью функции uart_set_mode(). Как только был выбран режим, драйвер UART будет соответствующим образом обрабатывать поведение подключенного устройства UART. В качестве примера, можно управлять микросхемой драйвера RS485 с помощью сигнала RTS, чтобы реализовать полудуплексный обмен данными интерфейса RS485.
// Настройка UART в полудуплексном режиме RS485
ESP_ERROR_CHECK(uart_set_mode(uart_num, UART_MODE_RS485_HALF_DUPLEX));
[Использование прерываний]
На различные состояния (события) UART и на обнаруженные ошибки могут быть сгенерированы прерывания. Полный список доступных прерываний предоставлен в техническом руководстве esp32_technical_reference_manual_en.pdf [3] (ESP32 Technical Reference Manual -> UART Controller (UART) -> UART Interrupts and UHCI Interrupts). Вы можете разрешить или запретить определенные прерывания вызовом функций uart_enable_intr_mask() или uart_disable_intr_mask() соответственно.
Функция uart_driver_install() устанавливает обработчик прерывания драйвера (ISR) для обслуживания кольцевых буферов Tx и Rx, и предоставляются высокоуровневые API-функции для обработки событий (см. далее).
API предоставляет удобный путь для обработки определенных прерываний, путем оборачивания их в выделенные функции:
● Детектирование события: определены несколько событий, определенных в перечислении uart_event_type_t, о которых может оповещаться приложение пользователя с использованием функционала очередей FreeRTOS. Вы можете разрешить этот функционал, когда вызываете uart_driver_install(), как это было описано выше в секции "Установка драйвера". Как использовать детектирование событий (event detection) можно найти в примере проекта examples\peripherals\uart\uart_events.
● Определение момента достижения порога места в FIFO или возникновения таймаута: буферы Tx и Rx FIFO могут вызывать прерывание, когда они были заполнены определенным количеством символов, или когда произошел таймаут при отправке или приеме данных. Для использования этих прерываний сделайте следующее:
- Сконфигурируйте соответствующе значения порога длины буфера и таймаута путем ввода их в структуру uart_intr_config_t, и вызова uart_intr_config(). - Разрешите прерывания с использованием функций uart_enable_tx_intr() и uart_enable_rx_intr(). - Запретите эти прерывания с использованием соответствующих функций uart_disable_tx_intr() и uart_disable_rx_intr().
● Детектирование последовательности (pattern detection): сработает прерывание, когда было определено появление повтора приема/передачи одного и того же символа (pattern) определенное количество раз. Эта функциональность демонстрируется в примере examples\peripherals\uart\uart_events. Это может использоваться, например, для детектирования строки команды, завершающейся определенным количеством одинаковых символов, которые добавлены в конец строки команды. Для использования pattern detection сделайте следующее:
- Сконфигурируйте и разрешите это прерывания с помощью uart_enable_pattern_det_intr(). - Запретите это прерывание с помощью uart_disable_pattern_det_intr().
Макросы. API также определяет несколько макросов. Нaпример, UART_FIFO_LEN определяет длину аппаратных буферов FIFO; UART_BITRATE_MAX дает максимальную скорость (baud rate) поддерживаемую контроллерами UART controllers, и т. д.
Удаление драйвера. Если обмен данными, установленный с помощью uart_driver_install(), больше не нужен, то драйвер можно удалить, чтобы освободить занимаемые им ресурсы, с помощью вызова uart_driver_delete().
[Обзор опций, специфичных для RS485]
В этой документации используется обозначение [UART_REGISTER_NAME].[UART_FIELD_BIT], чтобы ссылаться на поля и биты регистра UART. Для дополнительной информации по определенному биту опций см. техническое руководство esp32_technical_reference_manual_en.pdf [3] (ESP32 Technical Reference Manual -> UART Controller (UART) -> Register Summary. Используйте имя регистра (UART_REGISTER_NAME), чтобы найти описание регистра, и затем ищите в нем соответствующее поле/бит опции (UART_FIELD_BIT).
UART_RS485_CONF_REG.UART_RS485_EN: установка этого бита разрешает поддержку коммуникационного режима RS485.
UART_RS485_CONF_REG.UART_RS485TX_RX_EN: если этот бит установлен, то выходной сигнал передатчика логически замыкается на входной сигнал приемника (используется для самотестирования).
UART_RS485_CONF_REG.UART_RS485RXBY_TX_EN: если этот бит установлен, то передатчик будет отправлять данные, если приемник занят (автоматическое аппаратное устранение коллизий данных).
Аппаратура RS485 UART микроконтроллера ESP32 может детектировать коллизии сигнала во время передачи датаграммы, и генерировать прерывание UART_RS485_CLASH_INT, если это прерывание разрешено. Термин "коллизия" обозначает ситуацию, когда на линию вклиниваются одновременно 2 или более передатчиков, тем самым мешая друг другу, и тогда переданная датаграмма не соответствует принятой на противоположном конце канала связи. Коллизии могут происходить из-за наличия на шине нескольких не согласованных друг с другом передатчиков, или из-за ошибок шины.
Функция детектирования коллизий позволяет их обрабатывать, когда активировано и сработало прерывание коллизии. Прерывания UART_RS485_FRM_ERR_INT и UART_RS485_PARITY_ERR_INT могут использоваться вместе с функцией детектирования коллизии, чтобы в режиме RS485 контролировать ошибки фрейма и ошибки бита четности соответственно. Эта функциональность поддерживается в драйвере UART, и может быть использована путем выбора режима UART_MODE_RS485_APP_CTRL (см. описание функции uart_set_mode).
Функция детектирования коллизии может работать со схемой A и схемой C (см. далее секцию "Схемы интерфейса RS485"). В случае использования схемы A или B ножка RTS, подключенная к выводу DE драйвера шины, должна управляться приложением пользователя. Используйте функцию uart_get_collision_flag(), чтобы проверить, установлен ли флаг детектирования коллизии.
Сами по себе контроллеры ESP32 UART не поддерживают полудуплексный обмен данными, поскольку они не могут предоставить автоматическое управление ножкой RTS, подключенной ко входу ~RE/DE драйвера шины RS485. Однако полудуплексный обмен может быть реализован программно, путем управления ножкой RTS со стороны драйвера UART. Это можно разрешить установкой режима UART_MODE_RS485_HALF_DUPLEX, когда вызывается функция uart_set_mode().
Когда хост начинает записывать данные в буфер Tx FIFO, драйвер UART автоматически установит вывод RTS (в лог. 1); как только последний бит данных был передан, драйвер снимет сигнал с вывода RTS (лог. 0). Для использования этого режима программа должна запретить функцию аппаратного управления потоком. Этот режим работает со всеми схемами, показанными ниже.
Схемы интерфейса RS485. В этой секции приведено несколько примеров схем, демонстрирующих базовые моменты организации интерфейса ESP32 RS485.
Примечание: схемы, показанные ниже, не обязательно будут содержать все необходимые элементы. Микросхемы драйвера ADM483 и ADM2483 от компании Analog Devices приведены в качестве примера, и могут быть заменены на другие аналогичные трансиверы.
VCC ---------------+
|
+-------x-------+
RXD < ------| R |
| B|----------< > B
TXD ------->| D ADM483 |
ESP | | RS485 bus side
RTS ------->| DE |
| A|----------< > A
+----| /RE |
| +-------x-------+
| |
GND GND
Рис. 1. Схема A: детектирование коллизий.
Схема на рис. 1 предпочтительна, потому что она позволяет определять коллизии, и одновременно достаточно простая. Приемник в драйвере линии постоянно разрешен, что позволяет для UART мониторинг шины RS485. Подавление эхо производится периферийным устройством UART, когда установлен бит UART_RS485_CONF_REG.UART_RS485TX_RX_EN.
VCC ---------------+
|
+-------x-------+
RXD < ------| R |
| B|-----------< > B
TXD ------->| D ADM483 |
ESP | | RS485 bus side
RTS ---+--->| DE |
| | A|-----------< > A
+----| /RE |
+-------x-------+
|
GND
Рис. 2. Схема B: переключение прием/передача вручную, без детектирования коллизий.
Схема на рис. 2 не позволяет делать детектирование коллизий. Она подавляет null-байты, которые принимает аппаратура при установленном бите UART_RS485_CONF_REG.UART_RS485TX_RX_EN. Для этого случая бит UART_RS485_CONF_REG.UART_RS485RXBY_TX_EN неприменим.
Рис. 3. Схема C: автоматическое переключение с передатчик/приемник.
Это схема с гальванической развязкой, которая не нуждается в управлении ножкой RTS со стороны приложения или драйвера, потому что она автоматически управляет направлением работы трансивера. Однако она требует подавления null-байтов во время передачи путем установки бита UART_RS485_CONF_REG.UART_RS485RXBY_TX_EN в 1 и установки бита UART_RS485_CONF_REG.UART_RS485TX_RX_EN в 0. Эта настройка может работать в любом режиме RS485 UART, или даже в режиме UART_MODE_UART.
[Примеры приложений]
В таблице ниже показаны примеры проектов от компании Espressif, доступные в папке examples\peripherals\uart\ установленной среды разработки ESP-IDF [2].
Таблица 1. Краткое описание примеров для UART, поставляемых вместе со средой разработки ESP-IDF.
Пример кода
Описание
peripherals/uart/uart_echo
Конфигурирование настроек UART, установка драйвера UART, и демонстрация чтения/записи (используется UART1).
peripherals/uart/uart_events
Сообщает о различных событиях обмена (communication events), демонстрируются прерывания детектирования шаблона данных (pattern detection interrupt).
peripherals/uart/uart_async_rxtxtasks
Передача и прием данных в отдельных задачах FreeRTOS через один и тот же UART.
peripherals/uart/uart_select
Использование синхронного мультиплексирования I/O для файловых дескрипторов UART.
peripherals/uart/uart_echo_rs485
Настройка драйвера UART для обмена через интерфейс RS485 в полудуплексном режиме. Этот пример подобен peripherals/uart/uart_echo, однако позволяет осуществлять обмен через чип интерфейса RS485, подключенный к ножкам ESP32.
peripherals/uart/nmea0183_parser
Получение информации GPS путем парсинга операторов NMEA0183, принимаемых от приемника GPS через периферийное устройство UART.
[Справочник по API драйвера UART]
Заголовочный файл:
components/driver/include/driver/uart.h
Описание макросов, структур, определений типов для UART API см. в документации [1].
esp_err_tuart_driver_install (uart_port_t uart_num,
int rx_buffer_size,
int tx_buffer_size,
int queue_size,
QueueHandle_t *uart_queue,
int intr_alloc_flags);
Производит инсталляцию драйвера UART, и устанавливает конфигурацию по умолчанию для UART. UART ISR будет подсоединен к тому же самому ядру CPU, на котором эта функция была запущена.
Примечание: параметр rx_buffer_size должен быть больше, чем UART_FIFO_LEN. Параметр tx_buffer_size должен быть либо 0, либо больше чем UART_FIFO_LEN.
Возвращаемые значения
ESP_OK успешный возврат ESP_FAIL ошибка параметра
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). rx_buffer_size: размер кольцевого буфера UART RX. tx_buffer_size: размер кольцевого буфера UART TX. Если установлен в 0, то драйвер не использует буфер TX, функция передачи будет блокировать задачу, когда отправляются данные. queue_size: размер/глубина очереди событий UART. uart_queue: дескриптор UART событий очереди (выходной параметр). В случае успеха сюда записывается новый дескриптор очереди, чтобы можно было обрабатывать события UART путем блокировки задачи на очереди. Если установлен в NULL, то драйвер не использует очередь событий. intr_alloc_flags: флаги, используемые для выделения прерывания. Сюда устанавливают одно или несколько объединенных операцией OR значений констант ESP_INTR_FLAG_*. Для дополнительной информации см. esp_intr_alloc.h. Не используйте здесь ESP_INTR_FLAG_IRAM (ISR драйвера UART не находится в IRAM).
Запрашивает конфигурацию количество бит данных во фрейме UART.
Возвращаемые значения
ESP_OK успешный возврат, результат будет помещен в ячейку памяти *data_bit ESP_FAIL ошибка параметра
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). data_bit: указатель на ячейку памяти, которая примет количество бит данных UART.
Запрашивает конфигурацию количества стоп-бит UART.
Возвращаемые значения
ESP_OK успешный возврат, результат будет помещен в ячейку памяти *stop_bit ESP_FAIL ошибка параметра
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). stop_bits: указатель на ячейку памяти, которая примет количество стоп-бит UART.
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). parity_mode: одно из значений перечисления, обозначающее режим проверки четности бит фрейма.
Запрашивает конфигурацию режима проверки четности фрейма UART.
Возвращаемые значения
ESP_OK успешный возврат, результат будет помещен в ячейку памяти *parity_mode ESP_FAIL ошибка параметра
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). parity_mode: указатель на ячейку памяти, которая примет режим проверки четности бит данных UART.
Запрашивает конфигурацию установленной скорости UART.
Возвращаемые значения
ESP_OK успешный возврат, результат будет помещен в ячейку памяти *baudrate ESP_FAIL ошибка параметра
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). baudrate: указатель на ячейку памяти, которая примет установленное значение скорости UART.
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). inverse_mask: определяет сигналы, которые должны быть инвертированы. Здесь используется маска, составленная из объединенных операцией OR значений uart_signal_inv_t.
Устанавливает аппаратное управление потоком данных (hardware flow control).
Возвращаемые значения
ESP_OK успешный возврат ESP_FAIL ошибка параметра
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). flow_ctrl: режим для hardware flow control. rx_thresh: порог срабатывания Hardware RX flow control (0 .. UART_FIFO_LEN). Значение rx_thresh устанавливается только если установлен UART_HW_FLOWCTRL_RTS.
Устанавливает программное управление потоком данных (software flow control).
Возвращаемые значения
ESP_OK успешный возврат ESP_FAIL ошибка параметра
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). enable: устанавливает, разрешено ли программное управление потоком (==true), или нет (==false). rx_thresh_xon: нижний порог срабатывания (low water mark). rx_thresh_xoff: верхний порог срабатывания (high water mark).
Запрашивает конфигурацию аппаратного управления потоком данных UART.
Возвращаемые значения
ESP_OK успешный возврат, результат будет помещен в ячейку памяти *flow_ctrl ESP_FAIL ошибка параметра
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). flow_ctrl: указатель на ячейку памяти, которая примет значение опции управления потоком.
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). enable_mask: битовая маска для прерываний, которые должны быть разрешены.
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). disable_mask: битовая маска для прерываний, которые должны быть запрещены.
esp_err_tuart_set_pin (uart_port_t uart_num,
int tx_io_num,
int rx_io_num,
int rts_io_num,
int cts_io_num);
Назначает сигналы периферийного устройства UART на определенные ножки GPIO.
Если номер GPIO, сконфигурированный для сигнала UART, совпадает с одним из сигналов IOMUX для этого сигнала GPIO, то этот сигнал будет подключен напрямую через IOMUX. Иначе GPIO и назначаемый сигнал будет подключаться через GPIO Matrix. Например, если ESP32 вызовет uart_set_pin (0, 1, 3, -1, -1), то поскольку GPIO1 это ножка TX по умолчанию для UART0, и GPIO3 это ножка по умолчанию RX для UART0, они оба будут подключены соответственно к U0TXD и U0RXD через IOMUX, полностью пропуская матрицу перенаправления GPIO. Проверка направления коммутации сигналов происходит для каждой ножки. Таким образом, можно сигнал RX привязать к ножке GPIO через матрицу GPIO, в то время как сигнал TX привязан к ножке GPIO через IOMUX.
Примечание: внутренний выходной сигнал может быть выведен на несколько контактов GPIO. Входной сигнал можно подключить только к одному контакту GPIO.
Возвращаемые значения
ESP_OK успешный возврат ESP_FAIL ошибка параметра
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). tx_io_num: номер ножки порта GPIO для сигнала TX. rx_io_num: номер ножки порта GPIO для сигнала RX. rts_io_num: номер ножки порта GPIO для сигнала RTS. cts_io_num: номер ножки порта GPIO для сигнала CTS.
esp_err_tuart_set_rts (uart_port_t uart_num, int level);
Установка сигнала RTS вручную. Для использования этой функции UART должен быть сконфигурирован с запретом аппаратного управления потоком.
Возвращаемые значения
ESP_OK успешный возврат ESP_FAIL ошибка параметра
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). level: значение 1 соответствует лог. 0 на на выходе RTS (активный уровень, передача разрешена), значение 0 соответствует лог. 1 на выходе RTS (блокировка передачи).
esp_err_tuart_set_dtr (uart_port_t uart_num,
int level);
Установка сигнала DTR вручную.
Возвращаемые значения
ESP_OK успешный возврат ESP_FAIL ошибка параметра
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). level: значение 1 соответствует лог. 0 на на выходе DTR, значение 0 соответствует лог. 1 на выходе DTR.
Установит интервал ожидания UART после опустошения FIFO передачи.
Возвращаемые значения
ESP_OK успешный возврат ESP_FAIL ошибка параметра
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). idle_num: интервал idle, после опустошения tx FIFO (единица интервала это время отправки одного бита с текущей установленной скоростью baudrate).
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). uart_config: указатель на структуру с заполненными параметрами настройки UART.
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). intr_conf: указатель на структуру с заполненными параметрами настройки прерываний UART.
Посылает данные буфера в порт UART. Эта функция не ожидает достаточного количества места в TX FIFO. Она просто заполнит свободное пространство TX FIFO передаваемыми данными, и сделает возврат.
Примечание: эта функция должна использоваться только когда не разрешен буфер UART TX.
Возвращаемые значения
(-1): ошибка параметра. Другие значения (>=0): количество байт, которые функции удалось протолкнуть в TX FIFO.
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). buffer: адрес буфера данных. len: длина данных для отправки в байтах.
Посылает данные буфера в порт UART. Если параметр tx_buffer_size драйвера UART установлен в 0, то эта функция не будет выполнять возврат управления, пока все данные не будут отправлены, либо как минимум не будут отправлены все данные, которые удалось протолкнуть в TX FIFO.
Иначе, если tx_buffer_size > 0, то эта функция возвратит управление после копирования все данных данных в кольцевой буфер передачи, затем UART ISR будет постепенно перемещать эти данные из кольцевого буфера в TX FIFO.
Возвращаемые значения
(-1): ошибка параметра. Другие значения (>=0): количество байт, которые функции удалось протолкнуть в TX FIFO.
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). src: адрес буфера данных. size: длина данных для отправки.
intuart_write_bytes_with_break (uart_port_t uart_num,
constvoid*src,
size_t size,
int brk_len);
Посылает данные буфера в порт UART. Если параметр tx_buffer_size драйвера UART установлен в 0, то эта функция не будет выполнить возврат, пока не будут переданы все данные и сигнал break. После того, как все данные отправлены, посылается сигнал break.
Иначе, если tx_buffer_size > 0, эта функция сделает возврат после копирования всех данных в кольцевой буфер передачи, затем UART ISR будет постепенно перемещать данные из кольцевого буфера в TX FIFO. После того, как все данные отправлены, посылается сигнал break.
Возвращаемые значения
(-1): ошибка параметра. Другие значения (>=0): количество байт, которые функции удалось протолкнуть в TX FIFO.
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). src: адрес буфера данных. size: длина данных для отправки. brk_len: длительность сигнала break (единицы: время, которое занимает отправка одного бита на текущей скорости передачи).
(-1): ошибка параметра. Другие значения (>=0): количество байт, которые прочитаны в из RX FIFO.
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). buf: указатель на буфер. length: длина данных. ticks_to_wait: sTimeout, в тиках RTOS.
Псевдоним для uart_flush_input. Сброс содержимого кольцевого буфера UART. Этот вызов отбросит все данные из буфера UART RX.
Вместо ожидания завершения отправки данных эта функция очистит буфер приема UART. Чтобы отправить все данные TX FIFO, мы можем использовать функцию uart_wait_tx_done.
Возвращаемые значения
ESP_OK успешный возврат ESP_FAIL ошибка параметра
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1).
Очищает входной буфер, все данные в кольцевом буфере отбрасываются. Чтобы отправить все данные TX FIFO, мы можем использовать функцию uart_wait_tx_done.
Возвращаемые значения
ESP_OK успешный возврат ESP_FAIL ошибка параметра
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1).
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). size: указатель на ячейку памяти, куда будет записано количество закешированных данных.
esp_err_tuart_enable_pattern_det_intr (uart_port_t uart_num,
char pattern_chr,
uint8_t chr_num,
int chr_tout,
int post_idle,
int pre_idle);
Разрешение функции детектирования шаблона (паттерн). Разработана для приложений наподобие обработчика команд AT. Когда аппаратура детектирует последовательность одного и того же символа, сработает прерывание.
Примечание: эта функция работает только для esp32. И эта функция устарела, используйте вместо неё uart_enable_pattern_det_baud_intr.
Возвращаемые значения
ESP_OK успешный возврат ESP_FAIL ошибка параметра
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). pattern_chr: символ шаблона. chr_num: количество символов, 8-битное значение. chr_tout: интервал таймаута между каждым символом шаблона. 24-битное значение, единицы длительность периода частоты тактов APB (80 МГц). Когда длительность интервала меньше этого значения, функция не возьмет эти данные в качестве символа at_cmd. post_idle: время ожидания после последнего символа шаблона. 24-битное значение, единицы длительность периода частоты тактов APB (80 МГц). Когда длительность интервала меньше этого значения, функция не возьмет предыдущие данные в качестве последнего символа at_cmd. pre_idle: время ожидания перед первым символом шаблона. 24-битное значение, единицы длительность периода частоты тактов APB (80 МГц). Когда длительность интервала меньше этого значения, функция не возьмет эти данные в качестве первого символа at_cmd.
Запрет функции детектирования паттерна. Разработана для приложений наподобие обработчика команд AT. Когда аппаратура детектирует последовательность одного и того же символа, сработает прерывание.
Возвращаемые значения
ESP_OK успешный возврат ESP_FAIL ошибка параметра
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1).
Возвратит самую ближайшую позицию детектированного шаблона в буфере. Позиции детектированного шаблона сохраняются в очередь, эта функция будет извлекать первую позицию шаблона из очереди, и переместит текущий указатель в буфере в следующую позицию шаблона.
Следующие API-функции будут модифицировать информацию позиции шаблона: uart_flush_input, uart_read_bytes, uart_driver_delete, uart_pop_pattern_pos. В зоне ответственности приложения гарантировать атомарность доступа к очереди шаблона и буферу приема данных, когда используется функция детектирования шаблона.
Примечание: если буфер RX полон, и управление потоком не разрешено, то из-за переполнения детектированный шаблон может не оказаться в буфере приема.
Возвращаемые значения
(-1): не найден шаблон для текущего индекса, или ошибка параметра. Другие значения: позиция шаблона в буфере приема.
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1).
Возвратит самую ближайшую позицию детектированного шаблона в буфере. Позиции детектированного шаблона сохраняются в очередь, эта функция будет извлекать первую позицию шаблона из очереди. Эта функция ничего не делает с очередью
Следующие API-функции будут модифицировать информацию позиции шаблона: uart_flush_input, uart_read_bytes, uart_driver_delete, uart_pop_pattern_pos. В зоне ответственности приложения гарантировать атомарность доступа к очереди шаблона и буферу приема данных, когда используется функция детектирования шаблона.
Примечание: если буфер RX полон, и управление потоком не разрешено, то из-за переполнения детектированный шаблон может не оказаться в буфере приема.
Возвращаемые значения
(-1): не найден шаблон для текущего индекса, или ошибка параметра. Другие значения: позиция шаблона в буфере приема.
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1).
esp_err_tuart_pattern_queue_reset (uart_port_t uart_num, int queue_length);
Выделяет новую память указанной длины, чтобы сохранить запись позиции детектированного шаблона в буфере приема.
Возвращаемые значения
ESP_ERR_NO_MEM: недостаточно памяти ESP_ERR_INVALID_STATE: драйвер не установлен ESP_FAIL: ошибка параметра ESP_OK: успешное завершение
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). queue_length: максимальная длина очереди для детектированного шаблона. Если длина очереди недостаточна, то некоторые позиции шаблонов могут быть потеряны. Установите это значение в максимальное количество шаблонов, которые могут быть сохранены в буфере данных одновременно.
esp_err_tuart_set_rx_full_threshold (uart_port_t uart_num, int threshold);
Установит значение порога заполненности RX FIFO.
Примечание: если приложение использует высокие скорости обмена, и наблюдается ситуация, что перезаписываются байты в аппаратном RX FIFO, то этот порог может быть уменьшен.
Возвращаемые значения
ESP_OK: успешное завершение ESP_ERR_INVALID_ARG: ошибка параметра ESP_ERR_INVALID_STATE: не был инсталлирован драйвер
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). threshold: значение порога заполненности буфера приема, выше которого генерируется прерывание RX FIFO full.
esp_err_tuart_set_tx_empty_threshold (uart_port_t uart_num, int threshold);
Установит значение порога опустошения TX FIFO.
Возвращаемые значения
ESP_OK: успешное завершение ESP_ERR_INVALID_ARG: ошибка параметра ESP_ERR_INVALID_STATE: не был инсталлирован драйвер
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). threshold: значение порога опустошенности буфера передачи, ниже которого генерируется прерывание TX FIFO empty.
Установит порог таймаута приема UART для функции TOUT.
Возвращаемые значения
ESP_OK: успешное завершение ESP_ERR_INVALID_ARG: ошибка параметра ESP_ERR_INVALID_STATE: не был инсталлирован драйвер
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). tout_thresh: этот параметр определяет порог таймаута в периодах символа. Максимальное значение для порога составляет 126. Значение tout_thresh = 1, определяет таймаут прерывания TOUT, равный времени передачи одного символа (~11 бит) на текущей скорости передачиe. Если это время истекло, то генерируется прерывание UART_RXFIFO_TOUT_INT. Если tout_thresh == 0, то функция TOUT запрещена.
Возвратит флаг детектирования коллизии для режима RS485 и запишет его в переменную, на которую указывает collision_flag. *collision_flag = true, если была детектирована коллизия, иначе вернет false. Эта функция должна выполняться, когда завершена актуальная передача (после uart_write_bytes()).
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). collision_flag: указатель на ячейку типа bool для возврата флага коллизии.
esp_err_tuart_set_wakeup_threshold (uart_port_t uart_num, int wakeup_threshold);
Устанавливает количество перепадов сигнала на ножке RX для пробуждения из легкого режима сна (light sleep wakeup).
UART может использоваться для вывода системы из light sleep. Эта функция работает путем подсчета количества количества положительных перепадов на ножке RX и сравнение этого количества с порогом. Когда счетчик превысит порог, система выйдет из режима легкого сна (light sleep). Эта функция установит значение порога.
Стоп-бит и бит четности (если он разрешен) также участвуют в подсвете количества перепадов. Например, буква 'a' с кодом ASCII 97 кодируется как 0100001101 на линии RX (при конфигурации 8n1), включая биты start и stop. У этой последовательности 3 положительных перепада (переходов 0 -> 1). Таким образом, чтобы система пробуждалась от отправки символа ‘a’, установите wakeup_threshold=3.
Символ, который вызвал пробуждение, не будет принят аппаратурой UART (т. е. его нельзя будет извлечь из RX FIFO). В зависимости от установленной скорости, несколько символов после этого символа также могут быть пропущена. Обратите внимание, что когда чип входит в режим light sleep и выходит из него, меняется частота APB. Убедитесь, что UART все время настроен на корректную скорость, выберите REF_TICK в качестве источника тактирования UART путем установки поля use_ref_tick структуры uart_config_t в true.
Примечание: в ESP32 сигнал пробуждения от UART0, UART1 может быть введен только через IO_MUX (т. е. ножка GPIO3 должна быть сконфигурирован как function_1, чтобы пробуждать UART0, ножка GPIO9 сконфигурирована как function_5 для пробуждения UART1), и UART2 не поддерживает функцию light sleep wakeup.
Возвращаемые значения
ESP_OK: успешное завершение ESP_ERR_INVALID_ARG: если uart_num некорректен, или wakeup_threshold выходит за пределы диапазона [3, 0x3ff].
Параметры
uart_num: номер порта UART (UART0 или UART1). wakeup_threshold: количество перепадов сигнала RX для пробуждения из легкого сна, значение в диапазоне 3 .. 0x3ff.
Запрашивает количество перепадов сигнала RX для вывода системы из легкого сна. См. описание этой функции выше во врезке по функции uart_set_wakeup_threshold.
Возвращаемые значения
ESP_OK: успешное завершение ESP_ERR_INVALID_ARG: если out_wakeup_threshold == NULL
Параметры
uart_num: номер порта UART (UART0 или UART1). out_wakeup_threshold: указатель, куда будет записано текущее значение порога пробуждения для указанного UART.
Конфигурирует обратное перенаправление сигнала передачи TX на сигнал RX (loop back), только для целей тестирования.
Возвращаемые значения
ESP_OK: успешное завершение ESP_ERR_INVALID_ARG: ошибка параметра ESP_FAIL: не был инсталлирован драйвер
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). loop_back_en: установите в trure для разрешения функции loop back, или установите его в false.
Конфигурирует поведение прерывания таймаута приема.
Когда параметр always_rx_timeout == true, сработает прерывание, даже если FIFO заполнен. Эта функция может вызывать дополнительные прерывания таймаута, инициируемые только для события таймаута отправки. Вызовите эту функцию только если хотите гарантировать, чтобы прерывание таймаута всегда происходило после потока байтов.
Параметры
uart_num: номер порта UART, диапазон возможных значений 0 .. (UART_NUM_MAX-1). always_rx_timeout_en: установка в false разрешает поведение по умолчанию прерывания таймаута, установка в true приведет к тому, что прерывание таймаута будет срабатывать всегда.
[Словарик]
APB Advanced Peripheral Bus.
ISR Interrupt Service Handler, обработчик прерывания.
MUX мультиплексор.
[Ссылки]
1. ESP32 Universal Asynchronous Receiver/Transmitter (UART) site:docs.espressif.com. 2. Установка среды разработки ESP-IDF для ESP32. 3. ESP32 Technical Reference Manual site:docs.espressif.com.
