Merge pull request gpiozero#729 from RPi-Distro/tones

Tones

Author: waveform80

docs/api_output.rst

@@ -84,8 +84,8 @@ Buzzer
 TonalBuzzer
 -----------
 
-.. autoclass:: TonalBuzzer(pin, \*, initial_value=None, mid_note='A4', octaves=1, pin_factory=None)
-    :members: play, stop, note_value, octaves, min_note, mid_note, max_note, is_active, value
+.. autoclass:: TonalBuzzer(pin, \*, initial_value=None, mid_tone=Tone('A4'), octaves=1, pin_factory=None)
+    :members: play, stop, octaves, min_tone, mid_tone, max_tone, tone, is_active, value
 
 
 Motor

docs/api_tones.rst

@@ -0,0 +1,18 @@
+===========
+API - Tones
+===========
+
+.. module:: gpiozero.tones
+
+GPIO Zero includes a :class:`Tone` class intended for use with the
+:class:`~gpiozero.TonalBuzzer`. This class is in the ``tones`` module of GPIO
+Zero and is typically imported as follows::
+
+    from gpiozero.tones import Tone
+
+
+Tone
+====
+
+.. autoclass:: Tone
+    :members:

docs/index.rst

@@ -56,6 +56,7 @@ Table of Contents
     api_internal
     api_generic
     api_tools
+    api_tones
     api_info
     api_pins
     api_exc

gpiozero/compat.py

@@ -93,6 +93,7 @@ def median(data):
         return (data[i - 1] + data[i]) / 2
 
 
+# Backported from py3.3
 def log2(x):
     return math.log(x, 2)
 

gpiozero/exc.py

@@ -208,3 +208,6 @@ class ThresholdOutOfRange(GPIOZeroWarning):
 
 class CallbackSetToNone(GPIOZeroWarning):
     "Warning raised when a callback is set to None when its previous value was None"
+
+class AmbiguousTone(GPIOZeroWarning):
+    "Warning raised when a Tone is constructed with an ambiguous number"

gpiozero/internal_devices.py

@@ -483,8 +483,12 @@ def usage(self):
         """
         # XXX Use os.statvfs?
         df = subprocess.Popen(['df', '--output=pcent', self.filesystem], stdout=subprocess.PIPE)
-        output = df.communicate()[0].split(b'\n')[1].split()[0]
-        return float(output.decode('UTF-8').rstrip('%'))
+        try:
+            output = df.communicate()[0].split(b'\n')[1].split()[0]
+            return float(output.decode('UTF-8').rstrip('%'))
+        finally:
+            df.stdout.close()
+            df.wait()
 
     @property
     def value(self):

gpiozero/output_devices.py

@@ -53,6 +53,7 @@
 from .devices import GPIODevice, Device, CompositeDevice
 from .mixins import SourceMixin
 from .threads import GPIOThread
+from .tones import Tone
 
 
 class OutputDevice(SourceMixin, GPIODevice):
@@ -626,74 +627,75 @@ class TonalBuzzer(SourceMixin, CompositeDevice):
         :class:`~gpiozero.pins.pigpio.PiGPIOFactory`.
     """
 
-    def __init__(self, pin=None, initial_value=None, mid_note='A4', octaves=1,
-                 pin_factory=None):
-        self._validate_note_range(mid_note, octaves)
+    def __init__(self, pin=None, initial_value=None, mid_tone=Tone("A4"),
+                 octaves=1, pin_factory=None):
+        self._mid_tone = None
         super(TonalBuzzer, self).__init__(
             pwm_device=PWMOutputDevice(
                 pin=pin, pin_factory=pin_factory
             ), pin_factory=pin_factory)
         try:
+            self._mid_tone = Tone(mid_tone)
+            if not (0 < octaves <= 9):
+                raise ValueError('octaves must be between 1 and 9')
             self._octaves = octaves
+            try:
+                self.min_tone.note
+            except ValueError:
+                raise ValueError(
+                    '%r is too low for %d octaves' %
+                    (self._mid_tone, self._octaves))
+            try:
+                self.max_tone.note
+            except ValueError:
+                raise ValueError(
+                    '%r is too high for %d octaves' %
+                    (self._mid_tone, self._octaves))
             self.value = initial_value
         except:
             self.close()
             raise
 
     def __repr__(self):
         try:
-            return '<gpiozero.%s object on pin %r, is_active=%s>' % (
-                self.__class__.__name__, self.pwm_device.pin, self.is_active)
+            if self.value is None:
+                return '<gpiozero.TonalBuzzer object on pin %r, silent>' % (
+                    self.pwm_device.pin,)
+            else:
+                return '<gpiozero.TonalBuzzer object on pin %r, playing %s>' % (
+                    self.pwm_device.pin, self.tone.note)
         except:
-            return super(OutputDevice, self).__repr__()
-
-    def _note_to_midi(self, note):
-        if isinstance(note, bytes):
-            note = note.decode('ascii')
-        if isinstance(note, str):
-            nt, num = note[:-1].replace('#', 'S'), int(note[-1])
-            notes = 'C CS D DS E F FS G GS A AS B'.split(' ')
-            note = (num  + 1) * 12 + notes.index(nt)
-        return note
-
-    def _note_to_freq(self, note):
-        midi = self._note_to_midi(note)
-        return 2**((midi-69)/12)*440
-
-    def _validate_note_range(self, mid_note, octaves):
-        self._mid_note = self._note_to_midi(mid_note)
-        self._octaves = octaves
-        if octaves < 1:
-            raise ValueError('octaves must be at least 1')
-        if self.min_note < 1:
-            plural = 's' if octaves > 1 else ''
-            raise ValueError(
-                'mid_note too low for {} octave{}'.format(octaves, plural))
-
-    def note_value(self, note):
-        """
-        Convert the given note to a normalized value scaled -1 to 1 relative to
-        the buzzer's range. If note is :data:`None`, :data:`None` is returned.
-        """
-        if note is None:
-            return None
-        note = self._note_to_midi(note)
-        return (note - self.mid_note) / (self.max_note - self.mid_note)
+            return super(TonalBuzzer, self).__repr__()
 
