ADuCM4x50 Device Drivers API Reference Manual  Release 4.0.0.0
BEEP Driver

Beeper Driver. More...

Modules

 Static Configuration
 

Data Structures

struct  ADI_BEEP_NOTE
 Beeper note structure. More...
 

Macros

#define ADI_BEEP_MEMORY_SIZE
 
#define ADI_BEEP_DUR_ZERO   (0)
 
#define ADI_BEEP_DUR_MIN   (1)
 
#define ADI_BEEP_DUR_MAX   (254)
 
#define ADI_BEEP_DUR_INFINITE   (255)
 

Typedefs

typedef void * ADI_BEEP_HANDLE
 

Enumerations

enum  ADI_BEEP_RESULT {
  ADI_BEEP_SUCCESS = 0,
  ADI_BEEP_FAILURE,
  ADI_BEEP_ALREADY_INITIALIZED,
  ADI_BEEP_BAD_DEV_HANDLE,
  ADI_BEEP_BAD_DEV_ID,
  ADI_BEEP_NOT_INITIALIZED,
  ADI_BEEP_PARAM_OUT_OF_RANGE,
  ADI_BEEP_INVALID_COUNT,
  ADI_BEEP_NULL_PTR,
  ADI_BEEP_SEMAPHORE_FAILED
}
 
enum  ADI_BEEP_DEV_ID {
  ADI_BEEP_DEVID_0 = 0,
  ADI_BEEP_MAX_DEVID
}
 Beeper Device IDs. More...
 
enum  ADI_BEEP_INTERRUPT {
  ADI_BEEP_INTERRUPT_SEQUENCE_END = BITM_BEEP_CFG_SEQATENDIRQ,
  ADI_BEEP_INTERRUPT_NOTE_END = BITM_BEEP_CFG_AENDIRQ
}
 Beeper Interrupt Bits. More...
 
