This API defines a player of melodies, defined as a sequence of tones and durations. More...

#include <fastarduino/devices/tone_player.h>

Inheritance diagram for devices::audio::AsyncTonePlayer< NTIMER, OUTPUT, TONEPLAY >:

Collaboration diagram for devices::audio::AsyncTonePlayer< NTIMER, OUTPUT, TONEPLAY >:

Public Types
using	GENERATOR = typename BASE::GENERATOR
	The type of `ToneGenerator` to use as constructor's argument. More...

using	TONE_PLAY = typename BASE::TONE_PLAY
	The type that holds unit of information of a melody. More...

Public Member Functions
	AsyncTonePlayer (GENERATOR &tone_generator)
	Create a new asynchronous tone player, based on an existing `ToneGenerator`. More...

uint16_t	get_min_duration () const
	Get the duration, in milliseconds, of a 32nd note. More...

void	play_sram (const TONE_PLAY *melody, const Beat &beat)
	Start playing a melody, defined by a sequence of `TONE_PLAY`s, stored in SRAM. More...

void	play_eeprom (const TONE_PLAY *melody, const Beat &beat)
	Start playing a melody, defined by a sequence of `TONE_PLAY`s, stored in EEPROM. More...

void	play_flash (const TONE_PLAY *melody, const Beat &beat)
	Start playing a melody, defined by a sequence of `TONE_PLAY`s, stored in Flash. More...

void	stop ()
	Stop playing current melody (if any). More...

bool	is_playing () const
	Tell if a melody is currently playing. More...

void	update (uint32_t rtt_millis)
	Ask this player to update current play if needed, based on current time (as returned by an `timer::RTT` for example). More...

Additional Inherited Members
Protected Types inherited from devices::audio::AbstractTonePlayer< NTIMER, OUTPUT, TONEPLAY >
using	TONE_PLAY = TONEPLAY
	The type that holds unit of information of a melody. More...

using	GENERATOR = ToneGenerator< NTIMER, OUTPUT >
	The type of `ToneGenerator` to use as constructor's argument. More...

Protected Member Functions inherited from devices::audio::AbstractTonePlayer< NTIMER, OUTPUT, TONEPLAY >
	AbstractTonePlayer (GENERATOR &tone_generator)
	Create a new tone player, based on an existing `ToneGenerator`. More...

void	set_min_duration (uint16_t min_duration)
	Set the duration, in milliseconds, of a 32nd note. More...

uint16_t	get_min_duration () const
	Get the duration, in milliseconds, of a 32nd note. More...

void	prepare_sram (const TONE_PLAY *melody)
	Prepare playing of `melody`, which should be stored in SRAM. More...

void	prepare_eeprom (const TONE_PLAY *melody)
	Prepare playing of `melody`, which should be stored in EEPROM. More...

void	prepare_flash (const TONE_PLAY *melody)
	Prepare playing of `melody`, which should be stored in Flash. More...

uint16_t	start_next_note ()
	Ask this player to start playing the next note of the melody. More...

uint16_t	stop_current_note ()
	Ask this player to stop playing the current note of the melody. More...

bool	is_finished () const
	Indicate if the currently played melody is finished. More...

Detailed Description

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>
class devices::audio::AsyncTonePlayer< NTIMER, OUTPUT, TONEPLAY >

This API defines a player of melodies, defined as a sequence of tones and durations.

This player is asynchronous, i.e. when asking it to play a melody, the called method will return immediately even before the melody starts playing; then its update() method must be called frequently (from an ISR, or from a main event loop).

Melodies are defined as sequence of unit information, which can be either:

TonePlays: easy to write in source code but not efficient in size of generated code
QTonePlays: requires more effort in source code, but reduces generated code size Which types is used is defined as the TONEPLAY template parameter.

With this API, played melodies can be stored on 3 possible locations:

in SRAM: this is useful when you get the melody from another support e.g. an external flash device
in Flash: this is the mostly used way as flash s the more abundant storage in AVR MCU
in EEPROM: this can be useful for short melodies, when you do not want to waste precious SRAM and Flash

Each API has 3 distinct methods, one for each storage strategy.

Template Parameters

NTIMER	the AVR timer to use for the underlying Timer
OUTPUT	the `board::PWMPin` connected to the buzzer; this must be the pin OCnA, where n is the AVR Timer number
TONEPLAY	the type used to store melody data, `QTonePlay` by default

See also: TonePlay; QTonePlay; TonePlayer

Definition at line 856 of file tone_player.h.

Member Typedef Documentation

◆ GENERATOR

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

using devices::audio::AsyncTonePlayer< NTIMER, OUTPUT, TONEPLAY >::GENERATOR = typename BASE::GENERATOR

The type of ToneGenerator to use as constructor's argument.

Definition at line 863 of file tone_player.h.

◆ TONE_PLAY

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

