Merge branch 'audio-cleaner-resets' of https://github.com/markshannon/micropython into markshannon-audio-cleaner-resets

Author: dpgeorge

docs/audio.rst

@@ -0,0 +1,71 @@
+Audio
+*******
+
+.. py:module:: audio
+
+This module allows you play sounds from a speaker attached to the Microbit.
+In order to use the audio module you will need to provide a sound source.
+
+A sound source is an iterable (sequence, like list or tuple, or a generator) of
+frames, each of 32 samples.
+The ``audio`` modules plays samples at the rate of 7812.5 samples per second,
+which means that it can reproduce frequencies up to 3.9kHz.
+
+Functions
+=========
+
+.. py:function:: play(source, wait=True, pins=(pin0, pin1))
+
+    Play the source to completion.
+
+    ``source`` is an iterable, each element of which must be an ``AudioFrame``.
+
+    If ``wait`` is ``True``, this function will block until the source is exhausted.
+
+    ``pins`` specifies which pins the speaker is connected to.
+
+Classes
+=======
+
+.. py:class::
+    AudioFrame
+
+    An ``AudioFrame`` object is a list of 32 samples each of which is a signed byte
+    (whole number between -128 and 127).
+
+    It takes just over 4 ms to play a single frame.
+
+Using audio
+===========
+
+You will need a sound source, as input to the ``play`` function. You can generate your own, like in
+``examples/waveforms.py`` or you can use the sound sources provided by modules like ``synth``.
+
+
+Technical Details
+=================
+
+.. note::
+    You don't need to understand this section to use the ``audio`` module.
+    It is just here in case you wanted to know how it works.
+
+The ``audio`` module consumes samples at 7812.5 kHz, and uses linear interpolation to
+output a PWM signal at 32.5 kHz, which gives tolerable sound quality.
+
+The function ``play`` fully copies all data from each ``AudioFrame`` before it
+calls ``next()`` for the next frame, so a sound source can use the same ``AudioFrame``
+repeatedly.
+
+The ``audio`` module has an internal 64 sample buffer from which it reads samples.
+When reading reaches the start or the mid-point of the buffer, it triggers a callback to
+fetch the next ``AudioFrame`` which is then copied into the buffer.
+This means that a sound source has under 4ms to compute the next ``AudioFrame``,
+and for reliable operation needs to take less 2ms (which is 32000 cycles, so should be plenty).
+
+
+Example
+=======
+
+.. include:: ../examples/waveforms.py
+    :code: python
+

examples/play_file.py

@@ -0,0 +1,14 @@
+#Plays a file on the specified pins.
+import audio
+
+def audio_generator(file, frame):
+    ln = -1
+    while ln:
+        ln = file.readinto(frame)
+        yield frame
+
+def play_file(name, pin=None, return_pin=None):
+    #Do allocation here, as we can't do it in an interrupt.
+    frame = audio.AudioFrame()
+    with open(name) as file:
+        audio.play(audio_generator(file, frame), pin=pin, return_pin=return_pin)

examples/reverb.py

@@ -0,0 +1,50 @@
+import audio
+
+def from_file(file, frame):
+    ln = -1
+    while ln:
+        ln = file.readinto(frame)
+        yield frame
+
+def reverb_gen(src, buckets, reflect, fadeout):
+    bucket_count = len(buckets)
+    bucket = 0
+    for frame in src:
+        echo = buckets[bucket]
+        echo *= reflect
+        echo += frame
+        yield echo
+        buckets[bucket] = echo
+        bucket += 1
+        if bucket == bucket_count:
+            bucket = 0
+    while fadeout:
+        fadeout -= 1
+        echo = buckets[bucket]
+        echo *= reflect
+        yield echo
+        buckets[bucket] = echo
+        bucket += 1
+        if bucket == bucket_count:
+            bucket = 0
+
+def reverb(src, delay, reflect):
+    #Do all allocation up front, so we don't need to do any in the generator.
+    bucket_count = delay>>2
+    buckets = [ None ] * bucket_count
+    for i in range(bucket_count):
+        buckets[i] = audio.AudioFrame()
+    vol = 1.0
+    fadeout = 0
+    while vol > 0.05:
+        fadeout += bucket_count
+        vol *= reflect
+    return reverb_gen(src, buckets, reflect, fadeout)
+
+def play_file(name, delay=80, reflect=0.5):
+    #Do allocation here, as we can't do it in an interrupt.
+    frame = audio.AudioFrame()
+    with open(name) as file:
+        gen = from_file(file, frame)
+        r = reverb(gen, delay, reflect)
+        audio.play(r)

examples/waveforms.py

