1 // Copyright 2020 Espressif Systems (Shanghai) PTE LTD
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 //     http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 #pragma once
15 
16 #include "esp_err.h"
17 
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21 
22 /**
23  * @brief Type of musical buzzer interface
24  *
25  */
26 typedef struct musical_buzzer_t musical_buzzer_t;
27 
28 /**
29  * @brief Type of musical buzzer underlying device
30  *
31  */
32 typedef void *musical_buzzer_dev_t;
33 
34 /**
35  * @brief Type of musical buzzer notation
36  *
37  */
38 typedef struct {
39     uint32_t note_freq_hz;     /*!< Note frequency, in Hz */
40     uint32_t note_duration_ms; /*!< Note duration, in ms */
41 } musical_buzzer_notation_t;
42 
43 /**
44  * @brief Declaration of musical buzzer interface
45  *
46  */
47 struct musical_buzzer_t {
48     /**
49     * @brief Start to play the given notation
50     *
51     * @param buzzer musical buzzer handle
52     * @param notation music notation
53     * @param notation_len notation length
54     * @return
55     *      - ESP_OK: Start playing notation successfully
56     *      - ESP_ERR_INVALID_ARG: wrong parameter
57     */
58     esp_err_t (*play)(musical_buzzer_t *buzzer, const musical_buzzer_notation_t *notation, uint32_t notation_len);
59 
60     /**
61      * @brief Stop playing
62      *
63      * @param buzzer musical buzzer handle
64      * @return
65      *      - ESP_OK: Stop playing successfully
66      */
67     esp_err_t (*stop)(musical_buzzer_t *buzzer);
68 
69     /**
70      * @brief Free memory used by musical buzzer
71      *
72      * @param buzzer musical buzzer handle
73      * @return
74      *      - ESP_OK: Recycle memory successfully
75      */
76     esp_err_t (*del)(musical_buzzer_t *buzzer);
77 };
78 
79 typedef struct {
80     musical_buzzer_dev_t dev; /*!< Musical buzzer device (e.g. RMT channel, PWM channel, etc) */
81     int flags;                /*!< Extra flags */
82 } musical_buzzer_config_t;
83 
84 /**
85  * @brief Default musical buzzer configuration
86  *
87  */
88 #define MUSICAL_BUZZER_DEFAULT_CONFIG(dev_hdl) \
89     {                                          \
90         .dev = dev_hdl,                        \
91         .flags = 0,                            \
92     }
93 
94 /**
95  * @brief Create musical buzzer instance based on RMT driver
96  *
97  * @param config musical buzzer configuration
98  * @param[out] ret_handle returned handle of musical buzzer instance
99  * @return
100  *      - ESP_OK: create musical buzzer instance successfully
101  *      - ESP_ERR_INVALID_ARG: wrong parameter
102  *      - ESP_ERR_NO_MEM: no memory to allocate instance
103  */
104 esp_err_t musical_buzzer_create_rmt(const musical_buzzer_config_t *config, musical_buzzer_t **ret_handle);
105 
106 #ifdef __cplusplus
107 }
108 #endif
109