This is an automated email from the ASF dual-hosted git repository.
xiaoxiang781216 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new c15a3bfc971 docs/audio_tone: Add documentation about the audio tone
driver
c15a3bfc971 is described below
commit c15a3bfc971eebac920f7f12c726f5b679ff499e
Author: Matteo Golin <[email protected]>
AuthorDate: Sun Jul 12 17:31:31 2026 -0400
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 <[email protected]>
---
Documentation/components/audio/index.rst | 6 ++++
Documentation/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 <nuttx/audio/tone.h>
+ #include <nuttx/timers/pwm.h>
+
+ /* 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)
+<https://en.wikipedia.org/wiki/Music_Macro_Language>`_ to the character driver.
+For example, here is how you would play Ode to Joy:
+
+.. code:: console
+
+ nsh> echo "L8eefggfedccdeL6eL16dL4d" > /dev/tone0
