SOUND module

About this

This module contains functions to generate audible tones, attaching a piezo buzzer or a speaker to an output GPIO. The module can be used in two ways:

• Raw notation, in which tones are described in terms of their frequency and duration.

• Musical notation, in which tones are described in terms of the musical note, note duration, octave, time signature, etc ...

Tone generator

Tones are synthesized by the module using a tone generator:

Generator	Id	Description
PWM	sound.PWM	The tone is synthesized by a PWM hardware module, which generates a square wave with a 50% duty cycle.
DAC	sound.DAC	The tone is synthesized by an I2S / DAC hardware module, which generates a sine wave at a 38 KHz sampling rate.

Configuration funcions

instance = sound.attach(tone_generator, pin)

Attach a tone generator to a piezo buzzer or a speaker.

Arguments:

• tone_generator: tone generator used to synthesize the tone.
• pin: GPIO where the piezo buzzer or the speaker is attached.

Returns: a sound instance, or an exception. You must store this instance into a variable for further operations with it.

instance:detach()

Detach the tone generator and free all resources used.

Arguments: none.

Returns: nothing, or an exception.

Operation functions

instance:playnote(note, octave)

Play a musical note on the desired octave.

Arguments:

• note: a formatted string (name [accidental] duration) describing the musical note to play and it's duration.

  • note name: the name of the note using the English naming convention.

    English	German	Latin
    A	A	La
    B	H	Si
    C	C	Do
    D	D	Re
    E	E	Mi
    F	F	Fa
    G	G	Sol

    Notes in English naming convention, and their correspondence to other naming conventions.

  • accidental (optional): can be either # to raise the note by a semitone or b to lower the note by the same amount.

  • duration: note duration, relative to a semibreve of 1 time unit.

    Duration	Time units	English	USA	Spanish	Example
    1	1	Semibreve	Whole note	Redonda
    2	1/2	Minim	Half note	Blanca
    4	1/4	Crotchet	Quarter note	Negra
    8	1/8	Quaver	Eighth note	Corchea
    16	1/16	Semiquaver	Sixteenth note	Semi-corchea
    32	1/32	Demisemiquaver	Thirty-second note	Fusa
    64	1/64	Hemidemisemiquaver	Sixty-fourth note	Semi-fusa

    The duration of the note can be increasing by the half of the note duration adding a dot (.).

• octave: the octave in which the note must be played.

Example:

In the following example it is shown how to translate the first 8 bars of the Harry Potter's music sheet.

buzzer = sound.attach(sound.DAC, pio.GPIO26)

buzzer:timesignature(3, 4, 240)

buzzer:playnote("B4",   4)
buzzer:playnote("E4.",  5)
buzzer:playnote("G8",   5)
buzzer:playnote("F#4",  5)
buzzer:playnote("E2",   5)
buzzer:playnote("B4",   5)
buzzer:playnote("A2.",  5)
buzzer:playnote("F#2.", 5)
buzzer:playnote("E4.",  5)
buzzer:playnote("G8",   5)
buzzer:playnote("F#4",  5)
buzzer:playnote("D2",   5)
buzzer:playnote("F4",   5)
buzzer:playnote("B2.",  4)

Returns: nothing, or an exception.

-- Attach the servo to GPIO26
s = servo.attach(pio.GPIO26)

-- Move an standard servo to the 45º position
s:write(45)

-- Attach the servo to GPIO26
s = servo.attach(pio.GPIO26)

-- Move a continuous rotation servo clock wise at full-speed
s:write(180)