#include <Microphone_PDM.h>

Inheritance diagram for Microphone_PDM:

Public Member Functions
Microphone_PDM &	withPinCLK (pin_t clkPin)

Microphone_PDM &	withPinDAT (pin_t datPin)

Microphone_PDM &	withOutputSize (OutputSize outputSize)

Microphone_PDM &	withRange (Range range)

Microphone_PDM &	withSampleRate (int sampleRate)

int	init ()

int	uninit ()

int	start ()

int	stop ()

void	loop ()

bool	bufferSamplingStart (Microphone_PDM_BufferSampling *sampling)

void	releaseBufferSampling ()

Microphone_PDM_BufferSampling *	getSampling ()

bool	samplesAvailable () const

size_t	getNumberOfSamples () const

bool	copySamples (void *pSamples)

bool	noCopySamples (std::function< void(void *pSamples, size_t numSamples)>callback)

size_t	getSampleSizeInBytes () const

size_t	getBufferSizeInBytes () const

uint8_t	getNumChannels () const

int	getSampleRate () const

uint8_t	getBitsPerSample () const

Public Member Functions inherited from Microphone_PDM_Base
int	getSampleRate () const

Static Public Member Functions
static Microphone_PDM &	instance ()

Protected Member Functions
	Microphone_PDM ()

virtual	~Microphone_PDM ()

	Microphone_PDM (const Microphone_PDM &)=delete

Microphone_PDM &	operator= (const Microphone_PDM &)=delete

Protected Member Functions inherited from Microphone_PDM_nRF52
	Microphone_PDM_nRF52 ()

virtual	~Microphone_PDM_nRF52 ()

virtual int	init ()

virtual int	uninit ()

virtual int	start ()

virtual int	stop ()

virtual bool	samplesAvailable () const

virtual bool	copySamples (void *pSamples)

virtual bool	noCopySamples (std::function< void(void *pSamples, size_t numSamples)>callback)

size_t	getNumberOfSamples () const

size_t	copySrcIncrement () const

Protected Member Functions inherited from Microphone_PDM_Base
	Microphone_PDM_Base (size_t numSamples)

virtual	~Microphone_PDM_Base ()

void	copySamplesInternal (const int16_t src, uint8_t dst) const

virtual size_t	copySrcIncrement () const

Protected Member Functions inherited from Microphone_PDM_RTL872x
	Microphone_PDM_RTL872x ()

virtual	~Microphone_PDM_RTL872x ()

virtual int	init ()

virtual int	uninit ()

virtual int	start ()

virtual int	stop ()

virtual bool	samplesAvailable () const

virtual bool	copySamples (void *pSamples)

virtual bool	noCopySamples (std::function< void(void *pSamples, size_t numSamples)>callback)

size_t	getNumberOfSamples () const

Protected Attributes
Microphone_PDM_BufferSampling *	sampling = 0

Protected Attributes inherited from Microphone_PDM_Base
pin_t	clkPin = A0

pin_t	datPin = A1

bool	stereoMode = false

int	sampleRate

OutputSize	outputSize = OutputSize::SIGNED_16

Range	range = Range::RANGE_2048

size_t	numSamples

Protected Attributes inherited from Microphone_PDM_RTL872x
bool	running = false

Static Protected Attributes
static Microphone_PDM *	_instance = NULL

Additional Inherited Members
Public Types inherited from Microphone_PDM_Base
enum class	OutputSize { UNSIGNED_8 , SIGNED_16 , RAW_SIGNED_16 }

enum class	Range { RANGE_128 = 0 , RANGE_256 , RANGE_512 , RANGE_1024 , RANGE_2048 , RANGE_4096 , RANGE_8192 , RANGE_16384 , RANGE_32768 }

Static Public Attributes inherited from Microphone_PDM_nRF52
static const size_t	BUFFER_SIZE_SAMPLES = 512

static const size_t	NUM_BUFFERS = 2

Static Public Attributes inherited from Microphone_PDM_RTL872x
static const size_t	BUFFER_SIZE_SAMPLES = SP_DMA_PAGE_SIZE / 2

static const size_t	NUM_BUFFERS = SP_DMA_PAGE_NUM

Detailed Description

Class for using the hardware PDM (pulse-density modulation) audio decoder on RTL872x and nRF52 devices.

This works on P2 and Photon 2 (RTL8721DM) as well as Boron, B Series SoM, Tracker SoM, and Argon (nRF52840).

It is a singleton class. You cannot construct a variable of this type, or copy this class. Instead, use Microphone_PDM::instance() to get the singleton instance.

You can create an instance at early initialization (STARTUP or global object construction) but you cannot call init() at that time. In almost all cases, you will first use Microphone_PDM::instance() from setup to configure the settings.

Constructor & Destructor Documentation

◆ Microphone_PDM() [1/2]

Microphone_PDM::Microphone_PDM ( )

protected

Allocate a Microphone_PDM object for using the hardware PDM decoder.

◆ Microphone_PDM() [2/2]

