diff --git a/docs/_static/.keep b/docs/_static/.keep new file mode 100644 index 0000000..e69de29 diff --git a/docs/api.rst b/docs/api.rst index 077b562..ac5879c 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,14 +3,43 @@ picozero API .. module:: picozero -Button ------- - LED --- .. autofunction:: LED +DigitalLED +---------- + +.. autoclass:: DigitalLED + :show-inheritance: + :inherited-members: + :members: + +PWMLED +---------- + +.. autoclass:: PWMLED + :show-inheritance: + :inherited-members: + :members: + +Button +------ + +.. autoclass:: Button + :show-inheritance: + :inherited-members: + :members: + +Switch +------ + +.. autoclass:: Switch + :show-inheritance: + :inherited-members: + :members: + RGBLED ------ @@ -22,15 +51,8 @@ Speaker ------- Potentiometer --------------- +------------- TemperatureSensor ----------------- -DigitalLED ----------- - -.. autoclass:: DigitalLED - :show-inheritance: - :inherited-members: - :members: \ No newline at end of file diff --git a/docs/examples/led_on_off.py b/docs/examples/led_on_off.py index 6ea9371..4ae4cee 100644 --- a/docs/examples/led_on_off.py +++ b/docs/examples/led_on_off.py @@ -3,7 +3,6 @@ led = LED(14) -while True: - led.toggle() - sleep(1) - +led.on() +sleep(1) +led.off() diff --git a/docs/examples/led_toggle.py b/docs/examples/led_toggle.py new file mode 100644 index 0000000..6ea9371 --- /dev/null +++ b/docs/examples/led_toggle.py @@ -0,0 +1,9 @@ +from picozero import LED +from time import sleep + +led = LED(14) + +while True: + led.toggle() + sleep(1) + diff --git a/docs/recipes.rst b/docs/recipes.rst index 721650f..40e4e62 100644 --- a/docs/recipes.rst +++ b/docs/recipes.rst @@ -148,7 +148,7 @@ Control a passive buzzer or speaker that can play different tones or frequencies .. literalinclude:: examples/speaker.py Internal Temperature Sensor ------------------------ +--------------------------- Check the internal temperature of the Raspberry Pi Pico in degrees Celcius: diff --git a/picozero/__init__.py b/picozero/__init__.py index 33f72b0..5e95691 100644 --- a/picozero/__init__.py +++ b/picozero/__init__.py @@ -7,6 +7,7 @@ LED, DigitalInputDevice, Button, + Switch, RGBLED, AnalogInputDevice, Potentiometer, diff --git a/picozero/picozero.py b/picozero/picozero.py index 0877cf4..056293c 100644 --- a/picozero/picozero.py +++ b/picozero/picozero.py @@ -67,7 +67,9 @@ def stop(self): self._timer.deinit() class OutputDevice: - + """ + Base class for output devices. + """ def __init__(self, active_high=True, initial_value=False): self.active_high = active_high self._write(initial_value) @@ -75,6 +77,12 @@ def __init__(self, active_high=True, initial_value=False): @property def active_high(self): + """ + Sets or returns the active_high property. If :data:`True`, the + :meth:`on` method will set the Pin to HIGH. If :data:`False`, + the :meth:`on` method will set the Pin toLOW (the :meth:`off` method + always does the opposite). + """ return self._active_state @active_high.setter @@ -109,7 +117,7 @@ def off(self): @property def is_active(self): """ - Returns :data:`True` is the device is on. + Returns :data:`True` if the device is on. """ return bool(self.value) @@ -171,6 +179,10 @@ def _write(self, value): self._pin.value(self._value_to_state(value)) def close(self): + """ + Closes the device and turns the device off. Once closed, the device + can no longer be used. + """ super().close() self._pin = None @@ -234,9 +246,16 @@ def _write(self, value): @property def is_active(self): + """ + Returns :data:`True` if the device is on. + """ return self.value != 0 def close(self): + """ + Closes the device and turns the device off. Once closed, the device + can no longer be used. + """ super().close() del PWMOutputDevice._channels_used[ PWMOutputDevice.PIN_TO_PWM_CHANNEL[self._pin_num] @@ -393,11 +412,21 @@ def LED(pin, use_pwm=True, active_high=True, initial_value=False): pico_led = LED(25) class InputDevice: + """ + Base class for input devices. + """ def __init__(self, active_state=None): self._active_state = active_state @property def active_state(self): + """ + Sets or returns the active state of the device. If :data:`None` (the default), + the device will return the value that the pin is set to. If + :data:`True`, the device will return :data:`True` if the pin is + HIGH. If :data:`False`, the device will return :data:`False` if the + pin is LOW. + """ return self._active_state @active_state.setter @@ -407,9 +436,32 @@ def active_state(self, value): @property def value(self): + """ + Returns the current value of the device. This is either :data:`True` + or :data:`False` depending on the value of :attr:`active_state`. + """ return self._read() class DigitalInputDevice(InputDevice): + """ + :param int pin: + The pin that the device is connected to. + + :param bool pull_up: + If :data:`True` (the default), the device will be pulled up to + HIGH. If :data:`False`, the device will be pulled down to LOW. + + :param bool active_state: + If :data:`True` (the default), the device will return :data:`True` + if the pin is HIGH. If :data:`False`, the device will return + :data:`False` if the pin is LOW. + + :param float bounce_time: + The bounce time for the device. If set, the device will ignore + any button presses that happen within the bounce time after a + button release. This is useful to prevent accidental button + presses from registering as multiple presses. + """ def __init__(self, pin, pull_up=False, active_state=None, bounce_time=None): super().__init__(active_state) self._pin = Pin( @@ -468,14 +520,23 @@ def _pin_change(self, p): @property def is_active(self): + """ + Returns :data:`True` if the device is active. + """ return bool(self.value) @property def is_inactive(self): + """ + Returns :data:`True` if the device is inactive. + """ return not bool(self.value) @property def when_activated(self): + """ + Returns a :samp:`callback` that will be called when the device is activated. + """ return self._when_activated @when_activated.setter @@ -484,6 +545,9 @@ def when_activated(self, value): @property def when_deactivated(self): + """ + Returns a :samp:`callback` that will be called when the device is deactivated. + """ return self._when_deactivated @when_activated.setter @@ -491,12 +555,31 @@ def when_deactivated(self, value): self._when_deactivated = value def close(self): + """ + Closes the device and releases any resources. Once closed, the device + can no longer be used. + """ self._pin.irq(handler=None) self._pin = None class Switch(DigitalInputDevice): - def __init__(self, pin, pull_up=True, bounce_time=0.02): + """ + :param int pin: + The pin that the device is connected to. + + :param bool pull_up: + If :data:`True` (the default), the device will be pulled up to + HIGH. If :data:`False`, the device will be pulled down to LOW. + + :param float bounce_time: + The bounce time for the device. If set, the device will ignore + any button presses that happen within the bounce time after a + button release. This is useful to prevent accidental button + presses from registering as multiple presses. Defaults to 0.02 + seconds. + """ + def __init__(self, pin, pull_up=True, bounce_time=0.02): super().__init__(pin=pin, pull_up=pull_up, bounce_time=bounce_time) Switch.is_closed = Switch.is_active @@ -504,7 +587,6 @@ def __init__(self, pin, pull_up=True, bounce_time=0.02): Switch.when_closed = Switch.when_activated Switch.when_opened = Switch.when_deactivated - class Button(Switch): pass