跳到主要内容

API-内部设备

GPIO Zero 还提供了几个"内部"设备，它们代表操作系统本身提供的功能。这些设备可用于响应诸如时间、网络服务器是否可用等事件。

这些设备提供了与 GPIO 设备类似且兼容的 API，因此内部设备事件可以像输入设备一样触发 GPIO 输出设备的更改。就像 Button 对象在按下时处于活动状态并可在状态变化时触发其他设备一样，TimeOfDay 对象在特定时间段内处于活动状态。

考虑以下代码，其中 Button 对象用于控制 LED 对象：

from gpiozero import LED, Button
from signal import pause

led = LED(2)
btn = Button(3)

btn.when_pressed = led.on
btn.when_released = led.off

pause()

现在考虑以下示例，其中 TimeOfDay 对象使用相同的方法控制 LED：

from gpiozero import LED, TimeOfDay
from datetime import time
from signal import pause

led = LED(2)
tod = TimeOfDay(time(9), time(10))

tod.when_activated = led.on
tod.when_deactivated = led.off

pause()

在这里，LED 不是由按钮控制，而是由时间控制。当时间达到上午 9:00 时，LED 亮起，在上午 10:00 时熄灭。

像 Button 对象一样，内部设备如 TimeOfDay 对象具有 value、values、is_active、when_activated 和 when_deactivated 属性，因此使用其他范式的替代方法也可以工作。

备注

请注意，虽然内部设备的构造函数参数中有 pin_factory，并且需要有效，但所选的引脚工厂不会产生任何实际差异。例如，目前无法读取远程 Pi 的 CPU 温度。

常规类​

以下类供与其命名的设备一般使用。本节中的所有类都是具体类（非抽象类）。

TimeOfDay​

class gpiozero.TimeOfDay(*args, **kwargs)

扩展 PolledInternalDevice 以提供一个设备，当计算机时钟指示当前时间在 start_time 和 end_time 之间（包含两端）时处于活动状态，这两个参数是 time 实例。

以下示例在上午 07:00 到 08:00 之间打开连接到 Energenie 插座的灯：

from gpiozero import TimeOfDay, Energenie
from datetime import time
from signal import pause

lamp = Energenie(1)
morning = TimeOfDay(time(7), time(8))

morning.when_activated = lamp.on
morning.when_deactivated = lamp.off

pause()

请注意，start_time 可以大于 end_time，表示跨越午夜的时间段。

参数：

  • start_time (time) - 从此时间起设备将被视为活动状态
  • end_time (time) - 在此时间之后设备将被视为非活动状态
  • utc (bool) - 如果为 True（默认），将使用 naive UTC 时间进行比较，而不是本地时区读数
  • event_delay (float) - 文件读取之间的秒数（默认为 10 秒）
  • pin_factory (Factory 或 None) - 参见 API-引脚 获取更多信息（这是高级功能，大多数用户可以忽略）
property end_time

设备被视为非活动状态之后的时间。

property is_active

如果设备当前处于活动状态则返回 True，否则返回 False。此属性通常派生自 value。与 value 不同，此属性始终是布尔值。

property start_time

设备被视为活动状态之后的时间。

property utc

如果为 True，使用 naive UTC 时间读数进行比较，而不是本地时区读数。

property value

当系统时钟读数在 start_time 和 end_time 之间时返回 1，否则返回 0。如果 start_time 大于 end_time（表示跨越午夜的时间段），则当当前时间大于 start_time 或小于 end_time 时返回 1。

property when_activated

当设备从非活动状态变为活动状态（时间达到 start_time）时运行的函数。

这可以设置为一个不接受（强制）参数的函数，或一个接受单个强制参数（以及任意多个可选参数）的 Python 函数。如果函数接受单个强制参数，则激活它的设备将作为该参数传递。

将此属性设置为 None（默认值）以禁用事件。

property when_deactivated

当设备从活动状态变为非活动状态（时间达到 end_time）时运行的函数。

这可以设置为一个不接受（强制）参数的函数，或一个接受单个强制参数（以及任意多个可选参数）的 Python 函数。如果函数接受单个强制参数，则激活它的设备将作为该参数传递。

将此属性设置为 None（默认值）以禁用事件。

PingServer​

class gpiozero.PingServer(*args, **kwargs)

扩展 PolledInternalDevice 以提供一个在主机（域名或 IP 地址）可以 ping 通时处于活动状态的设备。

以下示例在 google.com 可达时点亮 LED：

from gpiozero import PingServer, LED
from signal import pause

google = PingServer('google.com')
led = LED(4)

