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

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

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

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

    from machine import UART

    uart = UART(1, 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位。

WiPy/CC3200：位数可为5、6、7、8。终止可为1或2。

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对象。

方法
-------

.. only:: port_wipy

    .. method:: UART.init(baudrate=9600, bits=8, parity=None, stop=1, \*, pins=(TX, RX, RTS, CTS))
    
       Initialise the UART bus with the given parameters:
    
         - ``baudrate`` is the clock rate.
         - ``bits`` is the number of bits per character, 7, 8 or 9.
         - ``parity`` is the parity, ``None``, 0 (even) or 1 (odd).
         - ``stop`` is the number of stop bits, 1 or 2.
         - ``pins`` is a 4 or 2 item list indicating the TX, RX, RTS and CTS pins (in that order).
           Any of the pins can be None if one wants the UART to operate with limited functionality.
           If the RTS pin is given the the RX pin must be given as well. The same applies to CTS. 
           When no pins are given, then the default set of TX and RX pins is taken, and hardware 
           flow control will be disabled. If pins=None, no pin assignment will be made.

.. 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()

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

.. only:: port_wipy

    .. method:: UART.irq(trigger, priority=1, handler=None, wake=machine.IDLE)

       Create a callback to be triggered when data is received on the UART.

           - ``trigger`` can only be ``UART.RX_ANY``
           - ``priority`` level of the interrupt. Can take values in the range 1-7.
             Higher values represent higher priorities.
           - ``handler`` an optional function to be called when new characters arrive.
           - ``wake`` can only be ``machine.IDLE``.

       .. note::

          The handler will be called whenever any of the following two conditions are met:

              - 8 new characters have been received.
              - At least 1 new character is waiting in the Rx buffer and the Rx line has been
                silent for the duration of 1 complete frame.

          This means that when the handler function is called there will be between 1 to 8 
          characters waiting.

       Returns an irq object.

    Constants
    ---------

    .. data:: UART.RX_ANY

        IRQ trigger sources