-    def play(self, note):
+    def play(self, tone):
         """
-        Play the given note e.g. ``play(60)`` (MIDI) or ``play('C4')`` (note).
-        ``play(None)`` turns the buzzer off.
+        Play the given *tone*. This can either be an instance of
+        :class:`~gpiozero.tones.Tone` or can be anything that could be used to
+        construct an instance of :class:`~gpiozero.tones.Tone`.
+
+        For example::
+
+            >>> from gpiozero import TonalBuzzer
+            >>> from gpiozero.tones import Tone
+            >>> b = TonalBuzzer(17)
+            >>> b.play(Tone("A4"))
+            >>> b.play(Tone(220.0)) # Hz
+            >>> b.play(Tone(60)) # middle C in MIDI notation
+            >>> b.play("A4")
+            >>> b.play(220.0)
+            >>> b.play(60)
         """
-        if note is None:
+        if tone is None:
             self.value = None
         else:
-            freq = self._note_to_freq(note)
-            if self.min_frequency <= freq <= self.max_frequency:
+            if not isinstance(tone, Tone):
+                tone = Tone(tone)
+            freq = tone.frequency
+            if self.min_tone.frequency <= tone <= self.max_tone.frequency:
                 self.pwm_device.pin.frequency = freq
                 self.pwm_device.value = 0.5
             else:
-                raise ValueError("note out of the device's range")
+                raise ValueError("tone is out of the device's range")
 
     def stop(self):
         """
@@ -702,33 +704,46 @@ def stop(self):
         """
         self.value = None
 
+    @property
+    def tone(self):
+        """
+        Returns the :class:`~gpiozero.tones.Tone` that the buzzer is currently
+        playing, or :data:`None` if the buzzer is silent. This property can
+        also be set to play the specified tone.
+        """
+        if self.pwm_device.pin.frequency is None:
+            return None
+        else:
+            return Tone.from_frequency(self.pwm_device.pin.frequency)
+
+    @tone.setter
+    def tone(self, value):
+        self.play(value)
+
     @property
     def value(self):
         """
-        Represents the state of the buzzer as a value between 0 (representing
+        Represents the state of the buzzer as a value between -1 (representing
         the minimum note) and 1 (representing the maximum note). This can also
         be the special value :data:`None` indicating that the buzzer is
         currently silent.
         """
         if self.pwm_device.pin.frequency is None:
             return None
         else:
-            freq = self.pwm_device.pin.frequency
-            mid_freq = self.mid_frequency
             try:
-                return log2(freq / mid_freq) / self.octaves
+                return log2(
+                    self.pwm_device.pin.frequency / self.mid_tone.frequency
+                ) / self.octaves
             except ZeroDivisionError:
-                return 0
+                return 0.0
 
     @value.setter
     def value(self, value):
         if value is None:
             self.pwm_device.pin.frequency = None
         elif -1 <= value <= 1:
-            if value == 0:
-                freq = self.mid_frequency
-            else:
-                freq = self.mid_frequency * 2**(self.octaves * value)
+            freq = self.mid_tone.frequency * 2 ** (self.octaves * value)
             self.pwm_device.pin.frequency = freq
             self.pwm_device.value = 0.5
         else:
@@ -751,49 +766,28 @@ def octaves(self):
         return self._octaves
 
     @property
-    def min_note(self):
-        """
-        The minimum note available (i.e. the MIDI note represented when value
-        is -1).
-        """
-        return self.mid_note - 12 * self.octaves
-
-    @property
-    def mid_note(self):
-        """
-        The middle note available (i.e. the MIDI note represented when value is
-        0).
-        """
-        return self._mid_note
-
-    @property
-    def max_note(self):
-        """
-        The maximum note available (i.e. the MIDI note represented when value
-        is 1).
-        """
-        return self.mid_note + 12 * self.octaves
-
-    @property
-    def min_frequency(self):
+    def min_tone(self):
         """
-        The frequency of the minimum note.
+        The lowest tone that the buzzer can play, i.e. the tone played
+        when :attr:`value` is -1.
         """
-        return self._note_to_freq(self.min_note)
+        return self._mid_tone.down(12 * self.octaves)
 
     @property
-    def mid_frequency(self):
+    def mid_tone(self):
         """
-        The frequency of the middle note.
+        The middle tone available, i.e. the tone played when :attr:`value` is
+        0.
         """
-        return self._note_to_freq(self.mid_note)
+        return self._mid_tone
 
     @property
-    def max_frequency(self):
+    def max_tone(self):
         """
-        The frequency of the maximum note.
+        The highest tone that the buzzer can play, i.e. the tone played when
+        :attr:`value` is 1.
         """
-        return self._note_to_freq(self.max_note)
+        return self._mid_tone.up(12 * self.octaves)
 
 
 class PWMLED(PWMOutputDevice):