Introduction

A tiny and simple buzzer library, implements a simple turn on, turn off, and the capability to play loops and ringtones. All functions work in NON-BLOCKING MODE, so, your application will never stop the execution while handling the device, and, inclusively, implementing a callback when an operation end.

Supports any microcontroller and Passive or Active buzzer.

Requirements

• A GPIO (active) or PWM (passive) output;
• A Task or timer interrupt;

Features

• Easy to use;
• Start and stop manually;
• Start for a defined time;
• "Blinks" with a fixed period;
• Play ringtones;
• Non-blocking functions;
• Callback to tell you that an operation is finished.

How to Use

First, declares your buzzer_t with, at least, the pwmOut or gpioOut (just pick one! the other fxn must be NULL). About the functions:

• void pwmOut(uint32_t freq) : Is used for PASSIVE buzzers, this function returns void and receives only the freq argument. When implementing, the freq=0, the device MUST turn off PWM.
• void gpioOut(uint32_t val) : Is used for the ACTIVE buzzer, the value val needs to be turn on when is 1, and 0 turnoff the Buzzer. These buzzers can't set frequency values.

The lib will automatically identify the Buzzer type on buzzer_init(), by checking the defined fxn. Another parameter that needs to be implemented, if the user wants to user buzzer_start and buzzer_start_array, is the interruptMs, which only indicates how often you will call the buzzer_interrupt in a timer/task routine, in milliseconds.

This parameter serves to chronometer the buzzer, turning it on and off, for loops, ringtones, etc.

Configuring for PASSIVE Buzzer

Bellow, in this example, we are configuring a buzzer in a generic chipset, with a 50ms timer interrupt and a PWM function.

void __pwm_buzzer_chipset(uint32_t freq);
// Buzzer Handler
buzzer_t Buzzer = {  
  .pwmOut = __pwm_chipset,  
  .interruptMs = 50
}

// Functions
void __pwm_buzzer_chipset(uint32_t freq){
  if (freq == 0){    
    chipset_pwm_turnoff();  
  }  
  else{    
    chipset_pwm_turnon();    
    chipset_pwm_set_freq(freq);  
  }
}
  
// Interrupts
void __tim_interrupt_50ms(){  
  buzzer_interrupt(&Buzzer);
}

// Main
void main(){
  buzzer_init(&Buzzer);
}

Configuring for ACTIVE Buzzer

In this example, an active buzzer is configured and implemented, with a 100ms timer interrupt and GPIO to control the Buzzer.

void __gpio_pwm_chipset(uint32_t val);
// Buzzer Handler
buzzer_t Buzzer = {  
  .pwmOut = __pwm_chipset,  
  .interruptMs = 100
}
  
// Functions
void __gpio_pwm_chipset(uint32_t val){  
  chipset_gpio(BUZZER_GPIO_Port, BUZZER_Pin, val);
}

// Interrupts
void __tim_interrupt_100ms(){  
  buzzer_interrupt(&Buzzer);
}

// Main
void main(){  
  buzzer_init(&Buzzer);
}

Examples

For the examples, consider a Passive Buzzer, configured with a timer and everything :) For Active buzzers, all freq parameters can be 0 or NULL.

Turnon buzzer and Turnoff manually

void main(){  
  ...  
  // turn on the buzzer with a 1500Hz frequency  
  buzzer_turn_on(&Buzzer, 1500);    
  
  // delay for 500ms  
  chipset_delay_ms(500);    
  
  // turnoff buzzer  
  buzzer_stop(&Buzzer);
}

Turnon buzzer for 500ms

void main(){  
  ...  
  // turnon buzzer with a 1500Hz frequency for 500ms  
  buzzer_start(&Buzzer, 1500, 500, BUZZER_LOOP_OFF);
}

"Blink" buzzer for a period of 500ms

void main(){  
  ...  
  // turn on the buzzer with a 2500Hz frequency  
  buzzer_start(&Buzzer, 2500, 500, BUZZER_LOOP_ON);    
  
  // The BUZZER_LOOP_ON parameter indicates that the Buzzer will be turnon for 500ms,
  // turnoff for the same period, and repeat the process
}

Play Super Mario Ringtone and turn on a LED after finish

// this callback is called when a buzzer_start or buzzer_start_array finish
// the solicited operation. In this case, when the Mario Ringtone is
// finished, the callback will be called
void buzzer_end_callback(buzzer_t *buzzer){  
  led_red(TRUE);
}

void main(){  
  ...  
  // play the Mario Theme ringtone, that's included in the library :D  
  buzzer_start_array(&Buzzer, mario_theme_time, mario_theme_melody, mario_theme_len);
}

Doubts

Any doubts, or issues, just post an issue. We have too an example implemented on an STM32F411 (Black Pill). Best regards folks.