:mod:`pyb` --- 板级功能
=============================================

.. module:: pyb
   :synopsis: 板级功能

``pyb`` 模块包含与插件相关的特定函数。

时间相关函数
----------------------

.. function:: delay(ms)

   延迟给定的毫秒数。

.. function:: udelay(us)

   延迟给定的微秒数。

.. function:: millis()

   插件重置后，返回毫秒数。

   结果通常是一个Micropython小整数(31位有号数)，因此在2^30毫秒(约12.4天)后，这一数值将开始返回负数。

   注意：若 `pyb.stop()` 发布，支持该功能的硬件计数器将在休眠状态期间暂停。这将影响 `pyb.elapsed_millis()` 的结果。


.. function:: micros()

   插件重置后，返回微秒数。

   结果通常是一个Micropython小整数(31位有号数)，因此在2^30微秒(约17.8分钟)后，这一数值将开始返回负数。

   注意：若 `pyb.stop()` 发布，支持该功能的硬件计数器将在休眠状态期间暂停。这将影响 `pyb.elapsed_micros()` 的结果。


.. function:: elapsed_millis(start)

   返回 ``start`` 后消耗的毫秒数。
   
   这个函数负责计数器换行，且总是返回一个正数。也就是说，该函数可用来测量长约12.4天的周期。

   例::

       start = pyb.millis()
       while pyb.elapsed_millis(start) < 1000:
           # Perform some operation 执行一些操作

.. function:: elapsed_micros(start)

   返回 ``start`` 后消耗的微秒数。

   这个函数负责计数器换行，且总是返回一个正数。也就是说，该函数可用来测量长约17.8分钟的周期。

   例::

       start = pyb.micros()
       while pyb.elapsed_micros(start) < 1000:
           # Perform some operation 执行一些操作
           pass 通过

复位相关的函数
-----------------------

.. function:: hard_reset()

   以类似于按下外部RESET按钮的方式重置pyboard或OpenMV Cam。

.. function:: bootloader()

   在不使用BOO T*引脚的情况下激活引导加载程序。

.. function:: fault_debug(value)

   启用或禁用硬故障调试。硬故障即发生在底层系统中的严重错误，例如内存访问失效。

   若value参数为 ``False`` ，则板子会在出现硬故障时自动重设。

   若value参数为 ``True`` ，板子出现硬故障时，则将打印寄存器和堆栈追踪，并无限循环LED。

   禁用默认值，即自动重设。

中断相关的函数
---------------------------

.. function:: disable_irq()

   禁用中断请求。返回先前的IRQ状态： ``False`` / ``True`` （分别为禁用/启用IRQs）。这个返回值可被传递，以启用IRQ，使IRQ返回初始状态。

.. function:: enable_irq(state=True)

   启用中断请求。
   若 ``state`` 为 ``True``（默认值），则启用IRQ。该函数的最广泛应用为传递由 ``disable_irq`` 返回的值，以退出临界区。

电源相关函数
-----------------------

.. function:: wfi()

   等待内部或外部中断。

   此处执行 ``wfi`` 指令，在任何中断（无论是内部或外部）出现前，该指令将减低MCU的能耗。此时将继续执行该指令。注意：系统节拍每毫秒（1000Hz）中断一次，因此该功能的停滞最长可达1毫秒。

.. function:: stop()

   将Pyboard或OpenMV Cam设置在睡眠状态。

   该设置将能耗降低到500uA以下。退出睡眠状态需外部中断或实时闹钟。退出睡眠状态后，系统将继续完成因睡眠而中止的任务。

       见 :meth:`rtc.wakeup` 配置一个实时时钟唤醒事件。

.. function:: standby()

   将OpenMV Cam设置在深度睡眠状态。

   该设置将能耗降低到50uA以下。
   从这个睡眠状态唤醒需要一个实时时钟事件。

   见 :meth:`rtc.wakeup` 配置一个实时时钟唤醒事件。

其他功能
-----------------------

.. function:: have_cdc()

   如果USB作为串行设备连接，则返回True，否则返回False。

   .. note:: 此功能已弃用。使用pyb.USB_VCP().isconnected()来代替。

.. function:: hid((buttons, x, y, z))

   采用4元组（或列表）并将其发送到USB主机（PC）以发出HID鼠标移动事件的信号。

   .. note:: 此功能已弃用。使用 :meth:`pyb.USB_HID.send()` 来代替。


.. function:: info([dump_alloc_table])

   打印插件信息。