google.when_activated = led.on
google.when_deactivated = led.off

pause()

参数：

  • host (str) - 要尝试 ping 的主机名或 IP 地址
  • event_delay (float) - ping 之间的秒数（默认为 10 秒）
  • pin_factory (Factory 或 None) - 参见 API-引脚 获取更多信息（这是高级功能，大多数用户可以忽略）
property host

每当查询 value 时要测试的主机名或 IP 地址。

property is_active

如果设备当前处于活动状态则返回 True，否则返回 False。此属性通常派生自 value。与 value 不同，此属性始终是布尔值。

property value

如果主机返回单个 ping，返回 1，否则返回 0。

property when_activated

当设备从非活动状态（主机无响应）变为活动状态（主机响应）时运行的函数。

这可以设置为一个不接受（强制）参数的函数，或一个接受单个强制参数（以及任意多个可选参数）的 Python 函数。如果函数接受单个强制参数，则激活它的设备将作为该参数传递。

将此属性设置为 None（默认值）以禁用事件。

property when_deactivated

当设备从活动状态（主机响应）变为非活动状态（主机无响应）时运行的函数。

这可以设置为一个不接受（强制）参数的函数，或一个接受单个强制参数（以及任意多个可选参数）的 Python 函数。如果函数接受单个强制参数，则激活它的设备将作为该参数传递。

将此属性设置为 None（默认值）以禁用事件。

CPUTemperature​

class gpiozero.CPUTemperature(*args, **kwargs)

扩展 PolledInternalDevice 以提供一个在 CPU 温度超过 threshold 值时处于活动状态的设备。

以下示例在 LED 条形图上绘制 CPU 温度：

from gpiozero import LEDBarGraph, CPUTemperature
from signal import pause

# 使用更接近"正常"使用的最小值和最大值，以便条形图更"活跃"
cpu = CPUTemperature(min_temp=50, max_temp=90)

print(f'Initial temperature: {cpu.temperature}C')

graph = LEDBarGraph(5, 6, 13, 19, 25, pwm=True)
graph.source = cpu

pause()

参数：

  • sensor_file (str) - 从中读取温度的文件。默认为 sysfs 文件 /sys/class/thermal/thermal_zone0/temp。指定的文件应包含以毫摄氏度表示的温度的单行
  • min_temp (float) - value 将读取 0.0 的温度。默认为 0.0
  • max_temp (float) - value 将读取 1.0 的温度。默认为 100.0
  • threshold (float) - 超过此温度时设备将被视为"活动"（参见 is_active）。默认为 80.0
  • event_delay (float) - 文件读取之间的秒数（默认为 5 秒）
  • pin_factory (Factory 或 None) - 参见 API-引脚 获取更多信息（这是高级功能，大多数用户可以忽略）
property is_active

当 CPU temperature 超过 threshold 时返回 True。

property temperature

返回当前 CPU 温度（以摄氏度为单位）。

property value

返回当前 CPU 温度作为 0.0（表示 min_temp 值）和 1.0（表示 max_temp 值）之间的值。这些分别默认为 0.0 和 100.0，因此 value 默认为 temperature 除以 100。

property when_activated

当设备从非活动状态变为活动状态（温度达到 threshold）时运行的函数。

这可以设置为一个不接受（强制）参数的函数，或一个接受单个强制参数（以及任意多个可选参数）的 Python 函数。如果函数接受单个强制参数，则激活它的设备将作为该参数传递。

将此属性设置为 None（默认值）以禁用事件。

property when_deactivated

当设备从活动状态变为非活动状态（温度降至 threshold 以下）时运行的函数。

这可以设置为一个不接受（强制）参数的函数，或一个接受单个强制参数（以及任意多个可选参数）的 Python 函数。如果函数接受单个强制参数，则激活它的设备将作为该参数传递。

将此属性设置为 None（默认值）以禁用事件。

LoadAverage​

class gpiozero.LoadAverage(*args, **kwargs)

扩展 PolledInternalDevice 以提供一个在 CPU 负载平均值超过 threshold 值时处于活动状态的设备。

以下示例在 LED 条形图上绘制负载平均值：

from gpiozero import LEDBarGraph, LoadAverage
from signal import pause

la = LoadAverage(min_load_average=0, max_load_average=2)
graph = LEDBarGraph(5, 6, 13, 19, 25, pwm=True)

graph.source = la

pause()

