Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add SoundEvent.CLAP. #793

Draft
wants to merge 1 commit into
base: v2-docs
Choose a base branch
from
+27 −15
Draft

docs: Add SoundEvent.CLAP. #793

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions docs/microbit_micropython_api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,8 @@ Sound events describe changes in the sound heard by the microphone::
# Value to represent the transition of sound events, from `loud` to `quiet`
# like speaking or background music.
SoundEvent.QUIET = SoundEvent('quiet')
# Value to represent a loud event similar to a clap.
SoundEvent.CLAP = SoundEvent('clap')

Microphone **V2**
-----------------
Expand All @@ -95,9 +97,9 @@ The Microphone is accessed via the `microphone` object::

# Returns the name of the last recorded sound event.
current_event()
# A sound event, such as `SoundEvent.LOUD` or `SoundEvent.QUIET`.
# Returns`true` if sound was heard at least once since the last
# call, otherwise `false`.
# A sound event, such as `SoundEvent.LOUD`, `SoundEvent.QUIET`, or
# `SoundEvent.CLAP`. Returns`true` if sound was heard at least once since
# the last call, otherwise `false`.
was_event(event)
# Returns a tuple of the event history. The most recent is listed last.
# Also clears the sound event history before returning.
Expand Down
34 changes: 22 additions & 12 deletions docs/microphone.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,9 @@ accessible via variables in ``microbit.SoundEvent``:
from ``loud`` to ``quiet`` like speaking or background music.

- ``microbit.SoundEvent.LOUD``: Represents the transition of sound events,
from ``quiet`` to ``loud`` like clapping or shouting.
from ``quiet`` to ``loud`` like shouting.

- ``microbit.SoundEvent.CLAP``: Detects a loud event similar to a clap.

Functions
=========
Expand All @@ -35,16 +37,17 @@ Functions

Get the last recorded sound event.

:return: The event, ``SoundEvent('loud')`` or ``SoundEvent('quiet')``.
:return: The event, ``SoundEvent('loud')``, ``SoundEvent('quiet')`` or
``SoundEvent('clap')``.

.. py:function:: was_event(event)

Check if a sound was heard at least once since the last call.

This call clears the sound history before returning.

:param event: The event to check for, such as ``SoundEvent.LOUD`` or
``SoundEvent.QUIET``.
:param event: The event to check for, such as ``SoundEvent.LOUD``,
``SoundEvent.QUIET`` or ``SoundEvent.CLAP``.
:return: ``True`` if sound was heard at least once since the last call,
otherwise ``False``.

Expand All @@ -54,8 +57,8 @@ Functions

This call does not clear the sound event history.

:param event: The event to check for, such as ``SoundEvent.LOUD`` or
``SoundEvent.QUIET``
:param event: The event to check for, such as ``SoundEvent.LOUD``,
``SoundEvent.QUIET`` or ``SoundEvent.CLAP``.
:return: ``True`` if sound was the most recent heard, ``False`` otherwise.

.. py:function:: get_events()
Expand All @@ -68,7 +71,7 @@ Functions

.. py:function:: set_threshold(event, value)

Set the threshold for a sound event.
Set the threshold for the ``LOUD`` or ``QUIET`` sound events.

The ``SoundEvent.LOUD`` event will be triggered when the sound level
crosses this threshold upwards (from "quiet" to "loud"),
Expand All @@ -80,8 +83,7 @@ Functions
threshold. If the ``SoundEvent.QUIET`` value is set higher than
``SoundEvent.LOUD``, then the "loud" threshold will be set one unit above.

:param event: A sound event, such as ``SoundEvent.LOUD`` or
``SoundEvent.QUIET``.
:param event: A ``SoundEvent.LOUD`` or ``SoundEvent.QUIET`` event.
:param value: The threshold level in the range 0-255. Values outside this
range will be clamped.

Expand Down Expand Up @@ -111,7 +113,10 @@ An example that runs through some of the functions of the microphone API::

while True:
if button_a.is_pressed():
if microphone.current_event() == SoundEvent.LOUD:
if microphone.current_event() == SoundEvent.CLAP:
display.show(Image.DIAMOND)
uart.write('isClap\n')
elif microphone.current_event() == SoundEvent.LOUD:
display.show(Image.SQUARE)
uart.write('isLoud\n')
elif microphone.current_event() == SoundEvent.QUIET:
Expand All @@ -120,7 +125,10 @@ An example that runs through some of the functions of the microphone API::
sleep(500)
display.clear()
if button_b.is_pressed():
if microphone.was_event(SoundEvent.LOUD):
if microphone.was_event(SoundEvent.CLAP):
display.show(Image.DIAMOND)
uart.write('wasClap\n')
elif microphone.was_event(SoundEvent.LOUD):
display.show(Image.SQUARE)
uart.write('wasLoud\n')
elif microphone.was_event(SoundEvent.QUIET):
Expand All @@ -135,7 +143,9 @@ An example that runs through some of the functions of the microphone API::
soundLevel = microphone.sound_level()
print(soundLevel)
for sound in sounds:
if sound == SoundEvent.LOUD:
if sound == SoundEvent.CLAP:
display.show(Image.DIAMOND)
elif sound == SoundEvent.LOUD:
display.show(Image.SQUARE)
elif sound == SoundEvent.QUIET:
display.show(Image.SQUARE_SMALL)
Expand Down