From c15a3bfc971eebac920f7f12c726f5b679ff499e Mon Sep 17 00:00:00 2001 From: Matteo Golin Date: Sun, 12 Jul 2026 17:31:31 -0400 Subject: [PATCH] docs/audio_tone: Add documentation about the audio tone driver This commit adds some documentation about the audio tone driver, how to use it and links to it from the main audio component page. I also added some back links to other audio docs there for convenience. Signed-off-by: Matteo Golin --- Documentation/components/audio/index.rst | 6 +++ .../components/drivers/special/audio.rst | 38 +++++++++++++++++++ 2 files changed, 44 insertions(+) diff --git a/Documentation/components/audio/index.rst b/Documentation/components/audio/index.rst index 0f1ccd2c9ea..7191c5996cb 100644 --- a/Documentation/components/audio/index.rst +++ b/Documentation/components/audio/index.rst @@ -119,3 +119,9 @@ Related Subdirectories * ``drivers/audio`` - Contains the lower-level device specific drivers. * ``apps/system/nxplayer`` - User-mode audio subsystem interface library. + +Related Pages +============= + +* :doc:`/components/drivers/special/audio` +* :doc:`/applications/audioutils/index` diff --git a/Documentation/components/drivers/special/audio.rst b/Documentation/components/drivers/special/audio.rst index bc03c10b7b4..3249c8de105 100644 --- a/Documentation/components/drivers/special/audio.rst +++ b/Documentation/components/drivers/special/audio.rst @@ -4,3 +4,41 @@ Audio Device Drivers See ``include/nuttx/audio/audio.h`` for interface definitions. See also the audio subsystem at ``nuttx/audio/``. + +Audio Tone +---------- + +This driver has an interfaces which accepts a PWM lower-half and a oneshot timer +lower-half. Its features are enabled by ``CONFIG_AUDIO_TONE=y`` You can register +a tone driver as follows: + +.. code:: c + + #include + #include + + /* Somewhere later in the code */ + + int err; + struct pwm_lowerhalf_s *pwm; /* Assume initialized */ + struct oneshot_lowerhalf_s *oneshot; /* Assume initialized */ + + /* Here, the argument '1' is the PWM channel to use */ + + err = tone_register("/dev/tone0", pwm, 1, oneshot); + if (err < 0) + { + syslog(LOG_ERR, "Couldn't register /dev/tone0: %d\n", err); + } + +The PWM interface generates the tone output, and the one-shot driver is used to +get the timing of musical notes correct. + +If you want to try playing sound after the device is registered, you can write +`Music Macro Language (MML) +`_ to the character driver. +For example, here is how you would play Ode to Joy: + +.. code:: console + + nsh> echo "L8eefggfedccdeL6eL16dL4d" > /dev/tone0