API-输入设备
这些输入设备组件接口是为日常组件的简单使用而提供的。在代码中使用组件前，必须正确布线。
所有 GPIO 引脚编号默认使用 Broadcom (BCM) 编号。更多信息，请参阅 引脚编号 部分。
常规类
下列类用于它们所代表的设备。本节中的所有类都是具体类（非抽象类）。
Button（按钮）
扩展 DigitalInputDevice，表示一个简单的按钮或开关。
将按钮的一侧连接到接地引脚，另一侧连接到任何 GPIO 引脚。或者，将按钮的一侧连接到 3V3 引脚，另一侧连接到任何 GPIO 引脚，然后在 Button 构造函数中将 pull_up 设置为 False。
下面的示例将在按下按钮时打印一行文本：
from gpiozero import Button
button = Button(4)
button.wait_for_press()
print("The button was pressed!")
| 参数 |
|
暂停脚本，直到设备被激活或超时。
| 参数 |
|
暂停脚本，直到设备被释放或超时。
| 参数 |
|
设备连接的 Pin。如果设备已关闭（参见 close() 方法），则为 None。处理 GPIO 引脚时，查询 pin.number 可发现设备连接到的 GPIO 引脚（BCM 编号）。
如果设备当前激活则返回 True，否则返回 False。此属性通常从 value 派生。与 value 不同，此属性始终是布尔值。
当设备按住超过 hold_time 秒时返回 True。
设备激活后等待多长时间（以秒为单位），直到执行 when_held 处理程序。如果 hold_repeat 为 True，这也是 when_held 两次调用之间的时间长度。
设备已被按住的时长（以秒为单位）。此时长从首次执行 when_held 事件开始计时，而不是从设备激活时开始，这与 active_time 形成对比。如果设备当前未被按住，则返回 None。
如果为 True，只要设备保持激活状态，就会每隔 hold_time 秒重复执行 when_held 处理程序。如果为 False（默认值），则每次保持时只执行一次 when_held 处理程序。
如果为 True，设备使用上拉电阻将 GPIO 引脚默认设置为"高电平"。
当设备从不活动状态变为活动状态时要运行的函数。
可以将其设置为不接受（强制）参数的函数，或接受单个强制参数（带任意数量可选参数）的 Python 函数。如果函数接受单个强制参数，激活设备的对象将作为该参数传递。
将此属性设置为 None（默认值）以禁用事件。
当设备从活动状态变为不活动状态时要运行的函数。
可以将其设置为不接受（强制）参数的函数，或接受单个强制参数（带任意数量可选参数）的 Python 函数。如果函数接受单个强制参数，停用设备的对象将作为该参数传递。
将此属性设置为 None（默认值）以禁用事件。
当设备保持活动状态达 hold_time 秒时要运行的函数。
可以将其设置为不接受（强制）参数的函数，或接受单个强制参数（带任意数量可选参数）的 Python 函数。如果函数接受单个强制参数，激活设备的对象将作为该参数传递。
将此属性设置为 None（默认值）以禁用事件。
返回 0（未按下）或 1（按下）。
LineSensor（TRCT5000）
扩展 SmoothedInputDevice，表示单引脚线传感器，如 CamJam #3 EduKit 中的 TCRT5000 红外接近传感器。
典型的线传感器有一个小电路板，带有三个引脚：VCC、GND 和 OUT。VCC 应连接到 3V3 引脚，GND 连接到一个接地引脚，最后 OUT 连接到构造函数中 pin 参数指定的 GPIO 引脚。
以下代码将在传感器检测到线或停止检测线时打印一行文本：
from gpiozero import LineSensor
from signal import pause
sensor = LineSensor(4)
sensor.when_line = lambda: print('Line detected')
sensor.when_no_line = lambda: print('No line detected')
pause()
| 参数 |
|
暂停脚本，直到设备被停用或达到超时。
| 参数 |
|
暂停脚本，直到设备被激活或达到超时。
| 参数 |
|
设备连接的 Pin。如果设备已关闭（参见 close() 方法），则为 None。处理 GPIO 引脚时，查询 pin.number 可发现设备连接到的 GPIO 引脚（BCM 编号）。
当传感器检测到线时返回 True。
当设备从活动状态变为不活动状态时要运行的函数。
可以将其设置为不接受（强制）参数的函数，或接受单个强制参数（带任意数量可选参数）的 Python 函数。如果函数接受单个强制参数，停用设备的对象将作为该参数传递。
将此属性设置为 None（默认值）以禁用事件。
当设备从不活动状态变为活动状态时要运行的函数。
可以将其设置为不接受（强制）参数的函数，或接受单个强制参数（带任意数量可选参数）的 Python 函数。如果函数接受单个强制参数，激活设备的对象将作为该参数传递。
将此属性设置为 None（默认值）以禁用事件。
返回表示队列值平均 值的值。传感器下方为黑色时，该值接近 0；传感器下方为白色时，该值接近 1。
MotionSensor（D-SUN PIR）
扩展 SmoothedInputDevice，表示被动红外（PIR）运动传感器，如 CamJam #2 EduKit 中的传感器。
典型的 PIR 设备有一个小电路板，带有三个引脚：VCC、OUT 和 GND。VCC 应连接到 5V 引脚，GND 连接到一个接地引脚，最后 OUT 连接到构造函数中 pin 参数指定的 GPIO 引脚。
以下代码将在检测到运动时打印一行文本：
from gpiozero import MotionSensor
pir = MotionSensor(4)
pir.wait_for_motion()
print("Motion detected!")
| 参数 |
|
暂停脚本，直到设备被激活或达到超时。
| 参数 |
|
暂停脚本，直到设备被停用或达到超时。
| 参数 |
|
设备连接的 Pin。如果设备已关闭（参见 close() 方法），则为 None。处理 GPIO 引脚时，查询 pin.number 可发现设备连接到的 GPIO 引脚（BCM 编号）。
如果 value 当前超过 threshold 则返回 True，否则返回 False。
当设备从不活动状态变为活动状态时要运行的函数。
可以将其设置为不接受（强制）参数的函数，或接受单个强制参数（带任意数量可选参数）的 Python 函数。如果函数接受单个强制参数，激活设备的对象将作为该参数传递。
将此属性设置为 None（默认值）以禁用事件。
当设备从活动状态变为不活动状态时要运行的函数。
可以将其设置为不接受（强制）参数的函数，或接受单个强制参数（带任意数量可选参数）的 Python 函数。如果函数接受单个强制参数，停用设备的对象将作为该参数传递。
将此属性设置为 None（默认值）以禁用事件。
使用默认的 queue_len 为 1 时，这实际上是布尔值，其中 0 表示未检测到运动，1 表示检测到运动。如果您指定大于 1 的 queue_len，这将是一个平均值，值越接近 1 表示检测到运动。
LightSensor（LDR）
扩展 SmoothedInputDevice，表示光敏电阻（LDR）。
将 LDR 的一条腿连接到 3V3 引脚；将 1µF 电容的一条腿连接到接地引脚；将 LDR 的另一条腿和电容的另一条腿连接到同一个 GPIO 引脚。此类重复放电电容，然后计时充电所需的时间（根据照射在 LDR 上的光线而变化）。
以下代码将在检测到光线时打印一行文本：
from gpiozero import LightSensor
ldr = LightSensor(18)
ldr.wait_for_light()
print("Light detected!")
| 参数 |
|
暂停脚本，直到设备被激活或达到超时。
| 参数 |
|
暂停脚本，直到设备被停用或达到超时。
| 参数 |
|
设备连接的 Pin。如果设备已关闭（参见 close() 方法），则为 None。处理 GPIO 引脚时，查询 pin.number 可发现设备连接到的 GPIO 引脚（BCM 编号）。
如果 value 当前超过 threshold 则返回 True，否则返回 False。
当设备从不活动状态变为活动状态时要运行的函数。
可以将其设置为不接受（强制）参数的函数，或接受单个强制参数（带任意数量可选参数）的 Python 函数。如果函数接受单个强制参数，激活设备的对象将作为该参数传递。
将此属性设置为 None（默认值）以禁用事件。
当设备从活动状态变为不活动状态时要运行的函数。
可以将其设置为不接受（强制）参数的函数，或接受单个强制参数（带任意数量可选参数）的 Python 函数。如果函数接受单个强制参数，停用设备的对象将作为该参数传递。
将此属性设置为 None（默认值）以禁用事件。
返回介于 0（黑暗）和 1（明亮）之间的值。
DistanceSensor（HC-SR04）
扩展 SmoothedInputDevice，表示 HC-SR04 超声波距离传感器，如 CamJam #3 EduKit 中的传感器。
距离传感器需要两个 GPIO 引脚：一个用于触发（传感器上标记为 TRIG），另一个用于回声（传感器上标记为 ECHO）。但是，需要分压器来确保 ECHO 引脚的 5V 电压不会损坏树莓派。请按照以下说明连接传感器：
- 将传感器的 GND 引脚连接到树莓派的接地引脚。
- 将传感器的 TRIG 引脚连接到一个 GPIO 引脚。
- 将一个 330Ω 电阻的一端连接到传感器的 ECHO 引脚。
- 将一个 470Ω 电阻的一端连接到传感器的 GND 引脚。
- 将两个电阻的另一端连接到另一个 GPIO 引脚。这形成了所需的分压器。
- 最后，将传感器的 VCC 引脚连接到树莓派的 5V 引脚。
或者，3V3 兼容的 HC-SR04P 传感器（不需要分压器）也适用于此类。
如果您没有上述指定的精确电阻值，不用担心！重要的是电阻之间的比率。
您也不需要绝对精确；上面给出的分压器实际上会输出约 3V（而不是 3.3V）。简单的 2:3 比率将给出 3.333V，这意味着您可以取三个相同值的电阻，使用其中一个代替 330Ω 电阻，并使用其中两个串联代替 470Ω 电阻。
以下代码将定期报告传感器测量的距离（以厘米为单位），假设 TRIG 引脚连接到 GPIO17，ECHO 引脚连接到 GPIO18：
from gpiozero import DistanceSensor
from time import sleep
sensor = DistanceSensor(echo=18, trigger=17)
while True:
print('Distance: ', sensor.distance * 100)
sleep(1)
为了提高精度，请使用 pigpio 引脚驱动程序而不是默认的 RPi.GPIO 驱动程序（pigpio 使用 DMA 采样以获得更精确的边缘定时）。如果您使用的是 Pi 1 或 Pi Zero，这尤其相关。有关更多信息，请参阅更改引脚工厂。
| 参数 |
|
暂停脚本，直到设备被停用或达到超时。
| 参数 |
|
暂停脚本，直到设备被激活或达到超时。
| 参数 |
|
TRIG 引脚连接的 Pin。
返回传感器回声连接的 Pin。这只是通常 pin 属性的别名。
如果检测到的 distance 小于 threshold_distance，则返回 True。
当设备从活动状态变为不活动状态时要运行的函数。
可以将其设置为不接受（强制）参数的函数，或接受单个强制参数（带任意数量可选参数）的 Python 函数。如果函数接受单个强制参数，停用设备的对象将作为该参数传递。
将此属性设置为 None（默认值）以禁用事件。
当设备从不活动状态变为活动状态时要运行的函数。
可以将其设置为不接受（强制）参数的函数，或接受单个强制参数（带任意数量可选参数）的 Python 函数。如果函数接受单个强制参数，激活设备的对象将作为该参数传递。
将此属性设置为 None（默认值）以禁用事件。
传感器将测量的最大距离（以米为单位）。此值在构造函数中指定，用于为 value 属性提供缩放。当 distance 等于 max_distance 时，value 将为 1。
返回传感器当前测量的距离（以米为单位）。请注意，此属性的值介于 0 和 max_distance 之间。
当越过时将触发 when_in_range 和 when_out_of_range 事件的距离（以米为单位）。这只是通常 threshold 属性的米缩放变体。
返回介于 0 和 1 之间的值，其中 0 表示反射器正在接触传感器或距离足够近以至于传感器无法区分，1 表示反射器位于或超过指定的 max_distance。
RotaryEncoder
表示一个简单的双引脚增量式旋转编码器设备。
这些设备通常有三个引脚，标记为"A"、"B"和"C"。将 A 和 B 直接连接到两个 GPIO 引脚，将 C（"公共"）连接到树莓派上的一个接地引脚。然后在构造此类时，只需将 A 和 B 引脚指定为参数。
例如，如果编码器的 A 引脚连接到 GPIO 21，B 引脚连接到 GPIO 20（并且 C 引脚presumably连接到合适的 GND 引脚），而一个 LED（带有合适的 300Ω 电阻）连接到 GPIO 5，以下会话将导致 LED 的亮度由旋转编码器的旋转来控制：
>>> from gpiozero import RotaryEncoder
>>> from gpiozero.tools import scaled_half
>>> rotor = RotaryEncoder(21, 20)
>>> led = PWMLED(5)
>>> led.source = scaled_half(rotor.values)
| 参数 |
|
暂停脚本，直到编码器向任一方向旋转至少一步，或达到超时。
| 参数 |
|
暂停脚本，直到编码器顺时针旋转至少一步，或达到超时。
| 参数 |
|
暂停脚本，直到编码器逆时针旋转 至少一步，或达到超时。
| 参数 |
|
旋转编码器顺时针移动将 value 从 0 变为 1，或逆时针从 0 变为 -1 所需的离散步数。从另一个意义上说，这也是此输入可以表示的离散状态的总数。
编码器的"步数"值从 0 开始。编码器每顺时针旋转一步，该值增加 1；每逆时针旋转一步，该值减少 1。步数值受 max_steps 限制。除非 wrap 为 True（此时它将通过取反回绕），否则它不会超过正或负 max_steps。如果 max_steps 为零，则步数完全不受限制，并将在任一方向无限增加，但 value 将返回常量零。
请注意，与大多数其他输入设备不同，由于旋转编码器没有绝对位置，因此 steps 属性（以及推论的 value）是可写的。
is_active 将返回 True 的最小和最大步数。默认为 (0, 0)。
表示旋转编码器的值，介于 -1 和 1 之间。该值是通过将 steps 的值划分到从负 max_steps 到正 max_steps 的范围来计算的。
请注意，与大多数其他输入设备不同，由于旋转编码器没有绝对位置，因此 value 属性是可写的。
当编码器向任一方向旋转时要运行的函数。
可以将其设置为不接受（强制）参数的函数，或接受单个强制参数（带任意数量可选参数）的 Python 函数。如果函数接受单个强制参数，激活的设备将作为该参数传递。
将此属性设置为 None（默认值）以禁用事件。
当编码器顺时针旋转时要运行的函数。
可以将其设置为不接受（强制）参数的函数，或接受单个强制参数（带任意数量可选参数）的 Python 函数。如果函数接受单个强制参数，激活的设备将作为该参数传递。
将此属性设置为 None（默认值）以禁用事件。
当编码器逆时针旋转时要运行的函数。
可以将其设置为不接受（强制）参数的函数，或接受单个强制参数（带任意数量可选参数）的 Python 函数。如果函数接受单个强制参数，激活的设备将作为该参数传递。
将此属性设置为 None（默认值）以禁用事件。
如果为 True，当 value 达到其限制（-1 或 1）时，它会"回绕"到相反的限制。当为 False 时，值（以及相应的 steps 属性）不会超出该限制。
基类
以上部分中的类派生自一系列基类，其中一些实际上是抽象的。这些类构成下图中显示的（部分）层次结构（抽象类比具体类颜色浅）：
以下部分记录了这些基类，供希望为自己的设备构建类的高级用户使用。
DigitalInputDevice
表示具有典型开/关行为的通用输入设备。
此类扩展 InputDevice，为以典型数字方式运行的设备提供激活和停用事件的触发机制：两种状态之间有（合理的）干净的转换。
| 参数 |
|
暂停脚本，直到设备被激活或达到超时。
| 参数 |
|
暂停脚本，直到设备被停用或达到超时。
| 参数 |
|
设备处于活动状态的时间长度（以秒为单位）。当设备处于不活动状态时，该值为 None。
设备处于不活动状态的时间长度（以秒为单位）。当设备处于活动状态时，该值为 None。
返回表示设备状态的值。通常这是一个布尔值，或介于 0 和 1 之间的数字，但某些设备使用更大的范围（例如 -1 到 +1），复合设备通常使用元组来返回其所有从属组件的状态。
当设备从不活动状态变为活动状态时要运行的函数。
可以将其设置为不接受（强制）参数的函数，或接受单个强制参数（带任意数量可选参数）的 Python 函数。如果函数接受单个强制参数，激活它的设备将作为该参数传递。
将此属性设置为 None（默认值）以禁用事件。
当设备从活动状态变为不活动状态时要运行的函数。
可以将其设置为不接受（强制）参数的函数，或接受单个强制参数（带任意数量可选参数）的 Python 函数。如果函数接受单个强制参数，停用它的设备将作为该参数传递。
将此属性设置为 None（默认值）以禁用事件。
SmoothedInputDevice
表示通用输入设备，其值取自历史值队列的平均值。
此类扩展 InputDevice，添加了一个由后台线程填充的队列，该线程持续轮询底层设备的状态。队列中值的平均值（一个可配置的函数）与阈值进行比较，该阈值用于确定 is_active 属性的状态。
后台队列不会在构造时自动启动。这是为了允许子类在队列开始读取值之前设置其他组件。实际上，这是一个抽象基类。
此类适用于表现出模拟行为（例如带有 LDR 的电容充电时间）或表现出"抖动"行为（例如某些运动传感器）的设备。
| 参数 |
|
如果 value 当前超过 threshold 则返回 True，否则返回 False。
如果为 False（默认值），在队列填满之前，尝试读取 value 或 is_active 属性将阻塞。
内部值队列的长度，用于平均以确定设备的总体状态。默认为 5。
如果 value 超过此值，则 is_active 将返回 True。
返回内部队列中值的平均值。将此值与 threshold 进行比较以确定 is_active 是否为 True。
InputDevice
表示通用 GPIO 输入设备。
此类扩展 GPIODevice，添加 GPIO 输入设备通用的功能。构造函数添加可选的 pull_up 参数来指定引脚应如何通过内部电阻拉动。is_active 属性会相应调整，以便 True 仍表示活动状态，无论 pull_up 设置如何。
| 参数 |
|
如果设备当前处于活动状态则返回 True，否则返回 False。此属性通常从 value 派生。与 value 不同，这总是一个布尔值。
如果为 True，设备使用上拉电阻默认将 GPIO 引脚设置为"高电平"。
返回表示设备状态的值。通常这是一个布尔值，或介于 0 和 1 之间的数字，但某些设备使用更大的范围（例如 -1 到 +1），复合设备通常使用元组来返回其所有从属组件的状态。
GPIODevice
扩展 Device。表示通用 GPIO 设备，并提供所有单引脚 GPIO 设备通用的服务（例如确保两个 GPIO 设备不共享一个 pin）。
| 参数 |
|
关闭设备并释放所有关联资源（例如 GPIO 引脚）。
此方法是幂等的（可以在已关闭的设备上调用而不会产生任 何副作用）。它主要用于命令行的交互式使用。它会禁用设备并释放其引脚，以供其他设备使用。
您可以尝试通过删除对象来完成此操作，但除非清除了对该对象的所有引用，否则这可能不起作用（即使清除了所有引用，也无法保证垃圾回收器会在那时实际删除该对象）。相比之下，close 方法提供了一种确保对象关闭的方法。
例如，如果您的面包板上有一个连接到引脚 16 的蜂鸣器，但随后希望改接一个 LED：
from gpiozero import *
bz = Buzzer(16)
bz.on()
bz.off()
bz.close()
led = LED(16)
led.blink()
Device 的子类也可以使用 with 语句作为上下文管理器。例如：
from gpiozero import *
with Buzzer(16) as bz:
bz.on()
with LED(16) as led:
led.on()
如果设备已关闭（参见 close() 方法）则返回 True。一旦设备关闭，您就无法再使用任何其他方法或属性来控制或查询该设备。
设备连接的 Pin。如果设备已关闭（参见 close() 方法），则为 None。处理 GPIO 引脚时，查询 pin.number 可发现设备连接到的 GPIO 引脚（BCM 编号）。
返回表示设备状态的值。通常这是一个布尔值，或介于 0 和 1 之间的数字，但某些设备使用更大的范围（例如 -1 到 +1），复合设备通常使用元组来返回其所有从属组件的状态。
中文翻译版以英文版相同知识授权方式共享：BSD-3-Clause。交流 Q群：498908352