@@ -0,0 +1,65 @@
+from microbit import display, sleep, button_a
+import audio
+import math
+
+def repeated_frame(frame, count):
+    for i in range(count):
+        yield frame
+
+# Press button A to skip to next wave.
+def show_wave(name, frame, duration=1500):
+    display.scroll(name + " wave", wait=False,delay=100)
+    audio.play(repeated_frame(frame, duration),wait=False)
+    for i in range(75):
+        sleep(100)
+        if button_a.is_pressed():
+            display.clear()
+            audio.stop()
+            break
+
+frame = audio.AudioFrame()
+
+for i in range(len(frame)):
+    frame[i] = int(math.sin(math.pi*i/16)*124+128.5)
+show_wave("Sine", frame)
+
+triangle = audio.AudioFrame()
+
+QUARTER = len(triangle)//4
+for i in range(QUARTER):
+    triangle[i] = i*15
+    triangle[i+QUARTER] = 248-i*15
+    triangle[i+QUARTER*2] = 128-i*15
+    triangle[i+QUARTER*3] = i*15+8
+show_wave("Triangle", triangle)
+
+square = audio.AudioFrame()
+
+HALF = len(square)//2
+for i in range(HALF):
+    square[i] = 8
+    square[i+HALF] = 248
+show_wave("Square", square)
+sleep(1000)
+
+for i in range(len(frame)):
+    frame[i] = 252-i*8
+show_wave("Sawtooth", frame)
+
+del frame
+
+#Generate a waveform that goes from triangle to square wave, reasonably smoothly.
+frames = [ None ] * 32
+for i in range(32):
+    frames[i] = frame = audio.AudioFrame()
+    for j in range(len(triangle)):
+        frame[j] = (triangle[j]*(32-i) + square[j]*i)>>5
+
+def repeated_frames(frames, count):
+    for frame in frames:
+        for i in range(count):
+            yield frame
+
+
+display.scroll("Ascending wave", wait=False)
+audio.play(repeated_frames(frames, 60))

inc/genhdr/qstrdefs.generated.h

@@ -351,6 +351,7 @@ QDEF(MP_QSTR_read_analog, (const byte*)"\x62\x0b" "read_analog")
 QDEF(MP_QSTR_write_analog, (const byte*)"\x2d\x0c" "write_analog")
 QDEF(MP_QSTR_set_analog_period, (const byte*)"\x08\x11" "set_analog_period")
 QDEF(MP_QSTR_set_analog_period_microseconds, (const byte*)"\xee\x1e" "set_analog_period_microseconds")
+QDEF(MP_QSTR_get_analog_period_microseconds, (const byte*)"\x7a\x1e" "get_analog_period_microseconds")
 QDEF(MP_QSTR_is_touched, (const byte*)"\x04\x0a" "is_touched")
 QDEF(MP_QSTR_MicroBitIO, (const byte*)"\xe6\x0a" "MicroBitIO")
 QDEF(MP_QSTR_pin0, (const byte*)"\x02\x04" "pin0")
@@ -677,6 +678,11 @@ QDEF(MP_QSTR_randrange, (const byte*)"\xa3\x09" "randrange")
 QDEF(MP_QSTR_randint, (const byte*)"\xaf\x07" "randint")
 QDEF(MP_QSTR_choice, (const byte*)"\x2e\x06" "choice")
 QDEF(MP_QSTR_uniform, (const byte*)"\x01\x07" "uniform")
+QDEF(MP_QSTR_audio, (const byte*)"\x53\x05" "audio")
+QDEF(MP_QSTR_AudioFrame, (const byte*)"\xae\x0a" "AudioFrame")
+QDEF(MP_QSTR_return_pin, (const byte*)"\x27\x0a" "return_pin")
+QDEF(MP_QSTR_source, (const byte*)"\xb8\x06" "source")
+QDEF(MP_QSTR_copyfrom, (const byte*)"\x56\x08" "copyfrom")
 QDEF(MP_QSTR_os, (const byte*)"\x79\x02" "os")
 QDEF(MP_QSTR_uname, (const byte*)"\xb7\x05" "uname")
 QDEF(MP_QSTR_sysname, (const byte*)"\x9b\x07" "sysname")
@@ -688,6 +694,7 @@ QDEF(MP_QSTR_writable, (const byte*)"\xf7\x08" "writable")
 QDEF(MP_QSTR_listdir, (const byte*)"\x98\x07" "listdir")
 QDEF(MP_QSTR_machine, (const byte*)"\x60\x07" "machine")
 QDEF(MP_QSTR_size, (const byte*)"\x20\x04" "size")
+QDEF(MP_QSTR_is_playing, (const byte*)"\x04\x0a" "is_playing")
 QDEF(MP_QSTR_radio, (const byte*)"\xd4\x05" "radio")
 QDEF(MP_QSTR_config, (const byte*)"\x4f\x06" "config")
 QDEF(MP_QSTR_send_bytes, (const byte*)"\xbf\x0a" "send_bytes")

