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

#include <PDMGen3_RK.h>

Inheritance diagram for PDMGen3:

Public Types
enum	OutputSize { OutputSize::UNSIGNED_8, OutputSize::SIGNED_16, OutputSize::RAW_SIGNED_16 }
	Configuration for the size of the output data. More...

enum	Range { Range::RANGE_128 = 0, Range::RANGE_256, Range::RANGE_512, Range::RANGE_1024, Range::RANGE_2048, Range::RANGE_4096, Range::RANGE_8192, Range::RANGE_16384, Range::RANGE_32768 }
	Adjustment value so samples fill most of an 8 or 16 bit output size. More...

Public Member Functions
	PDMGen3 (pin_t clkPin, pin_t datPin, int16_t *samples, size_t samplesPerBuf)
	Allocate a PDMGen3 object for using the hardware PDM decoder. More...

virtual	~PDMGen3 ()
	Destructor. You typically allocate this as a global variable so it won't be deleted.

nrfx_err_t	init ()
	Initialize the PDM module. More...

void	uninit ()
	Uniniialize the PDM module. More...

nrfx_err_t	start ()
	Start sampling.

nrfx_err_t	stop ()
	Stop sampling.

PDMGen3 &	withGainDb (float gainDb)
	Sets the gain in dB. More...

PDMGen3 &	withGain (nrf_pdm_gain_t gainL, nrf_pdm_gain_t gainR)
	Sets the PDM gain using an rRF52 configuration value. More...

PDMGen3 &	withStereoMode ()
	Set stereo mode. In stereo mode, each buffer will interleave L and R samples. Default is mono mode.

PDMGen3 &	withMonoMode ()
	Set mono mode (left channel only). The default is mono mode, so you normally don't need to set this. More...

PDMGen3 &	withMode (nrf_pdm_mode_t mode)
	Sets a mode using a nrf_pdm_mode_t constant. Default is NRF_PDM_MODE_MONOl. More...

PDMGen3 &	withFreq (nrf_pdm_freq_t freq)
	Sets the sampling frequency. Default is 1.032 MHz, which works out to be a PCM sample rate of 16125 samples/sec. More...

PDMGen3 &	withEdge (nrf_pdm_edge_t edge)
	Sets the edge mode. More...

PDMGen3 &	withOutputSize (OutputSize outputSize)
	Sets the size of the output samples. More...

PDMGen3 &	withRange (Range range)
	Sets the range of the output samples. More...

PDMGen3 &	withInterruptCallback (std::function< void(void *sampleBuf, size_t numSamples)> interruptCallback)
	Sets a callback function to be called at interrupt time.

void *	getAvailableSamples () const
	Call this to poll for available samples from loop() More...

void	doneWithSamples ()
	Call when you are done using the samples returns from getAvailableSamples(). Required! More...

size_t	getSamplesPerBuf () const
	Returns the number of samples (not bytes) that was returned from getAvailableSamples()

Protected Member Functions
void	dataHandler (nrfx_pdm_evt_t const *const pEvent)
	Used internally to handle notifications from the PDM peripheral.

Static Protected Member Functions
static void	dataHandlerStatic (nrfx_pdm_evt_t const *const pEvent)
	Used internally to handle notifications from the PDM peripheral (static function) More...

Protected Attributes
pin_t	clkPin
	The pin used for the PDM clock (output)

pin_t	datPin
	The pin used for the PDM data (input)

int16_t *	samples
	Buffer to hold samples. There are 2x samples per buf because of double buffering.

size_t	samplesPerBuf
	Number of samples per each of the double buffers.

nrf_pdm_gain_t	gainL = NRF_PDM_GAIN_DEFAULT
	0x28 = 0dB gain

nrf_pdm_gain_t	gainR = NRF_PDM_GAIN_DEFAULT
	0x28 = 0dB gain

nrf_pdm_mode_t	mode = NRF_PDM_MODE_MONO
	mono or stereo mode

nrf_pdm_freq_t	freq = NRF_PDM_FREQ_1032K
	clock frequency

nrf_pdm_edge_t	edge = NRF_PDM_EDGE_LEFTFALLING
	clock edge configuration

OutputSize	outputSize = OutputSize::SIGNED_16
	Output size (8 or 16 bits)

Range	range = Range::RANGE_2048
	Range adjustment factor.

std::function< void(void *sampleBuf, size_t numSamples)>	interruptCallback = NULL
	buffer completion callback

bool	useBufferA = true
	Which buffer we're reading from of the double buffers.

int16_t *	availableSamples = NULL
	Used to pass data to loop() for processing out of interrupt context.

Static Protected Attributes
static PDMGen3 *	instance = NULL
	Singleton instance of this class. More...

Detailed Description

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

This only works on Gen 3 device (Argon, Boron, Xenon). Gen 2 devices include a STM32F205 MCU which does not include PDM support.

You typically create one PDMGen3 object as a global variable in your application.

Member Enumeration Documentation

◆ OutputSize

enum PDMGen3::OutputSize

strong

Configuration for the size of the output data.

Enumerator
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)

◆ Range

enum PDMGen3::Range

strong

Adjustment value so samples fill most of an 8 or 16 bit output size.