参数：

  • load_average_file (str) - 从中读取负载平均值的文件。默认为 proc 文件 /proc/loadavg。指定的文件应在开头包含三个以空格分隔的负载平均值，分别表示 1 分钟、5 分钟和 15 分钟的平均值
  • min_load_average (float) - value 将读取 0.0 的负载平均值。默认为 0.0
  • max_load_average (float) - value 将读取 1.0 的负载平均值。默认为 1.0
  • threshold (float) - 超过此负载平均值时设备将被视为"活动"（参见 is_active）。默认为 0.8
  • minutes (int) - 计算平均负载的分钟数。必须为 1、5 或 15。默认为 5
  • event_delay (float) - 文件读取之间的秒数（默认为 10 秒）
  • pin_factory (Factory 或 None) - 参见 API-引脚 获取更多信息（这是高级功能，大多数用户可以忽略）
property is_active

当 load_average 超过 threshold 时返回 True。

property load_average

返回当前负载平均值。

property value

返回当前负载平均值作为 0.0（表示 min_load_average 值）和 1.0（表示 max_load_average 值）之间的值。这些分别默认为 0.0 和 1.0。

property when_activated

当设备从非活动状态变为活动状态（负载平均值达到 threshold）时运行的函数。

这可以设置为一个不接受（强制）参数的函数，或一个接受单个强制参数（以及任意多个可选参数）的 Python 函数。如果函数接受单个强制参数，则激活它的设备将作为该参数传递。

将此属性设置为 None（默认值）以禁用事件。

property when_deactivated

当设备从活动状态变为非活动状态（负载平均值降至 threshold 以下）时运行的函数。

这可以设置为一个不接受（强制）参数的函数，或一个接受单个强制参数（以及任意多个可选参数）的 Python 函数。如果函数接受单个强制参数，则激活它的设备将作为该参数传递。

将此属性设置为 None（默认值）以禁用事件。

DiskUsage​

class gpiozero.DiskUsage(*args, **kwargs)

扩展 PolledInternalDevice 以提供一个在磁盘使用率超过 threshold 值时处于活动状态的设备。

以下示例在 LED 条形图上绘制磁盘使用率：

from gpiozero import LEDBarGraph, DiskUsage
from signal import pause

disk = DiskUsage()

print(f'Current disk usage: {disk.usage}%')

graph = LEDBarGraph(5, 6, 13, 19, 25, pwm=True)
graph.source = disk

pause()

参数：

  • filesystem (str) - 需要计算磁盘使用率的文件系统内的路径。默认为 /，即根文件系统
  • threshold (float) - 超过此磁盘使用率百分比时设备将被视为"活动"（参见 is_active）。默认为 90.0
  • event_delay (float) - 文件读取之间的秒数（默认为 30 秒）
  • pin_factory (Factory 或 None) - 参见 API-引脚 获取更多信息（这是高级功能，大多数用户可以忽略）
property is_active

当磁盘 usage 超过 threshold 时返回 True。

property usage

返回当前磁盘使用率（百分比）。

property value

返回当前磁盘使用率作为 0.0 到 1.0 之间的值，通过将 usage 除以 100 获得。

property when_activated

当设备从非活动状态变为活动状态（磁盘使用率达到 threshold）时运行的函数。

这可以设置为一个不接受（强制）参数的函数，或一个接受单个强制参数（以及任意多个可选参数）的 Python 函数。如果函数接受单个强制参数，则激活它的设备将作为该参数传递。

将此属性设置为 None（默认值）以禁用事件。

property when_deactivated

当设备从活动状态变为非活动状态（磁盘使用率降至 threshold 以下）时运行的函数。

这可以设置为一个不接受（强制）参数的函数，或一个接受单个强制参数（以及任意多个可选参数）的 Python 函数。如果函数接受单个强制参数，则激活它的设备将作为该参数传递。

将此属性设置为 None（默认值）以禁用事件。

基类​

上述部分中的类派生自一系列基类，其中一些实际上是抽象的。这些类形成下图中显示的（部分）层次结构（抽象类的颜色比具体类浅）：

内部设备层次结构

以下部分记录了这些基类，供希望为自己的设备构建类的高级用户使用。

PolledInternalDevice​

class gpiozero.PolledInternalDevice(*args, **kwargs)

扩展 InternalDevice 以提供一个后台线程来轮询缺乏其他机制通知实例更改的内部设备。

InternalDevice​

class gpiozero.InternalDevice(*args, **kwargs)

扩展 Device 以提供没有特定硬件表示的设备的基础。这些实际上是伪设备，通常代表操作系统服务，如内部时钟、文件系统或网络设施。

中文翻译版以英文版相同知识授权方式共享：BSD-3-Clause。交流 Q群：498908352

最后于 更新