enum  ADI_BEEP_NOTE_FREQUENCY {
  ADI_BEEP_FREQ_REST = (0),
  ADI_BEEP_FREQ_C4 = FREQUENCY_ENCODE(261.63f),
  ADI_BEEP_FREQ_Cs4 = FREQUENCY_ENCODE(277.18f),
  ADI_BEEP_FREQ_D4 = FREQUENCY_ENCODE(293.66f),
  ADI_BEEP_FREQ_Ds4 = FREQUENCY_ENCODE(311.13f),
  ADI_BEEP_FREQ_E4 = FREQUENCY_ENCODE(329.63f),
  ADI_BEEP_FREQ_F4 = FREQUENCY_ENCODE(349.23f),
  ADI_BEEP_FREQ_Fs4 = FREQUENCY_ENCODE(369.99f),
  ADI_BEEP_FREQ_G4 = FREQUENCY_ENCODE(392.00f),
  ADI_BEEP_FREQ_Gs4 = FREQUENCY_ENCODE(415.30f),
  ADI_BEEP_FREQ_A4 = FREQUENCY_ENCODE(440.00f),
  ADI_BEEP_FREQ_As4 = FREQUENCY_ENCODE(466.16f),
  ADI_BEEP_FREQ_B4 = FREQUENCY_ENCODE(493.88f),
  ADI_BEEP_FREQ_C5 = FREQUENCY_ENCODE(523.25f),
  ADI_BEEP_FREQ_Cs5 = FREQUENCY_ENCODE(554.37f),
  ADI_BEEP_FREQ_D5 = FREQUENCY_ENCODE(587.33f),
  ADI_BEEP_FREQ_Ds5 = FREQUENCY_ENCODE(622.25f),
  ADI_BEEP_FREQ_E5 = FREQUENCY_ENCODE(659.26f),
  ADI_BEEP_FREQ_F5 = FREQUENCY_ENCODE(698.46f),
  ADI_BEEP_FREQ_Fs5 = FREQUENCY_ENCODE(739.99f),
  ADI_BEEP_FREQ_G5 = FREQUENCY_ENCODE(783.99f),
  ADI_BEEP_FREQ_Gs5 = FREQUENCY_ENCODE(830.61f),
  ADI_BEEP_FREQ_A5 = FREQUENCY_ENCODE(880.00f),
  ADI_BEEP_FREQ_As5 = FREQUENCY_ENCODE(932.33f),
  ADI_BEEP_FREQ_B5 = FREQUENCY_ENCODE(987.77f),
  ADI_BEEP_FREQ_C6 = FREQUENCY_ENCODE(1046.50f),
  ADI_BEEP_FREQ_Cs6 = FREQUENCY_ENCODE(1108.73f),
  ADI_BEEP_FREQ_D6 = FREQUENCY_ENCODE(1174.66f),
  ADI_BEEP_FREQ_Ds6 = FREQUENCY_ENCODE(1244.51f),
  ADI_BEEP_FREQ_E6 = FREQUENCY_ENCODE(1318.51f),
  ADI_BEEP_FREQ_F6 = FREQUENCY_ENCODE(1396.91f),
  ADI_BEEP_FREQ_Fs6 = FREQUENCY_ENCODE(1479.98f),
  ADI_BEEP_FREQ_G6 = FREQUENCY_ENCODE(1567.98f),
  ADI_BEEP_FREQ_Gs6 = FREQUENCY_ENCODE(1661.22f),
  ADI_BEEP_FREQ_A6 = FREQUENCY_ENCODE(1760.00f),
  ADI_BEEP_FREQ_As6 = FREQUENCY_ENCODE(1864.66f),
  ADI_BEEP_FREQ_B6 = FREQUENCY_ENCODE(1975.53f),
  ADI_BEEP_FREQ_C7 = FREQUENCY_ENCODE(2093.00f),
  ADI_BEEP_FREQ_Cs7 = FREQUENCY_ENCODE(2217.46f),
  ADI_BEEP_FREQ_D7 = FREQUENCY_ENCODE(2349.32f),
  ADI_BEEP_FREQ_Ds7 = FREQUENCY_ENCODE(2489.02f),
  ADI_BEEP_FREQ_E7 = FREQUENCY_ENCODE(2637.02f),
  ADI_BEEP_FREQ_F7 = FREQUENCY_ENCODE(2793.83f),
  ADI_BEEP_FREQ_Fs7 = FREQUENCY_ENCODE(2959.96f),
  ADI_BEEP_FREQ_G7 = FREQUENCY_ENCODE(3135.96f),
  ADI_BEEP_FREQ_Gs7 = FREQUENCY_ENCODE(3322.44f),
  ADI_BEEP_FREQ_A7 = FREQUENCY_ENCODE(3520.00f),
  ADI_BEEP_FREQ_As7 = FREQUENCY_ENCODE(3729.31f),
  ADI_BEEP_FREQ_B7 = FREQUENCY_ENCODE(3951.07f),
  ADI_BEEP_FREQ_C8 = FREQUENCY_ENCODE(4186.01f),
  ADI_BEEP_FREQ_Cs8 = FREQUENCY_ENCODE(4434.92f),
  ADI_BEEP_FREQ_D8 = FREQUENCY_ENCODE(4698.64f),
  ADI_BEEP_FREQ_Ds8 = FREQUENCY_ENCODE(4978.03f),
  ADI_BEEP_FREQ_E8 = FREQUENCY_ENCODE(5274.04f),
  ADI_BEEP_FREQ_F8 = FREQUENCY_ENCODE(5587.65f),
  ADI_BEEP_FREQ_Fs8 = FREQUENCY_ENCODE(5919.91f),
  ADI_BEEP_FREQ_G8 = FREQUENCY_ENCODE(6271.93f)
}
 Beeper tone frequency list. More...
 
enum  ADI_BEEP_NOTE_DURATION {
  ADI_BEEP_DUR_0 = ADI_BEEP_DUR_ZERO,
  ADI_BEEP_DUR_32_32 = DURATION_ENCODE(1),
  ADI_BEEP_DUR_16_32 = DURATION_ENCODE(2),
  ADI_BEEP_DUR_12_32 = DURATION_ENCODE(8/3),
  ADI_BEEP_DUR_8_32 = DURATION_ENCODE(4),
  ADI_BEEP_DUR_6_32 = DURATION_ENCODE(16/3),
  ADI_BEEP_DUR_4_32 = DURATION_ENCODE(8),
  ADI_BEEP_DUR_2_32 = DURATION_ENCODE(16),
  ADI_BEEP_DUR_1_32 = DURATION_ENCODE(32),
  ADI_BEEP_DUR_N = ADI_BEEP_DUR_INFINITE
}
 Beeper tone duration list. More...
 

