LEDBoard(*pins, pwm=False, active_high=True, initial_value=False, pin_factory=None, **named_pins)
Extends LEDCollection and represents a generic LED board or collection of LEDs.
The following example turns on all the LEDs on a board containing 5 LEDs attached to GPIO pins 2 through 6:
from gpiozero import LEDBoard
leds = LEDBoard(2, 3, 4, 5, 6)
leds.on()
Parameters:
*pins – Specify the GPIO pins that the LEDs of the board are attached to.
pwm (bool) – If True, construct PWMLED instances for each pin. If False (the default), construct regular LED instances.
active_high (bool) – If True (the default), the on() method will set all the associated pins to HIGH. If False, the on() method will set all pins to LOW (the off() method always does the opposite).
initial_value (bool or None) – If False (the default), all LEDs will be off initially. If None, each device will be left in whatever state the pin is found in when configured for output (warning: this can be on). If True, the device will be switched on initially.
pin_factory (Factory or None) – Advanced users
**named_pins – Specify GPIO pins that LEDs of the board are attached to, associating each LED with a property name. You can designate as many pins as necessary and use any names, provided they’re not already in use by something else. You can also specify LEDBoard instances to create trees of LEDs.
from gpiozero import LEDBoard
leds = LEDBoard(2, 3, 4, 5, pwm=True)
leds[0].value=0.5 #LED 1 half bright
leds[1].value=0 #LED 2 off
leds[2].value=1 #LED 3 on
leds[-1].value=0 #last LED off
from gpiozero import LEDBoard
leds = LEDBoard(2, 3, 4, 5)
leds[0].value=0 #LED 1 off
leds[1].value=0 #LED 2 off
leds[2].value=1 #LED 3 on
leds[-1].value=0 #last LED off
blink(on_time=1, off_time=1, fade_in_time=0, fade_out_time=0, n=None, background=True)
Make all the LEDs turn on and off repeatedly.
Parameters:
on_time (float) – Number of seconds on. Defaults to 1 second.
off_time (float) – Number of seconds off. Defaults to 1 second.
fade_in_time (float) – Number of seconds to spend fading in. Defaults to 0. Must be 0 if pwm was False when the class was constructed (ValueError will be raised if not).
fade_out_time (float) – Number of seconds to spend fading out. Defaults to 0. Must be 0 if pwm was False when the class was constructed (ValueError will be raised if not).
n (int or None) – Number of times to blink; None (the default) means forever.
from gpiozero import LEDBoard
leds = LEDBoard(2, 3, 4, 5)
leds.blink(on_time=1, off_time=1, fade_in_time=0, fade_out_time=0, n=10)
off(*args) - If no arguments are specified, turn all the LEDs off. If arguments are specified, they must be the indexes of the LEDs you wish to turn off.If blink() is currently active, it will be stopped first.
Parameters: args (int) – The index(es) of the LED(s) to turn off. If no indexes are specified turn off all LEDs. For example:
from gpiozero import LEDBoard
leds = LEDBoard(2, 3, 4, 5)
leds.on() # turn on all LEDs
leds.off(0) # turn off the first LED (pin 2)
leds.off(-1) # turn off the last LED (pin 5)
leds.off(1, 2) # turn off the middle LEDs (pins 3 and 4)
leds.on() # turn on all LEDs
on(*args) - If no arguments are specified, turn all the LEDs on. If arguments are specified, they must be the indexes of the LEDs you wish to turn on. For example:
from gpiozero import LEDBoard
leds = LEDBoard(2, 3, 4, 5)
leds.on(0) # turn on the first LED (pin 2)
leds.on(-1) # turn on the last LED (pin 5)
leds.on(1, 2) # turn on the middle LEDs (pins 3 and 4)
leds.off() # turn off all LEDs
leds.on() # turn on all LEDs
If blink() is currently active, it will be stopped first. Parameters: args (int) – The index(es) of the LED(s) to turn on. If no indexes are specified turn on all LEDs.
pulse(fade_in_time=1, fade_out_time=1, n=None, background=True)
Make all LEDs fade in and out repeatedly. Note that this method will only work if the pwm parameter was True at construction time.
Parameters:
fade_in_time (float) – Number of seconds to spend fading in. Defaults to 1.
fade_out_time (float) – Number of seconds to spend fading out. Defaults to 1.
n (int or None) – Number of times to blink; None (the default) means forever.
background (bool) – For advanced users.
from gpiozero import LEDBoard
leds = LEDBoard(2, 3, 4, 5)
leds.pulse(fade_in_time=1, fade_out_time=1, n=10)
toggle(*args) If no arguments are specified, toggle the state of all LEDs. If arguments are specified, they must be the indexes of the LEDs you wish to toggle. For example:
from gpiozero import LEDBoard
leds = LEDBoard(2, 3, 4, 5)
leds.toggle(0) # turn on the first LED (pin 2)
leds.toggle(-1) # turn on the last LED (pin 5)
leds.toggle() # turn the first and last LED off, and the
# middle pair on
If blink() is currently active, it will be stopped first.
Parameters: args (int) – The index(es) of the LED(s) to toggle. If no indexes are specified toggle the state of all LEDs.
gpiozero.LEDBarGraph(*pins, pwm=False, active_high=True, initial_value=0, pin_factory=None)
Extends LEDCollection to control a line of LEDs representing a bar graph. Positive values (0 to 1) light the LEDs from first to last. Negative values (-1 to 0) light the LEDs from last to first.
The following example demonstrates turning on the first two and last two LEDs in a board containing five LEDs attached to GPIOs 2 through 6:
from gpiozero import LEDBarGraph
from time import sleep
graph = LEDBarGraph(2, 3, 4, 5, 6)
graph.value = 2/5 # Light the first two LEDs only
sleep(1)
graph.value = -2/5 # Light the last two LEDs only
sleep(1)
graph.off()
As with all other output devices, source and values are supported:
from gpiozero import LEDBarGraph, MCP3008
from signal import pause
graph = LEDBarGraph(2, 3, 4, 5, 6, pwm=True)
pot = MCP3008(channel=0)
graph.source = pot
pause()
Parameters:
*pins – Specify the GPIO pins that the LEDs of the bar graph are attached to. See Pin Numbering for valid pin numbers. You can designate as many pins as necessary.
pwm (bool) – If True, construct PWMLED instances for each pin. If False (the default), construct regular LED instances. This parameter can only be specified as a keyword parameter.
active_high (bool) – If True (the default), the on() method will set all the associated pins to HIGH. If False, the on() method will set all pins to LOW (the off() method always does the opposite). This parameter can only be specified as a keyword parameter.
initial_value (float) – The initial value of the graph given as a float between -1 and +1. Defaults to 0.0. This parameter can only be specified as a keyword parameter.
pin_factory (Factory or None) – For advanced users.
from gpiozero import LEDBarGraph
from time import sleep
graph = LEDBarGraph(2, 3, 4, 5, 6, pwm=True)
graph.value = 2.5/5 # Light the first two LEDs and third at half brightness
sleep(1)
graph.value = -2.5/5 # Light the last two LEDs and third at half brightness
sleep(1)
graph.off() #turn off all LEDs
lit_count The number of LEDs on the bar graph actually lit up. Note that just like value, this can be negative if the LEDs are lit from last to first.
from gpiozero import LEDBarGraph
from time import sleep
graph = LEDBarGraph(2, 3, 4, 5, 6, pwm=True)
graph.value = 2.5/5 # Light the first two LEDs and third at half brightness
print("LEDS on",graph.lit_count) #2.5
sleep(1)
graph.value = -2.5/5 # Light the last two LEDs and third at half brightness
print("LEDS on",graph.lit_count) #-2.5
sleep(1)
source The iterable to use as a source of values for value.
value The value of the LED bar graph. When no LEDs are lit, the value is 0. When all LEDs are lit, the value is 1. Values between 0 and 1 light LEDs linearly from first to last. Values between 0 and -1 light LEDs linearly from last to first.
To light a particular number of LEDs, simply divide that number by the number of LEDs. For example, if your graph contains 3 LEDs, the following will light the first:
from gpiozero import LEDBarGraph
graph = LEDBarGraph(12, 16, 19)
graph.value = 1/3
Note Setting value to -1 will light all LEDs. However, querying it subsequently will return 1 as both representations are the same in hardware. The readable range of value is effectively -1 < value <= 1.
values An infinite iterator of values read from value.
TimeOfDay(start_time, end_time, *, utc=True, pin_factory=None)
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, LED
from datetime import time
from signal import pause
lamp = LED(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.
from gpiozero import TimeOfDay, LED
from datetime import time
from signal import pause
lamp = LED(1)
morning = TimeOfDay(time(13), time(8)) #starts at 1pm to 8am
lamp.source = morning
pause()
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) – for advanced users
value Returns True when the system clock reads between start_time and end_time, and False otherwise. If start_time is greater than end_time (indicating a period that crosses midnight), then this returns True when the current time is greater than start_time or less than end_time.
from gpiozero import TimeOfDay, LED
from datetime import time
from signal import pause
lamp = LED(1)
morning = TimeOfDay(time(1), time(8)) #starts at 1pm to 8am
print(morning.value) #between 1am to 8am prints true
pause()
PingServer(host, *, pin_factory=None)
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) – for advanced users.
value Returns True if the host returned a single ping, and False otherwise.
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
print("Did it ping?", google.value)
pause()
17.1.3. CPUTemperature classgpiozero.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 CPU temperature 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 is temperature divided by 100 by default.
17.1.4. LoadAverage classgpiozero.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 the load_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.
17.1.5. DiskUsage classgpiozero.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). is_active Returns True when the disk usage exceeds the threshold. usage Returns the current disk usage in percentage. value Returns the current disk usage as a value between 0.0 and 1.0 by dividing usage by 100.