.. currentmodule:: machine
.. _machine.UART:

UART类 -- 双工串行通信总线
=============================================

UART实现标准UART / USART双向串行通信协议。其物理层包括两条线：RX和TX。通信单元是一个可为8位或9位宽的字符（请勿与字符串字符混淆）。

UART对象可使用下列方式创建并初始化::

    from machine import UART

    uart = UART(3, 9600)                         # init with given baudrate 使用给定波特率初始化
    uart.init(9600, bits=8, parity=None, stop=1) # init with given parameters 使用给定参数初始化

所支持的参数在一个板上有所不同:

Pyboard/OpenMVCam：位数可为7、8、9。终止可为1或2。当parity为None时，仅支持8位和9位。启用parity时，仅支持7位和8位。

UART对象的运行类似于流对象，其读写都使用标准流方法进行::

    uart.read(10)       # read 10 characters, returns a bytes object 读取10字符，返回一个字节对象
    uart.read()         # read all available characters 读取所有可用字符
    uart.readline()     # read a line 读取一个行
    uart.readinto(buf)  # read and store into the given buffer 读取并存入给定缓冲区
    uart.write('abc')   # write the 3 characters 写入3字符

构造函数
------------

.. class:: UART(id, ...)

   构造一个具有给定id的UART对象。

方法
-------

.. method:: UART.init(baudrate=9600, bits=8, parity=None, stop=1, \*, ...)

   用给定的参数初始化UART总线:

     - *baudrate* 是时钟速率。
     - *bits* 是每个字符的位数，7，8或9。
     - *parity* 是奇偶校验，``None``，0(偶数) 或 1(奇数)。
     - *stop* 是停止位的数目，1或2。

.. method:: UART.deinit()

   关闭UART总线。

.. method:: UART.any()

   返回一个整数，该整数即为在不阻塞情况下可读取的字符数。若无可用字符，则返回0,；若有可用字符，则返回一个正数。若有超过1个可读取字符，该方法则返回1。

   若对可用字符进行更复杂查询，请使用select.poll::

    poll = select.poll()
    poll.register(uart, select.POLLIN)
    poll.poll(timeout)

.. method:: UART.read([nbytes])

   读取字符。若指定 ``nbytes`` ，则最多读取该数量的字节。否则可读取尽可能多的数据。

   返回值：一个包括读入字节的字节对象。超时则返回 ``None`` 。

.. method:: UART.readinto(buf[, nbytes])

   将字节读取入 ``buf`` 。若指定 ``nbytes`` ，则最多读取该数量的字节。否则，最多读取 ``len(buf)`` 数量的字节。

   返回值：读取并存入 ``buf`` 的字节数；若超时则返回 ``None`` 。

.. method:: UART.readline()

   读取一行，并以一个换行符结束。

   返回值：读取的行；若超时，则返回 ``None`` 。

.. method:: UART.write(buf)

   将字节缓冲区写入总线。

   返回值：写入的字节数；若超时，则返回 ``None`` 。

.. method:: UART.sendbreak()

   在总线上发送一个中断状态。这使得总线在一段时间内保持低状态，其持续时间比字符的正常传输所需时间长。