Functions

ADI_BEEP_RESULT adi_beep_Open (ADI_BEEP_DEV_ID const DeviceNum, void *const pMemory, uint32_t const MemorySize, ADI_BEEP_HANDLE *const phDevice)
 BEEP Initialization. More...
 
ADI_BEEP_RESULT adi_beep_RegisterCallback (ADI_BEEP_HANDLE const hDevice, ADI_CALLBACK pfCallback, void *const pCBParam)
 Register a callback for the beeper driver. More...
 
ADI_BEEP_RESULT adi_beep_PlayNote (ADI_BEEP_HANDLE const hDevice, ADI_BEEP_NOTE note)
 Play a single note/beep. More...
 
ADI_BEEP_RESULT adi_beep_PlayTwoTone (ADI_BEEP_HANDLE const hDevice, ADI_BEEP_NOTE noteA, ADI_BEEP_NOTE noteB, uint8_t count)
 Play a a repeating two-tone beep. Similar to an alarm. More...
 
ADI_BEEP_RESULT adi_beep_PlaySequence (ADI_BEEP_HANDLE const hDevice, ADI_BEEP_NOTE aSequence[], uint8_t count)
 Play a beeper tone sequence. More...
 
ADI_BEEP_RESULT adi_beep_Enable (ADI_BEEP_HANDLE const hDevice, bool const bFlag)
 Enable or disable the beeper. Other APIs will automatically enable the beeper if required, so this function is best used in the following situations: More...
 
ADI_BEEP_RESULT adi_beep_Wait (ADI_BEEP_HANDLE const hDevice)
 Wait for the current playback to finish. This is a blocking call, that will not return until the current playback (if any) has finished. If there is no current playback, it will return immediately. More...
 
ADI_BEEP_RESULT adi_beep_Close (ADI_BEEP_HANDLE const hDevice)
 Uninitialize and deallocate a BEEP device. More...
 

Detailed Description

Beeper Driver.

Note
The application must include drivers/beep/adi_beep.h to use this driver.
This documentation presented here is API documentation only. The device drive user's guide, located in the Documents folder, explains how to use these APIs in an application.

Macro Definition Documentation

◆ ADI_BEEP_MEMORY_SIZE

#define ADI_BEEP_MEMORY_SIZE

Amount of memory(In bytes) required by the Beep device driver for managing the operation. This memory is completely owned by the driver till the end of the operation.

Indicates the size of the BEEP memory to be used

Definition at line 35 of file adi_beep.h.

◆ ADI_BEEP_DUR_ZERO

#define ADI_BEEP_DUR_ZERO   (0)

Beeper zero tone duration value

Definition at line 168 of file adi_beep.h.

◆ ADI_BEEP_DUR_MIN

#define ADI_BEEP_DUR_MIN   (1)

Beeper minimum tone duration value

Definition at line 169 of file adi_beep.h.

◆ ADI_BEEP_DUR_MAX

#define ADI_BEEP_DUR_MAX   (254)

Beeper maximum tone duration value

Definition at line 170 of file adi_beep.h.

◆ ADI_BEEP_DUR_INFINITE

#define ADI_BEEP_DUR_INFINITE   (255)

Beeper infinite tone duration value

Definition at line 171 of file adi_beep.h.

Typedef Documentation

◆ ADI_BEEP_HANDLE

typedef void* ADI_BEEP_HANDLE

A device handle used in all API functions to identify the BEEP device.

Definition at line 174 of file adi_beep.h.

Enumeration Type Documentation

◆ ADI_BEEP_RESULT

Beeper API return codes

Enumerator
ADI_BEEP_SUCCESS 

No Error, API suceeded

ADI_BEEP_FAILURE 

An unknown error was detected

ADI_BEEP_ALREADY_INITIALIZED 

BEEP is already initialized

ADI_BEEP_BAD_DEV_HANDLE 

Invalid device handle passed

ADI_BEEP_BAD_DEV_ID 

Asking to initialize an unknown device num

ADI_BEEP_NOT_INITIALIZED 

BEEP not yet initialized

