Add PWMAudio for DAC-free audio playback (#1076)

Use the PWM hardware to generate a signal suitable for filtering and
amplifying 16bps audio output.

Refactor the AudioBufferManager to allow sharing with I2S

Add example

libraries/AudioBufferManager/library.properties

@@ -0,0 +1,10 @@
+name=AudioBufferManager
+version=1.0.0
+author=Earle F. Philhower, III <earlephilhower@yahoo.com>
+maintainer=Earle F. Philhower, III <earlephilhower@yahoo.com>
+sentence=Manages DMA buffers for audio output
+paragraph=Manages DMA buffers for audio output
+category=Device Control
+url=https://github.com/earlephilhower/arduino-pico
+architectures=rp2040
+dot_a_linkage=true

libraries/AudioBufferManager/src/AudioBufferManager.cpp

@@ -1,6 +1,6 @@
 /*
-    AudioRingBuffer for Raspnerry Pi Pico RP2040
-    Implements a ring buffer for PIO DMA for I2S read or write
+    AudioBufferManager for Raspnerry Pi Pico RP2040
+    Implements a DMA controlled linked-list series of buffers
 
     Copyright (c) 2022 Earle F. Philhower, III <earlephilhower@yahoo.com>
 
@@ -22,12 +22,12 @@
 #include <Arduino.h>
 #include "hardware/dma.h"
 #include "hardware/irq.h"
-#include "AudioRingBuffer.h"
+#include "AudioBufferManager.h"
 
-static int              __channelCount = 0;    // # of channels left.  When we hit 0, then remove our handler
-static AudioRingBuffer* __channelMap[12];      // Lets the IRQ handler figure out where to dispatch to
+static int                 __channelCount = 0;    // # of channels left.  When we hit 0, then remove our handler
+static AudioBufferManager* __channelMap[12];      // Lets the IRQ handler figure out where to dispatch to
 
-AudioRingBuffer::AudioRingBuffer(size_t bufferCount, size_t bufferWords, int32_t silenceSample, PinMode direction) {
+AudioBufferManager::AudioBufferManager(size_t bufferCount, size_t bufferWords, int32_t silenceSample, PinMode direction, enum dma_channel_transfer_size dmaSize) {
     _running = false;
 
     // Need at least 2 DMA buffers and 1 user or this isn't going to work at all
@@ -38,6 +38,7 @@ AudioRingBuffer::AudioRingBuffer(size_t bufferCount, size_t bufferWords, int32_t
     _bufferCount = bufferCount;
     _wordsPerBuffer = bufferWords;
     _isOutput = direction == OUTPUT;
+    _dmaSize = dmaSize;
     _overunderflow = false;
     _callback = nullptr;
     _userOff = 0;
@@ -66,7 +67,7 @@ AudioRingBuffer::AudioRingBuffer(size_t bufferCount, size_t bufferWords, int32_t
     _active[1] = _silence;
 }
 
-AudioRingBuffer::~AudioRingBuffer() {
+AudioBufferManager::~AudioBufferManager() {
     if (_running) {
         for (auto i = 0; i < 2; i++) {
             dma_channel_set_irq0_enabled(_channelDMA[i], false);
@@ -98,11 +99,11 @@ AudioRingBuffer::~AudioRingBuffer() {
     _deleteAudioBuffer(_silence);
 }
 
-void AudioRingBuffer::setCallback(void (*fn)()) {
+void AudioBufferManager::setCallback(void (*fn)()) {
     _callback = fn;
 }
 
-bool AudioRingBuffer::begin(int dreq, volatile void *pioFIFOAddr) {
+bool AudioBufferManager::begin(int dreq, volatile void *pioFIFOAddr) {
     _running = true;
 
     // Get ping and pong DMA channels
@@ -119,7 +120,7 @@ bool AudioRingBuffer::begin(int dreq, volatile void *pioFIFOAddr) {
     // Need to know both channels to set up ping-pong, so do in 2 stages
     for (auto i = 0; i < 2; i++) {
         dma_channel_config c = dma_channel_get_default_config(_channelDMA[i]);
-        channel_config_set_transfer_data_size(&c, DMA_SIZE_32); // 32b transfers into PIO FIFO
+        channel_config_set_transfer_data_size(&c, _dmaSize); // 16b/32b transfers into PIO FIFO
         if (_isOutput) {
             channel_config_set_read_increment(&c, true); // Reading incrementing addresses
             channel_config_set_write_increment(&c, false); // Writing to the same FIFO address
@@ -155,7 +156,7 @@ bool AudioRingBuffer::begin(int dreq, volatile void *pioFIFOAddr) {
 // cause GCC to keep re-reading from memory and not use cached value read
 // on the first pass.
 
-bool AudioRingBuffer::write(uint32_t v, bool sync) {
+bool AudioBufferManager::write(uint32_t v, bool sync) {
     if (!_running || !_isOutput) {
         return false;
     }
@@ -177,7 +178,7 @@ bool AudioRingBuffer::write(uint32_t v, bool sync) {
     return true;
 }
 
-bool AudioRingBuffer::read(uint32_t *v, bool sync) {
+bool AudioBufferManager::read(uint32_t *v, bool sync) {
     if (!_running || _isOutput) {
         return false;
     }
@@ -201,13 +202,13 @@ bool AudioRingBuffer::read(uint32_t *v, bool sync) {
     return true;
 }
 
-bool AudioRingBuffer::getOverUnderflow() {
+bool AudioBufferManager::getOverUnderflow() {
     bool hold = _overunderflow;
     _overunderflow = false;
     return hold;
 }
 
-int AudioRingBuffer::available() {
+int AudioBufferManager::available() {
     AudioBuffer *p = _isOutput ? _empty : _filled;
 
     if (!_running || !p) {
@@ -226,7 +227,7 @@ int AudioRingBuffer::available() {
     return avail;
 }
 
-void AudioRingBuffer::flush() {
+void AudioBufferManager::flush() {
     AudioBuffer ** volatile a = (AudioBuffer ** volatile)&_active[0];
     AudioBuffer ** volatile b = (AudioBuffer ** volatile)&_active[1];
     AudioBuffer ** volatile c = (AudioBuffer ** volatile)&_filled;
@@ -235,7 +236,7 @@ void AudioRingBuffer::flush() {
     }
 }
 
-void __not_in_flash_func(AudioRingBuffer::_dmaIRQ)(int channel) {
+void __not_in_flash_func(AudioBufferManager::_dmaIRQ)(int channel) {
     if (_isOutput) {
         if (_active[0] != _silence) {
             _addToList(&_empty, _active[0]);
@@ -265,7 +266,7 @@ void __not_in_flash_func(AudioRingBuffer::_dmaIRQ)(int channel) {
     }
 }
 
-void __not_in_flash_func(AudioRingBuffer::_irq)() {
+void __not_in_flash_func(AudioBufferManager::_irq)() {
     for (size_t i = 0; i < sizeof(__channelMap); i++) {
         if (dma_channel_get_irq0_status(i) && __channelMap[i]) {
             __channelMap[i]->_dmaIRQ(i);

libraries/AudioBufferManager/src/AudioBufferManager.h

@@ -1,6 +1,6 @@
 /*
-    AudioRingBuffer for Rasperry Pi Pico
-    Implements a ring buffer for PIO DMA for I2S read or write
+    AudioBufferManager for Rasperry Pi Pico
+    Implements a DMA controlled linked-list series of buffers
 
     Copyright (c) 2022 Earle F. Philhower, III <earlephilhower@yahoo.com>
 
@@ -21,11 +21,12 @@
 
 #pragma once
 #include <Arduino.h>
+#include "hardware/dma.h"
 
-class AudioRingBuffer {
+class AudioBufferManager {
 public:
-    AudioRingBuffer(size_t bufferCount, size_t bufferWords, int32_t silenceSample, PinMode direction = OUTPUT);
-    ~AudioRingBuffer();
+    AudioBufferManager(size_t bufferCount, size_t bufferWords, int32_t silenceSample, PinMode direction = OUTPUT, enum dma_channel_transfer_size dmaSize = DMA_SIZE_32);
+    ~AudioBufferManager();
 
     void setCallback(void (*fn)());
 
@@ -88,6 +89,7 @@ private:
     int _bitsPerSample;
     size_t _wordsPerBuffer;
     size_t _bufferCount;
+    enum dma_channel_transfer_size _dmaSize;
     bool _isOutput;
 
     int _channelDMA[2];

libraries/I2S/src/I2S.cpp

@@ -139,7 +139,7 @@ bool I2S::begin() {
     if (!_bufferWords) {
         _bufferWords = 16 * (_bps == 32 ? 2 : 1);
     }
-    _arb = new AudioRingBuffer(_buffers, _bufferWords, _silenceSample, _isOutput ? OUTPUT : INPUT);
+    _arb = new AudioBufferManager(_buffers, _bufferWords, _silenceSample, _isOutput ? OUTPUT : INPUT);
     _arb->begin(pio_get_dreq(_pio, _sm, _isOutput), _isOutput ? &_pio->txf[_sm] : (volatile void*)&_pio->rxf[_sm]);
     _arb->setCallback(_cb);
     pio_sm_set_enabled(_pio, _sm, true);

libraries/I2S/src/I2S.h

@@ -21,7 +21,7 @@
 
 #pragma once
 #include <Arduino.h>
-#include "AudioRingBuffer.h"
+#include "AudioBufferManager.h"
 
 class I2S : public Stream {
 public:
@@ -120,7 +120,7 @@ private:
 
     void (*_cb)();
 
-    AudioRingBuffer *_arb;
+    AudioBufferManager *_arb;
     PIOProgram *_i2s;
     PIO _pio;
     int _sm;

libraries/PWMAudio/examples/PlayRaw/PlayRaw.ino

@@ -0,0 +1,37 @@
+/*
+  This example plays a raw, headerless, mono 16b, 44.1 sample using the PWMAudio library on GPIO 1.
+
+  Released to the public domain by Earle F. Philhower, III <earlephilhower@yahoo.com>
+*/
+
+#include <PWMAudio.h>
+#include "wav.h"
+
+// The sample pointers
+const int16_t *start = (const int16_t *)out_raw;
+const int16_t *p = start;
+
+// Create the PWM audio device on GPIO 1.   Hook amp/speaker between GPIO1 and convenient GND.
+PWMAudio pwm(1);
+
+unsigned int count = 0;
+
+void cb() {
+  while (pwm.availableForWrite()) {
+    pwm.write(*p++);
+    count += 2;
+    if (count >= sizeof(out_raw)) {
+      count = 0;
+      p = start;
+    }
+  }
+}
+
+void setup() {
+  pwm.onTransmit(cb);
+  pwm.begin(44100);
+}
+
+void loop() {
+  /* noop, everything is done in the CB */
+}

libraries/PWMAudio/keywords.txt

@@ -0,0 +1,25 @@
+#######################################
+# Syntax Coloring Map
+#######################################
+
+#######################################
+# Datatypes (KEYWORD1)
+#######################################
+
+PWMAudio	KEYWORD1
+
+#######################################
+# Methods and Functions (KEYWORD2)
+#######################################
+begin	KEYWORD2
+end	KEYWORD2
+
+setPin	KEYWORD2
+setFrequency	KEYWORD2
+setBuffers	KEYWORD2
+
+onTransmit	KEYWORD2
+
+#######################################
+# Constants (LITERAL1)
+#######################################

libraries/PWMAudio/library.properties

@@ -0,0 +1,10 @@
+name=PWMAudio
+version=1.0
+author=Earle F. Philhower, III <earlephilhower@yahoo.com>
+maintainer=Earle F. Philhower, III <earlephilhower@yahoo.com>
+sentence=Plays audio on a pin using the PWM hardware, no DAC required
+paragraph=Plays audio on a pin using the PWM hardware, no DAC required
+category=Communication
+url=http://github.com/earlephilhower/arduino-pico
+architectures=rp2040
+dot_a_linkage=true

libraries/PWMAudio/src/PWMAudio.cpp

@@ -0,0 +1,161 @@
+/*
+    PWMAudio
+    Plays a 16b audio stream on a user defined pin using PWM
+
+    Copyright (c) 2022 Earle F. Philhower, III <earlephilhower@yahoo.com>
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2.1 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+*/
+#include <Arduino.h>
+#include "PWMAudio.h"
+#include <hardware/pwm.h>
+
+
+PWMAudio::PWMAudio(pin_size_t pin) {
+    _running = false;
+    _pin = pin;
+    _freq = 48000;
+    _arb = nullptr;
+    _cb = nullptr;
+    _buffers = 8;
+    _bufferWords = 0;
+}
+
+PWMAudio::~PWMAudio() {
+}
+
+bool PWMAudio::setBuffers(size_t buffers, size_t bufferWords) {
+    if (_running || (buffers < 3) || (bufferWords < 8)) {
+        return false;
+    }
+    _buffers = buffers;
+    _bufferWords = bufferWords;
+    return true;
+}
+
+bool PWMAudio::setFrequency(int newFreq) {
+    if (_running) {
+        return false;
+    }
+    _freq = newFreq;
+    return true;
+}
+
+void PWMAudio::onTransmit(void(*fn)(void)) {
+    _cb = fn;
+    if (_running) {
+        _arb->setCallback(_cb);
+    }
+}
+
+bool PWMAudio::begin() {
+    _running = true;
+
+    if (!_bufferWords) {
+        _bufferWords = 16;
+    }
+
+    // Figure out the scale factor for PWM values
+    float fPWM = 65535.0 * _freq; // ideal
+
+    if (fPWM > clock_get_hz(clk_sys)) {
+        // Need to downscale the range to hit the frequency target
+        float pwmMax = (float) clock_get_hz(clk_sys) /(float) _freq;
+        _pwmScale = pwmMax;
+        fPWM = clock_get_hz(clk_sys);
+    } else {
+        _pwmScale = 1 << 16;
+    }
+
+    pwm_config c = pwm_get_default_config();
+    pwm_config_set_clkdiv(&c, clock_get_hz(clk_sys) / fPWM);
+    pwm_config_set_wrap(&c, _pwmScale);
+    pwm_init(pwm_gpio_to_slice_num(_pin), &c, true);
+    gpio_set_function(_pin, GPIO_FUNC_PWM);
+    pwm_set_gpio_level(_pin, (0x8000 * _pwmScale) >> 16);
+
+    uint32_t ccAddr = PWM_BASE + PWM_CH0_CC_OFFSET + pwm_gpio_to_slice_num(_pin) * 20;
+
+    _arb = new AudioBufferManager(_buffers, _bufferWords, 0x80008000, OUTPUT, DMA_SIZE_32);
+    _arb->begin(pwm_get_dreq(pwm_gpio_to_slice_num(_pin)), (volatile void*)ccAddr);
+    _arb->setCallback(_cb);
+
+    return true;
+}
+
+void PWMAudio::end() {
+    _running = false;
+    delete _arb;
+    _arb = nullptr;
+}
+
+int PWMAudio::available() {
+    return availableForWrite(); // Do what I mean, not what I say
+}
+
+int PWMAudio::read() {
+    return -1;
+}
+
+int PWMAudio::peek() {
+    return -1;
+}
+
+void PWMAudio::flush() {
+    if (_running) {
+        _arb->flush();
+    }
+}
+
+int PWMAudio::availableForWrite() {
+    if (!_running) {
+        return 0;
+    }
+    return _arb->available();
+}
+
+size_t PWMAudio::write(int16_t val, bool sync) {
+    if (!_running) {
+        return 0;
+    }
+    // Go from signed -32K...32K to unsigned 0...64K
+    uint32_t sample = (uint32_t) (val + 0x8000); 
+    // Adjust to the real range
+    sample *= _pwmScale;
+    sample >>= 16;
+    // Duplicate sample since we don't care which PWM channel
+    sample = (sample & 0xffff) | (sample << 16);
+    return _arb->write(sample, sync);
+}
+
+size_t PWMAudio::write(const uint8_t *buffer, size_t size) {
+    // We can only write 16-bit chunks here
+    if (size & 0x1) {
+        return 0;
+    }
+    size_t writtenSize = 0;
+    int16_t *p = (int16_t *)buffer;
+    while (size) {
+        if (!write((int16_t)*p)) {
+            // Blocked, stop write here
+            return writtenSize;
+        } else {
+            p++;
+            size -= 4;
+            writtenSize += 4;
+        }
+    }
+    return writtenSize;
+}

libraries/PWMAudio/src/PWMAudio.h

@@ -0,0 +1,80 @@
+/*
+    PWMAudio
+    Plays a signed 16b audio stream on a user defined pin using PWM
+
+    Copyright (c) 2022 Earle F. Philhower, III <earlephilhower@yahoo.com>
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2.1 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+*/
+
+#pragma once
+#include <Arduino.h>
+#include "AudioBufferManager.h"
+
+class PWMAudio : public Stream {
+public:
+    PWMAudio(pin_size_t pin);
+    virtual ~PWMAudio();
+
+    bool setBuffers(size_t buffers, size_t bufferWords);
+    bool setFrequency(int newFreq);
+
+    bool begin(long sampleRate) {
+        setFrequency(sampleRate);
+        return begin();
+    }
+
+    bool begin();
+    void end();
+
+    // from Stream
+    virtual int available() override;
+    virtual int read() override;
+    virtual int peek() override;
+    virtual void flush() override;
+
+    // from Print (see notes on write() methods below)
+    virtual size_t write(const uint8_t *buffer, size_t size) override;
+    virtual int availableForWrite() override;
+
+    virtual size_t write(uint8_t x) override {
+        return write((int16_t) x, true);
+    }
+
+    // Write 16 bit value to port, user responsible for packing/alignment, etc.
+    size_t write(int16_t val, bool sync = true);
+    size_t write(int val, bool sync = true) {
+        return write((int16_t) val, sync);
+    }
+
+    // Note that these callback are called from **INTERRUPT CONTEXT** and hence
+    // should be in RAM, not FLASH, and should be quick to execute.
+    void onTransmit(void(*)(void));
+
+private:
+    pin_size_t _pin;
+    int _freq;
+
+    size_t _buffers;
+    size_t _bufferWords;
+
+    uint32_t _pwmScale;
+
+    bool _running;
+
+    void (*_cb)();
+
+    AudioBufferManager *_arb;
+};