using devices::audio::AsyncTonePlayer< NTIMER, OUTPUT, TONEPLAY >::TONE_PLAY = typename BASE::TONE_PLAY

The type that holds unit of information of a melody.

Definition at line 865 of file tone_player.h.

Constructor & Destructor Documentation

◆ AsyncTonePlayer()

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

devices::audio::AsyncTonePlayer< NTIMER, OUTPUT, TONEPLAY >::AsyncTonePlayer ( GENERATOR & tone_generator )

inlineexplicit

Create a new asynchronous tone player, based on an existing ToneGenerator.

Parameters

tone_generator the ToneGenerator used to actually produce tones.

Definition at line 872 of file tone_player.h.

Member Function Documentation

◆ get_min_duration()

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

uint16_t devices::audio::AsyncTonePlayer< NTIMER, OUTPUT, TONEPLAY >::get_min_duration ( ) const

inline

Get the duration, in milliseconds, of a 32nd note.

This value can be used to set the ideal timer/counter value that shall be used to asynchronously play a melody. This method shall be called only AFTER one of play_xxxx() methods has been called.

See also: play_sram(); play_eeprom(); play_flash()

Definition at line 884 of file tone_player.h.

◆ play_sram()

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

void devices::audio::AsyncTonePlayer< NTIMER, OUTPUT, TONEPLAY >::play_sram	(	const TONE_PLAY *	melody,
		const Beat &	beat
	)

inline

Start playing a melody, defined by a sequence of TONE_PLAYs, stored in SRAM.

This method is asynchronous: it returns immediately even ebfore starting playing the first melody's note. Actual play is performed by frequent calls of update().

Parameters

melody	a pointer, in SRAM, to the sequence of `TONE_PLAY` to be played; the sequence MUST finish with a `SpecialTone::END`.
beat	the tempo (beats per minute) at which the melody shall be played; one beat is the duration of a quarter note.

See also: play_eeprom(); play_flash(); stop(); update()

Definition at line 903 of file tone_player.h.

◆ play_eeprom()

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

void devices::audio::AsyncTonePlayer< NTIMER, OUTPUT, TONEPLAY >::play_eeprom	(	const TONE_PLAY *	melody,
		const Beat &	beat
	)

inline

Start playing a melody, defined by a sequence of TONE_PLAYs, stored in EEPROM.

This method is asynchronous: it returns immediately even ebfore starting playing the first melody's note. Actual play is performed by frequent calls of update().

Parameters

melody	a pointer, in EEPROM, to the sequence of `TONE_PLAY` to be played; the sequence MUST finish with a `SpecialTone::END`.
beat	the tempo (beats per minute) at which the melody shall be played; one beat is the duration of a quarter note.

See also: play_sram(); play_flash(); stop(); update()

Definition at line 926 of file tone_player.h.

◆ play_flash()

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

void devices::audio::AsyncTonePlayer< NTIMER, OUTPUT, TONEPLAY >::play_flash	(	const TONE_PLAY *	melody,
		const Beat &	beat
	)

inline

Start playing a melody, defined by a sequence of TONE_PLAYs, stored in Flash.

This method is asynchronous: it returns immediately even ebfore starting playing the first melody's note. Actual play is performed by frequent calls of update().

Parameters

melody	a pointer, in Flash, to the sequence of `TONE_PLAY` to be played; the sequence MUST finish with a `SpecialTone::END`.
beat	the tempo (beats per minute) at which the melody shall be played; one beat is the duration of a quarter note.

See also: play_eeprom(); play_sram(); stop(); update()

Definition at line 949 of file tone_player.h.

◆ stop()

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

void devices::audio::AsyncTonePlayer< NTIMER, OUTPUT, TONEPLAY >::stop ( )

inline

Stop playing current melody (if any).

Effect is not immediate but will stop at the end of the current tone.

Definition at line 962 of file tone_player.h.

◆ is_playing()

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

bool devices::audio::AsyncTonePlayer< NTIMER, OUTPUT, TONEPLAY >::is_playing ( ) const

inline

Tell if a melody is currently playing.

Definition at line 971 of file tone_player.h.

◆ update()

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

void devices::audio::AsyncTonePlayer< NTIMER, OUTPUT, TONEPLAY >::update ( uint32_t rtt_millis )

inline

Ask this player to update current play if needed, based on current time (as returned by an timer::RTT for example).

This may be called from an ISR or from an event loop in main(). This is the end program responsibility to call this method at proper intervals, in order to ensure fidelity of melody tempo.

Parameters

rtt_millis the current real time (in milliseconds), as obtained from an timer::RTT instance.

Definition at line 986 of file tone_player.h.

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

fastarduino/devices/tone_player.h

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ GENERATOR

◆ TONE_PLAY

Constructor & Destructor Documentation

◆ AsyncTonePlayer()

Member Function Documentation

◆ get_min_duration()

◆ play_sram()

◆ play_eeprom()

◆ play_flash()

◆ stop()

◆ is_playing()

◆ update()