.. function:: main(filename)

   设置boot.py完成后要运行的主脚本的文件名。 如果未调用此函数，则将执行默认文件main.py。

   只在boot.py中调用此函数才有意义。

.. function:: mount(device, mountpoint, *, readonly=False, mkfs=False)

  .. note:: 这个函数是不推荐的。安装和卸载设备应由 :meth:`uos.mount` 和 :meth:`uos.umount`来执行。
      
   挂载一个块设备并使其作为文件系统的一部分运行。 ``device`` 须为一个提供块协议的对象：
   （以下内容也不推荐。见 :class:`uos.AbstractBlockDev` 获取创建块设备的正确方法。)

    - ``readblocks(self, blocknum, buf)``
    - ``writeblocks(self, blocknum, buf)``  (任选)
    - ``count(self)``
    - ``sync(self)``  (任选)

   ``readblocks`` 和 ``writeblocks`` 应从设备上的块数量 ``blocknum`` 开始，
   在 ``buf`` 和块设备之间复制数据。 ``buf`` 为一个长度为512的字节数组。
   若 ``writeblocks`` 未定义，则设备为只读的。这两个函数的返回值被忽略。


   ``count`` 应返回设备上可用的块数。 ``Sync`` 若运行，应同步设备上的数据。

   参数 ``mountpoint`` 是在文件系统的根目录下安装设备的位置。该参数应以斜杠开始。

   若 ``readonly`` 为 ``True``，则设备为只读，否则为可读写。

   若 ``mkfs`` 为 ``True`` ，且尚不存在文件系统，则会创建一个新文件系统。

   卸载设备，只需将设备设置为 ``None`` ，并将挂载位置设置为 ``mountpoint`` 。

.. function:: repl_uart(uart)

   在REPL重复之处，获取或设置UART对象。

.. function:: rng()

   返回一个硬件产生的30位随机数值。

.. function:: sync()
 
   同步所有文件系统。

.. function:: unique_id()

   返回一个12字节的字符串（96位），即MCU的唯一ID。

.. function:: usb_mode([modestr], port=-1, vid=0xf055, pid=-1, msc=(), hid=pyb.hid_mouse, high_speed=False)

   若无参数调用，则作为字符串返回当前USB。

   若使用给定 *modestr* 调用，则尝试设置USB模式。
   以下的 *modestr* 值被理解:

   - ``None``: 禁用USB
   - ``'VCP'``: 使用VCP接口启用（虚拟COM端口）
   - ``'VCP+MSC'``: 使用VCP和MSC启用（大容量存储设备类）
   - ``'VCP+HID'``: 使用VCP和HID启用（人工接口设备）
   - ``'VCP+MSC+HID'``: 启用 VCP、MSC 和 HID（仅在 PYBD 板上可用）

   为了向后兼容， ``CDC`` 被理解为 ``VCP`` （对于 ``CDC+MSC`` 和 ``CDC+HID`` 也类似）。

   *port* 参数应该是一个整数 (0, 1, ...)，如果板子支持多个端口，则选择要使用的 USB 端口。值 -1 使用默认或自动选择的端口。

   ``vid`` 和 ``pid`` 参数允许您指定VID（供应商id）和PID（产品id）。
   *pid* 值为 -1 将根据 *modestr* 的值选择 PID。
   
   如果启用 MSC 模式，*msc* 参数可用于指定要在大容量存储接口上公开的 SCSI LUN 列表。例如 ``msc=(pyb.Flash(), pyb.SDCard())`` 。

   若启用HID模式，您可能也需要通过传递 *hid* 关键参数来指定HID的具体细节。
   其需要一个（子类、协议、最大数据包长度、轮询间隔、报告描述符）的元组。默认情况下，其将为USB鼠标设置适当值。
   ``pyb.hid_keyboard`` 常量为USB键盘的适当元组。

   *high_speed* 参数设置为 ``True`` 时，如果硬件支持，则启用 USB HS 模式。

类
-------

.. toctree::
   :maxdepth: 1

   pyb.ADC.rst
   pyb.CAN.rst
   pyb.DAC.rst
   pyb.ExtInt.rst
   pyb.Flash.rst
   pyb.I2C.rst
   pyb.LED.rst
   pyb.Pin.rst
   pyb.RTC.rst
   pyb.Servo.rst
   pyb.SPI.rst
   pyb.Timer.rst
   pyb.UART.rst
   pyb.USB_VCP.rst