# buzzer模块

| 状态 |最后更新 | API版本 |
| ------ | ------ | ------ |
| Active | 2020-1-7 | V1.00.00 |

## 描述

这个模块提供对板载蜂鸣器的访问



## sysSound
您应该尽量使用`sysSound`
下面的表格列举系统声音：

| 名称              | 用法                                                 |
| ----------------- | ---------------------------------------------------- |
| sysSound.alarm    | 发生错误和警告时应当使用 |
| sysSound.hint     | 发生提醒时使用      |
| sysSound.started  | 某个过程开始时使用     |
| sysSound.finished | 某个过程结束时使用     |



## buzzer.system()

### 描述
播放系统声音。

### 参数

| 名称 | 类型 | 范围 | 用途 |
| ------ | ------ | ------ |  ------ |
| <Sound> | `sysSound` |       |指定播放的声音.|
| [WaitForEnd] | boolean |       |可选参数，如果为true，则在声音播放完成后才返回，如果为false，则立刻返回。若未指定，则立刻返回|

### 返回值
nil
### 调用例
```lua
buzzer.system(sysSound.alarm) --without block
delay.ms(1000)
buzzer.system(sysSound.started,true) --with block 
```



## buzzer.singleTone()

### 描述
播放一个指定时长和频率的声音。

### 参数

| 名称 | 类型 | 范围 | 用途 |
| ------ | ------ | ------ |  ------ |
| <Frequency> | number| 100-10000 |指定以赫兹为单位的频率|
| [Duration] | number | 1-65535 |可选参数。指定时长，如果未指定，则永远播放。|
| [WaitForEnd] | boolean |  |可选参数，如果为true，则在声音播放完成后才返回，如果为false，则立刻返回。若未指定，则立刻返回|

### 返回值
nil
### 调用例
```lua
buzzer.singleTone(1000,1000) --1000HZ for 1000ms, non-blocking
buzzer.singleTone(1000,1000,true) --1000HZ for 1000ms, blocking
```



## buzzer.waitForEnd()

### 描述
等待当前正在播放的音效结束。
如果没有正在播放的音效，立刻返回。

### 参数
nil

### 返回值
nil

### 调用例

```lua
buzzer.singleTone(1000,1000) --1000HZ for 1000ms, non-blocking
buzzer.waitForEnd() --Wait for last sound to be played.
```



## buzzer.stop()

### 描述
停止当前正在播放的音效。

### 参数
nil


### 返回值
nil

### 调用例
```lua
buzzer.singleTone(1000,1000) --1000HZ for 1000ms, non-blocking
delay.ms(200)
buzzer.stop() --Stop the sound, the sound should be played for only 200 miliseconds.
```



## 示例代码
```lua
--[[This is a demo for buzzer APIs.
    See comments to understand well.

    Detailed Documentation:
    Version: 20200117
    Author:  yanke928
]]

buzzer.system(sysSound.alarm) --Non-blocking
buzzer.waitForEnd() --Wait for end

delay.ms(1000)

buzzer.system(sysSound.alarm,true) --Blocking

delay.ms(1000)

buzzer.singleTone(1000,1000) --1000HZ for 1000ms, Non-blocking
buzzer.waitForEnd() --Wait for end

delay.ms(1000)

buzzer.singleTone(1000,1000,true) --1000HZ for 1000ms, blocking

delay.ms(1000)

buzzer.singleTone(1000,1000) --1000HZ for 1000ms, non-blocking
delay.ms(200)
buzzer.stop() --Stop the sound, the sound should be played for only 200ms

os.exit(0)
```