// -----------------------------------------------------------------------------
/// \file  Buzzer.h
/// \brief File description
// -----------------------------------------------------------------------------
//  Micro-Key bv
//  Industrieweg 28, 9804 TG Noordhorn
//  Postbus 92, 9800 AB Zuidhorn
//  The Netherlands
//  Tel: +31 594 503020
//  Fax: +31 594 505825
//  Email: support@microkey.nl
//  Web: www.microkey.nl
// -----------------------------------------------------------------------------
/// $Revision$
/// $Author$
/// $Date$
//  (c) 2015 Micro-Key bv
// -----------------------------------------------------------------------------

#ifndef INC_BUZZER_H_
#define INC_BUZZER_H_

/**
 * Buzzer implementation
 * \defgroup Buzzer Buzzer
 * \ingroup HAL
 * @{
 */

// -----------------------------------------------------------------------------
// Include files 
// -----------------------------------------------------------------------------

#include <stdbool.h>

#include "FreeRTOS.h"
#include "task.h"
#include "semphr.h"

#include "stm32f10x.h"

// -----------------------------------------------------------------------------
// Constant and macro definitions 
// -----------------------------------------------------------------------------

#define BUZZER_MIN_PULSEWIDTH_MS       (10)
#define BUZZER_KEYPAD_PULSEWIDTH_MS    (60)
#define BUZZER_ERROR_PULSEWIDTH_MS     (1000)
#define BUZZER_WARNING_PULSEWIDTH_MS   (250)

#define BUZZER_KEYPAD_ACKNOWLEDGE(self)   \
   Buzzer_singleTone(self, BUZZER_KEYPAD_PULSEWIDTH_MS)

#define BUZZER_ERROR(self)                \
   Buzzer_start(self, BUZZER_ERROR_PULSEWIDTH_MS)

#define BUZZER_WARNING(self)                \
   Buzzer_start(self, BUZZER_WARNING_PULSEWIDTH_MS)

// -----------------------------------------------------------------------------
// Type definitions. 
// -----------------------------------------------------------------------------

/**
 * \ingroup Buzzer
 * \class Buzzer
 * The Buzzer struct that can be used as an object
 */
struct Buzzer
{
   // General
   bool initialized;                   //!< Flag indicating initialisation status
   struct Gpio* gpio;                  //!< The GPIO to use for the buzzer
   // Functionary properties
   unsigned int pulseWidth;            //!< Pulsewidth of the buzzer tone
   // Task properties
   bool runTask;                       //!< keep-alive flag for buzzer task
   bool runPeriodically;               //!< Indicates single or periodical run
   SemaphoreHandle_t semaphore;        //!< Task semaphore for synchronisation
   xTaskHandle taskHandle;             //!< FreeRTOS task handle
   int taskPriority;                   //!< FreeRTOS task priority
   uint16_t stackSize;                 //!< FreeRTOS task stacksize
};

// -----------------------------------------------------------------------------
// Function declarations 
// -----------------------------------------------------------------------------

/** Buzzer_construct
 * \brief Constructor for a new buzzer instance
 *
 * This function creates a new buzzer object
 *
 * Created by: mmi
 * \memberof Buzzer
 *
 * \param	   self                    The buzzer object that gets created
 * \param[in]  gpio                    The GPIO to use
 * \param[in]  taskPriority            FreeRTOS task priority
 * \param[in]  stackSize               FreeRTOS stack size
 * \return	   ErrorStatus             SUCCESS if constructor was successful,
 *                                     including generation/start of task
 *                                     ERROR otherwise
 *
 * \todo
 */
extern ErrorStatus Buzzer_construct(struct Buzzer* self, struct Gpio* gpio, int taskPriority, uint16_t stackSize);


/** Buzzer_destruct
 * Destructor for buzzer instance. Also removes the buzzer task
 *
 * Created by: mmi
 * \memberof Buzzer
 *
 * \param      self                    The buzzer instance to destruct
 * \return	   void
 *
 * \todo
 */
extern void Buzzer_destruct(struct Buzzer* self);


/** Buzzer_start
 * \brief Starts the buzzer with a repeating tone.
 * Tone length is given with argument pulseWidth
 *
 * Created by: mmi
 * \memberof Buzzer
 *
 * \param	   self                    The buzzer instance to use
 * \param[in]  pulseWidth              The length of the tone in ms. Also defines
 *                                     the length of the pause between two
 *                                     tones
 *
 * \return	void
 *
 * \todo
 */
extern void Buzzer_start(struct Buzzer* self, unsigned int pulseWidth);


/** Buzzer_stop
 * \brief Stops the repeating buzzer tone
 *
 * Created by: mmi
 * \memberof Buzzer
 *
 * \param	   self                    The buzzer instance to stop *
 * \return	   void
 *
 * \todo
 */
extern void Buzzer_stop(struct Buzzer* self);


/** Buzzer_singleTone
 * Creates a single tone with the length given in pulseWidth
 *
 * Created by: mmi
 * \memberof Buzzer
 *
 * \param	   self                    The buzzer instance to use
 * \param[in]  pulseWidth              The length of the tone in ms
 * \return	void
 *
 * \todo
 */
extern void Buzzer_singleTone(struct Buzzer* self, unsigned int pulseWidth);





#endif /* INC_BUZZER_H_ */

/** @} */