inc/lib/pwm.h

@@ -0,0 +1,11 @@
+#ifndef __MICROPY_INCLUDED_LIB_PWM_H__
+#define __MICROPY_INCLUDED_LIB_PWM_H__
+
+void pwm_start(void);
+void pwm_stop(void);
+
+int32_t pwm_set_period_us(int32_t us);
+int32_t pwm_get_period_us(void);
+int pwm_set_duty_cycle(int32_t pin, int32_t value);
+
+#endif // __MICROPY_INCLUDED_LIB_PWM_H__

inc/microbit/microbitpin.h

@@ -34,6 +34,9 @@
 #define MICROBIT_PIN_P14    (P0_22)
 #define MICROBIT_PIN_P15    (P0_21)
 
+mp_obj_t microbit_pin_write_digital(mp_obj_t self_in, mp_obj_t value_in);
+mp_obj_t microbit_pin_read_digital(mp_obj_t self_in);
+
 #endif
 
 #endif // __MICROPY_INCLUDED_MICROBIT_MICROBITPIN_H__

inc/microbit/modaudio.h

@@ -0,0 +1,25 @@
+
+#ifndef __MICROPY_INCLUDED_MICROBIT_AUDIO_H__
+#define __MICROPY_INCLUDED_MICROBIT_AUDIO_H__
+
+#include "nrf.h"
+#include "py/obj.h"
+#include "py/runtime.h"
+
+void audio_play_source(mp_obj_t src, mp_obj_t pin1, mp_obj_t pin2, bool wait);
+
+#define LOG_AUDIO_CHUNK_SIZE 5
+#define AUDIO_CHUNK_SIZE (1<<LOG_AUDIO_CHUNK_SIZE)
+#define AUDIO_BUFFER_SIZE (AUDIO_CHUNK_SIZE*2)
+#define AUDIO_CALLBACK_ID 0
+
+typedef struct _microbit_audio_frame_obj_t {
+    mp_obj_base_t base;
+    uint8_t data[AUDIO_CHUNK_SIZE];
+} microbit_audio_frame_obj_t;
+
+extern const mp_obj_type_t microbit_audio_frame_type;
+
+microbit_audio_frame_obj_t *new_microbit_audio_frame(void);
+
+#endif // __MICROPY_INCLUDED_MICROBIT_AUDIO_H__

inc/microbit/mpconfigport.h

@@ -95,6 +95,7 @@ extern const struct _mp_obj_module_t neopixel_module;
 extern const struct _mp_obj_module_t random_module;
 extern const struct _mp_obj_module_t os_module;
 extern const struct _mp_obj_module_t radio_module;
+extern const struct _mp_obj_module_t audio_module;
 
 #define MICROPY_PORT_BUILTIN_MODULES \
     { MP_OBJ_NEW_QSTR(MP_QSTR_microbit), (mp_obj_t)&microbit_module }, \
@@ -106,6 +107,7 @@ extern const struct _mp_obj_module_t radio_module;
     { MP_OBJ_NEW_QSTR(MP_QSTR_random), (mp_obj_t)&random_module }, \
     { MP_OBJ_NEW_QSTR(MP_QSTR_os), (mp_obj_t)&os_module }, \
     { MP_OBJ_NEW_QSTR(MP_QSTR_radio), (mp_obj_t)&radio_module }, \
+    { MP_OBJ_NEW_QSTR(MP_QSTR_audio), (mp_obj_t)&audio_module }, \
     \
     /* the following provide aliases for existing modules */ \
     { MP_OBJ_NEW_QSTR(MP_QSTR_collections), (mp_obj_t)&mp_module_collections }, \
@@ -119,6 +121,9 @@ extern const struct _mp_obj_module_t radio_module;
     void *async_data[2]; \
     void *async_music_data; \
     uint8_t *radio_buf; \
+    void *pwm_next_event; \
+    void *audio_buffer; \
+    void *audio_source;
 
 // We need to provide a declaration/definition of alloca()
 #include <alloca.h>

inc/microbit/qstrdefsport.h

@@ -28,6 +28,7 @@ Q(read_analog)
 Q(write_analog)
 Q(set_analog_period)
 Q(set_analog_period_microseconds)
+Q(get_analog_period_microseconds)
 Q(is_touched)
 
 Q(MicroBitIO)
@@ -388,8 +389,15 @@ Q(randint)
 Q(choice)
 Q(uniform)
 
+Q(audio)
+Q(play)
+Q(AudioFrame)
+Q(pin)
+Q(return_pin)
+Q(source)
+Q(copyfrom)
+
 Q(name)
-Q(os)
 
 Q(os)
 Q(uname)
@@ -409,6 +417,7 @@ Q(listdir)
 Q(machine)
 Q(size)
 
+Q(is_playing)
 Q(radio)
 Q(reset)
 Q(config)