Microphone_PDM::Microphone_PDM ( const Microphone_PDM & )

protecteddelete

This class is a singleton and cannot be copied

Member Function Documentation

◆ bufferSamplingStart()

bool Microphone_PDM::bufferSamplingStart ( Microphone_PDM_BufferSampling * sampling )

brief Sample data into a buffer

Parameters

sampling Microphone_PDM_BufferSampling class. Must be allocated with new. Ownerships transfers to this class.

Returns: true; false

Added in version 0.0.2

◆ copySamples()

bool Microphone_PDM::copySamples ( void * pSamples )

inlinevirtual

Copy samples from the DMA buffer to your buffer.

Parameters

pSamples Pointer to buffer to copy samples to. It must be at least getNumberOfSamples() samples in length.

Returns: true; false

You can skip calling samplesAvailable() and just call copySamples which will return false in the same cases where samplesAvailable() would have returned false.

Reimplemented from Microphone_PDM_nRF52.

◆ getBitsPerSample()

uint8_t Microphone_PDM::getBitsPerSample ( ) const

inline

Get the number of bits per sample, 8 or 16.

Returns: uint8_t bits per sample (8 or 16)

◆ getBufferSizeInBytes()

size_t Microphone_PDM::getBufferSizeInBytes ( ) const

inline

Get the buffer size in bytes.

Returns: size_t Size of the DMA buffer in bytes

You can use this with copySamples() to know how big of a buffer you need if you are allocating a buffer in bytes instead of samples.

◆ getNumberOfSamples()

size_t Microphone_PDM::getNumberOfSamples ( ) const

inline

Return the number of int16_t samples that copySamples will copy.

Returns: size_t Number of uint16_t samples. Number of bytes is twice that value

You will never get a partial buffer of data. The number of samples is a constant that is determined by the MCU type at compile time and does not change.

On the nRF52, it's 512 samples (1024 bytes), except in one case: If you set a sample rate of 8000 Hz, it will be 256 samples because the hardware only samples at 16000 Hz but the code will automatically discard every other sample so there will only be 256 samples.

On the RTL872x, it's 256 samples (512 bytes). It's smaller because the are 4 buffers instead of the 2 buffers used on the nRF52, and the optimal DMA size on the RTL872x is 512 bytes.

◆ getNumChannels()

uint8_t Microphone_PDM::getNumChannels ( ) const

inline

Get the number of channels, either 1 or 2.

Returns: uint8_t

◆ getSampleRate()

int Microphone_PDM::getSampleRate ( ) const

inline

Get the sample rate, either 16000 or 32000.

Returns: int

◆ getSampleSizeInBytes()

size_t Microphone_PDM::getSampleSizeInBytes ( ) const

Get the sample size in bytes.

Returns: size_t 1 (8-bit samples) or 2 (16-bit samples)

◆ getSampling()

Microphone_PDM_BufferSampling * Microphone_PDM::getSampling ( )

inline

Get the Microphone_PDM_BufferSampling object if it has been set by bufferSamplingStart.

Returns: Microphone_PDM_BufferSampling*

◆ init()

int Microphone_PDM::init ( )

inlinevirtual

Initialize the PDM module.

This is often done from setup(). You can defer it until you're ready to sample if desired, calling right before start().

Reimplemented from Microphone_PDM_nRF52.

◆ instance()

Microphone_PDM & Microphone_PDM::instance ( )

static

Get the singleton instance of this class.

Returns: Microphone_PDM&

◆ loop()

void Microphone_PDM::loop ( )

Call from loop() to process samples.

This is only required if you are using buffering mode, but you can call it in all cases if desired.

Added in version 0.0.2

◆ noCopySamples()

bool Microphone_PDM::noCopySamples ( std::function< void(void *pSamples, size_t numSamples)> callback )

inlinevirtual

Alternative API to get samples.

Parameters

callback Callback function or lambda

Returns: true; false

Alternative API that does not require a buffer to be passed in. You should only use this if you can consume the buffer immediately without blocking.

The callback function or lamba has this prototype:

void callback(void *pSamples, size_t numSamples)

It will be called with a pointer to the samples (in the DMA buffer) and the number of samples (not bytes!) of data. The number of bytes will vary depending on the outputSize.

You can skip calling samplesAvailable() and just call noCopySamples which will return false in the same cases where samplesAvailable() would have returned false.

Reimplemented from Microphone_PDM_nRF52.

◆ operator=()

Microphone_PDM & Microphone_PDM::operator= ( const Microphone_PDM & )

protecteddelete

This class is a singleton and cannot be copied

◆ releaseBufferSampling()

void Microphone_PDM::releaseBufferSampling ( )

Release the buffer used by bufferSamplingStart()

◆ samplesAvailable()

bool Microphone_PDM::samplesAvailable ( ) const

inlinevirtual

Return true if there is data available to be copied using copySamples.

Returns: true; false

Reimplemented from Microphone_PDM_nRF52.

◆ start()

int Microphone_PDM::start ( )

