buzzer/buzzer.h

/**
 * @file buzzer.h
 * @author Pablo Jean Rozario (pablo.jean.eel@gmail.com)
 * @brief This library is to handle Buzzer devices, without
 * chipset depedency, can be used in any microcontroller
 * @version 1.0
 * @date 2022-12-01
 * 
 * @copyright Copyright (c) 2022
 * 
 */

#ifndef _BUZZER_DRIVER_H_
#define _BUZZER_DRIVER_H_

#include <stdint.h>
#include <stddef.h>
#include <string.h>

#define _BUZZER_DERIVER_USE_PWM 
//#define _BUZZER_DERIVER_USE_GPIO 

/*
 * Enumerates
 */
/**
 * @brief indicate if a logic is handle the buzzer. Not necesary
 * indicate if buzzer is vibrating.
 * 
 * BUZZER_IS_NOT_ACTIVE: no routine is applied on buzzer
 * BUZZER_IS_ACTIVE buzzer is working with a logic
 */
typedef enum{
	BUZZER_IS_NOT_ACTIVE,
	BUZZER_IS_ACTIVE
}buzzer_active_e;

/**
 * BUZZER_ERR_OK : Eveything is OK
 * BUZZER_ERR_FAIL : failed to initialize the buzzer
 * BUZZER_ERR_PARAMS : some parameter is missing or incorrect
 * 
 */
typedef enum{
	BUZZER_ERR_OK,
	BUZZER_ERR_FAIL,
	BUZZER_ERR_PARAMS,

	BUZZER_ERR_UNKNOWN = 0xFF
}buzzer_err_e;

/*
 * Functions typedefs
 */

/**
 * @brief Function pointers. For Pwm or GPIO
 * 
 */
#ifdef _BUZZER_DERIVER_USE_PWM
typedef void (*pwmOutFx)(uint16_t freq);
#endif

#ifdef _BUZZER_DERIVER_USE_GPIO
typedef void (*gpioOutFx)(uint8_t val);
#endif

/*
 * Structs and Unions
 */

typedef struct{

#ifdef _BUZZER_DERIVER_USE_PWM
    	pwmOutFx pwmOut;
#endif
	/**
	 * @brief Function to handle with GPIO that will
	 * handle the Buzzer.
	 * USE THIS FOR ACTIVE DEVICES
	 */
#ifdef _BUZZER_DERIVER_USE_GPIO
    	gpioOutFx gpioOut;
#endif

    // the interrupt period that you will call buzzer_interrupt()
    // necessary for buzzer_start() and buzzer_start_array()
    uint16_t cycleMsInterval;

    buzzer_active_e active;
    uint16_t counting;
    struct{
        uint16_t *pTimes;/*播放次数数组指针*/
        uint16_t *pFreq; /*播放频率数组指针*/
        uint16_t i;      /*数组位置*/
        uint16_t len;    /*数组长度*/

        uint16_t time;	/*播放次数*/
        uint16_t freq;	/*播放频率*/

        uint16_t loop_time;/*播放循环次数*/ 
    }play_param;
}buzzer_t;

/*
 * Functions Prototypes
 */

/**
 * @brief Initialize the buzzer
 * 
 * @param buzzer : pointer to the handle of the buzzer
 * @return buzzer_err_e 
 */
buzzer_err_e buzzer_init(buzzer_t *buzzer);

/**
 * @brief Turnoff the buzzer imediatly
 * 
 * @param buzzer : pointer to the handle of the buzzer
 */
void buzzer_stop(buzzer_t *buzzer);

/**
 * @brief Turnon buzzer immediately
 * 
 * @param buzzer : pointer to the handle of the buzzer
 * @param freq : frequency that will inserted on buzzer.
 * 
 * @note freq parameters is relevant only in passive devices
 */
void buzzer_turn_on(buzzer_t *buzzer, uint16_t freq);

/**
 * Start buzzer for a determined period
 * If loop is BUZZER_LOOP_ON the buzzer will turn on and turn off
 * with the period
 * buzzer_interrupt must be working
 */

/**
 * @brief  Start buzzer for a determined period
 * If loop is BUZZER_LOOP_ON the buzzer will turn on and turn off
 * with the period
 * buzzer_interrupt must be working
 * 
 * @param buzzer : pointer to the handle of the buzzer
 * @param freq : frequency of the device
 * @param period : period that buzzer will stay on, or period
 * of beeps
 * @param loop : BUZZER_LOOP_ON buzzer will turned on and off with
 * provided period
 * BUZZER_LOOP_OFF will keep device vibrating only for period prived.
 * 
 * @note : freq is relevant only for Passive devices
 */
void buzzer_start(buzzer_t *buzzer, uint16_t freq, uint16_t period, uint16_t loop);

/**
 * Start to play a array of period and frequencies, generally used to play ringtones
 * buzzer_interrupt must be working
 */

/**
 * @brief : Start to play a array of period and frequencies, generally used to play ringtones
 * buzzer_interrupt must be working
 * 
 * @param buzzer : pointer to the handle of the buzzer
 * @param pPeriod : array of period
 * @param pFreq : array of frequency values, must have the same len of pPeriod
 * @param len : number of values on pFreq and/or pPeriod
 * 
 * @note pFreq is relevant only for Passive devices
 */
void buzzer_start_array(buzzer_t *buzzer, uint16_t *pPeriod, uint16_t *pFreq, uint16_t len);

/**
 * Return if Buzzer is active
 */

/**
 * @brief Return if Buzzer is active
 * 
 * @param buzzer : pointer to the handle of the buzzer
 * @return buzzer_active_e 
 */
buzzer_active_e buzzer_is_active(buzzer_t *buzzer);

/**
 * @brief call this function in a periodic timing, if you're using a RTOS
 * we suggest you to use a task to handle this with a sleep
 * the period of interrupt is configured on buzzer_t structure
 * 
 * @param buzzer : pointer to the handle of the buzzer
 */
void buzzer_interrupt(buzzer_t *buzzer);

/**
 * @brief callback when an array has your execution finished
 * 
 * @param buzzer : pointer to the handle of the buzzer
 */
void buzzer_end_callback(buzzer_t *buzzer);


#endif /* _BUZZER_DRIVER_H_ */