17. API - Internal Devices¶
GPIO Zero also provides several “internal” devices which represent facilities provided by the operating system itself. These can be used to react to things like the time of day, or whether a server is available on the network.
Warning
These devices are experimental and their API is not yet considered stable. We welcome any comments from testers, especially regarding new “internal devices” that you’d find useful!
17.1. Regular Classes¶
The following classes are intended for general use with the devices they are named after. All classes in this section are concrete (not abstract).
17.1.1. TimeOfDay¶
-
class
gpiozero.
TimeOfDay
(start_time, end_time, *, utc=True, pin_factory=None)[source]¶ Extends
InternalDevice
to provide a device which is active when the computer’s clock indicates that the current time is between start_time and end_time (inclusive) which aretime
instances.The following example turns on a lamp attached to an
Energenie
plug between 7 and 8 AM:from gpiozero import TimeOfDay, Energenie from datetime import time from signal import pause lamp = Energenie(1) morning = TimeOfDay(time(7), time(8)) lamp.source = morning pause()
Note that start_time may be greater than end_time, indicating a time period which crosses midnight.
Parameters: - start_time (time) – The time from which the device will be considered active.
- end_time (time) – The time after which the device will be considered inactive.
- utc (bool) – If
True
(the default), a naive UTC time will be used for the comparison rather than a local time-zone reading. - pin_factory (Factory or None) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
end_time
¶ The time of day after which the device will be considered inactive.
-
start_time
¶ The time of day after which the device will be considered active.
-
value
¶ Returns
True
when the system clock reads betweenstart_time
andend_time
, andFalse
otherwise. Ifstart_time
is greater thanend_time
(indicating a period that crosses midnight), then this returnsTrue
when the current time is greater thanstart_time
or less thanend_time
.
17.1.2. PingServer¶
-
class
gpiozero.
PingServer
(host, *, pin_factory=None)[source]¶ Extends
InternalDevice
to provide a device which is active when a host on the network can be pinged.The following example lights an LED while a server is reachable (note the use of
source_delay
to ensure the server is not flooded with pings):from gpiozero import PingServer, LED from signal import pause google = PingServer('google.com') led = LED(4) led.source_delay = 60 # check once per minute led.source = google pause()
Parameters: - host (str) – The hostname or IP address to attempt to ping.
- pin_factory (Factory or None) – See API - Pins for more information (this is an advanced feature which most users can ignore).
17.1.3. CPUTemperature¶
-
class
gpiozero.
CPUTemperature
(sensor_file='/sys/class/thermal/thermal_zone0/temp', *, min_temp=0.0, max_temp=100.0, threshold=80.0, pin_factory=None)[source]¶ Extends
InternalDevice
to provide a device which is active when the CPU temperature exceeds the threshold value.The following example plots the CPU’s temperature on an LED bar graph:
from gpiozero import LEDBarGraph, CPUTemperature from signal import pause # Use minimums and maximums that are closer to "normal" usage so the # bar graph is a bit more "lively" cpu = CPUTemperature(min_temp=50, max_temp=90) print('Initial temperature: {}C'.format(cpu.temperature)) graph = LEDBarGraph(5, 6, 13, 19, 25, pwm=True) graph.source = cpu pause()
Parameters: - sensor_file (str) – The file from which to read the temperature. This defaults to the
sysfs file
/sys/class/thermal/thermal_zone0/temp
. Whatever file is specified is expected to contain a single line containing the temperature in milli-degrees celsius. - min_temp (float) – The temperature at which
value
will read 0.0. This defaults to 0.0. - max_temp (float) – The temperature at which
value
will read 1.0. This defaults to 100.0. - threshold (float) – The temperature above which the device will be considered “active”.
(see
is_active
). This defaults to 80.0. - pin_factory (Factory or None) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
is_active
¶ Returns
True
when the CPUtemperature
exceeds the threshold.
-
temperature
¶ Returns the current CPU temperature in degrees celsius.
-
value
¶ Returns the current CPU temperature as a value between 0.0 (representing the min_temp value) and 1.0 (representing the max_temp value). These default to 0.0 and 100.0 respectively, hence
value
istemperature
divided by 100 by default.
- sensor_file (str) – The file from which to read the temperature. This defaults to the
sysfs file
17.1.4. LoadAverage¶
-
class
gpiozero.
LoadAverage
(load_average_file='/proc/loadavg', *, min_load_average=0.0, max_load_average=1.0, threshold=0.8, minutes=5, pin_factory=None)[source]¶ Extends
InternalDevice
to provide a device which is active when the CPU load average exceeds the threshold value.The following example plots the load average on an LED bar graph:
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()
Parameters: - load_average_file (str) – The file from which to read the load average. This defaults to the
proc file
/proc/loadavg
. Whatever file is specified is expected to contain three space-separated load averages at the beginning of the file, representing 1 minute, 5 minute and 15 minute averages respectively. - min_load_average (float) – The load average at which
value
will read 0.0. This defaults to 0.0. - max_load_average (float) – The load average at which
value
will read 1.0. This defaults to 1.0. - threshold (float) – The load average above which the device will be considered “active”.
(see
is_active
). This defaults to 0.8. - minutes (int) – The number of minutes over which to average the load. Must be 1, 5 or 15. This defaults to 5.
- pin_factory (Factory or None) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
is_active
¶ Returns
True
when theload_average
exceeds the threshold.
-
load_average
¶ Returns the current load average.
-
value
¶ Returns the current load average as a value between 0.0 (representing the min_load_average value) and 1.0 (representing the max_load_average value). These default to 0.0 and 1.0 respectively.
- load_average_file (str) – The file from which to read the load average. This defaults to the
proc file
17.1.5. DiskUsage¶
-
class
gpiozero.
DiskUsage
(filesystem='/', *, threshold=90.0, pin_factory=None)[source]¶ Extends
InternalDevice
to provide a device which is active when the disk space used exceeds the threshold value.The following example plots the disk usage on an LED bar graph:
from gpiozero import LEDBarGraph, DiskUsage from signal import pause disk = DiskUsage() print('Current disk usage: {}%'.format(disk.usage)) graph = LEDBarGraph(5, 6, 13, 19, 25, pwm=True) graph.source = disk pause()
Parameters: - filesystem (str) – A path within the filesystem for which the disk usage needs to be
computed. This defaults to
/
, which is the root filesystem. - threshold (float) – The disk usage percentage above which the device will be considered
“active” (see
is_active
). This defaults to 90.0. - pin_factory (Factory or None) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
usage
¶ Returns the current disk usage in percentage.
- filesystem (str) – A path within the filesystem for which the disk usage needs to be
computed. This defaults to
17.2. Base Classes¶
The classes in the sections above are derived from a series of base classes, some of which are effectively abstract. The classes form the (partial) hierarchy displayed in the graph below (abstract classes are shaded lighter than concrete classes):
The following sections document these base classes for advanced users that wish to construct classes for their own devices.