inlinevirtual

Start sampling.

Reimplemented from Microphone_PDM_nRF52.

◆ stop()

int Microphone_PDM::stop ( )

inlinevirtual

Stop sampling.

On the RTL872x (P2, Photon 2), it's not actually possible to stop sampling once you start it. Calling stop() will discard the data and samplesAvailable(), copySamples(), etc. will behave as if the DMA had been stopped.

Reimplemented from Microphone_PDM_nRF52.

◆ uninit()

int Microphone_PDM::uninit ( )

inlinevirtual

Uninitialize the PDM module. Not supported on RTL872x (P2, Photon 2)!

Releases the resources used by the PDM module, though the 2K RAM buffer is statically allocated on the heap and is not freed.

Reimplemented from Microphone_PDM_nRF52.

◆ withOutputSize()

Microphone_PDM & Microphone_PDM::withOutputSize ( OutputSize outputSize )

inline

Sets the size of the output samples.

Parameters

outputSize The output size enumeration

UNSIGNED_8 Output unsigned 8-bit values (adjusted by PDMRange)
SIGNED_16, Output signed 16-bit values (adjusted by PDMRange) (default)
RAW_SIGNED_16 Output values as signed 16-bit values as returned by nRF52 (unadjusted)

The DMA buffer is always 16 bit, and if you use UNSIGNED_8 it just discards the unused bits when copying the samples using copySamples() or noCopySamples().

This is only relevant because you will be called at the rate you'd expect for 16-bit samples even when using 8-bit output.

◆ withPinCLK()

Microphone_PDM & Microphone_PDM::withPinCLK ( pin_t clkPin )

inline

Overrides the default clock (CLK) pin (A0). Not supported on RTL872x (P2, Photon 2)!

Parameters

clkPin Pin (such as A2, D3, etc.)

Returns: Microphone_PDM&

This setting is only used on nRF52 and must be set before init().

On the RTL872x (P2, Photon 2), the setting is ignored as you cannot override the pins used for PDM.

◆ withPinDAT()

Microphone_PDM & Microphone_PDM::withPinDAT ( pin_t datPin )

inline

Overrides the default data (DAT) pin (A1). Not supported on RTL872x (P2, Photon 2)!

Parameters

datPin Pin (such as A3, D4, etc.)

Returns: Microphone_PDM&

This setting is only used on nRF52 and must be set before init().

On the RTL872x (P2, Photon 2), the setting is ignored as you cannot override the pins used for PDM.

◆ withRange()

Microphone_PDM & Microphone_PDM::withRange ( Range range )

inline

Sets the range of the output samples.

Parameters

range The range enumeration

RANGE_128 From -128 to 127 (8 bits) RANGE_256 From -256 to 255 (9 bits) RANGE_512 From -512 to 511 (10 bits) RANGE_1024 From -1024 to 1023 (11 bits) RANGE_2048 From -2048 to 2047 (12 bits) (default) RANGE_4096 From -4096 to 4095 (13 bits) RANGE_8192 From -8192 to 8191 (14 bits) RANGE_16384 From -16384 to 16383 (15 bits) RANGE_32768 From -32768 to 32767 (16 bits) (same as raw mode)

The range should be set based on the PDM microphone you are using. For the Adafruit microphone, the default value of RANGE_2048 (12-bit) is correct.

◆ withSampleRate()

Microphone_PDM & Microphone_PDM::withSampleRate ( int sampleRate )

inline

Sets the sampling rate. Default is 16000. Cannot be changed on nRF52!

Parameters

sampleRate 8000, 16000, or 32000. The default is 16000.

This call can only be used on RTL827x (P2, Photon 2). It is ignored on nRF52. Setting an invalid value will use 16000.

Field Documentation

◆ _instance

Microphone_PDM * Microphone_PDM::_instance = NULL

staticprotected

Singleton instance of this class.

Since there is only one PDM decoder on the nRF52 you must create only one instance of this class (typically as a global variable).

◆ sampling

Microphone_PDM_BufferSampling* Microphone_PDM::sampling = 0

protected

Class to hold parameters and state for buffer sampling

The documentation for this class was generated from the following files:

src/Microphone_PDM.h
src/Microphone_PDM.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Microphone_PDM() [1/2]

◆ Microphone_PDM() [2/2]

Member Function Documentation

◆ bufferSamplingStart()

◆ copySamples()

◆ getBitsPerSample()

◆ getBufferSizeInBytes()

◆ getNumberOfSamples()

◆ getNumChannels()

◆ getSampleRate()

◆ getSampleSizeInBytes()

◆ getSampling()

◆ init()

◆ instance()

◆ loop()

◆ noCopySamples()

◆ operator=()

◆ releaseBufferSampling()

◆ samplesAvailable()

◆ start()

◆ stop()

◆ uninit()

◆ withOutputSize()

◆ withPinCLK()

◆ withPinDAT()

◆ withRange()

◆ withSampleRate()

Field Documentation

◆ _instance

◆ sampling