Enumerator
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)

Constructor & Destructor Documentation

◆ PDMGen3()

PDMGen3::PDMGen3	(	pin_t	clkPin,
		pin_t	datPin,
		int16_t *	samples,
		size_t	samplesPerBuf
	)

Allocate a PDMGen3 object for using the hardware PDM decoder.

Parameters

clkPin	Clock pin. Use any available GPIO: A0, A1, ..., D0, D1, ... even pins like RX, TX, etc. if you are not using that interface. Will be set as OUTPUT.
datPin	Data pin. Use any available GPIO. Will be set as INPUT.
samples	Pointer to a buffer to hold samples. Note: This must be 2 * samplesPerBuf int16_t values, and the number of bytes used will be 4 * samplesPerBuf because they're 16-bit samples.
samplesPerBuf	The number of int16_t (signed 16-bit) samples in each of the double buffers.

You may want to use the PDMGen3Static class instead which statically allocates the buffers on the heap at compile time, eliminating the need to manually manage them.

Member Function Documentation

◆ dataHandlerStatic()

void PDMGen3::dataHandlerStatic ( nrfx_pdm_evt_t const *const pEvent )

staticprotected

Used internally to handle notifications from the PDM peripheral (static function)

As this relies on the singleton (instance), there can only be one instance of this class, however that's also the case because there is only one PDM peripheral on the nRF52.

◆ doneWithSamples()

void PDMGen3::doneWithSamples ( )

inline

Call when you are done using the samples returns from getAvailableSamples(). Required!

This allows the buffer to be reused. If you don't call this, data will be corrupted.

◆ getAvailableSamples()

void* PDMGen3::getAvailableSamples ( ) const

inline

Call this to poll for available samples from loop()

Returns: A point to a sample buffer or NULL if no samples are available

Be sure to call doneWithSamples() if a non-NULL value is returned!

◆ init()

nrfx_err_t PDMGen3::init ( )

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().

◆ uninit()

void PDMGen3::uninit ( )

Uniniialize the PDM module.

You normally will just initialize it once and only start and stop it as necessary, however you can completely uninitialize it if desired. The clkPin will be reset to INPUT mode.

◆ withEdge()

PDMGen3& PDMGen3::withEdge ( nrf_pdm_edge_t edge )

inline

Sets the edge mode.

Parameters

edge	Edge mode. Whether left or mono channel is sample on falling CLK (default) or rising CLK

NRF_PDM_EDGE_LEFTFALLING Left (or mono) is sampled on falling edge of PDM_CLK (default)
NRF_PDM_EDGE_LEFTRISING Left (or mono) is sampled on rising edge of PDM_CLK.

◆ withFreq()

PDMGen3& PDMGen3::withFreq ( nrf_pdm_freq_t freq )

inline

Sets the sampling frequency. Default is 1.032 MHz, which works out to be a PCM sample rate of 16125 samples/sec.

Parameters

freq	Sampling frequency: NRF_PDM_FREQ_1000K, NRF_PDM_FREQ_1032K (default), or NRF_PDM_FREQ_1067K

◆ withGain()

PDMGen3& PDMGen3::withGain	(	nrf_pdm_gain_t	gainL,
		nrf_pdm_gain_t	gainR
	)

inline

Sets the PDM gain using an rRF52 configuration value.

Parameters

gainL	The nRF52 gain value for the left or mono channel
gainR	The nRF52 gain value for the right channel

NRF_PDM_GAIN_MINIMUM (0x00)
NRF_PDM_GAIN_DEFAULT (0x28) 0 dB gain, default value
NRF_PDM_GAIN_MAXIMUM (0x50)

◆ withGainDb()

PDMGen3 & PDMGen3::withGainDb ( float gainDb )

Sets the gain in dB.

Parameters

gainDb Gain in dB, from -20 (minimum) to +20 (maximum) in 0.5 dB steps

◆ withMode()

PDMGen3& PDMGen3::withMode ( nrf_pdm_mode_t mode )

inline

Sets a mode using a nrf_pdm_mode_t constant. Default is NRF_PDM_MODE_MONOl.

In mono mode, only the left channel is sampled, so every sample in the buffer will be from the left channel.

◆ withMonoMode()

PDMGen3& PDMGen3::withMonoMode ( )

inline

Set mono mode (left channel only). The default is mono mode, so you normally don't need to set this.

In mono mode, only the left channel is sampled, so every sample in the buffer will be from the left channel.

◆ withOutputSize()

PDMGen3& PDMGen3::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)

◆ withRange()

PDMGen3& PDMGen3::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)

Field Documentation

◆ instance

PDMGen3 * PDMGen3::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).

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

src/PDMGen3_RK.h
src/PDMGen3_RK.cpp

Public Types

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ OutputSize

◆ Range

Constructor & Destructor Documentation

◆ PDMGen3()

Member Function Documentation

◆ dataHandlerStatic()

◆ doneWithSamples()

◆ getAvailableSamples()

◆ init()

◆ uninit()

◆ withEdge()

◆ withFreq()

◆ withGain()

◆ withGainDb()

◆ withMode()

◆ withMonoMode()

◆ withOutputSize()

◆ withRange()

Field Documentation

◆ instance