.. currentmodule:: pyb
.. _pyb.ADC:

ADC类 – 模数转换
=========================================

Usage::

    import pyb

    adc = pyb.ADC(pin)                  # create an analog object from a pin
    val = adc.read()                    # read an analog value

    adc = pyb.ADCAll(resolution)        # create an ADCAll object
    adc = pyb.ADCAll(resolution, mask)  # create an ADCAll object for selected analog channels
    val = adc.read_channel(channel)     # read the given channel
    val = adc.read_core_temp()          # read MCU temperature
    val = adc.read_core_vbat()          # read MCU VBAT
    val = adc.read_core_vref()          # read MCU VREF
    val = adc.read_vref()               # read MCU supply voltage


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

.. class:: pyb.ADC(pin)

    创建一个与给定引脚相关联的ADC对象，然后您就可在引脚中读取模拟值。

方法
-------

.. method:: ADC.read()

       在模拟引脚上读取值并返回。返回值应介于0至4095之间。

.. method:: ADC.read_timed(buf, timer)

       以 ``timer`` 对象设定的比率将模拟值读取到 ``buf`` 中。

       ``buf`` 可为字节数组或数组。ADC值有12位分辨率，其中元素大小大于等于16位时，直接储存到 ``buf`` 中。
       若 ``buf`` 仅有8位元素（例如一个字节元组），则样本分辨率将会降低到8位。

       ``timer`` 应为一个定时器对象，定时器每次触发时，样本都会被读取。定时器须已初始化，且以预设的样本频率运行。

       为支持此函数之前的活动， ``timer`` 可为一个指定样本频率（以Hz为单位）的整数。在此种情况下，定时器（6）可自动配置为以给定频率运行。

       定时器对象用法示例（最佳方法）::

           adc = pyb.ADC(pyb.Pin("P5"))        # create an ADC on pin P5
           tim = pyb.Timer(6, freq=10)         # create a timer running at 10Hz 创建一个以10Hz运行的定时器
           buf = bytearray(100)                # creat a buffer to store the samples 创建一个储存样本的缓冲区
           adc.read_timed(buf, tim)            # sample 100 values, taking 10s 样本100个值，耗时10s

       使用整数作为频率的例子::

           adc = pyb.ADC(pyb.Pin("P5"))        # create an ADC on pin P5
           buf = bytearray(100)                # create a buffer of 100 bytes 创建100字节的缓冲区
           adc.read_timed(buf, 10)             # read analog values into buf at 10Hz 以10Hz将模拟值读取到缓冲区中
                                               #   this will take 10 seconds to finish 耗时10s后结束
           for val in buf:                     # loop over all values 循环所有值
               print(val)                      # print the value out 打印值

       此函数不分配任何内存。
       它有阻塞行为:
       在缓冲区满之前，它不会返回到调用程序。

ADCAll对象
-----------------

这一实例将所有ADC引脚转换为模拟输入。原始的MCU温度、VREF和VBAT数据可分别在ADC通道16、17和18中访问。需要适度的缩放。

芯片上的温度传感器已经过工厂校准，可以读取芯片温度至+/- 1摄氏度。尽管听起来很准确，但是不要忘记MCU的内部
测量温度。取决于处理负载和I/O子系统的活动状态，芯片温度很容易比环境温度高几十度。
另一方面，经过长时间的待机时间后唤醒的pyboard将在上述范围内显示正确的环境温度。

``ADCAll``  ``read_core_vbat()`` 和 ``read_core_vref()`` 使用3.3 V电源作为参考，读取备用电池电压和(1.21 V)参考电压。所有结果均为浮点数，给出直流电压值。
    
``read_core_vbat()`` 返回备用电池的电压。该电压也根据实际电源电压进行调整。
为避免模拟输入过载，电池电压通过分压器进行测量，并根据分压器的值进行缩放。
为防止备用电池负载过大，分压器仅在ADC转换期间处于活动状态。

``read_vref()``是通过测量内部参考电压并使用内部参考电压的出厂校准值。
在大多数情况下，读数将接近3.3V。如果使用电池来操作Pyboard，则电源电压可能会降至3.3V以下。
只要满足操作条件，Pyboard仍可以正常运行。通过正确设置MCU时钟，闪存访问速度和编程模式，可以将pyboard降低至
2V，仍然可获得有用的ADC转换。

确保模拟输入电压不超过实际电源电压非常重要。

其他模拟输入通道(0..15)将根据所选精度返回未缩放的整数值。

为避免不必要的模拟输入激活（通道0..15），可以指定第二个参数。
该参数是一个二进制模式，其中每个请求的模拟输入都有相应的位设置。
默认值为0xffffffff，表示所有模拟输入均处于活动状态。如果只是内部
通道（16..18）是必需的，掩码值应为0x70000。

例子::

    adcall = pyb.ADCAll(12, 0x70000) # 12 bit resolution, internal channels
    temp = adcall.read_core_temp()