.. _buzzer:

Buzzer
######

Drive a buzzer or speaker using the PWM API.

Overview
********

This is a sample app which drives a buzzer or speaker using the
:ref:`PWM API <zephyr:pwm_api>`.

The sample plays a short beep with 1108.73 ㎐ (music note `D♭₆`_) for the
time of a ⅛ `music note`_ at boot time and offers the special shell command
:program:`buzzer` for playing other jingles or short songs.

Requirements
************

The sample requires a buzzer or speaker whose signal pin is connected to a pin
driven by PWM. The buzzer or speaker must be defined in Devicetree using the
``pwm-buzzers`` compatible (part of the sample) and setting its node to the
alias ``pwm-buzzer0``. You will need to do something like this:

.. code-block:: devicetree

   / {
       aliases {
           pwm-buzzer0 = &pwm_buzzer0;
       };

       pwm_buzzers {
           compatible = "pwm-buzzers";
           status = "okay";

           pwm_buzzer0: pwm_buzzer0 {
               pwms = <&pwm0 1 PWM_HZ(880) PWM_POLARITY_NORMAL>;
               label = "PWM_BUZZER";
           };
       };
   };

Note that a commonly used period value is 880 ㎐, twice the concert pitch
frequency of 440 ㎐. See one of the following development boards:

  * :ref:`cytron_maker_rp2040`

Building and Running
********************

* On :ref:`Maker Nano RP2040 <cytron_maker_nano_rp2040>` board:

  .. zephyr-app-commands::
     :app: bridle/samples/buzzer
     :build-dir: buzzer-cytron_maker_nano_rp2040
     :board: cytron_maker_nano_rp2040
     :west-args: -p -S usb-console
     :flash-args: -r uf2
     :goals: flash
     :host-os: unix

* On :ref:`Maker Pi RP2040 <cytron_maker_pi_rp2040>` board:

  .. zephyr-app-commands::
     :app: bridle/samples/buzzer
     :build-dir: buzzer-cytron_maker_pi_rp2040
     :board: cytron_maker_pi_rp2040
     :west-args: -p -S usb-console
     :flash-args: -r uf2
     :goals: flash
     :host-os: unix

Sample Output
=============

(text in bold is a command input, text in angle brackets are keys to press)

.. parsed-literal::
   :class: highlight-console notranslate

   [00:00:00.003,000] <inf> buzzersh: Buzzer shell is ready!


   :bgn:`uart:~$` **<Tab>**
     :bcy:`bridle   buzzer   clear    device   devmem   gpio     help`
     :bcy:`history  kernel   log      pwm      rem      resize   retval`
     :bcy:`shell`

   :bgn:`uart:~$` **help**
   Please press the <Tab> button to see all available commands.
   You can also use the <Tab> button to prompt or auto-complete all commands or its subcommands.
   You can try to call commands with <-h> or <--help> parameter for more information.

   Shell supports following meta-keys:
     Ctrl + (a key from: abcdefklnpuw)
     Alt  + (a key from: bf)
   Please refer to shell documentation for more details.

   Available commands:
     bridle   :Bridle commands.
     buzzer   :Buzzer related commands
     clear    :Clear screen.
     device   :Device commands
     devmem   :Read/write physical memory
               Usage:
               Read memory at address with optional width:
               devmem address [width]
               Write memory at address with mandatory width and value:
               devmem address <width> <value>
     gpio     :GPIO commands
     help     :Prints the help message.
     history  :Command history.
     kernel   :Kernel commands
     log      :Commands for controlling logger
     pwm      :PWM shell commands
     rem      :Ignore lines beginning with 'rem '
     resize   :Console gets terminal screen size or assumes default in case the
               readout fails. It must be executed after each terminal width change
               to ensure correct text display.
     retval   :Print return value of most recent command
     shell    :Useful, not Unix-like shell commands.

   :bgn:`uart:~$` **buzzer -h**
   buzzer - Buzzer related commands
   Subcommands:
     info  :Get buzzer info
     beep  :Use buzzer to beep
     play  :Play one of predefined sounds

   :bgn:`uart:~$` **buzzer info**
   Warning: not yet implemented.

   :bgn:`uart:~$` **buzzer beep**

   :bgn:`uart:~$` **buzzer play**
   play - Play one of predefined sounds
   Subcommands:
     folksong   :Play the 'folksong' song
     xmastime   :Play the 'folksong' song
     funkytown  :Play the 'funkytown' song
     mario      :Play the 'mario' song
     golioth    :Play the 'golioth' song
     tiacsys    :Play the 'tiacsys' song

   :bgn:`uart:~$` **buzzer play folksong**
   :bgn:`uart:~$` **buzzer play xmastime**
   :bgn:`uart:~$` **buzzer play funkytown**
   :bgn:`uart:~$` **buzzer play mario**
   :bgn:`uart:~$` **buzzer play golioth**
   :bgn:`uart:~$` **buzzer play tiacsys**

References
**********

.. target-notes::

.. _D♭₆: https://en.wikipedia.org/wiki/D%E2%99%AD_(musical_note)
.. _music note: https://en.wikipedia.org/wiki/Musical_note