16. 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.


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!

16.1. TimeOfDay

class gpiozero.TimeOfDay(start_time, end_time, utc=True)[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 are time 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(0)
morning = TimeOfDay(time(7), time(8))

lamp.source = morning.values

  • 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.

16.2. PingServer

class gpiozero.PingServer(host)[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.values

Parameters:host (str) – The hostname or IP address to attempt to ping.

16.3. CPUTemperature

class gpiozero.CPUTemperature(sensor_file='/sys/class/thermal/thermal_zone0/temp', min_temp=0.0, max_temp=100.0, threshold=80.0)[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.values

  • 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”. This defaults to 80.0.

Returns True when the CPU temperature exceeds the threshold.


Returns the current CPU temperature in degrees celsius.

16.4. 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.

16.5. InternalDevice

class gpiozero.InternalDevice[source]

Extends Device to provide a basis for devices which have no specific hardware representation. These are effectively pseudo-devices and usually represent operating system services like the internal clock, file systems or network facilities.