ADI_BEEP_PARAM_OUT_OF_RANGE 

Parameter is out of range.

ADI_BEEP_INVALID_COUNT 

Invalid count for supplied beep sequence

ADI_BEEP_NULL_PTR 

Null pointer supplied.

ADI_BEEP_SEMAPHORE_FAILED 

BEEP semaphore failure.

Definition at line 45 of file adi_beep.h.

◆ ADI_BEEP_DEV_ID

Beeper Device IDs.

List of all Beeper Device IDs for the current part

Enumerator
ADI_BEEP_DEVID_0 

BEEP Timer Device 0

ADI_BEEP_MAX_DEVID 

max number of BEEP devices

Definition at line 66 of file adi_beep.h.

◆ ADI_BEEP_INTERRUPT

Beeper Interrupt Bits.

List of all Beeper interrupt (enables and status) bits.

Enumerator
ADI_BEEP_INTERRUPT_SEQUENCE_END 

Beeper sequence has finished

ADI_BEEP_INTERRUPT_NOTE_END 

Beeper note has finished

Definition at line 77 of file adi_beep.h.

◆ ADI_BEEP_NOTE_FREQUENCY

Beeper tone frequency list.

List of possible Beeper tone frequencies.

Enumerator
ADI_BEEP_FREQ_REST 

silence

ADI_BEEP_FREQ_C4 

Middle C (lowest representable frequency @ 32KHz)

Definition at line 93 of file adi_beep.h.

◆ ADI_BEEP_NOTE_DURATION

Beeper tone duration list.

List of possible Beeper tone durations.

Enumerator
ADI_BEEP_DUR_0 

stop

ADI_BEEP_DUR_32_32 

whole note (1.016 seconds)

ADI_BEEP_DUR_16_32 

half note

ADI_BEEP_DUR_12_32 

three eights note

ADI_BEEP_DUR_8_32 

one quarter note

ADI_BEEP_DUR_6_32 

three sixteenth note

ADI_BEEP_DUR_4_32 

one eighth note

ADI_BEEP_DUR_2_32 

one sixteenth note

ADI_BEEP_DUR_1_32 

one thirty-secondth note

ADI_BEEP_DUR_N 

continuous play

Definition at line 185 of file adi_beep.h.

Function Documentation

◆ adi_beep_Open()

ADI_BEEP_RESULT adi_beep_Open ( ADI_BEEP_DEV_ID const  DeviceNum,
void *const  pMemory,
uint32_t const  MemorySize,
ADI_BEEP_HANDLE *const  phDevice 
)

BEEP Initialization.

Parameters
[in]DeviceNumInteger specifying the ID of Beeper to use.
[in]pMemoryPointer to the memory to be used by the driver. Size of the memory should be at least ADI_BEEP_MEMORY_SIZE bytes.
[in]MemorySizeSize of the memory passed in pMemory parameter.
[out]phDevicePointer to a location that the device data pointer will be written upon successful initialization.
Returns
Status

Initialize the BEEP device for use. The core NVIC BEEP interrupt is enabled. This API must preceed all other beeper API calls and the handle returned must be passed to all other beeper API calls.

Note
The contents of phDevice will be set to NULL upon failure.

The BEEP device driver will clear all pending interrupts and disable all beeper interrupts during beeper device initialization.
CALLBACKS: If a callback is registered, it will be called on completion of the note or sequence. The "Event" parameter will contain which event occurred, either ADI_BEEP_INTERRUPT_SEQUENCE_END or ADI_BEEP_INTERRUPT_NOTE_END.
Warning
This API will put the beeper in preconfigured mode as defined in adi_beep_config.h file. Refer adi_beep_config.h file to see which all features can be preconfigured.
See also
adi_beep_Close().

Definition at line 161 of file adi_beep.c.

◆ adi_beep_RegisterCallback()

ADI_BEEP_RESULT adi_beep_RegisterCallback ( ADI_BEEP_HANDLE const  hDevice,
ADI_CALLBACK  pfCallback,
void *const  pCBParam 
)

Register a callback for the beeper driver.

Parameters
[in]hDeviceDevice handle obtained from adi_beep_Open().
[in]pfCallbackThe application supplied callback which will be called to notify device related events.
[in]pCBParamThe application supplied callback parameter which can be passed back in the callback function.
Returns
Status

Registers a callback for the beeper interrupts. When an interrupt occurs, the driver will handle any required interaction with the hardware and then call the registered callback.

See also
adi_beep_Open().

Definition at line 293 of file adi_beep.c.

◆ adi_beep_PlayNote()

ADI_BEEP_RESULT adi_beep_PlayNote ( ADI_BEEP_HANDLE const  hDevice,
ADI_BEEP_NOTE  note 
)

Play a single note/beep.

Parameters
[in]hDeviceDevice handle obtained from adi_beep_Open().
[in]noteThe note to play.
Returns
Status

Programs the A tone to play a single note.

See also
adi_beep_Open().

Definition at line 428 of file adi_beep.c.

◆ adi_beep_PlayTwoTone()

ADI_BEEP_RESULT adi_beep_PlayTwoTone ( ADI_BEEP_HANDLE const  hDevice,
ADI_BEEP_NOTE  noteA,
ADI_BEEP_NOTE  noteB,
uint8_t  count 
)

Play a a repeating two-tone beep. Similar to an alarm.

Parameters
[in]hDeviceDevice handle obtained from adi_beep_Open().
[in]noteAThe note to play first.
[in]noteBThe note to play second.
[in]countThe number of times to repeat the two-note signal, maximum of 127.
Returns
Status

Programs the beeper to play a repeating two-tone signal. The count argument refers to the number of iterations of both notes, not just a single note.

See also
adi_beep_Open().
adi_beep_PlayNote().
adi_beep_PlayNSequence().

Definition at line 491 of file adi_beep.c.

◆ adi_beep_PlaySequence()

ADI_BEEP_RESULT adi_beep_PlaySequence ( ADI_BEEP_HANDLE const  hDevice,
ADI_BEEP_NOTE  aSequence[],
uint8_t  count 
)

Play a beeper tone sequence.

Parameters
[in]hDeviceDevice handle obtained from adi_beep_Open().
[in]aSequenceThe sequence of notes to be played by the beeper.
[in]countThe number of notes in the sequence, must be a multiple of two, and a maximum size of 254 notes.
Returns
Status

Programs the A/B tone pair to play a sequence of notes. The sequnce can be stopped by calling adi_beep_Enable(..., false). The beeper will be enabled and disabled internally by the driver. This code, and supporting data, can be removed by setting ADI_BEEP_INCLUDE_PLAY_SEQUENCE == 0 in the adi_beep_config.h configuration file.

See also
adi_beep_Open().
adi_beep_Enable()

Definition at line 345 of file adi_beep.c.

◆ adi_beep_Enable()

ADI_BEEP_RESULT adi_beep_Enable ( ADI_BEEP_HANDLE const  hDevice,
bool const  bFlag 
)

Enable or disable the beeper. Other APIs will automatically enable the beeper if required, so this function is best used in the following situations:

  • when only using static configuration, i.e. start playing the notes set up in static adi_beep_config.h.
  • Otherwise, this can be used to stop the beeper during playback, when started from any other API.
Parameters
[in]hDeviceDevice handle obtained from adi_beep_Open().
[in]bFlagtrue to enable the device, false to stop playback.
Returns
Status
See also
adi_beep_Open().

Definition at line 552 of file adi_beep.c.

◆ adi_beep_Wait()

ADI_BEEP_RESULT adi_beep_Wait ( ADI_BEEP_HANDLE const  hDevice)

Wait for the current playback to finish. This is a blocking call, that will not return until the current playback (if any) has finished. If there is no current playback, it will return immediately.

Parameters
[in]hDeviceDevice handle obtained from adi_beep_Open().
Returns
Status
See also
adi_beep_Open().

Definition at line 603 of file adi_beep.c.

◆ adi_beep_Close()

ADI_BEEP_RESULT adi_beep_Close ( ADI_BEEP_HANDLE const  hDevice)

Uninitialize and deallocate a BEEP device.

Parameters
[in]hDeviceDevice handle obtained from adi_beep_Open().
Returns
Status

Uninitialize and release an allocated BEEP device for other use. The core NVIC BEEP interrupt is disabled.

See also
adi_beep_Open().

Definition at line 238 of file adi_beep.c.